pi-crew 0.11.0 → 0.11.2

package/src/state/crew-init.ts

@@ -13,10 +13,20 @@
  * The `node:path` import is retained as a *fallback* (only used when the
  * binding is healthy). Don't add new dependencies on other pi-crew modules.
  *
+ * TWO sanctioned exceptions (RR-020):
+ *   - `node:os` — a builtin like fs/path, used ONLY inside try/catch so a
+ *     jiti namespace race degrades to "no home/tmp boundary" (the pre-RR-020
+ *     walk) instead of crashing ensureCrewDirectory.
+ *   - `../utils/project-markers.ts` — a zero-import module of plain string
+ *     literals, so it cannot itself suffer the namespace race and it keeps
+ *     this resolver from drifting away from `src/utils/paths.ts`.
+ *
  * See: https://github.com/baphuongna/pi-crew/issues/28
  */
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
+import { PROJECT_DIR_MARKERS, PROJECT_FILE_MARKERS } from "../utils/project-markers.ts";
 import { atomicWriteFile } from "./atomic-write.ts";
 import { updateGitignore } from "./gitignore-manager.ts";
 
@@ -164,29 +174,94 @@ function safeResolve(p: string, pathDep?: typeof path): string {
 }
 
 function findProjectRoot(start: string, pathDep?: typeof path): string | undefined {
-	const dirMarkers = [".git", ".hg", ".svn"];
-	const fileMarkers = ["package.json", "pyproject.toml", "Cargo.toml", "go.mod"];
-	// Use `parseRoot` (inlined above) to avoid `path.parse` for the critical
-	// termination root — fixes the jiti namespace race in issue #28.
-	const root = parseRoot(start);
+	// Marker lists come from src/utils/project-markers.ts (RR-020 Fix 1) so this
+	// resolver can never drift from src/utils/paths.ts:computeRepoRoot again —
+	// the drift resolved `parent/subproject` (.pi) to `parent/.crew` here while
+	// paths.ts resolved the same cwd to `subproject/.pi/teams` (two roots).
+	// The module has NO imports of its own, so it is safe under the jiti
+	// namespace race documented at the top of this file.
+	// RR-020 hardening (cold-verify round 2): the marker arrays are the ONE
+	// critical-path dependency on a static import binding. Under the jiti
+	// namespace race (issue #28) a binding can arrive undefined — degrade to the
+	// narrow `.git`-only probe (findProjectRoot then returns undefined more
+	// often, so computeCrewRoot anchors the crew root at the cwd — the same
+	// fallback paths.ts uses) instead of throwing inside ensureCrewDirectory,
+	// the very function hardened for #28. Mirrors the defensive style of
+	// safeJoin/safeDirname/parseRoot and the lazy updateGitignore import.
+	function markerLists(): { dirs: string[]; files: string[] } {
+		try {
+			if (Array.isArray(PROJECT_DIR_MARKERS) && Array.isArray(PROJECT_FILE_MARKERS)) {
+				return { dirs: PROJECT_DIR_MARKERS as string[], files: PROJECT_FILE_MARKERS as string[] };
+			}
+		} catch {
+			// namespace unavailable — fall through to the narrow probe
+		}
+		return { dirs: [".git"], files: [] };
+	}
+	const markers = markerLists();
+	const hasMarker = (dir: string): boolean =>
+		markers.dirs.some((marker) => fs.existsSync(safeJoin(dir, marker))) ||
+		markers.files.some((marker) => fs.existsSync(safeJoin(dir, marker)));
 	let current = safeResolve(start, pathDep);
+	// RR-020 cold-verify follow-up: match findRepoRoot (paths.ts) which
+	// realpaths the start BEFORE walking, so the boundary comparisons below
+	// compare canonical-to-canonical (macOS /var -> /private/var). Best-effort:
+	// ENOENT keeps the lexical path, exactly like findRepoRoot's fallback.
+	try {
+		current = fs.realpathSync(current);
+	} catch {
+		// keep the lexical resolution
+	}
+	// Use `parseRoot` (inlined above) to avoid `path.parse` for the critical
+	// termination root — fixes the jiti namespace race in issue #28. Computed
+	// from the RESOLVED `current` (post-realpath) so a root-prefix change
+	// through a symlink cannot desync `current !== root` (paths.ts computes
+	// path.parse on the realpath'd start for the same reason).
+	const root = parseRoot(current);
+	// RR-020 cold-verify follow-up (bug-029 parity): home/tmp boundary STOP.
+	// computeRepoRoot (paths.ts) refuses to check markers at $HOME or the temp
+	// root; this walk did not, so once the marker lists were unified onto the
+	// wide set, `$HOME/.pi` (created by userPiRoot()) became a marker HERE — a
+	// MARKERLESS cwd under $HOME resolved crew-init to $HOME (⇒
+	// $HOME/.pi/teams) while projectCrewRoot resolved to <cwd>/.crew: the
+	// two-roots bug Fix 1 was meant to kill, in a new shape. `os` access is
+	// defensive: under the jiti namespace race (issue #28) the binding can be
+	// undefined — degrade to "no boundary" (the pre-RR-020 walk), never crash.
+	let home: string | undefined;
+	let tempRoot: string | undefined;
+	try {
+		home = canonicalBoundary(os.homedir());
+		tempRoot = canonicalBoundary(os.tmpdir());
+	} catch {
+		home = undefined;
+		tempRoot = undefined;
+	}
+	const atBoundary = (dir: string): boolean => (home !== undefined && dir === home) || (tempRoot !== undefined && dir === tempRoot);
 	// Walk up to find project root
 	while (current !== root) {
-		for (const marker of dirMarkers) {
-			if (fs.existsSync(safeJoin(current, marker))) return current;
-		}
-		for (const marker of fileMarkers) {
-			if (fs.existsSync(safeJoin(current, marker))) return current;
-		}
+		// Stop walking before checking markers at home or temp root.
+		if (atBoundary(current)) return undefined;
+		if (hasMarker(current)) return current;
 		const parent = safeDirname(current);
 		if (parent === current) break;
 		current = parent;
 	}
 	// Check root as fallback
-	if (dirMarkers.some((m) => fs.existsSync(safeJoin(root, m)))) return root;
+	if (atBoundary(root)) return undefined;
+	if (hasMarker(root)) return root;
 	return undefined;
 }
 
