Authored by Claude Opus 4.7 (Claude Code). Session 48197e2e-3e95-47eb-9eb8-bbb032948845 consuming handoff from session b5a17132-7324-46e1-b73e-038825bb4d55 (same model, prior session).

Resolves #10339

Summary

Closes Track 2C of the Phase 1 Swarm Autonomy epic (#10311) by adding a cron-driven TTL sweeper that atomically transitions stale A2A tasks past their task.expiresAt to the Expired state. Without this, tasks Submitted to offline agents accumulate eternally pending and tasks Working on agents that crashed mid-execution stay locked indefinitely (claim-and-lock from #10338 is permanent absent expiration). The sweeper is the operational primitive that maintains the queue's actionable-set bounded.

Built on the substrate landed in this session-arc:

• #10334 introduced the task.expiresAt ISO field on the MESSAGE node envelope.
• #10342 introduced the state machine (VALID_TASK_STATES + transitionTask) including the Expired terminal state.
• This PR adds the consumer that closes the loop — the cron-driven sweep.

Changes

• ai/mcp/server/memory-core/services/MailboxService.mjs — new sweepExpiredTasks() method: bulk atomic UPDATE-WHERE that transitions all non-terminal (Submitted/Working/InputRequired) MESSAGE-task nodes past expiresAt to Expired. Distinguished from transitionTask by three properties: no identity context required (maintenance role bypasses RBAC), no state-machine validation (the WHERE clause itself constrains source states), bulk operation (returns sweptCount for observability). NOT exposed via MCP tool surface — internal cron primitive only.
• ai/scripts/sweepExpiredTasks.mjs — thin CLI wrapper that boots LifecycleService, calls the sweep, prints {success, sweptCount} JSON to stdout. Designed for short-lived invocation by the heartbeat (~200ms cold-start per cycle, distributed across the 5-min poll interval). Exit codes 0/1 for shell capture.
• ai/scripts/swarm-heartbeat.sh — adds sweep_expired_tasks() shell function that invokes the JS CLI and parses the count. Sweep fires every cycle BEFORE the token-economy fast-path because TTL expiry is substrate maintenance, not agent-conversational. Sweep count does NOT factor into the inject decision (silent maintenance per AC); it surfaces in the heartbeat prompt only when the prompt is being injected anyway.
• test/playwright/unit/ai/mcp/server/memory-core/services/MailboxService.spec.mjs — new TTL Sweeper (#10339) describe block with 8 tests covering: multi-state transition (Submitted/Working/InputRequired), opt-in expiresAt skip, future-expiresAt skip, terminal-state preservation across all five terminal states, idempotency across consecutive cycles, atomic lastModifiedAt update, no-identity-context invocation, and a mixed-cohort end-to-end sweep.

Net: 383 insertions across 4 files (1 new, 3 modified).

Subtle Substrate Bug Caught + Fixed (Inline)

First test pass surfaced node returning null after sweep. Root cause: my raw db.storage.db.prepare(...).run(...) SQL UPDATE triggers node_update GraphLog entries via SQLite triggers (see ai/graph/storage/SQLite.mjs:125), and the next getAdjacentNodes call (e.g. via downstream transitionTask) invokes syncCache() which reads those entries as external invalidation events and removes the swept nodes from the in-memory cache.

Fix: call db.acknowledgeLocalMutations() immediately after the SQL UPDATE to fast-forward lastSyncId. Mirrors the discipline already used by GraphService.upsertNode (line 197-199) after storage.addNodes. Documented inline in the method JSDoc + comment block.

The same latent issue exists in transitionTask but is masked because its tests assert on the return value (res.task.state), not on the cached node state (db.nodes.get(id).properties.task.state). Surfacing this here as a memory anchor — could file a follow-up ticket if transitionTask consumers ever start reading via the cache and hit the same null trap.

Test Evidence

8 passed (835ms)  // TTL Sweeper isolation, run 1
8 passed (887ms)  // TTL Sweeper isolation, run 2
8 passed (853ms)  // TTL Sweeper isolation, run 3

8/8 stable in isolation × 3 consecutive runs.

Pre-existing cross-describe flakiness: When the full MailboxService.spec.mjs runs (43 tests across 5 describe blocks), 1-3 tests intermittently fail across DIFFERENT describes per run (#10174 / #10252 / #10338 patterns). Verified pre-existing by stashing my changes — 1 failure remained even without #10339 added. The pattern matches memory feedback_symmetric_spec_cleanup: Playwright fullyParallel interleaves specs in same worker; cross-singleton mutations need symmetric beforeEach + afterEach resets, and not all describes implement them. The defaultReplyPolicy pin is the most likely contamination vector. Out of scope for this PR; could file a tracking ticket for spec hardening.

To minimize my describe's contribution to that surface, the new TTL Sweeper describe:

• Uses suite-local agent IDs (@ttl-alice, @ttl-bob) instead of the shared @alice / @bob to avoid identity-node collisions across interleaved beforeEach runs.
• Defensively sets GraphService.db.autoSave = true in beforeEach (in case a prior describe's test left it false post-crash).
• Skips the unnecessary CAN_REPLY_TO grants — sweep itself bypasses RBAC, and the default policy is 'open' outside the #10174 pin window.

Acceptance Criteria — Per-Item Status

• swarm-heartbeat.sh extended with TTL sweep invocation (Path 1 inline via JS CLI per ticket recommendation; CLI wrapper makes the SQL JS-substrate-consistent + Playwright-testable).
• Sweep correctly transitions Submitted / Working / InputRequired tasks past expiresAt to Expired state — covered by test 1 (multi-state) + test 8 (mixed cohort).
• lastModifiedAt updated atomically with sweep transitions — covered by test 6 (atomic boundary check).
• Tasks WITHOUT expiresAt field unaffected (TTL is opt-in) — covered by test 2.
• Tasks already in terminal states not re-swept (idempotent) — covered by test 4 (all five terminal states) + test 5 (consecutive cycles).
• Observability: per-cycle log of swept count — emitted to stderr from heartbeat shell when count > 0 (zero-default to avoid noise per AC).
• No regression on heartbeat token-economy fast-path — sweep count does NOT factor into inject decision; verified by reading the modified shell flow.
• No new MCP tool surface — sweeper is internal cron primitive; OpenAPI schema unchanged.
• Test: integration test using Playwright unit-test (preferred over the ticket's suggested ai/examples/ script-style verification — Playwright is the canonical test substrate per memory feedback_mcp_test_location).

Cross-Skill Integration Audit (Self-Applied per pr-review §8.1)

• No predecessor skill needs to fire the sweep — it's substrate maintenance, not an agent-flow operation.
• No AGENTS_STARTUP.md §9 update needed (no new convention surface for agents).
• No reference file mentions a predecessor pattern that needs updating.
• No new MCP tool surface — sweeper is internal cron only (per ticket's own scope).
• No new convention introduced; the SQL-UPDATE-WHERE pattern follows the precedent set by transitionTask.
• NEW per pr-review §5.3 (PR #10348 just merged this audit step): No ai/mcp/server/*/openapi.yaml modifications — N/A.

Deltas from Ticket

• Path 1 inline + JS CLI hybrid rather than pure shell sqlite3 CLI inline. The ticket recommends Path 1 inline; I followed Path 1's operational shape (heartbeat invokes per cycle) but moved the SQL into JS via MailboxService.sweepExpiredTasks() for two reasons: testability (Playwright direct call vs awkward shell-test scaffolding), and substrate consistency (rest of MailboxService uses better-sqlite3 from JS). Trade-off documented: ~200ms Node startup per heartbeat cycle (288 cycles/day × 2 agents = ~58s/day per agent, negligible).
• acknowledgeLocalMutations fix caught and addressed inline (see "Subtle Substrate Bug" section above) — surfaced by testing infrastructure that wasn't part of the original ticket scope.

Post-Merge Validation

• Run heartbeat with seeded expired test task; verify the stderr log emits sweep: 1 task(s) transitioned to Expired once per cycle.
• Verify MailboxService.transitionTask consumers reading via cache see fresh state after sweep (the latent bug noted above could be a follow-up if encountered).

Cross-Family Review Request

Per pull-request §6.1 cross-family mandate. Requesting review from @neo-gemini-pro after she finishes the cross-family review on PR #10348.

Related

• #10311 — Phase 1 Swarm Autonomy epic; this completes Track 2C.
• #10334 — A2A Task envelope primitive (introduced expiresAt).
• #10342 — A2A state machine (introduced Expired state).
• #10335 — swarm-heartbeat.sh originator (Track 1 MVP).
• #10339 — this ticket.
• #10319 — concurrency semantics; orthogonal to TTL sweep but adjacent territory.