cool-workflow 0.2.3 → 0.2.5

package/scripts/verify-bump-reproduction.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+"use strict";
+// verify-bump-reproduction.js — closes the HEAD~1 verdict-replay bypass.
+//
+// release-gate.yml / npm-publish.yml tolerate a verdict written for the tag
+// commit's PARENT (release-flow.js's cut() reviews content, then adds a
+// mechanical version-bump + the verdict as a NEW child commit that actually
+// gets tagged). A validly-signed verdict at the parent proves someone once
+// approved THAT commit — it does NOT prove the child (the thing actually being
+// tagged) is the deterministic bump cut() would have produced, rather than an
+// attacker's own commit smuggling in arbitrary changes on top of an old,
+// genuinely-approved parent (a real signature on a REPLAYED verdict).
+//
+// This script independently reproduces the bump: checks out the approved
+// parent into a scratch worktree, runs the SAME bump:version/sync:project-index
+// steps cut() runs, stages the SAME way cut() stages (git add -u + the
+// explicit verdict/.sig paths, never -A), and requires the resulting tree to
+// match the ACTUAL tagged commit's tree byte-for-byte. Any difference —
+// anywhere, including a single added file — fails closed.
+//
+// (Node port of the former verify-bump-reproduction.sh; behavior kept line
+// for line — same steps, same messages, same exit map.)
+//
+// Usage: verify-bump-reproduction.js <approved-parent-sha> <tagged-sha> <verdict-repo-relative-path> [sig-repo-relative-path]
+//
+// Exit 0: the tagged commit's tree matches the reproduced bump exactly.
+// Exit 1: mismatch, or any step failed (install, bump, sync, worktree, etc).
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+// Where THIS SCRIPT ITSELF lives — distinct from REPO_ROOT (the git repo being
+// operated ON, resolved below from the invocation cwd). These coincide in
+// ordinary production use (the script runs from within the same checkout it
+// verifies), but conflating them is wrong: REPO_ROOT could be an ARBITRARY git
+// context (e.g. a test harness's throwaway clone of old history, which never
+// has this script's own sibling files, since they postdate whatever was
+// cloned). Sibling files this script depends on must be found relative to
+// where it is installed, never relative to the repo it happens to be pointed at.
+const SCRIPT_DIR = __dirname;
+
+function err(msg) {
+  process.stderr.write(`${msg}\n`);
+}
+
+const [, , PARENT, TAGGED, VERDICT_REL, SIG_REL = ""] = process.argv;
+if (!PARENT || !TAGGED || !VERDICT_REL) {
+  err("usage: verify-bump-reproduction.js <parent-sha> <tagged-sha> <verdict-rel-path> [sig-rel-path]");
+  process.exit(1);
+}
+
+function run(cmd, args, opts = {}) {
+  return spawnSync(cmd, args, { encoding: "utf8", ...opts });
+}
+function gitIn(dir, args, opts = {}) {
+  return run("git", ["-C", dir, ...args], opts);
+}
+
+const top = run("git", ["rev-parse", "--show-toplevel"]);
+if (top.status !== 0) process.exit(1);
+const REPO_ROOT = top.stdout.trim();
+
+const SCRATCH_PARENT = fs.mkdtempSync(path.join(os.tmpdir(), "cw-bump-repro-"));
+const SCRATCH = path.join(SCRATCH_PARENT, "wt");
+function cleanup() {
+  gitIn(REPO_ROOT, ["worktree", "remove", "--force", SCRATCH], { stdio: "ignore" });
+  fs.rmSync(SCRATCH_PARENT, { recursive: true, force: true });
+}
+
+function main() {
+  const wt = gitIn(REPO_ROOT, ["worktree", "add", "--quiet", "--detach", SCRATCH, PARENT], { stdio: "ignore" });
+  if (wt.status !== 0) {
+    err(`verify-bump-reproduction: could not create a scratch worktree at ${PARENT}`);
+    return 1;
+  }
+
+  // The target version comes from the TAGGED commit (not the parent, which may
+  // still be pre-bump) — read via git plumbing, no separate checkout needed.
+  const pkgShow = gitIn(REPO_ROOT, ["show", `${TAGGED}:plugins/cool-workflow/package.json`]);
+  let VERSION = "";
+  if (pkgShow.status === 0) {
+    try {
+      VERSION = JSON.parse(pkgShow.stdout).version || "";
+    } catch {
+      VERSION = "";
+    }
+  }
+  if (!VERSION) {
+    err(`verify-bump-reproduction: could not read package.json version from tagged commit ${TAGGED}`);
+    return 1;
+  }
+
+  // sync-project-index.js embeds a wall-clock "Generated on <date>" line. Pin it
+  // to the TAGGED commit's own committer date (UTC) via a Node --require preload
+  // that overrides the global Date constructor (fake-date-for-reproduction.js),
+  // NOT an application-level env var: the scratch worktree runs the APPROVED
+  // PARENT's OWN checked-out copy of sync-project-index.js, which for every
+  // release cut before this mechanism existed has no idea any such env var is
+  // meant to be read — an app-level opt-in is a no-op against code that doesn't
+  // know to opt in, so it can only ever "work" for releases cut after the
+  // mechanism landed (confirmed empirically: re-running an already-shipped
+  // release's real approved-parent/tagged pair on a later calendar day produced
+  // a tree mismatch whose ONLY diff was that one date line). A global override
+  // of the Date constructor, injected before any application code runs, is
+  // transparent to the code being executed regardless of which version it is.
+  const dateShow = gitIn(REPO_ROOT, ["show", "-s", "--format=%cd", "--date=format-local:%Y-%m-%d", TAGGED], {
+    env: { ...process.env, TZ: "UTC" },
+  });
+  const CUT_DATE = dateShow.status === 0 ? dateShow.stdout.trim() : "";
+  if (!CUT_DATE) {
+    err("verify-bump-reproduction: could not read the tagged commit's committer date");
+    return 1;
+  }
+  const FAKE_DATE_PRELOAD = path.join(SCRIPT_DIR, "fake-date-for-reproduction.js");
+
+  // Each step's exit code is checked EXPLICITLY and immediately (not via one
+  // combined chain) — a chain's overall success can silently survive an earlier
+  // step's failure if a future edit ever loosens it, which would flip this
+  // fail-closed gate to fail-open without changing its outward shape.
+  // stdout/stderr from each step are captured (not discarded) so a real
+  // failure — a transient npm registry hiccup vs. an actual reproduction
+  // mismatch — is distinguishable in the workflow log instead of both
+  // collapsing into the same generic message.
+  const stepCwd = path.join(SCRATCH, "plugins", "cool-workflow");
+  const stepEnv = {
+    ...process.env,
+    NODE_OPTIONS: `--require ${FAKE_DATE_PRELOAD}`,
+    CW_FAKE_DATE: CUT_DATE,
+  };
+  function runStep(label, cmd, args) {
+    const r = run(cmd, args, { cwd: stepCwd, env: stepEnv });
+    const out = (r.stdout || "") + (r.stderr || "");
+    const code = r.error ? 1 : r.status;
+    if (code !== 0) {
+      err(`verify-bump-reproduction: ${label} failed (exit ${code}):`);
+      err(out);
+      return false;
+    }
+    return true;
+  }
+
+  const bumpOk =
+    runStep("npm install", "npm", ["install", "--no-package-lock", "--ignore-scripts"]) &&
+    runStep("bump:version", "npm", ["run", "bump:version", "--", VERSION]) &&
+    runStep("sync:project-index", "npm", ["run", "sync:project-index", "--", "--repo-only"]);
+  if (!bumpOk) {
+    err(`verify-bump-reproduction: reproducing the bump for ${PARENT} -> v${VERSION} failed`);
+    return 1;
+  }
+
+  fs.mkdirSync(path.join(SCRATCH, ".cw-release"), { recursive: true });
+  try {
+    fs.copyFileSync(path.join(REPO_ROOT, VERDICT_REL), path.join(SCRATCH, VERDICT_REL));
+  } catch {
+    return 1;
+  }
+  if (SIG_REL && fs.existsSync(path.join(REPO_ROOT, SIG_REL))) {
+    try {
+      fs.copyFileSync(path.join(REPO_ROOT, SIG_REL), path.join(SCRATCH, SIG_REL));
+    } catch {
+      return 1;
+    }
+  }
+
+  // Mirror cut()'s OWN staging exactly (git-add -u + the explicit verdict/.sig
+  // paths) — never -A, so an untracked stray left by npm/tooling in the scratch
+  // worktree can never silently ride into what we compare.
+  gitIn(SCRATCH, ["add", "-u"]);
+  gitIn(SCRATCH, ["add", "--", VERDICT_REL]);
+  if (SIG_REL && fs.existsSync(path.join(SCRATCH, SIG_REL))) {
+    gitIn(SCRATCH, ["add", "--", SIG_REL]);
+  }
+
+  const EXPECTED_TREE = gitIn(SCRATCH, ["write-tree"]).stdout.trim();
+  const ACTUAL_TREE = gitIn(REPO_ROOT, ["rev-parse", `${TAGGED}^{tree}`]).stdout.trim();
+
+  if (EXPECTED_TREE !== ACTUAL_TREE) {
+    err(`verify-bump-reproduction: ${TAGGED}'s tree (${ACTUAL_TREE}) does not match the deterministic bump reproduced from approved parent ${PARENT} (${EXPECTED_TREE}) — refusing`);
+    return 1;
+  }
+
+  return 0;
+}
+
+let code = 1;
+try {
+  code = main();
+} finally {
+  cleanup();
+}
+process.exit(code);

