Skip to content

Commit 8d87b8b

Browse files
radroidclaude
andcommitted
docs(coil): resolve the independent review's findings across the Loops package
A five-axis review (standards / spec / claim re-verification / internal consistency / prototype QA) turned up 102 findings, ~60 unique. The load-bearing ones, all verified against the code before editing: - The compose-don't-replace correction was applied unevenly: the check-in prompt still said "I am the scheduler for this thread. Do not schedule your own wake-ups", the report kept the CLAUDE_CODE_DISABLE_CRON switch PLAN drops, and the report's deferred table still had session_crons in Phase 3. All now carry the composed story. - Deference now matches #42's Guard #15: T3 stands down while a recorded wake is pending regardless of distance (the binary clamps at 3600s), and fires wake_lost only past a new wakeGraceMs. TESTS 11c reworded. - session_crons carries a cron EXPRESSION, not a timestamp (SessionCronSummary in sdk.d.ts 0.3.170) — the nextFireAtMs parse is the fork's and is now an explicit [A]. - pingdotgg#5127's voiding was overstated: the aborted branch resolves the Deferred with {} but then DENIES the tool call while the session stops. What survives is user-input.resolved with empty answers — voided reads as answered downstream, which is still why the durable record exists. - The §1.4 "second kill" is gone upstream (pingdotgg#5710, e70cdb4): the no-turnState branch emits token usage plus a log, no lifecycle event. - total_cost_usd is stamped onto turn.completed.totalCostUsd, not "unread"; nothing aggregates it, and its semantics stay [A]. - Numbers re-stamped on the a4cc136 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 (the fork's added delta stays 0), Sidebar +184/-81. #112 answered with measured churn (RightPanelTabs 14, rightPanelStore 7). - Seam accounting unified on PLAN §6 (3 rows, phases 1-4); SETTINGS_SECTION_ICONS attributed to SettingsSidebarNav.tsx; the "search-invisible" claim dropped (the id union is derived). - Fork main SHAs are rewritten by every sync, so the docs now anchor on the merge-base; the 08-18 force-rewrite to 94c6328 is recorded. - Report section refs renumbered after the mobile insert (§13→§14 etc.), the 137-sum test table now sums to 159, the orphaned decision-4 chips and the four-vs-five scenario counts fixed. - Prototypes: tokens re-lifted where they had drifted ([data-app-sidebar] values, sky-300 not sky-400, computed base literals), p5 gains the self-pacing and wake-lost states (15 total), the spinner became the product's stepped pulse, switches got role/aria, p2 prices the sidebar row chrome honestly (deferred — it would be a new Sidebar.tsx row), p6/p3 align with #44's v1 contract (never pushes, PRs opt-in later). - build-report.mjs: function replacer, escapeHtml on marker fields, a GENERATED banner in the output, honest self-containedness claim, +x. - LoopRecord gains the checkIns array the console's ledger reads; workSource leaves phase 1 (lands with #44); stop-with-pending-crons now calls stopSession, the honest cancel from #42 1c. - The archived loop/ design's DESIGN.md banner no longer overclaims, and its report.html carries a superseded pointer. Co-Authored-By: Claude Fable 5 <[email protected]>
1 parent e4ab571 commit 8d87b8b

18 files changed

Lines changed: 862 additions & 697 deletions

‎docs/coil/loop/DESIGN.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
# Loop Watch — design (radroid/t3code#38)
22

33
> **Superseded by [`docs/coil/loops-v2/`](../loops-v2/PLAN.md) (2026-08-17).** The re-checks the
4-
> paragraph below asks for were done there — see
5-
> [`loops-v2/UPSTREAM-DELTA.md`](../loops-v2/UPSTREAM-DELTA.md) — and three of this design's
4+
> second paragraph below asks for are covered in
5+
> [`loops-v2/UPSTREAM-DELTA.md`](../loops-v2/UPSTREAM-DELTA.md): #5219 as `ThreadBackgroundLiveness`
6+
> in its §2, and #3638 confirmed still not on `upstream/main` in its §1. Three of this design's
67
> premises did not survive them.
78
>
89
> **Status: designed, not built.** No `apps/server/src/coil/loop/` exists — every path this

