@giladbarnea/pi-user-agents 0.0.4 → 0.0.6

package/INTERNALS.md

@@ -16,13 +16,13 @@ How a finished run reaches (or hides from) the main agent rests on two Pi SDK ch
 
 - **`pi.appendEntry(customType, data)` + `pi.registerEntryRenderer`** — the only channel that renders in the transcript while staying out of LLM context *forever*. Entries are persisted in the session file and re-rendered on reload. The entry's `data` is optional in the type — renderers must guard it.
 
-This extension maps the two extremes onto the `-j` flag: the default posts the result card via `appendEntry` (main agent structurally oblivious), and `-j` posts a visible custom message with `{ triggerTurn: true }` (steered mid-turn or answered immediately). Both channels share one card renderer in `transcript.ts`.
+This extension maps the two extremes onto the `-s` flag: the default posts the result card via `appendEntry` (main agent structurally oblivious), and `-s` posts a visible custom message with `{ triggerTurn: true }` (steered mid-turn or answered immediately). Both channels share one card renderer in `transcript.ts`.
 
-Immediate `-j` delivery and late `j join` delivery share one canonical message builder. Its `display` option prevents a second visible result card. Both paths use the same selected conversation and `{ triggerTurn: true }` delivery. For a run launched without `-j`, the context message stays hidden at join time because the TUI-only result card is already visible.
+Immediate `-s` delivery and late `s` squash delivery share one canonical message builder. Its `display` option prevents a second visible result card. Both paths use the same selected conversation and `{ triggerTurn: true }` delivery. For a run launched without `-s`, the context message stays hidden at squash time because the TUI-only result card is already visible.
 
-## Joined message format
+## Squashed message format
 
-The joined text starts with this sentence:
+The squashed text starts with this sentence:
 
 > The user has dispatched a background sub-agent with a task. The sub-agent is done. The following is the back and forth between them:
 
@@ -30,6 +30,26 @@ A plain `<user_agent>` tag follows it. The tag contains only the model and inher
 
 One selection rule builds the body. It keeps every user message. Before each next user message, it keeps only the latest assistant response. It applies the same rule after the final user message. Tool calls, thinking, tool results, and other message roles stay out.
 
+## Rebase
+
+`r` fast-forwards the raw child conversation onto the dispatching session. Three Pi facts shape the mechanism:
+
+1. The main agent's next LLM call reads the in-memory `agent.state.messages`, not the session file, and the TUI transcript renders from `AgentSession` events, not from the `SessionManager`. Appending entries alone reaches neither.
+2. Extensions have no path to the main `AgentSession`, so the state cannot be pushed in place.
+3. On `ctx.switchSession()` the host rebuilds both from the file — `agent.state.messages` from `buildSessionContext()` and the transcript from `buildContextEntries()` — while tearing the extension runtime down (`session_shutdown`, then a fresh extension instance).
+
+Delivery therefore appends the processed messages through the session manager (`ctx.sessionManager` is typed `ReadonlySessionManager`, but the runtime object is the writable `SessionManager` — one cast), drops a persisted `pi-user-agents-rebased` breadcrumb entry naming the child session, and calls `ctx.switchSession(<current session file>)`. Not `ctx.reload()` — that one reloads extensions and resources only and never re-reads the session file.
+
+Message processing (`selectRebaseMessages`) keeps the child's history verbatim, with two exceptions: the first user message becomes the plain task (dropping the internal background-process prefix), and this extension's own custom messages (`pi-user-agents`) are dropped — they are the one trace of the user-agents machinery. Everything else the child saw passes through, other extensions' custom messages included.
+
+A child compaction passes through deliberately and lands as a real `compaction` entry mid-file. `buildContextEntries` treats the latest compaction on the path as the context boundary, so after the switch main's LLM context is exactly the child's live context — summary, kept tail, then everything after — while the transcript keeps the full history. Dropping it would instead graft an over-window context onto main and force a fresh, lossy auto-compaction.
+
+Two mechanics make that exact. First, a live compaction emits no message event — only `compaction_end` — so the child subscription captures it there as a synthetic `compactionSummary` message, or the append-only conversation would never contain it. Second, the kept-tail boundary (`firstKeptEntryId`) is a child-session entry id that means nothing in the main session's file; but at `compaction_end` the child's live context is exactly `[summary, kept tail]`, so the capture records `keptTailCount`, and the rebase replay counts back that many context messages to pass the main-session id of the message that starts the tail. The tail may reach past the replayed messages into main's pre-existing context — a child that inherits a nearly full context compacts early — so the delivery prepends main's own per-message entry ids to the count.
+
+The fast-forward precondition is fingerprint equality: at dispatch the agent stores `JSON.stringify` of the inherited context messages (`[]` for `-i`), and `r` is offered only while the main session's current `buildSessionContext().messages` fingerprint still matches. The live fingerprint is cached per session manager and recomputed only when the branch leaf moves, so TUI-only entries (result cards, detach lines) move the leaf, trigger one recompute, and correctly do not block the rebase. One rule covers isolated agents too: their base is empty, so they rebase only onto a still-empty session.
+
+Because the session switch tears the extension down, live widget rows cannot survive it: `r` is withheld while any agent is mid-turn, and the remaining parked and completed agents are detached first through the ordinary detach paths, so every one of them leaves its `Detached session …` breadcrumb before the switch. The switch re-opens the same file, so the session id does not change.
+
 ## Child session persistence
 
 Every dispatched agent gets a persisted `SessionManager.create(cwd, undefined, { parentSession })` rather than an in-memory one, so its conversation is an ordinary Pi session file from birth. `parentSession` is a *path*, and it records the main session that dispatched the agent — the same field `/fork` uses, surfaced by `SessionManager.list()` as `parentSessionPath`. There is no API to promote an in-memory session to disk later: `SessionManager` fixes `persist` at construction, and both `_persist()` and `_rewriteFile()` return early when it is false, so `setSessionFile()` on an in-memory manager sets a path and writes nothing.
