@zhuxixi/pi-agent-board 0.7.0 → 0.9.0

package/src/core/host-protocol.mjs

@@ -0,0 +1,62 @@
+/** Control-socket client identity helpers (issue #103).
+ *
+ * Client ids travel in the `hello` handshake. `helloBookkeeping` turns the
+ * classification into the explicit socket policy: probes and the resident
+ * editor-state reporter stay out of `attachedClients` / `attachedEver`, and
+ * probes additionally never trigger a host.json write — counting or writing
+ * either would pin every host against warm-host reclaim (issue #75 / #103 §C /
+ * #130).
+ */
+
+/** Read-only endpoint probe (attach resolver); never counts as attached. */
+export const CLIENT_ID_PROBE = "probe";
+/** Resident editor-state reporter inside a hosted child; never counts as attached. */
+export const CLIENT_ID_EDITOR_REPORTER = "editor-reporter";
+
+/**
+ * @param {{ type?: string, clientId?: string } | null | undefined} msg
+ * @returns {"probe" | "editor-reporter" | "client"}
+ */
+export function classifyClientHello(msg) {
+	const clientId = msg && typeof msg.clientId === "string" ? msg.clientId : "";
+	if (clientId === CLIENT_ID_PROBE) return "probe";
+	if (clientId === CLIENT_ID_EDITOR_REPORTER) return "editor-reporter";
+	return "client";
+}
+
+/**
+ * Socket bookkeeping implied by a hello classification (issue #103 §C / #130).
+ *
+ * `probe` and `editor-reporter` are bookkeeping-only: neither may keep
+ * `attachedClients` — whose sole source is the runner's `clients` set —
+ * non-zero, or warm-host reclaim never fires and hosts leak (issue #75). Both
+ * therefore leave `clients` at hello time, while their socket stays writable so
+ * probe replies and editor_state keep flowing.
+ *
+ * `persist: false` for probes is deliberate: the attach resolver probes every
+ * HOST_PROBE_RETRY_MS (see host-probe.mjs), so one host.json write per probe
+ * would amplify fenced writes — the exact cost the runner's probe-socket write
+ * suppression exists to avoid. Dropping the socket from `clients` already makes
+ * the in-memory count right, and the next heartbeat (<=1s) persists it.
+ *
+ * `suppressCloseWrite: true` is the other half of that suppression: close is the
+ * wrong moment to flush a record a probe never changed.
+ *
+ * An unrecognized kind falls back to the real-client row on purpose — counting
+ * an unknown connection is the conservative direction (it can only delay
+ * reclaim, never risk killing a host with a live client).
+ *
+ * @param {"probe" | "editor-reporter" | "client"} kind
+ * @returns {{ keepInClients: boolean, registerReporter: boolean,
+ *             flipAttachedEver: boolean, persist: boolean, suppressCloseWrite: boolean }}
+ */
+export function helloBookkeeping(kind) {
+	switch (kind) {
+		case "probe":
+			return { keepInClients: false, registerReporter: false, flipAttachedEver: false, persist: false, suppressCloseWrite: true };
+		case "editor-reporter":
+			return { keepInClients: false, registerReporter: true, flipAttachedEver: false, persist: true, suppressCloseWrite: false };
+		default:
+			return { keepInClients: true, registerReporter: false, flipAttachedEver: true, persist: true, suppressCloseWrite: false };
+	}
+}

package/src/core/launch-options.mjs

@@ -361,6 +361,43 @@ export function filterCwdCandidates(candidates, query) {
 	return candidates.filter((entry) => entry.path.toLowerCase().includes(q));
 }
 
