[design] A coding session is a cache, not a thing to manage — stop asking the user to start one, and decide resume-vs-fresh

[serge-ivo]

The question

"Why do I need to press that button? Why can't it just be on forever? What even IS a session?"

Three fair questions, and the answers split cleanly into one thing with a real justification and two
without. This is the redesign; #407 is the one-call fix that should land first regardless.

What a session is, and the fact that decides the design

A session is a coding_sessions row plus a live child process on the owner's machine — the
claude CLI, spawned by the runner (HeadlessSession). Not tmux: a tmux server owns its sessions
and nothing reaps them, which is why they last forever and this does not.

The decisive fact: the engine's conversation is not in the process. Claude Code persists it to
~/.claude, and the runner re-spawns with --resume <session_id> (coding/headless.ts:45,331,363).
So a reaped session loses a process, not a memory. Re-opening restores the conversation.

That single property is what makes the current model wrong. If ending a session destroyed the work,
asking the user to manage it deliberately would be defensible. It doesn't — so the session is a
cache, and the user is being asked to manage a cache.

Keep exactly one thing

The idle reap. coding-session-sweeper.ts:63, 6 hours untouched. Its header states the cost it
prevents and the cost is real: a claude --dangerously-skip-permissions child resident forever, one
per repo, on someone's laptop. Six idle hours is generous and interaction of any kind resets it.
Not proposing to change it.

Drop two

