@giladbarnea/pi-user-agents 0.0.3 → 0.0.5

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,43 @@ 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.
+
+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. `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.
+
+The file itself appears on the child's first assistant message (`_persist` defers until then). An agent dispatched with `-i` that never answers therefore leaves nothing behind, while an agent that inherited context has a file immediately.
+
+## 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; squashing and session shutdown deliberately do not announce.
+
 ## Runtime sharing
 
 Child agent sessions share the parent's `ModelRuntime` instance. This is critical because extension-registered providers (like `claude-bridge`) use a global `Symbol.for` dedup guard — they register once per process and skip subsequent loads. A child session with its own fresh runtime would never receive the provider, leaving it without auth for bridge-backed models.

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,34 +77,56 @@ 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 disposal. In fact, nothing disposes an agent except you: pressing `x` 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
+
+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
+```
 
-### 4. Join — or don't
+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. 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
@@ -91,11 +136,21 @@ 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
 
@@ -104,7 +159,7 @@ Everything goes through one command: `/agent [options] <task>`.
 | 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`, … |
 
@@ -113,23 +168,33 @@ Everything goes through one command: `/agent [options] <task>`.
 | Editor | `←` / `↓` | Focus the agents widget |
 | Widget | `↑` `↓` · `Enter` | Select an agent · open its overlay |
 | Widget / overlay | `Ctrl+x` | Interrupt the current turn (agent stays alive) |
-| Widget / overlay | `x` `x` | Dispose the agent (twice to confirm) |
+| 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
 
-- Result cards persist across session reloads; live agent sessions don't. After a reload you keep every card, not the steerable sessions.
 - 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] 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 mechanism, 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,
@@ -32,7 +34,7 @@ import {
 } from "./tool-render/index.js";
 
 export type ViewableAgent = RunningAgent | CompletedAgent;
-export type AgentViewerAction = "hide" | "dispose";
+export type AgentViewerAction = "hide" | "detach";
 
 export type ActivityDescription = {
 	text: string;
@@ -141,7 +143,7 @@ function truncateMiddle(
 
 const VIEWER_CHROME_LINES = 6;
 const VIEWER_MIN_VIEWPORT = 3;
-const VIEWER_HEIGHT_PCT = 70;
+const VIEWER_HEIGHT_PCT = 85;
 
 /** Focus-capturing overlay that shows an agent's live or finished response. */
 export class AgentViewer implements Component {
@@ -149,7 +151,12 @@ export class AgentViewer implements Component {
 	private autoScroll = true;
 	private lastWidth = 0;
 	private justCopied = false;
-	private confirmingDispose = 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,29 +166,33 @@ 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.confirmingDispose = false;
+			this.confirmation.cancel();
 			this.interrupt();
 			this.tui.requestRender();
 			return;
 		}
 		if (this.composer) {
-			this.confirmingDispose = false;
+			this.confirmation.cancel();
 			this.composer.handleInput(data);
 			this.tui.requestRender();
 			return;
 		}
-		if (matchesKey(data, "x")) {
-			this.requestDispose();
+		if (matchesKey(data, "d")) {
+			this.requestDetach();
 			return;
 		}
-		this.confirmingDispose = 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);
@@ -253,6 +282,7 @@ export class AgentViewer implements Component {
 			renderAgentContextMeter(this.agent, th),
 			th.fg("dim", status),
 			...stats.map((stat) => th.fg("dim", stat)),
+			th.fg("dim", this.agent.sessionId),
 		]
 			.filter(Boolean)
 			.join(` ${th.fg("dim", "·")} `);
@@ -289,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
@@ -305,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.confirmingDispose ? "error" : "dim",
-						this.confirmingDispose ? "x again to confirm" : "x dispose",
+						this.confirmation.isArmedOn("detach") ? "error" : "dim",
+						this.confirmation.isArmedOn("detach") ? "d again to confirm" : "d detach",
 					),
 				].filter(Boolean),
 			);
@@ -325,12 +368,22 @@ export class AgentViewer implements Component {
 
 	dispose(): void {}
 
-	private requestDispose(): void {
-		if (this.confirmingDispose) {
-			this.done("dispose");
+	/** 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.confirmation.press("detach")) {
+			this.done("detach");
 			return;
 		}
-		this.confirmingDispose = true;
 		this.tui.requestRender();
 	}
 

package/command-line.ts

@@ -57,7 +57,7 @@ export type AgentSemanticToken = {
 
 export type AgentArgumentScan = {
 	isolate: boolean;
-	context: boolean;
+	squash: boolean;
 	forwardedArgs: string[];
 	/** Ordered, non-overlapping semantic tokens over the argument text. Prose stays untokenized. */
 	tokens: AgentSemanticToken[];
@@ -115,12 +115,12 @@ export const AGENT_OPTIONS: readonly AgentOptionDefinition[] = [
 		description: "Start without parent-session context",
 	},
 	{
-		semanticId: "context",
-		names: ["-j", "--join"],
+		semanticId: "squash",
+		names: ["-s", "--squash"],
 		role: "extension",
 		arity: "boolean",
 		autocomplete: true,
-		description: "Join the completed result into the main agent context",
+		description: "Squash the completed result into the main agent context",
 	},
 	{
 		semanticId: "provider",
@@ -360,7 +360,7 @@ export function scanAgentArguments(
 	const tokens: AgentSemanticToken[] = [];
 	const forwardedArgs: string[] = [];
 	let isolate = false;
-	let context = false;
+	let squash = false;
 	let blocked: AgentSemanticToken | undefined;
 	let consumedOption = false;
 	let position = 0;
@@ -393,8 +393,8 @@ export function scanAgentArguments(
 			}
 		} else if (option.semanticId === "isolate") {
 			isolate = true;
-		} else if (option.semanticId === "context") {
-			context = true;
+		} else if (option.semanticId === "squash") {
+			squash = true;
 		} else if (option.arity === "value") {
 			forwardedArgs.push(option.forwardName ?? token);
 			const read = readValueSpan(args, position);
@@ -427,7 +427,7 @@ export function scanAgentArguments(
 	}
 	const scan: AgentArgumentScan = {
 		isolate,
-		context,
+		squash,
 		forwardedArgs,
 		tokens,
 		proseStart,
@@ -487,11 +487,11 @@ export function parseAgentCommand(args: string, command: AgentCommandName): Pars
 	}
 	if (!scan.prose.trim())
 		throw new Error(
-			`Usage: /${command} [pi options] [-m MODELNAME] [-i|--isolate] [-j|--join] "<task>"`,
+			`Usage: /${command} [pi options] [-m MODELNAME] [-i|--isolate] [-s|--squash] "<task>"`,
 		);
 	return {
 		isolate: scan.isolate,
-		context: scan.context,
+		squash: scan.squash,
 		forwardedArgs: scan.forwardedArgs,
 		task: scan.task,
 		warnings: scan.warnings,

package/index.ts

@@ -3,16 +3,27 @@ import type {
 	MessageEndEventResult,
 } from "@earendil-works/pi-coding-agent";
 import { registerAgentAutocomplete } from "./autocomplete.js";
-import { handleAgentCommand } from "./runner.js";
-import type { AgentCommandDetails, ExtensionAPI, RunningAgent } from "./shared.js";
-import { MESSAGE_TYPE } from "./shared.js";
+import { createRebaseDelivery, handleAgentCommand } from "./runner.js";
+import type {
+	AgentCommandDetails,
+	DetachedEntryData,
+	ExtensionAPI,
+	ExtensionCommandContext,
+	RunningAgent,
+} from "./shared.js";
+import { DETACHED_ENTRY_TYPE, MESSAGE_TYPE } from "./shared.js";
 import { registerUserAgentRenderer } from "./transcript.js";
 import { UserAgentWidget } from "./widget.js";
 
 export default function userAgent(pi: ExtensionAPI): void {
 	const runningAgents = new Set<RunningAgent>();
-	const widget = new UserAgentWidget(runningAgents, (message) =>
-		pi.sendMessage(message, { triggerTurn: true }),
+	// The session every agent was dispatched from; rebase fast-forwards onto it.
+	let mainSessionContext: ExtensionCommandContext | undefined;
+	const widget = new UserAgentWidget(
+		runningAgents,
+		(message) => pi.sendMessage(message, { triggerTurn: true }),
+		(sessionId) => pi.appendEntry<DetachedEntryData>(DETACHED_ENTRY_TYPE, { sessionId }),
+		createRebaseDelivery(pi, () => mainSessionContext),
 	);
 	let shuttingDown = false;
 	let nextAgentNumber = 0;
@@ -20,12 +31,13 @@ export default function userAgent(pi: ExtensionAPI): void {
 	registerUserAgentRenderer(pi);
 	registerAgentAutocomplete(pi);
 
-	pi.on("message_end", (event) => confirmMainContextJoin(event, widget));
+	pi.on("message_end", (event) => confirmMainContextSquash(event, widget));
 
 	pi.registerCommand("agent", {
 		description:
 			"Run a background SDK agent with current session context; forwards pi CLI options like --thinking (-i/--isolate for none)",
 		handler: async (args, ctx) => {
+			mainSessionContext = ctx;
 			await handleAgentCommand(
 				pi,
 				runningAgents,
@@ -56,19 +68,19 @@ export default function userAgent(pi: ExtensionAPI): void {
 	});
 }
 
-export function confirmMainContextJoin(
+export function confirmMainContextSquash(
 	event: MessageEndEvent,
 	widget: UserAgentWidget,
 ): MessageEndEventResult | undefined {
 	if (event.message.role !== "custom" || event.message.customType !== MESSAGE_TYPE) return;
 	const details = event.message.details as AgentCommandDetails | undefined;
-	if (!details?.agentId || details.mainContextState !== "will-join") return;
-	widget.confirmMainContextJoin(details.agentId);
-	details.mainContextState = "joined";
+	if (!details?.agentId || details.mainContextState !== "will-squash") return;
+	widget.confirmMainContextSquash(details.agentId);
+	details.mainContextState = "squashed";
 	return {
 		message: {
 			...event.message,
-			details: { ...details, mainContextState: "joined" },
+			details: { ...details, mainContextState: "squashed" },
 		},
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giladbarnea/pi-user-agents",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Run, view, and control background Pi agents.",
   "keywords": [
     "pi-package",