+/**
+ * Whether two path strings resolve to the same directory. Blank inputs never
+ * match (path.resolve("") would silently equal process.cwd()).
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+export function sameResolvedDir(a, b) {
+	const na = String(a ?? "").trim();
+	const nb = String(b ?? "").trim();
+	if (!na || !nb) return false;
+	return path.resolve(expandHome(na)) === path.resolve(expandHome(nb));
+}
+
+/**
+ * Browse-mode Tab completion for the cwd picker. Completes to the highlighted
+ * suggestion with a trailing separator (so the next recompute lists that
+ * directory's children); when the highlight already equals the current query
+ * (no progress), advances cyclically so repeated Tab drills downward. A lone
+ * self suggestion stays put, so drilling stops naturally at leaf directories.
+ * @param {string} query
+ * @param {string[]} suggestions
+ * @param {number} index
+ * @returns {{query: string, completed: string, usedIndex: number} | null}
+ */
+export function browseTabCompletion(query, suggestions, index) {
+	if (!suggestions || suggestions.length === 0) return null;
+	const len = suggestions.length;
+	let usedIndex = ((index % len) + len) % len;
+	let completed = suggestions[usedIndex];
+	if (len > 1 && sameResolvedDir(completed, query)) {
+		usedIndex = (usedIndex + 1) % len;
+		completed = suggestions[usedIndex];
+	}
+	return { query: completed + path.sep, completed, usedIndex };
+}
+
 /**
  * Decide cwd picker mode + suggestions for a query: favorites when the query
  * is empty or matches ranked candidates, filesystem browse otherwise.

package/src/core/locks.mjs

@@ -143,6 +143,12 @@ function releaseLock(lockPath, fs) {
 const defaultLeaseFs = Object.freeze({ ...defaultLocksFs, renameSync });
 /** Max stale-reclaim → republish rounds inside a single acquire attempt. */
 const MAX_LEASE_RECLAIM_ATTEMPTS = 3;
+/**
+ * Age past which an identity-less lock is treated as an orphan candidate.
+ * Host-meta holds are millisecond-scale critical sections, so no legitimate
+ * holder reaches this (issue #112).
+ */
+const ORPHAN_LEASE_AGE_MS = 5 * 60_000;
 
 /**
  * A token-fenced lease over the view-lock directory. Every operation re-reads
@@ -189,6 +195,23 @@ export function tryAcquireOwnedViewLock(root, viewId, name, opts = {}) {
 	return { acquired: true, lease: attempt };
 }
 
+/**
+ * Whether a publish-rename failure means "the lock path already exists"
+ * (contention) rather than a genuine filesystem error.
+ *
+ * POSIX reports EEXIST/ENOTEMPTY when renaming a directory onto an existing
+ * one; Windows reports EPERM (errno -4048) for the same situation — this op's
+ * platform equivalent of EEXIST (issue #114: a crashed owner's lease could
+ * never be reclaimed because EPERM was rethrown before reclaimOrBlock).
+ * Routing a genuine permission error here stays safe: reclaimability is still
+ * decided solely by `classifyLeaseOwner`, so it resolves `blocked`/`busy`.
+ * @param {string|undefined|null} code
+ * @returns {boolean}
+ */
+export function isPublishConflictCode(code) {
+	return code === "EEXIST" || code === "ENOTEMPTY" || code === "EPERM";
+}
+
 /**
  * Single-shot acquire round: publish a complete candidate lock (owner.json
  * written BEFORE the lock path exists) via atomic rename, and on contention
@@ -219,9 +242,9 @@ function attemptAcquireLease(lockPath, opts) {
 			return makeLease(lockPath, token, fs, now);
 		} catch (err) {
 			try { fs.rmSync(candidate, { recursive: true, force: true }); } catch { /* best effort */ }
-			const code = err && err.code;
-			if (code !== "EEXIST" && code !== "ENOTEMPTY") throw err;
-			const verdict = reclaimOrBlock(lockPath, token, fs, isProcessDead);
+			const code = /** @type {NodeJS.ErrnoException|undefined} */ (err)?.code;
+			if (!isPublishConflictCode(code)) throw err;
+			const verdict = reclaimOrBlock(lockPath, token, fs, isProcessDead, now);
 			if (verdict !== true) return verdict;
 			// Reclaimed a dead owner's lock — retry the publish on the next round.
 		}
