agent-farm: PTY session logs have no rotation or retention policy

[waleedkadous]

Found during a disk audit (2026-07-25): ~/.agent-farm/logs held 29,728 PTY session log files totaling 19 GB, 97% of them older than 30 days — only ~300 files had been touched in the past week. Logs accrete forever; nothing rotates, caps, or expires them.

Proposal:

• Retention policy (e.g. delete session logs N days after their session ends; N=30 default, configurable).
• Enforced by Tower on a periodic sweep (it already runs an orphan sweep) or at workspace start.
• codev doctor could report total log footprint as a health line.

On the audited machine this was the 4th-largest disk consumer, ahead of most caches.

[waleedkadous]

Completed — PR #1243 merged (c8d8be78)

PTY session logs now have a retention policy. A log is deleted once its mtime passes the retention window; Tower enforces it at startup and on a daily timer, and codev doctor reports the footprint.

Delivered

Protocol	AIR, 1 iteration, no escalation
PR	#1243 → merged c8d8be78
Commits	7 (4 substantive + 3 porch state)
Diff	673 insertions / 1 deletion, 6 files
Production code	226 lines (excl. comments/blanks) — within AIR's <300 budget. Raw added production lines were 347, of which 93 are rationale comments.
Tests	324 lines, 26 new tests (18 sweep + 8 doctor)
Full suite	3667 passed / 0 failed
Required CI	6/6 green
Wall clock	09:40Z → 12:43Z (~3h02m); of that 2h41m was gate wait — active build+review was ~21 min

Configuration

Variable	Default	Meaning
AGENT_FARM_LOG_RETENTION_DAYS	30	Age at which a log is deleted. 0 disables the sweep — an explicit opt-out for anyone treating these as an audit trail.
AGENT_FARM_LOG_SWEEP_INTERVAL_MS	86400000 (24h)	Sweep cadence, floored at 1s.

Env vars rather than .codev/config.json, because the log dir is user-global (~/.agent-farm/logs), not per-workspace — same precedent as SHELLPER_HUSK_GRACE_MS.

Verified against the real 2.1 GB log directory

Not just green tests. The built module was run against an mtime-preserving copy of the live ~/.agent-farm/logs (737 files / 2.1 GB) — never the real directory:

BEFORE: 737 files, 2.1 GB, oldest=2026-06-24T08:31:12.921Z
30d retention → deleted 12 logs, freed 29 MB
 7d retention → deleted 418 logs, freed 1.4 GB

Live-session exclusion on real aged data: a 23-day-old log whose id was passed as active survived a 7-day sweep, while 429 others were deleted. This matters because a session's log fd stays open for its whole life — unlinking under a live writer would silently redirect subsequent writes into an unlinked inode.

codev doctor render, from the built CLI (the real machine is over the 2 GB threshold, so this exercised the warn branch):

Session Logs (~/.agent-farm/logs)

  ⚠ 741 file(s), 2.1 GB (retention 30d)

CMAP at PR

• claude — APPROVE (HIGH). One finding: unused MS_PER_DAY. Accepted; exported and used in tower-server.ts.
• codex — REQUEST_CHANGES (MEDIUM). Two findings:
  • doctor logic untested / not isolated — accepted: extracted checkSessionLogs(logDir, env) and added 8 focused tests using sparse files, so the 2 GB threshold case costs no real disk.
  • drop status.yaml and the builder thread file — rejected and upheld by the architect (same ruling as bugfix-1224): both are committed to main by Codev convention.

Known gap

The "Tower boots → sweep fires" edge was never exercised live — verifying it requires a Tower restart, which kills every running builder session, so it was left to the human. Everything the startup path calls is verified above. On the next Tower restart the boot log should read:

Session logs: N file(s), X GB (retention 30d)

Spun off

• codev doctor: findWorkspaceRoot accepts packages/codev as an instance marker, silently auditing the wrong tree #1246 (area/scaffold) — codev doctor's findWorkspaceRoot() accepts packages/codev (the npm package) as a codev-instance marker, so running doctor from packages/ silently audits the wrong tree. Found while working this issue; reproduces on main. Deliberately not fixed here to keep this PR scoped.