‎docs/coil/loop/report.html‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1393,6 +1393,20 @@
13931393
</style>
13941394
</head>
13951395
<body>
1396+
<div
1397+
style="
1398+
font-family: var(--mono);
1399+
font-size: 11px;
1400+
letter-spacing: 0.14em;
1401+
text-transform: uppercase;
1402+
color: var(--ink-faint);
1403+
border-bottom: 1px solid var(--rule-soft);
1404+
padding: 10px 20px;
1405+
"
1406+
>
1407+
Superseded 2026-08-17 →
1408+
<a href="../loops-v2/report.html" style="color: var(--ink-dim)">../loops-v2/report.html</a>
1409+
</div>
13961410
<div class="rule-top"></div>
13971411

13981412
<div class="wrap">

‎docs/coil/loops-v2/BACKEND.md‎

Lines changed: 113 additions & 50 deletions
Large diffs are not rendered by default.

‎docs/coil/loops-v2/FINDINGS.md‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,8 @@ da6e1a967 2026-08-04 feat(sidebar-v2): thread pinning for sidebar v2 (#5312)
2323
> A pin overrides the settled/snoozed lifecycle: while `pinnedAt` is set the thread renders
2424
> in the pinned block and never classifies into a shelf.
2525
26-
Also real today: `thread.pinned` / `thread.unpinned` commands (`:1056-1057`), a fractional
26+
Also real today: `thread.pinned` / `thread.unpinned` **events** (`:1056-1057`; the commands that
27+
produce them are `thread.pin` / `thread.unpin`), a fractional
2728
`pinOrderKey` for user-arranged order, a drag-reorderable pinned block in `Sidebar.tsx`
2829
(`SortablePinnedThreadRow`, `planPinnedReorder`), and the pinned block deliberately renders
2930
with **no header** (`Sidebar.tsx:674`).
@@ -222,7 +223,7 @@ Design consequences to work through in the prototypes:
222223
much they already exist: (a) real pending approvals / pending user input / actionable
223224
proposed plans — all already SQL-backed columns on `OrchestrationThreadShell`
224225
(`contracts/orchestration.ts:432-436`); (b) the loop's own skip reasons, which the
225-
archived design already surfaces as `t3x.loop.skipped` breadcrumbs; (c) **model-authored
226+
archived design already surfaces as `coil.loop.skipped` breadcrumbs; (c) **model-authored
226227
questions**, which need a channel that does not exist yet.
227228
- (c) is the interesting one and the risky one. The archived design deliberately **rejected**
228229
an agent-authored JSON contract (BATON) because "it outsources the hardest judgement to
@@ -270,6 +271,13 @@ different prompt and trigger**, or a genuinely different thing. First read: same
270271
different *stop condition* and different *source of work* — a maintainer loop is
271272
goal-sourced from an issue queue rather than from a single thread's unfinished work.
272273

274+
### F5. Deliverable shape
275+
276+
- An explanation for the **backend**.
277+
- A **visual** for the frontend — HTML prototypes, embedded in the report.
278+
- **All angles considered**, with explicit reasoning for why the rejected ones fail.
279+
- If time allows: **the full backend test-case list**.
280+
273281
---
274282

275283
## G. The questionnaire already half-exists — and its other half is the whole problem
@@ -359,10 +367,3 @@ useful, rather than to silence.
359367

360368
That is the test the prototypes must visibly pass: **show the empty state**, and make sure
361369
it is still worth opening.
362-
363-
### F5. Deliverable shape
364-
365-
- An explanation for the **backend**.
366-
- A **visual** for the frontend — HTML prototypes, embedded in the report.
367-
- **All angles considered**, with explicit reasoning for why the rejected ones fail.
368-
- If time allows: **the full backend test-case list**.

‎docs/coil/loops-v2/PLAN.md‎

Lines changed: 41 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
# Loops — implementation plan
22

3-
**Status:** ready for independent review. Nothing built, nothing merged.
4-
**Branch:** `t3code/loop-observation-thread-prototypes`
5-
**Baseline:** fork `main` @ `f6355f06f`, on upstream merge-base `a4cc1367b` (2026-08-17), **zero
6-
commits behind upstream at verification (2026-08-17)**. Every claim below was verified against that tree — see
3+
**Status:** proposed — nothing built.
4+
**Baseline:** upstream merge-base `a4cc1367b` (2026-08-17), with the fork **zero commits behind
5+
upstream at verification (2026-08-17)**. The merge-base is the anchor rather than a fork `main` SHA,
6+
because every sync rewrites `main`. Every claim below was verified against that tree — see
77
[UPSTREAM-DELTA.md](UPSTREAM-DELTA.md) §7.
88

99
| Companion doc | What it holds |
@@ -90,13 +90,13 @@ Each with the reasoning, so a reviewer can attack the reasoning rather than gues
9090
| D1 | **Durable T3-native reactor, backstopping Claude's scheduler** | Claude's scheduler works ≤30min but is in-process, clamped to 1h, and Claude-only `[V]` | High — evidence in BACKEND §1.1 |
9191
| D2 | **Trigger on `updatedAt` staleness + recorded `session_crons`, never `session.status`** | A background subagent's message auto-opens a synthetic turn that pins `status = running` and nothing closes it — gating on it deadlocks the exact threads this is for `[V]` | High |
9292
| D3 | **A loop is a pinned thread** (Direction A) | Upstream shipped pinning 2026-08-04; `pinnedAt` overrides the settled/snoozed lifecycle; costs zero sidebar edits `[V]` | High |
93-
| D4 | **The Loops workspace (Direction C) is phase 2, not phase 1** | User agreed. Lives in fork-owned routes, so cost is low, but it is only worth it once several loops exist | High — user-confirmed |
93+
| D4 | **The Loops workspace (Direction C) is a later phase (Phase 6), not phase 1** | User agreed. Lives in fork-owned routes, so cost is low, but it is only worth it once several loops exist | High — user-confirmed |
9494
| D5 | **Never Direction B** (a bespoke Loops section in the sidebar) | Would open a row in `Sidebar.tsx` (3911 lines, 7 commits in 3 days `[V]`) and `Sidebar.logic.ts`; also has no mobile equivalent | High |
9595
| D6 | **Two question channels: blocking (native) + deferred (`raise_blocker`)** | `AskUserQuestion` blocks on a `Deferred` `[V]`; a loop that waits loses the night, and one that nudges past a pending decision is worse | High |
9696
| D7 | **Console reads three sources, two needing no model cooperation** | Degradation test: a model that never calls `raise_blocker` must still produce a useful console | High |
97-
| D8 | **Budget is check-ins + wall-clock, not dollars** | `total_cost_usd` is unread anywhere in the repo and is documented as session-accumulated, so per-turn summing would inflate quadratically `[A - not measured]` | Medium — revisit if metered |
97+
| D8 | **Budget is check-ins + wall-clock, not dollars** | The adapter stamps `total_cost_usd` onto `turn.completed.totalCostUsd` and nothing downstream aggregates it; its per-turn vs session-accumulated semantics are unmeasured `[A]`, so summing per turn could inflate quadratically | Medium — revisit if metered |
9898
| D9 | **Mandatory budget, no unlimited option; route returns 400 rather than clamping** | A silent clamp hides a mistake in a feature that spends money unattended | Medium |
99-
| D10 | **Own settings section** (`/settings/loops`) | Now priced at 2 small additive seam rows, with a 3-day-old upstream precedent `[V]` | High |
99+
| D10 | **Own settings section** (`/settings/loops`) | Now priced at 2 small additive seam rows, with an upstream precedent that landed the same day (2026-08-17) `[V]` | High |
100100
| D11 | **Fork-owned durable JSON, not a DB migration** | The migration registry is upstream-owned; `autoResume` set this precedent and it has held | High |
101101
| D12 | **Zero `packages/contracts` edits** | Activity `kind` is an open string with an `Unknown` payload, so breadcrumbs are free; and upstream has pre-announced this file as its own automations landing zone | High |
102102

@@ -111,7 +111,8 @@ Each with the reasoning, so a reviewer can attack the reasoning rather than gues
111111
- The console: blocking items, deferred blockers, loop state, iteration ledger.
112112
- `raise_blocker` / `loop_status` / `loop_done` as a fork MCP toolkit.
113113
- Settings: master toggle, defaults, armed roster.
114-
- Web + desktop (same app). Mobile read-only surfacing.
114+
- Web + desktop (same app). Mobile read-only surfacing — **deferred until after Phase 3** and
115+
priced when it is built; this plan takes no mobile seam row.
115116

116117
### Out (explicitly, with reasons in report §12)
117118

@@ -128,21 +129,31 @@ Each with the reasoning, so a reviewer can attack the reasoning rather than gues
128129
### Divergences from #42 (deliberate, and open to challenge)
129130

130131
- **#42 Phase 1d's `CLAUDE_CODE_DISABLE_CRON` per-thread toggle (default off) is dropped.** It was
131-
specified when the scheduler looked untrustworthy; the correction in §1 inverted that, and the
132+
specified when the scheduler looked untrustworthy; the correction in BACKEND §1.1 inverted that, and the
132133
user now relies on self-paced wakes — a default-off kill switch would disable the very mechanism
133134
Phase 1 exists to observe. #42's "50 recurring jobs with no human in the path" concern is real,
134135
but it is a full-access policy question, not a loops question. If review disagrees, the switch is
135136
one env line in the same `ClaudeAdapter` row this plan already takes.
136-
- **#42's Experiments B and D were not run.** B (does a cron-fired turn render in the transcript as
137-
if the human typed it?) needs a real `session_crons` fire to answer — it moves into Phase 1's
138-
observation checklist rather than blocking the design. D (gate stability under the `sdk-ts` entrypoint) is
139-
absorbed by designing for the `gate_off` degraded state (BACKEND §4; TESTS case 11h): nothing here
140-
depends on the gates staying on.
137+
- **None of #42's Phase 0 experiments A–D were run.** A (does a cron-fired turn reach T3 at all?)
138+
and C (does the reaper win the race?) are cheap, and they fold into Phase 1's observation
139+
checklist, which is exactly what Phase 1 is for — the record it writes answers both by watching a
140+
real session rather than by staging one. B (does a cron-fired turn render in the transcript as if
141+
the human typed it?) also needs a real `session_crons` fire, so it rides along with A and C. D
142+
(gate stability under the `sdk-ts` entrypoint) is absorbed by designing for the `gate_off`
143+
degraded state (BACKEND §4; TESTS case 11h): nothing here depends on the gates staying on. The
144+
design does not claim these results; it claims Phase 1 is the cheapest way to get them.
141145
- **#42 Phase 2's `wake_me` tool is not carried over.** The agent already has native long-horizon
142146
scheduling (`CronCreate` / `ScheduleWakeup`); a fork mirror would be a parallel path to an
143147
upstream capability. `raise_blocker` covers the one thing the native tools cannot do — hand a
144148
durable, non-blocking question to a human — and a wake armed-then-lost is exactly what the
145149
staleness trigger backstops.
150+
- **The sentinel file stays the primary "done" contract**, inverting #42's reasoning for replacing
151+
it with a `loop_stop` tool. #42's objection was cwd ambiguity; statting the worktree first
152+
mitigates that, and a file works from a plain terminal with no MCP at all, which a tool cannot.
153+
`loop_done` exists beside it, not instead of it.
154+
- **#42's `thread_note` tool is dropped.** Timeline breadcrumbs are reactor-authored
155+
(`thread.activity.append` with `coil.loop.*` kinds), so the model does not need a tool to write
156+
them and the console does not depend on the model to have called one.
146157

