Symphony / Codex vacuum timed job

Nightly Codex vacuum

A direct housekeeping timer that checkpoints and vacuums Codex local sqlite stores so long-running Symphony usage does not accumulate bloated telemetry databases.

Cadence 06:00 host timeMode direct housekeepingScope logs_*.sqlite + state_*.sqliteOutput journal size lines

systemd timer->sqlite discovery->checkpoint + vacuum->size report

Operating model

timed job

Unlike report routes, this timer does not create a Linear issue. It runs as the symphony user, scans CODEX_HOME for Codex sqlite stores, folds WAL files back into the main databases, and vacuums each store.

06:00

Nightly start

systemd calendar

Database globs

logs and state stores

Linear writes

direct maintenance

Required tool

sqlite3 on PATH

KEYKeep Codex stores small enough to checkpoint

Large WAL-backed stores can stall checkpoints and make agent sessions sluggish. This job keeps the local rollout stores from becoming an operational drag.

System shape

click the nodes

The direct housekeeping path is intentionally narrower than the report routes: no workspace, no Codex turn, and no Linear issue.

Cadence design

compare modes

Each timed job has a small set of modes that decide whether the run is healthy, degraded, or ready to create follow-up work. Use the controls to compare the operating contract.

Discover

Find only Codex sqlite stores

The script uses a narrow CODEX_HOME search and nullglob so missing stores are a no-op, not a failure.

CODEX_HOME resolved
logs_*.sqlite glob checked
state_*.sqlite glob checked
no-store path exits 0

Maintenance confidence threshold82%

Run manually and inspect journal output before trusting the nightly cadence.

Execution tracks

interactive

The tracks make each run inspectable. They separate inputs, outputs, and failure modes so reports do not collapse into vague status updates.

Codex local stores

Scope

Limit maintenance to Codex telemetry and state stores under CODEX_HOME.

Inputs

CODEX_HOME
logs_*.sqlite
state_*.sqlite

Outputs

database list
nothing-to-vacuum message
bounded maintenance scope

Maintenance risk map

priority map

The script is narrow, but these details protect it from being either ineffective or too aggressive.

CODEX_HOME correctnesswrong home means the job vacuums nothing useful

96

sqlite3 availabilitymissing binary makes the timer fail every night

88

WAL checkpoint ordervacuum without checkpoint can leave WAL residue

84

Glob scopeonly Codex sqlite stores should be touched

78

Journal evidenceoperators need size deltas to prove work happened

68

No Linear issuedirect jobs must be monitored through systemd, not Symphony states

54

This job should never delete Codex stores. It uses SQLite compaction only, so a vacuum failure is safer than an over-broad cleanup.

Output rubric

ticket rules

The run should create follow-up work only when the output is concrete. Use the rubric to keep reports, bug tickets, and operational follow-ups separated.

Vacuumed

One or more stores were compacted and before or after byte counts were printed.

logs_2026.sqlite compacted
state_2026.sqlite compacted

Run contract

evidence rows

The contract is small: discover bounded database files, compact them with SQLite, and print enough evidence for systemd logs.

Service

Direct timer

symphony-codex-vacuum.timer starts symphony-codex-vacuum.service as the symphony user.

Boundary

No issue route

The job does not create Linear issues and does not invoke Codex. It is host maintenance with systemd as the control plane.

CODEX_HOME

sqlite3 present on PATH

logs_*.sqlite files discovered

state_*.sqlite files discovered

wal_checkpoint(TRUNCATE) run

VACUUM run

Before and after byte counts

No-store no-op message when applicable

Command plan

operator path

Operators can install, run, and inspect this job entirely through systemd and the script.

Manual runsudo -u symphony /opt/symphony/elixir/scripts/codex_logs_vacuum.sh

Timer installsudo systemctl enable --now symphony-codex-vacuum.timer

List timersystemctl list-timers | grep symphony-codex-vacuum

Read journaljournalctl -u symphony-codex-vacuum.service -n 80 --no-pager

!Install sqlite3 first

The script intentionally fails when sqlite3 is unavailable. Install the package instead of hiding the failure.

Rollout path

ship safely

Install sqlite3 dependency

Confirm sqlite3 is on PATH for the symphony user.

Run manually once evidence

Inspect before and after byte counts and no-op behavior before enabling the timer.

Enable nightly timer systemd

Install the service and timer units, daemon-reload, and enable the timer.

Inspect journal drift ops

Check for repeated setup failures, wrong CODEX_HOME, or unexpectedly large stores.