package/scripts/verify-verdict-signature.js

@@ -4,7 +4,7 @@
 // verify-verdict-signature.js — verify an ed25519 signature over a committed
 // release verdict file, against the committed public key
 // (.cw-release/verdict-signing.pub). Portable (node + node:crypto only) so
-// CI (release-gate.yml, npm-publish.yml) and the local block-unapproved-tag.sh
+// CI (release-gate.yml, npm-publish.yml) and the local block-unapproved-tag.js
 // hook can all shell out to the SAME check instead of three drifting copies.
 //
 // Exit 0: signature verifies. Exit 1: missing file, unreadable key, or a

package/scripts/version-sync-check.js

@@ -106,68 +106,68 @@ function main() {
   // above (version.ts/dist/package.json/manifests/docs) still pin the release.
   checkIncludes("plugins/cool-workflow/docs/index.md", "release and migration", checks);
   checkIncludes("plugins/cool-workflow/docs/multi-agent-topologies.7.md", "Multi-Agent Topologies", checks);
-  checkIncludes("plugins/cool-workflow/docs/multi-agent-cli-mcp-surface.7.md", VERSION, checks);
-  checkIncludes("plugins/cool-workflow/docs/multi-agent-operator-ux.7.md", VERSION, checks);
-  checkIncludes("plugins/cool-workflow/docs/multi-agent-eval-replay-harness.7.md", VERSION, checks);
+  checkIncludesOwnLine("plugins/cool-workflow/docs/multi-agent-cli-mcp-surface.7.md", VERSION, checks);
+  checkIncludesOwnLine("plugins/cool-workflow/docs/multi-agent-operator-ux.7.md", VERSION, checks);
+  checkIncludesOwnLine("plugins/cool-workflow/docs/multi-agent-eval-replay-harness.7.md", VERSION, checks);
   checkIncludes("plugins/cool-workflow/docs/state-explosion-management.7.md", "State Explosion Management", checks);
-  checkIncludes("plugins/cool-workflow/docs/state-explosion-management.7.md", VERSION, checks);
+  checkIncludesOwnLine("plugins/cool-workflow/docs/state-explosion-management.7.md", VERSION, checks);
   checkIncludes("plugins/cool-workflow/docs/evidence-adoption-reasoning-chain.7.md", "Evidence Adoption Reasoning Chain", checks);
-  checkIncludes("plugins/cool-workflow/docs/evidence-adoption-reasoning-chain.7.md", VERSION, checks);
+  checkIncludesOwnLine("plugins/cool-workflow/docs/evidence-adoption-reasoning-chain.7.md", VERSION, checks);
   checkIncludes("plugins/cool-workflow/docs/coordinator-blackboard.7.md", "Coordinator / Blackboard", checks);
   checkIncludes("plugins/cool-workflow/docs/cli-mcp-parity.7.md", "CLI", checks);
-  checkIncludes("plugins/cool-workflow/docs/cli-mcp-parity.7.md", VERSION, checks);
+  checkIncludesOwnLine("plugins/cool-workflow/docs/cli-mcp-parity.7.md", VERSION, checks);
   checkIncludes("plugins/cool-workflow/docs/index.md", "cli-mcp-parity.7.md", checks);
   checkIncludes("plugins/cool-workflow/docs/run-registry-control-plane.7.md", "Run Registry / Control Plane", checks);
-  checkIncludes("plugins/cool-workflow/docs/run-registry-control-plane.7.md", VERSION, checks);
+  checkIncludesOwnLine("plugins/cool-workflow/docs/run-registry-control-plane.7.md", VERSION, checks);
   checkIncludes("plugins/cool-workflow/docs/index.md", "run-registry-control-plane.7.md", checks);
   checkIncludes("plugins/cool-workflow/test/run-registry-control-plane-smoke.js", "run-registry-control-plane-smoke", checks);
   checkIncludes("plugins/cool-workflow/docs/execution-backends.7.md", "Execution Backends", checks);
-  checkIncludes("plugins/cool-workflow/docs/execution-backends.7.md", VERSION, checks);
+  checkIncludesOwnLine("plugins/cool-workflow/docs/execution-backends.7.md", VERSION, checks);
   checkIncludes("plugins/cool-workflow/docs/index.md", "execution-backends.7.md", checks);
   checkIncludes("plugins/cool-workflow/test/execution-backends-smoke.js", "execution-backends-smoke", checks);
   checkIncludes("plugins/cool-workflow/docs/web-desktop-workbench.7.md", "Web / Desktop Workbench", checks);
-  checkIncludes("plugins/cool-workflow/docs/web-desktop-workbench.7.md", VERSION, checks);
+  checkIncludesOwnLine("plugins/cool-workflow/docs/web-desktop-workbench.7.md", VERSION, checks);
   checkIncludes("plugins/cool-workflow/docs/index.md", "web-desktop-workbench.7.md", checks);
   checkIncludes("plugins/cool-workflow/test/web-desktop-workbench-smoke.js", "web-desktop-workbench-smoke", checks);
   checkIncludes("plugins/cool-workflow/docs/observability-cost-accounting.7.md", "Observability + Cost Accounting", checks);
-  checkIncludes("plugins/cool-workflow/docs/observability-cost-accounting.7.md", VERSION, checks);
+  checkIncludesOwnLine("plugins/cool-workflow/docs/observability-cost-accounting.7.md", VERSION, checks);
   checkIncludes("plugins/cool-workflow/docs/index.md", "observability-cost-accounting.7.md", checks);
   checkIncludes("plugins/cool-workflow/test/observability-cost-accounting-smoke.js", "observability-cost-accounting-smoke", checks);
   checkIncludes("plugins/cool-workflow/docs/team-collaboration.7.md", "Team Collaboration", checks);
-  checkIncludes("plugins/cool-workflow/docs/team-collaboration.7.md", VERSION, checks);
+  checkIncludesOwnLine("plugins/cool-workflow/docs/team-collaboration.7.md", VERSION, checks);
   checkIncludes("plugins/cool-workflow/docs/index.md", "team-collaboration.7.md", checks);
   checkIncludes("plugins/cool-workflow/test/team-collaboration-smoke.js", "team-collaboration-smoke", checks);
   checkIncludes("plugins/cool-workflow/docs/release-tooling.7.md", "Release Tooling", checks);
-  checkIncludes("plugins/cool-workflow/docs/release-tooling.7.md", VERSION, checks);
+  checkIncludesOwnLine("plugins/cool-workflow/docs/release-tooling.7.md", VERSION, checks);
   checkIncludes("plugins/cool-workflow/docs/index.md", "release-tooling.7.md", checks);
   checkIncludes("plugins/cool-workflow/test/release-tooling-smoke.js", "release-tooling-smoke", checks);
   checkIncludes("plugins/cool-workflow/docs/real-execution-backends.7.md", "Real Execution Backend Integrations", checks);
-  checkIncludes("plugins/cool-workflow/docs/real-execution-backends.7.md", VERSION, checks);
+  checkIncludesOwnLine("plugins/cool-workflow/docs/real-execution-backends.7.md", VERSION, checks);
   checkIncludes("plugins/cool-workflow/docs/index.md", "real-execution-backends.7.md", checks);
   checkIncludes("plugins/cool-workflow/test/real-execution-backends-smoke.js", "real-execution-backends-smoke", checks);
   checkIncludes("plugins/cool-workflow/docs/node-snapshot-diff-replay.7.md", "Node Snapshot / Diff / Replay", checks);
-  checkIncludes("plugins/cool-workflow/docs/node-snapshot-diff-replay.7.md", VERSION, checks);
+  checkIncludesOwnLine("plugins/cool-workflow/docs/node-snapshot-diff-replay.7.md", VERSION, checks);
   checkIncludes("plugins/cool-workflow/docs/index.md", "node-snapshot-diff-replay.7.md", checks);
   checkIncludes("plugins/cool-workflow/test/node-snapshot-diff-replay-smoke.js", "node-snapshot-diff-replay-smoke", checks);
   checkIncludes("plugins/cool-workflow/docs/contract-migration-tooling.7.md", "Contract Migration Tooling", checks);
-  checkIncludes("plugins/cool-workflow/docs/contract-migration-tooling.7.md", VERSION, checks);
+  checkIncludesOwnLine("plugins/cool-workflow/docs/contract-migration-tooling.7.md", VERSION, checks);
   checkIncludes("plugins/cool-workflow/docs/index.md", "contract-migration-tooling.7.md", checks);
   checkIncludes("plugins/cool-workflow/test/contract-migration-tooling-smoke.js", "contract-migration-tooling-smoke", checks);
   checkIncludes("plugins/cool-workflow/docs/control-plane-scheduling.7.md", "Control-Plane Scheduling", checks);
-  checkIncludes("plugins/cool-workflow/docs/control-plane-scheduling.7.md", VERSION, checks);
+  checkIncludesOwnLine("plugins/cool-workflow/docs/control-plane-scheduling.7.md", VERSION, checks);
   checkIncludes("plugins/cool-workflow/docs/index.md", "control-plane-scheduling.7.md", checks);
   checkIncludes("plugins/cool-workflow/test/control-plane-scheduling-smoke.js", "control-plane-scheduling-smoke", checks);
   checkIncludes("plugins/cool-workflow/docs/agent-delegation-drive.7.md", "Agent Delegation Drive", checks);
-  checkIncludes("plugins/cool-workflow/docs/agent-delegation-drive.7.md", VERSION, checks);
+  checkIncludesOwnLine("plugins/cool-workflow/docs/agent-delegation-drive.7.md", VERSION, checks);
   checkIncludes("plugins/cool-workflow/docs/index.md", "agent-delegation-drive.7.md", checks);
   checkIncludes("plugins/cool-workflow/test/agent-delegation-drive-smoke.js", "agent-delegation-drive-smoke", checks);
   checkIncludes("plugins/cool-workflow/docs/run-retention-reclamation.7.md", "Run Retention & Provable Reclamation", checks);
-  checkIncludes("plugins/cool-workflow/docs/run-retention-reclamation.7.md", VERSION, checks);
+  checkIncludesOwnLine("plugins/cool-workflow/docs/run-retention-reclamation.7.md", VERSION, checks);
   checkIncludes("plugins/cool-workflow/docs/index.md", "run-retention-reclamation.7.md", checks);
   checkIncludes("plugins/cool-workflow/test/run-retention-reclamation-smoke.js", "run-retention-reclamation-smoke", checks);
   checkIncludes("plugins/cool-workflow/src/wiring/capability-table/scheduling-registry.ts", "gc.plan", checks);
   checkIncludes("plugins/cool-workflow/docs/durable-state-and-locking.7.md", "Durable State & Locking", checks);
-  checkIncludes("plugins/cool-workflow/docs/durable-state-and-locking.7.md", VERSION, checks);
+  checkIncludesOwnLine("plugins/cool-workflow/docs/durable-state-and-locking.7.md", VERSION, checks);
   checkIncludes("plugins/cool-workflow/docs/index.md", "durable-state-and-locking.7.md", checks);
   checkIncludes("plugins/cool-workflow/test/durable-atomic-write-smoke.js", "durable-atomic-write-smoke", checks);
   checkIncludes("plugins/cool-workflow/src/shell/fs-atomic.ts", "withFileLock", checks);
@@ -201,12 +201,12 @@ function main() {
   checkIncludes("plugins/cool-workflow/docs/getting-started.md", "npm run release:check", checks);
   checkIncludes("plugins/cool-workflow/package.json", "eval:replay", checks);
   checkIncludes("plugins/cool-workflow/docs/trust-audit-anchor.7.md", "Trust Audit Anchor", checks);
-  checkIncludes("plugins/cool-workflow/docs/trust-audit-anchor.7.md", VERSION, checks);
+  checkIncludesOwnLine("plugins/cool-workflow/docs/trust-audit-anchor.7.md", VERSION, checks);
   checkIncludes("plugins/cool-workflow/docs/index.md", "trust-audit-anchor.7.md", checks);
   checkIncludes("plugins/cool-workflow/test/trust-audit-anchor-smoke.js", "trust-audit-anchor-smoke", checks);
-  checkIncludes("plugins/cool-workflow/docs/release-and-migration.7.md", VERSION, checks);
+  checkIncludesOwnLine("plugins/cool-workflow/docs/release-and-migration.7.md", VERSION, checks);
   checkIncludes("CHANGELOG.md", `## ${VERSION}`, checks);
-  checkIncludes("RELEASE.md", VERSION, checks);
+  checkIncludesOwnLine("RELEASE.md", VERSION, checks);
   // Homebrew formula (repo root): git-tag formula. Homebrew scans the version
   // from the tag, so the tag is the single version surface to gate (an explicit
   // `version` line would be redundant and brew audit rejects it). bump-version.js
@@ -266,4 +266,21 @@ function checkIncludes(relativePath, needle, checks) {
   checks.push({ path: relativePath, includes: needle });
 }
 
+// A bare version number (e.g. "0.2.4") can appear anywhere in a doc's
+// prose — an example command, a cross-reference — without the doc's own
+// version-history footer (a blank-line-separated list, one release per
+// line, appended by bump-version.js's --content step) actually having
+// been updated. A plain substring check would silently pass on the
+// coincidental prose match and never notice the real footer line is
+// missing (found live: v0.2.4's bump left release-tooling.7.md's footer
+// stuck at 0.2.3, masked by an unrelated "npm run release -- 0.2.4"
+// example a few lines up). Require the needle on its own line instead.
+function checkIncludesOwnLine(relativePath, needle, checks) {
+  const src = readReleaseSource(relativePath);
+  assert.ok(src.exists, `${relativePath} must exist`);
+  const hasOwnLine = src.text.split("\n").some((line) => line.trim() === needle);
+  assert.ok(hasOwnLine, `${relativePath} must include ${needle} as its own line (not just as a substring)`);
+  checks.push({ path: relativePath, includesOwnLine: needle });
+}
+
 main();

package/ui/workbench/app.css

@@ -27,21 +27,31 @@
   }
 }
 * { box-sizing: border-box; }
