pi-subagents 0.80.0 → 0.82.0

package/src/tui/fleet.js

@@ -2,6 +2,8 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
 import { matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { fleetContains, fleetLayout } from "./fleet-layout.js";
+import { FleetViewport } from "./fleet-viewport.js";
 import { snapshotExternalRuns } from "../api/external-runs.js";
 import { getArtifactPaths, getArtifactsDir } from "../shared/artifacts.js";
 import { formatDuration, formatModelThinking, formatTokens, formatTokenUsage, shortenPath } from "../shared/formatters.js";
@@ -14,7 +16,9 @@ import { steerAsyncRun } from "../runs/foreground/async-steering-action.js";
 import { stopAsyncRun } from "../runs/foreground/async-stop-action.js";
 import { resolveWorkflowForegroundSteeringTarget, steerWorkflowForegroundTarget } from "../runs/foreground/workflow-foreground-steering.js";
 import { contextModeBadge, contextModeLabel } from "../runs/shared/context-mode.js";
+import { foregroundChildStateLabel } from "../runs/foreground/foreground-history.js";
 import { FLEET_STATUS_WIDGET_KEY, reportFleetWarning } from "./fleet-status.js";
+import { stepTaskSummary } from "./render.js";
 import { readFleetTranscript, renderFleetTranscript } from "./fleet-transcript.js";
 import { runningTone } from "./running-tone.js";
 import { childThinkingLevel } from "../shared/model-info.js";
@@ -108,18 +112,22 @@ function asyncItems(run, description) {
     if (run.steps.length === 0 || run.mode === "workflow") {
         return [{ key: `async:${run.id}`, kind: "async", runId: run.id, agent: run.mode, state: run.state, updatedAt, run, ...(description ? { description } : {}) }];
     }
-    return run.steps.map((step) => ({
-        key: `async:${run.id}:${step.index}`,
-        kind: "async",
-        runId: run.id,
-        index: step.index,
-        agent: step.label ? `${step.label} (${step.agent})` : step.agent,
-        state: step.status,
-        updatedAt: step.lastActivityAt ?? updatedAt,
-        run,
-        step,
-        ...(description ? { description } : {}),
-    }));
+    return run.steps.map((step) => {
+        const task = stepTaskSummary(step, step.agent);
+        return {
+            key: `async:${run.id}:${step.index}`,
+            kind: "async",
+            runId: run.id,
+            index: step.index,
+            agent: step.label ? `${step.label} (${step.agent})` : step.agent,
+            state: step.status,
+            updatedAt: step.lastActivityAt ?? updatedAt,
+            run,
+            step,
+            ...(task ? { task } : {}),
+            ...(description ? { description } : {}),
+        };
+    });
 }
 function orderFleetAsyncRuns(runs, terminalLimit, trackedJobs) {
     const updatedAt = (run) => run.lastUpdate ?? run.endedAt ?? run.startedAt;
@@ -443,7 +451,7 @@ function foregroundRecentDetail(item, state) {
     const lines = [
         `Run: ${item.runId}`,
         "Source: foreground",
-        `State: ${child.status}`,
+        `State: ${foregroundChildStateLabel(run, child)}`,
         `Mode: ${run.mode}`,
         `Child: ${child.index} (${child.agent})${contextModeLabel(child.context) ? ` ${contextModeLabel(child.context)}` : ""}`,
         modelThinking ? `Model: ${modelThinking}` : undefined,
@@ -746,11 +754,8 @@ export class SubagentFleetComponent {
     snapshot = { items: [] };
     selected = 0;
     selectedKey;
-    detailScroll = 0;
-    detailAutoFollow = true;
-    detailLineCount = 0;
-    detailViewportHeight = 8;
-    bodyHeight = 8;
+    viewport;
+    renderedLayout;
     expandedTools = false;
     promptAuditOpen = false;
     promptAuditView = "authored";
@@ -773,6 +778,7 @@ export class SubagentFleetComponent {
     keybindings;
     constructor(tui, theme, state, done, options = {}) {
         this.tui = tui;
+        this.viewport = new FleetViewport(() => this.tui.requestRender());
         this.theme = theme;
         this.markdownTheme = options.markdownTheme ?? getMarkdownTheme();
         this.state = state;
@@ -820,11 +826,14 @@ export class SubagentFleetComponent {
         this.selectedKey = this.snapshot.items[this.selected]?.key;
     }
     moveSelection(delta) {
-        if (this.snapshot.items.length === 0)
+        this.selectItem(Math.max(0, Math.min(this.snapshot.items.length - 1, this.selected + delta)));
+    }
+    selectItem(index) {
+        if (!this.snapshot.items[index])
             return;
-        this.selected = Math.max(0, Math.min(this.snapshot.items.length - 1, this.selected + delta));
+        this.selected = index;
         this.selectedKey = this.snapshot.items[this.selected]?.key;
-        this.detailAutoFollow = true;
+        this.viewport.follow();
         this.resetActionInput();
         this.tui.requestRender();
     }
@@ -862,8 +871,7 @@ export class SubagentFleetComponent {
             return;
         this.selected = this.snapshot.items.findIndex((item) => item.key === target.key);
         this.selectedKey = target.key;
-        this.detailScroll = 0;
-        this.detailAutoFollow = false;
+        this.viewport.resetTop();
         this.tui.requestRender();
     }
     resetActionInput() {
@@ -951,8 +959,7 @@ export class SubagentFleetComponent {
     setActionNotice(result) {
         this.actionNotice = result;
         this.resetActionInput();
-        this.detailAutoFollow = false;
-        this.detailScroll = 0;
+        this.viewport.resetTop();
         this.refresh();
         this.tui.requestRender();
     }
@@ -972,10 +979,35 @@ export class SubagentFleetComponent {
         });
     }
     scrollDetail(delta) {
-        const maxScroll = Math.max(0, this.detailLineCount - this.detailViewportHeight);
-        this.detailScroll = Math.max(0, Math.min(maxScroll, this.detailScroll + delta));
-        this.detailAutoFollow = this.detailScroll >= maxScroll;
-        this.tui.requestRender();
+        this.viewport.scroll.scrollBy(delta);
+    }
+    handleMouse(event) {
+        // Block pointer fallback as well as inspector actions while a text/confirmation modal owns input.
+        if (this.steerDraft !== undefined || this.redoGuidanceDraft !== undefined || this.stopConfirming || this.actionBusy) {
+            return { handled: true, render: false };
+        }
+        const layout = this.renderedLayout;
+        if (!layout || layout.width !== event.width || layout.rows !== (this.tui.terminal?.rows ?? 32)) {
+            // Never use hit regions from a different size; wheel must not escape to the transcript.
+            return event.type === "wheel" ? { handled: true, render: false } : undefined;
+        }
+        if (event.type === "wheel" && fleetContains(layout.output, event.x, event.y)) {
+            this.scrollDetail(event.wheelDelta ?? 0);
+            return { handled: true, render: false };
+        }
+        if (this.promptAuditOpen)
+            return { handled: true, render: false };
+        if (event.type === "click" && event.button === "left" && !event.shift && !event.alt && !event.ctrl
+            && fleetContains(layout.roster, event.x, event.y)) {
+            const key = layout.rosterKeys[event.y - layout.roster.y];
+            const index = key === undefined ? -1 : this.snapshot.items.findIndex((item) => item.key === key);
+            if (index < 0)
+                return undefined;
+            this.selectItem(index);
+            return { handled: true, render: false };
+        }
+        // Unowned wheel inside the overlay would otherwise scroll the transcript behind it.
+        return event.type === "wheel" ? { handled: true, render: false } : undefined;
     }
     handleInput(data) {
         if (this.promptAuditOpen && this.redoGuidanceDraft !== undefined) {
@@ -1012,7 +1044,7 @@ export class SubagentFleetComponent {
         if (this.promptAuditOpen) {
             if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
                 this.promptAuditOpen = false;
-                this.detailAutoFollow = true;
+                this.viewport.follow();
                 this.tui.requestRender();
                 return;
             }
@@ -1022,7 +1054,7 @@ export class SubagentFleetComponent {
                 return this.movePromptSelection(-1);
             if (data === "1" || data === "2" || data === "3") {
                 this.promptAuditView = data === "1" ? "authored" : data === "2" ? "runtime" : "effective";
-                this.detailScroll = 0;
+                this.viewport.resetTop();
                 this.tui.requestRender();
                 return;
             }
@@ -1037,8 +1069,7 @@ export class SubagentFleetComponent {
                 else {
                     this.actionNotice = undefined;
                     this.redoGuidanceDraft = "";
-                    this.detailAutoFollow = false;
-                    this.detailScroll = 0;
+                    this.viewport.resetTop();
                     this.tui.requestRender();
                 }
                 return;
@@ -1061,9 +1092,9 @@ export class SubagentFleetComponent {
             if (matchesFleetAction(data, this.keybindings, "scrollDown"))
                 return this.scrollDetail(1);
             if (matchesFleetAction(data, this.keybindings, "pageUp"))
-                return this.scrollDetail(-this.detailViewportHeight);
+                return this.scrollDetail(-this.viewport.scroll.viewportHeight);
             if (matchesFleetAction(data, this.keybindings, "pageDown"))
-                return this.scrollDetail(this.detailViewportHeight);
+                return this.scrollDetail(this.viewport.scroll.viewportHeight);
             return;
         }
         if (this.steerDraft !== undefined) {
@@ -1137,9 +1168,9 @@ export class SubagentFleetComponent {
         if (matchesFleetAction(data, this.keybindings, "selectLast"))
             return this.moveSelection(this.snapshot.items.length);
         if (matchesFleetAction(data, this.keybindings, "pageUp"))
-            return this.scrollDetail(-this.detailViewportHeight);
+            return this.scrollDetail(-this.viewport.scroll.viewportHeight);
         if (matchesFleetAction(data, this.keybindings, "pageDown"))
-            return this.scrollDetail(this.detailViewportHeight);
+            return this.scrollDetail(this.viewport.scroll.viewportHeight);
         if (matchesFleetAction(data, this.keybindings, "refresh")) {
             this.transcriptCache = undefined;
             this.refresh();
@@ -1152,8 +1183,7 @@ export class SubagentFleetComponent {
             else {
                 this.promptAuditOpen = true;
                 this.promptAuditView = "authored";
-                this.detailScroll = 0;
-                this.detailAutoFollow = false;
+                this.viewport.resetTop();
                 this.actionNotice = undefined;
                 this.tui.requestRender();
             }
@@ -1166,8 +1196,7 @@ export class SubagentFleetComponent {
             else {
                 this.actionNotice = undefined;
                 this.steerDraft = "";
-                this.detailAutoFollow = false;
-                this.detailScroll = 0;
+                this.viewport.resetTop();
                 this.tui.requestRender();
             }
             return;
@@ -1179,8 +1208,7 @@ export class SubagentFleetComponent {
             else {
                 this.actionNotice = undefined;
                 this.stopConfirming = true;
-                this.detailAutoFollow = false;
-                this.detailScroll = 0;
+                this.viewport.resetTop();
                 this.tui.requestRender();
             }
             return;
@@ -1196,18 +1224,21 @@ export class SubagentFleetComponent {
             return;
         }
     }
-    rosterLines(width) {
+    rosterLines(layout) {
         if (this.snapshot.items.length === 0)
             return [this.theme.fg("dim", "No tracked children")];
-        const start = Math.max(0, Math.min(this.selected - this.bodyHeight + 1, Math.max(0, this.snapshot.items.length - this.bodyHeight)));
-        return this.snapshot.items.slice(start, start + this.bodyHeight).map((item, offset) => {
-            const index = start + offset;
+        return layout.rosterKeys.map((_key, offset) => {
+            const index = layout.rosterStart + offset;
+            const item = this.snapshot.items[index];
             const marker = index === this.selected ? this.theme.fg("accent", "›") : " ";
             const context = item.kind === "async" ? contextModeBadge(this.theme, item.step?.context ?? item.run.context) : item.kind === "foreground-recent" ? contextModeBadge(this.theme, item.child.context) : "";
-            const agent = index === this.selected ? this.theme.bold(item.agent) : item.agent;
-            const identity = item.runId.slice(0, 8);
+            // A child's task tells rows of one run apart; the run id stays in the detail header.
+            const task = item.kind === "async" ? item.task : undefined;
+            const name = task && item.kind === "async" && item.step ? item.step.agent : item.agent;
+            const agent = index === this.selected ? this.theme.bold(name) : name;
+            const identity = task ?? item.runId.slice(0, 8);
             const left = `${marker} ${statusGlyph(item, this.theme)} ${agent}${context} ${this.theme.fg("dim", `· ${identity}`)}`;
-            return rightAligned(left, this.theme.fg("dim", item.state), width);
+            return rightAligned(left, this.theme.fg("dim", item.state), layout.roster.width);
         });
     }
     renderedTranscript(target, width) {
@@ -1305,26 +1336,21 @@ export class SubagentFleetComponent {
         return { header: [], body: this.withActionLines(lines) };
     }
     render(width) {
-        if (width < 36)
+        const layout = fleetLayout(width, this.tui.terminal?.rows ?? 32, this.selected, this.snapshot.items);
+        this.renderedLayout = layout;
+        if (!layout)
             return [truncateToWidth("Subagent fleet needs at least 36 columns. Esc closes.", width)];
         const innerWidth = width - 2;
-        const rows = this.tui.terminal?.rows ?? 32;
-        this.bodyHeight = Math.max(2, Math.floor(rows * 0.85) - 6);
-        const rosterWidth = Math.max(22, Math.min(46, Math.floor((innerWidth - 1) * 0.38)));
-        const detailWidth = Math.max(1, innerWidth - rosterWidth - 1);
-        const roster = this.rosterLines(rosterWidth);
+        const { bodyHeight } = layout;
+        const rosterWidth = layout.roster.width;
+        const detailWidth = layout.output.width;
+        const roster = this.rosterLines(layout);
         const detail = this.wrappedDetail(detailWidth);
-        const detailHeader = detail.header.slice(0, Math.max(0, this.bodyHeight - 1));
-        this.detailViewportHeight = Math.max(1, this.bodyHeight - detailHeader.length);
-        this.detailLineCount = detail.body.length;
-        const maxDetailScroll = Math.max(0, detail.body.length - this.detailViewportHeight);
-        if (this.detailAutoFollow)
-            this.detailScroll = maxDetailScroll;
-        else if (this.detailScroll > maxDetailScroll)
-            this.detailScroll = maxDetailScroll;
+        const detailHeader = detail.header.slice(0, Math.max(0, bodyHeight - 1));
+        const outputBodyHeight = bodyHeight - detailHeader.length;
         const visibleDetails = [
             ...detailHeader,
-            ...detail.body.slice(this.detailScroll, this.detailScroll + this.detailViewportHeight),
+            ...this.viewport.render(detail.body, detailWidth, outputBodyHeight),
         ];
         const lines = [this.theme.fg("border", `╭${"─".repeat(innerWidth)}╮`)];
         const selected = this.snapshot.items[this.selected];
@@ -1336,7 +1362,7 @@ export class SubagentFleetComponent {
             : this.theme.fg("dim", "no children ");
         lines.push(this.theme.fg("border", "│") + rightAligned(title, selectedStatus, innerWidth) + this.theme.fg("border", "│"));
         lines.push(this.theme.fg("border", `├${"─".repeat(rosterWidth)}┬${"─".repeat(detailWidth)}┤`));
-        for (let index = 0; index < this.bodyHeight; index++) {
+        for (let index = 0; index < bodyHeight; index++) {
             lines.push(this.theme.fg("border", "│")
                 + fit(roster[index] ?? "", rosterWidth)
                 + this.theme.fg("border", "│")
@@ -1355,6 +1381,7 @@ export class SubagentFleetComponent {
         return lines.map((line) => truncateToWidth(line, width));
     }
     invalidate() {
+        this.renderedLayout = undefined;
         this.transcriptCache = undefined;
         this.refresh();
     }

package/src/tui/render.d.ts

@@ -39,6 +39,12 @@ export interface AsyncLaneProjection {
 /** Project already-loaded async status facts into one bounded, render-only lane row. */
 export declare function projectAsyncLane(job: AsyncJobState, ...args: [selectedStep?: AsyncJobStep]): AsyncLaneProjection | undefined;
 export declare function widgetRenderKey(job: AsyncJobState, expanded?: boolean): string;
+/** A child's task in one line: its label and task, else its session name without the repeated agent name. */
+export declare function stepTaskSummary(step: {
+    description?: string;
+    label?: string;
+    sessionName?: string;
+}, agentName: string | undefined): string | undefined;
 /** Structural identity of the workflow rows that Fleet can cover. */
 export declare function inlineWorkflowRenderKey(job: AsyncJobState, children: AsyncJobState[]): string;
 /** Presentation-only coverage from the mounted inline Fleet roster, never configuration. */

package/src/tui/render.js

@@ -1104,14 +1104,14 @@ function shouldCollapseSingleChildDetails(job, step) {
         return isCompletedWidgetStepStatus(step.status);
     return false;
 }
-function singleChildTask(job, step) {
+/** A child's task in one line: its label and task, else its session name without the repeated agent name. */
+export function stepTaskSummary(step, agentName) {
     const task = compactTaskText(step.description, step.label);
     if (task)
         return task;
     const sessionName = step.sessionName?.trim();
     if (!sessionName)
         return undefined;
-    const agentName = singleChildAgentName(job, step);
     const sessionTask = stripRepeatedAgentPrefix(sessionName, agentName);
     return sessionTask === agentName ? undefined : compactTaskText(sessionTask);
 }
@@ -2223,7 +2223,7 @@ function foregroundStyleWidgetStepLines(job, theme, step, itemTitle, index, tota
     const lane = projectAsyncLane(job, step);
     if (lane)
         lines.push(...formatLaneProjectionLines(lane, theme, detailIndent));
-    const task = collapseDetails ? singleChildTask(job, step) : compactTaskText(step.description, step.label);
+    const task = collapseDetails ? stepTaskSummary(step, displayName) : compactTaskText(step.description, step.label);
     if (task)
         lines.push(`${detailIndent}${theme.fg("dim", `task: ${task}`)}`);
     const activity = widgetStepActivityLine(step, width, expanded, job.updatedAt);

package/src/tui/subagent-messages.js

@@ -183,6 +183,7 @@ const MESSAGE_VIEWS = new Map([
     ["subagent-wait-subscription", readsContent("result", (message) => waitSubscriptionHeadline(message.details))],
     ["subagent-incremental-child-notify", readsContent("result", workflowChildHeadline)],
     ["subagent-workflow-result-write-failed", readsContent("result", () => ["workflow result ", { status: "save failed" }])],
+    ["subagent-auto-resume", readsContent("result", () => ["workflow auto-resume ", { status: "failed" }])],
     [SUBAGENT_CONTROL_MESSAGE_TYPE, readsContent("attention", (message) => controlNoticeHeadline(message.details))],
     [SUBAGENT_STEERING_MESSAGE_TYPE, readsContent("attention", (message) => steeringNoticeHeadline(message.details))],
     [SUBAGENT_WATCHDOG_WARNING_TYPE, (message) => watchdogWarningView(message.details, contentText(message.content))],

package/src/workflows/scripted-workflow.d.ts

@@ -60,7 +60,7 @@ export interface WorkflowScriptChildResult {
     };
     artifactPaths: string[];
     results?: SingleResult[];
-    /** Came from a runtime-replaced run of the same script (and args, unless named by options.reuseFrom): its saved result, or its still-running child re-attached; this run launched nothing. */
+    /** Came from a runtime-replaced or owner-exited run of the same script (and args, unless named by options.reuseFrom): its saved result, or its still-running child re-attached; this run launched nothing. */
     reused?: boolean;
 }
 export interface WorkflowScriptTraceEntry {

package/src/workflows/structured-workflow-scripts.d.ts

@@ -4,6 +4,7 @@
  * and never becomes code. Scripts run on the ordinary workflow runtime.
  */
 export type StructuredWorkflowKind = "tasks" | "chain";
+export declare const TOP_LEVEL_CONTROLS_HINT = " Put worktree and other child controls on the subagent call itself; they apply to every child.";
 export declare function isPlainRecord(value: unknown): value is Record<string, unknown>;
 /** Validate exact data shapes and expand them into a package-owned workflow script. */
 export declare function buildStructuredWorkflowScript(kind: StructuredWorkflowKind, steps: unknown, originalTask: string | undefined): string;

package/src/workflows/structured-workflow-scripts.js

@@ -7,6 +7,7 @@ const OUTPUT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const PLACEHOLDER_PATTERN = /\{(?:task|previous|outputs\.([A-Za-z_][A-Za-z0-9_]*))\}/g;
 /** Optional per-child launch fields copied verbatim onto the generated runs.all item. */
 const CHILD_FIELDS = ["cwd", "model"];
+export const TOP_LEVEL_CONTROLS_HINT = " Put worktree and other child controls on the subagent call itself; they apply to every child.";
 export function isPlainRecord(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
@@ -97,7 +98,7 @@ function buildTasksScript(steps, originalTask) {
         throw new Error("tasks must be a non-empty array of { agent, task } items.");
     const children = steps.map((item, index) => {
         const path = `tasks[${index}]`;
-        const record = exactFields(item, path, ["agent", "task", ...CHILD_FIELDS], "Each tasks item accepts agent and task, plus optional cwd and model.");
+        const record = exactFields(item, path, ["agent", "task", ...CHILD_FIELDS], `Each tasks item accepts agent and task, plus optional cwd and model.${TOP_LEVEL_CONTROLS_HINT}`);
         const agent = nonEmptyString(record.agent, `${path}.agent`);
         const task = nonEmptyString(record.task, `${path}.task`);
         const taskExpression = compileTemplate(task, {
@@ -131,20 +132,20 @@ function buildChainScript(steps, originalTask) {
         let stepChildren;
         let outputName;
         if (isPlainRecord(step) && Object.hasOwn(step, "parallel")) {
-            const record = exactFields(step, path, ["parallel"], "A parallel step accepts only parallel; as is supported on sequential steps only.");
+            const record = exactFields(step, path, ["parallel"], `A parallel step accepts only parallel; as is supported on sequential steps only.${TOP_LEVEL_CONTROLS_HINT}`);
             const items = record.parallel;
             if (!Array.isArray(items) || items.length === 0)
                 throw new Error(`${path}.parallel must be a non-empty array of { agent, task } items.`);
             stepChildren = items.map((item, itemIndex) => {
                 const itemPath = `${path}.parallel[${itemIndex}]`;
-                const itemRecord = exactFields(item, itemPath, ["agent", "task", ...CHILD_FIELDS], "Each parallel item accepts agent and task, plus optional cwd and model.");
+                const itemRecord = exactFields(item, itemPath, ["agent", "task", ...CHILD_FIELDS], `Each parallel item accepts agent and task, plus optional cwd and model.${TOP_LEVEL_CONTROLS_HINT}`);
                 const agent = nonEmptyString(itemRecord.agent, `${itemPath}.agent`);
                 const task = nonEmptyString(itemRecord.task, `${itemPath}.task`);
                 return { key: `step-${number}-${itemIndex + 1}`, agent, fields: childFields(itemRecord, itemPath), taskExpression: compileTemplate(task, { path: `${itemPath}.task`, hasOriginalTask, previous, outputs }) };
             });
         }
         else {
-            const record = exactFields(step, path, ["agent", "task", "as", ...CHILD_FIELDS], "A sequential step accepts agent, task, as, cwd and model; a parallel step accepts only parallel.");
+            const record = exactFields(step, path, ["agent", "task", "as", ...CHILD_FIELDS], `A sequential step accepts agent, task, as, cwd and model; a parallel step accepts only parallel.${TOP_LEVEL_CONTROLS_HINT}`);
             const agent = nonEmptyString(record.agent, `${path}.agent`);
             let task;
             if (record.task === undefined) {

package/src/workflows/workflow-auto-resume.d.ts

@@ -0,0 +1,32 @@
+import { type PreparedWorkflowResume, type WorkflowResumeRefusalReason } from "./workflow-resume.ts";
+/** Custom message posted when an auto-resume launch did not start. */
+export declare const WORKFLOW_AUTO_RESUME_MESSAGE_TYPE = "subagent-auto-resume";
+/** One planned auto-resume: its claim is held from session start until the launch starts or is cancelled. */
+export interface PendingWorkflowAutoResume {
+    readonly sessionId: string;
+    /** The extension runtime that planned it. */
+    readonly owner: object;
+    readonly prepared: PreparedWorkflowResume;
+    /** `cancelled` before it started: its run id is reused by the next scan. */
+    state: "pending" | "started" | "cancelled";
+}
+/** Cancels matching launches that have not started and gives their claims back, synchronously. */
+export declare function cancelPendingWorkflowAutoResumes(match: (entry: PendingWorkflowAutoResume) => boolean): void;
+/** A cancelled entry stays recorded until its session's next scan reuses its run id. */
+export declare function finishWorkflowAutoResume(entry: PendingWorkflowAutoResume): void;
+/**
+ * Claims this session's interrupted top-level workflows for auto-resume. Synchronous and bounded:
+ * one listing of the session's terminal index, reads only for runs that ended in the last 24 h,
+ * then the cheap filters before any claim. A refusal is recorded in the run, so each run gets one
+ * automatic attempt; the launch itself happens later, off session start. Launches of this session
+ * that another runtime (or an earlier session start) planned but did not start are cancelled first,
+ * so their claims do not hide the runs from this scan.
+ */
+export declare function planWorkflowAutoResumes(input: {
+    asyncDirRoot: string;
+    currentSessionId: string;
+    now: number;
+    owner: object;
+}): PendingWorkflowAutoResume[];
+/** The one line posted when an auto-resume launch did not start. */
+export declare function autoResumeFailureText(sourceRunId: string, refusal: Pick<WorkflowResumeRefusalReason, "reason" | "byHand">): string;

package/src/workflows/workflow-auto-resume.js

@@ -0,0 +1,102 @@
+import * as path from "node:path";
+import { readRecentTerminalRunIndex } from "../runs/background/terminal-run-index.js";
+import { readStatus } from "../shared/utils.js";
+import { hasWorkflowResumeRefusal, recordWorkflowResumeRefusal, refusalSentence, releaseWorkflowResumeClaim, workflowResumeClaimState } from "./workflow-resume-claim.js";
+import { prepareWorkflowResume } from "./workflow-resume.js";
+import { isReusableWorkflowStopCause, WORKFLOW_STOP_CAUSE_OWNER_EXITED } from "./workflow-stop-cause.js";
+/** Custom message posted when an auto-resume launch did not start. */
+export const WORKFLOW_AUTO_RESUME_MESSAGE_TYPE = "subagent-auto-resume";
+/** Interrupted workflows older than this are left for a resume by hand. */
+const AUTO_RESUME_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const AUTO_RESUME_SCAN_LIMIT = 50;
+/** When the run was interrupted: the dead owner's last update, or the runtime replacement. */
+function interruptedAt(status) {
+    return status.workflow?.stopCause === WORKFLOW_STOP_CAUSE_OWNER_EXITED ? status.workflow.ownerExitedAt : status.endedAt;
+}
+// Shared by every runtime in the process: a reload's new runtime must see the old runtime's pending claims.
+const registryKey = Symbol.for("pi-subagents.workflow-auto-resume.v1");
+const registryGlobal = globalThis;
+const pendingAutoResumes = registryGlobal[registryKey] ?? (registryGlobal[registryKey] = new Set());
+/** Cancels matching launches that have not started and gives their claims back, synchronously. */
+export function cancelPendingWorkflowAutoResumes(match) {
+    for (const entry of pendingAutoResumes) {
+        if (entry.state !== "pending" || !match(entry))
+            continue;
+        // It stays in the set, so the next scan of its session claims the run again under the same id and
+        // a notice that already said `Auto-resumed as <id>.` stays true.
+        entry.state = "cancelled";
+        try {
+            releaseWorkflowResumeClaim(entry.prepared.sourceAsyncDir, entry.prepared.newRunId);
+        }
+        catch (error) {
+            console.error(`Failed to give back the auto-resume claim of workflow ${entry.prepared.sourceRunId}:`, error);
+        }
+    }
+}
+/** A cancelled entry stays recorded until its session's next scan reuses its run id. */
+export function finishWorkflowAutoResume(entry) {
+    if (entry.state !== "cancelled")
+        pendingAutoResumes.delete(entry);
+}
+/**
+ * Claims this session's interrupted top-level workflows for auto-resume. Synchronous and bounded:
+ * one listing of the session's terminal index, reads only for runs that ended in the last 24 h,
+ * then the cheap filters before any claim. A refusal is recorded in the run, so each run gets one
+ * automatic attempt; the launch itself happens later, off session start. Launches of this session
+ * that another runtime (or an earlier session start) planned but did not start are cancelled first,
+ * so their claims do not hide the runs from this scan.
+ */
+export function planWorkflowAutoResumes(input) {
+    const { asyncDirRoot, currentSessionId, now } = input;
+    cancelPendingWorkflowAutoResumes((entry) => entry.sessionId === currentSessionId);
+    const reusableRunIds = new Map();
+    for (const entry of pendingAutoResumes) {
+        if (entry.sessionId !== currentSessionId || entry.state !== "cancelled")
+            continue;
+        reusableRunIds.set(entry.prepared.sourceRunId, entry.prepared.newRunId);
+        pendingAutoResumes.delete(entry);
+    }
+    let runIds;
+    try {
+        runIds = readRecentTerminalRunIndex(asyncDirRoot, { sessionId: currentSessionId, limit: AUTO_RESUME_SCAN_LIMIT, endedAfter: now - AUTO_RESUME_MAX_AGE_MS });
+    }
+    catch (error) {
+        console.error("Failed to read interrupted workflows for auto-resume:", error);
+        return [];
+    }
+    const planned = [];
+    for (const runId of runIds) {
+        const asyncDir = path.join(asyncDirRoot, runId);
+        try {
+            const status = readStatus(asyncDir);
+            if (!status || status.mode !== "workflow" || status.parentWorkflowRunId !== undefined || status.sessionId !== currentSessionId)
+                continue;
+            if (!isReusableWorkflowStopCause(status.workflow?.stopCause))
+                continue;
+            const at = interruptedAt(status);
+            if (at === undefined || now - at > AUTO_RESUME_MAX_AGE_MS)
+                continue;
+            if (workflowResumeClaimState(asyncDir).kind !== "none" || hasWorkflowResumeRefusal(asyncDir))
+                continue;
+            const preparation = prepareWorkflowResume({ asyncDirRoot, sourceRunId: runId, trigger: "auto", now, currentSessionId, newRunId: reusableRunIds.get(runId) });
+            if (preparation.ok) {
+                const entry = { sessionId: currentSessionId, owner: input.owner, prepared: preparation.prepared, state: "pending" };
+                pendingAutoResumes.add(entry);
+                planned.push(entry);
+                continue;
+            }
+            // Another claimant continues it; nothing to record.
+            if (preparation.code === "claim-busy" || preparation.code === "claim-resumed")
+                continue;
+            recordWorkflowResumeRefusal(asyncDir, { reason: preparation.reason, byHand: preparation.byHand }, now);
+        }
+        catch (error) {
+            console.error(`Failed to prepare auto-resume of workflow ${runId}:`, error);
+        }
+    }
+    return planned;
+}
+/** The one line posted when an auto-resume launch did not start. */
+export function autoResumeFailureText(sourceRunId, refusal) {
+    return `Workflow ${sourceRunId} was not auto-resumed: ${refusalSentence(refusal.reason, refusal.byHand)}`;
+}

package/src/workflows/workflow-launch-record.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The public launch of an async top-level workflow, saved in its run directory so the run can be
+ * relaunched later. A named resource is saved by name (its `runs.host` permit cannot be saved);
+ * structured tasks/chain launches save no params, so they cannot be relaunched from this record.
+ */
+export type WorkflowLaunch = {
+    source: "script" | "resource";
+    params: Record<string, unknown>;
+} | {
+    source: "structured";
+};
+export type WorkflowLaunchRecord = WorkflowLaunch & {
+    version: 1;
+    scriptDigest: string;
+};
+type WorkflowLaunchRecordRead = {
+    ok: true;
+    record: WorkflowLaunchRecord;
+} | {
+    ok: false;
+    missing: boolean;
+    error: string;
+};
+/** Throws on a write failure; the launch must fail rather than start a run it cannot relaunch. */
+export declare function writeWorkflowLaunchRecord(asyncDir: string, record: WorkflowLaunchRecord): void;
+export declare function readWorkflowLaunchRecord(asyncDir: string): WorkflowLaunchRecordRead;
+export {};

package/src/workflows/workflow-launch-record.js

@@ -0,0 +1,48 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writeAtomicJson } from "../shared/atomic-json.js";
+const WORKFLOW_LAUNCH_RECORD_FILE = "launch.json";
+function launchRecordPath(asyncDir) {
+    return path.join(asyncDir, WORKFLOW_LAUNCH_RECORD_FILE);
+}
+/** Throws on a write failure; the launch must fail rather than start a run it cannot relaunch. */
+export function writeWorkflowLaunchRecord(asyncDir, record) {
+    writeAtomicJson(launchRecordPath(asyncDir), record);
+}
+function isPlainObject(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function invalid(error) {
+    return { ok: false, missing: false, error };
+}
+export function readWorkflowLaunchRecord(asyncDir) {
+    let text;
+    try {
+        text = fs.readFileSync(launchRecordPath(asyncDir), "utf-8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { ok: false, missing: true, error: "launch.json is missing" };
+        return invalid(`could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        return invalid(`not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isPlainObject(value))
+        return invalid("not a JSON object");
+    if (value.version !== 1)
+        return invalid("version must be 1");
+    if (typeof value.scriptDigest !== "string" || !value.scriptDigest)
+        return invalid("scriptDigest must be a non-empty string");
+    if (value.source === "structured")
+        return { ok: true, record: { version: 1, source: "structured", scriptDigest: value.scriptDigest } };
+    if (value.source !== "script" && value.source !== "resource")
+        return invalid("source must be \"script\", \"resource\", or \"structured\"");
+    if (!isPlainObject(value.params))
+        return invalid("params must be an object");
+    return { ok: true, record: { version: 1, source: value.source, params: value.params, scriptDigest: value.scriptDigest } };
+}