feat(coding-agent): show generated session summaries in the resume picker

[MarkAronov]

Closes #1033

Problem

The resume picker identifies sessions by a truncated first message, so you have to guess which conversation is which, or open them one at a time to find out.

Solution

Atomic now generates a one-line summary of each session once the agent goes idle, stores it in the session file, and shows it in /resume and atomic -r.

Per @flora131's guidance, this reuses the existing summarization request path — model, credentials, stream function, retry policy — with a new one-line prompt, stored separately from branch_summary, generated on idle rather than when the picker opens, and falling back to today's display when unavailable.

How it works

• Generation (core/compaction/session-summarization.ts) mirrors generateBranchSummary's pipeline minus the parts that don't apply: no entry collection, file-op tracking, preamble, custom instructions, or reasoning request. The response has whitespace collapsed and length clamped, because the picker renders one row per session and the prompt can only ask for one line.
• Orchestration (core/agent-session-summary.ts) runs fire-and-forget from agent_end. It declines when disabled, in --print/JSON mode, while streaming or compacting, without a model, on workflow-stage sessions, on very short sessions, and — the main cost control — when the last conversation message hasn't moved since the stored summary.
• Staleness is anchored to the id of the last user/assistant message the summary covers, not the leaf id. Appends move the leaf (including the summary's own append, and every model or thinking-level change), so a leaf-based check would regenerate on every idle. The picker shows the summary only while that anchor is still the newest conversation message; a later branch_summary also retires it, since the branch it described was abandoned.
• Concurrency uses a monotonic token plus a session-scoped AbortController. After the request returns, the run re-reads both the token and the anchor and discards its own result if either moved. The next prompt and session disposal both cancel it.
• Display is summary ?? name ?? firstMessage. A stale or missing summary is simply absent from SessionInfo, so the fallback needs no logic in the selector. Session id, message count, age, and cwd stay on the row.

sessionSummary.enabled (default true) turns it off.

Decisions worth a second opinion

• A generated summary currently outranks an explicitly user-set session name. That follows the fallback ordering in Improve resume list context with chat summaries #1033 ("fall back to the current session name or first message"), but it's the one call I'd happily reverse — it's a one-line change plus a test.
• Summary token usage counts toward session totals and the footer, matching branch_summary. It's deliberately excluded from cache-stats.ts, where compaction/branch_summary reset prompt-cache continuity — a separate one-shot request doesn't break the main prefix.
• Retries are silent. The retry policy is passed, but not the lifecycle callbacks, which drive a foreground "retrying summarization…" banner meant for work the user initiated.
• Known gap: navigating to an earlier point without summarizing leaves no trace in the file, so the picker can briefly show a summary describing an abandoned branch. It self-heals on the next turn; the cost of being wrong is one slightly-off line.

Tests

Added test/session-manager/session-summary-listing.test.ts (fresh; stale after a newer message; retired by a later branch summary; unaffected by tool results; absent when never generated) and test/suite/agent-session-summary.test.ts (anchored to the newest conversation message; no regeneration while the conversation hasn't moved; disabled by setting; skipped in non-interactive modes; no persistence once the conversation has outrun the request).

test/suite/agent-session-summary.test.ts                    5 passed
test/session-manager/session-summary-listing.test.ts        5 passed
test/unit/host-session-picker-local.test.ts                 
test/unit/interactive-engine-session-picker.test.ts         31 passed
test/unit/workflow-resume-selector-host-picker.test.ts      
test/session-selector-*.test.ts, internal-session-resume-*  24 passed

npm run check passes. The full npm run test:unit has two pre-existing failures on my Windows machine, both verified against clean upstream/main with none of these commits present: flaky-test-suite-runner.test.ts fails deterministically ('C:\Program' is not recognized — an unquoted path with a space when it spawns the child suite), and one load-sensitive timeout that varies by run and passes in isolation. Happy to open a separate issue for the first if it's not already known.

Follow-up

Workflow-run summaries are a second PR, as agreed on the issue — those use different storage and have no single shared transcript, so stage names and results are the right source there.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

Greptile Summary

Atomic now generates concise, bounded summaries for eligible idle interactive sessions, persists them with message freshness anchors, and shows current summaries in resume pickers.

Executed session-lifecycle and picker checks ruled out duplicate idle generation, stale writes after prompt changes, navigation, or disposal, and stale summary display after branch retirement. The branch-retirement behavior was also reproduced on the earlier implementation and confirmed fixed in this change.

Confidence Score: 5/5

The PR is safe to merge; no blocking failure remains.

Focused execution covered summary freshness, idle scheduling, concurrent launches, prompt supersession, navigation cancellation, disposal, persisted listing, and resume-picker rendering. These checks confirmed that the feature avoids stale summary writes and display.

T-Rex Logs

What T-Rex did

• The team reproduced the branch-retirement summary behavior against the earlier implementation and confirmed that the current change regenerates the summary after retirement.
• Focused real-harness tests for idle freshness, concurrent-launch coalescing, prompt supersession, navigation cancellation, and disposal completed with all seven tests passing.
• Persisted-listing and picker tests for fresh, stale, retired, tool-result, and rebranched summaries completed with all twelve tests passing.
• Obsolete summaries are neither persisted nor displayed, while valid summaries are regenerated when retirement invalidates an earlier one.

_{Ran code and verified through T-Rex}

_{Reviews (13): Last reviewed commit: "Merge remote-tracking branch 'origin/mai..." | Re-trigger Greptile}

[flora131]

Hi @MarkAronov thanks for the thoughtful work on this and for the detailed tests and documentation. We tested the exact PR head (aee30eb0ae934a6683754714fdc62c5b93c2561a) using the built Atomic CLI in a real tmux TUI session and found two lifecycle issues that need to be fixed before approval.

1. Start summary generation only after the agent has fully become idle

The summary attempt currently starts from agent_end, but that callback can run while the agent still reports isStreaming. _maybeGenerateSessionSummary() then returns early and nothing retries it.

We reproduced this with the current built --no-extensions TUI: two user/assistant turns completed, the session remained idle, and the JSONL contained four conversation messages but no session_summary entries. The resume picker therefore showed the existing fallback instead of a generated summary.

Please move the launch to a confirmed post-settlement/idle boundary, or schedule a safe deferred retry when streaming clears. Please add regressions for both the normal CLI and --no-extensions path so an eligible completed turn reliably produces a summary after idle.

Relevant location: packages/coding-agent/src/core/agent-session-events.ts:267.

2. Prevent queued summary work from running after disposal

dispose() currently aborts a summary controller only if that controller already exists. Work queued before the controller is created can resume after disposal, create a new request, contact the provider, and append to retired session state.

We reproduced this with a held-queue harness: it paused _checkCompaction(), called dispose(), and then released the queued agent_end work. The provider was called and a summary was appended after disposal.

Please track a disposed/session-generation state and reject summary work both when it starts and after each asynchronous boundary. At minimum, check ownership/disposal before auth, before contacting the provider, and before persisting the result. Please add a regression that holds the queue, disposes the session, releases the queue, and asserts zero provider calls and zero post-disposal appends.

Relevant location: packages/coding-agent/src/core/agent-session-events.ts:479-481.

These findings are based on repeatable runtime evidence rather than source review alone. In short, the first issue can silently prevent the feature from running, while the second can let it run after the session should be finished. Thank you again for the contribution and for taking a look at these cases.

[flora131]

One workflow tip: you can have Atomic run this verification for you after you make the fixes instead of driving the TUI manually.

From your PR checkout, start Atomic and give it a prompt like:

Test the changes on this PR for correctness. Build and run this branch's own
Atomic CLI in a tmux session and manually verify the feature works as the
linked issue describes, then post the evidence of the results to the PR as
a comment. Don't modify the code or the PR itself.

Atomic turns that into a tracked workflow: it scopes the acceptance criteria from the issue and PR, builds your branch, launches that exact build inside a tmux session, operates the resume picker and the rest of the TUI manually, and surfaces anything it reproduces — with the evidence (commands, pane captures, session-file contents) posted back here as a comment.

Two details in the prompt matter: "this branch's own Atomic CLI" keeps it from testing the globally installed binary, and "don't modify the code or the PR" keeps it review-only. If a specific path matters, name it in one extra sentence — for example the --no-extensions flow from the findings above.

You can watch the run with /workflow connect <run-id> while it works, and the tmux session stays alive afterward for your own inspection.

[MarkAronov]

Hi @flora131, thanks for taking the time to run this against a real build and write it up so clearly. Both findings reproduce.

The first has a sharper cause than the callback running early. I subscribed to agent_end and measured it: isStreaming is true there and stays true across the whole microtask queue, clearing only on a later macrotask. So generation worked only when await this._checkCompaction(msg) on the previous line happened to cross that boundary. It does in the unit harness, which is why seven tests passed while your run produced nothing. Good catch, this would have shipped silently.

Fixed both in one commit, since they interact: deferring to idle widens the disposal window the second finding is about.

1. await this.agent.waitForIdle() inside _maybeGenerateSessionSummary, with the supersession token claimed before the wait so a later turn abandons a parked launch.
2. A terminal _disposed flag set by dispose(), checked on entry, after the wait, before auth, before the provider call, and before persisting. abortSessionSummary() bumps the token too, since a parked launch has no AbortController yet. dispose() is idempotent.

Regressions: a launch fired from inside agent_end while isStreaming is true, which also asserts that condition is reproduced so it cannot pass for the wrong reason; and dispose then release, asserting zero provider calls and zero appends. Both fail against the pre-fix source, with two more covering the new token semantics.

One scope question before I go further. --no-extensions only affects the resource loader, not _extensionMode, and the harness already runs with no extensions, so that path is covered. For the normal CLI I have stayed at harness level. Would you like a real CLI regression that spawns the binary and checks the JSONL? Happy to add it, just want to match the bar you have in mind.

[flora131]

Thanks @MarkAronov. Your explanation and fixes address the two findings. The harness coverage for --no-extensions sounds reasonable, and I don’t think an additional real-CLI regression is necessary if the existing regression reliably reproduces the timing condition that failed in the TUI.

The branch now conflicts with main in agent-session-events.ts due to the newer model-fallback handling. Could you merge or rebase the latest main, preserve both the fallback lifecycle logic and the session-summary launch, and rerun the relevant checks? Sorry for the delay on our side. Once the conflicts are resolved and checks pass, we should be good.

[MarkAronov]

Hey @flora131! Thanks for getting back to me, and no worries at all about the delay,
it really wasn't a problem on my end.

Will do. One thing: I'd like to merge main in rather than rebase, if that's
fine by you. Three of the commits here touch agent-session-events.ts, so a
rebase replays the same conflict two or three times, and the force push would
mark the existing threads outdated and make it harder to see what actually
changed since you last looked. Since the PR squash-merges, main ends up
identical either way.

On preserving both: the collision is that my summary launch sits exactly where
#2201 added the overflow-fallback block, at the tail of _processAgentEvent.
Keeping both, with the launch last, for two reasons:

• A fallback switch returns before it, so a turn that continues on another model
  doesn't get summarized mid-flight.
• _restoreFallbackModel() has already run by then. That matters because the
  launch reads this.model synchronously before it parks on waitForIdle(), so
  launching any earlier would send the summary request on the fallback model
  instead of the one the user actually picked.

CHANGELOG.md was the other conflict. Both sides had added to [Unreleased],
so I kept both.

Two things the merge turned up:

A race it exposed. #2201's extra awaits changed the turn timing enough that
two overlapping summary launches each sent a provider request, and only the
second could save. That was always possible, the old timing just hid it. Now the
in-flight request is published with the throughId it covers, so a launch for
the same state waits on it instead of cancelling it and starting over.

One bug that was mine. I hadn't guarded the launch with
typeof this._maybeGenerateSessionSummary === "function" like the other optional
methods there, so it threw on the fake session the main-chat fallback tests use
and broke a compactable context overflow does not spend a fallback candidate.
Fixed, 21/21 again.

Results: npm run check clean, test:integration 485 passed, summary/listing/
retry suites 29 passed. test:unit has 10 failures but all 10 also fail on clean
upstream/main here, and main-chat-model-fallback passes.

One ask: the Tests workflow is stuck at action_required on every push to this
PR, so CI has never run. Could you approve it?

Also hit four Windows issues in the repo's tooling, none related to this PR.
Happy to open issues:

• test/global-setup-natives.ts calls spawnSync("npm", ...) without
  shell: true. npm is npm.cmd on Windows, so it's ENOENT and all three root
  suites die before any test runs.
• cargo clippy -- -D warnings fails on crates/atomic-natives/src/grep/run.rs
  (refactor(natives): split grep and fs_cache into responsibility modules #2206). Its #[cfg(test)] helpers are only used by #[cfg(unix)] tests, so
  they're dead code on Windows.
• rustfmt.toml sets newline_style = "Unix" but .gitattributes has
  * text=auto, so with core.autocrlf=true every .rs file checks out CRLF
  and cargo fmt --check can never pass.
• release-publisher-contracts.test.ts calls bare tar, which picks up Git's
  GNU tar on Windows and reads C:\... as a remote host.

[greptile-apps]

Want your agent to iterate on Greptile's feedback? Try greploops.

[MarkAronov]

Hey @flora131 - following up on this. Pushed the fix for both issues on Aug 5 (9d340ab: deferred generation to a real idle boundary, added terminal disposal tracking).
Also still curious on the scope question from my last comment - want a real CLI regression that spawns the binary and checks the JSONL, or is harness-level coverage enough?

[flora131]

Hey @flora131 - following up on this. Pushed the fix for both issues on Aug 5 (9d340ab: deferred generation to a real idle boundary, added terminal disposal tracking). Also still curious on the scope question from my last comment - want a real CLI regression that spawns the binary and checks the JSONL, or is harness-level coverage enough?

Thanks for your patience, we are working on a large suite of fixes with the latest pi dependency upgrade to 0.84.1 which is taking longer than expected. Merge makes sense for conflict resolution, but we will most likely need to fix some conflicts because of the larger refactor for our pi dependency. We'll handle the conflicts and put your changes into the merge queue once you have the E2E test implemented as described below.

An E2E harness test is preferred: just ask Atomic to "spawn an instance of itself and mention that it's authenticated and can drive the CLI to make sure it works and then ask Atomic to comment on this PR with tmux screenshot evidence that the change works."

[flora131]

Thanks for finding the dev environment issues in Windows @MarkAronov! Yes, it would be great to file them, so we can understand if these are still issues in the latest main branch.

[MarkAronov]

Fixed the failing unit test in 63ec766.

The idle session-summary launch is a second caller of the same fake provider in interactive-engine-cycle-fallback, so the requests === 1 assertion saw 2. The fixture now opts out of session summaries.

Worth knowing for later: any fixture test that counts provider requests is now sensitive to background summary traffic. This is the only one today.

[flora131]

Ran a local E2E pass of this branch (macOS, Bun 1.3.14, tmux-driven dummy CLI session):

1. Fresh session in a throwaway cwd, one prompt, agent went idle → a session_summary entry landed in the session file ~17s later, anchored via summarizedThroughId and counted in session usage totals.
2. Relaunched with -r: the picker row shows the generated summary instead of the truncated first message.
3. Selecting the row resumes the correct session with the full prior conversation.

Stored entry:

{"type":"session_summary","summary":"Answered a quick question defining git worktrees as linked working directories for multiple branch checkouts","summarizedThroughId":"a080e293",...}

[flora131]

Pushed 7f30478 with three amendments:

1. Summary is now its own column. The row identity (session name or first message) is never displaced; the generated summary renders beside it, dim. The column only appears when at least one listed row has a summary, so the durable-workflow picker and fresh installs keep the old single-column layout.
2. Explicit fallback. Rows without a usable summary (missing, stale, failed, whitespace-only) show a muted italic "No summary available." placeholder; the column is skipped entirely on narrow terminals.
3. CI fix. The linux agent-suite failure was a race in "runs no summary work once the session has been disposed": it assumed turn 2's fire-and-forget launch reached the provider before dispose(). It now gates on request start with the same Promise.withResolvers mechanism as the neighboring mid-request test, making the pending-response count deterministic.

Docs (docs/sessions.md) and the changelog entry updated to match. New render coverage in test/session-selector-summary-column.test.ts (6 tests: column, name+summary coexistence, placeholder, whitespace-only, no-summary lists, narrow terminals).

[flora131]

Updated E2E capture of the column layout on 68e5250 (tmux-driven, same dummy-session flow as before, now with two sessions to show both states):

Row identity (first message) stays in the left column; the generated summary sits in its own aligned column, with the muted italic placeholder for the session that has no summary yet.

[MarkAronov]

Thanks @flora131, and thanks for the amount of work you put into this one.
Building the branch and driving it in tmux to find the agent_end timing
problem is well beyond a source review, and both findings were real.

Sorry about the changelog. My Aug 7 merge folded the released
0.9.13-alpha.2 entries into [Unreleased] and dropped the section
header. I took the immutability rule to mean don't edit released entries
and missed that main had already promoted that set.

I went through your other commits. The summary column is better than what
I had, keeping the row identity and adding an explicit placeholder is the
right call. And clearing _lastSummarizedMessageId in
abortSessionSummary() is correct: the in-memory anchor is not
retirement-aware and needs to defer to the persisted lookup after any
cancellation. Good one to have caught.

On the Windows side, #2291 is filed and already fixed. The rest of what I
hit looks environment-specific rather than worth separate issues.

Planning to pick up #2329 next if possible.

Thanks again :)