+/* The body is a flex column and main takes the leftover height (flex: 1 +
+   min-height: 0 so the inner panes can scroll) — no hardcoded header
+   height, so a header that wraps to two lines no longer pushes the panes
+   past the bottom of the window. */
 body {
   margin: 0;
   font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
   background: var(--bg);
   color: var(--ink);
   font-size: 14px;
+  display: flex;
+  flex-direction: column;
+  height: 100vh;
 }
 header { padding: 14px 20px; border-bottom: 1px solid var(--line); }
 header h1 { margin: 0; font-size: 18px; font-weight: 600; }
 header .muted, .muted { color: var(--muted); font-weight: 400; }
 header .trust { margin: 4px 0 0; font-size: 12px; color: var(--muted); }
 code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
-main { display: grid; grid-template-columns: 320px 1fr; height: calc(100vh - 64px); }
+main { display: grid; grid-template-columns: 320px 1fr; flex: 1; min-height: 0; }
 .sidebar { border-right: 1px solid var(--line); overflow-y: auto; padding: 12px; }
 .bar { display: flex; align-items: center; justify-content: space-between; margin-bottom: 8px; }
+/* The sidebar heading is a real <h2> (document outline / screen-reader
+   navigation) styled to the size the old <strong> label had. */
+.bar h2 { margin: 0; font-size: 14px; font-weight: 600; }
 button {
   background: var(--panel-2); color: var(--ink); border: 1px solid var(--line);
   border-radius: 6px; padding: 4px 10px; cursor: pointer; font-size: 12px;
@@ -51,16 +61,28 @@ input[type="search"] {
   width: 100%; background: var(--panel); color: var(--ink);
   border: 1px solid var(--line); border-radius: 6px; padding: 6px 8px; margin-bottom: 8px;
 }
-.freshness { font-size: 11px; color: var(--muted); margin-bottom: 8px; }
+.freshness { font-size: 12px; color: var(--muted); margin-bottom: 8px; }
 .run-list { list-style: none; margin: 0; padding: 0; }
-.run-list li {
+.run-list li,
+.run-list button {
   padding: 8px; border: 1px solid var(--line); border-radius: 6px;
   margin-bottom: 6px; cursor: pointer; background: var(--panel);
 }
-.run-list li:hover { border-color: var(--accent); }
-.run-list li.active { border-color: var(--accent); background: var(--panel-2); }
+/* Only the run-row <button> needs a plain-element reset: a <button> has
+   its own default display/width/font/color, a plain <li> (used only for
+   the error and empty-state rows) does not and must keep its own color
+   (.err red, .muted gray) — see app.js. */
+.run-list button {
+  display: block; width: 100%; text-align: left; font: inherit; color: inherit;
+}
+.run-list li:hover, .run-list button:hover { border-color: var(--accent); }
+.run-list li.active, .run-list button.active { border-color: var(--accent); background: var(--panel-2); }
+/* Run rows are now real <button> elements (for Tab/Enter/Space); make the
+   keyboard focus ring visible — there is no :focus-visible rule for this
+   element otherwise. */
+.run-list button:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
 .run-list .rid { font-family: ui-monospace, monospace; font-size: 12px; display: flex; align-items: center; gap: 6px; }
-.run-list .meta { color: var(--muted); font-size: 11px; margin-top: 2px; }
+.run-list .meta { color: var(--muted); font-size: 12px; margin-top: 2px; }
 .status-dot {
   display: inline-block; width: 8px; height: 8px; border-radius: 50%; flex: none;
   background: var(--muted);
@@ -81,13 +103,23 @@ input[type="search"] {
   padding: 8px 12px; border-bottom: 1px solid var(--line);
 }
 .panel-card > .head .title { font-weight: 600; }
-.panel-card > .head .src { font-size: 11px; color: var(--muted); font-family: ui-monospace, monospace; }
-.badge { font-size: 11px; padding: 2px 8px; border-radius: 999px; border: 1px solid var(--line); }
+.panel-card > .head .src { font-size: 12px; color: var(--muted); font-family: ui-monospace, monospace; }
+.badge { font-size: 12px; padding: 2px 8px; border-radius: 999px; border: 1px solid var(--line); }
 .badge.present { color: var(--present); border-color: var(--present); }
 .badge.absent { color: var(--absent); border-color: var(--absent); }
 .badge.stale { color: var(--absent); border-color: var(--absent); }
 .badge.valid { color: var(--present); border-color: var(--present); }
 .badge.missing, .badge.bad { color: var(--bad); border-color: var(--bad); }
+/* Lifecycle states shown as a badge in the run detail header (the other
+   lifecycle values reuse the neutral/present/absent colors above). */
+.badge.blocked { color: var(--absent); border-color: var(--absent); }
+.badge.failed { color: var(--bad); border-color: var(--bad); }
+.badge.completed { color: var(--present); border-color: var(--present); }
+.badge.running { color: var(--accent); border-color: var(--accent); }
+/* One plain next-step line under the header when a run is blocked/failed. */
+.recovery-hint { margin: 0 0 12px; font-size: 12px; color: var(--absent); }
+/* Second line of the empty-list state: the suggested next command. */
+.run-list li .hint { margin-top: 4px; font-size: 12px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
 pre.json {
   margin: 0; padding: 12px; overflow-x: auto; font-size: 12px;
   font-family: ui-monospace, SFMono-Regular, Menlo, monospace; line-height: 1.5;
@@ -99,7 +131,7 @@ pre.json {
 .err { color: var(--bad); }
 .struct-block { padding: 10px 12px; border-top: 1px solid var(--line); }
 .struct-block:first-child { border-top: none; }
-.struct-block .struct-title { font-size: 11px; text-transform: uppercase; letter-spacing: 0.04em; color: var(--muted); margin-bottom: 6px; }
+.struct-block .struct-title { font-size: 12px; text-transform: uppercase; letter-spacing: 0.04em; color: var(--muted); margin-bottom: 6px; }
 .struct-table { width: 100%; border-collapse: collapse; font-size: 12px; }
 .struct-table th, .struct-table td {
   text-align: left; padding: 4px 8px; border-bottom: 1px solid var(--line);