@@ -230,29 +253,60 @@ function attemptAcquireLease(lockPath, opts) {
 }
 
 /**
- * Decide whether an existing lock may be reclaimed. Only a lock whose
- * owner.json carries a usable identity (pid + startToken) AND whose pid is
- * provably dead is reclaimable; anything corrupt, unreadable, or live is
- * never deleted. Reclaim quarantines via rename first so a concurrent winner
- * can only ever delete the directory it itself renamed.
+ * Decide what to do with an inspected lease owner. Pure: the caller supplies
+ * `now` and a pid-liveness probe.
+ *
+ * A full identity (pid + startToken) reclaims exactly when its pid is dead.
+ * An identity-less owner — legacy short-hold locks, or platforms where
+ * startToken cannot be captured — is only reclaimable past `orphanAgeMs`
+ * with a provably dead top-level pid: fresh identity-less locks stay blocked,
+ * preserving the short-critical-section contract (issue #112).
+ * @param {any} owner parsed owner.json
+ * @param {number} now
+ * @param {(pid: number) => boolean} isProcessDead
+ * @param {{ orphanAgeMs?: number }} [opts]
+ * @returns {"reclaim" | "busy" | "blocked"}
+ */
+export function classifyLeaseOwner(owner, now, isProcessDead, opts = {}) {
+	if (!owner || typeof owner !== "object") return "blocked";
+	const ownPid = Number(owner?.identity?.pid ?? 0);
+	const hasIdentity = Number.isFinite(ownPid) && ownPid > 0 && typeof owner?.identity?.startToken === "string";
+	if (hasIdentity) {
+		if (!isProcessDead(ownPid)) return "busy";
+		// Quarantine-mode reclaim verifies by token that it renamed the lock it
+		// inspected — without one nothing may be deleted.
+		return typeof owner.token === "string" ? "reclaim" : "blocked";
+	}
+	const pid = Number(owner?.pid ?? 0);
+	if (!Number.isFinite(pid) || pid <= 0) return "blocked";
+	const orphanAgeMs = Number(opts.orphanAgeMs ?? ORPHAN_LEASE_AGE_MS);
+	if (!(Number(now) - Number(owner?.startedAt ?? 0) >= orphanAgeMs)) return "blocked";
+	if (!isProcessDead(pid)) return "busy";
+	return typeof owner.token === "string" ? "reclaim" : "blocked";
+}
+
+/**
+ * Decide whether an existing lock may be reclaimed. Verdicts come from the
+ * pure `classifyLeaseOwner`; reclaim itself quarantines via rename first so a
+ * concurrent winner can only ever delete the directory it itself renamed.
  * @param {string} lockPath
  * @param {string} token the caller's own token (names the quarantine dir)
  * @param {typeof defaultLeaseFs} fs
  * @param {(pid: number) => boolean} isProcessDead
+ * @param {() => number} now clock (matching the caller's candidate timestamps)
  * @returns {true | "busy" | "blocked"}
  */