147158
---
148159

@@ -201,6 +212,8 @@ one focused agent-assisted session per unit.
201212
**Files:** `coil/http/auth.ts` (new), `coil/autoResume/http.ts`, `coil/webPush/http.ts`,
202213
`coil/autoResume/guards.ts` — all fork-owned.
203214
**Seam cost:** 0. **Acceptance:** existing suites green, zero behaviour change.
215+
**Ships as its own PR** — this is unrelated debt the feature merely surfaced, and one concern per PR.
216+
Phase 1 depends on nothing in it.
204217
**Size:** S.
205218

206219
---
@@ -213,8 +226,10 @@ This phase is deliberately inert, and it is the most important one to get right
213226
reads its state.
214227

215228
- `coil/loop/state.ts` — the durable store (`coil-loop.json`). Every field with a decoding default.
216-
- `coil/loop/crons.ts` — the `Stop` / `SubagentStop` hook callbacks: read `input.session_crons`,
217-
normalise to `{ id, kind, nextFireAtMs, prompt }`, persist per thread.
229+
- `coil/loop/crons.ts` — the `Stop` / `SubagentStop` hook callbacks: read `input.session_crons`
230+
(`{ id, schedule, recurring, prompt }` — a cron expression, not a timestamp), compute
231+
`nextFireAtMs` fork-side from `schedule` (one-shot = single fire time encoded in the fields;
232+
server-local tz) `[A — the parse is ours]`, persist per thread.
218233
- `coil/loop/config.ts` — env-overridable defaults.
219234
- **The one upstream edit:** a single spread into `ClaudeAdapter`'s existing `queryOptions` object,
220235
beside the `mcpServers` spread:
@@ -230,7 +245,7 @@ reads its state.
230245
- Arming is impossible (no arm route yet); nothing dispatches.
231246
- On a Claude thread that self-paces, `GET` shows the pending wake with a plausible `nextFireAtMs`.
232247
- On a non-Claude thread, the record exists and `crons` is empty — no errors.
233-
- A hook callback that throws does not break the turn `[V-by-test]`.
248+
- A hook callback that throws does not break the turn `[A — to be proven by the §4b hook-failure case]`.
234249
- Killing and restarting the server preserves the record.
235250

