pi-crew 0.9.11 → 0.9.13

package/src/extension/registration/commands.ts

@@ -260,6 +260,66 @@ async function handleHealthDashboardAction(ctx: ExtensionCommandContext, selecti
 
 let depsRef: RegisterTeamCommandsDeps | undefined;
 
+/**
+ * Open the pi-crew run dashboard overlay and run its action loop.
+ *
+ * Extracted verbatim from the `team-dashboard` command so it is reusable from
+ * a keyboard shortcut (alt+c, see crew-shortcuts.ts). Takes the base
+ * `ExtensionContext` (the shortcut handler's context) — uses only `hasUI`,
+ * `cwd`, `ui`, and `sessionManager` fields, so both `ExtensionContext` and
+ * `ExtensionCommandContext` satisfy it. Reads run caches via the module-level
+ * `depsRef` (set by `registerTeamCommands`), so it is a no-op if commands
+ * have not been registered yet. `deps` is captured into a local const so the
+ * non-undefined narrowing survives the awaited overlay call.
+ *
+ * The dashboard action helpers (handleMailboxDashboardAction, the viewers,
+ * notifyCommandResult, teamCommandContext/handleTeamTool) are declared for
+ * `ExtensionCommandContext` but only ever read base `ExtensionContext` fields
+ * (verified). The keyboard-shortcut path supplies an `ExtensionContext`, so we
+ * bridge those over-typed helpers with a single cast rather than relaxing
+ * signatures across several modules (some outside this file's scope).
+ */
+export async function openTeamDashboard(ctx: ExtensionContext): Promise<void> {
+	if (!ctx.hasUI) return;
+	const deps = depsRef;
+	if (!deps) return;
+	const cmdCtx = ctx as ExtensionCommandContext;
+	for (;;) {
+		// Extract sessionId for workspace-scoped filtering
+		const sessionId = cmdCtx.sessionManager?.getSessionId?.();
+		const runs = deps.getManifestCache(cmdCtx.cwd).list(50);
+		const uiConfig = loadConfig(cmdCtx.cwd).config.ui;
+		const rightPanel = (uiConfig?.dashboardPlacement ?? DEFAULT_UI.dashboardPlacement) === "right";
+		const width = rightPanel ? Math.min(90, Math.max(40, uiConfig?.dashboardWidth ?? DEFAULT_UI.dashboardWidth)) : "90%";
+		const { RunDashboard } = await ui();
+		const selection = await cmdCtx.ui.custom<RunDashboardSelection | undefined>((tui, theme, _keybindings, done) => new RunDashboard(runs, done, theme, { placement: rightPanel ? "right" : "center", showModel: uiConfig?.showModel, showTokens: uiConfig?.showTokens, showTools: uiConfig?.showTools, snapshotCache: deps.getRunSnapshotCache?.(cmdCtx.cwd), runProvider: () => deps.getManifestCache(cmdCtx.cwd).list(50), registry: deps.getMetricRegistry?.(), workspaceId: sessionId, requestRender: () => requestRenderTarget(tui) }), { overlay: true, overlayOptions: rightPanel ? { width, minWidth: 40, maxHeight: "100%", anchor: "top-right", offsetX: 0, offsetY: 0, margin: { top: 0, right: 0, bottom: 0, left: 0 } } : { width, maxHeight: "90%", anchor: "center", margin: 2 } });
+		if (!selection) return;
+		if (selection.action === "reload") continue;
+		if (selection.action === "notifications-dismiss") {
+			deps.dismissNotifications?.();
+			cmdCtx.ui.notify("pi-crew notifications dismissed.", "info");
+			continue;
+		}
+		if (selection.action === "mailbox-detail") {
+			await handleMailboxDashboardAction(cmdCtx, selection.runId);
+			deps.getRunSnapshotCache?.(cmdCtx.cwd).invalidate(selection.runId);
+			continue;
+		}
+		if (selection.action === "health-recovery" || selection.action === "health-kill-stale" || selection.action === "health-diagnostic-export") {
+			await handleHealthDashboardAction(cmdCtx, selection);
+			deps.getRunSnapshotCache?.(cmdCtx.cwd).invalidate(selection.runId);
+			continue;
+		}
+		if (selection.action === "agent-transcript" && await openTranscriptViewer(cmdCtx, selection.runId)) continue;
+		if (selection.action === "agent-live" && await openLiveConversation(cmdCtx, selection.runId)) continue;
+		if (selection.action === "agent-live") { await notifyCommandResult(cmdCtx, commandText({ content: [{ type: "text", text: "No live agent found for this run." }] })); continue; }
+		const result = selection.action === "api" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-manifest" } }, teamCommandContext(cmdCtx)) : selection.action === "agents" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "agent-dashboard" } }, teamCommandContext(cmdCtx)) : selection.action === "mailbox" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-mailbox" } }, teamCommandContext(cmdCtx)) : selection.action === "agent-events" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-agent-events", limit: 50 } }, teamCommandContext(cmdCtx)) : selection.action === "agent-output" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-agent-output", maxBytes: 32_000 } }, teamCommandContext(cmdCtx)) : selection.action === "agent-transcript" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-agent-transcript" } }, teamCommandContext(cmdCtx)) : // eslint-disable-next-line @typescript-eslint/no-explicit-any
+			await handleTeamTool({ action: selection.action as any, runId: selection.runId }, teamCommandContext(cmdCtx));
+		await notifyCommandResult(cmdCtx, commandText(result));
+		return;
+	}
+}
+
 export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommandsDeps): void {
 	depsRef = deps;
 	pi.registerCommand("teams", {
@@ -497,40 +557,7 @@ export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommand
 	} });
 
 	pi.registerCommand("team-dashboard", { description: "Open a pi-crew run dashboard overlay", handler: async (_args: string, ctx: ExtensionCommandContext) => {
-		for (;;) {
-			// Extract sessionId for workspace-scoped filtering
-			const sessionId = ctx.sessionManager?.getSessionId?.();
-			const runs = deps.getManifestCache(ctx.cwd).list(50);
-			const uiConfig = loadConfig(ctx.cwd).config.ui;
-			const rightPanel = (uiConfig?.dashboardPlacement ?? DEFAULT_UI.dashboardPlacement) === "right";
-			const width = rightPanel ? Math.min(90, Math.max(40, uiConfig?.dashboardWidth ?? DEFAULT_UI.dashboardWidth)) : "90%";
-			const { RunDashboard } = await ui();
-			const selection = await ctx.ui.custom<RunDashboardSelection | undefined>((tui, theme, _keybindings, done) => new RunDashboard(runs, done, theme, { placement: rightPanel ? "right" : "center", showModel: uiConfig?.showModel, showTokens: uiConfig?.showTokens, showTools: uiConfig?.showTools, snapshotCache: deps.getRunSnapshotCache?.(ctx.cwd), runProvider: () => deps.getManifestCache(ctx.cwd).list(50), registry: deps.getMetricRegistry?.(), workspaceId: sessionId, requestRender: () => requestRenderTarget(tui) }), { overlay: true, overlayOptions: rightPanel ? { width, minWidth: 40, maxHeight: "100%", anchor: "top-right", offsetX: 0, offsetY: 0, margin: { top: 0, right: 0, bottom: 0, left: 0 } } : { width, maxHeight: "90%", anchor: "center", margin: 2 } });
-			if (!selection) return;
-			if (selection.action === "reload") continue;
-			if (selection.action === "notifications-dismiss") {
-				deps.dismissNotifications?.();
-				ctx.ui.notify("pi-crew notifications dismissed.", "info");
-				continue;
-			}
-			if (selection.action === "mailbox-detail") {
-				await handleMailboxDashboardAction(ctx, selection.runId);
-				deps.getRunSnapshotCache?.(ctx.cwd).invalidate(selection.runId);
-				continue;
-			}
-			if (selection.action === "health-recovery" || selection.action === "health-kill-stale" || selection.action === "health-diagnostic-export") {
-				await handleHealthDashboardAction(ctx, selection);
-				deps.getRunSnapshotCache?.(ctx.cwd).invalidate(selection.runId);
-				continue;
-			}
-			if (selection.action === "agent-transcript" && await openTranscriptViewer(ctx, selection.runId)) continue;
-			if (selection.action === "agent-live" && await openLiveConversation(ctx, selection.runId)) continue;
-			if (selection.action === "agent-live") { await notifyCommandResult(ctx, commandText({ content: [{ type: "text", text: "No live agent found for this run." }] })); continue; }
-			const result = selection.action === "api" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-manifest" } }, teamCommandContext(ctx)) : selection.action === "agents" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "agent-dashboard" } }, teamCommandContext(ctx)) : selection.action === "mailbox" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-mailbox" } }, teamCommandContext(ctx)) : selection.action === "agent-events" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-agent-events", limit: 50 } }, teamCommandContext(ctx)) : selection.action === "agent-output" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-agent-output", maxBytes: 32_000 } }, teamCommandContext(ctx)) : selection.action === "agent-transcript" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-agent-transcript" } }, teamCommandContext(ctx)) : // eslint-disable-next-line @typescript-eslint/no-explicit-any
-				await handleTeamTool({ action: selection.action as any, runId: selection.runId }, teamCommandContext(ctx));
-			await notifyCommandResult(ctx, commandText(result));
-			return;
-		}
+		await openTeamDashboard(ctx);
 	} });
 
 	pi.registerCommand("team-mascot", { description: "Show an animated mascot splash", handler: async (args: string, ctx: ExtensionCommandContext) => {

package/src/extension/team-tool/chain-dispatch.ts

@@ -0,0 +1,103 @@
+/**
+ * Team-tool entry point for the `chain` feature.
+ *
+ * Dispatched from `handleRun` (run.ts) via an early-return guard:
+ *   if (params.chain) → handleChainRun(params, ctx, handleRun)
+ *
+ * `handleRun` is passed by reference (NOT imported) to break the
+ * run.ts ↔ chain-dispatch.ts import cycle. This file imports only
+ * chain-runner, handoff-manager, chain-executor, and the shared
+ * tool-result helpers — none of which import run.ts.
+ *
+ * @see src/extension/team-tool/chain-executor.ts (ChainTeamRunExecutor)
+ * @see src/runtime/chain-runner.ts (ChainRunner.runChain, parseChainString)
+ */
+
+import { ChainRunner, parseChainString } from "../../runtime/chain-runner.ts";
+import { HandoffManager } from "../../runtime/handoff-manager.ts";
+import { ChainTeamRunExecutor, type HandleRunFn } from "./chain-executor.ts";
+import { result, type TeamContext } from "./context.ts";
+import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
+import type { PiTeamsToolResult } from "../tool-result.ts";
+
+/**
+ * Execute a chain expression (`"a -> b -> c"`). Each step runs a real team run
+ * via the injected `handleRun`, with handoff context passed forward through the
+ * goal text. Returns a multi-line summary plus structured `data` for the TUI.
+ *
+ * @param params  - Must contain `chain`. `team`/`workflow`/`model` are forwarded
+ *                  as per-step overrides when a step does not declare its own.
+ * @param ctx     - The team tool context (cwd is used to load run manifests).
+ * @param handleRun - The run.ts `handleRun` function reference (injected).
+ */
+export async function handleChainRun(
+	params: TeamToolParamsValue,
+	ctx: TeamContext,
+	handleRun: HandleRunFn,
+): Promise<PiTeamsToolResult> {
+	const chainString = params.chain;
+	if (!chainString || chainString.trim().length === 0) {
+		return result("Chain expression is empty.", { action: "run", status: "error" }, true);
+	}
+
+	const spec = parseChainString(chainString);
+	if (spec.steps.length === 0) {
+		return result(
+			"Chain must contain at least one step. Use the form: \"step1 -> step2 -> step3\".",
+			{ action: "run", status: "error" },
+			true,
+		);
+	}
+
+	// Construct the concrete executor with per-step overrides forwarded from the
+	// chain invocation (overridden by any step that parsed to a @team reference).
+	const executor = new ChainTeamRunExecutor({
+		handleRun,
+		ctx,
+		overrides: {
+			team: params.team,
+			workflow: params.workflow,
+			model: params.model,
+		},
+	});
+
+	// Surface the global continueOnError from the parsed spec (e.g. --continue-on-error=true).
+	const runner = new ChainRunner(executor, new HandoffManager());
+	const chainResult = await runner.runChain(spec, {}, undefined);
+
+	// Build a readable multi-line summary.
+	const lines: string[] = [
+		`Chain ${chainResult.success ? "completed" : "ended"}: ${spec.steps.length} step(s), ${chainResult.totalHandoffs.length} handoff(s).`,
+		"",
+	];
+	for (const s of chainResult.steps) {
+		const runId = executor.stepRunIds[s.step - 1];
+		const tag =
+			s.outcome === "success" ? "✓"
+			: s.outcome === "failure" ? "✗"
+			: s.outcome === "partial" ? "≈"
+			: "⊘";
+		lines.push(
+			`${tag} Step ${s.step} [${s.name}]: ${s.outcome} (${s.duration}ms)${runId ? ` runId=${runId}` : ""}${s.error ? ` | ${s.error}` : ""}`,
+		);
+	}
+	lines.push("");
+	lines.push(
+		`Total: ${chainResult.totalDuration}ms${chainResult.totalTokens !== undefined ? `, ${chainResult.totalTokens} tokens` : ""}`,
+	);
+
+	return result(
+		lines.join("\n"),
+		{
+			action: "run",
+			status: chainResult.success ? "ok" : "error",
+			data: {
+				chain: true,
+				steps: chainResult.steps.length,
+				totalTokens: chainResult.totalTokens,
+				runIds: executor.stepRunIds,
+			},
+		},
+		!chainResult.success,
+	);
+}

package/src/extension/team-tool/chain-executor.ts

@@ -0,0 +1,400 @@
+/**
+ * Concrete `ChainTaskRunner` that executes each chain step as a REAL team run.
+ *
+ * This is the production wiring that makes `ChainRunner` (and Fix C's
+ * `__chainHistoryNotes`) reachable: previously `ChainRunner` had zero production
+ * callers and only existed with unit-test mock runners. Each step delegates to
+ * the existing `handleRun` (which owns config load, team/workflow discovery,
+ * worktree preconditions, manifest creation, and `executeTeamRun`), so the
+ * ~200 lines of run machinery are NOT duplicated.
+ *
+ * Context passage (the whole point of the chain feature): `enrichContextFromHandoffs`
+ * places `__chainHistory` + `__chainHistoryNotes` into `packet.context`; this
+ * executor serializes them into a `# Previous Steps in This Chain` block that is
+ * prepended to the step's goal. `handleRun` → `executeTeamRun` → worker prompt,
+ * so step N+1's worker sees step N's handoff summary and the Fix C markers.
+ *
+ * Circular-import avoidance: `handleRun` is received as an INJECTED function
+ * reference (dependency injection) rather than a static import. `run.ts` lazy-
+ * imports `chain-dispatch.ts`, which imports this file. A static import of
+ * `run.ts` here would create a `run.ts ↔ chain-executor.ts` cycle that races
+ * module-record instantiation under jiti. The DI pattern breaks the cycle.
+ *
+ * @see src/runtime/chain-runner.ts (runChain, enrichContextFromHandoffs — Fix C)
+ * @see src/extension/team-tool/run.ts (handleRun — the reused machinery)
+ */
+
+import type { ChainTaskRunner } from "../../runtime/chain-runner.ts";
+import type { TaskPacket, TaskResult, Decision } from "../../runtime/handoff-manager.ts";
+import { loadRunManifestById, createRunPaths } from "../../state/state-store.ts";
+import { readIfSmallWithTee } from "../../runtime/task-output-context.ts";
+import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
+import type { PiTeamsToolResult } from "../tool-result.ts";
+import { textFromToolResult } from "../tool-result.ts";
+import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
+import type { TeamContext } from "./context.ts";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/**
+ * Signature of `handleRun`, declared locally (type-only) to break the
+ * import cycle with run.ts. Structurally identical to
+ * `(params, ctx) => Promise<PiTeamsToolResult>`.
+ */
+export type HandleRunFn = (
+	params: TeamToolParamsValue,
+	ctx: TeamContext,
+) => Promise<PiTeamsToolResult>;
+
+/** Per-step team/workflow/model overrides forwarded from the chain invocation. */
+export interface ChainExecutorOverrides {
+	team?: string;
+	workflow?: string;
+	model?: string;
+}
+
+/** Shape of one entry in `context.__chainHistory` produced by enrichContextFromHandoffs. */
+interface ChainHistoryEntry {
+	step?: string;
+	outcome?: string;
+	filesCreated?: string[];
+	filesModified?: string[];
+	decisions?: Decision[];
+	nextSteps?: string[];
+	outputText?: string;
+}
+
+/**
+ * Serialize `packet.context.__chainHistory` (+ `__chainHistoryNotes`) into a
+ * human-readable block prefixed with `# Previous Steps in This Chain`.
+ *
+ * This is the CRITICAL coupling that makes Fix C's `__chainHistoryNotes`
+ * markers visible to step N+1's worker: those markers travel as a sibling
+ * array on the context object, and only become worker-visible once formatted
+ * into the goal text here. Returns `""` when there is no history.
+ *
+ * Extracted as a pure function for unit testability (acceptance criterion 6c).
+ */
+export function formatChainHistory(context: Record<string, unknown>): string {
+	const history = context.__chainHistory;
+	if (!Array.isArray(history) || history.length === 0) {
+		return "";
+	}
+
+	const lines: string[] = ["# Previous Steps in This Chain", ""];
+
+	for (const raw of history) {
+		if (!raw || typeof raw !== "object") continue;
+		const entry = raw as ChainHistoryEntry;
+		const stepName = entry.step ?? "unknown";
+		const outcome = entry.outcome ?? "unknown";
+		lines.push(`## Step ${stepName}: ${outcome}`);
+		lines.push(`Files created: ${entry.filesCreated?.length ? entry.filesCreated.join(", ") : "none"}`);
+		lines.push(`Files modified: ${entry.filesModified?.length ? entry.filesModified.join(", ") : "none"}`);
+		if (entry.decisions?.length) {
+			lines.push("Decisions:");
+			for (const d of entry.decisions) {
+				const rationale = (d && typeof d === "object" && "rationale" in d) ? String(d.rationale) : "(undocumented)";
+				const decisionOutcome = (d && typeof d === "object" && "outcome" in d) ? String(d.outcome) : "";
+				lines.push(`- ${rationale}${decisionOutcome ? ` → ${decisionOutcome}` : ""}`);
+			}
+		}
+		if (entry.nextSteps?.length) {
+			lines.push("Next steps:");
+			for (const ns of entry.nextSteps) lines.push(`- ${ns}`);
+		}
+		if (entry.outputText) {
+			lines.push("Output:");
+			lines.push(entry.outputText);
+		}
+		lines.push("");
+	}
+
+	// Append Fix C honesty markers verbatim — these note elided/oversized history.
+	const notes = context.__chainHistoryNotes;
+	if (Array.isArray(notes)) {
+		for (const note of notes) {
+			if (typeof note === "string" && note.length > 0) lines.push(note);
+		}
+	}
+
+	return lines.join("\n").trimEnd();
+}
+
+/**
+ * Map a completed team run's manifest+tasks → a chain `TaskResult`.
+ *
+ * Outcome is derived from the manifest status, cross-checked against task
+ * statuses (a run that completed but with a failed task reads as "partial").
+ * `usage.totalTokens` sums each task's input+output tokens; `duration` from
+ * manifest timestamps; `error` is best-effort from the first failed task or
+ * the manifest summary. `filesCreated`/`filesModified` are intentionally left
+ * unset — `TeamTaskState` does not carry them, so we never fabricate them.
+ *
+ * Extracted as a pure function for unit testability (acceptance criterion 6b).
+ */
+export function mapRunToTaskResult(
+	manifest: TeamRunManifest,
+	tasks: TeamTaskState[],
+): TaskResult {
+	// Determine outcome from manifest status.
+	let outcome: TaskResult["outcome"];
+	if (manifest.status === "completed") {
+		outcome = "success";
+	} else if (
+		manifest.status === "failed" ||
+		manifest.status === "blocked" ||
+		manifest.status === "cancelled"
+	) {
+		outcome = "failure";
+	} else {
+		// queued / planning / running → not terminal yet
+		outcome = "partial";
+	}
+
+	// Cross-check tasks: if a manifest claims completed but a task failed, it is partial.
+	const hasFailed = tasks.some((t) => t.status === "failed" || t.status === "needs_attention");
+	const hasCompleted = tasks.some((t) => t.status === "completed");
+	if (hasFailed && (hasCompleted || outcome === "success")) {
+		outcome = "partial";
+	}
+
+	// Token usage: sum task input + output.
+	let totalTokens = 0;
+	for (const t of tasks) {
+		totalTokens += (t.usage?.input ?? 0) + (t.usage?.output ?? 0);
+	}
+
+	// Duration from manifest timestamps.
+	let duration = 0;
+	const created = Date.parse(manifest.createdAt);
+	const updated = Date.parse(manifest.updatedAt);
+	if (!Number.isNaN(created) && !Number.isNaN(updated) && updated >= created) {
+		duration = updated - created;
+	}
+
+	// Error: best-effort from first failed task, else manifest summary.
+	let error: string | undefined;
+	if (outcome !== "success") {
+		const failedTask = tasks.find((t) => t.status === "failed");
+		error = failedTask?.error ?? manifest.summary;
+	}
+
+	const taskResult: TaskResult = {
+		outcome,
+		usage: { totalTokens },
+		duration,
+	};
+	if (error) taskResult.error = error;
+	return taskResult;
+}
+
+/**
+ * Read completed tasks' result artifacts and concatenate their output text.
+ * Mirrors the pattern in task-output-context.ts:collectDependencyOutputContext
+ * (readIfSmallWithTee with baseDir = artifactsRoot).
+ *
+ * Returns the concatenated output text, or undefined if no artifacts were readable.
+ */
+export function readChainStepOutput(
+	manifest: TeamRunManifest,
+	tasks: TeamTaskState[],
+): string | undefined {
+	const parts: string[] = [];
+	for (const t of tasks) {
+		if (t.status !== "completed" || !t.resultArtifact?.path) continue;
+		const read = readIfSmallWithTee(t.resultArtifact.path, {
+			baseDir: manifest.artifactsRoot,
+		});
+		if (read?.content && read.content.trim().length > 0) {
+			parts.push(read.content.trim());
+		}
+	}
+	return parts.length > 0 ? parts.join("\n\n") : undefined;
+}
+
+/**
+ * Concrete `ChainTaskRunner`: each step is a full team run via the injected
+ * `handleRun`. Step runIds are captured on `stepRunIds` so the dispatch can
+ * surface them in the summary and acceptance verification.
+ *
+ * Errors are intentionally NOT caught here — `runChain` wraps each step's
+ * `runTask` call in try/catch, records `outcome: "failure"`, and respects
+ * `continueOnError`. Letting exceptions propagate keeps the chain-runner's
+ * existing failure semantics intact.
+ */
+export class ChainTeamRunExecutor implements ChainTaskRunner {
+	/** RunId captured per executed step, in execution order. */
+	readonly stepRunIds: string[] = [];
+
+	private readonly handleRunRef: HandleRunFn;
+	private readonly ctx: TeamContext;
+	private readonly overrides: ChainExecutorOverrides;
+
+	constructor(opts: {
+		handleRun: HandleRunFn;
+		ctx: TeamContext;
+		overrides?: ChainExecutorOverrides;
+	}) {
+		this.handleRunRef = opts.handleRun;
+		this.ctx = opts.ctx;
+		this.overrides = opts.overrides ?? {};
+	}
+
+	async runTask(packet: TaskPacket): Promise<TaskResult> {
+		const context = packet.context ?? {};
+
+		// 1. Format chain history into the goal — this is how context reaches the worker.
+		//    Mirrors the parentContext pattern in child-pi.ts (parent context + task delimiter).
+		const historyPrefix = formatChainHistory(context);
+		const enrichedGoal = historyPrefix
+			? `${historyPrefix}\n\n---\n# Current Chain Step\n${packet.goal}`
+			: packet.goal;
+
+		// 2. Resolve team/workflow/model: step config (set by executeStep) → overrides → default.
+		const stepTeam =
+			(context.__chainStepTeam as string | undefined) ??
+			this.overrides.team ??
+			"default";
+		const stepWorkflow =
+			(context.__chainStepWorkflow as string | undefined) ??
+			this.overrides.workflow;
+		const stepModel =
+			(context.__chainStepModel as string | undefined) ??
+			this.overrides.model;
+
+		// 3. Call handleRun for the heavy lifting. async:false forces each step to
+		//    complete synchronously (overrides asyncByDefault) so the chain is sequential.
+		//    NO `chain` key here — so the run.ts guard does not re-enter chain dispatch.
+		const runParams: TeamToolParamsValue = {
+			action: "run",
+			goal: enrichedGoal,
+			team: stepTeam,
+			async: false,
+			...(stepWorkflow ? { workflow: stepWorkflow } : {}),
+			...(stepModel ? { model: stepModel } : {}),
+		};
+		const runRes = await this.handleRunRef(runParams, this.ctx);
+
+		// 4. Extract runId + map to TaskResult. If no runId, the run was blocked before
+		//    a manifest existed — map as a failure.
+		const runId = runRes.details?.runId;
+		if (!runId) {
+			return {
+				outcome: "failure",
+				error: textFromToolResult(runRes) || "Chain step produced no runId",
+			};
+		}
+		this.stepRunIds.push(runId);
+
+		const cwd = this.ctx.cwd ?? process.cwd();
+		const loaded = loadRunManifestById(cwd, runId);
+		if (!loaded) {
+			// Manifest not loadable — fall back to the tool result's own status.
+			return {
+				outcome: runRes.details?.status === "error" ? "failure" : "partial",
+			};
+		}
+		const result = mapRunToTaskResult(loaded.manifest, loaded.tasks);
+		const outputText = readChainStepOutput(loaded.manifest, loaded.tasks);
+		if (outputText) result.outputText = outputText;
+		return result;
+	}
+}
+
+// ─── test helpers (exported for unit/integration tests) ──────────────────
+
+/**
+ * Write a minimal valid run fixture (manifest + tasks + events) to `cwd`'s
+ * state root so `loadRunManifestById(cwd, runId)` validates and returns it.
+ * Used by integration tests to exercise `ChainTeamRunExecutor` with a mocked
+ * `handleRun` while still going through the REAL manifest loader + result mapper.
+ */
+export function writeRunFixture(
+	cwd: string,
+	runId: string,
+	opts: {
+		status?: TeamRunManifest["status"];
+		tasks?: TeamTaskState[];
+		summary?: string;
+		/** Worker result text to write to results/<taskId>.txt (sets resultArtifact on tasks). */
+		resultText?: string;
+		/** Task ID for the result artifact (default: "01_task"). */
+		taskId?: string;
+	},
+): TeamRunManifest {
+	const paths = createRunPaths(cwd, runId);
+	fs.mkdirSync(paths.stateRoot, { recursive: true });
+	const now = new Date().toISOString();
+	const start = new Date(Date.now() - 10_000).toISOString();
+	const taskId = opts.taskId ?? "01_task";
+
+	// Build tasks: if resultText is provided without explicit tasks, create a
+	// default completed task carrying a resultArtifact pointing at the result file.
+	let tasks = opts.tasks;
+	if (opts.resultText) {
+		const resultArtifact = {
+			kind: "result" as const,
+			path: `results/${taskId}.txt`,
+			createdAt: now,
+			producer: "worker",
+			retention: "run" as const,
+		};
+		if (!tasks || tasks.length === 0) {
+			tasks = [{
+				id: taskId,
+				runId,
+				role: "executor",
+				agent: "executor",
+				title: "(chain step fixture)",
+				status: "completed",
+				dependsOn: [],
+				cwd,
+				resultArtifact,
+			}];
+		} else {
+			// Attach resultArtifact to the first task if it doesn't have one.
+			tasks = tasks.map((t, i) => i === 0 && !t.resultArtifact
+				? { ...t, resultArtifact }
+				: t);
+		}
+	}
+
+	const manifest: TeamRunManifest = {
+		schemaVersion: 1,
+		runId,
+		team: "default",
+		workflow: "default",
+		goal: "(chain step fixture)",
+		status: opts.status ?? "completed",
+		workspaceMode: "single",
+		createdAt: start,
+		updatedAt: now,
+		cwd,
+		stateRoot: paths.stateRoot,
+		artifactsRoot: paths.artifactsRoot,
+		tasksPath: paths.tasksPath,
+		eventsPath: paths.eventsPath,
+		artifacts: [],
+		...(opts.summary ? { summary: opts.summary } : {}),
+	};
+
+	// Write the result artifact file + register on manifest if resultText provided.
+	if (opts.resultText) {
+		const resultDir = path.join(paths.artifactsRoot, "results");
+		fs.mkdirSync(resultDir, { recursive: true });
+		fs.writeFileSync(path.join(resultDir, `${taskId}.txt`), opts.resultText, "utf-8");
+		manifest.artifacts.push({
+			kind: "result",
+			path: `results/${taskId}.txt`,
+			createdAt: now,
+			producer: "worker",
+			retention: "run",
+		});
+	}
+
+	fs.writeFileSync(paths.manifestPath, JSON.stringify(manifest), "utf-8");
+	fs.writeFileSync(paths.tasksPath, JSON.stringify(tasks ?? []), "utf-8");
+	fs.writeFileSync(paths.eventsPath, "", "utf-8");
+	return manifest;
+}

package/src/extension/team-tool/run.ts

@@ -113,6 +113,15 @@ function scheduleBackgroundEarlyExitGuard(cwd: string, runId: string, pid: numbe
 }
 
 export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext): Promise<PiTeamsToolResult> {
+	// CHAIN DISPATCH: runs before goal validation since a chain has no top-level
+	// goal. The injected handleRun reference breaks the run.ts ↔ chain-dispatch.ts
+	// import cycle; the lazy import defers the chain-executor cost until a chain is
+	// actually requested. Existing run/workflow paths below are unchanged.
+	if (params.chain) {
+		// LAZY: defer chain-dispatch import until a chain is actually requested.
+		const { handleChainRun } = await import("./chain-dispatch.ts");
+		return handleChainRun(params, ctx, handleRun);
+	}
 	const goal = params.goal ?? params.task;
 	if (!goal) return result("Run requires goal or task.", { action: "run", status: "error" }, true);
 	const intentPrefix = goal.length > 60 ? `${goal.slice(0, 57)}...` : goal;

package/src/runtime/agent-memory.ts

@@ -43,10 +43,13 @@ export function ensureMemoryDir(memoryDir: string): void {
 
 export function readMemoryIndex(memoryDir: string): string | undefined {
 	if (isSymlink(memoryDir)) return undefined;
-	const content = safeReadMemoryFile(path.join(memoryDir, "MEMORY.md"));
+	const memPath = path.join(memoryDir, "MEMORY.md");
+	const content = safeReadMemoryFile(memPath);
 	if (content === undefined) return undefined;
 	const lines = content.split(/\r?\n/);
-	return lines.length > MAX_MEMORY_LINES ? `${lines.slice(0, MAX_MEMORY_LINES).join("\n")}\n... (truncated at 200 lines)` : content;
+	return lines.length > MAX_MEMORY_LINES
+		? `${lines.slice(0, MAX_MEMORY_LINES).join("\n")}\n... (truncated at 200 lines). Full file: ${memPath} — use the \`read\` tool if you need entries beyond the head.`
+		: content;
 }
 
 export function buildMemoryBlock(agentName: string, scope: AgentMemoryScope, cwd: string, writable: boolean): string {