@zhuxixi/pi-agent-board 0.7.0 → 0.9.0

package/runner/state-coordinator.mjs

@@ -74,8 +74,16 @@ const LAST_ACTIVITY_STAMP_KINDS = new Set(["mark_queued", "archive_view", "adopt
  *  full status content for a run that has no materialized status yet. Every
  *  other kind keeps PR #1's "patch presence ≠ file requirement" semantics
  *  (e.g. mark_completed's `status: {autoState: null}` on a legacy row without
- *  a status file must not fabricate one). */
-const STATUS_BOOTSTRAP_KINDS = new Set(["run_started", "followup_started"]);
+ *  a status file must not fabricate one).
+ *
+ *  `run_progress` joins them (issue #91 hard-down residual closure): its beat
+ *  patch IS the runner's full in-memory status, and when the coordinator was
+ *  down through the runner's boot window (mark_queued applied, run_started
+ *  lost) the first post-recovery beat is the only surviving source that can
+ *  recreate the file — without it beats and finalize reject stale_run forever
+ *  and the row can never converge. The decision layer gates this on a
+ *  qualified live-run beat (full-shaped patch, matching string runId). */
+const STATUS_BOOTSTRAP_KINDS = new Set(["run_started", "followup_started", "run_progress"]);
 
 const root = process.argv[2];
 if (!root) {
@@ -312,32 +320,50 @@ async function main() {
 	 * guards stamp only files strictly behind the record revision: the live path
 	 * always qualifies (the global counter is monotonic), while replay repairs
 	 * just the half that missed its write in a crash window and never moves the
-	 * other half backwards. A status patch without a status file is skipped —
-	 * patch presence ≠ file requirement (mark_completed always emits
-	 * `status: {autoState: null}`). The status run binding is the decision-time
-	 * one (`statusRunId`, recorded in the journal) so replay cannot re-bind a
-	 * runId-less patch to whatever run is current on disk at replay time;
-	 * `state.currentRunId` remains only as a legacy fallback for records written
-	 * before statusRunId existed.
+	 * other half backwards.
+	 *
+	 * Pairing invariant (issue #91 final review): EVERY applied revision pairs
+	 * BOTH files. A state-only patch (e.g. patch_fields markVisited) restamps
+	 * the existing status file's revision with no content change, and a
+	 * status-only patch restamps the state file the same way — a healthy
+	 * coordinator can never produce the asymmetric pair the reader-side
+	 * revision check (reconcile) treats as a crash signature. Journaled
+	 * state-only records heal on replay through this shared path. Residual:
+	 * a torn TRANSIENT beat (crash between the two writes, never journaled)
+	 * stays half-paired — ms-window × adjacent-crash, documented in the spec.
+	 *
+	 * A status patch without a status file is skipped — patch presence ≠ file
+	 * requirement (mark_completed always emits `status: {autoState: null}`).
+	 * The status run binding is the decision-time one (`statusRunId`, recorded
+	 * in the journal) so replay cannot re-bind a runId-less patch to whatever
+	 * run is current on disk at replay time; `state.currentRunId` remains only
+	 * as a legacy fallback for records written before statusRunId existed.
 	 */
 	function materialize(viewId, command, mutate, revision, statusRunId) {
 		withViewLockSync(root, viewId, "state-materialize", () => {
 			const state = readState(root, viewId);
-			if (mutate?.state && state && (state.materializedRevision ?? 0) < revision) {
-				writeState(root, { ...state, ...mutate.state, materializedRevision: revision });
+			if (state && (state.materializedRevision ?? 0) < revision) {
+				writeState(root, mutate?.state
+					? { ...state, ...mutate.state, materializedRevision: revision }
+					: { ...state, materializedRevision: revision });
 			}
 			const runId = command?.runId ?? statusRunId ?? state?.currentRunId ?? null;
-			if (mutate?.status && runId) {
-				const status = readStatus(root, viewId, runId);
+			if (!runId) return;
+			const status = readStatus(root, viewId, runId);
+			if (mutate?.status) {
 				if (!status && STATUS_BOOTSTRAP_KINDS.has(command?.kind)) {
-					// run_started / followup_started carry the full status content for a
-					// run that has no status file yet — create it (F1's clean-bootstrap
-					// half). Identity fields come from the command context; the patch
-					// carries everything meaningful.
+					// run_started / followup_started / (bootstrapping) run_progress
+					// carry the full status content for a run that has no status
+					// file yet — create it. Identity fields come from the command
+					// context; the patch carries everything meaningful.
 					writeStatus(root, { version: 1, runId, viewId, ...mutate.status, materializedRevision: revision });
 				} else if (status && (status.materializedRevision ?? 0) < revision) {
 					writeStatus(root, { ...status, ...mutate.status, materializedRevision: revision });
 				}
+			} else if (status && (status.materializedRevision ?? 0) < revision) {
+				// State-only patch: restamp the existing status file's revision with
+				// no content change (pairing invariant above).
+				writeStatus(root, { ...status, materializedRevision: revision });
 			}
 		});
 	}

package/runner/state-runner.mjs

@@ -14,6 +14,7 @@ import { finalizeEvidence, readEvidence, summarizeEvidence, writeEvidence } from
 import { updateCodeRefsFromEvidence } from "../src/core/code-refs-store.mjs";
 import { readState, readStatus, readMeta, writeState, writeStatus } from "../src/core/store.mjs";
 import { sendStateCommand } from "../src/core/coordinator-client.mjs";
+import { commandRejectDiagnostic } from "../src/core/state-commands.mjs";
 
 async function main() {
 	const configPath = process.argv[2];
@@ -69,12 +70,12 @@ async function main() {
 
 	if (result.status === "applied") {
 		appendDiagnostic(config.root, config.viewId, { source: "service", runId: config.runId, code: "auto_state_classified", message: "Auto-state classifier updated row state", details: { kind: classification.kind, confidence: classification.confidence, source: classification.source, reason: classification.reason } });
-	} else if (result.reason === "manual_fence" || result.reason === "no_change" || result.reason === "stale_run") {
-		// Designed fences — informational, not errors: the coordinator is the
-		// authority and a manual completion wins by design.
-		appendDiagnostic(config.root, config.viewId, { source: "service", runId: config.runId, code: "auto_state_classified_skipped", message: `Auto-state classification not applied (${result.reason})`, details: { reason: result.reason } });
 	} else if (result.reason !== "coordinator_disabled") {
-		appendDiagnostic(config.root, config.viewId, { source: "service", runId: config.runId, level: "warn", code: "auto_state_command_ambiguous", message: `Auto-state classification outcome unknown (${result.reason}); if the command was journaled, coordinator replay will recover it; otherwise the next classification pass will converge the row`, details: { reason: result.reason } });
+		// Unified decided/ambiguous classification (CR r2 issue-3): decided
+		// rejects (manual_fence/stale_run/…) log as info *_skipped — the
+		// coordinator's verdict is authoritative; only genuinely ambiguous
+		// outcomes (timeout/connection_reset) keep the recovery-path warn.
+		appendDiagnostic(config.root, config.viewId, { source: "service", runId: config.runId, ...commandRejectDiagnostic("auto_state", "Auto-state classification", result.reason, "otherwise the next classification pass will converge the row"), details: { reason: result.reason } });
 	}
 
 	if (result.reason === "coordinator_disabled") {

package/scripts/release.mjs

@@ -0,0 +1,446 @@
+#!/usr/bin/env node
+/**
+ * Release orchestrator — the single entry point for a release, from a clean
+ * `main` to a published npm version.
+ *
+ * Flow (prose version: docs/RELEASE.md):
+ *
+ *   precheck → prepare <bump> → open-pr <version>
+ *     → merge the PR with a MERGE COMMIT
+ *     → finish <version>   (creates the GitHub Release)
+ *     → .github/workflows/publish.yml publishes to npm with provenance
+ *
+ * Two ordering rules are baked in, because breaking either one ships a version
+ * that `main` does not contain, or skips a version's notes:
+ *
+ * 1. The CHANGELOG section is generated BEFORE `npm version`, because
+ *    `npm version` commits and tags the bump and would empty the commit range
+ *    the section is rendered from.
+ * 2. The GitHub Release is created AFTER the release PR is merged, and only
+ *    once the tag is an ancestor of `origin/main`. A squash-merged release PR
+ *    leaves the tag orphaned; `finish` refuses to continue in that case
+ *    instead of publishing a version whose bump commit never reached main.
+ *
+ * Modes:
+ *
+ *   node scripts/release.mjs precheck
+ *     Read-only gate: on main, clean tree, in sync with origin, no open
+ *     release/* PR, last tag reachable from origin/main, and at least one
+ *     functional commit to release.
+ *   node scripts/release.mjs prepare <patch|minor|major|X.Y.Z> [--dry-run]
+ *     Runs the gate, renders the CHANGELOG section from conventional commits,
+ *     commits it, runs `npm version` (bump commit + tag), and switches to
+ *     `release/vX.Y.Z`. Nothing leaves the machine.
+ *   node scripts/release.mjs open-pr <version> [--dry-run]
+ *     Pushes the release branch and its tag, then opens the release PR.
+ *   node scripts/release.mjs finish <version> [--dry-run] [--sync-main]
+ *     After the PR is merged: checks tag ancestry and CHANGELOG sync, then
+ *     creates the GitHub Release — the CI publish trigger. `--sync-main`
+ *     additionally resets a clean local main to origin/main.
+ *   node scripts/release.mjs notes <version>
+ *     Prints the CHANGELOG section for a version (the GitHub Release notes).
+ *
+ * Every mode is fail-closed: a failed check stops the run with exit code 1 and
+ * a JSON body naming the failure. All modes print JSON except `notes`, which
+ * prints the section itself so it can be redirected to a file.
+ *
+ * Changelog rendering is delegated to the pure, unit-tested functions in
+ * release_helper.mjs; the git/npm/gh side effects live here and nowhere else.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	functionalLines,
+	generateChangelog,
+	hasSection,
+	insertSection,
+	nextVersion,
+	parseCommitLines,
+	verifyFrom,
+} from "./release_helper.mjs";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const CHANGELOG_MD = join(REPO_ROOT, "CHANGELOG.md");
+const PACKAGE_JSON = join(REPO_ROOT, "package.json");
+const MAIN_BRANCH = "main";
+const PACKAGE_NAME = "@zhuxixi/pi-agent-board";
+const COMMANDS = new Set(["precheck", "prepare", "open-pr", "finish", "notes"]);
+const FLAGS = new Set(["--dry-run", "--sync-main"]);
+
+/* ------------------------------------------------------------------ *
+ * Pure helpers (unit-tested in test/release-flow.test.mjs)
+ * ------------------------------------------------------------------ */
+
+/** Branch a version is prepared on: `release/v0.9.0`. */
+export function releaseBranchName(version) {
+	return `release/v${version}`;
+}
+
+/**
+ * The `## [version]` section of a CHANGELOG, without the trailing link
+ * reference definition — i.e. the body used as GitHub Release notes.
+ * @param {string} changelogText
+ * @param {string} version
+ * @returns {string|null} null when the section is absent
+ */
+export function extractReleaseSection(changelogText, version) {
+	const text = String(changelogText ?? "");
+	const escaped = String(version).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const heading = new RegExp(`^##\\s*\\[${escaped}]`, "m");
+	const match = heading.exec(text);
+	if (!match) return null;
+	const rest = text.slice(match.index);
+	// The next `## [` heading ends the section; +1 because the search runs on a
+	// sliced string, so its index is relative to rest[1].
+	const nextHeading = rest.slice(1).search(/^##\s*\[/m);
+	const section = nextHeading === -1 ? rest : rest.slice(0, nextHeading + 1);
+	return section
+		.replace(/^\[[^\]]+]:\s+\S+\s*$/gm, "")
+		.replace(/\s+$/, "")
+		.replace(/^\n+/, "");
+}
+
+/**
+ * Decide whether a release may start, from a collected snapshot of repo state.
+ * Pure so the rules can be tested without a repository.
+ * @param {{branch: string, clean: boolean, ahead: number, behind: number, openReleasePrs: number|null, lastTag: string|null, lastTagReachable: boolean, functionalCommits: number}} state
+ * @returns {{ok: boolean, failures: string[]}}
+ */
+export function evaluatePreconditions(state) {
+	const failures = [];
+	if (state.branch !== MAIN_BRANCH) {
+		failures.push(`must run on ${MAIN_BRANCH} (currently on "${state.branch || "detached HEAD"}")`);
+	}
+	if (!state.clean) failures.push("working tree is dirty — commit or stash first");
+	if (state.behind > 0) failures.push(`local ${MAIN_BRANCH} is behind origin/${MAIN_BRANCH} by ${state.behind} commit(s) — pull first`);
+	if (state.ahead > 0) failures.push(`local ${MAIN_BRANCH} is ahead of origin/${MAIN_BRANCH} by ${state.ahead} commit(s)`);
+	if ((state.openReleasePrs ?? 0) > 0) failures.push(`${state.openReleasePrs} open release/* PR(s) — finish or close them first`);
+	if (state.lastTag && !state.lastTagReachable) {
+		failures.push(`tag ${state.lastTag} is not an ancestor of origin/${MAIN_BRANCH} (orphan tag) — re-point it before releasing`);
+	}
+	if (state.functionalCommits === 0) failures.push("no functional commits since the last tag — nothing to release");
+	return { ok: failures.length === 0, failures };
+}
+
+/**
+ * Parse the CLI argv into a command, its positional argument, and flags.
+ * @param {string[]} argv
+ * @returns {{command: string, arg: string|undefined, dryRun: boolean, syncMain: boolean}}
+ */
+export function parseArgs(argv) {
+	const flags = [];
+	const positional = [];
+	for (const raw of argv) {
+		if (raw.startsWith("--")) flags.push(raw);
+		else positional.push(raw);
+	}
+	const [command, arg] = positional;
+	if (!COMMANDS.has(command ?? "")) {
+		throw new Error(`unknown command "${command ?? ""}" — expected one of ${[...COMMANDS].join(", ")}`);
+	}
+	for (const flag of flags) {
+		if (!FLAGS.has(flag)) throw new Error(`unknown flag "${flag}" — expected ${[...FLAGS].join(", ")}`);
+	}
+	return { command, arg, dryRun: flags.includes("--dry-run"), syncMain: flags.includes("--sync-main") };
+}
+
+/* ------------------------------------------------------------------ *
+ * Repo plumbing
+ * ------------------------------------------------------------------ */
+
+/**
+ * Run a command, capturing both streams. stderr is folded into the thrown error
+ * so a failure names the command and what it said, while a successful run stays
+ * quiet (git's "Switched to a new branch" chatter included).
+ * @param {string} cmd
+ * @param {string[]} args
+ * @returns {string} stdout
+ */
+function run(cmd, args) {
+	try {
+		return execFileSync(cmd, args, { cwd: REPO_ROOT, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+	} catch (err) {
+		const stderr = String(err?.stderr ?? "").trim();
+		const detail = stderr ? `: ${stderr}` : "";
+		throw new Error(`${cmd} ${args.join(" ")} failed${detail}`);
+	}
+}
+
+/** @param {string[]} args @returns {string} git stdout */
+function git(args) {
+	return run("git", args);
+}
+
+/** @param {string[]} args @returns {boolean} true when the command succeeded */
+function gitOk(args) {
+	try {
+		git(args);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** @param {string[]} args @returns {string} npm stdout */
+function npm(args) {
+	return run("npm", args);
+}
+
+/** @param {string[]} args @returns {string} gh stdout */
+function gh(args) {
+	return run("gh", args);
+}
+
+/** @returns {string} version from package.json */
+function packageVersion() {
+	const version = JSON.parse(readFileSync(PACKAGE_JSON, "utf8")).version;
+	if (!/^\d+\.\d+\.\d+$/.test(version ?? "")) throw new Error(`package.json has no semver version: ${version}`);
+	return version;
+}
+
+/** @returns {string|null} newest reachable `v*` tag */
+function latestTag() {
+	try {
+		const tag = git(["describe", "--tags", "--abbrev=0", "--match", "v*"]).trim();
+		return tag || null;
+	} catch {
+		return null;
+	}
+}
+
+/** @param {string} range @returns {string[]} commit subjects in the range */
+function subjects(range) {
+	return git(["log", range, "--format=%s"])
+		.split("\n")
+		.map((s) => s.trim())
+		.filter(Boolean);
+}
+
+/** @returns {boolean} whether the tag exists locally */
+function tagExists(tag) {
+	return gitOk(["rev-parse", "--verify", "--quiet", `refs/tags/${tag}`]);
+}
+
+/** @param {string} ref @returns {boolean} whether ref exists locally */
+function refExists(ref) {
+	return gitOk(["rev-parse", "--verify", "--quiet", ref]);
+}
+
+/** @param {string} tag @param {string} ref @returns {boolean} */
+function isAncestor(tag, ref) {
+	return gitOk(["merge-base", "--is-ancestor", tag, ref]);
+}
+
+/**
+ * Count open `release/*` PRs. null means the check could not run (no `gh`, no
+ * auth, or not a GitHub remote) — reported but never a hard failure, so a
+ * missing `gh` cannot block a release that does not need it.
+ * @returns {number|null}
+ */
+function openReleasePrCount() {
+	try {
+		const json = gh(["pr", "list", "--state", "open", "--limit", "50", "--json", "headRefName"]);
+		return JSON.parse(json).filter((pr) => String(pr.headRefName ?? "").startsWith("release/")).length;
+	} catch {
+		return null;
+	}
+}
+
+/** @returns {object} the state consumed by evaluatePreconditions */
+function collectState() {
+	git(["fetch", "origin", "--quiet"]);
+	const [behind, ahead] = git(["rev-list", "--left-right", "--count", `origin/${MAIN_BRANCH}...HEAD`])
+		.trim()
+		.split(/\s+/)
+		.map(Number);
+	const lastTag = latestTag();
+	const functionalCommits = functionalLines(subjects(lastTag ? `${lastTag}..HEAD` : "HEAD")).length;
+	return {
+		branch: git(["branch", "--show-current"]).trim(),
+		clean: git(["status", "--porcelain"]).trim() === "",
+		ahead,
+		behind,
+		openReleasePrs: openReleasePrCount(),
+		lastTag,
+		lastTagReachable: lastTag ? isAncestor(lastTag, `origin/${MAIN_BRANCH}`) : true,
+		functionalCommits,
+	};
+}
+
+/** Throw unless the release may start; returns the collected state. */
+function assertPreconditions() {
+	const state = collectState();
+	const { ok, failures } = evaluatePreconditions(state);
+	if (!ok) throw new Error(`precheck failed:\n- ${failures.join("\n- ")}`);
+	return state;
+}
+
+/* ------------------------------------------------------------------ *
+ * Commands
+ * ------------------------------------------------------------------ */
+
+/** @returns {object} precheck report (never throws on a failed gate) */
+function cmdPrecheck() {
+	const state = collectState();
+	const { ok, failures } = evaluatePreconditions(state);
+	return { ok, failures, ...state, prCheck: state.openReleasePrs === null ? "unavailable (gh not authenticated or not a GitHub remote)" : "ok" };
+}
+
+/**
+ * @param {string|undefined} bump patch|minor|major|X.Y.Z
+ * @param {boolean} dryRun
+ * @returns {object}
+ */
+function cmdPrepare(bump, dryRun) {
+	const state = assertPreconditions();
+	const version = nextVersion(bump ?? "patch", packageVersion());
+	const branch = releaseBranchName(version);
+	const existing = readFileSync(CHANGELOG_MD, "utf8");
+	if (hasSection(existing, version)) {
+		throw new Error(`CHANGELOG.md already has a [${version}] section — remove the stale section before re-applying`);
+	}
+	const range = state.lastTag ? `${state.lastTag}..HEAD` : "HEAD";
+	const entries = parseCommitLines(subjects(range));
+	const section = generateChangelog({
+		version,
+		date: new Date().toISOString().slice(0, 10),
+		entries,
+		prevTag: state.lastTag,
+	});
+	const plan = [
+		`git add CHANGELOG.md && git commit -m "docs(changelog): add ${version} section"`,
+		`npm version ${bump ?? "patch"}`,
+		`git switch -c ${branch}`,
+	];
+	const next = `node scripts/release.mjs open-pr ${version}`;
+	if (dryRun) {
+		return { ok: true, dry_run: true, current_version: packageVersion(), new_version: version, last_tag: state.lastTag, changelog_preview: section, plan, next };
+	}
+	writeFileSync(CHANGELOG_MD, insertSection(existing, section));
+	git(["add", "CHANGELOG.md"]);
+	git(["commit", "-m", `docs(changelog): add ${version} section`]);
+	npm(["version", bump ?? "patch"]);
+	git(["switch", "-c", branch]);
+	return { ok: true, version, branch, tag: `v${version}`, next };
+}
+
+/**
+ * @param {string|undefined} version
+ * @param {boolean} dryRun
+ * @returns {object}
+ */
+function cmdOpenPr(version, dryRun) {
+	if (!version) throw new Error("open-pr requires a version (node scripts/release.mjs open-pr 0.9.0)");
+	const branch = releaseBranchName(version);
+	const tag = `v${version}`;
+	const current = git(["branch", "--show-current"]).trim();
+	if (packageVersion() !== version) throw new Error(`package.json is at ${packageVersion()}, expected ${version}`);
+	if (current !== branch) throw new Error(`expected to be on ${branch} (currently on "${current || "detached HEAD"}")`);
+	if (!tagExists(tag)) throw new Error(`tag ${tag} does not exist — run prepare first`);
+	const notes = extractReleaseSection(readFileSync(CHANGELOG_MD, "utf8"), version);
+	if (!notes) throw new Error(`CHANGELOG.md has no [${version}] section`);
+	const body = `${notes}\n\n---\n\nMerge with a **merge commit** — squashing would orphan the \`${tag}\` tag and break the changelog range for the next release.`;
+	const commands = [
+		`git push -u origin ${branch}`,
+		`git push origin ${tag}`,
+		`gh pr create --base ${MAIN_BRANCH} --head ${branch} --title "chore: release ${version}"`,
+	];
+	if (dryRun) return { ok: true, dry_run: true, version, branch, tag, commands };
+	git(["push", "-u", "origin", branch]);
+	git(["push", "origin", tag]);
+	const url = gh(["pr", "create", "--base", MAIN_BRANCH, "--head", branch, "--title", `chore: release ${version}`, "--body", body]).trim();
+	return { ok: true, version, branch, tag, pr: url, next: `merge with a merge commit, then: node scripts/release.mjs finish ${version} --sync-main` };
+}
+
+/**
+ * @param {string|undefined} version
+ * @param {{dryRun: boolean, syncMain: boolean}} opts
+ * @returns {object}
+ */
+function cmdFinish(version, { dryRun, syncMain }) {
+	if (!version) throw new Error("finish requires a version (node scripts/release.mjs finish 0.9.0)");
+	const tag = `v${version}`;
+	if (packageVersion() !== version) throw new Error(`package.json is at ${packageVersion()}, expected ${version}`);
+	git(["fetch", "origin", "--quiet"]);
+	if (!tagExists(tag)) throw new Error(`tag ${tag} is missing — push it with open-pr first`);
+	if (!isAncestor(tag, `origin/${MAIN_BRANCH}`)) {
+		throw new Error(
+			`tag ${tag} is not an ancestor of origin/${MAIN_BRANCH} — the release PR was probably squash-merged. ` +
+				`Point the tag at the content-equivalent commit on main (git tag -f ${tag} <sha> && git push origin ${tag} --force) and retry`,
+		);
+	}
+	const changelogText = readFileSync(CHANGELOG_MD, "utf8");
+	const drift = verifyFrom({ lines: subjects(`${tag}..origin/${MAIN_BRANCH}`), changelogText });
+	if (!drift.ok) {
+		throw new Error(
+			`CHANGELOG is missing functional PR(s) ${drift.missing.join(", ")} merged after the bump — ` +
+				`add them to the ${version} section in a docs(changelog) PR, then retry`,
+		);
+	}
+	const notes = extractReleaseSection(changelogText, version);
+	if (!notes) throw new Error(`CHANGELOG.md has no [${version}] section`);
+	if (dryRun) {
+		return { ok: true, dry_run: true, tag, notes, commands: [`gh release create ${tag} --title ${tag} --notes-file <notes>`], syncMain };
+	}
+	const dir = mkdtempSync(join(tmpdir(), "release-notes-"));
+	const notesFile = join(dir, `${tag}.md`);
+	try {
+		writeFileSync(notesFile, `${notes}\n`);
+		gh(["release", "create", tag, "--title", tag, "--notes-file", notesFile]);
+	} finally {
+		rmSync(dir, { recursive: true, force: true });
+	}
+	let syncedMain = false;
+	if (syncMain && git(["status", "--porcelain"]).trim() === "") {
+		git(["switch", MAIN_BRANCH]);
+		git(["reset", "--hard", `origin/${MAIN_BRANCH}`]);
+		syncedMain = true;
+	}
+	return {
+		ok: true,
+		version,
+		tag,
+		release: `https://github.com/zhuxixi/pi-agent-board/releases/tag/${tag}`,
+		package: `${PACKAGE_NAME}@${version}`,
+		synced_main: syncedMain,
+		publish: "CI publishes on release — watch it with: gh run list --workflow=publish.yml --limit 1",
+	};
+}
+
+/**
+ * @param {string|undefined} version
+ * @returns {string} the release notes text
+ */
+function cmdNotes(version) {
+	if (!version) throw new Error("notes requires a version (node scripts/release.mjs notes 0.9.0)");
+	const notes = extractReleaseSection(readFileSync(CHANGELOG_MD, "utf8"), version);
+	if (!notes) throw new Error(`CHANGELOG.md has no [${version}] section`);
+	return notes;
+}
+
+/* ------------------------------------------------------------------ *
+ * CLI
+ * ------------------------------------------------------------------ */
+
+function main(argv) {
+	try {
+		const { command, arg, dryRun, syncMain } = parseArgs(argv);
+		if (command === "notes") {
+			process.stdout.write(`${cmdNotes(arg)}\n`);
+			return;
+		}
+		const result = command === "precheck" ? cmdPrecheck() : command === "prepare" ? cmdPrepare(arg, dryRun) : command === "open-pr" ? cmdOpenPr(arg, dryRun) : cmdFinish(arg, { dryRun, syncMain });
+		console.log(JSON.stringify(result, null, 1));
+		if (result.ok === false) process.exitCode = 1;
+	} catch (err) {
+		console.log(JSON.stringify({ ok: false, error: String(err?.message ?? err) }));
+		process.exitCode = 1;
+	}
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+	main(process.argv.slice(2));
+}

package/scripts/run-perf-gate.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/**
+ * Authoritative entry for the A11 perf gate (issue #121).
+ *
+ * Loudly refuses under coverage instrumentation: c8 sets NODE_V8_COVERAGE
+ * for its whole process tree, and instrumented latency measurements are
+ * invalid (2.5–6× inflation). Silently skipping here would manufacture a
+ * fake-green gate, so refusal is a nonzero exit with an explicit message.
+ *
+ * This script is the side-effect layer only — no decision logic, no
+ * measurement. The pure gate decision lives in test-support/perf-gate.mjs
+ * and serves the test file; do not merge the layers (spec §3.2/§4).
+ */
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+if (process.env.NODE_V8_COVERAGE !== undefined) {
+	console.error(
+		"run-perf-gate: refusing to measure under coverage instrumentation " +
+			"(NODE_V8_COVERAGE is set). Perf assertions are only valid without c8; " +
+			"run `npm run test:perf` directly, outside any coverage wrapper.",
+	);
+	process.exit(1);
+}
+
+const perfTest = fileURLToPath(new URL("../test/terminal-model-perf.test.mjs", import.meta.url));
+// No --test-concurrency=1: the flag requires Node 21+ but package.json
+// declares engines >=20, and it is a no-op while the gate runs a single
+// file (spec D3, revised 2026-09-20). Re-add it when a second perf file
+// lands — parallel measurement across files must stay impossible.
+const child = spawn(
+	process.execPath,
+	["--test", perfTest],
+	{ stdio: "inherit", env: { ...process.env, AGENT_BOARD_PERF_GATE: "1" } },
+);
+child.on("error", (err) => {
+	console.error(`run-perf-gate: failed to spawn the perf suite: ${err.message}`);
+	process.exit(1);
+});
+child.on("exit", (code) => process.exit(code ?? 1));

package/src/commands/agent-board.ts

@@ -106,7 +106,7 @@ export async function openDashboard(
 					currentThinkingLevel: options.currentThinkingLevel ?? "off",
 				});
 				interval = setInterval(() => {
-					service.reconcile();
+					void service.reconcile().catch(() => {});
 					comp.refresh();
 					requestDashboardRender(tui);
 				}, POLL_MS);
@@ -146,8 +146,8 @@ export async function dashboardAttachLoop(
 	let again = true;
 	while (again) {
 		const currentId = currentViewId(ctx, service);
-		if (currentId) service.markVisited?.(currentId);
-		service.reconcile();
+		if (currentId) void service.markVisited?.(currentId)?.catch(() => {});
+		void service.reconcile().catch(() => {});
 		const result = await openDashboard(ctx, service, {
 			initialSelectedId: selectedId,
 			currentThinkingLevel: getThinkingLevel?.(),
@@ -185,9 +185,9 @@ async function attach(
 	// Single async resolver entry: real probe + bounded recovery decide readiness (issue #70).
 	const plan = planAttachResolved(await service.resolveAttachTarget(viewId));
 	if (plan.plan === "open-pty") {
-		service.markVisited?.(viewId);
+		void service.markVisited?.(viewId)?.catch(() => {});
 		const result = await openPtyAttach(ctx, root, row.meta.id, row.meta.name, plan.socketPath);
-		service.markVisited?.(viewId);
+		void service.markVisited?.(viewId)?.catch(() => {});
 		return { action: result.action === "closed" ? "closed" : "detached" };
 	}
 	if (plan.plan === "session-switch") {
@@ -197,7 +197,7 @@ async function attach(
 			return { action: "none" };
 		}
 		const name = latest.meta.name;
-		service.markVisited?.(viewId);
+		void service.markVisited?.(viewId)?.catch(() => {});
 		const switchingOverlay = await showSwitchingOverlay(ctx, name, "PTY unavailable");
 		const result = await ctx.switchSession(latest.meta.sessionFile, {
 			withSession: async (replaced) => {
@@ -296,8 +296,8 @@ function installBackToDashboard(ctx: ExtensionCommandContext, service: ReturnTyp
 			try {
 				let selectedId = currentViewId(ctx, service);
 				while (true) {
-					if (selectedId) service.markVisited?.(selectedId);
-					service.reconcile();
+					if (selectedId) void service.markVisited?.(selectedId)?.catch(() => {});
+					void service.reconcile().catch(() => {});
 					const result = await openDashboard(ctx, service, { initialSelectedId: selectedId });
 					if (result.action !== "attach") return;
 					selectedId = result.viewId;