1. The user starting sessions. ensureActiveSession already reuses / re-attaches / opens /
explains-why-not, and has exactly one caller — the Loop (#407). Every path that needs a session
should ensure one. A "Start session" button in the primary flow is the platform asking the user to
do something it can do better.

2. The user knowing sessions exist. The mental model should be repos, which are what the
owner actually chose and configured. A session becomes an implementation detail, visible only in the
🩺 diagnostics panel where it already lives. Reaping becomes invisible — the next request re-opens
and resumes.

The real cost, and the decision this ticket needs

Making resume automatic and unbounded reintroduces, in a different place, the thing the reap was
built to prevent. Today the reap is the only event that ever resets an engine's context; if every
path silently resumes, a repo's engine conversation grows for weeks, and every turn re-sends it. The
symptom moves from "a process on your laptop" to "a slow, expensive first message", which is
harder to see and paid per token.

The coding_session_fresh MCP tool exists, so the distinction is already understood — it just is not
policy.

Decide: when does an auto-opened session resume, and when does it start fresh?
Candidates, and I would take the second:

• always resume — simplest, unbounded growth;
• resume within N days of last activity, otherwise fresh — bounded, and the boundary is the same
  idleness the reaper already measures;
• resume only when the reap was the reason it ended (a runner restart / laptop sleep is a different
  event from six hours of nobody caring).

Whatever is chosen must be stated to the user on the turn it happens — "resumed where we left
off" vs "started fresh; the previous conversation was N days old" is exactly the kind of fact that,
left unsaid, produces a bug report about an agent that "forgot everything".

Do

• [bug] Chat cannot open a coding session — only the Loop can, so "what's the terminal doing?" fails while "go fix it" silently starts one #407 first — chat ensures a session like the Loop does. Independent of everything below.
• Make every session-needing path ensure one; delete the notion of a user-started session
  from the primary flow.
• Adopt a resume-vs-fresh policy (above) and surface which one happened.
• Show the opening state. A spawn plus --resume takes seconds, not milliseconds. Silence
  here reads as a hang; the Terminal tab's [bug] The Terminal tab learns the runner is gone only by failing — and blanks that error every 4s, so a phone shows an empty pane and a flicker #378 treatment is the precedent.
• Demote the session list to diagnostics; the repo row carries the status a user needs.
• Never auto-open when the runner is offline — answer with the offline diagnosis instead.

Acceptance

• A user can go from "subscribed, repo added" to "asking about the terminal" without ever
  learning what a session is.
• Six idle hours still reaps; the next question still works.
• The reply says whether it resumed or started fresh, and why.
• With the runner offline, nothing is created and the answer names the real problem.

Files: lib/coding-session-open.ts:102, lib/coding-session-sweeper.ts:63,
lib/storage-tools.ts:637,682, lib/loop-drivers.ts:181,
packages/browser-runner/src/coding/headless.ts:331-400. Supersedes nothing; extends #407.

[serge-ivo]

Delivered in two commits, both on main and deployed:

• a7f2ffd feat(coding): a re-opened session continues the repo's conversation for four days, and says which one it got
• c8d132c refactor(console): the Coding tab opens a REPO, and stops asking the user to manage a session

The decisive fact in this issue is wrong, and it inverts the decision

"the engine's conversation is not in the process … a reaped session loses a process, not a memory. Re-opening restores the conversation."

Half right, and the wrong half is the half the cost analysis rests on. The runner's resume store is keyed by our coding_sessions.id — readState(config.statePath, config.id) at coding/headless.ts:224, and --resume is appended only when that lookup returns something (:815). A reap ENDS the row; the next open createSessions a new id; readState(statePath, <new id>) is null. So the real prior behaviour was:

• runner restart, same session row → resumes (this is all headless.ts:45 ever described)
• reap, then re-open → always fresh, silently

coding-session-sweeper.ts:60 already said so in its own words: "reaping early costs a live CLI context that cannot be recovered, because the next session gets a new id and starts cold."

So the unbounded-context cost this issue worries about did not exist on the auto-open path, and "always resume" was never the status quo. The live defect was the opposite one this issue's own last paragraph predicts: the agent "forgot everything" after a reap and nothing said so. The policy below is therefore not a restriction on an over-generous default — it adds resume as a capability and states its boundary in the same breath. Pinned by a test ("a NEW session id has nothing to resume").

The decision: four days

resolveSessionContinuity in lib/coding-session-continuity.ts — pure, tested, with the reasoning next to it. Two clocks measuring different things, and it matters they are not the same number: IDLE_SESSION_MS (6h, unchanged) asks "is anyone looking right now?" and its cost is a resident process; RESUME_WINDOW_MS (4 days) asks "is this still the same piece of work?" and its cost is tokens, re-sent every turn forever. Four days clears a long weekend (Friday evening → Tuesday after a public holiday ≈ 3.6 days) and is comfortably short of "I came back to this after a week", by which time the old transcript is a liability. A test pins RESUME_WINDOW_MS > IDLE_SESSION_MS.

Fresh is returned — each with a reason a reply can use verbatim — for: an explicit Fresh start, a non-Claude engine (no conversation to resume), no previous session, an engine switch, a session whose engine never launched, an unmeasurable age, or older than the window.

The near-miss

The policy would have silently deleted "Fresh start". The console's Fresh button and MCP's coding_session_fresh both end a session and immediately open another — so the row they are escaping is the most resumable thing on the repo, and "clean state, my CLI is wedged" would have handed the wedged conversation straight back. forceFresh is now the first branch of the rule, POST /coding/sessions takes fresh: true, and both callers send it, each with a test. This issue cites coding_session_fresh as evidence the distinction was already understood; that tool is exactly why the distinction had to stay expressible after it became policy.

Honesty about what actually happened — three outcomes, not two

The most important correctness detail here. mode:"resume" is what the cloud asked for; resumed is what the machine confirmed (/coding/start now answers it). So:

1. asked, confirmed → "It picked up this repo's previous conversation"
2. decided fresh → "It started a fresh conversation — <reason>"
3. asked, not confirmed → also reported as fresh

Case 3 is not hypothetical: a pags up published before this drops the unknown resumeFrom field and starts clean, and it could not have resumed a new session id anyway (its store has no entry for an id it has never seen). A cloud that reported its own intent would have told most of the fleet the opposite of what happened — a confident wrong answer to "did you remember what we were doing?", which is worse than the silence this issue set out to fix. Tested from both sides.

Per-call-site audit (the "every path ensures one" box)

coding-brains.ts delegateToTarget now ensures via ensureSessionForChat — reusing #407's connectivity gate, not copying it. The other five call sites of getActiveSessionForRepo are reporting and deliberately must NOT ensure: the overseer context builder, next-issue, the repo-move guard, repo-state.ts, and the create route. repo-state.ts is the one that matters — an ensure there would have spawned engines across a supervisor's entire tower from a status poll.

Console

The active ? openTerminal : startSession fork is gone from four call sites into one openRepoSession, which also carries the opening state (a spawn plus --resume takes seconds; silence reads as a hang — #378's precedent) and an inline error where an alert used to swallow the server's runner diagnosis. There is no separate session list in agents/coder/web to demote — the 🩺 panel already owned it; only the "N active sessions" line needed removing.

Verification

pnpm typecheck (11), pnpm vitest run (401 files, 6556 tests), biome, design tokens, agents allowlist, QA config, file-size ratchet, migration hygiene, test isolation, docs:drift — all re-run after rebasing onto efe285a, then pushed. CI, Deploy API / Host / MCP, and Publish to npm all green on c8d132c. No migration needed.

Live: api.proagentstore.online/health ok; the new "What a session remembers" section is serving at https://proagentstore.online/docs/browser-runtime/.

One local e2e spec (browser runtime docs …) fails on this machine. I ran it at origin/main with none of these changes and it fails identically, and CI's own e2e is green — environmental, not this change.

What is NOT verified, and what you must do

The resume path is inert until a machine upgrades. It needs the runner half, which shipped in @proagentstore/cli@0.4.44 (published). Mac is on 0.4.40 and Mac-mini on 0.4.22, so today both would take outcome 3 above — correctly reported as fresh, but never actually resuming.

npm i -g @proagentstore/cli on both, then the four acceptance checks, none of which I can run without a runner:

1. Add a repo, ask the agent about the terminal without pressing anything — it opens a session and answers.
2. Leave it 6h, ask again — it re-opens and the reply says it picked up the previous conversation.
3. Force a fresh start; confirm the reply says fresh and why, and that the wedged conversation is gone.
4. Stop pags up, ask again — the answer names the runner, and coding_sessions gains no row.

Also worth knowing, and now documented: a conversation only exists on the machine that held it, so opening the same repo on the other laptop legitimately starts clean.