pi-cockpit 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cockpit",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Agent cockpit for Pi: a list-mode status stack (live teammates + todo plan) pinned above the editor, plus a Starship-style footer. Renders only via public extension APIs (setWidget/setFooter).",
   "type": "module",
   "keywords": [
@@ -59,7 +59,7 @@
     "@earendil-works/pi-coding-agent": "0.82.1",
     "@earendil-works/pi-tui": "0.82.1",
     "@types/node": "^22.0.0",
-    "pi-maestro-teammate": "1.0.0",
+    "pi-maestro-teammate": "1.2.0",
     "typescript": "^5.5.0"
   },
   "main": "./src/index.ts",

package/src/agents-store.ts

@@ -37,6 +37,8 @@ export interface ProgressPayload {
 	dependencies?: number[];
 	status?: string;
 	startedAt?: number | string;
+	completedAt?: number | string;
+	durationMs?: number;
 	lastActivityAt?: number | string;
 	recentTools?: Array<string | { name?: string; status?: string }>;
 	toolCount?: number;
@@ -48,6 +50,10 @@ export interface ProgressPayload {
 export interface MessagePayload {
 	correlationId: string;
 	taskCorrelationId?: string;
+	// Present on progress/interaction deltas (teammate/.../index.ts publishProgress);
+	// absent on send deltas. Used to self-heal a row when `started` was missed.
+	agent?: string;
+	name?: string;
 	taskIndex?: number;
 	dependencies?: number[];
 	message?: string;
@@ -61,7 +67,8 @@ export interface MessagePayload {
 	lastActivityAt?: number | string;
 	progress?: ProgressPayload[];
 }
-export type CompletePayload = Pick<TeammateCompleteEvent, "correlationId" | "exitCode">;
+export type CompletePayload = Pick<TeammateCompleteEvent, "correlationId" | "exitCode">
+	& Partial<Pick<TeammateCompleteEvent, "durationMs">>;
 
 /**
  * How long a failed agent stays on screen after it completes.
@@ -105,6 +112,19 @@ function normalizeStartedAt(value: number | string | undefined, fallback: number
 	return fallback;
 }
 
+function terminalTime(
+	row: AgentRow,
+	payload: { completedAt?: number | string; durationMs?: number },
+	now: number,
+): number {
+	const completedAt = normalizeStartedAt(payload.completedAt, Number.NaN);
+	if (Number.isFinite(completedAt)) return Math.max(row.startedAt, completedAt);
+	if (typeof payload.durationMs === "number" && Number.isFinite(payload.durationMs)) {
+		return row.startedAt + Math.max(0, payload.durationMs);
+	}
+	return row.finishedAt ?? now;
+}
+
 function latestTool(tools: MessagePayload["recentTools"]): string | undefined {
 	if (!tools?.length) return undefined;
 	const tool = tools.find((candidate) => typeof candidate === "object" && candidate?.status === "running")
@@ -120,13 +140,16 @@ function latestTool(tools: MessagePayload["recentTools"]): string | undefined {
 // Self-accumulating roster. The teammate extension only broadcasts deltas
 // (started/message/complete), never a full snapshot, so we rebuild the list here.
 // Cold start is empty by design — we only reflect activity observed after load.
+// The roster is self-healing: message/progress deltas for an agent whose
+// `started` delta was missed still materialize a row, so a running agent is
+// always represented as long as it keeps emitting activity.
 export class AgentsStore {
 	private readonly roster = new Map<string, AgentRow>();
 
 	applyStarted(p: StartedPayload, now: number = Date.now()): void {
 		const id = p.correlationId;
 		const prev = this.roster.get(id);
-		this.roster.set(id, {
+		const row: AgentRow = {
 			...prev,
 			correlationId: id,
 			agent: clean(p.agent) || prev?.agent || "",
@@ -142,7 +165,9 @@ export class AgentsStore {
 				: prev?.parentCorrelationId
 					? { parentCorrelationId: prev.parentCorrelationId }
 					: {}),
-		});
+		};
+		if (row.status !== "done" && row.status !== "failed") delete row.finishedAt;
+		this.roster.set(id, row);
 	}
 
 	applyMessage(p: MessagePayload, now = Date.now()): void {
@@ -150,6 +175,22 @@ export class AgentsStore {
 			for (const progress of p.progress) this.applyProgress(p.correlationId, progress, now);
 		}
 		const targetId = p.taskCorrelationId ?? p.correlationId;
+		if (!this.roster.has(targetId)) {
+			// Self-heal the roster: a running agent must stay visible even when its
+			// `started` delta was missed (cold start, event reorder, or a foreground
+			// dispatch that detached to background). Materialize the row from this
+			// event instead of dropping it; later deltas refine the placeholder.
+			this.applyStarted({
+				correlationId: targetId,
+				agent: p.agent ?? "",
+				name: p.name,
+				status: p.status,
+				lastActivityAt: p.lastActivityAt,
+				...(p.taskCorrelationId && p.taskCorrelationId !== p.correlationId
+					? { spawnedBy: p.correlationId }
+					: {}),
+			}, now);
+		}
 		const row = this.roster.get(targetId);
 		if (!row) return;
 		const progressActivity = p.progress?.find((progress) => progress.correlationId === targetId)?.lastActivityAt;
@@ -168,6 +209,8 @@ export class AgentsStore {
 		if (typeof p.status === "string") {
 			row.taskStatus = p.status;
 			row.status = mapAgentStatus(p.status);
+			if (row.status === "done" || row.status === "failed") row.finishedAt ??= now;
+			else delete row.finishedAt;
 		}
 		if (typeof p.taskIndex === "number") row.taskIndex = p.taskIndex;
 		if (Array.isArray(p.dependencies)) row.dependencies = [...p.dependencies];
@@ -193,6 +236,7 @@ export class AgentsStore {
 			if (row && (row.status === "failed" || failedByExitCode)) {
 				row.status = "failed";
 				row.taskStatus = "failed";
+				row.finishedAt = terminalTime(row, id === p.correlationId ? p : {}, now);
 				row.failedAt = now;
 				row.lastActivityAt = now;
 				delete row.activeTool;
@@ -223,22 +267,43 @@ export class AgentsStore {
 	}
 
 	private applyProgress(parentCorrelationId: string, p: ProgressPayload, now: number): void {
+		if (!this.roster.has(p.correlationId)) {
+			// Self-heal: see applyMessage. A graph child whose `started` delta was
+			// missed still materializes from its first progress event.
+			this.applyStarted({
+				correlationId: p.correlationId,
+				agent: p.agent,
+				name: p.name,
+				status: p.status,
+				startedAt: p.startedAt,
+				lastActivityAt: p.lastActivityAt,
+				...(parentCorrelationId !== p.correlationId
+					? { spawnedBy: parentCorrelationId }
+					: {}),
+			}, now);
+		}
 		const row = this.roster.get(p.correlationId);
 		if (!row) return;
-		row.parentCorrelationId = parentCorrelationId === p.correlationId
-			? row.parentCorrelationId
-			: parentCorrelationId;
+		if (
+			parentCorrelationId !== p.correlationId
+			&& row.parentCorrelationId === undefined
+		) row.parentCorrelationId = parentCorrelationId;
 		row.agent = clean(p.agent) || row.agent;
 		row.name = p.name === undefined ? row.name : clean(p.name);
 		row.role = deriveRole(p.agent, p.name);
 		row.task = p.name === undefined ? row.task : clean(p.name);
+		if (p.startedAt !== undefined) row.startedAt = normalizeStartedAt(p.startedAt, row.startedAt);
 		if (typeof p.status === "string") {
 			row.taskStatus = p.status;
 			row.status = mapAgentStatus(p.status);
+			if (row.status === "done" || row.status === "failed") {
+				row.finishedAt = terminalTime(row, p, now);
+			} else {
+				delete row.finishedAt;
+			}
 		}
 		row.taskIndex = p.taskIndex;
 		row.dependencies = Array.isArray(p.dependencies) ? [...p.dependencies] : [];
-		if (p.startedAt !== undefined) row.startedAt = normalizeStartedAt(p.startedAt, row.startedAt);
 		row.lastActivityAt = normalizeStartedAt(p.lastActivityAt, now);
 		if (p.recentTools) {
 			const tool = latestTool(p.recentTools);

package/src/render.ts

@@ -239,7 +239,7 @@ export function renderAgents(
 		if (status.label) segs.push({ text: theme.fg(status.color, status.label), priority: 95, clippable: false });
 		segs.push({ text: theme.fg(rc, r.role), priority: 90 });
 		if (r.task) segs.push({ text: r.task, priority: 80, minWidth: 6 });
-		segs.push({ text: theme.fg("muted", formatDuration(now - r.startedAt)), priority: 70, clippable: false });
+		segs.push({ text: theme.fg("muted", formatDuration((r.finishedAt ?? now) - r.startedAt)), priority: 70, clippable: false });
 		if (r.dependencies?.length) {
 			segs.push({ text: theme.fg("dim", formatDependencies(r.dependencies, g)), priority: 60, clippable: false });
 		}

package/src/stack-widget.ts

@@ -1,111 +1,133 @@
-import type { Theme } from "@earendil-works/pi-coding-agent";
-import type { TUI } from "@earendil-works/pi-tui";
-import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import { renderAgents, renderTodos, type PaintTheme, type WidthUtils } from "./render.ts";
-import { fitLineByPriority, type PrioritizedSegment } from "./layout.ts";
-import { resolveGlyphs, spinFrame } from "./icons.ts";
-import { panelRows } from "./viewport.ts";
-import type { AgentRow, CockpitConfig, TodoItem } from "./types.ts";
-
-export interface TodoWidgetDeps {
-	getTodos: () => TodoItem[];
-	getConfig: () => CockpitConfig;
-	/** False when no redraw loop is running, so spinners must not freeze mid-cycle. */
-	isAnimating?: () => boolean;
-}
-
-export interface AgentWidgetDeps {
-	getAgents: () => AgentRow[];
-	getConfig: () => CockpitConfig;
-	isRunning: () => boolean;
-	isAnimating?: () => boolean;
-}
-
-const UTILS: WidthUtils = { measure: visibleWidth, clip: truncateToWidth };
-
-// The TUI exposes the live terminal size, but a widget must never fail to render
-// because a host handed it a stub without one.
-export function terminalRows(tui: TUI): number | undefined {
-	try {
-		const rows = tui.terminal?.rows;
-		return typeof rows === "number" && rows > 0 ? rows : undefined;
-	} catch {
-		return undefined;
-	}
-}
-
-// Todo widget: pinned above the editor (setWidget "cockpit-stack", aboveEditor).
-export function makeTodoWidget(deps: TodoWidgetDeps) {
-	return (tui: TUI, theme: Theme) => {
-		const paint: PaintTheme = theme;
-		return {
-			render(width: number): string[] {
-				const cfg = deps.getConfig();
-				const todos = deps.getTodos();
-				if (todos.length === 0) return [];
-				const g = resolveGlyphs(cfg.icons.mode);
-				const now = Date.now();
-				const spin = spinFrame(g, now, deps.isAnimating?.() ?? true);
-				const opts = {
-					glyphs: g,
-					spin,
-					now,
-					expanded: cfg.todoExpanded,
-					maxRows: panelRows(terminalRows(tui)),
-				};
-				return renderTodos(todos, cfg.todoExpanded ? "list" : cfg.todoMode, width, paint, UTILS, opts);
-			},
-			invalidate(): void {},
-			dispose(): void {},
-		};
-	};
-}
-
-// Agent widget: pinned below the editor, near the input box (setWidget "cockpit-agents", belowEditor).
-export function makeAgentWidget(deps: AgentWidgetDeps) {
-	return (tui: TUI, theme: Theme) => {
-		const paint: PaintTheme = theme;
-		return {
-			render(width: number): string[] {
-				const cfg = deps.getConfig();
-				const agents = deps.getAgents();
-				if (agents.length === 0) return [];
-				const g = resolveGlyphs(cfg.icons.mode);
-				const now = Date.now();
-				const animating = deps.isAnimating?.() ?? true;
-				const spin = spinFrame(g, now, animating);
-				const running = deps.isRunning();
-				// The panel budget covers the roster header and its rows.
-				const panel = panelRows(terminalRows(tui));
-				const rosterRows = panel === undefined
-					? undefined
-					: Math.max(1, panel - 1);
-				const opts = { glyphs: g, spin, now, maxRows: rosterRows };
-				const dot = theme.fg(running ? "success" : "muted", running ? g.dotRunning : g.dotIdle);
-				const failedCount = agents.filter((a) => a.status === "failed").length;
-				const runCount = agents.filter((a) => a.status === "running" || a.status === "retrying").length;
-				const pendingCount = agents.filter((a) => a.status === "pending").length;
-				const sleepingCount = agents.filter((a) => a.status === "sleeping").length;
-				// This header owns the roster summary, so compact mode must not print
-				// its own count line right underneath saying the same thing.
-				const headerSegs: PrioritizedSegment[] = [
-					{ text: dot, priority: 100, clippable: false },
-					{ text: theme.fg("muted", "Agents"), priority: 90, clippable: false },
-				];
-				if (failedCount) {
-					headerSegs.push({ text: theme.fg("error", `${failedCount} failed`), priority: 95, clippable: false });
-				}
-				if (runCount) headerSegs.push({ text: theme.fg("dim", `${runCount} running`), priority: 80, clippable: false });
-				if (pendingCount) headerSegs.push({ text: theme.fg("dim", `${pendingCount} pending`), priority: 60, clippable: false });
-				if (sleepingCount) headerSegs.push({ text: theme.fg("dim", `${sleepingCount} sleeping`), priority: 50, clippable: false });
-				const lines: string[] = [];
-				// Was the one line in the package pushed without any width clipping.
-				lines.push(fitLineByPriority(headerSegs, width, UTILS, theme.fg("dim", g.separator), g.ellipsis));
-				lines.push(...renderAgents(agents, cfg.agentsMode, width, paint, UTILS, { ...opts, withHead: false }));
-				return lines;
-			},
-			invalidate(): void {},
-			dispose(): void {},
-		};
-	};
-}
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { TUI } from "@earendil-works/pi-tui";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { renderAgents, renderTodos, type PaintTheme, type WidthUtils } from "./render.ts";
+import { fitLineByPriority, type PrioritizedSegment } from "./layout.ts";
+import { resolveGlyphs, spinFrame } from "./icons.ts";
+import { panelRows } from "./viewport.ts";
+import type { AgentRow, CockpitConfig, TodoItem } from "./types.ts";
+
+export interface TodoWidgetDeps {
+	getTodos: () => TodoItem[];
+	getConfig: () => CockpitConfig;
+	/** False when no redraw loop is running, so spinners must not freeze mid-cycle. */
+	isAnimating?: () => boolean;
+}
+
+export interface AgentWidgetDeps {
+	getAgents: () => AgentRow[];
+	getConfig: () => CockpitConfig;
+	isRunning: () => boolean;
+	isAnimating?: () => boolean;
+}
+
+const UTILS: WidthUtils = { measure: visibleWidth, clip: truncateToWidth };
+
+// The TUI exposes the live terminal size, but a widget must never fail to render
+// because a host handed it a stub without one.
+export function terminalRows(tui: TUI): number | undefined {
+	try {
+		const rows = tui.terminal?.rows;
+		return typeof rows === "number" && rows > 0 ? rows : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function visibleAgentRows(rows: AgentRow[]): AgentRow[] {
+	const byId = new Map(rows.map((row) => [row.correlationId, row]));
+	return rows.filter((row) => !row.agent.startsWith("graph(")).map((row) => {
+		let parent = row.parentCorrelationId;
+		const visited = new Set([row.correlationId]);
+		while (parent) {
+			if (visited.has(parent)) {
+				parent = undefined;
+				break;
+			}
+			visited.add(parent);
+			const parentRow = byId.get(parent);
+			if (!parentRow || !parentRow.agent.startsWith("graph(")) break;
+			parent = parentRow.parentCorrelationId;
+		}
+		return parent === row.parentCorrelationId ? row : { ...row, parentCorrelationId: parent };
+	});
+}
+
+// Todo widget: pinned above the editor (setWidget "cockpit-stack", aboveEditor).
+export function makeTodoWidget(deps: TodoWidgetDeps) {
+	return (tui: TUI, theme: Theme) => {
+		const paint: PaintTheme = theme;
+		return {
+			render(width: number): string[] {
+				const cfg = deps.getConfig();
+				const todos = deps.getTodos();
+				if (todos.length === 0) return [];
+				const g = resolveGlyphs(cfg.icons.mode);
+				const now = Date.now();
+				const spin = spinFrame(g, now, deps.isAnimating?.() ?? true);
+				const opts = {
+					glyphs: g,
+					spin,
+					now,
+					expanded: cfg.todoExpanded,
+					maxRows: panelRows(terminalRows(tui)),
+				};
+				return renderTodos(todos, cfg.todoExpanded ? "list" : cfg.todoMode, width, paint, UTILS, opts);
+			},
+			invalidate(): void {},
+			dispose(): void {},
+		};
+	};
+}
+
+// Agent widget: pinned below the editor, near the input box (setWidget "cockpit-agents", belowEditor).
+export function makeAgentWidget(deps: AgentWidgetDeps) {
+	return (tui: TUI, theme: Theme) => {
+		const paint: PaintTheme = theme;
+		return {
+			render(width: number): string[] {
+				const cfg = deps.getConfig();
+				// graph(...) is the dispatch container, not an additional worker. Keep it
+				// in AgentsStore for linkage and cleanup, and bridge its visible descendants
+				// to the nearest non-graph ancestor for rendering.
+				const agents = visibleAgentRows(deps.getAgents());
+				if (agents.length === 0) return [];
+				const g = resolveGlyphs(cfg.icons.mode);
+				const now = Date.now();
+				const animating = deps.isAnimating?.() ?? true;
+				const spin = spinFrame(g, now, animating);
+				const running = deps.isRunning();
+				// The panel budget covers the roster header and its rows.
+				const panel = panelRows(terminalRows(tui));
+				const rosterRows = panel === undefined
+					? undefined
+					: Math.max(1, panel - 1);
+				const opts = { glyphs: g, spin, now, maxRows: rosterRows };
+				const dot = theme.fg(running ? "success" : "muted", running ? g.dotRunning : g.dotIdle);
+				const failedCount = agents.filter((a) => a.status === "failed").length;
+				const runCount = agents.filter((a) => a.status === "running" || a.status === "retrying").length;
+				const pendingCount = agents.filter((a) => a.status === "pending").length;
+				const sleepingCount = agents.filter((a) => a.status === "sleeping").length;
+				// This header owns the roster summary, so compact mode must not print
+				// its own count line right underneath saying the same thing.
+				const headerSegs: PrioritizedSegment[] = [
+					{ text: dot, priority: 100, clippable: false },
+					{ text: theme.fg("muted", "Agents"), priority: 90, clippable: false },
+				];
+				if (failedCount) {
+					headerSegs.push({ text: theme.fg("error", `${failedCount} failed`), priority: 95, clippable: false });
+				}
+				if (runCount) headerSegs.push({ text: theme.fg("dim", `${runCount} running`), priority: 80, clippable: false });
+				if (pendingCount) headerSegs.push({ text: theme.fg("dim", `${pendingCount} pending`), priority: 60, clippable: false });
+				if (sleepingCount) headerSegs.push({ text: theme.fg("dim", `${sleepingCount} sleeping`), priority: 50, clippable: false });
+				const lines: string[] = [];
+				// Was the one line in the package pushed without any width clipping.
+				lines.push(fitLineByPriority(headerSegs, width, UTILS, theme.fg("dim", g.separator), g.ellipsis));
+				lines.push(...renderAgents(agents, cfg.agentsMode, width, paint, UTILS, { ...opts, withHead: false }));
+				return lines;
+			},
+			invalidate(): void {},
+			dispose(): void {},
+		};
+	};
+}

package/src/types.ts

@@ -1,114 +1,116 @@
-// Cross-extension event names broadcast by pi-maestro-teammate.
-// Hard-coded strings (stable contract; see pi-maestro-teammate/src/shared/types.ts:184-186)
-// so this package needs no import path into the teammate package.
-export const TEAMMATE_STARTED_EVENT = "teammate:started";
-export const TEAMMATE_MESSAGE_EVENT = "teammate:message";
-export const TEAMMATE_COMPLETE_EVENT = "teammate:complete";
-export const COCKPIT_UI_OWNERSHIP_EVENT = "cockpit:ui-ownership";
-export const COCKPIT_TODO_TOGGLE_EVENT = "cockpit:toggle-todo";
-export const BASH_BG_UPDATE_EVENT = "bash-bg:update";
-export const BASH_BG_QUERY_EVENT = "bash-bg:query";
-export const WORKFLOW_STATUS_KEY = "maestro-workflow";
-
-// Widget keys owned by pi-cockpit. Native Flow/teammate widgets yield through
-// COCKPIT_UI_OWNERSHIP_EVENT instead of being cleared across extension boundaries.
-export const STACK_WIDGET_KEY = "cockpit-stack";
-export const AGENT_WIDGET_KEY = "cockpit-agents";
-
-// todo tool name registered by pi-maestro-flow (src/extension/index.ts:594).
-export const TODO_TOOL_NAME = "todo";
-// appendEntry customType the todo tool persists after every mutation (tools/todo.ts:145).
-export const TODO_STATE_ENTRY_TYPE = "todo-state";
-
-export type AgentStatus = "pending" | "running" | "retrying" | "sleeping" | "done" | "failed";
-
-export interface AgentRow {
-	correlationId: string;
-	parentCorrelationId?: string;
-	agent: string;
-	name: string | undefined;
-	role: string;
-	task: string;
-	status: AgentStatus;
-	tail: string;
-	startedAt: number;
-	lastActivityAt: number;
-	toolCount?: number;
-	tokens?: number;
-	inputTokens?: number;
-	outputTokens?: number;
-	taskStatus?: string;
-	activeTool?: string;
-	taskIndex?: number;
-	dependencies?: number[];
-	/** Set only on a failed row that outlived its completion, so it can be pruned. */
-	failedAt?: number;
-}
-
-export type BashBgStatus = "running" | "stopping" | "completed" | "failed" | "killed";
-
-export interface BashBgJob {
-	id: string;
-	command: string;
-	cwd: string;
-	pid: number;
-	status: BashBgStatus;
-	startedAt: number;
-	updatedAt: number;
-	finishedAt?: number;
-	exitCode: number | null;
-	outputTail: string;
-	outputBytes: number;
-	logPath: string;
-}
-
-export type TodoState = "pending" | "in_progress" | "completed" | "blocked";
-
-export interface TodoItem {
-	id: string;
-	subject: string;
-	status: TodoState;
-	blockedBy: string[];
-	createdBy?: TodoActor;
-	assignee?: TodoActor;
-	skills: TodoSkill[];
-	updatedAt?: number;
-}
-
-export interface TodoActor {
-	id: string;
-	label: string;
-}
-
-export interface TodoSkill {
-	name: string;
-	role?: string;
-}
-
-export type ViewMode = "list" | "compact";
-
-export type IconMode = "auto" | "nerd" | "ascii";
-
-export interface CockpitConfig {
-	enabled: boolean;
-	agentsMode: ViewMode;
-	todoMode: ViewMode;
-	todoExpanded: boolean;
-	hideNativeAgents: boolean;
-	icons: { mode: IconMode };
-	/**
-	 * Theme to apply at session start. Empty means "leave whatever pi is using",
-	 * so cockpit never overrides a theme the user picked elsewhere.
-	 */
-	theme: string;
-}
-
-export const DEFAULT_CONFIG: CockpitConfig = {
-	enabled: true,
-	agentsMode: "list",
-	todoMode: "list",
-	todoExpanded: false,
-	hideNativeAgents: true,
-	icons: { mode: "auto" },
-	theme: "",
-};
+// Cross-extension event names broadcast by pi-maestro-teammate.
+// Hard-coded strings (stable contract; see pi-maestro-teammate/src/shared/types.ts:184-186)
+// so this package needs no import path into the teammate package.
+export const TEAMMATE_STARTED_EVENT = "teammate:started";
+export const TEAMMATE_MESSAGE_EVENT = "teammate:message";
+export const TEAMMATE_COMPLETE_EVENT = "teammate:complete";
+export const COCKPIT_UI_OWNERSHIP_EVENT = "cockpit:ui-ownership";
+export const COCKPIT_TODO_TOGGLE_EVENT = "cockpit:toggle-todo";
+export const BASH_BG_UPDATE_EVENT = "bash-bg:update";
+export const BASH_BG_QUERY_EVENT = "bash-bg:query";
+export const WORKFLOW_STATUS_KEY = "maestro-workflow";
+
+// Widget keys owned by pi-cockpit. Native Flow/teammate widgets yield through
+// COCKPIT_UI_OWNERSHIP_EVENT instead of being cleared across extension boundaries.
+export const STACK_WIDGET_KEY = "cockpit-stack";
+export const AGENT_WIDGET_KEY = "cockpit-agents";
+
+// todo tool name registered by pi-maestro-flow (src/extension/index.ts:594).
+export const TODO_TOOL_NAME = "todo";
+// appendEntry customType the todo tool persists after every mutation (tools/todo.ts:145).
+export const TODO_STATE_ENTRY_TYPE = "todo-state";
+
+export type AgentStatus = "pending" | "running" | "retrying" | "sleeping" | "done" | "failed";
+
+export interface AgentRow {
+	correlationId: string;
+	parentCorrelationId?: string;
+	agent: string;
+	name: string | undefined;
+	role: string;
+	task: string;
+	status: AgentStatus;
+	tail: string;
+	startedAt: number;
+	/** Terminal wall-clock used to freeze elapsed time for completed/failed rows. */
+	finishedAt?: number;
+	lastActivityAt: number;
+	toolCount?: number;
+	tokens?: number;
+	inputTokens?: number;
+	outputTokens?: number;
+	taskStatus?: string;
+	activeTool?: string;
+	taskIndex?: number;
+	dependencies?: number[];
+	/** Set only on a failed row that outlived its completion, so it can be pruned. */
+	failedAt?: number;
+}
+
+export type BashBgStatus = "running" | "stopping" | "completed" | "failed" | "killed";
+
+export interface BashBgJob {
+	id: string;
+	command: string;
+	cwd: string;
+	pid: number;
+	status: BashBgStatus;
+	startedAt: number;
+	updatedAt: number;
+	finishedAt?: number;
+	exitCode: number | null;
+	outputTail: string;
+	outputBytes: number;
+	logPath: string;
+}
+
+export type TodoState = "pending" | "in_progress" | "completed" | "blocked";
+
+export interface TodoItem {
+	id: string;
+	subject: string;
+	status: TodoState;
+	blockedBy: string[];
+	createdBy?: TodoActor;
+	assignee?: TodoActor;
+	skills: TodoSkill[];
+	updatedAt?: number;
+}
+
+export interface TodoActor {
+	id: string;
+	label: string;
+}
+
+export interface TodoSkill {
+	name: string;
+	role?: string;
+}
+
+export type ViewMode = "list" | "compact";
+
+export type IconMode = "auto" | "nerd" | "ascii";
+
+export interface CockpitConfig {
+	enabled: boolean;
+	agentsMode: ViewMode;
+	todoMode: ViewMode;
+	todoExpanded: boolean;
+	hideNativeAgents: boolean;
+	icons: { mode: IconMode };
+	/**
+	 * Theme to apply at session start. Empty means "leave whatever pi is using",
+	 * so cockpit never overrides a theme the user picked elsewhere.
+	 */
+	theme: string;
+}
+
+export const DEFAULT_CONFIG: CockpitConfig = {
+	enabled: true,
+	agentsMode: "list",
+	todoMode: "list",
+	todoExpanded: false,
+	hideNativeAgents: true,
+	icons: { mode: "auto" },
+	theme: "",
+};