TITAN AI · Core module · agent_version_updater

Your 26 agents upgrade themselves. Every day. Without breaking.

Every night at 03:47 local, TITAN pulls the latest version of every library that every agent uses, applies security + patch + minor bumps, imports all 26 agents, runs the full health check, and only promotes the new environment if everything still works. If a single agent fails to import, the whole upgrade rolls back to last night’s known-good snapshot — automatically, before anyone notices.

On the 1st of every month at 04:17, the monthly cadence handles major version bumps one at a time with the same smoke-test gate, plus an optional Claude-powered breaking-change review. Packages that have rolled back before get flagged in the self-learning store so the next cycle treats them with extra caution.

Version feed sources: PyPI + NVD (CVE scoring) + CISA KEV (exploit-in-the-wild priority) + your own learning store. See the 36-feed compliance auto-updater for the full list.

How it works — one night in the life of your stack

03:47 local. Scheduler wakes up. python -m core.agent_version_updater --upgrade-security runs.
Snapshot. Current pip freeze saved to data/version_upgrades/active_freeze.txt (plus 7-day rolling .bak). This is the rollback anchor.
Plan. Query PyPI for every dep in requirements.txt. Cross-reference against NVD + CISA KEV. Build the target list: security_urgent / patch / minor / major.
Apply (daily channel). Install every target with pip install --upgrade. Write new candidate_freeze.txt.
Smoke test. Import every one of the 26 agents + run core.health_check --quick. Timeout 180s. Any failure = abort.
Promote or rollback. On success: mark targets safe in learning store. On failure: pip install -r active_freeze.txt to restore. Append to audit.log.
Human-readable report. LAST_RUN_REPORT.md regenerates with per-agent import status, last 10 runs, rollback-prone packages, and next-step commands.

The two cadences

DAILY — Security + Minor channel

03:47 local, every night

Patch + minor bumps. Any dep with a Critical/High CVE in NVD goes first. Full 26-agent smoke test. Auto-rollback on any failure.

12h cadenceauto-rollback

MONTHLY — Major channel

04:17 local, 1st of the month

Major bumps applied one-at-a-time — a single bad major never taints the batch. Optional LLM breaking-change review (ANTHROPIC_API_KEY). Stronger smoke test. Rollback-prone flagging.

30d cadenceLLM-assisted

What makes this safe

Atomic snapshot + rollback

Every run starts with a pip freeze snapshot. If the post-upgrade smoke test fails, we pip install -r that snapshot to restore the previous environment exactly.

GUARD

All-26-agent import gate

Every known agent module is imported in a clean subprocess. If any one of Scout / Sentinel / Forge / Comply / Shadow / Phoenix / Legacy / Bastion / Oracle / Lattice / Flux / Conduit / AUDIT / DR-Guard / AML / Banking / Fraud / KYC / Telco / Voice / Watch / Pulse / Sage / Engage / Predict / Code fails to import, the upgrade aborts.

GUARD

core.health_check --quick

Short-form health check runs after imports. Verifies core pipelines, config loading, and connector smoke paths. 180-second timeout — if it hangs, we kill it and rollback.

GUARD

One-at-a-time major bumps

Major version changes go through the pipeline individually. A failure on package #3 doesn’t undo packages #1 and #2. Faster converge, smaller blast radius.

GUARD

Self-learning rollback-prone list

Any package that triggers a rollback is tracked in learning.json. Next cycle treats it with extra caution (smaller step, LLM review even on minor, one-at-a-time promotion). The platform gets smarter every month.

LEARN

Optional LLM breaking-change review

If ANTHROPIC_API_KEY is set, Claude Haiku 4.5 scans the changelog + release notes for breaking API changes before we apply a major bump. Result is cached in the learning store. Offline / AIRLOCK deployments fall back to text-diff heuristics — never blocks the upgrade.

LLM

Offline-safe (AIRLOCK mode)

If PyPI, NVD, or the Claude API are unreachable (air-gapped / DMZ deployments), the updater logs and no-ops. Never crashes. Never leaves the env half-upgraded.

AIRLOCK

Append-only audit log

Every action — check, upgrade attempt, promote, rollback — lands in data/version_upgrades/audit.log as JSONL. Tamper-evident record for your own audit + post-mortems.

AUDIT

Zero external deps

Pure Python standard library + pip as subprocess. No extra packages to install, nothing to upgrade in the updater itself. Works the day you clone the repo.

STDLIB

How do I know it ran? How do I know what changed?

Four independent evidence surfaces — pick whichever fits your workflow.

