@ferris1225/pi-subagents 4.1.18 → 4.1.21

package/src/format.ts

@@ -1,179 +1,173 @@
-/**
- * Pure formatting/result helpers shared by the subagent tool and the lookup
- * tools (subagent_wait/status): usage rendering, completion blocks, synthetic
- * result constructors, and run-id matching.
- */
-
-import type { AgentConfig } from "./agents.ts";
-import { formatTaskSummary } from "./monitor.ts";
-import { emptyUsage } from "./rpc-run.ts";
-import {
-	getResultOutput,
-	isFailedResult,
-	truncateResultOutput,
-	writeResultArtifact,
-	type SingleResult,
-	type UsageStats,
-} from "./spawn.ts";
-
-export function queuedResult(agent: AgentConfig, task: string, thinking?: string): SingleResult {
-	return {
-		agent: agent.name,
-		task,
-		exitCode: -1,
-		messages: [],
-		stderr: "",
-		usage: emptyUsage(),
-		model: agent.model,
-		...(thinking ? { thinking } : {}),
-	};
-}
-
-export function failedStartResult(agentName: string, task: string, errorMessage: string): SingleResult {
-	return {
-		agent: agentName,
-		task,
-		exitCode: 1,
-		messages: [],
-		stderr: errorMessage,
-		usage: emptyUsage(),
-		errorMessage,
-		dispatchFailed: true,
-	};
-}
-
-/** Failed result for a background task that crashed with an exception (spawn
- * infra, delivery API, ...) instead of returning a normal result. */
-export function dispatchFailedResult(agent: AgentConfig, task: string, error: unknown, thinking?: string): SingleResult {
-	const errorMessage = error instanceof Error ? error.message : String(error);
-	return {
-		...queuedResult(agent, task, thinking),
-		exitCode: 1,
-		stderr: errorMessage,
-		stopReason: "error",
-		errorMessage,
-		dispatchFailed: true,
-	};
-}
-
-function formatTokens(count: number): string {
-	if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
-	if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
-	return String(count);
-}
-
-export function formatUsage(usage: UsageStats): string {
-	const parts: string[] = [];
-	if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
-	if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
-	if (usage.output) parts.push(`↓${formatTokens(usage.output)}`);
-	if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
-	if (usage.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
-	if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
-	return parts.join(" ");
-}
-
-export interface CompletionFormatOptions {
-	/** Include individual failed-tool errors. Reserved for explicit status lookup. */
-	failedToolDetails?: boolean;
-	/** Project-scoped directory the full result is written to when the output
-	 * is truncated: <projectRoot>/results. */
-	resultRoot?: string;
-}
-
-export function formatCompletionBlock(
-	result: SingleResult,
-	maxResultLines: number,
-	options: CompletionFormatOptions = {},
-): string {
-	const failed = isFailedResult(result);
-	const failedTools = result.failedTools ?? [];
-	const status = failed
-		? "failed"
-		: options.failedToolDetails && failedTools.length > 0
-			? `completed with ${failedTools.length} failed tool call${failedTools.length === 1 ? "" : "s"}`
-			: "completed";
-	const usage = formatUsage(result.usage);
-	const output = getResultOutput(result);
-	const { text, truncated } = truncateResultOutput(output, maxResultLines);const fallbackNote = result.modelFallbackFrom
-		? ` (selected model ${result.modelFallbackFrom} failed → main ${result.model ?? "dynamic default"})`
-		: "";
-	const startupRetryNote = result.startupRetries
-		? ` (recovered after ${result.startupRetries} startup retr${result.startupRetries === 1 ? "y" : "ies"} — concurrent pi startup race)`
-		: "";
-	const runNote = result.runId !== undefined ? ` · run #${result.runId}` : "";
-	const lines = [`### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}${fallbackNote}${startupRetryNote}${runNote}`, "", `Task: ${formatTaskSummary(result.task, 80, false)}`, ""];
-	if (result.isolation === "worktree") {
-		const isolation =
-			result.integrationStatus === "integrated"
-				? "worktree · changes integrated into the original working tree"
-				: result.integrationStatus === "no_changes"
-					? "worktree · no changes; temporary worktree removed"
-					: result.integrationStatus === "retained"
-						? result.integrationApplied
-							? "worktree · changes applied, but cleanup failed; recovery artifacts retained"
-							: "worktree · integration failed; recovery artifacts retained"
-						: "worktree · isolated";
-		lines.push(`Isolation: ${isolation}`);
-		if (result.integrationWorktreePath) lines.push(`Retained worktree: ${result.integrationWorktreePath}`);
-		if (result.integrationPatchPath) lines.push(`Retained patch: ${result.integrationPatchPath}`);
-		if (result.integrationError) lines.push(`Integration error: ${result.integrationError}`);
-		lines.push("");
-	}
-	lines.push(text);
-	// Failed-tool diagnostics are deliberate opt-in via subagent_status: agents
-	// report their own verification in the output above, and a transient failed
-	// call (no-match grep, rejected edit) is noise in an automatic delivery.
-	if (options.failedToolDetails && failedTools.length > 0) {
-		lines.push(
-			"",
-			`⚠ ${failedTools.length} failed tool call${failedTools.length === 1 ? "" : "s"}:`,
-			...failedTools.map((tool) => `- ${tool.toolName}: ${tool.error.trim() || "(no output)"}`),
-		);
-	}
-	if (truncated) {
-		// The full text lives on disk so the main agent can read it on demand.
-		const artifact = options.resultRoot
-			? writeResultArtifact(output, result.agent, options.resultRoot)
-			: "(result root unavailable)";
-		lines.push("", `(output truncated to ${maxResultLines} lines; full result: ${artifact})`);
-	}
-	return lines.join("\n");
-}
-
-/** Instruction appended to a model-level failure: the sub-agent's provider never
- * produced usable output (or the run stalled), so the task is handed back to the
- * main window instead of being left as a dead failure. When the run preserved a
- * session with earlier work (and the run id is known), steer the main agent to
- * RESUME it in-context once a model is available, instead of re-dispatching
- * fresh (which would re-scan everything). */
-export function modelLevelTakeoverNote(result: SingleResult, opts?: { runId?: number }): string {
-	const retry = result.modelFallbackFrom ? ", and the current main model also failed" : "";
-	const detail = result.errorMessage?.trim();
-	const cause = detail
-		? `its model/provider call failed (${detail})`
-		: "its model was unavailable or failed (or the run stalled)";
-	const sessionPreserved = Boolean(result.sessionDir && result.sessionId) && opts?.runId !== undefined;
-	const recovery = sessionPreserved
-		? ` The sub-agent's earlier work in this run is preserved. Once a model is available again, call subagent_control with { action: "resume", id: ${opts!.runId} } to CONTINUE it in-context (it keeps the same run id and does not re-scan), or execute the task in the main window with your own tools.`
-		: ` Please execute this task in the main window with your own tools; do not re-dispatch it as a sub-agent.`;
-	return `The sub-agent could not complete this task: ${cause}${retry}.${recovery}`;
-}
-
-/** Instruction appended whenever a failing gate verdict is delivered: the
- * findings return to the main agent, which owns the fix decision — the runtime
- * never auto-fixes. Stating it at this exact decision point keeps the main
- * agent from relaying the findings to the user and stopping. */
-export function reviewFailFollowUpNote(): string {
-	return "This gate failed and the findings are yours to resolve now: fix them inline or dispatch a worker briefed with these fix instructions, then re-verify the change. Ask the user only before a genuinely destructive or scope-changing fix; do not deliver while a finding stands.";
-}
-
-/** Resolve a run-id request to actual ids: an exact numeric match always wins
- * (so "1" never fans out to 10, 11, …); only when no exact match exists does a
- * prefix match run, as a convenience for partial ids. Keeps single-digit lookups
- * from returning — or, for subagent_stop, acting on — a whole prefix family. */
-export function matchRunIds(ids: number[], requested: string): number[] {
-	const exact = ids.filter((id) => String(id) === requested);
-	if (exact.length > 0) return exact;
-	return ids.filter((id) => String(id).startsWith(requested));
-}
+/**
+ * Pure formatting/result helpers shared by the subagent tool and completion
+ * delivery: usage rendering, completion blocks, synthetic result constructors,
+ * and run-id matching.
+ */
+
+import type { AgentConfig } from "./agents.ts";
+import { formatTaskSummary } from "./monitor.ts";
+import { emptyUsage } from "./rpc-run.ts";
+import {
+	getResultOutput,
+	isFailedResult,
+	truncateResultOutput,
+	writeResultArtifact,
+	type SingleResult,
+	type UsageStats,
+} from "./spawn.ts";
+
+export function queuedResult(agent: AgentConfig, task: string, thinking?: string): SingleResult {
+	return {
+		agent: agent.name,
+		task,
+		exitCode: -1,
+		messages: [],
+		stderr: "",
+		usage: emptyUsage(),
+		model: agent.model,
+		...(thinking ? { thinking } : {}),
+	};
+}
+
+export function failedStartResult(agentName: string, task: string, errorMessage: string): SingleResult {
+	return {
+		agent: agentName,
+		task,
+		exitCode: 1,
+		messages: [],
+		stderr: errorMessage,
+		usage: emptyUsage(),
+		errorMessage,
+		dispatchFailed: true,
+	};
+}
+
+/** Failed result for a background task that crashed with an exception (spawn
+ * infra, delivery API, ...) instead of returning a normal result. */
+export function dispatchFailedResult(agent: AgentConfig, task: string, error: unknown, thinking?: string): SingleResult {
+	const errorMessage = error instanceof Error ? error.message : String(error);
+	return {
+		...queuedResult(agent, task, thinking),
+		exitCode: 1,
+		stderr: errorMessage,
+		stopReason: "error",
+		errorMessage,
+		dispatchFailed: true,
+	};
+}
+
+function formatTokens(count: number): string {
+	if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
+	if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
+	return String(count);
+}
+
+export function formatUsage(usage: UsageStats): string {
+	const parts: string[] = [];
+	if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
+	if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
+	if (usage.output) parts.push(`↓${formatTokens(usage.output)}`);
+	if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
+	if (usage.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
+	if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
+	return parts.join(" ");
+}
+
+export interface CompletionFormatOptions {
+	/** Project-scoped directory the full result is written to when the output
+	 * is truncated: <projectRoot>/results. */
+	resultRoot?: string;
+}
+
+export function formatCompletionBlock(
+	result: SingleResult,
+	maxResultLines: number,
+	options: CompletionFormatOptions = {},
+): string {
+	const failed = isFailedResult(result);
+	const failedTools = result.failedTools ?? [];
+	const status = failed ? "failed" : "completed";
+	const usage = formatUsage(result.usage);
+	const output = getResultOutput(result);
+	const { text, truncated } = truncateResultOutput(output, maxResultLines);const fallbackNote = result.modelFallbackFrom
+		? ` (selected model ${result.modelFallbackFrom} failed → main ${result.model ?? "dynamic default"})`
+		: "";
+	const startupRetryNote = result.startupRetries
+		? ` (recovered after ${result.startupRetries} startup retr${result.startupRetries === 1 ? "y" : "ies"} — concurrent pi startup race)`
+		: "";
+	const runNote = result.runId !== undefined ? ` · run #${result.runId}` : "";
+	const lines = [`### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}${fallbackNote}${startupRetryNote}${runNote}`, "", `Task: ${formatTaskSummary(result.task, 80, false)}`, ""];
+	if (result.isolation === "worktree") {
+		const isolation =
+			result.integrationStatus === "integrated"
+				? "worktree · changes integrated into the original working tree"
+				: result.integrationStatus === "no_changes"
+					? "worktree · no changes; temporary worktree removed"
+					: result.integrationStatus === "retained"
+						? result.integrationApplied
+							? "worktree · changes applied, but cleanup failed; recovery artifacts retained"
+							: "worktree · integration failed; recovery artifacts retained"
+						: "worktree · isolated";
+		lines.push(`Isolation: ${isolation}`);
+		if (result.integrationWorktreePath) lines.push(`Retained worktree: ${result.integrationWorktreePath}`);
+		if (result.integrationPatchPath) lines.push(`Retained patch: ${result.integrationPatchPath}`);
+		if (result.integrationError) lines.push(`Integration error: ${result.integrationError}`);
+		lines.push("");
+	}
+	lines.push(text);
+	// Failed-tool diagnostics ride along only when the run itself failed: they
+	// explain the failure, while on a successful run a transient failed call
+	// (no-match grep, rejected edit) is noise the agent already worked around.
+	if (failed && failedTools.length > 0) {
+		lines.push(
+			"",
+			`⚠ ${failedTools.length} failed tool call${failedTools.length === 1 ? "" : "s"}:`,
+			...failedTools.map((tool) => `- ${tool.toolName}: ${tool.error.trim() || "(no output)"}`),
+		);
+	}
+	if (truncated) {
+		// The full text lives on disk so the main agent can read it on demand.
+		const artifact = options.resultRoot
+			? writeResultArtifact(output, result.agent, options.resultRoot)
+			: "(result root unavailable)";
+		lines.push("", `(output truncated to ${maxResultLines} lines; full result: ${artifact})`);
+	}
+	return lines.join("\n");
+}
+
+/** Instruction appended to a model-level failure: the sub-agent's provider never
+ * produced usable output (or the run stalled), so the task is handed back to the
+ * main window instead of being left as a dead failure. When the run preserved a
+ * session with earlier work (and the run id is known), steer the main agent to
+ * RESUME it in-context once a model is available, instead of re-dispatching
+ * fresh (which would re-scan everything). */
+export function modelLevelTakeoverNote(result: SingleResult, opts?: { runId?: number }): string {
+	const retry = result.modelFallbackFrom ? ", and the current main model also failed" : "";
+	const detail = result.errorMessage?.trim();
+	const cause = detail
+		? `its model/provider call failed (${detail})`
+		: "its model was unavailable or failed (or the run stalled)";
+	const sessionPreserved = Boolean(result.sessionDir && result.sessionId) && opts?.runId !== undefined;
+	const recovery = sessionPreserved
+		? ` The sub-agent's earlier work in this run is preserved. Once a model is available again, call subagent_control with { action: "resume", id: ${opts!.runId} } to CONTINUE it in-context (it keeps the same run id and does not re-scan), or execute the task in the main window with your own tools.`
+		: ` Please execute this task in the main window with your own tools; do not re-dispatch it as a sub-agent.`;
+	return `The sub-agent could not complete this task: ${cause}${retry}.${recovery}`;
+}
+
+/** Instruction appended whenever a failing gate verdict is delivered: the
+ * findings return to the main agent, which owns the fix decision — the runtime
+ * never auto-fixes. Stating it at this exact decision point keeps the main
+ * agent from relaying the findings to the user and stopping. */
+export function reviewFailFollowUpNote(): string {
+	return "This gate failed and the findings are yours to resolve now: fix them inline or dispatch a worker briefed with these fix instructions, then re-verify the change. Ask the user only before a genuinely destructive or scope-changing fix; do not deliver while a finding stands.";
+}
+
+/** Resolve a run-id request to actual ids: an exact numeric match always wins
+ * (so "1" never fans out to 10, 11, …); only when no exact match exists does a
+ * prefix match run, as a convenience for partial ids. Keeps single-digit lookups
+ * from returning — or, for subagent_stop, acting on — a whole prefix family. */
+export function matchRunIds(ids: number[], requested: string): number[] {
+	const exact = ids.filter((id) => String(id) === requested);
+	if (exact.length > 0) return exact;
+	return ids.filter((id) => String(id).startsWith(requested));
+}

package/src/index.ts

@@ -5,7 +5,7 @@
  * The heavy lifting lives in focused modules:
  *   - dispatch.ts         — tool contract, managed role policy, internal steps
  *   - thread-lifecycle.ts — stable generations, controls, final integration/delivery
- *   - tools.ts            — subagent_control / subagent_wait / status / stop
+ *   - tools.ts            — subagent_control / subagent_stop
  *   - announcements.ts — session-start recovery, notices, and widget install
  *   - widget.ts        — active-only TUI run status
  *   - runtime.ts       — shared per-session state
@@ -78,16 +78,16 @@ export default function (pi: ExtensionAPI): void {
 
 	registerAnnouncements(pi, runtime);
 
-	// Durable bootstrap: restore parked/settled threads from the manifest so a
-	// reload or restart keeps status and resume working, then age out old
-	// records and sweep leaked temp/state directories. Fire-and-forget; every
-	// stage is best-effort and never blocks registration.
+	// Durable bootstrap: restore parked threads from the manifest so a reload or
+	// restart keeps status and resume working, then age out old records and sweep
+	// leaked temp/state directories. Registration never blocks on it and every
+	// stage is best-effort; the restore pass is published as runtime.durableRestore
+	// so the tools and the session-start notice wait for it instead of racing it.
 	void bootstrapDurableState(runtime);
 
 	// Proactive dispatch: inject the delegation directive into the parent system prompt.
 	pi.on("before_agent_start", async (event, ctx) => {
 		const config = await loadConfig(configPath);
-		if (!config.proactiveInjection) return undefined;
 		const { agents } = discoverAgents(ctx.cwd, {
 			scope: config.agentScope,
 			enabledNames: config.enabledAgents,

package/src/models.ts

@@ -45,7 +45,6 @@ export interface ResolvedAgentModelRoute {
 export interface AgentModelRouteInput {
 	selectedRef?: string;
 	mainRef?: string;
-	declaredDefaultRef?: string;
 	/** When supplied, a configured selection outside this live set is skipped. */
 	availableRefs?: readonly string[];
 }
@@ -107,20 +106,19 @@ export function filterUnavailableModelOverrides(
  *
  * configured selection -> current main-window model
  *
- * Without an override, current main is primary; the agent-declared default is
- * used only when no main model exists. A configured selection that Pi no longer
- * reports as available is skipped immediately instead of spawning a doomed child.
+ * Without an override the current main model is primary, so an agent never
+ * pins its own model. A configured selection that Pi no longer reports as
+ * available is skipped immediately instead of spawning a doomed child.
  */
 export function resolveAgentModelRoute(input: AgentModelRouteInput): ResolvedAgentModelRoute {
 	const selectedRef = cleanModelRef(input.selectedRef);
 	const mainRef = cleanModelRef(input.mainRef);
-	const declaredDefaultRef = cleanModelRef(input.declaredDefaultRef);
 	const available = input.availableRefs
 		? new Set(input.availableRefs.map((ref) => ref.trim()).filter(Boolean))
 		: undefined;
 	const selectedAvailable = !selectedRef || !available || available.has(selectedRef);
 	const usableSelectedRef = selectedAvailable ? selectedRef : undefined;
-	const primaryRef = usableSelectedRef ?? mainRef ?? declaredDefaultRef;
+	const primaryRef = usableSelectedRef ?? mainRef;
 	const ordered = [primaryRef, usableSelectedRef && usableSelectedRef !== mainRef ? mainRef : undefined];
 	const candidateRefs = [...new Set(ordered.filter((ref): ref is string => Boolean(ref)))];
 	return {

package/src/monitor.ts

@@ -22,6 +22,16 @@ export type RunStatus = "queued" | "running" | "interrupting" | "parked" | "done
 export type ContinuationKind = "resume-retained" | "resume-appended";
 export type WorkflowStageStatus = "done" | "active" | "pending" | "changes" | "failed";
 
+/** Why a queued run has produced no output yet. Three genuinely different
+ * situations used to be reported as one "queued": waiting for a free process
+ * slot (real pool pacing), serialized behind the shared-checkout repository
+ * write lane (a slot is free — the wait is write serialization), and already
+ * starting its child process (a slot is held; output is seconds away).
+ * Conflating them taught the parent model that the pool was exhausted when it
+ * was not, so it stopped dispatching. Meaningful only while status is
+ * "queued"; cleared on every transition out of it. */
+export type RunWaitReason = "process-slot" | "repository-lane" | "starting";
+
 /** Ephemeral projection of one real or currently planned managed stage. It is
  * live monitor state only; durable results remain the per-run chain records. */
 export interface WorkflowStage {
@@ -58,6 +68,8 @@ export interface RunView {
 	 * one isolated worktree; changes when a continuation worktree is created. */
 	worktreeId?: string;
 	status: RunStatus;
+	/** What a queued run is actually waiting for; see RunWaitReason. */
+	waitReason?: RunWaitReason;
 	usage: UsageStats;
 	/** Concise current activity ("thinking", "read src/index.ts"); last writer wins. */
 	activity?: string;
@@ -93,6 +105,10 @@ export interface RunChainMeta {
 	isolation?: IsolationMode;
 	worktreeId?: string;
 	continuationKind?: ContinuationKind;
+	/** Initial wait reason; defaults to "process-slot" (a fresh dispatch enters
+	 * the process queue). Workflow-internal children pass "starting" because
+	 * they spawn immediately and never wait for a slot. */
+	waitReason?: RunWaitReason;
 }
 
 // ---------------------------------------------------------------------------
@@ -247,13 +263,16 @@ export const RUN_LABEL_MAX = 32;
 
 /**
  * Short content label for a run, derived from its task: the single most
- * distinguishing fragment (path, quoted phrase, symbol) so concurrent same-agent
- * runs are told apart by WHAT they do, not just their run id. A long path keeps
- * its tail (the filename is the recognisable part); a task with no recognizable
- * fragment falls back to a head slice of its prose. Grapheme-safe.
+ * distinguishing fragment so concurrent same-agent runs are told apart by WHAT
+ * they do, not just their run id. A file/directory path outranks other
+ * fragment kinds (a kebab-case word like "edge-case" never beats
+ * "tests/config.test.ts"); a long path keeps its tail (the filename is the
+ * recognisable part); a task with no recognizable fragment falls back to a
+ * head slice of its prose. Grapheme-safe.
  */
 export function runLabel(task: string): string {
-	const fragment = extractKeyFragments(task)[0];
+	const fragments = extractKeyFragments(task);
+	const fragment = fragments.find((candidate) => /[\\/]|\.[A-Za-z0-9]{1,5}$/.test(candidate)) ?? fragments[0];
 	const src = fragment ?? stripVTControlCharacters(task).replace(/\s+/g, " ").trim();
 	if (visibleWidth(src) <= RUN_LABEL_MAX) return src;
 	const chars = [...graphemeSegmenter.segment(src)].map((s) => s.segment);
@@ -388,7 +407,11 @@ export function formatToolActivity(toolName: string, args: unknown): string {
 	};
 	let target: string;
 	switch (toolName) {
+		// Pi ships one shell tool per platform flavor, all with a `command`
+		// parameter: a Windows parent that swapped bash for powershell must still
+		// show the command it is running, not a bare tool name.
 		case "bash":
+		case "powershell":
 		case "shell":
 			target = pick("command");
 			break;
@@ -476,6 +499,7 @@ export class MonitorStore {
 			model,
 			thinking,
 			status: "queued",
+			waitReason: meta?.waitReason ?? "process-slot",
 			usage: emptyUsage(),
 			elapsedMs: 0,
 			...(meta?.groupId ? { groupId: meta.groupId } : {}),
@@ -496,6 +520,7 @@ export class MonitorStore {
 		const isExecuting = status === "running" || status === "interrupting";
 		const now = Date.now();
 		run.status = status;
+		if (status !== "queued") run.waitReason = undefined;
 		if (isExecuting && !wasExecuting) {
 			run.startedAt ??= now;
 			run.activeSince = now;
@@ -509,6 +534,15 @@ export class MonitorStore {
 		}
 		this.notify();
 	}
+	/** Record what a still-queued run is actually waiting for, at the exact
+	 * transition owned by the caller (lane wait begins, child process starts). */
+	setWaitReason(id: number, waitReason: RunWaitReason): void {
+		const run = this.find(id);
+		if (!run || run.status !== "queued" || run.waitReason === waitReason) return;
+		run.waitReason = waitReason;
+		this.notify();
+	}
+
 	/** Switch a stable top-level row from one model run to workflow ownership.
 	 * The original role remains for identity; child rows show stage telemetry. */
 	setManagedWorkflow(id: number, active: boolean): void {
@@ -645,6 +679,7 @@ export class MonitorStore {
 					}
 					: {}),
 				status: "queued",
+				waitReason: "process-slot",
 				usage: emptyUsage(),
 				elapsedMs: meta?.elapsedMs ?? 0,
 				continuationKind: meta?.continuationKind,
@@ -662,6 +697,7 @@ export class MonitorStore {
 		if (isolation === "worktree" && meta?.worktreeId) run.worktreeId = meta.worktreeId;
 		else if (isolation !== "worktree") run.worktreeId = undefined;
 		run.status = "queued";
+		run.waitReason = "process-slot";
 		run.usage = emptyUsage();
 		run.activity = undefined;
 		run.managedWorkflow = undefined;
@@ -778,3 +814,18 @@ export function statusLabel(status: RunStatus): string {
 			return "stopped";
 	}
 }
+
+/** Truthful description of why a queued run has produced no output yet, so a
+ * repository-lane wait or a starting child is never mistaken for an exhausted
+ * process pool. Undefined for runs that are not queued. */
+export function runWaitLabel(run: Pick<RunView, "status" | "waitReason">): string | undefined {
+	if (run.status !== "queued") return undefined;
+	switch (run.waitReason) {
+		case "repository-lane":
+			return "waiting for the repository write lane";
+		case "starting":
+			return "starting";
+		default:
+			return "queued for a free process slot";
+	}
+}