-function reclaimOrBlock(lockPath, token, fs, isProcessDead) {
+function reclaimOrBlock(lockPath, token, fs, isProcessDead, now) {
 	let owner;
 	try {
 		owner = JSON.parse(fs.readFileSync(path.join(lockPath, "owner.json"), "utf8"));
 	} catch {
 		return "blocked";
 	}
-	const pid = Number(owner?.identity?.pid ?? 0);
-	if (!Number.isFinite(pid) || pid <= 0 || typeof owner?.identity?.startToken !== "string") return "blocked";
-	if (!isProcessDead(pid)) return "busy";
-	const inspectedToken = typeof owner?.token === "string" ? owner.token : null;
-	if (inspectedToken === null) return "blocked";
+	const verdict = classifyLeaseOwner(owner, now(), isProcessDead);
+	if (verdict !== "reclaim") return verdict;
+	// classifyLeaseOwner only returns "reclaim" when owner.token is a string.
+	const inspectedToken = owner.token;
 	const quarantine = `${lockPath}.reclaim.${token}`;
 	try {
 		fs.renameSync(lockPath, quarantine);

package/src/core/paths.mjs

@@ -37,6 +37,10 @@ export const metaPath = (root, viewId) => path.join(viewDir(root, viewId), "meta
 export const statePath = (root, viewId) => path.join(viewDir(root, viewId), "state.json");
 /** @param {string} root @param {string} viewId */
 export const hostPath = (root, viewId) => path.join(viewDir(root, viewId), "host.json");
+/** Durable control-command journal for a view's host (issue #91 phase 5, spec
+ *  D4): one JSONL line per durable-command lifecycle transition
+ *  (accepted/applied). Sibling of host.json in the view dir. */
+export const controlJournalPath = (root, viewId) => path.join(viewDir(root, viewId), "control-journal.jsonl");
 /** @param {string} root @param {string} viewId */
 export const hostConfigPath = (root, viewId) => path.join(viewDir(root, viewId), "host-config.json");
 /**
@@ -71,6 +75,21 @@ export function controlSocketPathFor(platform, root, viewId) {
 }
 /** @param {string} root @param {string} viewId */
 export const controlSocketPath = (root, viewId) => controlSocketPathFor(process.platform, root, viewId);
+/**
+ * Endpoint a hosted child's editor-state reporter should connect to.
+ *
+ * The runner knows which endpoint it actually bound and injects it into the
+ * child env as AGENT_BOARD_CONTROL_SOCKET (issue #103): since #70 the owned
+ * runner binds a per-instance address, while the reporter kept dialing the
+ * stable per-view one, so it never connected and the attach gate lost its
+ * authoritative editor state. The injected value wins; the stable address
+ * remains the fallback for legacy hosts and older runners that predate the key.
+ * @param {{ envSocketPath?: string | null, platform: "win32"|"linux"|"darwin", root: string, viewId: string }} args
+ */
+export function resolveControlEndpoint({ envSocketPath, platform, root, viewId }) {
+	const injected = typeof envSocketPath === "string" ? envSocketPath.trim() : "";
+	return injected.length > 0 ? injected : controlSocketPathFor(platform, root, viewId);
+}
 /**
  * Per-instance control endpoint. Each new host instance binds its own socket/pipe,
  * so a superseded runner can never unlink the current owner's endpoint (issue #70).
@@ -93,14 +112,27 @@ export const screenLogPath = (root, viewId) => path.join(viewDir(root, viewId),
  * Well-known endpoint for the board-root View State Coordinator (issue #91, spec D3).
  * Exactly one coordinator may own a root (token-fenced lease), so one stable path
  * suffices; a stale POSIX socket left by a crashed coordinator is unlinked by the
- * new lease owner before bind. win32 pipe names embed a 16-hex hash of the root to
- * stay under the 256-char limit and keep per-root isolation.
+ * new lease owner before bind. win32 pipe names embed a 16-hex hash of the
+ * *normalized* root to stay under the 256-char limit and keep per-root isolation.
  * @param {"win32"|"linux"|"darwin"} platform
  * @param {string} root
  */
 export function coordinatorEndpointPathFor(platform, root) {
 	if (platform === "win32") {
-		const hash = createHash("sha256").update(String(root)).digest("hex").slice(0, 16);
+		// Normalize before hashing: the pipe name must be invariant to the root's
+		// spelling (C:/x vs C:\x, trailing separators, dot segments). The lock path
+		// derived from the same root already is (via path.join); a mismatch yields
+		// "same lock, two pipes" — the panel probes a pipe nobody bound, spawns
+		// replacements that cannot take the held lease, and locks itself out
+		// (issue #124). resolve() is idempotent on canonical roots, so coordinators
+		// already deployed keep their pipe name and need no restart.
+		// win32 semantics are named explicitly rather than using the ambient
+		// path.resolve: this branch must emit the same pipe name on every host OS
+		// (on POSIX, ambient resolve treats `C:\x` as a relative path: no
+		// drive-letter or backslash-separator semantics), so platform-injected
+		// tests and CI behave identically everywhere.
+		const normalized = path.win32.resolve(root);
+		const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
 		return `\\\\.\\pipe\\agent-board-coordinator-${hash}`;
 	}
 	return path.join(root, "coordinator.sock");

package/src/core/pid.mjs

@@ -1,4 +1,5 @@
-/** Process liveness checks. */
+/** Process liveness checks and process identity capture. */
+import { readFileSync } from "node:fs";
 
 /**
  * Whether `pid` refers to a live process.
@@ -40,3 +41,33 @@ export function killProcess(pid, graceMs = 4000) {
 		}
 	}, graceMs).unref?.();
 }
+
+/**
+ * POSIX process start token — /proc/<pid>/stat field 22 (starttime), stable
+ * across exec(2). Distinguishes an owned-live pid from a reused one; null on
+ * failure or non-Linux platforms. Mirrors the runner's captureStartToken
+ * (issue #70); shared here for host-meta lease identity (issue #112).
+ * @param {number|null|undefined} pid
+ * @returns {string|null}
+ */
+export function captureStartToken(pid) {
+	if (process.platform !== "linux" || !pid) return null;
+	try {
+		const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+		// comm (field 2) may contain spaces and parens — fields resume AFTER the
+		// last ')'. fields[0] is state (field 3) → starttime (field 22) is [19].
+		const afterComm = stat.slice(stat.lastIndexOf(")") + 1).trimStart();
+		return afterComm.split(/\s+/)[19] ?? null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Launch-time identity for the current process, as stamped on host-meta
+ * acquisitions (issue #112).
+ * @returns {{pid: number, startToken: string|null}}
+ */
+export function currentProcessIdentity() {
+	return { pid: process.pid, startToken: captureStartToken(process.pid) };
+}

package/src/core/pty-attach-jiggle-controller.mjs

@@ -1,4 +1,13 @@
 /**
+ * LEGACY FALLBACK (issue #91 phase 6 marking): the shrink-and-hold jiggle is
+ * kept only for pre-protocol runners and the AGENT_BOARD_TERMINAL_SNAPSHOT=0
+ * kill switch. It is NOT a success condition of the snapshot+subscribe
+ * protocol path — the protocol re-baselines the view from runner-owned
+ * snapshots (phase 4), and jiggle arming is skipped once the probe resolves
+ * to the protocol attach mode. Removal condition: the installed runner fleet
+ * is on the snapshot protocol baseline (wire-detectable via hello protocol
+ * fields).
+ *
  * Injectable orchestration for the attach shrink-and-hold jiggle protocol.
  *
  * Replaces the pulse-pair jiggle (shrink → 200ms → restore) with a
@@ -208,17 +217,32 @@ export function createJiggleRetryController(deps) {
 	 * Feed one socket output chunk. A clear wins over the re-arm when both
 	 * appear in one chunk — but frame cognition is still learned from that
 	 * chunk: a clear only proves the child redraws, not that it isn't a TUI
-	 * (screen-log replay bundles historical frames with clears, issue #11).
+	 * (a live fullRender chunk bundles a frame start with its clear, issue #11).
 	 * The first TUI frame restores the held size (the
 	 * child is now rendering and will fullRender on the width delta) and
 	 * does NOT reschedule the chain; if G1 already released the hold before
 	 * the TUI booted, the frame instead re-arms a fresh hold so the running
 	 * child still sees a width delta (F1 slow-boot probe).
+	 * Terminal chain states still learn frame cognition from later output
+	 * (issue #106) — cognition only; re-opening the protocol stays heal()'s job.
 	 * @param {string} data
 	 */
 	function feed(data) {
-		if (state.clearDetected) return; // chain done; nothing left to detect
-		if (state.stopped) return; // chain ended (G2/G3/G4); output is inert
+		// Terminal chain states: a clear was seen (chain done) or the chain ended
+		// (G2/G3/G4). Output no longer drives the retry protocol — but frame
+		// cognition must still be learned from it (issue #106): a TUI whose first
+		// frame lands after the chain settled must still open the runtime desync
+		// backstop's gate 2 (issue #11), otherwise heal() stays unreachable for the
+		// rest of this connection. Cognition only — no timers, no resizes, and no
+		// retry-state change: re-opening the protocol is heal()'s job (rate-limited
+		// and lifetime-capped), not an output chunk's.
+		if (state.clearDetected || state.stopped) {
+			if (tuiFrameSeen) return; // latched already — nothing left to learn
+			const terminal = feedOutput(state, data, carry);
+			carry = terminal.carry; // keep cross-chunk marker detection intact
+			if (terminal.frameStartFound) tuiFrameSeen = true;
+			return;
+		}
 		const result = feedOutput(state, data, carry);
 		state = result.state;
 		carry = result.carry;

package/src/core/pty-attach-reconnect.mjs

@@ -31,13 +31,20 @@ export function evaluateAttachReconnect({ everConnected, disconnectedAt, connect
 }
 
 /**
- * Detach-key policy: while the socket is down a key can never reach the child,
- * so treat ← / ctrl+] as "leave the view" unconditionally; otherwise keep the
- * existing empty-input-line gate (issue #48 comment 1).
+ * Detach-key policy (issue #91 Phase 6, spec §D1): while the socket is down a
+ * key can never reach the child, so treat ← as "leave the view"
+ * unconditionally; otherwise detach only when the pushed editorEmpty side
+ * channel is exactly true. false and null/undefined mean "forward" — the
+ * explicit conservative policy; callers pass `editorEmpty === true` so an
+ * unknown state can never arm the detach, and no terminal-buffer heuristic is
+ * consulted (the deleted terminal-buffer heuristic family — issues
+ * #42/#66/#69/#103 — stays deleted).
  * @param {boolean} connected
- * @param {boolean} childInputLooksEmpty
+ * @param {boolean | null | undefined} editorEmpty
  * @returns {boolean}
  */
-export function shouldEscapeAttach(connected, childInputLooksEmpty) {
-	return !connected || childInputLooksEmpty;
+export function shouldEscapeAttach(connected, editorEmpty) {
+	// Normalize to a strict boolean: a null/undefined editorEmpty (unknown)
+	// forwards — never escapes — and must not leak through the return value.
+	return !connected || editorEmpty === true;
 }

package/src/core/pty-attach-render.mjs

@@ -43,6 +43,26 @@ export function projectPtyCursor(buf, start, height) {
 	return { row, col: buf.cursorX };
 }
 
+/**
+ * Duck-typed read of the child terminal's DECTCEM visibility state.
+ *
+ * pi-tui hides the hardware cursor (ESC[?25l) on essentially every frame and
+ * still parks it for IME positioning, so the xterm cursor position outlives its
+ * visibility: it is a rendering byproduct, not a request to show a cursor. The
+ * attach projection must not resurrect that parked cell as a visible block, and
+ * must equally not hide a cursor the child wants shown (shells, vim,
+ * PI_HARDWARE_CURSOR=1). Only an explicit `true` from xterm's cursor service
+ * counts as hidden; anything unknown (renamed internals, another @xterm build)
+ * falls back to visible, which is the pre-#102 behavior.
+ */
+export function isPtyCursorHidden(term) {
+	try {
+		return term?._core?.coreService?.isCursorHidden === true;
+	} catch {
+		return false;
+	}
+}
+
 /**
  * Coalesce PTY parser callbacks into a bounded stream of repaint requests.
  *

package/src/core/state-commands.mjs

@@ -59,6 +59,45 @@ export const STATE_COMMAND_KINDS = Object.freeze([
  */
 export const TRANSIENT_KINDS = Object.freeze(["run_progress"]);
 
+/**
+ * Decision-layer reject reasons: journaled, authoritative coordinator verdicts
+ * with NO recovery semantics (a retry would be decided the same way). The
+ * complement — transport ambiguity ("timeout"/"connection_reset"/
+ * "connection_failed"/"coordinator_unavailable") — is the only class where
+ * "outcome unknown, replay will recover" diagnostics are honest (issue #91
+ * hygiene). validateCommand envelope errors are first-party programmer errors
+ * and are not in this set.
+ */
+export const DECIDED_REJECT_REASONS = Object.freeze(new Set([
+	"manual_fence",
+	"stale_run",
+	"no_change",
+	"busy",
+	"revision_conflict",
+	"unknown_view",
+	"unknown_kind",
+	"field_not_allowed",
+]));
+
+/**
+ * Diagnostic fields for a non-applied command result (issue #91 hygiene):
+ * decided rejects are info-level skips — the coordinator's verdict is
+ * authoritative, so "outcome unknown, replay will recover" would be a lie.
+ * Transport ambiguity keeps the warn with the caller's recovery hint.
+ * Pure: shapes only, no I/O.
+ * @param {string} code diagnostic code stem (e.g. "run_started")
+ * @param {string} label human phrase for the message (e.g. "Run bootstrap")
+ * @param {string|null} reason rejected reason from the command result
+ * @param {string} ambiguousTail recovery hint appended ONLY for ambiguous reasons
+ * @returns {{ level: "info"|"warn", code: string, message: string }}
+ */
+export function commandRejectDiagnostic(code, label, reason, ambiguousTail) {
+	const decided = reason != null && DECIDED_REJECT_REASONS.has(reason);
+	return decided
+		? { level: "info", code: `${code}_skipped`, message: `${label} skipped by the coordinator (${reason}); its decision is authoritative` }
+		: { level: "warn", code: `${code}_ambiguous`, message: `${label} outcome unknown (${reason}); if the command was journaled, coordinator replay will recover it; ${ambiguousTail}` };
+}
+
 /**
  * Per-source whitelist for `patch_fields` (metadata/evidence-mirror merges).
  * Anything not listed here is rejected with "field_not_allowed" — semantic
@@ -141,7 +180,10 @@ export function validateCommand(raw) {
 			if (raw.payload.runId != null && (typeof raw.payload.runId !== "string" || !raw.payload.runId)) return { ok: false, error: "missing_runId" };
 			break;
 		case "run_started": {
-			if (raw.runId == null) return { ok: false, error: "missing_runId" };
+			// Non-empty string (not just != null): a degenerate runId passes the
+			// null guard, then the statusRunId binding silently drops the status
+			// half while the ack still says "applied" (Task 2 review P2-A).
+			if (typeof raw.runId !== "string" || !raw.runId) return { ok: false, error: "missing_runId" };
 			const status = raw.payload?.status;
 			if (!status || typeof status !== "object") return { ok: false, error: "missing_status" };
 			if (typeof status.runId !== "string" || status.runId !== raw.runId) return { ok: false, error: "bad_status" };
@@ -359,11 +401,32 @@ export function decideStateTransition(command, currentState, currentStatus, now
 			// Liveness semantics: only the row's current live run may move forward.
 			// Late/duplicate progress from a finished run is dropped (next run's
 			// progress supersedes it anyway — this kind is transient by design).
-			// A live run with no materialized status cannot legitimately progress
-			// (F2): the first beat always follows run_started's bootstrap write, so
-			// a missing status here means the beat is stale or out of order — and
-			// projecting onto `null` would materialize undefined processState.
-			if (!currentStatus) return reject("stale_run");
+			//
+			// A missing status file splits two ways (F2, split by the hard-down
+			// residual closure): a QUALIFIED beat from the row's current live run —
+			// full-shaped patch carrying processState/semanticState and the same
+			// runId — bootstraps the file, because the coordinator may have been
+			// down through the runner's boot window (mark_queued applied,
+			// run_started lost): without the bootstrap the row can never converge
+			// (beats and finalize both reject forever). Anything else — exited or
+			// re-pointed rows, sparse patches that would materialize an
+			// undefined-shaped status — stays stale_run (F2's original exposure).
+			if (!currentStatus) {
+				// P2 hardening: the bootstrap is keyed on command.runId (it becomes the
+				// status-file identity), so a degenerate null==null row match must never
+				// bootstrap — the shell would silently drop the status half. The check
+				// lives here beside its sibling liveness guards (runId semantics for
+				// run_progress are decision-layer; envelope validation stays minimal,
+				// matching the generic stale-run guard's decision-side read).
+				const rowMatches = typeof command.runId === "string" && command.runId.length > 0
+					&& currentState.currentRunId === command.runId
+					&& currentState.processState === "alive";
+				if (!rowMatches || !beatPatchQualifiesForBootstrap(command)) return reject("stale_run");
+				// The patch itself is the base: it is the runner's authoritative
+				// full in-memory status, so applyStatusProjection's merge-onto-empty
+				// materializes exactly the patch (validated full-shaped above).
+				return applyStatusProjection(command, currentState, null, now);
+			}
 			if (currentState.currentRunId !== command.runId || currentState.processState !== "alive") return reject("stale_run");
 			return applyStatusProjection(command, currentState, currentStatus, now);
 		}
@@ -580,6 +643,25 @@ function buildPatches(currentState, stateClone, stateChanged, currentStatus, sta
 	return mutate;
 }
 
+/**
+ * Whether a run_progress beat may bootstrap a missing status file: the patch
+ * must be full-shaped — carrying processState and semanticState (so the
+ * materialized status never has an undefined shape) and pinned to the same
+ * runId as the command (so a foreign run's snapshot can never masquerade as
+ * this run's bootstrap). Sparse or mismatched patches stay stale_run.
+ * @param {object} command
+ */
+function beatPatchQualifiesForBootstrap(command) {
+	const patch = command.payload?.statusPatch;
+	return Boolean(
+		patch &&
+		typeof patch === "object" &&
+		typeof patch.processState === "string" &&
+		typeof patch.semanticState === "string" &&
+		patch.runId === command.runId,
+	);
+}
+
 /**
  * Shared body for the status-patch kinds (`run_progress`, `followup_started`):
  * merge payload.statusPatch onto the materialized status, then let