pum-agent 0.2.22-beta.1 → 0.2.24-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pum-agent",
-  "version": "0.2.22-beta.1",
+  "version": "0.2.24-beta.1",
   "description": "A compact terminal coding agent powered by pi and OpenTUI.",
   "license": "MIT",
   "type": "module",

package/src/animation.tsx

@@ -285,13 +285,16 @@ export function AnimationProvider({
   );
   const workingRuleCycleWidth = useCallback(() => workingCycleWidth.current, []);
 
-  return (
-    <ClockContext.Provider
-      value={{ subscribe, workingElapsed, workingRuleCycleWidth, enabled }}
-    >
-      {children}
-    </ClockContext.Provider>
+  // A fresh object here would be a changed context value on every render of the
+  // app, and React answers that by walking the whole tree below the provider to
+  // find consumers. With a long transcript that walk is the largest part of the
+  // cost of one keystroke, so the value keeps its identity while its parts do.
+  const clock = useMemo(
+    () => ({ subscribe, workingElapsed, workingRuleCycleWidth, enabled }),
+    [subscribe, workingElapsed, workingRuleCycleWidth, enabled],
   );
+
+  return <ClockContext.Provider value={clock}>{children}</ClockContext.Provider>;
 }
 
 /** Exported for the test that guards the run-coalescing loop below. */

package/src/app.tsx

@@ -3,13 +3,14 @@ import {
   stripAnsiSequences,
   type PasteEvent,
   type ScrollBoxRenderable,
+  type SyntaxStyle,
   type TextareaRenderable,
 } from "@opentui/core";
 import { randomUUID } from "node:crypto";
 import { useKeyboard, usePaste, useRenderer, useTerminalDimensions } from "@opentui/react";
 import { getSupportedThinkingLevels, type Model } from "@earendil-works/pi-ai";
 import type { AgentSession, BashOperations, ModelRuntime } from "@earendil-works/pi-coding-agent";
-import { Component, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import { Component, memo, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from "react";
 import {
   AnimationProvider,
   supportsTrueColor,
@@ -87,7 +88,11 @@ import {
   webSearch,
   withSearchRoute,
 } from "./web-search";
-import { isCommandInput, matchingCommands, moveCommandSelection } from "./commands";
+import {
+  isCommandInput,
+  matchingCommandsForTarget,
+  moveCommandSelection,
+} from "./commands";
 import { truncateStatusText } from "./status-metadata";
 import { modeLineLabels } from "./mode-line";
 import { RULE_LABEL_TRAILING_RULE_COLUMNS } from "./goal-line";
@@ -114,6 +119,7 @@ import {
 } from "./session-settings";
 import { AfkController, type AfkStatus } from "./afk";
 import { parseAfkCommand } from "./afk-command";
+import { parseBackgroundCommand } from "./background-command";
 import {
   afkAnswerFailureText,
   buildAfkTask,
@@ -262,9 +268,20 @@ import {
   projectPendingTranscriptLines,
   projectTranscriptLines,
   transcriptOutputMode,
+  type TranscriptOutputMode,
 } from "./transcript-output";
 import type { MinimalTranscriptLine } from "./output-minimal";
 import { heldTranscriptLines, type DwellMemory } from "./transcript-dwell";
+import {
+  atWindowBottom,
+  atWindowTop,
+  clampWindowStart,
+  extendedWindowStart,
+  nearWindowTop,
+  tailWindowStart,
+  transcriptWindowRows,
+  windowStartForRow,
+} from "./transcript-window";
 
 type Stream = { kind: "assistant" | "thinking"; text: string } | null;
 type Transcript = { lines: Line[]; stream: Stream; pending: PendingLine[] };
@@ -291,6 +308,18 @@ function projectedLineRawText(line: MinimalTranscriptLine): string {
 
 const QUIT_WINDOW_MS = 2000;
 const MAX_INPUT_ROWS = 8;
+/** How long a scroll to a row waits between tries for React to draw it. */
+const ROW_DRAW_RETRY_MS = 30;
+/**
+ * How many of those tries it makes before it gives up.
+ *
+ * A busy machine with a long session can take most of a second to draw a row
+ * that had to be mounted first, and a jump that gives up before then looks to
+ * the reader exactly like a dead key.
+ */
+const ROW_DRAW_TRIES = 30;
+/** Frames a scroll correction waits for its rows before it gives up. */
+const ANCHOR_FRAME_BUDGET = 30;
 /** Keys that move around without changing the text. */
 const NAV_KEYS = new Set(["up", "down", "left", "right", "home", "end", "pageup", "pagedown"]);
 
@@ -391,6 +420,91 @@ export function promptPlaceholder(options: {
 /** A blank row. An empty <text> measures to nothing, so this needs a height. */
 const Gap = () => <box style={{ height: 1, flexShrink: 0 }} />;
 
+/**
+ * One rendered transcript row.
+ *
+ * Memoized on purpose. The transcript is a child of the same component that
+ * holds the prompt draft, so without this every keystroke re-rendered every
+ * row, and the cost of a keypress grew with the length of the session. Each
+ * prop here must therefore stay identity-stable while the row is unchanged:
+ * pass the row index and one shared handler rather than a fresh closure.
+ */
+const TranscriptRow = memo(function TranscriptRow({
+  theme,
+  syntaxStyle,
+  line,
+  index,
+  selected,
+  expanded,
+  outputMode,
+  workingCaret,
+  gapBefore,
+  news,
+  onDisclosure,
+}: {
+  theme: Theme;
+  syntaxStyle: SyntaxStyle;
+  line: MinimalTranscriptLine;
+  index: number;
+  selected: boolean;
+  expanded: boolean;
+  outputMode: TranscriptOutputMode;
+  workingCaret: boolean;
+  gapBefore: boolean;
+  news?: "seen" | "unseen";
+  onDisclosure: (index: number) => void;
+}) {
+  const onDisclosureClick = () => onDisclosure(index);
+  const row =
+    line.kind === "tool-summary" ? (
+      <ActivitySummaryLine
+        theme={theme}
+        syntaxStyle={syntaxStyle}
+        summary={line}
+        expanded={expanded}
+        outputMode={outputMode}
+        onDisclosureClick={onDisclosureClick}
+      />
+    ) : line.kind === "tool" ? (
+      <ToolLine
+        theme={theme}
+        syntaxStyle={syntaxStyle}
+        call={line.call}
+        workingCaret={workingCaret}
+        outputMode={outputMode}
+        expanded={expanded}
+        onDisclosureClick={onDisclosureClick}
+      />
+    ) : line.kind === "agent-message" ? (
+      <AgentMessageLine theme={theme} syntaxStyle={syntaxStyle} line={line} />
+    ) : line.kind === "goal-review" ? (
+      <GoalReviewLine theme={theme} line={line} />
+    ) : (
+      <TextLine
+        theme={theme}
+        syntaxStyle={syntaxStyle}
+        role={line.role as Role}
+        text={line.text}
+        workingCaret={workingCaret}
+        news={news}
+      />
+    );
+  return (
+    <box
+      id={`transcript-line-${index}`}
+      style={{
+        flexDirection: "column",
+        width: "100%",
+        flexShrink: 0,
+        backgroundColor: selected ? theme.selectionBg : "transparent",
+      }}
+    >
+      {gapBefore ? <Gap /> : null}
+      {row}
+    </box>
+  );
+});
+
 type RenderErrorBoundaryProps = {
   theme: Theme;
   label: string;
@@ -808,6 +922,12 @@ export function App({
   const transcriptCursorRef = useRef(0);
   const [detailOverrides, setDetailOverrides] = useState<Map<string, boolean>>(() => new Map());
   const detailOverridesRef = useRef(detailOverrides);
+  // Disclosure clicks reach the memoized rows through one stable function, so a
+  // re-render of the app cannot invalidate every row by handing it a new one.
+  const clickTranscriptDisclosureRef = useRef<(index: number) => void>(() => {});
+  const onTranscriptDisclosure = useRef(
+    (index: number) => clickTranscriptDisclosureRef.current(index),
+  ).current;
   // Mirrors settings for update(): a keypress or an async .then can fire a
   // second update before React commits the first, so update() must build the
   // next value from the latest pending settings, not the render closure.
@@ -924,9 +1044,13 @@ export function App({
   const todoVisible = todoOpen
     && !settingsOpen && !helpOpen && !historyOpen && !statsOpen && !agentSelectorOpen
     && !triggersOpen && !loginOpen && !newsOpen && !visibleQuestionnaire && !spawnPreview;
-  const visibleTx = transcriptForThinkingVisibility(
-    activeAgent?.transcript ?? tx,
-    settings.showThinking,
+  // Memoized because the filtered result is a new object every call whenever
+  // the transcript holds reasoning. That new identity would re-run the dwell
+  // and projection passes below on every render, keystrokes included.
+  const sourceTx = activeAgent?.transcript ?? tx;
+  const visibleTx = useMemo(
+    () => transcriptForThinkingVisibility(sourceTx, settings.showThinking),
+    [sourceTx, settings.showThinking],
   );
   const outputMode = transcriptOutputMode(settings);
   const showAgentMessages = settings.showAgentMessages !== false;
@@ -958,10 +1082,79 @@ export function App({
     () => projectTranscriptLines(held.lines, outputMode, showAgentMessages),
     [held, outputMode, showAgentMessages],
   );
+  // The rows as they are drawn. A callback that has to find a row needs these,
+  // not the transcript lines: folding and hidden kinds mean the two lists have
+  // different lengths, so a line index is not a row index.
+  const visibleLinesRef = useRef(visibleLines);
+  visibleLinesRef.current = visibleLines;
   const visiblePending = useMemo(
     () => projectPendingTranscriptLines(visibleTx.pending, showAgentMessages),
     [visibleTx.pending, showAgentMessages],
   );
+
+  // Which rows are mounted. See `transcript-window.ts` for the rules; these
+  // three refs are the state they run on.
+  //
+  // The start is derived during render rather than stored in state, so a
+  // resumed session mounts its tail on the first render instead of mounting
+  // everything and then trimming. Both derivations are idempotent, so a
+  // repeated render cannot walk the window anywhere.
+  const transcriptWindowStartRef = useRef(0);
+  /** True while the last row is on screen. Only then may the window advance. */
+  const transcriptAtBottomRef = useRef(true);
+  /** Lowest start the reader has asked for. Released on returning to the end. */
+  const transcriptWindowFloorRef = useRef(Number.POSITIVE_INFINITY);
+  /**
+   * The row to hold still while history is mounted above it.
+   *
+   * Rows appearing above the viewport would otherwise push the reader's place
+   * down the screen. `contentOffset` is where the row sat before the mount, so
+   * the restore can tell a laid-out frame from one that still shows the old
+   * tree, and `viewportOffset` is the screen position to put it back at.
+   */
+  const transcriptWindowAnchorRef = useRef<
+    { index: number; viewportOffset: number; contentOffset: number; frames: number } | null
+  >(null);
+  /**
+   * Did the reader just finish dragging the transcript somewhere?
+   *
+   * Only a drag raises this: every scroll the app makes is a property
+   * assignment, which raises no mouse event, and a wheel raises a different
+   * event. The window needs the difference. A drag that ends against the top
+   * of the mounted rows is a reader asking for the history above them, while a
+   * reveal that lands a row in the same place is asking for nothing.
+   */
+  /** Reveals still waiting for React to draw the row they asked for. */
+  const transcriptRevealsRef = useRef(0);
+  const transcriptReaderDragRef = useRef(false);
+  const onTranscriptReaderDrag = useRef(() => {
+    transcriptReaderDragRef.current = true;
+  }).current;
+  const transcriptWindowRowCount = transcriptWindowRows(height);
+  const transcriptWindowRowsRef = useRef(transcriptWindowRowCount);
+  transcriptWindowRowsRef.current = transcriptWindowRowCount;
+  // Another agent's transcript is another conversation, shown from its end. Its
+  // scrollbox is a new one, so none of the positions collected for the previous
+  // view mean anything against it.
+  const transcriptWindowAgentRef = useRef(activeAgentId);
+  if (transcriptWindowAgentRef.current !== activeAgentId) {
+    transcriptWindowAgentRef.current = activeAgentId;
+    transcriptAtBottomRef.current = true;
+    transcriptWindowFloorRef.current = Number.POSITIVE_INFINITY;
+    transcriptWindowAnchorRef.current = null;
+  }
+  const transcriptWindowStart = clampWindowStart(
+    Math.min(
+      transcriptAtBottomRef.current
+        ? tailWindowStart(visibleLines.length, transcriptWindowRowCount)
+        : transcriptWindowStartRef.current,
+      transcriptWindowFloorRef.current,
+    ),
+    visibleLines.length,
+  );
+  transcriptWindowStartRef.current = transcriptWindowStart;
+  /** Bumped to re-render when the reader changes the window from a callback. */
+  const [, setTranscriptWindowTick] = useState(0);
   useLayoutEffect(() => {
     const next = Math.max(0, Math.min(transcriptCursorRef.current, visibleLines.length - 1));
     transcriptCursorRef.current = next;
@@ -1006,11 +1199,14 @@ export function App({
     1,
     width - 2 - promptRightColumns - visibleInputHint.length,
   );
-  // Slash commands only exist for the main agent, so a subagent view neither
-  // shows them nor completes them into a message to the child.
-  const commandSuggestions = shellMode || activeAgentId || stashOpen || commandSuggestionsDismissed
+  // Most slash commands belong to main. A selected mutable agent can still own
+  // a descendant started with /background, so expose only that command there.
+  const commandSuggestions = shellMode || stashOpen || commandSuggestionsDismissed
     ? []
-    : matchingCommands(commandInput).slice(0, 5);
+    : matchingCommandsForTarget(
+      commandInput,
+      activeAgentId ? "subagent" : "main",
+    ).slice(0, 5);
   const pathSuggestions = (!shellMode && activeAgentId) || stashOpen || commandSuggestionsDismissed
     || isCommandInput(commandInput)
     || !shouldAutoShowPathCompletions(commandInput, inputCursorOffset)
@@ -1996,6 +2192,96 @@ export function App({
     };
   }, [renderer]);
 
+  // Drive the mounted window off the scroll position. The frame is the only
+  // place both the position and the laid-out rows are known, and nothing
+  // renders while the app is idle, so this costs nothing then. Everything it
+  // reads is a ref, so the handler installed on mount stays correct.
+  useEffect(() => {
+    const onFrame = () => {
+      const scroll = transcriptScrollRef.current;
+      if (!scroll || scroll.isDestroyed) return;
+      const viewportHeight = scroll.viewport.height;
+
+      // A drag that ends against the top of the mounted rows asks for the
+      // history above them. One window per gesture never reaches the start of a
+      // long session, and every step holds the reader’s place, so the view
+      // does not move and the first message stays out of reach. Mount the rest
+      // instead, and leave the reader on it. This runs before the correction
+      // below and drops it: the place to hold is the place they just left.
+      if (!atWindowTop(scroll.scrollTop)) transcriptReaderDragRef.current = false;
+      else if (transcriptReaderDragRef.current && transcriptWindowStartRef.current > 0) {
+        transcriptReaderDragRef.current = false;
+        transcriptWindowAnchorRef.current = null;
+        ensureTranscriptRowMounted(0);
+        return;
+      }
+
+      // Put the reader's row back under the rows that just mounted above it.
+      const anchor = transcriptWindowAnchorRef.current;
+      if (anchor) {
+        const row = scroll.findDescendantById(`transcript-line-${anchor.index}`);
+        const contentOffset = row ? row.y - scroll.content.y : anchor.contentOffset;
+        if (row && contentOffset !== anchor.contentOffset) {
+          const target = topAnchorScrollTop(
+            contentOffset - anchor.viewportOffset,
+            scroll.scrollHeight,
+            viewportHeight,
+          );
+          // scrollBy, not scrollTop: it is the path that marks the scroll as
+          // manual, and without that sticky-to-bottom drags the reader back to
+          // the end of a transcript they are reading the middle of.
+          if (target !== scroll.scrollTop) scroll.scrollBy({ x: 0, y: target - scroll.scrollTop });
+          transcriptWindowAnchorRef.current = null;
+        } else if (anchor.frames++ > ANCHOR_FRAME_BUDGET) {
+          // The rows never arrived. Drop the anchor rather than hold a scroll
+          // correction that would fire against some later, unrelated layout.
+          transcriptWindowAnchorRef.current = null;
+        }
+      }
+
+      const atBottom = atWindowBottom(scroll.scrollTop, scroll.scrollHeight, viewportHeight);
+      transcriptAtBottomRef.current = atBottom;
+      if (atBottom) {
+        // A reveal that is still waiting for its row holds the window. The view
+        // does not leave the end until it scrolls, so releasing here would
+        // unmount the very row it just asked for, every frame until it gave up.
+        if (transcriptRevealsRef.current > 0) return;
+        // Back at the end: the window may shrink to its tail again. Releasing
+        // the floor only changes a ref, so the render that acts on it has to be
+        // asked for. Once per return to the end, never on every frame.
+        if (transcriptWindowFloorRef.current !== Number.POSITIVE_INFINITY) {
+          transcriptWindowFloorRef.current = Number.POSITIVE_INFINITY;
+          setTranscriptWindowTick((tick) => tick + 1);
+        }
+        return;
+      }
+      if (transcriptWindowStartRef.current <= 0) return;
+      if (!nearWindowTop(scroll.scrollTop, viewportHeight)) return;
+      // One mount at a time. The anchor clears once the rows are laid out.
+      if (transcriptWindowAnchorRef.current) return;
+
+      const current = transcriptWindowStartRef.current;
+      const next = extendedWindowStart(current, transcriptWindowRowsRef.current);
+      if (next === current) return;
+      const row = scroll.findDescendantById(`transcript-line-${current}`);
+      transcriptWindowAnchorRef.current = row
+        ? {
+          index: current,
+          viewportOffset: row.y - scroll.viewport.y,
+          contentOffset: row.y - scroll.content.y,
+          frames: 0,
+        }
+        : null;
+      transcriptWindowStartRef.current = next;
+      transcriptWindowFloorRef.current = Math.min(transcriptWindowFloorRef.current, next);
+      setTranscriptWindowTick((tick) => tick + 1);
+    };
+    renderer.on("frame", onFrame);
+    return () => {
+      renderer.off("frame", onFrame);
+    };
+  }, [renderer]);
+
   // Hosted web searches are not pi tool calls, so they arrive out of band.
   useEffect(() => {
     return observeSearchCalls(session.sessionId, (call) => {
@@ -2754,19 +3040,36 @@ export function App({
         }
       }
     }
-    if (targetIndex < 0) return;
+    const targetLine = lines[targetIndex];
+    if (!targetLine) {
+      // A stored answer whose text no longer appears in the session, after a
+      // compaction for example, has no row to jump to, and neither has the
+      // prompt that asked for it. Say so: leaving the popup open makes the key
+      // look broken.
+      newsOpenRef.current = false;
+      setNewsOpen(false);
+      append({
+        kind: "text",
+        role: "error",
+        text: "news: that message is not in the transcript any more",
+      });
+      queueMicrotask(() => inputRef.current?.focus());
+      return;
+    }
 
     if (activeAgentIdRef.current !== requesterAgentId && !selectAgentView(requesterAgentId)) return;
     newsOpenRef.current = false;
     setNewsOpen(false);
-    const scrollToTarget = () => {
-      const transcript = transcriptScrollRef.current;
-      if (!transcript) return;
-      transcript.scrollTop = 0;
-      transcript.scrollChildIntoView(`transcript-line-${targetIndex}`);
-    };
-    queueMicrotask(scrollToTarget);
-    setTimeout(scrollToTarget, 30);
+    // Rows are the projected lines: successful tool calls fold into one
+    // activity row and hidden kinds drop out, so the line has to be matched to
+    // the row that draws it. The match runs at scroll time, which is also
+    // after a switch to another agent has drawn that agent’s rows.
+    // The answer can be anywhere in the session, including far above the rows
+    // that are mounted, so this asks for the row and waits for it.
+    scrollToTranscriptRow(
+      () => visibleLinesRef.current.indexOf(targetLine as MinimalTranscriptLine),
+      { fromTop: true },
+    );
   };
 
   const toggleCurrentNewsRead = () => {
@@ -3551,6 +3854,99 @@ export function App({
     return true;
   };
 
+  const appendRequesterLine = (requesterAgentId: string | null, line: Line) => {
+    if (requesterAgentId === null || !subagentManager.getAgent(requesterAgentId)) {
+      appendMainLine(line);
+    } else {
+      subagentManager.appendAgentLine(requesterAgentId, line);
+    }
+  };
+
+  /** Start a fresh managed child without occupying or steering the requester. */
+  const runBackgroundCommand = (
+    text: string,
+    requesterAgentId: string | null,
+    draftText = text,
+  ): boolean => {
+    const command = parseBackgroundCommand(text);
+    if (!command) return false;
+    const requesterKey = requesterAgentId ?? "main";
+    const restoreDraft = () => {
+      if (activeAgentIdRef.current !== requesterAgentId) {
+        if (!(viewDrafts.current.get(requesterKey) ?? "")) {
+          viewDrafts.current.set(requesterKey, draftText);
+        }
+        return;
+      }
+      if (!(inputRef.current?.plainText ?? "")) {
+        viewDrafts.current.set(requesterKey, draftText);
+        setEditorText(draftText, draftText.length, true);
+      }
+    };
+    if (command.kind === "error") {
+      setEditorText(draftText, draftText.length, true);
+      appendRequesterLine(requesterAgentId, {
+        kind: "text",
+        role: "error",
+        text: command.message,
+      });
+      return true;
+    }
+    if (sessionSwitchRef.current) {
+      setEditorText(draftText, draftText.length, true);
+      appendRequesterLine(requesterAgentId, {
+        kind: "text",
+        role: "error",
+        text: "wait for the session change to finish before starting a background agent",
+      });
+      return true;
+    }
+    if (relocatingRef.current || pendingRelocationRef.current) {
+      setEditorText(draftText, draftText.length, true);
+      appendRequesterLine(requesterAgentId, {
+        kind: "text",
+        role: "error",
+        text: "wait for the worktree move to finish before starting a background agent",
+      });
+      return true;
+    }
+
+    setEditingStash(null);
+    viewDrafts.current.set(requesterKey, "");
+    setEditorText("");
+    histCursor.current = null;
+    draft.current = "";
+    void (async () => {
+      // The registry and every child session belong to the active main session.
+      // Bind it before spawning so an App-start race cannot persist elsewhere.
+      await subagentManager.bindMainSession(session.sessionManager, cwd);
+      const spawned = requesterAgentId === null
+        ? await subagentManager.spawnBackground({
+          task: command.prompt,
+          requesterAgentId: null,
+          modelId: `${session.agent.state.model.provider}/${session.agent.state.model.id}`,
+          thinkingLevel: String(session.agent.state.thinkingLevel),
+        })
+        : await subagentManager.spawnBackground({
+          task: command.prompt,
+          requesterAgentId,
+        });
+      appendRequesterLine(requesterAgentId, {
+        kind: "text",
+        role: "system",
+        text: `background agent started: ${spawned.name} (${spawned.id})\n${spawned.worktree.branch}\n${spawned.worktree.path}`,
+      });
+    })().catch((error) => {
+      appendRequesterLine(requesterAgentId, {
+        kind: "text",
+        role: "error",
+        text: `background agent could not start: ${String(error)}`,
+      });
+      restoreDraft();
+    });
+    return true;
+  };
+
   const submitPrompt = (value?: string, stashIndex?: number) => {
     // Read the selected agent from the ref, not the state. A view switch updates
     // the ref synchronously, but a switch-then-send in one input chunk runs
@@ -3578,6 +3974,26 @@ export function App({
 
     if (!promptText && attachments.length === 0 && pastedTexts.length === 0) return;
 
+    const backgroundCandidate = commandEligible ? parseBackgroundCommand(promptText) : null;
+    if (backgroundCandidate?.kind === "error") {
+      setEditorText(rawDisplayText, rawDisplayText.length, true);
+      appendRequesterLine(selectedAgentId, {
+        kind: "text",
+        role: "error",
+        text: backgroundCandidate.message,
+      });
+      return;
+    }
+    if (backgroundCandidate && (attachments.length > 0 || pastedTexts.length > 0)) {
+      setEditorText(rawDisplayText, rawDisplayText.length, true);
+      appendRequesterLine(selectedAgentId, {
+        kind: "text",
+        role: "error",
+        text: "/background accepts text only; remove image and pasted-text attachments",
+      });
+      return;
+    }
+
     // The main session is being replaced, so keep the draft rather than deliver
     // into a session that is about to be aborted and disposed.
     if (!selectedAgentId && sessionSwitchRef.current) {
@@ -3659,6 +4075,17 @@ export function App({
       return;
     }
 
+    // /background belongs to the selected transcript, unlike the main-only
+    // command router below, and must never become an ordinary child message.
+    if (
+      attachments.length === 0
+      && commandEligible
+      && runBackgroundCommand(promptText, selectedAgentId, rawDisplayText)
+    ) {
+      if (!selectedAgentId) appendCommandHistory();
+      return;
+    }
+
     // AFK is process-global, so it is intercepted above the child routing below.
     // Successful command handling still makes the entered command recallable.
     if (attachments.length === 0 && commandEligible && runAfkCommand(promptText)) {
@@ -4053,8 +4480,65 @@ export function App({
     } else queueMicrotask(() => inputRef.current?.focus());
   };
 
+  /**
+   * Put a row in the tree so it can be scrolled to.
+   *
+   * Only rows near the end are mounted, so anything that scrolls to a row has
+   * to ask for it first. The floor keeps it mounted: without one, the very next
+   * frame could decide the reader is still at the end and drop it again before
+   * React had rendered it.
+   */
+  const ensureTranscriptRowMounted = (index: number) => {
+    const next = windowStartForRow(transcriptWindowStartRef.current, index);
+    if (next >= transcriptWindowStartRef.current) return;
+    transcriptWindowStartRef.current = next;
+    transcriptWindowFloorRef.current = Math.min(transcriptWindowFloorRef.current, next);
+    setTranscriptWindowTick((tick) => tick + 1);
+  };
+
+  /**
+   * Scroll to a row once React has drawn it.
+   *
+   * A row that had to be mounted first is not in the tree at microtask time,
+   * and a long transcript can take several frames to draw it, so keep asking
+   * rather than asking once. `wanted` stops a walk that has moved on: the
+   * reader holding a key starts one of these per row, and the older ones must
+   * not drag the view back to where the walk began.
+   */
+  const scrollToTranscriptRow = (
+    resolve: () => number,
+    options: { fromTop?: boolean; wanted?: () => boolean } = {},
+  ) => {
+    transcriptRevealsRef.current++;
+    let tries = 0;
+    const done = () => {
+      transcriptRevealsRef.current = Math.max(0, transcriptRevealsRef.current - 1);
+    };
+    const reveal = () => {
+      if (options.wanted && !options.wanted()) return done();
+      const index = resolve();
+      const scroll = transcriptScrollRef.current;
+      if (scroll && index >= 0) {
+        // Asked for again on every try: the row is only held by the window
+        // while something wants it, and the frame that runs in between is free
+        // to decide the reader is at the end of the transcript.
+        ensureTranscriptRowMounted(index);
+        if (scroll.findDescendantById(`transcript-line-${index}`)) {
+          // From the top, the row lands on the first screen row instead of the
+          // last: `scrollChildIntoView` moves as little as it can.
+          if (options.fromTop) scroll.scrollTop = 0;
+          scroll.scrollChildIntoView(`transcript-line-${index}`);
+          return done();
+        }
+      }
+      if (tries++ < ROW_DRAW_TRIES) setTimeout(reveal, ROW_DRAW_RETRY_MS);
+      else done();
+    };
+    queueMicrotask(reveal);
+  };
+
   const revealTranscriptCursor = (index: number) => {
-    queueMicrotask(() => transcriptScrollRef.current?.scrollChildIntoView(`transcript-line-${index}`));
+    scrollToTranscriptRow(() => index, { wanted: () => transcriptCursorRef.current === index });
   };
 
   /**
@@ -4066,6 +4550,7 @@ export function App({
    * The layout runs after React commits, hence the second, later attempt.
    */
   const anchorTranscriptRow = (index: number) => {
+    ensureTranscriptRowMounted(index);
     const apply = () => {
       const scroll = transcriptScrollRef.current;
       const row = scroll?.findDescendantById(`transcript-line-${index}`);
@@ -4115,6 +4600,9 @@ export function App({
     selectTranscriptRow(index);
     toggleTranscriptDetail(index);
   };
+  // Rows are memoized, so the handler they receive has to keep one identity for
+  // the life of the app. The ref carries the current closure behind it.
+  clickTranscriptDisclosureRef.current = clickTranscriptDisclosure;
 
   const copyTranscriptRow = () => {
     const line = visibleLines[transcriptCursorRef.current];
@@ -4626,9 +5114,12 @@ export function App({
       isReturnKey && !hasCtrlForReturn && !hasShiftForReturn && !hasAltForReturn;
     const inputValue = inputRef.current?.plainText ?? "";
     const commandMatches =
-      shellModeRef.current || activeAgentIdRef.current || stashOpenRef.current || commandSuggestionsDismissedRef.current
+      shellModeRef.current || stashOpenRef.current || commandSuggestionsDismissedRef.current
         ? []
-        : matchingCommands(inputValue).slice(0, 5);
+        : matchingCommandsForTarget(
+          inputValue,
+          activeAgentIdRef.current ? "subagent" : "main",
+        ).slice(0, 5);
     const inputCursor = inputRef.current?.cursorOffset ?? inputValue.length;
     const pathMatches =
       (!shellModeRef.current && activeAgentIdRef.current)
@@ -4756,7 +5247,7 @@ export function App({
         queueMicrotask(() => inputRef.current?.focus());
         return;
       }
-      if (!activeAgentId && commandMatches.length > 0 && !/\s/.test(inputValue)) {
+      if (commandMatches.length > 0 && !/\s/.test(inputValue)) {
         key.stopPropagation();
         const selected = commandMatches[Math.min(commandCursorRef.current, commandMatches.length - 1)]!;
         setEditorText(selected.name);
@@ -5002,6 +5493,59 @@ export function App({
     ? needsTranscriptGap(lastLine, { kind: "text", role: visibleTx.stream.kind, text: visibleTx.stream.text })
     : false;
 
+  // One element for the whole transcript, rebuilt only when what it shows
+  // changes. React walks a child list of this size on every render of the app,
+  // and an answer arriving mid-turn re-renders the app many times a second, so
+  // handing back the identical element lets React skip the list entirely.
+  // Every value a row reads is a dependency below. Add the dependency when a
+  // row starts reading something new, or the rows go stale.
+  // The stream is reduced to a flag on purpose: only the caret on the last row
+  // depends on it, so a delta must not rebuild the settled rows.
+  const streaming = visibleTx.stream !== null;
+  const transcriptRows = useMemo(
+    () => <>{visibleLines.slice(transcriptWindowStart).map((line, offset) => {
+      // The absolute index, not the offset in the window: the row ids, the
+      // transcript cursor, and the gap rule are all in terms of the whole
+      // transcript, and they must not change when older rows mount.
+      const i = transcriptWindowStart + offset;
+      const projectedKey = projectedLineKey(line, i);
+      return (
+        <TranscriptRow
+          key={projectedKey}
+          theme={theme}
+          syntaxStyle={syntaxStyle}
+          line={line}
+          index={i}
+          selected={transcriptFocused && transcriptCursor === i}
+          expanded={detailOverrides.get(projectedKey) ?? outputMode === "verbose"}
+          outputMode={outputMode}
+          workingCaret={visibleBusy && !streaming && i === visibleLines.length - 1}
+          gapBefore={needsTranscriptGap(visibleLines[i - 1], line)}
+          news={
+            line.kind === "text" && line.role === "assistant" && line.newsId
+              ? (newsReadById.get(line.newsId) ? "seen" : "unseen")
+              : undefined
+          }
+          onDisclosure={onTranscriptDisclosure}
+        />
+      );
+    })}</>,
+    [
+      visibleLines,
+      transcriptWindowStart,
+      theme,
+      syntaxStyle,
+      outputMode,
+      detailOverrides,
+      transcriptFocused,
+      transcriptCursor,
+      visibleBusy,
+      streaming,
+      newsReadById,
+      onTranscriptDisclosure,
+    ],
+  );
+
   return (
     <AnimationProvider
       enabled={animations}
@@ -5049,69 +5593,12 @@ export function App({
           style={{ flexGrow: 1, paddingLeft: 1, paddingRight: 1 }}
           stickyScroll
           stickyStart="bottom"
+          onMouseDragEnd={onTranscriptReaderDrag}
+          onMouseDrop={onTranscriptReaderDrag}
           verticalScrollbarOptions={{ visible: true }}
         >
           <RenderErrorBoundary theme={theme} label="transcript" resetKey={transcriptResetKey}>
-            {visibleLines.map((line, i) => {
-              const workingCaret = visibleBusy && !visibleTx.stream && i === visibleLines.length - 1;
-              const projectedKey = projectedLineKey(line, i);
-              const selected = transcriptFocused && transcriptCursor === i;
-              const expanded = detailOverrides.get(projectedKey) ?? outputMode === "verbose";
-              const row =
-                line.kind === "tool-summary" ? (
-                  <ActivitySummaryLine
-                    theme={theme}
-                    syntaxStyle={syntaxStyle}
-                    summary={line}
-                    expanded={expanded}
-                    outputMode={outputMode}
-                    onDisclosureClick={() => clickTranscriptDisclosure(i)}
-                  />
-                ) : line.kind === "tool" ? (
-                  <ToolLine
-                    theme={theme}
-                    syntaxStyle={syntaxStyle}
-                    call={line.call}
-                    workingCaret={workingCaret}
-                    outputMode={outputMode}
-                    expanded={expanded}
-                    onDisclosureClick={() => clickTranscriptDisclosure(i)}
-                  />
-                ) : line.kind === "agent-message" ? (
-                  <AgentMessageLine theme={theme} syntaxStyle={syntaxStyle} line={line} />
-                ) : line.kind === "goal-review" ? (
-                  <GoalReviewLine theme={theme} line={line} />
-                ) : (
-                  <TextLine
-                    theme={theme}
-                    syntaxStyle={syntaxStyle}
-                    role={line.role as Role}
-                    text={line.text}
-                    workingCaret={workingCaret}
-                    news={
-                      line.kind === "text" && line.role === "assistant" && line.newsId
-                        ? (newsReadById.get(line.newsId) ? "seen" : "unseen")
-                        : undefined
-                    }
-                  />
-                );
-              const gapBefore = needsTranscriptGap(visibleLines[i - 1], line);
-              return (
-                <box
-                  id={`transcript-line-${i}`}
-                  key={projectedKey}
-                  style={{
-                    flexDirection: "column",
-                    width: "100%",
-                    flexShrink: 0,
-                    backgroundColor: selected ? theme.selectionBg : "transparent",
-                  }}
-                >
-                  {gapBefore ? <Gap /> : null}
-                  {row}
-                </box>
-              );
-            })}
+            {transcriptRows}
             {visibleTx.stream ? (
               <>
                 {/* Same gap while the answer is still arriving, so it does not

package/src/background-command.ts

@@ -0,0 +1,24 @@
+export type BackgroundCommand =
+  | { kind: "spawn"; prompt: string }
+  | { kind: "error"; message: string };
+
+export const BACKGROUND_USAGE = "Usage: /background <prompt>";
+
+/** True for any input `/background` owns, so App can route it before child prompts. */
+export function isBackgroundCommand(text: string): boolean {
+  return /^\/background(?:\s|$)/.test(text.trim());
+}
+
+/** Parse one fresh managed-agent task without interpreting aliases or control words. */
+export function parseBackgroundCommand(text: string): BackgroundCommand | null {
+  const trimmed = text.trim();
+  if (!isBackgroundCommand(trimmed)) return null;
+  const prompt = trimmed.slice("/background".length).trim();
+  if (!prompt) {
+    return {
+      kind: "error",
+      message: `/background needs a prompt. ${BACKGROUND_USAGE}`,
+    };
+  }
+  return { kind: "spawn", prompt };
+}

package/src/commands.ts

@@ -29,6 +29,10 @@ export const COMMANDS: Command[] = [
     name: "/afk",
     description: "Toggle away mode, or start it with instructions",
   },
+  {
+    name: "/background",
+    description: "Start a managed worktree agent for the selected transcript",
+  },
   {
     name: "/history",
     description: "Browse saved sessions for this directory",
@@ -73,15 +77,24 @@ export function isCommandInput(input: string): boolean {
 }
 
 export function matchingCommands(input: string): Command[] {
-  if (!isCommandInput(input) || input.includes("\n")) return [];
-  const name = input.split(/\s/, 1)[0]!;
+  // Suggestions complete only the command name. Once an argument starts, the
+  // prompt belongs to the editor and Up/Down must navigate wrapped input.
+  if (!isCommandInput(input) || /\s/.test(input)) return [];
   // No command name holds a second separator, so one means the user is typing
   // an absolute path. Leaving it to prefix matching would let Tab on /u turn
   // /usr/lib into /new.
-  if (/[/\\]/.test(name.slice(1))) return [];
-  return COMMANDS.filter((command) =>
-    /\s/.test(input) ? command.name === name : command.name.startsWith(input),
-  );
+  if (/[/\\]/.test(input.slice(1))) return [];
+  return COMMANDS.filter((command) => command.name.startsWith(input));
+}
+
+export function matchingCommandsForTarget(
+  input: string,
+  target: "main" | "subagent",
+): Command[] {
+  const matches = matchingCommands(input);
+  return target === "subagent"
+    ? matches.filter((command) => command.name === "/background")
+    : matches;
 }
 
 export function moveCommandSelection(current: number, count: number, step: -1 | 1): number {

package/src/help-popup.tsx

@@ -59,6 +59,7 @@ export const HELP_GROUPS: HelpGroup[] = [
       ["/clear", "Start a fresh session"],
       ["/goal", "Set or control a goal"],
       ["/goalf", "Work out a goal, then start it"],
+      ["/background", "Start a managed agent for the selected transcript"],
       ["/history", "Browse saved sessions"],
       ["/login", "Add or update a provider"],
       ["/news", "Open recent answers (News)"],

package/src/subagents/manager.ts

@@ -284,6 +284,18 @@ type OpenReminderResources = {
 
 const TERMINAL_SUBAGENT_STATUSES: readonly SubagentStatus[] = ["completed", "failed", "stopped"];
 
+export type BackgroundSpawnRequest =
+  | {
+    task: string;
+    requesterAgentId: null;
+    modelId: string;
+    thinkingLevel: string;
+  }
+  | {
+    task: string;
+    requesterAgentId: string;
+  };
+
 type ManagerOptions = {
   modelRuntime: ModelRuntime;
   agentDir: string;
@@ -488,7 +500,14 @@ export class SubagentManager {
     cwd: string,
   ): Promise<void> {
     const sessionId = sessionManager.getSessionId();
-    if (this.mainApi === pi && this.parentSessionId === sessionId && this.mainSessionManager) return;
+    if (this.mainApi === pi && this.parentSessionId === sessionId && this.mainSessionManager) {
+      // A relocated session keeps its identity while its authoritative project
+      // root changes. Fresh worktrees must be based on the active directory,
+      // and direct UI commands must persist through the current manager object.
+      this.mainSessionManager = sessionManager;
+      this.mainCwd = cwd;
+      return;
+    }
     if (this.parentSessionId !== "detached") {
       this.spawnPreviewManager?.cancelRequester(this.parentSessionId);
       await this.shellManager?.invalidateSession(this.parentSessionId);
@@ -1770,6 +1789,49 @@ export class SubagentManager {
     return this.spawnPreviewManager.request(requester, options, signal);
   }
 
+  /**
+   * Start a user-requested managed agent with only its task as conversation
+   * context. A selected mutable agent owns the descendant and supplies its
+   * model settings; otherwise the main session owns it.
+   */
+  async spawnBackground(request: BackgroundSpawnRequest): Promise<SubagentSnapshot> {
+    if (!request.task.trim()) throw new Error("A background agent needs a prompt");
+    if (request.requesterAgentId === null) {
+      return this.spawn({
+        task: request.task,
+        modelId: request.modelId,
+        thinkingLevel: request.thinkingLevel,
+        parentAgentId: null,
+        context: "fresh",
+        createWorktree: true,
+        role: "worker",
+      });
+    }
+
+    const parent = this.records.get(request.requesterAgentId);
+    if (!parent) throw new Error("Spawner subagent no longer exists");
+    if (isInternalRole(parent.snapshot.role)) {
+      throw new Error("Internal agents cannot own background agents");
+    }
+    if (parent.snapshot.readonly) {
+      throw new Error("Readonly subagents cannot spawn child agents");
+    }
+    if (!["starting", "running", "idle"].includes(parent.snapshot.status)) {
+      throw new Error(
+        `Subagent ${parent.snapshot.name} cannot spawn while ${parent.snapshot.status}`,
+      );
+    }
+    return this.spawn({
+      task: request.task,
+      modelId: parent.snapshot.modelId,
+      thinkingLevel: parent.snapshot.thinkingLevel,
+      parentAgentId: parent.snapshot.id,
+      context: "fresh",
+      createWorktree: true,
+      role: "worker",
+    });
+  }
+
   /** A descriptive record for an agent that runs in the launch project itself. */
   private projectWorktreeRecord(name: string): WorktreeRecord {
     const branch = readBranch(this.mainCwd) ?? "HEAD";

package/src/transcript-window.ts

@@ -0,0 +1,108 @@
+/**
+ * Which part of the transcript is mounted.
+ *
+ * OpenTUI paints only what the viewport covers, but it lays out every mounted
+ * node on every frame, and it rebuilds the render list with them. A resumed
+ * session holds thousands of rows, so mounting all of them made the cost of one
+ * keystroke grow with the length of the conversation.
+ *
+ * The transcript therefore mounts a contiguous run that always reaches the last
+ * row: rows `[start, end)` of the projected lines. Older rows join the tree when
+ * the reader scrolls back to them, or when something asks to reveal one. They
+ * are never dropped while the reader is above the last row, so nothing can
+ * vanish from under a scroll position.
+ *
+ * All of this is index arithmetic on the projected lines. It is kept here, away
+ * from the renderer, so the rules can be read and tested on their own.
+ */
+
+/** Rows added per step, and the smallest run kept mounted. */
+export function transcriptWindowRows(terminalHeight: number): number {
+  // A row is one message, one tool call, or one summary, and it occupies at
+  // least one terminal row. Two terminal heights of rows therefore always
+  // outgrow the viewport, however short the individual rows turn out to be.
+  //
+  // That factor is what stops one step back turning into all of them: a step
+  // moves the reader more than one screen away from the top of the mounted run,
+  // so the trigger to mount more does not fire again straight away.
+  return Math.max(MIN_WINDOW_ROWS, Math.max(0, Math.floor(terminalHeight)) * 2);
+}
+
+/** Floor for a very short terminal, so scrolling back is not one row at a time. */
+export const MIN_WINDOW_ROWS = 60;
+
+/** Rows mounted before a revealed row, so it does not land against the top edge. */
+export const REVEAL_MARGIN_ROWS = 20;
+
+/** Keep a start inside the transcript. A shrunken transcript can strand one. */
+export function clampWindowStart(start: number, lineCount: number): number {
+  const count = Math.max(0, lineCount);
+  if (!Number.isFinite(start)) return 0;
+  return Math.max(0, Math.min(Math.floor(start), count));
+}
+
+/**
+ * The start to use while the reader sits at the last row.
+ *
+ * Exactly one window of rows, so arriving rows cannot grow the mounted run
+ * without limit over a long turn, and a terminal that just got taller gets the
+ * rows to fill itself. History the reader asked for is held by the floor
+ * instead, which is released only on returning here.
+ */
+export function tailWindowStart(lineCount: number, windowRows: number): number {
+  const rows = Math.max(1, Math.floor(windowRows));
+  return Math.max(0, Math.max(0, lineCount) - rows);
+}
+
+/** The start after the reader scrolls back for more history. */
+export function extendedWindowStart(current: number, windowRows: number): number {
+  const rows = Math.max(1, Math.floor(windowRows));
+  return Math.max(0, clampWindowStart(current, Number.POSITIVE_INFINITY) - rows);
+}
+
+/**
+ * The start that puts `index` in the tree.
+ *
+ * Only ever moves the start backwards. A reveal must not unmount the rows the
+ * reader already has, and a target that is mounted already needs no change.
+ */
+export function windowStartForRow(
+  current: number,
+  index: number,
+  margin = REVEAL_MARGIN_ROWS,
+): number {
+  if (!Number.isFinite(index) || index < 0) return current;
+  return Math.min(current, Math.max(0, Math.floor(index) - Math.max(0, margin)));
+}
+
+/**
+ * Is the viewport within one screen of the top of the mounted run?
+ *
+ * The trigger to mount more history. One screen of slack means the rows are
+ * there before the reader reaches the edge, rather than after it.
+ */
+export function nearWindowTop(scrollTop: number, viewportHeight: number): boolean {
+  return scrollTop <= Math.max(1, viewportHeight);
+}
+
+/** Is the viewport at the last row? Sticky scroll holds it there while it is. */
+export function atWindowBottom(
+  scrollTop: number,
+  scrollHeight: number,
+  viewportHeight: number,
+): boolean {
+  // One row of tolerance: the scroll position is rounded to whole rows, and a
+  // content height that just changed can leave it a row short of the end.
+  return scrollTop >= Math.max(0, scrollHeight - viewportHeight) - 1;
+}
+
+/**
+ * Is the viewport at the top of the mounted run?
+ *
+ * A reader who sends the view here has asked for what is above it. One window
+ * per gesture never reaches the start of a long session, so this answers a
+ * different question than `nearWindowTop` and gets a different response.
+ */
+export function atWindowTop(scrollTop: number): boolean {
+  return scrollTop <= 0;
+}