docs(coil): Loops — design, prototypes and implementation plan (#42, #38 residue)

[radroid]

Design and plan for Loops — running a T3 Coil thread unattended, and, more to the point, what you see when you come back to it. Consolidates #42 (self-paced loops) with the residue #38 left when it closed ("durability + acting on the signal"); #44 (maintainer agent) is sequenced after and shares the reactor.

Docs only. 18 files, +16,831, zero deletions, no code, no seam rows. Nothing here ships behaviour — it exists to be argued with before any of it gets built.

What's in it

File	What it is
report.html	the design report — 8 clickable prototypes inlined, single self-contained file, no server needed
PLAN.md	the implementation plan, written to be read without repo access
BACKEND.md	full backend design, including the architectures I rejected and why
TESTS.md	159 test cases
UPSTREAM-DELTA.md	re-verification against upstream, and against the post-sync tree
FINDINGS.md	raw research notes
prototypes/, build-report.mjs	the prototype sources and the inliner that builds the report

gh pr checkout <this>
open docs/coil/loops-v2/report.html      # start here — the prototypes are interactive

Why this supersedes the 2026-08-02 design

docs/coil/loop/ was frozen on 2026-08-02 and never built. Three things have since made it out of date, and all three make the feature cheaper:

1. Upstream shipped thread pinning (da6e1a967) two days after that design froze. A pin overrides the settled/snoozed lifecycle, so "a loop is a thread that stays at the top" is now mostly an upstream feature. The old design's long argument for a bespoke sidebar rail is correct and moot.
2. Sidebar.tsx / Sidebar.logic.ts are not seam rows. Loop-as-pinned-thread costs zero; bespoke loop rendering would open a new row in a 3911-line file that took 7 commits in 3 days. That kills the middle option outright.
3. AskUserQuestion already gives structured questions natively — and blocks the turn. A correct question at 01:00 costs the whole night. Hence a second, non-blocking channel beside it.

That third point got worse while this was being written. Upstream pingdotgg#5127 now settles a pending question as an empty answer when the session stops — so an unanswered question isn't merely stranded, the agent receives {}, a thing shaped like a decision that carries none, and proceeds on it. The human never sees the question at all.

The shape

• The console is the headline. One page answering "what do you need from me?" — blocking items, deferred blockers, loop state, iteration ledger. It reads three sources, two of which need no model cooperation, so a model that never calls raise_blocker still produces a useful page. That degradation property is the acceptance test.
• T3 backstops Claude's scheduler; it does not replace it. [Feature]: Self-paced loops — the Claude binary can already wake a T3 thread; surface it, bound it, and give models a durable T3-native wake_me instead #42's read that the scheduler is unusable is stale — the gates are on and upstream 2c7267ad4 made the reaper skip live background work, so self-paced wakes ≤30min land reliably. T3 defers when a wake is pending and covers only what an in-process scheduler cannot: wakes over an hour, wakes lost to a restart, non-Claude providers, and any notion of a budget.
• Trigger on updatedAt staleness — never on session.status. A background subagent's message auto-opens a synthetic turn that pins status = running and nothing closes it, so gating on it deadlocks exactly the threads this is for.
• A → C, agreed. Pinned thread first, Loops workspace later. Never the middle option.
• spent must never read as success. "It finished" vs "it ran out of rope" is the distinction that actually failed in practice.

What it costs the fork

Three new seam rows for phases 1–4, ~7 lines, all additive, against a ledger that carries 53:

Phase	File	Delta
1	ClaudeAdapter.ts	+1 — one spread beside the existing mcpServers one, read-only
4	settingsSearch.ts	~+4
4	SettingsSidebarNav.tsx	+2
3	_chat.…$threadId.tsx	±0 — existing row rewritten in place
—	packages/contracts, Sidebar.tsx, Sidebar.logic.ts, server.ts	0

The settings pricing is not an estimate — upstream shipped /settings/integrations (pingdotgg#7082) three days ago, so it's read off a worked example, including which two expensive rows to avoid.

Verification

Every claim in PLAN.md is marked [V] (a command verified it) or [A] (assumed). Every [A] is a place this could be wrong, and they're listed rather than buried.

The branch was cut before the 116-commit sync landed. Main was then force-rewritten under it, so this was rebased onto the new main (f6355f06f, merge-base a4cc1367b, zero behind upstream), and re-based once more onto 94c6328ef after the daily sync force-rewrote main a second time and every load-bearing claim re-run against the fork's own post-sync tree — a stronger check than against upstream, since it's the tree the work would be built on. Recorded as UPSTREAM-DELTA.md §7. Nothing moved: the beachhead is still empty (session_crons / ScheduleWakeup / CronCreate zero across server and contracts, options.hooks unset, toolkits still only preview), Sidebar.logic.ts is still zero-diff, the overlay row is still +10/−6, pinnedAt is still in contracts.

One useful side effect: the sync also dissolved the plan's only sequencing constraint, and it answers open wayfinder issue #112 — registering a right-panel tab costs 2 seam rows.

What I want from review

PLAN.md §10 has the four questions where an outside opinion is worth most, and §11 states what would falsify each major decision, so disagreement can aim at evidence rather than taste. The two I'd most like challenged:

• Is deference to Claude's scheduler right, or merely clever? It's more correct and more complex, and it makes behaviour depend on a hook whose delivery is still [A].
• Should the console be loop-scoped at all, or a global "needs you" inbox from day one? The second is barely more work, is useful with loops switched off, and might be the better feature.

Build order

Phase 1 is deliberately inert — record session_crons and the durable state, act on nothing — because that is the cheapest way to test the plan's largest assumption. If the Stop hook doesn't deliver session_crons as documented, the design changes there and one additive line is the whole loss.

Phase 0 is unrelated debt this turned up: the fork has two independent mirrors of upstream's private HTTP scope-auth, in autoResume and webPush. Promote the parameterised one and let the loop routes be the third caller rather than the third paste.

Not for merge

Draft on purpose — this is the artefact for independent review, and per the original brief nothing lands on main until the feature is done. Happy to mark it ready and merge the docs early if you'd rather implementation PRs reference a merged plan.

UI changes

None — no product code is touched. The visuals are prototypes; open report.html to click through them.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 41deaab5-ec50-4322-8d44-e1fdea35df59

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[radroid]

Review — two axes, then fixes (pushed as 8d87b8b59…bf947b06d)

Ran the review this PR asked for: standards vs the repo's docs (AGENTS.md, docs/coil/agents/*, SEAMS conventions), spec vs #42 / #38's residue / #44 / #112, plus a claim-re-verification pass that re-ran every checkable [V] against the post-sync tree, an internal-consistency pass, and static QA over the prototypes and build-report.mjs. 102 raw findings, ~60 unique after dedupe; every fix below was verified against the code before editing. All fixes are on the branch; the design itself was not relitigated — Q1–Q4 in PLAN §10 are still yours to decide.

Standards

• Formatting: 17/18 files had escaped the vp fmt staged hook. Now formatted (2c995f5d0); committed pipeline is build → fmt, idempotent.
• Baseline citation: the docs anchored on fork-main f6355f06f, which the next daily sync force-rewrote away. Now anchored on the merge-base a4cc1367b, with the 08-18 rewrite to 94c6328ef recorded (same merge-base; the two extra upstream commits touch nothing load-bearing).
• AGENTS.md conflicts: TESTS.md endorsed the repo-wide test command (now: targeted vp test run, CI owns the suite); the prototypes' spinning glyph is now the product's stepped pulse; a11y basics added (role="switch"/aria-checked, labels on icon-only buttons, p6 heading order).
• Stale figures re-stamped on the a4cc1367b ledger: ClaudeAdapter churn 16 / ~4.6k lines, orchestration.ts 20, settingsSearch.ts 14, SettingsPanels 36/2088, contracts/settings 26, the _chat row churn 4 / risk 64 (added delta still 0), Sidebar +184/−81, nine settings routes, feat(web): configurable browser defaults in Settings → Integrations pingdotgg/t3code#7082 landed the same day.
• docs/coil/loop/report.html now carries a superseded banner; DESIGN.md's banner no longer overclaims (feat: scheduled tasks (automations) pingdotgg/t3code#3638 verified still not on upstream/main; feat: native subagent & workflow observability pingdotgg/t3code#5219 named).

Spec

Three claims did not survive re-verification against the code and are corrected everywhere they appeared:

1. fix(server): settle pending user-input requests when a Claude session stops pingdotgg/t3code#5127: the aborted branch resolves the Deferred with {} but then denies the tool call while the session stops — the agent does not "proceed on a null choice". What survives (and still justifies the durable record): user-input.resolved carries empty answers, so a voided question is indistinguishable from an answered one downstream.
2. §1.4's "second kill": upstream fix(server): stop Claude resume handshakes from completing turns that never ran pingdotgg/t3code#5710 (e70cdb478) removed the untargeted turn.completed — that branch now emits token usage + a log only. The turn-boundary rejection now rests on the Stop-path kill and fails-open.
3. total_cost_usd is stamped onto turn.completed.totalCostUsd, not "unread"; nothing aggregates it, semantics stay [A].

The compose-don't-replace correction had been applied unevenly — the check-in prompt still said "I am the scheduler… do not schedule your own wake-ups", the report kept the kill switch PLAN drops, and session_crons was still "Phase 3" in three places. All unified on the composed story. Also: session_crons delivers a cron expression, not a timestamp (SessionCronSummary in sdk.d.ts 0.3.170) — the nextFireAtMs parse is now an explicit fork-side [A].

Four spec-conformance changes worth your eyes (each follows #42/#44 rather than my taste):

• Deference is now grace-bounded, not threshold-bounded ([Feature]: Self-paced loops — the Claude binary can already wake a T3 thread; surface it, bound it, and give models a durable T3-native wake_me instead #42 Guard chore(t3x): auto-build on a 12h cadence, not every main commit #15): T3 stands down while a recorded wake is pending at any distance, fires wake_lost only past wakeGraceMs. Previously a legal 45–60 min ScheduleWakeup got nudged mid-wait.
• Bounds can now stop a self-paced run: terminal states/disarm with pending crons call stopSession ([Feature]: Self-paced loops — the Claude binary can already wake a T3 thread; surface it, bound it, and give models a durable T3-native wake_me instead #42 1c's honest cancel) — otherwise the deadline was advisory.
• LoopRecord.checkIns[] added so the console's iteration ledger has backing data ([Feature]: supervise long-running threads — turns complete while background subagents are still working, and nothing restarts the run #38's close required it in the phase-1 schema); ledger rows render derived facts, never model summaries.
• p2/p6 priced honestly: the sidebar row chrome is Sidebar.tsx work and is now stated as deferred (v1 = plain pinned row); the maintainer copy carries [Feature]: maintainer agent — work a repo's issue queue automatically (triage → plan or draft PR → human approval) #44's v1 contract (never pushes, PRs opt-in later).

Counts now agree everywhere (159 test cases incl. the report's table, fifteen guards, five p1 scenarios, fifteen p5 states — self-pacing and wake-lost added), section refs renumbered after the mobile insert, the orphaned decision-4 chips are gone, prototype tokens re-lifted where they'd drifted ([data-app-sidebar] values, sky-300), and build-report.mjs got a function replacer, escaping on marker fields, a GENERATED banner, and +x.

Loose end: #112's answer (RightPanelTabs churn 14, rightPanelStore 7, no extension point — the tab switch is the only way in) now lives in UPSTREAM-DELTA §4; worth copying onto the issue when you close it.

Review + fixes by Claude Fable 5 (Claude Code); finder/fixer passes ran on Opus.