fix(core): bound recovery copies and add workit gc

[BrainerVirus]

Stacked on #150 (bugfix/store-lock-reclaim). Review only the top two commits.

CI note: this PR targets a non-main branch, so the CI workflows do not run on it. They will run once it is retargeted to main after #150 merges. Local verification is below.

What

• Recovery copies are capped. Each task or workspace record keeps its newest 3 copies (RECOVERY_COPIES_PER_RECORD) in .workit/recovery/. Pruning runs after each copy, always keeps the copy just written, and is best-effort: a pruning failure never fails the mutation. When an existing copy is saved again with the same bytes, its mtime is refreshed so it counts as newest.

• New workit gc [--dry-run] [--json] (TaskStore.collectGarbage). It runs in the current directory and:

  • prunes every record's copies down to the cap,
  • removes *.tmp files older than 1 h that crashed writers left in recovery/, tasks/ and .workit/,
  • dedupes stored candidates where it is safe: duplicate copies of the same content-addressed candidate ID collapse to their latest position, so lookups by ID and candidates.at(-1) are unchanged. This only happens in paused tasks. Active tasks (skippedActive) are left alone so a live session's revision is not bumped under it. Closed tasks (skippedClosed) are never rewritten, because they are immutable history (docs/workit-v1/contracts.md).

  It never deletes tasks/*.json or workspace.json. --dry-run is strictly read-only: no lock, no mkdir, no .gitignore rewrite. The root resolves like task commands (WORKFLOW_WORKSPACE_ROOT, then cwd).

• state.recover is no longer advertised. I checked the claim in code first. The operation requires OperationContext.nativeRecovery, and no production host sets it. The only sources are workit-cli/src/task.ts deps.nativeRecovery, which index.tsx never passes, and two core tests. The OpenCode, Pi, MCP (Cursor and Codex) and CLI hosts all go through paths without it, so in production the operation can only return permission_denied. Changes:

  • operationJsonSchema and boundedOperationJsonSchema now use the new advertisedOperationSchemas, where state is export|import. MCP and Pi read their schemas from these.
  • OpenCode's tool shape uses advertisedOperationSchemas.
  • The CLI drops state recover.
  • parseOperation and the engine path are unchanged, so embedders that do supply nativeRecovery, and the existing continuity tests, keep working.

• README, AGENTS.md and CHANGELOG are updated.

Why

The audit (§3.4, §6 #3 and #10, §7.2 #2) measured 818 MB and 5,752 files in recovery/ for 74 tasks, growing about quadratically with mutations. It also found that state.recover was advertised on every host but could not succeed anywhere.

Given/When/Then covered (test/workit-core/recovery-gc.test.ts)

• Given 20 writes to one task, Then at most 3 recovery copies remain and the latest prior bytes are kept
• Given 1,000 writes to one task (soak, opt-in with WORKIT_SOAK=1; measured 7.9 s and passing)
• Given a recovery dir with N stale copies per record, When gc runs, Then each record keeps only the newest copies up to the cap (40 task copies and 25 workspace copies leave 3 + 3)
• Given gc --dry-run, Then it reports what it would remove and writes nothing at all (unchanged .workit listing and mtimes; no .gitignore or lock created)
• Given gc runs, Then every current read returns the same records (byte-identical tasks/*.json and workspace.json, equal listTasks)
• Given paused, active, and closed tasks with duplicate stored candidates, When gc runs, Then only the paused task collapses to its latest positions (the closed record's bytes are unchanged)
• Given a stale leftover temp file, When gc runs, Then it is removed while fresh temp files stay
• Given stale recovery copies, When workit gc --json runs, Then it prunes to the cap and reports the count
• Given no host supplies native recovery authority, Then state.recover is not advertised but stays parseable for the engine

Existing tests updated, none deleted:

• task-commands.test.ts: the CLI action count goes from 24 to 23.
• mcp/server.test.ts: the advertised-action parity excludes state.recover.

Verification (measured, Node 24.20.0, Bun 1.3.14, in the worktree)

• Red before the change: on the S1 code, 1,000 mutateTask writes left 1000 recovery files. With this change they leave 3. The time for 1,000 writes is fsync-bound and stayed in the same range across runs (S1: 7.8 s / 22.8 s, S2: 8.9 s / 38.9 s on a noisy disk; no consistent regression). The new test file could not even load against S1 because collectGarbage and RECOVERY_COPIES_PER_RECORD did not exist yet.
• Green after: 8/8 recovery-gc tests, MCP server 17/17, CLI task-commands green.
• End to end with the built CLI (node packages/workit-cli/dist/index.js): a checkout seeded with 6,000 stale copies (3,000 task + 3,000 workspace) went through workit gc in 0.6 s, with 5,994 copies removed (11.8 MB) and 6 kept. task inspect output was byte-identical before and after. A later task progress succeeded and the directory stayed at 6 files.
• bun run lint ✅, format:check ✅, typecheck ✅, knip ✅, build ✅.
• Full bun test after the review fixes: 1598 pass / 1 skip (soak) / 1 fail. The one failure is AR-14, which already fails on origin/main because its repoRoot resolves to the parent of the checkout (details in fix(core): reclaim stale metadata locks and report contention as busy #150).

Risks

• Pruning orders copies by mtime with nanosecond precision. A filesystem with coarse mtimes could tie-break by name, but the copy just written is always kept.
• The first write after upgrade still lists the whole recovery/ directory, but only lstats the copies of that one record. Running workit gc once clears old backlogs.
• Candidate dedupe bumps the revision of the paused tasks it rewrites. A stale explicit expectedRevision held for such a task gets revision_conflict.

🤖 Generated with Claude Code

[github-actions]

🎉 This PR is included in version 2.2.0 🎉

The release is available on:

• v2.2.0
• GitHub release

Your semantic-release bot 📦🚀