+/** Canonicalize a boundary dir for comparison with the (realpath'd) walk.
+ *  Best-effort: an unresolvable path stays lexical. */
+function canonicalBoundary(p: string): string {
+	try {
+		return fs.realpathSync(p);
+	} catch {
+		return p;
+	}
+}
+
 /**
  * Compute the crew root directory for a given working directory.
  * Matches src/utils/paths.ts:projectCrewRoot() logic.

package/src/state/event-log/cursor.ts

@@ -114,6 +114,10 @@ export function readEvents(eventsPath: string): TeamEvent[] {
 
 export interface EventCursorOptions {
 	sinceSeq?: number;
+	/** Delivery cap for one read. When `limit` truncates the result, `events` is
+	 *  a PREFIX of everything available — resume from the returned `nextSeq`
+	 *  (never from `nextByteOffset`; see the continuation contract on
+	 *  `readEventsCursor`). */
 	limit?: number;
 	fromByteOffset?: number;
 	/** R-03: generation the caller captured on its previous read. When set, a
@@ -528,6 +532,30 @@ export function clearEventsCursorTailCache(eventsPath?: string): void {
 	cursorTailCache.delete(eventsPath);
 }
 
+/**
+ * Read team events with an optional incremental anchor (`sinceSeq`) plus a
+ * delivery cap (`limit`).
+ *
+ * Continuation / backpressure contract (BR-08):
+ *  - `nextSeq` is the continuation token for events that CARRY `metadata.seq`
+ *    (scheduler-emitted events): the max seq among the events DELIVERED by
+ *    this call — never a watermark past an undelivered event. Resume with
+ *    `{ sinceSeq: nextSeq }` (`>` comparison) to receive the rest.
+ *    LIMITS (cold-verify correction — documented, not fixed here): events
+ *    WITHOUT `metadata.seq` (e.g. the worker progress channel) are filtered
+ *    out of the sinceSeq path entirely, and DUPLICATE seqs cannot be paged
+ *    through by seq. Those cases need the `fromByteOffset` anchor.
+ *  - `total` is the number of events AVAILABLE for this read (after the
+ *    sinceSeq filter, before the `limit` slice) — EXCEPT that the tail cap
+ *    (TAIL_EVENT_CAP) may drop a prefix first, in which case `total` counts
+ *    only the retained suffix.
+ *  - `nextByteOffset` is an OPTIONAL incremental-read accelerator, and is only
+ *    returned when it is a SAFE resume anchor: on the `fromByteOffset` path it
+ *    is OMITTED whenever `limit` truncated the delta, because the underlying
+ *    offset then points past the ENTIRE delta (undelivered tail included) —
+ *    resuming from it would silently skip events. The default (non-byte)
+ *    path never returns it at all.
+ */
 export function readEventsCursor(eventsPath: string, options: EventCursorOptions = {}): EventCursorResult {
 	// Incremental byte-offset path: read only new bytes since last known offset
 	if (options.fromByteOffset !== undefined) {
@@ -558,11 +586,19 @@ export function readEventsCursor(eventsPath: string, options: EventCursorOptions
 		const limit = positiveInteger(options.limit);
 		const events = limit !== undefined ? merged.slice(0, limit) : merged;
 		const returnedMaxSeq = events.reduce((max, event) => Math.max(max, event.metadata?.seq ?? 0), sinceSeq);
+		// BR-08: `newState.byteOffset` sits past the ENTIRE delta read above —
+		// including the events the `limit` slice just dropped. Handing that back
+		// as `nextByteOffset` let a caller resume PAST events it never saw (silent
+		// loss: the delta read then returns an empty tail). Only expose the
+		// accelerator when this call delivered the whole delta; under truncation
+		// the caller must continue from `nextSeq` (see the doc comment on
+		// readEventsCursor).
+		const deliveredWholeDelta = limit === undefined || merged.length <= limit;
 		return {
 			events,
 			nextSeq: returnedMaxSeq,
 			total: merged.length,
-			nextByteOffset: newState.byteOffset,
+			...(deliveredWholeDelta ? { nextByteOffset: newState.byteOffset } : {}),
 			generation: liveGen,
 		};
 	}

package/src/state/event-log/event-log-rotation.ts

@@ -169,18 +169,83 @@ export interface CompactionResult {
  * 6. Return compaction stats
  */
 export function compactEventLog(eventsPath: string, config?: Partial<RotationConfig>): CompactionResult | undefined {
-	const prepared = prepareCompaction(eventsPath, config);
-	if (!prepared) return undefined;
-	// FIX: Wrap entire read-compact-write-recover sequence in lock to prevent
-	// event loss during compaction. Without lock, events can be appended between
-	// read and write, lost silently.
+	// US-001 (2026-09-22): lock-scope reduction. The expensive part is the READ +
+	// parse of the whole log (prepareCompaction). It is read-only, so it does NOT
+	// need the append lock: hold the lock ONLY for the write+recover phase
+	// (applyCompactionUnlocked), which is what must be atomic w.r.t. appends.
+	//
+	// Why this is safe: appenders take the SAME lock, so an append can only land
+	// before our prepareCompaction read or after our applyCompactionUnlocked
+	// write — never inside the write. applyCompactionUnlocked already re-reads
+	// after the write and splices back any events that arrived in the window
+	// (C2 recovery), so no event is lost; it only becomes slightly more likely to
+	// splice, which is exactly the case it was built for.
+	//
+	// No concurrent-rotator guard is needed: this function is fully SYNCHRONOUS
+	// (prepareCompaction and withEventLogLockSync both block), so two calls on the
+	// same path cannot interleave within a process. An in-flight flag was tried
+	// and removed — it was untestable dead code (mutation survived), and the
+	// synchronous execution already serializes rotators. Cross-process rotators
+	// are serialized by the on-disk lock in withEventLogLockSync.
 	//
 	// NOTE (Round 24 BUG 1): callers ALREADY holding the event-log lock (e.g.
-	// appendEventInsideLock in event-log.ts) must call applyCompactionUnlocked
+	// appendEventInsideLock in event-log.ts) must still call applyCompactionUnlocked
 	// directly — calling compactEventLog from inside the lock deadlocks (the
 	// mkdir lock is not re-entrant → 5s timeout → compaction never ran → the
 	// log grew unbounded until events were silently dropped past 50MB).
-	return withEventLogLockSync(eventsPath, () => applyCompactionUnlocked(eventsPath, prepared));
+	const prepared = prepareCompaction(eventsPath, config);
+	if (!prepared) return undefined;
+	return compactPreparedEventLog(eventsPath, prepared);
+}
+
+/**
+ * US-001 phase 3 — the LOCKED write phase, extracted so the read→write race is
+ * deterministically testable: a caller (test) can run prepareCompaction, append
+ * to the file (simulating another process landing events in the window), then
+ * call this and assert nothing was lost.
+ *
+ * prepareCompaction reads OUTSIDE the lock, so an appender may have added events
+ * between that read and this write. applyCompactionUnlocked writes exactly
+ * `prepared.lines` (the kept window from the snapshot), which would CLOBBER those
+ * newer events; its C2 recovery only re-splices events that were in `kept`, not
+ * ones it never saw. So under the lock we read the bytes appended after the
+ * snapshot offset and append them to the write. Appenders hold the same lock,
+ * so this read is a complete tail snapshot.
+ */
+export function compactPreparedEventLog(
+	eventsPath: string,
+	prepared: { lines: string; originalSize: number; originalCount: number; kept: TeamEvent[] },
+): CompactionResult | undefined {
+	return withEventLogLockSync(eventsPath, () => {
+		const merged = { ...prepared, lines: prepared.lines + readTailSince(eventsPath, prepared.originalSize) };
+		return applyCompactionUnlocked(eventsPath, merged);
+	});
+}
+
+/**
+ * US-001: return the raw text appended to `filePath` after `offset`, or "" when
+ * nothing was appended / the file was replaced by a smaller one (a foreign
+ * rotation — caller then proceeds without a splice, which is the pre-US-001
+ * behaviour). Must be called while holding the event-log lock.
+ */
+function readTailSince(filePath: string, offset: number): string {
+	try {
+		const size = fs.statSync(filePath).size;
+		if (size <= offset) return "";
+		const fd = fs.openSync(filePath, "r");
+		try {
+			const length = size - offset;
+			const buf = Buffer.alloc(length);
+			const read = fs.readSync(fd, buf, 0, length, offset);
+			const tail = buf.subarray(0, read).toString("utf-8");
+			// Only splice complete lines (a partial trailing write would corrupt JSONL).
+			return tail.endsWith("\n") ? tail : tail.slice(0, tail.lastIndexOf("\n") + 1);
+		} finally {
+			fs.closeSync(fd);
+		}
+	} catch {
+		return "";
+	}
 }
 
 /** Round 24 (BUG 1): the lock-free pre-read for compaction. Safe to run

package/src/state/stores/active-run-registry.ts

@@ -61,6 +61,14 @@ function removeStaleRegistryLock(lockPath: string, staleMs: number): boolean {
 }
 
 function withRegistryLock<T>(fn: () => T): T {
+	// US-010 (2026-09-22): sleepSync below is INTENTIONAL — this lock is sync-only
+	// (fn is synchronous, and its callers at :352/:378 are sync). Converting the
+	// backoff to `await sleep` here would repeat the documented v0.9.26
+	// starvation: the sync spinner's sleepSync blocks the event loop while an
+	// in-process async holder's `await`-based release can never run. The lock is
+	// held only for a sub-millisecond read-modify-write and the loop is bounded by
+	// a 10s deadline, so blocking is bounded and rare (contention is cross-process
+	// only). See src/state/event-log/sequence-cache.ts:270 for the same reasoning.
 	const filePath = registryLockPath();
 	const staleMs = 30_000;
 	fs.mkdirSync(path.dirname(filePath), { recursive: true });
@@ -84,7 +92,11 @@ function withRegistryLock<T>(fn: () => T): T {
 			break;
 		} catch (error) {
 			const code = (error as NodeJS.ErrnoException).code;
-			if (code !== "EEXIST") throw error;
+			// Windows lock contention surfaces as EPERM/EACCES/EBUSY (not EEXIST) while
+			// another handle holds the lock file open — cross-process contention in
+			// CI (run 36019884258). Treat as contention: bounded retry via the 10s
+			// deadline below, mirroring isLockContention() in coordination/locks.ts.
+			if (code !== "EEXIST" && code !== "EPERM" && code !== "EACCES" && code !== "EBUSY") throw error;
 			if (!removeStaleRegistryLock(filePath, staleMs) && Date.now() > deadline)
 				throw new Error("Active-run registry is locked by another operation.");
 			sleepSync(Math.min(250, 25 * 2 ** attempt));

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

@@ -193,19 +193,37 @@ function resolveRunStateRoot(cwd: string, runId: string): string | undefined {
 	const now = Date.now();
 	const cached = runStateRootCache.get(key);
 	if (cached && cached.expiresAt > now) return cached.root;
-	const runsRoot = path.join(scopeBaseRoot(cwd), DEFAULT_PATHS.state.runsSubdir);
-	const scopedPath = resolveContainedRelativePath(runsRoot, runId, "runId");
-	try {
-		resolveRealContainedPath(runsRoot, runId);
-	} catch {
-		return undefined;
-	}
-	if (runStateRootCache.size >= RUN_STATE_ROOT_CACHE_MAX) {
-		const oldest = runStateRootCache.keys().next().value;
-		if (oldest !== undefined) runStateRootCache.delete(oldest);
+	// F-L1 (2026-09-22): listing (run-index scopedRunRoots) UNIONS the user and
+	// project run roots, but this resolution used scopeBaseRoot's single XOR
+	// pick — a run living under the OTHER root (e.g. created by another cwd or
+	// before the repo got a marker) listed fine yet FAILED every by-ID lookup:
+	// team status / prune / forget / scheduler provenance all returned "not
+	// found". Try the primary root first (hot path unchanged — one contained
+	// resolve + cache hit), then fall back to the other root. The no-repo case
+	// never falls back to a project path, mirroring scopedRunRoots' `if
+	// (projectRoot)` guard — resolution sees exactly what listing sees.
+	const candidates = useProjectState(cwd) ? [projectCrewRoot(cwd), userCrewRoot()] : [userCrewRoot()];
+	for (const root of candidates) {
+		const runsRoot = path.join(root, DEFAULT_PATHS.state.runsSubdir);
+		const scopedPath = resolveContainedRelativePath(runsRoot, runId, "runId");
+		// resolveRealContainedPath deliberately ACCEPTS a missing target (write-path
+		// semantics: ENOENT is fine, only symlink/escape violations throw) — so
+		// existence must be probed explicitly. Without this, the primary root
+		// always "wins" with a phantom path and the fallback can never run.
+		if (!fs.existsSync(path.join(scopedPath, DEFAULT_PATHS.state.manifestFile))) continue;
+		try {
+			resolveRealContainedPath(runsRoot, runId);
+		} catch {
+			continue; // symlink/escape violation under this root — try the other
+		}
+		if (runStateRootCache.size >= RUN_STATE_ROOT_CACHE_MAX) {
+			const oldest = runStateRootCache.keys().next().value;
+			if (oldest !== undefined) runStateRootCache.delete(oldest);
+		}
+		runStateRootCache.set(key, { root: scopedPath, expiresAt: now + RUN_STATE_ROOT_TTL_MS });
+		return scopedPath;
 	}
-	runStateRootCache.set(key, { root: scopedPath, expiresAt: now + RUN_STATE_ROOT_TTL_MS });
-	return scopedPath;
+	return undefined;
 }
 
 // PERF (2026-08-24): the artifacts containment verdict (existsSync + lstat +
@@ -239,7 +257,13 @@ function validateRunManifestPaths(cwd: string, runId: string, manifest: TeamRunM
 		manifest.eventsPath !== path.join(stateRoot, "events.jsonl")
 	)
 		return false;
-	const artifactsParent = path.join(scopeBaseRoot(cwd), DEFAULT_PATHS.state.artifactsSubdir);
+	// F-L1 (2026-09-22): derive the artifacts parent from the RESOLVED stateRoot's
+	// base root (…/<base>/state/runs/<runId>), not scopeBaseRoot — cross-root
+	// runs (state under the fallback root, artifacts written beside it at
+	// creation) must validate against their OWN root; scopeBaseRoot would
+	// reject every fallback-resolved run and keep it invisible by ID.
+	const baseRoot = path.resolve(stateRoot, "..", "..", "..");
+	const artifactsParent = path.join(baseRoot, 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.
@@ -409,9 +433,14 @@ export function createRunManifest(params: {
 	runKind?: "team-run" | "goal-loop" | "dynamic-workflow";
 	/** round-14 P1-5: typed workflow arguments for .dwf.ts scripts (ctx.args<T>()). */
 	args?: unknown;
+	/** Deterministic-capture support (2026-09-22): pin the run ID and/or clock
+	 * so tools like docs/ui-samples/capture.ts produce byte-stable output.
+	 * Defaults preserve current behavior (generated id, wall clock). */
+	runId?: string;
+	now?: () => Date;
 }): { manifest: TeamRunManifest; tasks: TeamTaskState[]; paths: RunPaths } {
-	const paths = createRunPaths(params.cwd);
-	const now = new Date().toISOString();
+	const paths = createRunPaths(params.cwd, params.runId);
+	const now = (params.now ? params.now() : new Date()).toISOString();
 	const tasks = params.workflow ? createTasksFromWorkflow(paths.runId, params.workflow, params.team, params.cwd, params.goal) : [];
 	const manifest: TeamRunManifest = {
 		schemaVersion: CURRENT_SCHEMA_VERSION,
@@ -479,7 +508,12 @@ export function createRunManifest(params: {
 	return { manifest, tasks, paths };
 }
 
-export function saveRunManifest(manifest: TeamRunManifest): void {
+export function saveRunManifest(manifest: TeamRunManifest, options?: { allowTerminalExit?: boolean }): TeamRunManifest {
+	// Finding 8 (2026-09-23): terminal-preserve at the WRITE layer. Mid-flight
+	// savers (task-runner artifact/progress writes carrying a stale in-memory
+	// "running" manifest) previously overwrote an externally-written terminal
+	// status; merge/finalize had their own guards but every other save site did
+	// not. Guard here so NO raw save can erase a terminal disk status.
 	// FIX: Capture the cached tasks array + mtime/size BEFORE we invalidate the
 	// cache. The previous implementation re-read tasks.json from disk after the
 	// manifest write (a JSON.parse + fs.readFileSync per call), which defeated
@@ -502,12 +536,13 @@ export function saveRunManifest(manifest: TeamRunManifest): void {
 	// which is always safe.
 	invalidateRunCache(manifest.stateRoot);
 	const manifestPath = path.join(manifest.stateRoot, "manifest.json");
+	const effective = preserveDiskTerminalStatus(manifest, options?.allowTerminalExit);
 	// REVIEW FIX (2026-09-10): reverted WI-2.2's coalesced conversion —
 	// saveRunManifest is a SYNCHRONOUS persist by name/contract (tests assert
 	// it, broker loadRunManifestById is a cross-process reader, and the
 	// statSync-based cache repopulation below needs the real post-write
 	// mtime/size). The 50ms coalesce window broke all three.
-	atomicWriteJson(manifestPath, manifest);
+	atomicWriteJson(manifestPath, effective);
 	// FIX: Re-populate cache with actual mtime/size so loadRunManifestById
 	// doesn't miss the cache on next read. Without this, every load until
 	// TTL expires would hit disk because cached 0 !== any real mtime.
@@ -516,16 +551,17 @@ export function saveRunManifest(manifest: TeamRunManifest): void {
 	// fresh tasks should call saveRunTasks or loadRunTasks separately.
 	const manifestStat = fs.statSync(manifestPath);
 	setManifestCache(manifest.stateRoot, {
-		manifest,
+		manifest: effective,
 		tasks: cachedTasks,
 		manifestMtimeMs: manifestStat.mtimeMs,
 		manifestSize: manifestStat.size,
 		tasksMtimeMs: cachedTasksMtimeMs,
 		tasksSize: cachedTasksSize,
 	});
+	return effective;
 }
 
-export async function saveRunManifestAsync(manifest: TeamRunManifest): Promise<void> {
+export async function saveRunManifestAsync(manifest: TeamRunManifest, options?: { allowTerminalExit?: boolean }): Promise<TeamRunManifest> {
 	// FIX: Capture cached tasks array + mtime/size BEFORE invalidating, same
 	// rationale as the sync saveRunManifest above. The async path previously
 	// always set tasks: [] with mtime/size 0, so any cache hit was guaranteed
@@ -538,7 +574,8 @@ export async function saveRunManifestAsync(manifest: TeamRunManifest): Promise<v
 	// after a crash. See saveRunManifest for full explanation.
 	invalidateRunCache(manifest.stateRoot);
 	const manifestPath = path.join(manifest.stateRoot, "manifest.json");
-	await atomicWriteJsonAsync(manifestPath, manifest);
+	const effective = preserveDiskTerminalStatus(manifest, options?.allowTerminalExit);
+	await atomicWriteJsonAsync(manifestPath, effective);
 	// FIX: Re-populate cache with actual mtime/size. See saveRunManifest.
 	// RACE GUARD: another concurrent async save (OPT-02) may unlink+rewrite
 	// manifest.json between our atomicWriteJsonAsync and this stat. If stat
@@ -553,13 +590,14 @@ export async function saveRunManifestAsync(manifest: TeamRunManifest): Promise<v
 		manifestStat = { mtimeMs: 0, size: 0 };
 	}
 	setManifestCache(manifest.stateRoot, {
-		manifest,
+		manifest: effective,
 		tasks: cachedTasks,
 		manifestMtimeMs: manifestStat.mtimeMs,
 		manifestSize: manifestStat.size,
 		tasksMtimeMs: cachedTasksMtimeMs,
 		tasksSize: cachedTasksSize,
 	});
+	return effective;
 }
 
 /**
@@ -803,6 +841,44 @@ function saveManifestAndTasksAtomicSync(manifest: TeamRunManifest, tasks: TeamTa
 export interface UpdateRunStatusOptions {
 	data?: Record<string, unknown>;
 	metadata?: Parameters<typeof appendEvent>[1]["metadata"];
+	/** Finding 8 (2026-09-23): allow leaving a TERMINAL disk status (resume is the
+	 * only legitimate terminal-exit flow). Defaults to false — a raw save with an
+	 * in-memory "running" manifest must never erase an externally-written
+	 * cancelled/failed/completed status (live race team_20260923175042: cancel
+	 * 17:51:08 → intermediate task-runner save re-wrote "running" → finalize
+	 * completed — the cancel was fully erased). */
+	allowTerminalExit?: boolean;
+}
+
+/** Finding 8: statuses a disk write must never silently leave. Mirrors
+ * isRunTerminalPreserved (merge-loop.ts) — kept local to avoid a runtime dep
+ * from the store layer to the runtime layer. */
+const DISK_TERMINAL_STATUSES: ReadonlySet<TeamRunManifest["status"]> = new Set(["cancelled", "failed", "completed"]);
+
+/** Finding 8 write-layer guard: if the DISK manifest is terminal and the
+ * incoming write carries a NON-terminal status (the erase class — a mid-flight
+ * saver with a stale in-memory "running" manifest), preserve the disk
+ * status/summary/updatedAt while keeping every other incoming field (artifacts,
+ * usage, surface…). Terminal→terminal re-decisions (e.g. cancelling a run that
+ * just completed — pinned by resume-cancel.test.ts) are LEGITIMATE and pass
+ * through; they are governed by canTransitionRunStatus at the updateRunStatus
+ * layer. Returns the effective manifest to persist. */
+function preserveDiskTerminalStatus(manifest: TeamRunManifest, allowTerminalExit: boolean | undefined): TeamRunManifest {
+	if (allowTerminalExit) return manifest;
+	// Terminal→terminal re-decisions pass through (governed by
+	// canTransitionRunStatus at the updateRunStatus layer); the guard applies
+	// ONLY to the erase class: a NON-terminal incoming status over terminal disk.
+	if (DISK_TERMINAL_STATUSES.has(manifest.status)) return manifest;
+	try {
+		const manifestPath = path.join(manifest.stateRoot, "manifest.json");
+		// Raw read (no cache): cross-process cancel writes must be seen NOW.
+		const raw = fs.readFileSync(manifestPath, "utf-8");
+		const disk = JSON.parse(raw) as TeamRunManifest;
+		if (!DISK_TERMINAL_STATUSES.has(disk.status) || disk.status === manifest.status) return manifest;
+		return { ...manifest, status: disk.status, summary: disk.summary, updatedAt: disk.updatedAt };
+	} catch {
+		return manifest; // no disk manifest yet (create) or unreadable — normal write
+	}
 }
 
 export function updateRunStatus(
@@ -820,7 +896,21 @@ export function updateRunStatus(
 		updatedAt: new Date().toISOString(),
 		summary: summary ?? manifest.summary,
 	};
-	saveRunManifest(updated);
+	// Finding 8 (2026-09-23): the write-layer guard may PRESERVE a terminal disk
+	// status (an external cancel/reconciler write the in-memory manifest never
+	// saw). In that case do NOT emit run.<status>, do NOT flip the manifest —
+	// record the refusal and return the preserved state. Resume passes
+	// allowTerminalExit for its legitimate cancelled→running transition.
+	const saved = saveRunManifest(updated, { allowTerminalExit: options.allowTerminalExit });
+	if (saved.status !== status) {
+		appendEvent(saved.eventsPath, {
+			type: "run.terminal_preserved",
+			runId: saved.runId,
+			message: `Preserved terminal status '${saved.status}'; refused in-memory transition to '${status}'.`,
+			data: { preserved: saved.status, refused: status },
+		});
+		return saved;
+	}
 	// Unregister from active-run-index when run reaches a terminal status.
 	// Without this, stale entries accumulate (e.g. integration tests in /tmp) and
 	// Pi UI shows ghost "queued" runs that are actually completed/failed/cancelled.

package/src/state/types.ts

@@ -543,6 +543,10 @@ export interface GoalLoopState {
 	nextTurnFeedback?: string;
 	/** The team-run of the current in-flight turn (for cancel/steer). */
 	currentRunId?: string;
+	/** GL-1b (2026-09-22): why the last turn (or the loop itself) failed —
+	 * persisted at goal level because turn-run dirs are pruned (keep=10 at
+	 * session start) and otherwise the reason becomes unrecoverable. */
+	lastTurnError?: string;
 	verdicts: GoalVerdict[];
 	history: {
 		runId: string;

package/src/ui/adaptive-card.ts

@@ -0,0 +1,65 @@
+/**
+ * AdaptiveCard — a width-deferred card component (R2, 2026-09-16).
+ *
+ * Problem it fixes: pi-crew's tool-renderer cards used to be BUILT as a
+ * pre-formatted string at a guessed width (`ctx.width || process.stdout.columns
+ * || 116`) and handed to `new Text(...)`. Pi's ToolRenderContext carries NO
+ * width field — neither the TUI nor export-html pass one — so the guess could
+ * never match the real render column. `Text.render(width)` WRAPS lines wider
+ * than the column, which tore the box frame apart (top border split mid-line,
+ * right border vanished). This hit HTML export hardest: export renders every
+ * card at width=100 while a non-TTY export process builds at the 116 fallback.
+ *
+ * Design: build the frame at RENDER time, at the width the caller actually
+ * provides. The card receives a `builder(width) => string`; `render(width)`
+ * invokes it and delegates line-wrapping/padding to a zero-padding `Text`.
+ * Results are cached per width (mirroring Text's own cache) so repeated
+ * renders of an unchanged card cost nothing.
+ *
+ * Fail-visible: a builder exception surfaces as a red `✖ card render error`
+ * line instead of propagating into the TUI render loop (which has no per-
+ * component catch). Construction-time errors in the ToolRenderer wrappers
+ * keep their own catch — this is the third and final layer.
+ */
+
+import { Text } from "@earendil-works/pi-tui";
+import type { CrewComponent } from "./component.ts";
+
+export class AdaptiveCard implements CrewComponent {
+	#builder: (width: number) => string;
+	#errorStyle: (text: string) => string;
+	#text = new Text("", 0, 0);
+	#cachedWidth: number | undefined;
+	#cachedLines: string[] | null = null;
+
+	/**
+	 * @param builder produces the full card text (frame included) for a width.
+	 *   Must keep every line within `width` visual columns — the same contract
+	 *   the old fixed-width builders already obeyed for their baked width.
+	 * @param errorStyle theme.fg("error", …) adapter for the fail-visible line.
+	 */
+	constructor(builder: (width: number) => string, errorStyle: (text: string) => string = (t) => t) {
+		this.#builder = builder;
+		this.#errorStyle = errorStyle;
+	}
+
+	invalidate(): void {
+		this.#cachedLines = null;
+		this.#cachedWidth = undefined;
+	}
+
+	render(width: number): string[] {
+		if (this.#cachedLines !== null && this.#cachedWidth === width) return this.#cachedLines;
+		let text: string;
+		try {
+			text = this.#builder(width);
+		} catch (e) {
+			const msg = e instanceof Error ? e.message : String(e);
+			text = this.#errorStyle(`✖ card render error: ${msg.slice(0, 60)}`);
+		}
+		this.#text.setText(text);
+		this.#cachedLines = this.#text.render(width);
+		this.#cachedWidth = width;
+		return this.#cachedLines;
+	}
+}