docs(loops): record the due-loop sweep, its idle cost and who reads the loop tables (#3436)

[vybe]

Fixes #3436. One of five independent stale-code PRs off dev. Docs only — 39 lines added, 3 removed, four files under docs/memory/.

What

The issue asked for agent loops to cost nothing on an instance with no loops. The diagnosis found the cost is already negligible, and the operator ruled no code change (comment on the issue, 2026-10-09). This PR records what was found, so the next reader does not have to rediscover it.

• architecture/background-services.md — a row for the loop due-run sweep, which was missing: started from main.py, first tick after 8–10 s, then every 5–6 s, in every backend worker with no leader lease (claim_due_loop decides which worker dispatches). With nothing parked it is one index seek on idx_loops_next_run returning no rows. The startup loop hook is renamed to what it does since feat(pull): make loops terminal-driven so they can run on the durable queue #2523: it re-arms or advances, and interrupts nothing.
• requirements/scheduling.md — §38.8, the restart-recovery behaviour from feat(pull): make loops terminal-driven so they can run on the durable queue #2523, which had no requirements entry; §38.9, the idle cost and why the sweep is deliberately not gated. §38.1's older restart bullet is marked superseded.
• architecture/execution.md — the sequential-loops paragraph described the pre-feat(pull): make loops terminal-driven so they can run on the durable queue #2523 in-process runner. It now describes the terminal-driven design: the row is the loop, stop stamps stop_requested_at, and the counter and fingerprint are rebuilt from the loop's run rows on every advance.
• feature-flows/run-agent-loop.md — who reads the loop tables without being asked: the sweep, the boot reconcile, and the per-terminal get_loop_run_by_execution lookup, which cannot be gated because a loop run's terminal can land on a worker that never touched the loop.

Ruling carried (operator, recorded on the issue)

• No code change. The sweep is the only continuous reader. Measured on a development database: about 6 µs per query, about 15,700 queries a day per worker. Gating it would add arm/disarm state to loop recovery and delay the pickup of a loop parked by a stuck worker until that worker is respawned.
• Acceptance criterion 2 ("no recurring background query touches the loop tables") is re-ruled as met by cost, not by count. No index, no test change.

Review

/review (reading review, report-only): MERGEABLE. All 14 factual statements the diff adds were checked against the code on the branch tip, each with a quoted line, and are true. One is scoped rather than universal: "index seek" holds for SQLite; PostgreSQL may scan a table this small. Fixed after review: four stale sentences in the touched paragraphs. Docs only, so the security pass is a paragraph: nothing sensitive in the added lines.

Tests

• Doc guards (test_2306, test_2338, test_2070, test_2339, test_2350): 147 passed.
• Links: 42 relative links and anchors in the four files resolve.
• git merge-tree against dev (21b4a11): clean. No conflict with the other four PRs of this set or with open PRs sharing these files (feat(skills): one Skills tab — own and shared skills, Run, Requires approval (abilityai/trinity-enterprise#754) #3412, fix(auth): an agent key reaches only itself, its edges and the agents it spawned — on the raw backend routes too (trinity-enterprise#629) #3346, feat(workspace): a stage advance reaches the Work card on the write, not the next poll (ent#533) #2713).

Before merge

Nothing beyond review.

Handoffs (from the plan, not filed)

• agent_loops / agent_loop_runs have no retention prune (only the cascade on agent delete) — the boot reconcile is a table scan that grows forever; same class as refactor(retention): product_events grows without bound — prune_product_events() has zero callers; wire the standard retention sweep #2442.
• The per-terminal lookup could become row-gated by threading schedule_executions.loop_id through spawn_task_terminal_event (16 call sites) — saves one ~4 µs read per non-loop terminal.

🤖 Generated with Claude Code