236251
**Why first:** it is the only phase that can be validated purely by observation, and it de-risks the
@@ -267,8 +282,10 @@ one upstream edit before anything depends on it. If the hook surface turns out n
267282

268283
**Goal:** the page you open at 9am.
269284

270-
- `apps/web/src/coil/ThreadCoilOverlay.tsx` — the fork-owned aggregator. **Rewrite the existing
271-
overlay row in place** so the seam delta is zero `[V — the row is +10/−6, risk 0]`.
285+
- `apps/web/src/coil/ThreadCoilOverlay.tsx` (new) — a fork-owned aggregator that mounts
286+
`AutoResumeOverlay` and the console; then **rewrite the existing overlay row in place** to mount
287+
it, so the seam delta is zero `[V — the row is +10/−6, churn 4; delta 0 (row already carries risk
288+
64)]`.
272289
- Console UI: blocking / deferred / loop-state sections, iteration ledger, empty state.
273290
- `POST /api/coil/loop/answer`, routing native pending-inputs to the existing resolve path and
274291
blockers to the fork store.
@@ -290,7 +307,7 @@ one upstream edit before anything depends on it. If the hook surface turns out n
290307
- `apps/web/src/routes/settings.loops.tsx` (new, fork-owned) + a fork-owned panel component.
291308
- `settingsSearch.ts`: `SettingsPath` union + label + 2–3 search items.
292309
- `SettingsSidebarNav.tsx`: icon import + record entry.
293-
- **Not** `SettingsPanels.tsx` (churn 32, risk 1856), **not** `contracts/settings.ts` (persisted).
310+
- **Not** `SettingsPanels.tsx` (churn 36, risk 2088), **not** `contracts/settings.ts` (churn 26, persisted).
294311

