Name local agent sessions after the issue branch and resume them #2

Merged

SebastienDenooz merged 1 commit from agent/issue-1-add-a-name-on-client-and-resume-from-it into main

2026-10-26 09:44:17 +00:00

Alfred commented

2026-10-26 00:47:26 +00:00

Owner

Summary

Updates docs/specification.md so a local coding-agent CLI keeps one continuous memory per issue. The session is named after the issue's branch, and each later run of the same issue tries to resume it.

Changes by section

§3.4: new per-mailbox, per-adapter session state directory, which outlives runs.
§7.2 / §7.3: the branch name is fixed at the first run, so it stays stable as a session name. Session state is removed on done or cancel, and is not removed by the run's finally block.
§11.7: reclaiming a lease keeps the session state. A half-written state falls back to a fresh session.
§13.1: new steps to resolve the session before the run and record it after.
§16.2 / §16.3:
- SessionRef added to LlmRequest.
- sessionId, resumed and resumeFallback added to LlmResult.
- resumableSessions and sessionStatePath capabilities.
§16.5: resume options for each CLI, a "Named sessions and resume" subsection, and a new trap about detecting resume failures.
§16.6: detection checks whether the installed version supports resume.
§17.2 / §17.5 / §17.6: mounts only the sessions subdirectory and isolates it per mailbox. Documents the accepted risk and the orphan removal.
§21.2 / §21.3: cleanup on 404, done, cancel and by the orphan sweep. State is kept while blocked and on lease reclaim.
§22.3: new session columns on llm_sessions, a resumable_sessions column on agent_installations, and a note on mailboxes.branch_name.
§23.3: AGENT_SESSION_RESUME, default true, at organization and project scope.
§24.3 / §24.5 / §25.2: new threat row, retention rule and audit fields.
§28.1 / §28.2: new rows for naming, resume, fallback, setting off, isolation, cleanup and name stability, plus support in the test doubles.
§29: non-goal 3 reworded.
§30: Laravel mapping, cleanup job, and the rule that the native id comes from the database, never from the mounted directory.

Validation

The repository holds only the specification. A script confirmed that every Markdown table has a consistent column count, and the cross-references were reviewed by reading. The edited Mermaid diagram (§13.1) was not rendered.

🤖 Generated with Claude Code

Closes #1

## Summary Updates `docs/specification.md` so a local coding-agent CLI keeps one continuous memory per issue. The session is named after the issue's branch, and each later run of the same issue tries to resume it. ### Changes by section - **§3.4:** new per-mailbox, per-adapter session state directory, which outlives runs. - **§7.2 / §7.3:** the branch name is fixed at the first run, so it stays stable as a session name. Session state is removed on done or cancel, and is not removed by the run's `finally` block. - **§11.7:** reclaiming a lease keeps the session state. A half-written state falls back to a fresh session. - **§13.1:** new steps to resolve the session before the run and record it after. - **§16.2 / §16.3:** - `SessionRef` added to `LlmRequest`. - `sessionId`, `resumed` and `resumeFallback` added to `LlmResult`. - `resumableSessions` and `sessionStatePath` capabilities. - **§16.5:** resume options for each CLI, a "Named sessions and resume" subsection, and a new trap about detecting resume failures. - **§16.6:** detection checks whether the installed version supports resume. - **§17.2 / §17.5 / §17.6:** mounts only the sessions subdirectory and isolates it per mailbox. Documents the accepted risk and the orphan removal. - **§21.2 / §21.3:** cleanup on 404, done, cancel and by the orphan sweep. State is kept while blocked and on lease reclaim. - **§22.3:** new session columns on `llm_sessions`, a `resumable_sessions` column on `agent_installations`, and a note on `mailboxes.branch_name`. - **§23.3:** `AGENT_SESSION_RESUME`, default `true`, at organization and project scope. - **§24.3 / §24.5 / §25.2:** new threat row, retention rule and audit fields. - **§28.1 / §28.2:** new rows for naming, resume, fallback, setting off, isolation, cleanup and name stability, plus support in the test doubles. - **§29:** non-goal 3 reworded. - **§30:** Laravel mapping, cleanup job, and the rule that the native id comes from the database, never from the mounted directory. ### Validation The repository holds only the specification. A script confirmed that every Markdown table has a consistent column count, and the cross-references were reviewed by reading. The edited Mermaid diagram (§13.1) was not rendered. 🤖 Generated with [Claude Code](https://claude.com/claude-code)  Closes #1

Alfred added 1 commit

2026-10-26 00:47:26 +00:00

feat: name local agent sessions after the issue branch and resume them ced09e798e

Specify named, resumable sessions for local coding-agent CLIs (claude-code,
codex, opencode, copilot, grok-build when verified):

- the session name is the issue's branch name, fixed at the first run
  of the issue mailbox and stored in mailboxes.branch_name (§7.3)
- every run of the same issue mailbox resumes the previous session of
  the same adapter, using the native id stored in llm_sessions
- silent fallback to a fresh session with a recorded reason; it never
  fails the run, never counts as an LLM retry and never comments
- session state lives in {base}/.agent-sessions/, scoped per mailbox
  and adapter; only the CLI's sessions subdirectory is mounted, and it
  is removed when the issue is done or cancelled, on a 404 and by the
  orphan sweep
- new capability resumableSessions/sessionStatePath, SessionRef in
  LlmRequest, session fields in LlmResult and llm_sessions
- new runtime setting AGENT_SESSION_RESUME (default true)
- accepted risk documented in §17.5 and §24.3; testing contract rows
  added; non-goal 3 reworded

Refs: #1

Alfred self-assigned this

2026-10-26 00:47:26 +00:00

SebastienDenooz changed title from ~~WIP: Name local agent sessions after the issue branch and resume them~~ to Name local agent sessions after the issue branch and resume them

2026-10-26 01:24:45 +00:00

Alfred requested review from SebastienDenooz

2026-10-26 01:31:05 +00:00

Alfred removed their assignment

2026-10-26 01:31:05 +00:00

SebastienDenooz was assigned by Alfred

2026-10-26 01:31:05 +00:00

SebastienDenooz merged commit ced09e798e into main

2026-10-26 09:44:17 +00:00