pi-crew 0.10.1 → 0.10.3

package/src/state/stores/state-store.ts

@@ -10,6 +10,7 @@ import { findRepoRoot, projectCrewRoot, userCrewRoot } from "../../utils/paths.t
 import { assertSafePathId, resolveContainedRelativePath, resolveRealContainedPath } from "../../utils/safe-paths.ts";
 import { toPiSessionId } from "../../utils/session-utils.ts";
 import type { WorkflowConfig } from "../../workflows/workflow-config.ts";
+import type { WriteDurability } from "../atomic-write.ts";
 import {
 	atomicWriteJson,
 	atomicWriteJsonAsync,
@@ -207,6 +208,26 @@ function resolveRunStateRoot(cwd: string, runId: string): string | undefined {
 	return scopedPath;
 }
 
+// PERF (2026-08-24): the artifacts containment verdict (existsSync + lstat +
+// resolveRealContainedPath ≈ 10-25 syscalls) cannot change for a run dir that
+// is not replaced — mirror the P1-12 runStateRootCache tradeoff: positive
+// verdicts cached 10s, negatives never cached (a newly created artifacts dir
+// must be found promptly). A stale positive is safe the same way P1-12 is:
+// downstream manifest stat catches deleted runs, and any write through
+// atomic-write re-runs isSymlinkSafeDirCached independently.
+const artifactsVerdictCache = new Map<string, { expiresAt: number }>();
+const ARTIFACTS_VERDICT_TTL_MS = 10_000;
+const ARTIFACTS_VERDICT_CACHE_MAX = 256;
+
+/** @internal — artifacts verdict cache introspection for unit tests. */
+export function __test__artifactsVerdictCacheSize(): number {
+	return artifactsVerdictCache.size;
+}
+/** @internal */
+export function __test__clearArtifactsVerdictCache(): void {
+	artifactsVerdictCache.clear();
+}
+
 function validateRunManifestPaths(cwd: string, runId: string, manifest: TeamRunManifest, stateRoot: string, tasksPath: string): boolean {
 	// Issue 2 fix: Reject manifests missing status field to prevent undefined
 	// behavior in callers like canTransitionRunStatus(manifest.status, newStatus).
@@ -221,6 +242,12 @@ function validateRunManifestPaths(cwd: string, runId: string, manifest: TeamRunM
 	const artifactsParent = path.join(scopeBaseRoot(cwd), DEFAULT_PATHS.state.artifactsSubdir);
 	const expectedArtifactsRoot = resolveContainedRelativePath(artifactsParent, runId, "runId");
 	if (manifest.artifactsRoot !== expectedArtifactsRoot) return false;
+	// PERF (2026-08-24): memoized verdict — see artifactsVerdictCache above.
+	// Hit only after the cheap manifest-identity checks above, so a tampered
+	// manifest (wrong paths/status) is still rejected without touching the memo.
+	const verdictKey = `${cwd}\0${runId}`;
+	const cachedVerdict = artifactsVerdictCache.get(verdictKey);
+	if (cachedVerdict && cachedVerdict.expiresAt > Date.now()) return true;
 	// Always validate artifactsRoot is not a symlink, even when manifest has
 	// no artifacts entries. A symlinked artifactsRoot pointing outside the
 	// artifacts parent is a security violation (could write to attacker-
@@ -237,8 +264,18 @@ function validateRunManifestPaths(cwd: string, runId: string, manifest: TeamRunM
 	} else if (manifest.artifacts && manifest.artifacts.length > 0) {
 		// Has artifacts entries but directory doesn't exist - benign state for
 		// runs still in progress.
+		if (artifactsVerdictCache.size >= ARTIFACTS_VERDICT_CACHE_MAX) {
+			const oldest = artifactsVerdictCache.keys().next().value;
+			if (oldest !== undefined) artifactsVerdictCache.delete(oldest);
+		}
+		artifactsVerdictCache.set(verdictKey, { expiresAt: Date.now() + ARTIFACTS_VERDICT_TTL_MS });
 		return true;
 	}
+	if (artifactsVerdictCache.size >= ARTIFACTS_VERDICT_CACHE_MAX) {
+		const oldest = artifactsVerdictCache.keys().next().value;
+		if (oldest !== undefined) artifactsVerdictCache.delete(oldest);
+	}
+	artifactsVerdictCache.set(verdictKey, { expiresAt: Date.now() + ARTIFACTS_VERDICT_TTL_MS });
 	return true;
 }
 
@@ -260,7 +297,42 @@ export function createRunPaths(cwd: string, runId = createRunId()): RunPaths {
 	};
 }
 
-export function createTasksFromWorkflow(runId: string, workflow: WorkflowConfig, team: TeamConfig, cwd: string): TeamTaskState[] {
+/**
+ * Trailing phrases a step template leaves in front of `{goal}` — "Explore
+ * the codebase for the goal: {goal}" should name the task ("Explore the
+ * codebase"), not quote the whole run goal after every verb. The run goal is
+ * run-level context (statusline shows it once); a task list that repeats it
+ * per row reads like a roster of workers, not a list of work.
+ */
+const GOAL_TAILS = ["for the goal", "for goal", "the goal", "goal", "cho mục tiêu", "của mục tiêu", "mục tiêu", "for", "of", "cho", "của"];
+
+function stripGoalTail(prefix: string): string {
+	let name = prefix.replace(/[\s:—-]+$/, "").trim();
+	let changed = true;
+	while (changed) {
+		changed = false;
+		const lowered = name.toLowerCase();
+		for (const tail of GOAL_TAILS) {
+			if (lowered.endsWith(tail) && lowered.length > tail.length) {
+				name = name
+					.slice(0, name.length - tail.length)
+					.replace(/[\s:—-]+$/, "")
+					.trim();
+				changed = true;
+				break;
+			}
+		}
+	}
+	return name;
+}
+
+export function createTasksFromWorkflow(
+	runId: string,
+	workflow: WorkflowConfig,
+	team: TeamConfig,
+	cwd: string,
+	goal?: string,
+): TeamTaskState[] {
 	const stepToTaskId = new Map(workflow.steps.map((step, index) => [step.id, createTaskId(step.id, index)]));
 	return workflow.steps.map((step, index) => {
 		const role = team.roles.find((candidate) => candidate.name === step.role);
@@ -270,13 +342,48 @@ export function createTasksFromWorkflow(runId: string, workflow: WorkflowConfig,
 			.filter((candidate) => candidate.dependsOn?.includes(step.id))
 			.map((candidate) => stepToTaskId.get(candidate.id))
 			.filter((childId): childId is string => childId !== undefined);
+		// The plan's own words become the task's display identity: a heading
+		// from the step body if present, else its first content line; the
+		// remaining body is kept as `description` for detail surfaces (task
+		// list detail line, view). Falls back to the step id when the body
+		// carries no text of its own — `task` is optional on literal
+		// WorkflowStep objects.
+		//
+		// `{goal}` in the title line is the RUN's goal, context for every
+		// task, not this task's name. The template prefix before the
+		// placeholder names the task; a placeholder-only body ("{goal}",
+		// direct-run) adopts the goal itself as the title. `description`
+		// lines substitute the placeholder (the prompt path substitutes
+		// separately — unchanged).
+		const bodyLines =
+			typeof step.task === "string" && step.task.trim()
+				? step.task
+						.split("\n")
+						.map((line) => line.trim())
+						.filter(Boolean)
+				: [];
+		const heading = bodyLines.find((line) => line.startsWith("#"));
+		const titleLine = heading ?? bodyLines[0];
+		const substitute = (text: string): string => (goal ? text.replaceAll("{goal}", goal) : text);
+		let title: string;
+		let restLines: string[];
+		const placeholderAt = titleLine?.indexOf("{goal}") ?? -1;
+		if (titleLine && placeholderAt >= 0) {
+			title = stripGoalTail(titleLine.slice(0, placeholderAt)) || goal || step.id;
+			restLines = bodyLines.filter((line) => line !== titleLine);
+		} else {
+			title = (titleLine ?? step.id).replace(/^#+\s*/, "");
+			restLines = heading ? bodyLines.filter((line) => line !== titleLine) : bodyLines.slice(1);
+		}
+		const description = restLines.map(substitute).join("\n");
 		return {
 			id,
 			runId,
 			stepId: step.id,
 			role: step.role,
 			agent: role?.agent ?? step.role,
-			title: step.id,
+			title: title.slice(0, 120),
+			description: description && description !== title ? description : undefined,
 			status: "queued",
 			dependsOn: dependencies,
 			cwd,
@@ -305,7 +412,7 @@ export function createRunManifest(params: {
 }): { manifest: TeamRunManifest; tasks: TeamTaskState[]; paths: RunPaths } {
 	const paths = createRunPaths(params.cwd);
 	const now = new Date().toISOString();
-	const tasks = params.workflow ? createTasksFromWorkflow(paths.runId, params.workflow, params.team, params.cwd) : [];
+	const tasks = params.workflow ? createTasksFromWorkflow(paths.runId, params.workflow, params.team, params.cwd, params.goal) : [];
 	const manifest: TeamRunManifest = {
 		schemaVersion: CURRENT_SCHEMA_VERSION,
 		runId: paths.runId,
@@ -554,19 +661,52 @@ export function saveRunTasks(manifest: TeamRunManifest, tasks: TeamTaskState[]):
  * tasks.json stale (showing "running") while events.jsonl already shows
  * the terminal event, causing false zombie detection / double-execution
  * on crash recovery.
+ *
+ * PERF round 2, Task 3: optional `durability` (default "full") overrides the
+ * coalesced entry's durability. When the caller wants a non-terminal checkpoint
+ * written without fsync (persistence.skipTasksFsync opt-in), pass
+ * `durability: "best-effort"` — the coalesced entry stores it and the flush
+ * forwards it to atomicWriteFile (see atomic-write.ts:997). Terminal
+ * transitions (skipCoalesce=true) always fall to atomicWriteJson with full
+ * durability regardless of this param.
  */
 /** @internal */
-export function saveRunTasksCoalesced(manifest: TeamRunManifest, tasks: TeamTaskState[], skipCoalesce: boolean = false): void {
+export function saveRunTasksCoalesced(
+	manifest: TeamRunManifest,
+	tasks: TeamTaskState[],
+	skipCoalesce: boolean = false,
+	durability: WriteDurability = "full",
+): void {
 	// ST-4: refuse to persist [] over a previously-non-empty tasks file.
 	if (!shouldPersistTasks(manifest, tasks)) return;
-	// FIX: Invalidate cache BEFORE atomic write to prevent stale cache serving.
-	invalidateRunCache(manifest.stateRoot);
+	// PERF (2026-08-24, Task 12): invalidating the WHOLE entry made every
+	// loadRunManifestById after a coalesced save re-read + re-parse
+	// manifest.json (24KB+) even though the manifest file did not change —
+	// persistSingleTaskUpdate's next call (~500ms later) always paid it. Keep
+	// the manifest half of the entry and zero only the tasks stamps, which is
+	// the exact pre-existing signal for "tasks on disk may be stale" (coalesced
+	// write not landed yet). The load path cooperates: the zeroed tasks stamps
+	// force the slow path (tasks are always re-read from disk), but when the
+	// retained manifest stamps still match a fresh stat of manifest.json — the
+	// same mtime/size verification the fast path performs — the retry loop
+	// reuses the cached manifest object and skips the re-read + re-parse.
+	// Crash safety is unchanged: a zeroed tasks stamp can only cause a miss,
+	// never a stale hit, and a concurrent manifest rewrite changes mtime/size
+	// so the manifest reuse never serves stale content. Generation semantics
+	// unchanged — setManifestCache stamps the CURRENT generation, so a
+	// concurrent writer's bump still invalidates us.
+	const cached = manifestCache.get(manifest.stateRoot);
+	if (cached) {
+		setManifestCache(manifest.stateRoot, { ...cached, tasks, tasksMtimeMs: 0, tasksSize: 0 });
+	} else {
+		invalidateRunCache(manifest.stateRoot);
+	}
 	try {
 		fs.statSync(manifest.stateRoot);
 	} catch {
 		return;
 	}
-	atomicWriteJsonCoalesced(manifest.tasksPath, tasks, undefined, { compact: true }, skipCoalesce);
+	atomicWriteJsonCoalesced(manifest.tasksPath, tasks, undefined, { compact: true, durability }, skipCoalesce);
 }
 
 export async function saveRunTasksAsync(manifest: TeamRunManifest, tasks: TeamTaskState[]): Promise<void> {
@@ -873,7 +1013,19 @@ export function loadRunManifestById(cwd: string, runId: string): { manifest: Tea
 	let tasks: TeamTaskState[] | undefined;
 	while (attempts < LOAD_MANIFEST_RETRY_LIMIT) {
 		const freshStat = fs.statSync(manifestPath);
-		manifest = readJsonFile<TeamRunManifest>(manifestPath);
+		// PERF (2026-08-24, Task 12 realized): after saveRunTasksCoalesced the
+		// cache keeps the manifest half of the entry while zeroing only the
+		// tasks stamps, so this slow path runs solely to refresh tasks. When the
+		// retained manifest stamps still match the fresh stat — the exact
+		// mtime/size verification the fast path performs — reuse the cached
+		// manifest object instead of re-reading + re-parsing manifest.json.
+		// Stamp verification is NOT bypassed: any manifest.json rewrite changes
+		// mtime/size and falls back to the disk read. The tasks re-read below
+		// still always happens — zeroed tasks stamps must force it.
+		manifest =
+			cached && cached.manifestMtimeMs === freshStat.mtimeMs && cached.manifestSize === freshStat.size
+				? cached.manifest
+				: readJsonFile<TeamRunManifest>(manifestPath);
 		const freshTasksStat = fs.existsSync(tasksPath) ? fs.statSync(tasksPath) : undefined;
 		tasks = loadTasksWithRecovery(tasksPath, manifest?.eventsPath ?? path.join(stateRoot, "events.jsonl"), manifest?.runId ?? runId);
 		// If size/mtime didn't change between stat and read, we're consistent.
@@ -1015,7 +1167,17 @@ export async function loadRunManifestByIdAsync(
 	let attempts = 0;
 	while (attempts < LOAD_MANIFEST_RETRY_LIMIT) {
 		const freshStat = await fs.promises.stat(manifestPath);
-		manifest = await readJsonFileAsync<TeamRunManifest>(manifestPath);
+		// PERF (2026-08-24, Task 12 realized): async twin of the sync reuse —
+		// after saveRunTasksCoalesced only the tasks stamps are zeroed, so when
+		// the retained manifest stamps match the fresh stat (same verification
+		// the fast path performs), reuse the cached manifest object instead of
+		// re-reading + re-parsing manifest.json. A manifest.json rewrite changes
+		// mtime/size and falls back to the disk read; the tasks re-read below
+		// always happens.
+		manifest =
+			cached && cached.manifestMtimeMs === freshStat.mtimeMs && cached.manifestSize === freshStat.size
+				? cached.manifest
+				: await readJsonFileAsync<TeamRunManifest>(manifestPath);
 		const freshTasksStat = await fs.promises.stat(tasksPath).catch(() => undefined);
 		tasks = await loadTasksWithRecoveryAsync(
 			tasksPath,

package/src/state/types.ts

@@ -408,6 +408,9 @@ export interface TeamRunManifest {
 	 * models.json happens to list first.
 	 */
 	modelContext?: RunModelContext;
+	/** MuxSurface A1 (spec §8.3): pane/pid/lockout state of this run. Absent on
+	 *  runs that never booted a surface worker and on older manifests. */
+	surface?: ManifestSurfaceState;
 }
 
 export interface RunModelContext {
@@ -421,6 +424,54 @@ export interface RunModelContext {
 	availableModels?: string[];
 }
 
+/**
+ * MuxSurface A1 run-scope surface state (spec §8.3 / §12.3). Written by the
+ * team-runner's surface-degrade controller (runtime/surface/degrade.ts) and
+ * read by doctor (T12). Plain JSON — manifests parse without a schema, so an
+ * absent field means "no surface worker ever booted" and older writers simply
+ * don't emit it (backward-compatible in both directions).
+ *
+ * Per-run scope: every new run starts without `surface`, which IS the
+ * "reset ở run sau" of the anti-flap policy (spec §7 step 3).
+ */
+export interface ManifestSurfaceState {
+	provider: "tmux" | "herdr" | null;
+	/** taskId → pane id of the LIVE pane (removed when the pane is released). */
+	panes: Record<string, string>;
+	/** taskId → pid, captured from the worker's own `worker.started` event. */
+	workerPids: Record<string, number>;
+	/**
+	 * taskId → session file path when the worker self-reports one (optional
+	 * field of §12.2 — never populated in A1 because pi does not expose its
+	 * session path to extensions; kept for the degrade-resume seam).
+	 */
+	sessionPaths: Record<string, string>;
+	/**
+	 * Tab-layout (spec 2026-08-27-surface-tab-layout §5): tabKey (runId) →
+	 * tab/window ids của run — ghi khi worker spawn trong tab-flow (handle.tabId
+	 * qua outcome), KHÔNG gỡ khi từng worker xong (tab sống tới run end). Entry
+	 * được clear (giữ key rỗng) khi run end đã đóng tab qua closeTabForRun.
+	 * Run dài vượt MAX_PANES_PER_TAB tích lũy nhiều id cùng key.
+	 *
+	 * Manifest TRÊN ĐĨA giữ nguyên tabIds sau run end (evidence cho doctor) —
+	 * tabs non-empty KHÔNG đồng nghĩa orphan; doctor phải liveness-check từng
+	 * tabId qua mux rồi close-by-ID idempotent (cleanupOrphanSurfacePanes,
+	 * provider.closeTabById), không đóng mù theo số entry.
+	 */
+	tabs?: Record<string, string[]>;
+	/**
+	 * Surface is OFF for the rest of this run since `since`:
+	 * - cause "degrade": ≥1 degrade entry after the classify timeout
+	 *   (anti-flap; counts keep per-cause evidence for doctor).
+	 * - cause "spawn-fail": 3 consecutive spawn failures.
+	 */
+	lockout?: {
+		since: string;
+		counts: { pane: number; mux: number };
+		cause: "degrade" | "spawn-fail";
+	};
+}
+
 export interface UsageState {
 	input?: number;
 	output?: number;
@@ -554,6 +605,8 @@ export interface TeamTaskState {
 	role: string;
 	agent: string;
 	title: string;
+	/** Full step body (the detailed plan text behind `title`). */
+	description?: string;
 	displayName?: string;
 	status: TeamTaskStatus;
 	dependsOn: string[];

package/src/ui/dock-footer.ts

@@ -0,0 +1,49 @@
+/**
+ * dock-footer.ts — dependency-free bridge between the crew dock and the
+ * crew-vibes footer.
+ *
+ * When `ui.widgetPlacement` is `"bottom"`, the dock's rendered lines are
+ * produced by the crew widget but PAINTED by the crew-vibes footer, below the
+ * quota/meter lines — the very bottom of the terminal. The two halves are
+ * mounted by different modules (widget/index.ts owns the widget lifecycle,
+ * crew-vibes/footer.ts owns the footer), so the connection lives here as a
+ * tiny observable registry with no imports:
+ *   - the widget registers a per-render line provider;
+ *   - crew-vibes flips the "sink" flag when its footer is (un)installed;
+ *   - the footer pulls the provider's lines on every render.
+ *
+ * Safety: the widget falls back to pi's `belowEditor` widget slot whenever no
+ * footer sink is active (crew-vibes disabled), so `"bottom"` never silently
+ * hides the dock.
+ */
+
+export type FooterDockLinesProvider = (width: number) => string[];
+
+let dockProvider: FooterDockLinesProvider | undefined;
+let sinkActive = false;
+
+/** Register the dock line provider (widget side). Pass `undefined` to detach. */
+export function setFooterDockProvider(provider: FooterDockLinesProvider | undefined): void {
+	dockProvider = provider;
+}
+
+/** Current dock line provider, or undefined when the dock is not in the footer. */
+export function getFooterDockProvider(): FooterDockLinesProvider | undefined {
+	return dockProvider;
+}
+
+/** Mark whether a footer sink (crew-vibes) is currently installed. */
+export function setFooterDockSinkActive(active: boolean): void {
+	sinkActive = active;
+}
+
+/** True while crew-vibes' custom footer is installed and can host the dock. */
+export function isFooterDockSinkActive(): boolean {
+	return sinkActive;
+}
+
+/** Test isolation. */
+export function resetFooterDockRegistry(): void {
+	dockProvider = undefined;
+	sinkActive = false;
+}