295312
**Seam cost:** **2 new rows**, ~+6 lines total, both additive.
296313
**Sequencing:** no longer a constraint. This originally had to wait for the sync carrying upstream
@@ -386,7 +403,7 @@ The four to write first:
386403

387404
| Risk | Likelihood | Impact | Mitigation |
388405
|---|---|---|---|
389-
| `session_crons` is not delivered as the SDK types document | Medium `[A]` | Phase 1 invalid | **Phase 1 is designed to find this out cheaply.** Fallback is pure staleness with a longer threshold — worse, but zero upstream cost |
406+
| `session_crons` arrives as a cron *expression*, not a fire time, so the `nextFireAtMs` parse is ours and can be wrong | Medium `[A]` | Deference misfires | **Phase 1 is designed to find this out cheaply** — it logs the parse beside the raw `schedule`. Fallback is pure staleness with a longer threshold — worse, but zero upstream cost |
390407
| Upstream ships its own automations feature | Medium | Duplicated work | Zero contracts edits means the fork becomes a *caller*, not a migration. Re-check each sync |
391408
| The `ClaudeAdapter` row conflicts on a sync | Low-Medium | Recurring cost | One additive line beside an existing spread; fails to a type error, not silent drift |
392409
| A loop pushes past a human decision | Low | Trust | Three separate guards (approvals, pending input, plan-ready), each non-consuming |
@@ -402,8 +419,9 @@ The four to write first:
402419
The four places an outside opinion is most valuable.
403420

404421
**Q1 — Is the deference rule right, or too clever?**
405-
T3 stands down when the agent has a wake pending. The alternative is that T3 always paces on its own
406-
clock and simply tolerates occasional double-firing. Deference is more correct and more complex, and
422+
T3 stands down for as long as a recorded wake is still pending — any legal delay, not merely one
423+
inside the threshold window — and covers it only once it is overdue by `graceMs`. The alternative is
424+
that T3 always paces on its own clock and simply tolerates occasional double-firing. Deference is more correct and more complex, and
407425
it makes the feature's behaviour depend on a hook whose delivery is `[A]`. *Is the complexity worth
408426
it, or should v1 pace unconditionally with a long threshold?*
409427

0 commit comments

Comments
 (0)