[design] The platform owns the conversation — an engine's own memory is an optimisation, not the source of truth

[serge-ivo]

The owner's words: "why do users have to know about sessions? why can't it just be seamless? when a user starts engaging with the agent it resurrects last everything as if the session never died" — and then: "can't it be fully persisted and work via DB completely, instead of relying on ephemeral sessions?"

The answer to the second question is where the first one is actually decided, so this issue is about ownership of conversation state. The user-facing consequences are filed separately (#695, #696, #697, #698) and are all cheap; this is the one with design in it.

The durable half already exists

coding_timeline is append-only in D1, 100 000 characters per entry (lib/coding-timeline.ts:59 — args.content.slice(0, 100_000)), and interleaves chat_user · chat_assistant · terminal · command · brain · outcome · system (:14-21). It is readable per session and per repo, the repo-scoped read tagging each row with its sessionId so the UI can draw boundaries (:31-35).

It works. The console reloads history from it, and #257 already uses the repo-scoped read so a finished run does not leave an empty screen.

It is read only ever FOR THE HUMAN. Nothing feeds it back INTO an engine.

The half that is not ours

Continuity today is a pointer, not a record. coding/headless.ts:266:

this.claudeSessionId = readState(config.statePath, config.id) ?? (config.resumeFrom ? readState(config.statePath, config.resumeFrom) : null);

readState (:938) reads a JSON file on the runner's disk (statePath: defaultStatePath(this.reposBaseDir), coding/runtime.ts:238) mapping our coding_sessions.id → Claude Code's own session id. The conversation itself lives inside ~/.claude, owned by another program, on one machine.

Four consequences follow, all verified in code:

1. Machine-bound. The state file is local to the runner that wrote it. See [bug] A coding session relocated to another machine silently starts with an empty conversation — the resume pointer is a file on the machine it left #694 for the case where this silently loses a live conversation.
2. Not ours to keep. Clearing ~/.claude, or Claude Code changing its store format, ends continuity and no D1 row can help.
3. Opaque. We cannot read, compact, or measure it. This is why RESUME_WINDOW_MS (lib/coding-session-continuity.ts:47) is four days: the header argues it from a long weekend, which is honest reasoning about a quantity we cannot observe.
4. Claude-only. headless.ts:260 returns resumedConversation false "for a raw (non-Claude) engine under every circumstance". Codex and Grok have no conversation at all — for them seamlessness does not degrade, it has never existed.

Proposal: invert the dependency

The platform owns the conversation. An engine's own memory becomes an optimisation, not the source of truth. On wake, seed the engine from coding_timeline instead of relying on --resume.

Slices, ordered so the first cannot regress anything:

1. Seed-from-timeline as the FALLBACK, used exactly where resolveSessionContinuity returns fresh today for a reason other than forceFresh: past the window, a different engine, a missing last_activity_at. Every one of those starts stone cold now, so any brief is an improvement and there is nothing to regress. The reason strings already distinguish these cases.
2. Make it primary for raw engines. They gain multi-turn memory they have never had. Again nothing to regress — see headless.ts:256-260.
3. Only once proven, decide whether Claude keeps preferring --resume (cheaper, higher fidelity when present) or moves over too.

Slice 1 also makes RESUME_WINDOW_MS a policy dial rather than a constraint, which is what the owner actually asked for ("night time or for a few days"). Filing a separate "make the window configurable" issue would be treating the symptom — a configurable window still falls off a cliff, it just falls later.

What this cannot buy — state plainly, do not let it surface later

• Reconstruction, not restoration. Claude Code's context is not a message list; it holds tool state, file caches and its own compaction. Seeding gives continuity of understanding, not a byte-identical context. Often better — a curated brief beats a bloated transcript — but the claim must not be "as if it never died".
• A process is not data. You cannot persist a running child process, only reconstitute one fast enough that nobody notices. Measured: a wake with --resume answered a memory question in 8 seconds (2026-08-17, instance bd43f4de).
• The machine must be on. Unmovable, and it should be reported as "your Mac mini is offline", never in session vocabulary.
• Token cost is unchanged. Re-sending context every turn is an LLM property, not a storage choice. Compaction matters either way — the platform already summarises chat after 20 messages and the same trick applies here.

Verified end-to-end, 2026-08-17

Instance bd43f4de (Chess coder 2), repo apps/chess-academy. Previous session csess_21b8d1b9 reaped at 6h idle. POST /v1/instances/:id/coding/sessions returned:

"resumed": true,
"continuity": { "mode": "resume", "resumeFrom": "csess_21b8d1b9-…",
                "reason": "the previous conversation on this repo was last touched 11 hours ago" }

The engine then recalled its previous closing question verbatim against coding_timeline seq 9227, and the correct 11-of-12 figure, with no tool use. So the mechanism works today — on one machine, for one engine, within four days, reachable from one surface. This issue is about removing those four qualifiers.

[serge-ivo]

Slices filed under this

The user-facing consequences, each independently shippable. Only the first is blocked on the design here; the rest are cheap and can land immediately.

Issue	What	Depends on this?
#694	A relocated session silently starts cold — the resume pointer is a file on the machine it left	Yes — this is the motivating case. The narrow fix is a patch; #693 removes the class.
#695	The reap message teaches "session" and instructs a false remedy	No
#696	No MCP tool can open a resuming session — the only opener hardcodes fresh:true	No
#697	continuity.reason is computed, phrased for a human, and displayed nowhere	No
#698	The reap releases a process on the user's machine and notifies nobody	No

Ship #695 and #697 together. #695 removes the sentence that misinforms; #697 supplies the one that belongs in its place. #695 alone just makes the platform quieter rather than clearer.

#696 is the one that unblocks a real workflow today — continuity is built, tested and shipped, and reachable from exactly one of its two entry points.

Not filed, deliberately

• Pane rehydration. [bug] Terminal history is session-scoped, and every finished run ends the session — so history looks lost while sitting in D1 #257 already built it: RepoHistory renders the repo-scoped timeline whenever there is no live session (agents/coder/web/src/CodingTab.tsx:161, 1197), and instance bd43f4de meets its singleRepo && repos.length === 1 guard. The empty screen the owner reported was the live terminal pane plus a history whose last line was the [bug] The idle-reap message teaches the user what a session is, then tells them to do something the platform already does by itself #695 string — not a missing history.
• "Make RESUME_WINDOW_MS configurable." Folded into [design] The platform owns the conversation — an engine's own memory is an optimisation, not the source of truth #693. A configurable window still falls off a cliff; it just falls later.

[serge-ivo]

Slice 1 shipped — e82da9b0 (+ a8c1927f, a fix-forward). Leaving open for slices 2 and 3.

The fallback only, under ADR 0005. forceFresh is untouched, and --resume still wins wherever it lands — this is what happens instead of nothing, not a replacement for the engine's own memory.

The rule, made checkable

SessionContinuity gains a required seed: SeedSource | null. Every branch of resolveSessionContinuity declares one; exactly one may decline, and it is the one the ADR names: forceFresh. resolveSessionContinuity's fresh() helper takes the source as a defaulted parameter, so a ninth branch added later gets the guarantee by writing nothing at all, and declining it costs an explicit null next to the reason it is declining.

Where it is attached, and why not at the two open paths

In startSessionOnRunner, the cloud's only caller of /coding/start. Hanging it off the continuity decision would have covered the fresh opens and missed the case this record was written about: a re-attach that relocates a session decided nothing (#694, below). That path has no continuity object at all. One funnel, one guarantee.

opts.cleanSlate is the single suppressor and it is spelled as a request, not as the absence of a seed, so a caller has to state it.

Who decides — and why the brief also rides on a resume

The cloud always composes and sends the brief; the runner decides whether to spend it, because only the machine knows whether the resume key was actually there. That closes a case the code already knew about: sessionOpenedNotice has had a whole branch for "asked to resume, machine did not confirm" since #408, and its own wording for that outcome is "It started a FRESH conversation". A cold engine is a cold engine however it got there. Withholding the brief on mode: "resume" would have left the guarantee broken on the exact path that produced the ADR.

This is not slice 3. HeadlessSession sets pendingSeed only when resumedConversation is false, so a landed --resume drops the brief unread. Pinned by a test that watches a warm session receive nothing.

Reconstruction, not restoration — enforced as text

The preamble the engine reads says the previous conversation is gone before it says anything else, names what is missing (file contents, tool state, anything worked out but never said), warns that the working tree may have moved on, and frames itself as background for the instruction that follows rather than as the instruction. Asserted, including the negatives: no restored, no as if it never.

The three surfaces say the same thing in their own registers, all "was given a brief… reconstructed", never "remembers":

• chat (sessionOpenedNotice) — a fourth outcome, placed ahead of the two loss-first branches;
• console (open-notice.ts) — keeps the warning tint. A brief softens the surprise; it does not remove it, and reading as reassurance would be the prohibited claim rendered as a colour;
• MCP (openConversationText) — added because [bug] No MCP tool can open a resuming session — the only opener hardcodes fresh:true, so #408's continuity is console-only #696 already established that the console and MCP must not tell one user two different stories about one open. It had no test at all; it has one now.

Bounded

60 rows, 12 000 characters, terminal snapshots kept by their tail and instructions by their head, budget spent newest-backwards and stopped rather than skipped — a budget that keeps looking for a smaller entry further back produces a history with a hole in the middle and no text saying so.

Enforcement (the ADR's own clauses)

1. Every branch declares a seed source. coding-session-continuity.test.ts now enumerates all eight decisions once, in a shared list, and asserts across the whole denominator. Watched failing.
2. Relocation cannot present a cold engine. coding-session-open.test.ts drives reassignSessionNode and asserts the launch body carries a non-empty brief. Watched failing with the wiring removed (4 tests red).
3. Retention unchanged — coding_timeline is still permanent.

Also pinned: no brief on cleanSlate (and no D1 read at all), seeded:false against a runner that does not acknowledge the field, and — after it actually happened — that a malformed row cannot fail a session open. The first version threw a TypeError inside the composer, past the read's own .catch, and took down eight unrelated session-open tests. A missing memory must never become a missing session; that is now a guarantee about the whole function rather than about one await inside it.

Out of scope, deliberately, and not folded in

• Slice 2 — multi-turn memory for raw engines. Raw engines do get the first-turn brief here, because "no conversation to continue" is one of the fresh branches slice 1 covers. What they still lack is memory between turns, since each turn is its own process. That is the real slice 2 and it is not done.
• Slice 3 — making seeding primary for Claude. Not touched.
• forceFresh — not touched.

Verified

Every gate enumerated from ci.yml: nine guard scripts, biome, docs:drift, the SDK build, four source typechecks, three TEST typechecks, the console vite build, pnpm test (10,226) and the full Playwright matrix (452, chromium + webkit — including the new briefed-banner specs at 320px and 390px in WebKit). CI green on a8c1927f; Deploy API Worker, Host, MCP all success; @proagentstore/cli@0.4.57 published.

e82da9b0 went red in CI and I fixed it forward in a8c1927f. Three pre-existing fixtures built a SessionContinuity without the new required field. pnpm typecheck cannot see them — workers/api/tsconfig.json excludes *.test.ts and vitest transpiles without typechecking — so 10,226 tests passed green over code that does not compile. Typecheck worker + SDK TESTS (#599) exists for precisely that class and was missing from the list I checked before pushing. Every ci.yml gate was enumerated from the file and run before the second push.

NOT verified — read this before treating slice 1 as proven

Nobody has watched a seeded engine answer a question about work it never saw. That needs a live run on a real machine, which I must not drive. The end-to-end claim rests on tests plus the runner's own echo of the text it received; it is not an observation of a model using the brief well, and a green suite is not evidence about behaviour nobody watched.

Specifically unobserved: whether 12 000 characters is the right budget against a real repo's history; whether an engine given a brief re-reads files it did not need to; and whether the honesty framing survives contact with a model that would rather sound confident. The measurement worth taking is the one #693 already took for --resume: reap a session, re-open it, ask it what you were doing, and compare against coding_timeline.

The runner half needs @proagentstore/cli@0.4.57 installed (npm i -g @proagentstore/cli). Until then pags up drops the seed field and behaves exactly as it does today — which is why the cloud reports what the machine confirmed rather than its own intent, and why seeded reads false on an older runner instead of promising a briefing that never landed.