What you want	Where to look	Command
Quick “is it running” check	`data/version_upgrades/state.json` — last_daily_utc / last_major_utc timestamps	`python -m core.agent_version_updater --status`
Human-readable last-run report	`data/version_upgrades/LAST_RUN_REPORT.md`	`python -m core.agent_version_updater --report`
Full jsonl audit (every action ever)	`data/version_upgrades/audit.log`	`tail -n 50 data/version_upgrades/audit.log`
Exact library versions currently active	`data/version_upgrades/active_freeze.txt`	`cat data/version_upgrades/active_freeze.txt`
Which agents are healthy right now	`--status` returns `agent_health` map (all 26)	`python -m core.agent_version_updater --status`
Rollback-prone package list	`data/version_upgrades/learning.json`	Shown in `--report` output
What’s scheduled right now	Windows: Task Scheduler library → TITAN_Daily_Upgrade / TITAN_Monthly_Major_Upgrade. Linux: `crontab -l` or `systemctl list-timers`	N/A

The report file — what you’ll see every morning

# TITAN AI - Version Self-Upgrader - Last Run Report
_Generated: 2026-04-23T08:47:14+00:00_

## Schedule status
- Last daily (security+minor) run: `2026-04-23T03:47:12+00:00`
- Last monthly (major) run:        `2026-04-01T04:17:08+00:00`
- Last rollback:                   `never`

## Last 5 runs
| Mode   | When (UTC)           | Targets | Promoted | Rolled back |
|--------|----------------------|---------|----------|-------------|
| daily  | 2026-04-23T03:47:12Z | 12      | true     | false       |
| daily  | 2026-04-22T03:47:11Z | 4       | true     | false       |
| major  | 2026-04-01T04:17:08Z | 3       | 3        | 0           |
| daily  | 2026-04-21T03:47:10Z | 7       | true     | false       |
| daily  | 2026-04-20T03:47:09Z | 9       | true     | false       |

## Rollback-prone packages (0)
_none - clean streak._

## Agent health (live import check)
- Total agents tracked: 29
- Healthy (imports cleanly): 29
- Failing: 0

| Agent    | Import |
|----------|--------|
| aml      | ok     |
| audit    | ok     |
| banking  | ok     |
| bastion  | ok     |
| code     | ok     |
| comply   | ok     |
| conduit  | ok     |
| ... (all 26 listed) ...

Install the scheduler (one command)

Run once on any customer's server after install. Writes platform-specific scheduler files to docs/scheduler/. You choose which one to wire in.

python -m core.agent_version_updater --install-schedule

Produces:

docs/scheduler/crontab.txt — Linux/macOS cron entries (daily + monthly + feed update)
docs/scheduler/install_windows_tasks.ps1 — elevated PowerShell script to register 3 Windows Scheduled Tasks
docs/scheduler/systemd.txt — systemd service + timer units for server deployments

CLI reference

python -m core.agent_version_updater --status           # last-run timestamps + per-agent health (all 26)
python -m core.agent_version_updater --report           # human-readable LAST_RUN_REPORT.md
python -m core.agent_version_updater --check-only       # dry-run; what WOULD change (no install)
python -m core.agent_version_updater --upgrade-security # daily cadence now
python -m core.agent_version_updater --upgrade-major    # monthly cadence now (one-at-a-time)
python -m core.agent_version_updater --upgrade-all      # daily + major back-to-back
python -m core.agent_version_updater --rollback         # revert to last-known-good freeze
python -m core.agent_version_updater --list-pending-major  # majors queued for monthly channel
python -m core.agent_version_updater --install-schedule # write scheduler files to docs/

Will this break? Will customers notice?

No. The smoke test has to pass on all 26 agents before a single change is promoted. If it doesn’t pass, we restore the exact environment that was working at 03:46 and log what tripped. Customer sees zero change. You see one line in LAST_RUN_REPORT.md telling you which package rolled back and why — handle it at your pace, not at 3am.

The only failure mode left: a package that passes the import + health-check smoke test but breaks in production under real traffic. That’s why every major bump also runs through TITAN RELIABILITY’s circuit breakers and graceful-degradation paths. If a real customer hits a broken path, the breaker opens, the old snapshot restores, and an incident lands on the ops board — see reliability.html.

Legal / cost posture

Same feeds Wiz, Orca, Qualys, Rapid7, Tenable, CrowdStrike, and Snyk use. Every source we pull — NVD, CISA KEV, MITRE ATT&CK, PyPI, NIST OSCAL, DISA STIG/SRG, CMMC, FFIEC, eCFR HIPAA — is public .gov/.mil or the authoritative landing page of a standards body. TITAN pays $0. No licensing issue. No “will I get in trouble” concern — these are the feeds every credible security tool uses, by design. Full list: compliance-feeds.html.

Consumed by

All 26 agents — every agent’s dependency graph stays current without anyone touching requirements.txt.
CONDUIT — the universal integration layer keeps its 8-destination HTTP / webhook client libraries patched.
TITAN AUDIT — evidence-pack generators update with the current framework revision numbers.
TITAN RELIABILITY — circuit breakers + graceful-degradation layer absorbs any runtime drift that slips past the import-time smoke test.

Bottom line: you sleep, we upgrade, we test, we promote or we roll back. You wake up to a clean LAST_RUN_REPORT.md. No 3am pages. No stale CVEs. No “oh, we forgot to upgrade that”.