pum-agent 0.2.14-beta.1 → 0.2.15-beta.1

package/README.md

@@ -325,7 +325,7 @@ Set `PUM_DIR` to override the complete PUM data directory.
 | `auth.json` | Provider credentials and custom-provider keys |
 | `models.json` | Custom endpoints and model metadata; submitted keys are not stored here |
 | `settings.json` | Model and thinking level managed by pi |
-| `pum.json` | Theme, animation, search, writing, explanation, Check mode, sandbox, and subagent settings |
+| `pum.json` | Theme, animation, transcript output, search, writing, explanation, Check mode, sandbox, and subagent settings |
 | `theme.json` | Optional semantic color overrides |
 | `history.json` | Prompt history by working directory |
 | `prompt-stash.json` | Stashed prompts by working directory |

package/package.json

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

package/src/app.tsx

@@ -25,6 +25,7 @@ import {
 import {
   CHECK_MODE_PROFILES,
   checkPathsForProject,
+  cycleOutputMode,
   MAX_ACTIVE_SUBAGENTS,
   MIN_ACTIVE_SUBAGENTS,
   SANDBOX_MODES,
@@ -48,6 +49,7 @@ import {
   type Role,
 } from "./transcript";
 import { bashOutput, bashResultDisplay, editCounts, toolArg, type ToolCall } from "./tool-line";
+import { toolPreviewFromResult, toolPreviewFromStart } from "./tool-preview";
 import { readBranch, watchBranch } from "./git-branch";
 import { HelpPopup, maxHelpScrollOffset } from "./help-popup";
 import { appendHistory, loadHistory, removeHistory } from "./history";
@@ -119,10 +121,17 @@ import {
   moveTriggerSelection,
   sortTriggers,
   triggerActionForKey,
-  TriggersPopup,
   type TriggerAction,
   type TriggerManagerLike,
 } from "./triggers/popup";
+import {
+  moveProcessSelection,
+  processTabForKey,
+  ProcessesPopup,
+  sortShells,
+  type ProcessTab,
+  type ShellManagerLike,
+} from "./processes-popup";
 import type { TerminalTitleController } from "./terminal-title";
 import { readClipboardText } from "./text-paste";
 import { copyTextToClipboard } from "./clipboard";
@@ -137,6 +146,10 @@ import {
 } from "./news";
 import { statsFromEntries, type SessionStatsManager } from "./session-stats";
 import { maxStatsScrollOffset, StatsPopup } from "./stats-popup";
+import {
+  projectTranscriptLines,
+  transcriptOutputMode,
+} from "./transcript-output";
 
 type Stream = { kind: "assistant" | "thinking"; text: string } | null;
 type Transcript = { lines: Line[]; stream: Stream; pending: PendingLine[] };
@@ -405,6 +418,7 @@ export function App({
   copyNewsAnswerText = copyTextToClipboard,
   onExit = () => process.exit(0),
   triggerManager,
+  shellManager,
   messageCacheController,
   terminalTitle,
   startupWarnings = [],
@@ -434,6 +448,7 @@ export function App({
   copyNewsAnswerText?: typeof copyTextToClipboard;
   onExit?: () => void | Promise<void>;
   triggerManager?: TriggerManagerLike;
+  shellManager?: ShellManagerLike;
   messageCacheController?: MessageCacheController;
   terminalTitle?: TerminalTitleController;
   /** Visible process-local warnings. These lines never enter pi session context. */
@@ -528,8 +543,12 @@ export function App({
   const [modelSearchFocused, setModelSearchFocused] = useState(false);
   const [, setAgentRevision] = useState(0);
   const [triggersOpen, setTriggersOpen] = useState(false);
+  const [processTab, setProcessTab] = useState<ProcessTab>("triggers");
   const [triggerCursor, setTriggerCursor] = useState(0);
+  const [shellCursor, setShellCursor] = useState(0);
   const [, setTriggerRevision] = useState(0);
+  const [shellRevision, setShellRevision] = useState(0);
+  const [shellTails, setShellTails] = useState<Record<string, string>>({});
 
   const [newsOpen, setNewsOpen] = useState(false);
   const newsOpenRef = useRef(false);
@@ -553,6 +572,11 @@ export function App({
   const questionnaire = questionnaireManager?.current();
   const spawnPreview = spawnPreviewManager?.current();
   const visibleTx = activeAgent?.transcript ?? tx;
+  const outputMode = transcriptOutputMode(settings);
+  const visibleLines = useMemo(
+    () => projectTranscriptLines(visibleTx.lines, outputMode),
+    [visibleTx.lines, outputMode],
+  );
   const visibleBusy = activeAgent
     ? activeAgent.status === "starting" || activeAgent.status === "running"
     : busy;
@@ -563,6 +587,10 @@ export function App({
   const visibleUsage = activeAgent?.usage ?? usage;
   const agentTreeRows = buildAgentTree(agents);
   const triggers = sortTriggers(triggerManager?.getTriggers() ?? []);
+  const shells = sortShells(shellManager?.list() ?? []);
+  const runningShellCount = shells.filter(
+    (shell) => shell.state === "starting" || shell.state === "running",
+  ).length;
   const statsSnapshot = useMemo(() => statsManager?.snapshot() ?? statsFromEntries(
     (session.sessionManager as any).getEntries?.() ?? session.sessionManager.buildContextEntries(),
     `${session.agent.state.model.provider}/${session.agent.state.model.id}`,
@@ -591,12 +619,14 @@ export function App({
   const spawnPreviewInputRef = useRef<TextareaRenderable>(null);
   const settingsOpenRef = useRef(settingsOpen);
   const triggersOpenRef = useRef(false);
+  const processTabRef = useRef<ProcessTab>("triggers");
   const settingsPageRef = useRef(page);
   const settingsSearchFocusedRef = useRef(settingsSearchFocused);
   const focusInputAfterSwitch = useRef(false);
   const activeAgentIdRef = useRef<string | null>(null);
   const agentSelectorCursorRef = useRef(0);
   const triggerCursorRef = useRef(0);
+  const shellCursorRef = useRef(0);
   const commandCursorRef = useRef(0);
   const stashRef = useRef(stash);
   const stashOpenRef = useRef(false);
@@ -678,11 +708,32 @@ export function App({
     setStatsOpen(false);
     statsOpenRef.current = false;
     setStashMode(false);
+    processTabRef.current = "triggers";
+    setProcessTab("triggers");
     const nextCursor = Math.min(triggerCursorRef.current, Math.max(0, triggers.length - 1));
     triggerCursorRef.current = nextCursor;
     setTriggerCursor(nextCursor);
     setTriggerPopup(true);
   };
+  const openProcesses = () => {
+    settingsOpenRef.current = false;
+    setSettingsOpen(false);
+    setHelpOpen(false);
+    setHistoryOpen(false);
+    setAgentSelectorOpen(false);
+    setNewsOpen(false);
+    newsOpenRef.current = false;
+    setStatsOpen(false);
+    statsOpenRef.current = false;
+    setStashMode(false);
+    const nextTriggerCursor = Math.min(triggerCursorRef.current, Math.max(0, triggers.length - 1));
+    const nextShellCursor = Math.min(shellCursorRef.current, Math.max(0, shells.length - 1));
+    triggerCursorRef.current = nextTriggerCursor;
+    shellCursorRef.current = nextShellCursor;
+    setTriggerCursor(nextTriggerCursor);
+    setShellCursor(nextShellCursor);
+    setTriggerPopup(true);
+  };
   // The event subscription is set up once, so it reads the toggle via a ref.
   const showThinkingRef = useRef(initial.showThinking);
   const startupWarningsRef = useRef([...startupWarnings]);
@@ -1051,6 +1102,28 @@ export function App({
     setTriggerCursor(next);
   }), [triggerManager]);
 
+  useEffect(() => shellManager?.subscribe(() => {
+    setShellRevision((revision) => revision + 1);
+    const count = shellManager.list().length;
+    const next = Math.min(shellCursorRef.current, Math.max(0, count - 1));
+    shellCursorRef.current = next;
+    setShellCursor(next);
+  }), [shellManager]);
+
+  useEffect(() => {
+    if (!shellManager || !triggersOpen || processTab !== "shells") return;
+    const shell = shells[shellCursor];
+    if (!shell || !shell.output.exists) return;
+    let active = true;
+    void shellManager.getOutput(shell.id, { lineLimit: 20 }).then((result) => {
+      if (!active) return;
+      setShellTails((tails) => tails[shell.id] === result.tail
+        ? tails
+        : { ...tails, [shell.id]: result.tail });
+    }).catch(() => {});
+    return () => { active = false; };
+  }, [shellManager, triggersOpen, processTab, shellCursor, shellRevision]);
+
   useEffect(
     () => subagentManager.subscribe((event) => {
       if (event.type === "main-line") append(event.line);
@@ -1184,6 +1257,8 @@ export function App({
               arg: toolArg(event.toolName, event.args, cwd),
               state: "running",
               startedAt: Date.now(),
+              input: event.args,
+              preview: toolPreviewFromStart(event.toolName, event.args),
             },
           });
           break;
@@ -1194,6 +1269,7 @@ export function App({
           break;
         case "tool_execution_end": {
           const bashResult = event.toolName === "bash" ? bashResultDisplay(event.result) : {};
+          const preview = toolPreviewFromResult(event.toolName, event.result);
           patchTool(event.toolCallId, {
             state: isRejectedToolResult(event.result, event.toolCallId)
               ? "rejected"
@@ -1210,6 +1286,9 @@ export function App({
                     ? messageCacheDetail(event.result)
                     : undefined,
             exitCode: bashResult.exitCode,
+            result: event.result,
+            isError: event.isError,
+            ...(preview ? { preview } : {}),
           });
           break;
         }
@@ -1435,6 +1514,10 @@ export function App({
     update({ workingRuleAnimation: next });
   };
 
+  const stepOutputMode = (step: number) => {
+    update({ outputMode: cycleOutputMode(settings.outputMode, step) });
+  };
+
   const openLogin = () => {
     settingsOpenRef.current = false;
     setSettingsOpen(false);
@@ -1817,10 +1900,11 @@ export function App({
     const loginCommand = trimmed === "/login";
     const checkPathCommand = /^\/check-path(?:\s|$)/.test(trimmed);
     const triggersCommand = trimmed === "/triggers";
+    const processesCommand = trimmed === "/processes";
     const newsCommand = trimmed === "/news";
     const statsCommand = trimmed === "/stats";
     const worktreeCommand = /^\/worktree(?:\s+([a-zA-Z0-9_-]+))?$/.exec(trimmed);
-    if (!compress && !clear && !historyCommand && !loginCommand && !checkPathCommand && !triggersCommand && !newsCommand && !statsCommand && !worktreeCommand) return false;
+    if (!compress && !clear && !historyCommand && !loginCommand && !checkPathCommand && !triggersCommand && !processesCommand && !newsCommand && !statsCommand && !worktreeCommand) return false;
     editingStashIndex.current = null;
 
     if (historyCommand) {
@@ -1838,6 +1922,11 @@ export function App({
       openTriggers();
       return true;
     }
+    if (processesCommand) {
+      setEditorText("");
+      openProcesses();
+      return true;
+    }
     if (newsCommand) {
       setEditorText("");
       openNews();
@@ -2108,6 +2197,16 @@ export function App({
     }));
   };
 
+  const killSelectedShell = () => {
+    const shell = shells[shellCursorRef.current];
+    if (!shell || !shellManager || (shell.state !== "starting" && shell.state !== "running")) return;
+    Promise.resolve(shellManager.terminate(shell.id)).catch((error) => append({
+      kind: "text",
+      role: "error",
+      text: `shell kill failed: ${String(error)}`,
+    }));
+  };
+
   const stepCheckMode = (step: number) => {
     const index = CHECK_MODE_PROFILES.indexOf(settings.checkMode);
     update({ checkMode: CHECK_MODE_PROFILES[(index + step + CHECK_MODE_PROFILES.length) % CHECK_MODE_PROFILES.length]! });
@@ -2124,6 +2223,7 @@ export function App({
     providers: { enter: openLogin },
     animations: { step: () => update({ animations: !settings.animations }) },
     workingRuleAnimation: { step: stepWorkingRuleAnimation },
+    outputMode: { step: stepOutputMode },
     webSearch: { step: () => update({ webSearch: !settings.webSearch }) },
     writingStyle: { step: stepWritingStyle },
     explanationStrength: { step: stepExplanationStrength },
@@ -2166,6 +2266,7 @@ export function App({
     providers: "login and custom setup ›",
     animations: `‹ ${settings.animations ? "on" : "off"} ›`,
     workingRuleAnimation: `‹ ${settings.workingRuleAnimation} ›${settings.workingRuleAnimation === "off" ? "" : animationUnavailable}`,
+    outputMode: `‹ ${settings.outputMode ?? "default"} ›`,
     webSearch: `‹ ${settings.webSearch ? "on" : "off"} ›${searchProviders.length ? "" : "  (not on provider)"}`,
     writingStyle: `‹ ${settings.writingStyle} ›`,
     explanationStrength: `‹ ${settings.explanationStrength} ›`,
@@ -2387,7 +2488,7 @@ export function App({
     if (key.ctrl && key.name === "t") {
       key.stopPropagation();
       if (triggersOpenRef.current) setTriggerPopup(false);
-      else openTriggers();
+      else openProcesses();
       return;
     }
 
@@ -2395,15 +2496,29 @@ export function App({
       key.stopPropagation();
       if (key.name === "escape") {
         setTriggerPopup(false);
+      } else if (processTabForKey(key, processTabRef.current)) {
+        const tab = processTabForKey(key, processTabRef.current)!;
+        processTabRef.current = tab;
+        setProcessTab(tab);
       } else if (key.name === "up" || key.name === "down" || key.name === "pageup" || key.name === "pagedown") {
         const direction = key.name === "up" || key.name === "pageup" ? -1 : 1;
         const steps = key.name === "pageup" || key.name === "pagedown" ? 5 : 1;
-        let next = triggerCursorRef.current;
+        const shellTab = processTabRef.current === "shells";
+        let next = shellTab ? shellCursorRef.current : triggerCursorRef.current;
         for (let index = 0; index < steps; index++) {
-          next = moveTriggerSelection(next, triggers.length, direction);
+          next = shellTab
+            ? moveProcessSelection(next, shells.length, direction)
+            : moveTriggerSelection(next, triggers.length, direction);
+        }
+        if (shellTab) {
+          shellCursorRef.current = next;
+          setShellCursor(next);
+        } else {
+          triggerCursorRef.current = next;
+          setTriggerCursor(next);
         }
-        triggerCursorRef.current = next;
-        setTriggerCursor(next);
+      } else if (processTabRef.current === "shells") {
+        if (key.name === "k" || key.sequence === "k") killSelectedShell();
       } else {
         const action = triggerActionForKey(key, triggers[triggerCursorRef.current]);
         if (action) performTriggerAction(action);
@@ -2869,7 +2984,10 @@ export function App({
     }
   });
 
-  const lastLine = visibleTx.lines[visibleTx.lines.length - 1];
+  const lastProjectedLine = visibleLines[visibleLines.length - 1];
+  const lastLine: Line | undefined = lastProjectedLine?.kind === "tool-summary"
+    ? { kind: "text", role: "system", text: lastProjectedLine.text }
+    : lastProjectedLine;
   const streamGap = visibleTx.stream
     ? needsTranscriptGap(lastLine, { kind: "text", role: visibleTx.stream.kind, text: visibleTx.stream.text })
     : false;
@@ -2904,6 +3022,7 @@ export function App({
           agentCount={agents.length}
           runningAgentCount={activeSubagentCount}
           maxActiveAgentCount={settings.maxActiveSubagents}
+          runningShellCount={runningShellCount}
           activeAgentName={activeAgent?.name}
         />
         <WorkingRule
@@ -2922,11 +3041,24 @@ export function App({
           stickyStart="bottom"
           verticalScrollbarOptions={{ visible: true }}
         >
-          {visibleTx.lines.map((line, i) => {
-            const workingCaret = visibleBusy && !visibleTx.stream && i === visibleTx.lines.length - 1;
+          {visibleLines.map((line, i) => {
+            const workingCaret = visibleBusy && !visibleTx.stream && i === visibleLines.length - 1;
             const row =
-              line.kind === "tool" ? (
-                <ToolLine theme={theme} call={line.call} workingCaret={workingCaret} />
+              line.kind === "tool-summary" ? (
+                <TextLine
+                  theme={theme}
+                  syntaxStyle={syntaxStyle}
+                  role="system"
+                  text={line.text}
+                />
+              ) : line.kind === "tool" ? (
+                <ToolLine
+                  theme={theme}
+                  syntaxStyle={syntaxStyle}
+                  call={line.call}
+                  workingCaret={workingCaret}
+                  outputMode={outputMode}
+                />
               ) : line.kind === "agent-message" ? (
                 <AgentMessageLine theme={theme} syntaxStyle={syntaxStyle} line={line} />
               ) : (
@@ -2943,9 +3075,18 @@ export function App({
                   }
                 />
               );
-            const gapBefore = needsTranscriptGap(visibleTx.lines[i - 1], line);
+            const currentGapLine: Line = line.kind === "tool-summary"
+              ? { kind: "text", role: "system", text: line.text }
+              : line;
+            const previousProjected = visibleLines[i - 1];
+            const previousGapLine: Line | undefined = previousProjected?.kind === "tool-summary"
+              ? { kind: "text", role: "system", text: previousProjected.text }
+              : previousProjected;
+            const gapBefore = needsTranscriptGap(previousGapLine, currentGapLine);
             const lineKey =
-              line.kind === "tool"
+              line.kind === "tool-summary"
+                ? `tool-summary:${i}:${line.text}`
+                : line.kind === "tool"
                 ? `tool:${line.call.id}`
                 : line.kind === "agent-message"
                   ? `agent:${line.sender}:${line.recipient}:${i}:${line.text}`
@@ -2976,7 +3117,7 @@ export function App({
           ) : null}
           {visibleTx.pending.some((pending) => !pending.delivered) ? (
             <>
-              {(visibleTx.lines.length > 0 || visibleTx.stream) ? <Gap /> : null}
+              {(visibleLines.length > 0 || visibleTx.stream) ? <Gap /> : null}
               {visibleTx.pending.filter((pending) => !pending.delivered).map((pending) => (
                 <PendingMessageLine
                   key={pending.id}
@@ -3124,10 +3265,14 @@ export function App({
           />
         ) : null}
         {triggersOpen ? (
-          <TriggersPopup
+          <ProcessesPopup
             theme={theme}
+            tab={processTab}
             triggers={triggers}
-            cursor={triggerCursor}
+            shells={shells}
+            triggerCursor={triggerCursor}
+            shellCursor={shellCursor}
+            shellTail={shells[shellCursor] ? shellTails[shells[shellCursor]!.id] : undefined}
             terminalWidth={width}
             terminalHeight={height}
           />

package/src/check-mode.ts

@@ -209,13 +209,14 @@ export function isProcessCheckProposal(value: unknown): value is ProcessCheckPro
   if (!value || typeof value !== "object") return false;
   const proposal = value as Partial<ProcessCheckProposal>;
   return proposal.kind === "process"
-    && proposal.source === "external-trigger"
+    && ["external-trigger", "managed-shell"].includes(proposal.source ?? "")
     && typeof proposal.executable === "string"
     && Array.isArray(proposal.args)
     && proposal.args.every((argument) => typeof argument === "string")
     && typeof proposal.cwd === "string"
     && ["create", "start", "resume", "repeat", "invoke-run"].includes(proposal.operation ?? "")
-    && (proposal.triggerName === undefined || typeof proposal.triggerName === "string");
+    && (proposal.triggerName === undefined || typeof proposal.triggerName === "string")
+    && (proposal.shellName === undefined || typeof proposal.shellName === "string");
 }
 
 /** Build the exact safety identity. Display-only triggerName is intentionally omitted. */
@@ -297,7 +298,7 @@ export async function prepareCheck(
   const paths = mutation?.changedPaths ?? [];
   const processProposal = isProcessCheckProposal(input) ? input : undefined;
   const summary = processProposal
-    ? `${processProposal.operation} external trigger process: ${processProposal.executable}`
+    ? `${processProposal.operation} ${processProposal.source === "managed-shell" ? "managed shell" : "external trigger"} process: ${processProposal.executable}`
     : toolName === "bash"
       ? `Run ${bash!.stages.length} shell stage${bash!.stages.length === 1 ? "" : "s"}`
       : `Change ${paths.length} project file${paths.length === 1 ? "" : "s"} (+${mutation!.additions} −${mutation!.removals})`;
@@ -325,6 +326,7 @@ export async function prepareCheck(
       args: processProposal.args,
       cwd: processProposal.cwd,
       triggerName: processProposal.triggerName,
+      shellName: processProposal.shellName,
       analysis: bash,
     } : undefined,
     proposedMutation: mutation ? {
@@ -710,6 +712,8 @@ export type ExternalTriggerSafetyChecker = (
   signal?: AbortSignal,
 ) => Promise<void>;
 
+export type ManagedShellSafetyChecker = ExternalTriggerSafetyChecker;
+
 /** Create the process safety callback used by TriggerManager. */
 export function createExternalTriggerSafetyChecker(
   runtime: CheckerRuntime,
@@ -733,6 +737,9 @@ export function createExternalTriggerSafetyChecker(
   };
 }
 
+/** Create the structured process safety callback used by ShellManager. */
+export const createManagedShellSafetyChecker = createExternalTriggerSafetyChecker;
+
 export async function verifyToolCall(runtime: CheckerRuntime, call: ToolCheck): Promise<ToolBlock | undefined> {
   const evaluation = await evaluateToolCall(runtime, call);
   return evaluation.decision === "allow" ? undefined : { block: true, reason: evaluation.reason };

package/src/check-policy.ts

@@ -144,7 +144,7 @@ export type ProcessCheckOperation = "create" | "start" | "resume" | "repeat" | "
 
 export type ProcessCheckProposal = {
   kind: "process";
-  source: "external-trigger";
+  source: "external-trigger" | "managed-shell";
   executable: string;
   /** Process arguments. The executable is not included. */
   args: readonly string[];
@@ -152,6 +152,8 @@ export type ProcessCheckProposal = {
   operation: ProcessCheckOperation;
   /** Display context only. This field is not part of the safety identity. */
   triggerName?: string;
+  /** Display context only. This field is not part of the safety identity. */
+  shellName?: string;
 };
 
 export type AnalyzeExecutablePolicyOptions = Pick<ProcessCheckProposal, "executable" | "args" | "cwd"> & {

package/src/commands.ts

@@ -39,7 +39,11 @@ export const COMMANDS: Command[] = [
   },
   {
     name: "/triggers",
-    description: "Manage external triggers",
+    description: "Open Processes on the Triggers tab",
+  },
+  {
+    name: "/processes",
+    description: "Manage external triggers and shells",
   },
   {
     name: "/worktree",

package/src/help-popup.tsx

@@ -59,7 +59,7 @@ export const HELP_GROUPS: HelpGroup[] = [
       ["/news", "Open recent answers (News)"],
       ["/stats", "Show session statistics"],
       ["/check-path", "Manage extra Check mode paths"],
-      ["/triggers", "Manage external triggers"],
+      ["/processes", "Manage triggers and shells"],
       ["/worktree", "Create a managed worktree"],
       ["Tab", "Complete a command preview"],
     ],
@@ -69,7 +69,7 @@ export const HELP_GROUPS: HelpGroup[] = [
     controls: [
       ["Ctrl+P", "Open Settings"],
       ["Ctrl+N", "Open News; n/p jump"],
-      ["Ctrl+T", "Open external triggers"],
+      ["Ctrl+T", "Open Processes"],
       ["Ctrl+End", "Scroll transcript to the end"],
       ["/ in Settings", "Focus settings search"],
       ["Esc", "Close; twice to cancel work"],

package/src/main.tsx

@@ -52,6 +52,16 @@ import {
   filesystemSandboxExtension,
 } from "./filesystem-sandbox";
 import { SessionStatsManager } from "./session-stats";
+import { ShellManager } from "./shells/manager";
+import {
+  NodeShellFileOperations,
+  NodeShellProcessAdapter,
+  systemShellClock,
+} from "./shells/process";
+import {
+  ManagedShellLifecycleController,
+  lifecycleEventFromSnapshot,
+} from "./shells/lifecycle";
 
 export async function start(options: StartupOptions): Promise<void> {
   mkdirSync(AGENT_DIR, { recursive: true });
@@ -100,6 +110,33 @@ export async function start(options: StartupOptions): Promise<void> {
     });
   });
   let subagentManager!: SubagentManager;
+  const shellLifecycle = new ManagedShellLifecycleController(
+    {
+      append: (_owner, _customType, data) =>
+        subagentManager.persistManagedShellEvent(data as any),
+    },
+    {
+      deliver: (message) => subagentManager.deliverManagedShellCompletion(message.details),
+    },
+  );
+  const startedShells = new Set<string>();
+  const shellManager = new ShellManager({
+    process: new NodeShellProcessAdapter(),
+    files: new NodeShellFileOperations(),
+    clock: systemShellClock,
+    async onCompleted(snapshot) {
+      const output = await shellManager.getOutput(snapshot.id, { lineLimit: 200 }).catch(() => undefined);
+      const event = lifecycleEventFromSnapshot(snapshot, output?.tail);
+      await shellLifecycle.recordExit(event, snapshot.state === "terminated");
+    },
+  });
+  shellManager.subscribe((event) => {
+    if (event.type !== "changed"
+      || !["starting", "running"].includes(event.snapshot.state)
+      || startedShells.has(event.snapshot.id)) return;
+    startedShells.add(event.snapshot.id);
+    void shellLifecycle.record(lifecycleEventFromSnapshot(event.snapshot));
+  });
   const triggerManager = new TriggerManager({
     process: new NodeTriggerProcessAdapter(),
     clock: systemTriggerClock,
@@ -151,6 +188,7 @@ export async function start(options: StartupOptions): Promise<void> {
     messageCacheController,
     statsManager,
     triggerManager,
+    shellManager,
     childExtensionFactories: [
       identityExtension,
       writingStyleExtension,
@@ -239,6 +277,7 @@ export async function start(options: StartupOptions): Promise<void> {
       selectionClipboard.dispose();
       cleanupPendingImages();
     },
+    shutdownShells: () => shellManager.shutdown(),
     shutdownTriggers: () => triggerManager.shutdown(),
     dispose: () => sessionRuntime.dispose(),
     destroy: async () => {