@@ -37,7 +57,7 @@ Every dispatched agent gets a persisted `SessionManager.create(cwd, undefined, {
 Two ordering constraints follow from `createAgentSession`:
 
 1. **Build the session while its manager is still empty.** Pi writes the `model_change` and `thinking_level_change` entries only on the empty-session path. Seed messages first and those entries never appear, so a resumed child falls back to `findInitialModel` instead of the model it was dispatched with.
-2. **Route the inherited snapshot through the session manager.** Persistence runs off message events, so the old `session.agent.state.messages = inherited` assignment never reached the file. `persistInheritedMessages` appends it entry by entry, then the agent state is set to the same list.
+2. **Route the inherited snapshot through the session manager.** Persistence runs off message events, so the old `session.agent.state.messages = inherited` assignment never reached the file. `persistMessages` appends it entry by entry, then the agent state is set to the same list.
 
 That snapshot is already compaction-resolved, so at most one `compactionSummary` leads it. Each role takes its own append method — `appendCompaction`, `branchWithSummary`, `appendCustomMessageEntry`, `appendMessage` — because pi's own compaction and branch bookkeeping locates boundaries by entry type, and a summary written as a plain message entry would be invisible to it. `appendCompaction` wants a `firstKeptEntryId` the replay cannot know, but `buildContextEntries` only consults it for entries *before* the compaction entry; a leading compaction has none, so the value is never read.
 
@@ -45,7 +65,17 @@ The file itself appears on the child's first assistant message (`_persist` defer
 
 ## Detaching
 
-`d` `d` ends the live child session and drops its widget row. The session file is untouched, and the transcript gets a `pi-user-agents-detached` custom entry naming the session id so it can be resumed later. Both detach paths funnel through `closeRunning` and `removeCompleted`, which is where the announcement is made; joining and session shutdown deliberately do not announce.
+`d` `d` ends the live child session and drops its widget row. The session file is untouched, and the transcript gets a `pi-user-agents-detached` custom entry naming the session id so it can be resumed later. Both detach paths funnel through `closeRunning` and `removeCompleted`, which is where the announcement is made; squashing and session shutdown deliberately do not announce.
+
+## Attaching
+
+`/agent-attach <session-id>` reverses a detach. The id (or a unique prefix) resolves in one pass over the whole universe of candidates: the widget's rows (live and completed) united with file names in pi's default session directory for the cwd — the directory every dispatch creates children in. File names, not `SessionManager.list()`, because list() reads every session file whole, gigabytes in a mature project; the union, because a prefix unique among rows could otherwise mask an ambiguity with a detached file, and a live row whose file is not flushed yet must still resolve. A resolved id that is already a row short-circuits to the "View agent?" confirmation and nothing else — the idempotent case. The authority for "is a child of this session" is the child file's header: its `parentSession` path must equal the main session's file. That is the same field `/fork` writes, so a fork of the main session attaches too.
+
+The session file does not persist the dispatch options, so every dispatch writes a `pi-user-agents-dispatch` custom entry into the child — the forwarded pi tokens, the plain task, and the isolate flag. At attach the record replays through the same projections dispatch used (`buildChildResourceLoaderOptions`, `resolveToolOptions`), so `--tools`, `--no-extensions`, `--system-prompt` and friends survive the round trip instead of silently widening back to pi defaults. The model and thinking level deliberately come from the file, not the record: reattachment is pi's own resume path — `SessionManager.open` plus `createAgentSessionFromServices` on a non-empty manager takes `createAgentSession`'s has-existing-session branch — and the file reflects any later changes. A record-less child (dispatched before the record existed, or `/fork`-made) still attaches, with pi's default tools and resources.
+
+The dispatch preamble — built at the dispatch call site, sent verbatim by `runChildTurns` — doubles as the boundary marker: `splitAtDispatchBoundary` finds the first user message carrying it and recovers the child's own conversation for the overlay and the inherited base whose fingerprint re-arms the rebase fast-forward. The fingerprint compares content, not file bookkeeping: rebuilding custom, compaction, and branch summaries from a session file re-stamps their timestamps (and a branch summary's `fromId`), so `conversationFingerprint` drops those fields or a round-tripped base would never equal main's live context. Without a recognizable boundary (a fork child, or a child whose compaction summarized it away) the whole context attaches and the base is a sentinel that never matches, so `r` stays withheld.
+
+The attached agent parks idle first (`runAttachedTurns` waits for an instruction before running the shared turn loop), and its latest persisted response seeds `pendingSquashMessage`, so steering, `s`, and `r` work immediately without a new turn. A successful attach leaves an `Attached session …` breadcrumb — the detach line's counterpart — and both success states end with a "View agent?" confirmation that opens the overlay.
 
 ## Runtime sharing
 

package/PARSER_SPEC.md

@@ -10,7 +10,7 @@ from the declaration in `command-line.ts`.
 ```ts
 type ParsedAgentCommand = {
   isolate: boolean;          // -i / --isolate
-  context: boolean;          // -j / --join
+  squash: boolean;           // -s / --squash
   forwardedArgs: string[];   // recognized pi option tokens (+values) in input order, e.g. ["--thinking","high"]
   task: string;              // the prose prompt (backslash escapes applied, quotes kept). Never empty.
   warnings: string[];        // advisory messages (see §5). May be empty.
@@ -43,11 +43,11 @@ leading whitespace (unchanged from today).
 |---|---|---|
 | `-m`, `--model` | value | Added to `forwardedArgs` as canonical `--model <value>` |
 | `-i`, `--isolate` | boolean | Consumed here; `isolate = true` |
-| `-j`, `--join` | boolean | Consumed here; `context = true` |
+| `-s`, `--squash` | boolean | Consumed here; `squash = true` |
 
 `-m` and `--model` are one semantic option. Both require an exact live model ID, canonical
 `provider/id` reference, or user-defined alias before resolving through Pi's `resolveCliModel()`
-path. A preceding `--provider` scopes either spelling. `-j` is the extension's join option.
+path. A preceding `--provider` scopes either spelling. `-s` is the extension's squash option.
 A model option with no value and no remaining task ends in the normal
 **usage error**.
 

package/README.md

@@ -1,10 +1,31 @@
+<div align="center">
+
 # pi-user-agents
 
-> You deserve your own agents, too. It's only fair.
+> **You deserve your own agents, too. It's only fair.**
+
+[![pi extension](https://img.shields.io/badge/pi-extension-blueviolet)](https://github.com/earendil-works/pi)
+[![npm version](https://img.shields.io/npm/v/%40giladbarnea%2Fpi-user-agents?logo=npm)](https://www.npmjs.com/package/@giladbarnea/pi-user-agents)
+[![tests](https://img.shields.io/github/actions/workflow/status/giladbarnea/pi-user-agents/test.yml?branch=main&label=tests&logo=github)](https://github.com/giladbarnea/pi-user-agents/actions/workflows/test.yml)
+[![license](https://img.shields.io/github/license/giladbarnea/pi-user-agents)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![tested with Bun](https://img.shields.io/badge/tested_with-Bun-14151A?logo=bun&logoColor=white)](https://bun.sh/)
+
+**No token tax. No derailed turns. No trace — unless you say so.**
 
 Pi extensions give your agent subagents. This one gives **you** — the user — your own: background agents you dispatch mid-turn, watch live, steer, and whose results stay **out of the main agent's context** until you decide otherwise.
 
-The moment it's for: your main agent is deep in a tool-calling frenzy on phase 1, and you already know what phase 2 needs.
+</div>
+
+---
+
+## Why
+
+You're watching your agent grind through phase 1, and you already know what phase 2 needs.
+
+You have two options, and both are bad. Steer — and derail the work in progress with an errand. Wait — and carry the thought in your head for twenty more minutes.
+
+Now there's a third:
 
 ```
 /agent plan the next phase and write it to phase-2.md
@@ -12,6 +33,8 @@ The moment it's for: your main agent is deep in a tool-calling frenzy on phase 1
 
 The instant you press Enter, a background agent forks off with a snapshot of the current conversation and gets to work — while your main agent keeps going, none the wiser.
 
+**A second pair of hands with the same memory — and a separate token budget.**
+
 ## Install
 
 ```sh
@@ -29,10 +52,10 @@ Classic dispatches:
 ```
 /agent write a handoff document for the work currently in progress
 /agent -i -m flash summarize what PARSER_SPEC.md guarantees
-/agent -j --thinking high find the root cause of the flaky widget test
+/agent -s --thinking high find the root cause of the flaky widget test
 ```
 
-The first preserves the session's knowledge before the context window fills, without interrupting the main agent to do it. The second is a cheap, isolated errand. The third auto-joins: its findings are delivered into the main conversation when it finishes.
+The first preserves the session's knowledge before the context window fills, without interrupting the main agent to do it. The second is a cheap, isolated errand. The third auto-squashes: its findings are delivered into the main conversation when it finishes.
 
 ### 2. Watch
 
@@ -46,7 +69,7 @@ Every agent gets a row in a widget under the editor: status, task, model, turn c
 
 <br>
 
-Press `←` or `↓` from the editor to focus the widget, pick an agent, press `Enter`, and its overlay opens: the full conversation, streaming live, following the tail as it grows. Scroll up to pause following; `End` resumes it. Tool calls render as proper views — `read`, `edit`, `write`, `grep`, `find`, `ls`, and `bash` each get a dedicated format, everything else a readable generic one.
+Press `←` or `↓` from the editor to focus the widget, pick an agent, press `Enter`, and its overlay opens: the full conversation, streaming live, following the tail as it grows. Tool calls render as proper views — `read`, `edit`, `write`, `grep`, `find`, `ls`, and `bash` each get a dedicated format, everything else a readable generic one.
 
 <a href="screenshots/overlay.png">
   <img src="screenshots/overlay.png" width="100%" alt="The agent overlay: a rendered bash call, its output, a todo update, and the final response, over the dimmed main conversation">
@@ -54,21 +77,17 @@ Press `←` or `↓` from the editor to focus the widget, pick an agent, press `
 
 <div align="center"><em>The overlay, over a main conversation that never paused.</em></div>
 
-<br>
-
-The context meter is the agent's own footer gauge in one cell: it fills `▁▂▃▄▅▆▇█` against that agent's model context window and shifts color through the same stages as Pi's footer (dim, then muted at 40%, warning at 65%, error at 85%).
-
 ### 3. Steer
 
 A background agent is not fire-and-forget — it's a session you can talk to.
 
 Press `Enter` in the overlay to open the steer composer. Mid-turn, your message queues in after the current tool batch, before the next model call — exactly like steering the main agent. After the turn completes, the same composer starts **another turn** on the same live session. Follow up as many times as you need; every completed turn posts its own result card.
 
-`Ctrl+x` interrupts only the current turn — the agent goes idle and stays available for steering, joining, or detaching. In fact, nothing ends an agent except you: pressing `d` twice, joining it, or ending the Pi session.
+`Ctrl+x` interrupts only the current turn — the agent goes idle and stays available for steering, squashing, or detaching. In fact, nothing ends an agent except you: pressing `d` twice, squashing or rebasing it, or ending the Pi session.
 
 ### 4. Detach
 
-Every dispatched agent gets its own Pi session on disk, exactly like the one you're sitting in. When a row has served its purpose, press `d` twice: the agent stops, its row leaves the widget, and its session file is left untouched. The transcript records which one it was:
+When a row has served its purpose, press `d` twice: the agent stops, its row leaves the widget, and its session file is left untouched. The transcript records which one it was:
 
 ```
 Detached session 0199c4f2-8b1a-7c3d-9e05-6a2f18d7b4ce
@@ -76,22 +95,40 @@ Detached session 0199c4f2-8b1a-7c3d-9e05-6a2f18d7b4ce
 
 Pick it back up whenever you like — `/resume 0199c4f2`, or `pi -r` and choose it from the list. It resumes as an ordinary Pi session with its full history, its model, and its thinking level, and from there it is a normal agent you talk to directly.
 
-### 5. Join — or don't
+Or take it back as a background agent instead: `/agent-attach 0199c4f2` puts the session back in the widget — parked idle, restored as dispatched down to its `--tools` and the rest of its options — and offers to open it. A unique id prefix is enough, only this conversation's own agents qualify, and the transcript records the return: `Attached session 0199c4f2-…`.
+
+### 5. Squash — or don't
 
 This is what makes user agents different from subagents: **by default, the main agent never learns any of this happened.**
 
 Each completed turn posts a result card into your transcript — metadata, a collapsed preview, expandable to the full Markdown response. The card is TUI-only: you read it, expand it, copy it, and the main agent's context is untouched. Ask an agent ten questions and your main agent's token budget doesn't move.
 
-When a result does belong in the main conversation, join it:
+When a result does belong in the main conversation, squash it in:
+
+- Dispatch with `-s`/`--squash` and the result is delivered automatically on completion.
+- Or press `s` in the overlay of any completed agent, whenever you decide it earned its place.
 
-- Dispatch with `-j`/`--join` and the result is delivered automatically on completion.
-- Or press `j` in the overlay of any completed agent, whenever you decide it earned its place.
+A squash delivers a compact record, not a transcript dump: every message you sent the agent and the final answer to each — no thinking, no tool traffic. The record is rebuilt from the agent's full history at squash time, so early turns survive even after the agent compacts its own context. If the main agent is mid-turn, the record is steered in; if idle, it triggers a turn. A squashed agent retires; its overlay stays readable.
 
-Joining delivers a compact record, not a transcript dump: every message you sent the agent and the final answer to each — no thinking, no tool traffic. The record is rebuilt from the agent's full history at join time, so early turns survive even after the agent compacts its own context. If the main agent is mid-turn, the record is steered in; if idle, it triggers a turn. A joined agent retires; its overlay stays readable.
+### 6. Or rebase — rewrite history
 
-## Per-agent configuration
+Squash has a raw sibling. Press `r` in the overlay and the agent's whole conversation — prompts, replies, tool calls and their results — is appended to the main session as ordinary messages, exactly as if you had prompted the main agent all along. The dispatch preamble is stripped, nothing is wrapped or summarized, and no trace remains that a background agent ever existed.
 
-Each dispatch takes its own configuration, using the same flags as the `pi` CLI:
+Everything the agent lived through rides along untouched. If it compacted its own context mid-run, the compaction rides along too, and the main conversation's context picks up exactly where the agent's left off. The transcript redraws with the conversation inline, plus one dim provenance line:
+
+```
+Rebased session 01a0534e-9fa7-7d6f-bd44-b85fba1f5e05 into this conversation (added 32 messages, ~135K tokens, 1 compaction event)
+```
+
+Rebase is a fast-forward, in the git sense: the agent forked from the main conversation's tip, and its history can graft back only while that tip hasn't moved. Send the main agent anything after the dispatch and `r` disappears, leaving `s` — which always works — as the way in. Press `r` anyway and the footer tells you why not.
+
+Delivering the rebase switches the session in place — same file, same session id, transcript redrawn — so `r` is withheld while any agent is mid-turn, and parked agents are detached first, each leaving its `Detached session …` line to `/resume` from. When siblings would be detached, the first `r` warns with the count and a second `r` confirms.
+
+## The mechanics
+
+### 🎛️ Per-dispatch configuration
+
+Each agent takes its own configuration, using the same flags as the `pi` CLI:
 
 ```
 /agent -m opus --thinking high design the caching layer
@@ -101,20 +138,30 @@ Each dispatch takes its own configuration, using the same flags as the `pi` CLI:
 
 Options come first; everything after them is your task, verbatim. The full grammar lives in [PARSER_SPEC.md](PARSER_SPEC.md) — not that you'll need it.
 
-## The fanciest autocomplete in the Pi universe 
+### ✨ The fanciest autocomplete in the Pi universe
 
 You'll rarely type any of this by hand. The moment you type `-`, a completion menu opens — no Tab needed. Anywhere the set of valid values is finite, the editor hands it to you: models, providers, thinking levels, the session's tools, even skill and prompt-template paths. You pick from what actually exists instead of typing and hoping.
 
-And what you do type by hand is checked live, as you type. Valid options and values light up in your theme's syntax colors; anything that won't parse — a blocked option, a model that doesn't resolve, an option stranded after the task began — shows in the error color before you ever press Enter. A `/agent` line that looks right is right.
+And what you do type by hand is checked live, as you type. Valid options and values light up in your theme's syntax colors; anything that won't parse — a blocked option, a model that doesn't resolve, an option stranded after the task began — shows in the error color before you ever press Enter. **A `/agent` line that looks right is right.**
+
+### 🧱 Agents are durable Pi sessions
+
+Every dispatch writes a real session file, exactly like the one you're sitting in, so dispatched agents show up in `/resume` and `pi -r` alongside your own sessions.
+
+Result cards persist across session reloads; the widget doesn't. After a reload you keep every card, and every agent's session is still on disk — but the steerable rows are gone. Reach them with `/resume`.
+
+### 🌡️ A context meter in one cell
+
+Each row carries the agent's own footer gauge: it fills `▁▂▃▄▅▆▇█` against that agent's model context window and shifts color through the same stages as Pi's footer — dim, then muted at 40%, warning at 65%, error at 85%. You see an agent approaching its limit before it becomes a problem.
 
 ## Reference
 
-Everything goes through one command: `/agent [options] <task>`.
+Everything goes through one command: `/agent [options] <task>`. Its one companion, `/agent-attach <session-id>`, brings a detached session back into the widget.
 
 | Flag | Effect |
 |---|---|
 | `-i`, `--isolate` | Start without the conversation snapshot |
-| `-j`, `--join` | Deliver the result into the main context on completion |
+| `-s`, `--squash` | Deliver the result into the main context on completion |
 | `-m MODEL` | Model for this agent (alias of Pi's `--model`) |
 | *pi CLI options* | Forwarded to the agent — `--thinking`, `--tools`, `--system-prompt`, … |
 
@@ -126,21 +173,31 @@ Everything goes through one command: `/agent [options] <task>`.
 | Widget / overlay | `d` `d` | Detach the agent, keeping its session (twice to confirm) |
 | Widget / overlay | `Esc` | Back |
 | Overlay | `Enter` | Steer mid-turn, or start another turn when idle |
-| Overlay | `j` | Join the conversation into the main context |
+| Overlay | `s` | Squash the conversation into the main context |
+| Overlay | `r` | Rebase the raw conversation into the main context (fast-forward only) |
 | Overlay | `c` | Copy the latest response |
 | Overlay | scroll · `End` | Pause tail-following · resume it |
 
 ## Good to know
 
-- Every dispatch writes a real session file, so dispatched agents show up in `/resume` and `pi -r` alongside your own sessions. An agent that never answered leaves no file.
-- Result cards persist across session reloads; the widget doesn't. After a reload you keep every card, and every agent's session is still on disk — but the steerable rows are gone. Reach them with `/resume`.
 - Some accepted `pi` options have no effect on a background run (the session, approval, offline, and API-key families). They parse; they just don't do anything yet.
 - `c` copies via `pbcopy`, so it's macOS-only for now.
 - The overlay caps very large tool outputs and omits thinking entries.
 
+## Roadmap
+
+- [x] Agents stay alive until you end them — steer, interrupt, resume, across turns.
+- [x] Squash: a compact record of the exchange, delivered into the main context.
+- [x] Rebase: the raw conversation grafted onto the main session — fast-forward only, compaction-faithful.
+- [x] Attach: a detached session returns to the widget, restored as dispatched.
+- [x] Live syntax coloring and eager autocomplete for the `/agent` line.
+- [ ] Render an agent's compaction event in the overlay.
+- [ ] Wire the accepted-but-inert `pi` options.
+- [ ] Clipboard support beyond macOS.
+
 ## Under the hood
 
-Design notes — result delivery through the Pi SDK, the joined-message format, runtime sharing, model resolution, and editor internals — live in [INTERNALS.md](INTERNALS.md). The complete command grammar lives in [PARSER_SPEC.md](PARSER_SPEC.md).
+Design notes — result delivery through the Pi SDK, the squashed-message format, the rebase and attach mechanisms, runtime sharing, model resolution, and editor internals — live in [INTERNALS.md](INTERNALS.md). The complete command grammar lives in [PARSER_SPEC.md](PARSER_SPEC.md).
 
 ---
 

package/agent-viewer.ts

@@ -14,7 +14,9 @@ import {
 import { renderAgentContextMeter } from "./context-meter.js";
 import type { AgentMessage, CompletedAgent, RunningAgent, Theme } from "./shared.js";
 import {
+	CONFIRMATION_WINDOW_MS,
 	errorMessage,
+	TimedConfirmation,
 	formatMs,
 	formatToolUses,
 	formatTurns,
@@ -149,7 +151,12 @@ export class AgentViewer implements Component {
 	private autoScroll = true;
 	private lastWidth = 0;
 	private justCopied = false;
-	private confirmingDetach = false;
+	private rebaseWarning: string | undefined;
+	private rebaseWarningTimer: ReturnType<typeof setTimeout> | undefined;
+	/** One confirmation slot for both destructive overlay actions. */
+	private readonly confirmation = new TimedConfirmation<"detach" | "rebase">(() =>
+		this.tui.requestRender(),
+	);
 	private composer: Input | undefined;
 	/** Rich tool rendering is far too costly to repeat on every 100 ms widget tick. */
 	private renderedContent: { key: string; lines: string[] } | undefined;
@@ -159,20 +166,24 @@ export class AgentViewer implements Component {
 		private readonly agent: ViewableAgent,
 		private readonly theme: Theme,
 		private readonly done: (result: AgentViewerAction) => void,
-		private readonly canJoinMainContext: () => boolean,
-		private readonly joinMainContext: () => void,
+		private readonly canSquashMainContext: () => boolean,
+		private readonly squashMainContext: () => void,
+		private readonly canRebaseMainContext: () => boolean,
+		private readonly rebaseMainContext: () => void,
+		private readonly rebaseBlockReason: () => string | undefined,
+		private readonly rebaseDetachCount: () => number,
 		private readonly interrupt: () => void,
 	) {}
 
 	handleInput(data: string): void {
 		if (matchesKey(data, "ctrl+x") && isLiveAgent(this.agent)) {
-			this.confirmingDetach = false;
+			this.confirmation.cancel();
 			this.interrupt();
 			this.tui.requestRender();
 			return;
 		}
 		if (this.composer) {
-			this.confirmingDetach = false;
+			this.confirmation.cancel();
 			this.composer.handleInput(data);
 			this.tui.requestRender();
 			return;
@@ -181,7 +192,7 @@ export class AgentViewer implements Component {
 			this.requestDetach();
 			return;
 		}
-		this.confirmingDetach = false;
+		if (!matchesKey(data, "r")) this.confirmation.cancel();
 		if (matchesKey(data, "escape") || matchesKey(data, "q")) {
 			this.done("hide");
 			return;
@@ -194,11 +205,29 @@ export class AgentViewer implements Component {
 			this.copyResponse();
 			return;
 		}
-		if (matchesKey(data, "j") && this.canJoinMainContext()) {
-			this.joinMainContext();
+		if (matchesKey(data, "s") && this.canSquashMainContext()) {
+			this.squashMainContext();
 			this.tui.requestRender();
 			return;
 		}
+		if (matchesKey(data, "r")) {
+			if (this.canRebaseMainContext()) {
+				if (this.rebaseDetachCount() > 0 && !this.confirmation.press("rebase")) {
+					this.tui.requestRender();
+					return;
+				}
+				// Close the overlay: the payoff is the rebased conversation now sitting in the main transcript.
+				this.rebaseMainContext();
+				this.done("hide");
+				return;
+			}
+			this.confirmation.cancel();
+			const reason = this.rebaseBlockReason();
+			if (reason) {
+				this.showRebaseWarning(`Can't rebase: ${reason}`);
+				return;
+			}
+		}
 		const viewport = this.viewportHeight();
 		const maxScroll = Math.max(
 			0,
@@ -206,7 +235,7 @@ export class AgentViewer implements Component {
 		);
 		if (matchesKey(data, "up") || matchesKey(data, "k"))
 			this.scrollOffset = Math.max(0, this.scrollOffset - 1);
-		else if (matchesKey(data, "down"))
+		else if (matchesKey(data, "down") || matchesKey(data, "j"))
 			this.scrollOffset = Math.min(maxScroll, this.scrollOffset + 1);
 		else if (matchesKey(data, "pageUp") || matchesKey(data, "shift+up"))
 			this.scrollOffset = Math.max(0, this.scrollOffset - viewport);
@@ -290,6 +319,18 @@ export class AgentViewer implements Component {
 						composeHint,
 				),
 			);
+		} else if (this.confirmation.isArmedOn("rebase")) {
+			const detachCount = this.rebaseDetachCount();
+			lines.push(
+				row(
+					th.fg(
+						"warning",
+						`⚠ Rebase will detach ${detachCount} other agent session${detachCount === 1 ? "" : "s"}. r again to confirm`,
+					),
+				),
+			);
+		} else if (this.rebaseWarning) {
+			lines.push(row(th.fg("warning", `⚠ ${this.rebaseWarning}`)));
 		} else {
 			const scrollPct =
 				content.length <= viewport
@@ -306,13 +347,14 @@ export class AgentViewer implements Component {
 					this.justCopied ? th.fg("success", "✓ copied") : th.fg("dim", "c copy"),
 					th.fg("dim", "↑↓ scroll"),
 					th.fg("dim", "PgUp/PgDn"),
-					this.canJoinMainContext() ? th.fg("dim", "j join") : "",
+					this.canSquashMainContext() ? th.fg("dim", "s squash") : "",
+					this.canRebaseMainContext() ? th.fg("dim", "r rebase") : "",
 					isLiveAgent(this.agent) ? th.fg("dim", "Ctrl+x interrupt") : "",
 					mainContext ? th.fg("dim", mainContext) : "",
 					isLiveAgent(this.agent) ? th.fg("dim", "Esc hide") : "",
 					th.fg(
-						this.confirmingDetach ? "error" : "dim",
-						this.confirmingDetach ? "d again to confirm" : "d detach",
+						this.confirmation.isArmedOn("detach") ? "error" : "dim",
+						this.confirmation.isArmedOn("detach") ? "d again to confirm" : "d detach",
 					),
 				].filter(Boolean),
 			);
@@ -326,12 +368,22 @@ export class AgentViewer implements Component {
 
 	dispose(): void {}
 
+	/** Surface why r did nothing, in the footer, for a few seconds. Memory-only, like `✓ copied`. */
+	private showRebaseWarning(warning: string): void {
+		this.rebaseWarning = warning;
+		if (this.rebaseWarningTimer) clearTimeout(this.rebaseWarningTimer);
+		this.rebaseWarningTimer = setTimeout(() => {
+			this.rebaseWarning = undefined;
+			this.tui.requestRender();
+		}, CONFIRMATION_WINDOW_MS);
+		this.tui.requestRender();
+	}
+
 	private requestDetach(): void {
-		if (this.confirmingDetach) {
+		if (this.confirmation.press("detach")) {
 			this.done("detach");
 			return;
 		}
-		this.confirmingDetach = true;
 		this.tui.requestRender();
 	}