@zhuxixi/pi-agent-board 0.3.0

package/src/core/screen-log-gc.mjs

@@ -0,0 +1,198 @@
+/**
+ * Startup GC for per-view PTY replay logs.
+ *
+ * screen.log write-path growth is already bounded by screen-log.mjs (cap + tail
+ * compaction inside pty-runner). This module reclaims the other half: logs of
+ * views whose session ENDED long ago — no runner will ever touch them again,
+ * so without a sweep they sit on disk forever.
+ *
+ * Safety rules:
+ * - Only screen.log is removed; meta/state/evidence stay so the dashboard row survives.
+ * - Views with a live host (state alive/starting, endedAt null) are never touched:
+ *   pty-runner holds an in-memory byte counter for its log and external mutation
+ *   would race with it. Live logs are bounded by the runner's own cap.
+ */
+import { existsSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import { readJson } from "./atomic.mjs";
+import * as P from "./paths.mjs";
+import { isAlive } from "./pid.mjs";
+
+export const DEFAULT_SCREEN_LOG_RETENTION_DAYS = 7;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * A live pty-runner heartbeat-persists host.json every second, and a booting runner
+ * persists state "starting" before the service's own writeHost lands. A host.json
+ * modified within this window therefore means a runner is live or mid-launch.
+ */
+const HOST_FRESH_GRACE_MS = 10_000;
+
+/**
+ * An "alive"/"starting" claim older than this is not trusted: heartbeat-persisted
+ * lastSeenAt goes stale when a runner dies, and a dead pid can later be recycled by
+ * an unrelated process — pid liveness alone must not exempt a view forever.
+ */
+const ALIVE_CLAIM_MAX_AGE_MS = 3 * DAY_MS;
+
+/**
+ * Shared input gate for the prefs normalizers: only finite numbers and non-blank
+ * numeric strings are meaningful. Anything else (booleans, arrays, "", "  ",
+ * objects) is a hand-edit accident, not a value.
+ * @param {unknown} value
+ * @returns {number|null} the coerced finite number, or null when not usable
+ */
+function coerceUsableNumber(value) {
+	if (typeof value === "number") return Number.isFinite(value) ? value : null;
+	if (typeof value === "string" && value.trim() !== "") {
+		const n = Number(value);
+		return Number.isFinite(n) ? n : null;
+	}
+	return null;
+}
+
+/**
+ * Normalize the `screenLogRetentionDays` pref.
+ * @param {unknown} value
+ * @returns {number|null} days, or null when GC is disabled (pref = 0)
+ */
+export function normalizeRetentionDays(value) {
+	const n = coerceUsableNumber(value);
+	if (n === null || n < 0) return DEFAULT_SCREEN_LOG_RETENTION_DAYS;
+	const days = Math.floor(n);
+	// Anything flooring to 0 (0, "0", "0.0", fractions in (0,1)) means "disabled".
+	// A 0-day retention would otherwise compute cutoff=now and delete EVERY ended log.
+	return days === 0 ? null : days;
+}
+
+/**
+ * Normalize the `screenLogMaxSize` pref.
+ * @param {unknown} value
+ * @returns {number|null} bytes, or null to keep the runner's built-in default
+ */
+export function normalizeScreenLogMaxBytes(value) {
+	const n = coerceUsableNumber(value);
+	if (n === null) return null;
+	const bytes = Math.floor(n);
+	return bytes > 0 ? bytes : null;
+}
+
+/**
+ * Delete screen.log of ended views older than the retention window.
+ * Best-effort: a per-file failure is counted and skipped, never thrown.
+ * @param {string} root
+ * @param {{ retentionDays?: number|null, now?: number }} [opts]
+ * @returns {{ scanned: number, removed: number, skippedActive: number, skippedFresh: number, skippedForeign: number, bytesReclaimed: number, errors: number }}
+ */
+export function pruneScreenLogs(root, opts = {}) {
+	const stats = { scanned: 0, removed: 0, skippedActive: 0, skippedFresh: 0, skippedForeign: 0, bytesReclaimed: 0, errors: 0 };
+	const retentionDays = normalizeRetentionDays(opts.retentionDays);
+	if (retentionDays === null) return stats;
+	const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+	const cutoff = now - retentionDays * DAY_MS;
+	/** @type {import("node:fs").Dirent[]} */
+	let entries;
+	try {
+		entries = readdirSync(P.viewsDir(root), { withFileTypes: true });
+	} catch {
+		return stats; // no views dir yet — nothing to do
+	}
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		if (!isViewDir(root, entry.name)) {
+			// Foreign dirs must never lose a file; count the ones holding a screen.log
+			// so the skip is visible in stats.
+			try {
+				if (statSync(P.screenLogPath(root, entry.name)).size > 0) stats.skippedForeign++;
+			} catch {}
+			continue;
+		}
+		const logFile = P.screenLogPath(root, entry.name);
+		/** @type {number} */
+		let size;
+		try {
+			size = statSync(logFile).size;
+		} catch {
+			continue; // no screen.log (job-runner views never have one)
+		}
+		if (size <= 0) continue;
+		stats.scanned++;
+		const basis = ageBasisMs(root, entry.name, logFile, now);
+		if (basis === "active") {
+			stats.skippedActive++;
+			continue;
+		}
+		if (basis === null || basis > cutoff) {
+			stats.skippedFresh++;
+			continue;
+		}
+		try {
+			unlinkSync(logFile);
+			stats.removed++;
+			stats.bytesReclaimed += size;
+		} catch (err) {
+			if (classifyUnlinkFailure(err) === "removed") stats.removed++;
+			else stats.errors++;
+		}
+	}
+	return stats;
+}
+
+/**
+ * Age basis for one view's log: host endedAt when known, else the log's mtime.
+ * @param {string} root @param {string} viewId @param {string} logFile @param {number} now
+ * @returns {number|null|"active"} epoch ms, "active" for live views, null when unknown
+ */
+function ageBasisMs(root, viewId, logFile, now) {
+	const hostFile = P.hostPath(root, viewId);
+	const host = readJson(hostFile, null);
+	if (host) {
+		// Fresh host.json = a runner is heartbeating or mid-launch. Checking mtime first
+		// closes the launch TOCTOU window (runner boots and opens the log before the
+		// service's writeHost records "starting"): a stale read can never delete the
+		// log of a runner that just started.
+		try {
+			if (now - statSync(hostFile).mtimeMs < HOST_FRESH_GRACE_MS) return "active";
+		} catch {}
+		if (host.endedAt == null && (host.state === "alive" || host.state === "starting")) {
+			// A runner killed by SIGKILL/OOM leaves state "alive" on disk forever, and its
+			// pid may later be recycled by an unrelated long-lived process (isAlive also
+			// treats EPERM as alive). Trust the claim only when the heartbeat refreshed
+			// lastSeenAt recently AND the pid is actually alive.
+			const claimFresh = Number.isFinite(host.lastSeenAt) && now - host.lastSeenAt < ALIVE_CLAIM_MAX_AGE_MS;
+			if (claimFresh && Number.isInteger(host.runnerPid) && isAlive(host.runnerPid)) return "active";
+		}
+		if (Number.isFinite(host.endedAt)) return host.endedAt;
+	}
+	try {
+		return statSync(logFile).mtimeMs;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Classify an unlinkSync failure. ENOENT after a successful stat means a concurrent
+ * sweep (a second dashboard sharing the root) won the unlink: the reclaim goal is
+ * achieved, so it counts as removed (without the bytes, which the winner accounted
+ * for), never as an error. Everything else is a real failure.
+ * Extracted as a pure predicate because the stat→unlink race cannot be reproduced
+ * deterministically in tests — the predicate is the part that can silently regress.
+ * @param {unknown} err
+ * @returns {"removed"|"error"}
+ */
+export function classifyUnlinkFailure(err) {
+	return err && err.code === "ENOENT" ? "removed" : "error";
+}
+
+/**
+ * A sweep-eligible directory is a real view: it carries meta.json, or — when
+ * meta.json was externally deleted — a host.json that is parseable AND names this
+ * directory as its view. A stray/garbage host.json in a foreign directory must not
+ * make that directory's screen.log a deletion candidate.
+ * @param {string} root @param {string} viewId
+ */
+function isViewDir(root, viewId) {
+	if (existsSync(P.metaPath(root, viewId))) return true;
+	const host = readJson(P.hostPath(root, viewId), null);
+	return Boolean(host && host.viewId === viewId);
+}

package/src/core/screen-log.mjs

@@ -0,0 +1,160 @@
+import {
+	appendFileSync,
+	closeSync,
+	existsSync,
+	fstatSync,
+	fsyncSync,
+	openSync,
+	readSync,
+	renameSync,
+	statSync,
+	unlinkSync,
+	writeSync,
+} from "node:fs";
+
+export const SCREEN_LOG_REPLAY_BYTES = 100_000;
+export const SCREEN_LOG_MAX_BYTES = 5_000_000;
+
+export const defaultScreenLogFs = Object.freeze({
+	appendFileSync,
+	closeSync,
+	existsSync,
+	fstatSync,
+	fsyncSync,
+	openSync,
+	readSync,
+	renameSync,
+	statSync,
+	unlinkSync,
+	writeSync,
+});
+
+let tempSequence = 0;
+
+/** @param {string} file @param {number} maxBytes @param {typeof defaultScreenLogFs} fs */
+export function readScreenLogTailBytes(file, maxBytes = SCREEN_LOG_REPLAY_BYTES, fs = defaultScreenLogFs) {
+	return readTailResult(file, maxBytes, fs).data;
+}
+
+/** @param {string} file @param {number} maxBytes */
+export function readScreenLogTail(file, maxBytes = SCREEN_LOG_REPLAY_BYTES) {
+	return readScreenLogTailBytes(file, maxBytes).toString("utf8");
+}
+
+/**
+ * Compact an existing screen log when it exceeds maxBytes.
+ * @param {string} file
+ * @param {{ maxBytes?: number, retainBytes?: number, fs?: typeof defaultScreenLogFs }} [opts]
+ */
+export function reconcileScreenLog(file, opts = {}) {
+	const fs = opts.fs ?? defaultScreenLogFs;
+	const { maxBytes, retainBytes } = limits(opts);
+	const size = fileSize(file, 0, fs);
+	if (size <= maxBytes) return size;
+	const tail = readTailResult(file, retainBytes, fs);
+	if (!tail.ok || !replaceScreenLog(file, tail.data, fs)) return fileSize(file, size, fs);
+	return fileSize(file, tail.data.length, fs);
+}
+
+/**
+ * Append PTY output while bounding the persisted replay log.
+ * @param {string} file
+ * @param {string|Buffer} data
+ * @param {number} currentBytes
+ * @param {{ maxBytes?: number, retainBytes?: number, fs?: typeof defaultScreenLogFs }} [opts]
+ */
+export function appendBoundedScreenLog(file, data, currentBytes, opts = {}) {
+	const fs = opts.fs ?? defaultScreenLogFs;
+	const { maxBytes, retainBytes } = limits(opts);
+	const payload = Buffer.isBuffer(data) ? data : Buffer.from(data);
+	let size = Number.isFinite(currentBytes) && currentBytes >= 0 ? currentBytes : fileSize(file, 0, fs);
+
+	if (size > maxBytes) {
+		size = reconcileScreenLog(file, { maxBytes, retainBytes, fs });
+		if (size > maxBytes) return size;
+	}
+	if (payload.length === 0) return size;
+	if (payload.length >= maxBytes) {
+		const tail = payload.subarray(Math.max(0, payload.length - retainBytes));
+		if (!replaceScreenLog(file, tail, fs)) return fileSize(file, size, fs);
+		return fileSize(file, tail.length, fs);
+	}
+
+	try {
+		fs.appendFileSync(file, payload);
+	} catch {
+		return fileSize(file, size, fs);
+	}
+	size += payload.length;
+	if (size <= maxBytes) return size;
+	return reconcileScreenLog(file, { maxBytes, retainBytes, fs });
+}
+
+/** @param {string} file @param {number} maxBytes @param {typeof defaultScreenLogFs} fs */
+function readTailResult(file, maxBytes, fs) {
+	if (!file || maxBytes <= 0 || !fs.existsSync(file)) return { ok: true, data: Buffer.alloc(0) };
+	let fd;
+	try {
+		fd = fs.openSync(file, "r");
+		const size = fs.fstatSync(fd).size;
+		const length = Math.min(size, Math.floor(maxBytes));
+		if (length <= 0) return { ok: true, data: Buffer.alloc(0) };
+		const output = Buffer.allocUnsafe(length);
+		const start = size - length;
+		let offset = 0;
+		while (offset < length) {
+			const read = fs.readSync(fd, output, offset, length - offset, start + offset);
+			if (read === 0) break;
+			offset += read;
+		}
+		return { ok: true, data: offset === length ? output : output.subarray(0, offset) };
+	} catch {
+		return { ok: false, data: Buffer.alloc(0) };
+	} finally {
+		if (fd !== undefined) {
+			try { fs.closeSync(fd); } catch {}
+		}
+	}
+}
+
+/** @param {{ maxBytes?: number, retainBytes?: number }} opts */
+function limits(opts) {
+	const maxBytes = positiveInt(opts.maxBytes, SCREEN_LOG_MAX_BYTES);
+	return { maxBytes, retainBytes: Math.min(positiveInt(opts.retainBytes, SCREEN_LOG_REPLAY_BYTES), maxBytes) };
+}
+
+/** @param {string} file @param {Buffer} data @param {typeof defaultScreenLogFs} fs */
+function replaceScreenLog(file, data, fs) {
+	const temp = `${file}.${process.pid}.${tempSequence++}.tmp`;
+	let fd;
+	try {
+		fd = fs.openSync(temp, "w");
+		let offset = 0;
+		while (offset < data.length) offset += fs.writeSync(fd, data, offset, data.length - offset, offset);
+		fs.fsyncSync(fd);
+		fs.closeSync(fd);
+		fd = undefined;
+		fs.renameSync(temp, file);
+		return true;
+	} catch {
+		if (fd !== undefined) {
+			try { fs.closeSync(fd); } catch {}
+		}
+		try { fs.unlinkSync(temp); } catch {}
+		return false;
+	}
+}
+
+/** @param {string} file @param {number} fallback @param {typeof defaultScreenLogFs} fs */
+function fileSize(file, fallback, fs) {
+	try {
+		return fs.statSync(file).size;
+	} catch {
+		return fallback;
+	}
+}
+
+function positiveInt(value, fallback) {
+	const number = Number(value);
+	return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback;
+}

package/src/core/session-view.mjs

@@ -0,0 +1,174 @@
+/**
+ * Read and project a managed Pi session file into a simple display model for the
+ * dashboard's non-interrupting session view.
+ *
+ * We show the current active branch only: starting from the last appended entry
+ * (the active leaf in normal Pi append semantics), walk parentId links to root,
+ * then render messages / visible custom messages / summaries on that branch.
+ */
+import { existsSync, readFileSync } from "node:fs";
+
+/**
+ * @typedef {Object} SessionViewItem
+ * @property {string} id
+ * @property {"user"|"assistant"|"custom"|"note"} role
+ * @property {string} label
+ * @property {string} text
+ * @property {string} timestamp
+ * @property {string} entryType
+ */
+
+/**
+ * @typedef {Object} SessionViewData
+ * @property {{ id:string, cwd:string }|null} header
+ * @property {SessionViewItem[]} items
+ * @property {string|null} error
+ */
+
+/**
+ * Load and parse one session file.
+ * @param {string} sessionFile
+ * @returns {SessionViewData}
+ */
+export function loadSessionView(sessionFile) {
+	if (!sessionFile || !existsSync(sessionFile)) {
+		return { header: null, items: [], error: "Session file not created yet." };
+	}
+	try {
+		return parseSessionText(readFileSync(sessionFile, "utf8"));
+	} catch (err) {
+		return {
+			header: null,
+			items: [],
+			error: `Couldn't read session: ${err instanceof Error ? err.message : String(err)}`,
+		};
+	}
+}
+
+/**
+ * Parse session JSONL into a displayable active branch.
+ * @param {string} text
+ * @returns {SessionViewData}
+ */
+export function parseSessionText(text) {
+	/** @type {{ id:string, cwd:string }|null} */
+	let header = null;
+	/** @type {any[]} */
+	const entries = [];
+	/** @type {Map<string, any>} */
+	const byId = new Map();
+
+	for (const rawLine of String(text || "").split(/\r?\n/)) {
+		const line = rawLine.trim();
+		if (!line) continue;
+		let entry;
+		try {
+			entry = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		if (entry?.type === "session") {
+			header = { id: String(entry.id || ""), cwd: String(entry.cwd || "") };
+			continue;
+		}
+		if (!entry || typeof entry !== "object" || typeof entry.id !== "string") continue;
+		entries.push(entry);
+		byId.set(entry.id, entry);
+	}
+
+	if (entries.length === 0) return { header, items: [], error: null };
+
+	const leaf = entries[entries.length - 1];
+	const branch = activeBranch(leaf, byId);
+	const items = branch.flatMap(displayItemsForEntry);
+	return { header, items, error: null };
+}
+
+/**
+ * Walk from `leaf` to root following parentId pointers.
+ * @param {any} leaf
+ * @param {Map<string, any>} byId
+ * @returns {any[]}
+ */
+function activeBranch(leaf, byId) {
+	/** @type {any[]} */
+	const out = [];
+	const seen = new Set();
+	let cur = leaf;
+	while (cur && typeof cur.id === "string" && !seen.has(cur.id)) {
+		out.push(cur);
+		seen.add(cur.id);
+		cur = cur.parentId ? byId.get(cur.parentId) ?? null : null;
+	}
+	out.reverse();
+	return out;
+}
+
+/**
+ * @param {any} entry
+ * @returns {SessionViewItem[]}
+ */
+function displayItemsForEntry(entry) {
+	switch (entry?.type) {
+		case "message": {
+			const role = entry.message?.role;
+			const text = contentText(entry.message?.content);
+			if (!text) return [];
+			if (role === "user") {
+				return [{ id: entry.id, role: "user", label: "you", text, timestamp: String(entry.timestamp || ""), entryType: entry.type }];
+			}
+			if (role === "assistant") {
+				return [{ id: entry.id, role: "assistant", label: "agent", text, timestamp: String(entry.timestamp || ""), entryType: entry.type }];
+			}
+			return [{ id: entry.id, role: "note", label: String(role || "message"), text, timestamp: String(entry.timestamp || ""), entryType: entry.type }];
+		}
+		case "custom_message": {
+			if (entry.display === false) return [];
+			const text = contentText(entry.content);
+			if (!text) return [];
+			return [{
+				id: entry.id,
+				role: "custom",
+				label: String(entry.customType || "context"),
+				text,
+				timestamp: String(entry.timestamp || ""),
+				entryType: entry.type,
+			}];
+		}
+		case "branch_summary":
+			return [{
+				id: entry.id,
+				role: "note",
+				label: "branch summary",
+				text: String(entry.summary || "").trim(),
+				timestamp: String(entry.timestamp || ""),
+				entryType: entry.type,
+			}].filter((x) => x.text);
+		case "compaction":
+			return [{
+				id: entry.id,
+				role: "note",
+				label: "compaction",
+				text: String(entry.summary || "").trim(),
+				timestamp: String(entry.timestamp || ""),
+				entryType: entry.type,
+			}].filter((x) => x.text);
+		default:
+			return [];
+	}
+}
+
+/**
+ * Convert Pi message/content blocks to plain text.
+ * @param {any} content
+ * @returns {string}
+ */
+function contentText(content) {
+	if (typeof content === "string") return content.trim();
+	if (!Array.isArray(content)) return "";
+	return content
+		.filter((b) => b && b.type === "text" && typeof b.text === "string")
+		.map((b) => b.text)
+		.join("\n")
+		.trim();
+}

package/src/core/steering-prompts.mjs

@@ -0,0 +1,34 @@
+/** Prompt builders for steering-first Agent Board workflows. */
+
+/** @param {string} userText */
+export function buildPlanRequestPrompt(userText = "") {
+	const extra = String(userText || "").trim();
+	return [
+		"Create an implementation plan only. Do not modify files unless explicitly instructed by the user.",
+		"Return: scope, assumptions, proposed steps, validation plan, risks, and open questions.",
+		"This Agent Board plan mode is advisory; hard tool restrictions may not be enforced by the runtime yet.",
+		extra ? `User request/context: ${extra}` : "Use the current session context and repository state.",
+	].join("\n\n");
+}
+
+/** @param {string} planText */
+export function buildApprovePlanPrompt(planText = "") {
+	return [
+		"The user approved the plan below. Implement it now.",
+		"When finished, summarize changed files, commands/tests run, validation results, and residual risks for the Agent Board evidence panel.",
+		"Plan:",
+		String(planText || "(no plan text captured)"),
+	].join("\n\n");
+}
+
+/** @param {string} planText @param {string} feedback */
+export function buildPlanChangesPrompt(planText = "", feedback = "") {
+	return [
+		"Revise the implementation plan based on the user's feedback. Do not implement yet.",
+		"Return the revised plan and call out what changed.",
+		"Current plan:",
+		String(planText || "(no prior plan captured)"),
+		"User feedback:",
+		String(feedback || "(no feedback supplied)"),
+	].join("\n\n");
+}

package/src/core/steering.mjs

@@ -0,0 +1,133 @@
+/** Durable steering / plan-approval state helpers. */
+import { atomicWriteJson, readJson } from "./atomic.mjs";
+import { truncate } from "./heuristics.mjs";
+import * as P from "./paths.mjs";
+
+const STATES = new Set(["none", "plan_requested", "awaiting_approval", "approved", "changes_requested", "executing_approved_plan"]);
+
+/** @param {string} viewId @param {number} [now] @returns {import("./types.mjs").SteeringState} */
+export function emptySteeringState(viewId, now = Date.now()) {
+	return {
+		version: 1,
+		viewId,
+		status: "none",
+		updatedAt: now,
+		planText: "",
+		planRunId: null,
+		approvedAt: null,
+		changeRequest: null,
+		executionRunId: null,
+		history: [],
+	};
+}
+
+/** @param {string} root @param {string} viewId */
+export function readSteering(root, viewId) {
+	return normalizeSteering(readJson(P.steeringPath(root, viewId), null), viewId);
+}
+
+/** @param {string} root @param {import("./types.mjs").SteeringState} state */
+export function writeSteering(root, state) {
+	const normalized = normalizeSteering(state, state.viewId);
+	normalized.updatedAt = Date.now();
+	atomicWriteJson(P.steeringPath(root, normalized.viewId), normalized);
+	return normalized;
+}
+
+/** @param {import("./types.mjs").SteeringState} state @returns {import("./types.mjs").SteeringSummary} */
+export function summarizeSteering(state) {
+	const s = normalizeSteering(state, state?.viewId ?? "");
+	return {
+		status: s.status,
+		awaitingApproval: s.status === "awaiting_approval",
+		planPreview: s.planText ? truncate(s.planText.replace(/\s+/g, " ").trim(), 180) : null,
+		updatedAt: s.updatedAt ?? null,
+		question: s.status === "awaiting_approval" ? "Approve this plan?" : null,
+	};
+}
+
+/** @param {string} root @param {string} viewId @param {{ runId?: string|null, note?: string }} [opts] */
+export function requestPlan(root, viewId, opts = {}) {
+	const state = readSteering(root, viewId);
+	transition(state, "plan_requested", "request_plan", opts.runId ?? null, opts.note ?? null);
+	state.planRunId = opts.runId ?? state.planRunId ?? null;
+	return writeSteering(root, state);
+}
+
+/** @param {string} root @param {string} viewId @param {{ runId?: string|null, planText: string, note?: string }} opts */
+export function recordPlanReady(root, viewId, opts) {
+	const state = readSteering(root, viewId);
+	state.planText = String(opts.planText || "").trim();
+	state.planRunId = opts.runId ?? state.planRunId ?? null;
+	transition(state, "awaiting_approval", "plan_ready", opts.runId ?? null, opts.note ?? null);
+	return writeSteering(root, state);
+}
+
+/** @param {string} root @param {string} viewId @param {{ runId?: string|null, note?: string }} [opts] */
+export function approvePlan(root, viewId, opts = {}) {
+	const state = readSteering(root, viewId);
+	if (state.status !== "awaiting_approval") return { ok: false, error: "No plan is awaiting approval", state };
+	state.approvedAt = Date.now();
+	state.executionRunId = opts.runId ?? null;
+	transition(state, "approved", "approve_plan", opts.runId ?? null, opts.note ?? null);
+	const saved = writeSteering(root, state);
+	return { ok: true, state: saved };
+}
+
+/** @param {string} root @param {string} viewId @param {string} feedback @param {{ runId?: string|null }} [opts] */
+export function requestPlanChanges(root, viewId, feedback, opts = {}) {
+	const clean = String(feedback || "").trim();
+	if (!clean) return { ok: false, error: "Empty change request", state: readSteering(root, viewId) };
+	const state = readSteering(root, viewId);
+	state.changeRequest = clean;
+	transition(state, "changes_requested", "request_plan_changes", opts.runId ?? null, clean);
+	const saved = writeSteering(root, state);
+	return { ok: true, state: saved };
+}
+
+/** @param {string} root @param {string} viewId @param {{ runId?: string|null }} [opts] */
+export function markExecutingApprovedPlan(root, viewId, opts = {}) {
+	const state = readSteering(root, viewId);
+	state.executionRunId = opts.runId ?? state.executionRunId ?? null;
+	transition(state, "executing_approved_plan", "execute_approved_plan", opts.runId ?? null, null);
+	return writeSteering(root, state);
+}
+
+/** @param {string} root @param {string} viewId @param {{ note?: string }} [opts] */
+export function resetSteering(root, viewId, opts = {}) {
+	const state = readSteering(root, viewId);
+	transition(state, "none", "reset", null, opts.note ?? null);
+	state.planText = "";
+	state.planRunId = null;
+	state.approvedAt = null;
+	state.changeRequest = null;
+	state.executionRunId = null;
+	return writeSteering(root, state);
+}
+
+/** @param {any} state @param {string} viewId @returns {import("./types.mjs").SteeringState} */
+function normalizeSteering(state, viewId) {
+	const base = emptySteeringState(viewId || state?.viewId || "");
+	if (!state || typeof state !== "object") return base;
+	return {
+		...base,
+		...state,
+		viewId: typeof state.viewId === "string" ? state.viewId : base.viewId,
+		status: STATES.has(state.status) ? state.status : "none",
+		planText: typeof state.planText === "string" ? state.planText : "",
+		planRunId: typeof state.planRunId === "string" ? state.planRunId : null,
+		approvedAt: Number.isFinite(state.approvedAt) ? state.approvedAt : null,
+		changeRequest: typeof state.changeRequest === "string" ? state.changeRequest : null,
+		executionRunId: typeof state.executionRunId === "string" ? state.executionRunId : null,
+		history: Array.isArray(state.history) ? state.history : [],
+	};
+}
+
+/** @param {import("./types.mjs").SteeringState} state @param {import("./types.mjs").SteeringModeState} to @param {string} action @param {string|null} runId @param {string|null} note */
+function transition(state, to, action, runId, note) {
+	const now = Date.now();
+	const from = state.status;
+	state.status = to;
+	state.updatedAt = now;
+	state.history.push({ at: now, from, to, action, runId, note: note ? truncate(note, 240) : null });
+}