@kontextmind/kxm 0.7.170 → 0.7.172

package/plugins/kxm/dist/mcp-server.js

@@ -25438,7 +25438,7 @@ function sessionTokenFixHint(policy) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.170";
+var VERSION = "0.7.172";
 var CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.170",
+  "version": "0.7.172",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/skills/kxm-runs/SKILL.md

@@ -32,6 +32,9 @@ serve` serves that site with `python3 ops/docs-site/serve.py` and passes
 | `kxm lane drop <unit>` | Remove the worktree and the record. The branch is not deleted | `--force`, `--json` |
 | `kxm lane run <unit>` | Create the lane if needed, start a run from a brief, and drive it | `--brief <file>` (required), `--workflow <id>`, `--base <ref>`, `--wait`, `--timeout-ms <n>`, `--json` |
 | `kxm land` | Verify, regenerate docs, push, open or reuse a pull request, rebase, unblock, squash-merge, watch the release, and note a milestone | `--pr <n>`, `--stage <name>`, `--body-file <path>`, `--json`, `--dry-run` |
+| `kxm supervise status` | Show persisted in-flight lanes, pull request and CI state, and backoff timers | `--json` |
+| `kxm supervise record --lane <unit>` | Record one lane observation in `.kxm/state/supervisor.json` | `--pr`, `--merge-state`, `--ci-status`, `--ci-conclusion`, `--backoff-ms`, `--settled` |
+| `kxm supervise tick` | Clear elapsed backoff timers and append `.kxm/logs/supervisor.log` | `--json`, `--dry-run` |
 | `kxm assign run` | Dispatch one assignment manifest. The runner performs every check | `--manifest <path>` |
 | `kxm assign witness` | Run the fixed witness for an existing record | `--record-dir <path>` |
 | `kxm assign plan-current` | Stamp or advance the current-plan pointer | `--task-dir <path>`, `--plan <path>`, `--sha256 <hex>`, `--base-commit <sha>`, `--expected-generation <n>` |
@@ -89,6 +92,13 @@ generated pages. `push` publishes the branch. `pr` reuses the open pull
 request or creates one from `--body-file`. `rebase` rebases onto
 `origin/main` for at most five rounds, resolving only the dist rebuild, the
 CHANGELOG Unreleased union, and the tracker "Landed in this tree" union.
+`UNKNOWN` is polled and never treated as ready; `CLEAN` and `HAS_HOOKS`
+proceed, `BEHIND` and `DIRTY` rebase, and any other known state blocks. A
+failed `verify` names the exit code, the failing step, and a short excerpt,
+and writes the full log under `.kxm/logs/`.
+`kxm supervise` stores in-flight lanes, last-seen pull request and CI state,
+and backoff timers in `.kxm/state/supervisor.json`. A later process loads
+that file. `tick` clears a backoff whose deadline has passed.
 `unblock` reruns one failed check and reports a required review. `merge`
 squash-merges. `release` waits for the tag and the npm publish. `milestone`
 reports `deep_review_required` when a phase flips to done or the body contains

package/plugins/kxm/src/cli/supervise.ts

@@ -0,0 +1,167 @@
+import { appendFileSync, chmodSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { discoverKxmProjectRoot } from "../project-config.ts";
+import {
+  applyObservation,
+  formatTickLine,
+  loadSupervisorState,
+  resolveSupervisorNow,
+  resumeTick,
+  saveSupervisorState,
+  type SupervisorState,
+} from "../supervise-state.ts";
+import { print, printPlan, type Runtime } from "./types.ts";
+
+export interface SuperviseRecordOptions {
+  lane: string;
+  pr?: string;
+  mergeState?: string;
+  ciStatus?: string;
+  ciConclusion?: string;
+  backoffMs?: string;
+  settled?: boolean;
+}
+
+function refuse(runtime: Runtime, error: string, text: string): number {
+  print(runtime.io, runtime.json, { ok: false, command: "supervise", error }, text);
+  return 1;
+}
+
+function requireProject(runtime: Runtime): number | undefined {
+  if (!discoverKxmProjectRoot(runtime.cwd)) {
+    return refuse(runtime, "project_required", "supervise requires a KXM project (run kxm init first)");
+  }
+  return undefined;
+}
+
+function nowOf(runtime: Runtime): string | number {
+  const now = resolveSupervisorNow(runtime.env.KXM_SUPERVISE_NOW, new Date());
+  if (now === "supervisor_clock_invalid") {
+    return refuse(runtime, "supervisor_clock_invalid", "KXM_SUPERVISE_NOW must be an ISO-8601 UTC timestamp");
+  }
+  return now;
+}
+
+function loaded(runtime: Runtime, now: string): SupervisorState | number {
+  const state = loadSupervisorState(runtime.dirs.state, now);
+  if (state === "supervisor_unreadable") {
+    return refuse(runtime, "supervisor_unreadable", "supervisor state is unreadable and was left unchanged");
+  }
+  if (state === "supervisor_schema_unsupported") {
+    return refuse(runtime, "supervisor_schema_unsupported", "supervisor state schema is not kxm.supervisor.v1 and was left unchanged");
+  }
+  return state;
+}
+
+function laneText(state: SupervisorState): string {
+  const units = Object.keys(state.lanes).sort();
+  if (units.length === 0) return "supervisor: no lanes";
+  const lines = [`supervisor: ${units.length} lane${units.length === 1 ? "" : "s"}`];
+  for (const unit of units) {
+    const lane = state.lanes[unit];
+    if (!lane) continue;
+    const flight = lane.inFlight ? "in-flight" : "settled";
+    const pr = lane.pr ? ` pr ${lane.pr.number} ${lane.pr.mergeState}` : "";
+    const ci = lane.ci ? ` ci ${lane.ci.status}/${lane.ci.conclusion}` : "";
+    const backoff = lane.backoffUntil ? ` backoff ${lane.backoffUntil}` : "";
+    lines.push(`${unit} ${flight}${pr}${ci}${backoff}`);
+  }
+  return lines.join("\n");
+}
+
+function show(runtime: Runtime, state: SupervisorState, extra: Record<string, unknown> = {}): number {
+  print(runtime.io, runtime.json, { ok: true, command: "supervise", ...extra, state }, laneText(state));
+  return 0;
+}
+
+export function cmdSuperviseStatus(runtime: Runtime): number {
+  const missing = requireProject(runtime);
+  if (missing !== undefined) return missing;
+  const now = nowOf(runtime);
+  if (typeof now === "number") return now;
+  const state = loaded(runtime, now);
+  if (typeof state === "number") return state;
+  return show(runtime, state);
+}
+
+function appendTick(runtime: Runtime, line: string): void {
+  mkdirSync(runtime.dirs.logs, { recursive: true });
+  const path = join(runtime.dirs.logs, "supervisor.log");
+  appendFileSync(path, `${line}\n`, { encoding: "utf8", mode: 0o600 });
+  try { chmodSync(path, 0o600); } catch { /* Windows may not expose POSIX modes. */ }
+}
+
+export function cmdSuperviseTick(runtime: Runtime): number {
+  const missing = requireProject(runtime);
+  if (missing !== undefined) return missing;
+  const now = nowOf(runtime);
+  if (typeof now === "number") return now;
+  const state = loaded(runtime, now);
+  if (typeof state === "number") return state;
+  const tick = resumeTick(state, now);
+  const line = formatTickLine(now, tick.resumed, tick.waiting);
+  if (runtime.dryRun) {
+    printPlan(runtime, { command: "supervise", resumed: tick.resumed, waiting: tick.waiting, log: line, state: tick.state }, [
+      { action: "write", target: join(runtime.dirs.state, "supervisor.json") },
+      { action: "write", target: join(runtime.dirs.logs, "supervisor.log") },
+    ], "resume lanes whose backoff has elapsed");
+    return 0;
+  }
+  saveSupervisorState(runtime.dirs.state, tick.state);
+  appendTick(runtime, line);
+  return show(runtime, tick.state, { resumed: tick.resumed, waiting: tick.waiting, log: line });
+}
+
+function parseBackoff(value: string | undefined): number | undefined | "supervisor_backoff_invalid" {
+  if (value === undefined) return undefined;
+  if (!/^[0-9]+$/.test(value)) return "supervisor_backoff_invalid";
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed)) return "supervisor_backoff_invalid";
+  return parsed;
+}
+
+export function cmdSuperviseRecord(runtime: Runtime, options: SuperviseRecordOptions): number {
+  const missing = requireProject(runtime);
+  if (missing !== undefined) return missing;
+  const now = nowOf(runtime);
+  if (typeof now === "number") return now;
+  const state = loaded(runtime, now);
+  if (typeof state === "number") return state;
+  const hasPr = options.pr !== undefined || options.mergeState !== undefined;
+  if (hasPr && (options.pr === undefined || options.mergeState === undefined || !/^[0-9]+$/.test(options.pr))) {
+    return refuse(runtime, "supervisor_pr_invalid", "record a pull request with both --pr and --merge-state");
+  }
+  const hasCi = options.ciStatus !== undefined || options.ciConclusion !== undefined;
+  if (hasCi && (options.ciStatus === undefined || options.ciConclusion === undefined)) {
+    return refuse(runtime, "supervisor_ci_invalid", "record CI with both --ci-status and --ci-conclusion");
+  }
+  const backoffMs = parseBackoff(options.backoffMs);
+  if (backoffMs === "supervisor_backoff_invalid") {
+    return refuse(runtime, "supervisor_backoff_invalid", "--backoff-ms must be a whole number of milliseconds from 0 through 86400000");
+  }
+  const next = applyObservation(state, {
+    unit: options.lane,
+    inFlight: options.settled !== true,
+    ...(hasPr ? { pr: { number: Number(options.pr), mergeState: String(options.mergeState).trim().toUpperCase() } } : {}),
+    ...(hasCi ? { ci: { status: String(options.ciStatus).trim().toLowerCase(), conclusion: String(options.ciConclusion).trim().toLowerCase() } } : {}),
+    ...(backoffMs !== undefined ? { backoffMs } : {}),
+  }, now);
+  if (typeof next === "string") {
+    const text = next === "lane_unit_invalid"
+      ? `lane unit ${options.lane} must match the KXM identifier pattern`
+      : next === "supervisor_pr_invalid"
+        ? "pull request number and merge state are not valid"
+        : next === "supervisor_ci_invalid"
+          ? "CI status and conclusion are not valid"
+          : "--backoff-ms must be a whole number of milliseconds from 0 through 86400000";
+    return refuse(runtime, next, text);
+  }
+  if (runtime.dryRun) {
+    printPlan(runtime, { command: "supervise", state: next }, [
+      { action: "write", target: join(runtime.dirs.state, "supervisor.json") },
+    ], `record lane ${options.lane}`);
+    return 0;
+  }
+  saveSupervisorState(runtime.dirs.state, next);
+  return show(runtime, next);
+}

package/plugins/kxm/src/cli.ts

@@ -136,6 +136,7 @@ import {
 } from "./cli/lanes.ts";
 
 import { cmdLand } from "./cli/land.ts";
+import { cmdSuperviseRecord, cmdSuperviseStatus, cmdSuperviseTick } from "./cli/supervise.ts";
 import { cmdAssign } from "./cli/assign.ts";
 
 import {
@@ -232,6 +233,7 @@ const DRY_RUN_COMMANDS: ReadonlySet<string> = new Set([
   "task create", "task list", "task get", "task run", "task sync",
   "studio layout", "studio serve",
   "docs build", "docs serve",
+  "supervise status", "supervise tick", "supervise record",
 ]);
 
 class DryRunRefused extends Error {
@@ -540,6 +542,36 @@ function createProgram(ctx: CliContext, result: { code: number }, argv: readonly
       });
     });
 
+  const superviseCmd = addGlobalOptions(program.command("supervise").description("Persist roadmap supervisor state across restarts"));
+  superviseCmd.helpCommand("help", "Show supervise help");
+  addGlobalOptions(superviseCmd.command("status").description("Show persisted in-flight lanes, pull request and CI state, and backoff timers"))
+    .action(async function superviseStatusAction(this: Command) {
+      result.code = cmdSuperviseStatus(runtimeFrom(ctx, this));
+    });
+  addGlobalOptions(superviseCmd.command("tick").description("Resume lanes whose backoff has elapsed and append a supervisor log line"))
+    .action(async function superviseTickAction(this: Command) {
+      result.code = cmdSuperviseTick(runtimeFrom(ctx, this));
+    });
+  addGlobalOptions(superviseCmd.command("record").description("Record one lane observation in the supervisor state"))
+    .requiredOption("--lane <unit>", "Lane unit")
+    .option("--pr <n>", "Last-seen pull request number")
+    .option("--merge-state <status>", "Last-seen mergeStateStatus")
+    .option("--ci-status <status>", "Last-seen CI status")
+    .option("--ci-conclusion <conclusion>", "Last-seen CI conclusion")
+    .option("--backoff-ms <n>", "Backoff from now, in milliseconds; 0 clears it")
+    .option("--settled", "Mark the lane not in flight")
+    .action(async function superviseRecordAction(this: Command, options: { lane: string; pr?: string; mergeState?: string; ciStatus?: string; ciConclusion?: string; backoffMs?: string; settled?: boolean }) {
+      result.code = cmdSuperviseRecord(runtimeFrom(ctx, this), {
+        lane: options.lane,
+        ...(options.pr !== undefined ? { pr: options.pr } : {}),
+        ...(options.mergeState !== undefined ? { mergeState: options.mergeState } : {}),
+        ...(options.ciStatus !== undefined ? { ciStatus: options.ciStatus } : {}),
+        ...(options.ciConclusion !== undefined ? { ciConclusion: options.ciConclusion } : {}),
+        ...(options.backoffMs !== undefined ? { backoffMs: options.backoffMs } : {}),
+        settled: options.settled === true,
+      });
+    });
+
   addGlobalOptions(program.command("land").description("Land the current branch: verify, regenerate docs, push, pull request, rebase, unblock, squash-merge, release, and milestone"))
     .option("--pr <n>", "Existing pull request number")
     .option("--stage <name>", "Run one stage: verify, docs, push, pr, rebase, unblock, merge, release, or milestone")

package/plugins/kxm/src/mcp-server.ts

@@ -11,7 +11,7 @@ import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 import { sessionTokenFixHint } from "./session-token-hint.ts";
 
-const VERSION = "0.7.170";
+const VERSION = "0.7.172";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();

package/plugins/kxm/src/supervise-state.ts

@@ -0,0 +1,232 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { kxmResourceIdentifier } from "./project-config.ts";
+
+/** First shape of the roadmap supervisor record. An unknown schema is refused
+ * and left on disk. A later shape migrates in this module the way the Runtime
+ * registry copies schema 1 to 2; this file is not a hub database table. */
+export const SUPERVISOR_SCHEMA = "kxm.supervisor.v1";
+
+const TIMESTAMP_RE = /^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]{1,9})?Z$/;
+const MERGE_STATE_RE = /^[A-Z][A-Z0-9_]{0,31}$/;
+const CI_TOKEN_RE = /^[a-z][a-z0-9_-]{0,31}$/;
+const MAX_BACKOFF_MS = 24 * 60 * 60 * 1000;
+
+export interface SupervisorPullRequest {
+  number: number;
+  mergeState: string;
+  seenAt: string;
+}
+
+export interface SupervisorCi {
+  status: string;
+  conclusion: string;
+  seenAt: string;
+}
+
+export interface SupervisorLane {
+  inFlight: boolean;
+  pr?: SupervisorPullRequest;
+  ci?: SupervisorCi;
+  backoffUntil?: string;
+}
+
+export interface SupervisorState {
+  schema: typeof SUPERVISOR_SCHEMA;
+  updatedAt: string;
+  lanes: Record<string, SupervisorLane>;
+}
+
+export interface SupervisorObservation {
+  unit: string;
+  inFlight: boolean;
+  pr?: { number: number; mergeState: string };
+  ci?: { status: string; conclusion: string };
+  /** Set when the caller passed a backoff. Zero clears a stored timer. */
+  backoffMs?: number;
+}
+
+export type SupervisorLoadError = "supervisor_unreadable" | "supervisor_schema_unsupported";
+
+export function supervisorStatePath(stateDir: string): string {
+  return join(stateDir, "supervisor.json");
+}
+
+export function emptySupervisorState(now: string): SupervisorState {
+  return { schema: SUPERVISOR_SCHEMA, updatedAt: now, lanes: {} };
+}
+
+export function isSupervisorTimestamp(value: string): boolean {
+  return TIMESTAMP_RE.test(value) && Number.isFinite(Date.parse(value));
+}
+
+export function resolveSupervisorNow(override: string | undefined, fallback: Date): string | "supervisor_clock_invalid" {
+  if (override === undefined || override.trim() === "") return fallback.toISOString();
+  const text = override.trim();
+  return isSupervisorTimestamp(text) ? text : "supervisor_clock_invalid";
+}
+
+function isPullRequest(value: unknown): value is SupervisorPullRequest {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  if (Object.keys(record).some((key) => key !== "number" && key !== "mergeState" && key !== "seenAt")) return false;
+  return Number.isInteger(record.number) && (record.number as number) > 0
+    && typeof record.mergeState === "string" && MERGE_STATE_RE.test(record.mergeState)
+    && typeof record.seenAt === "string" && isSupervisorTimestamp(record.seenAt);
+}
+
+function isCi(value: unknown): value is SupervisorCi {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  if (Object.keys(record).some((key) => key !== "status" && key !== "conclusion" && key !== "seenAt")) return false;
+  return typeof record.status === "string" && CI_TOKEN_RE.test(record.status)
+    && typeof record.conclusion === "string" && CI_TOKEN_RE.test(record.conclusion)
+    && typeof record.seenAt === "string" && isSupervisorTimestamp(record.seenAt);
+}
+
+function isLane(value: unknown): value is SupervisorLane {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  if (Object.keys(record).some((key) => key !== "inFlight" && key !== "pr" && key !== "ci" && key !== "backoffUntil")) return false;
+  if (typeof record.inFlight !== "boolean") return false;
+  if (record.pr !== undefined && !isPullRequest(record.pr)) return false;
+  if (record.ci !== undefined && !isCi(record.ci)) return false;
+  if (record.backoffUntil !== undefined && (typeof record.backoffUntil !== "string" || !isSupervisorTimestamp(record.backoffUntil))) return false;
+  return true;
+}
+
+function isState(value: unknown): value is SupervisorState {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  if (Object.keys(record).some((key) => key !== "schema" && key !== "updatedAt" && key !== "lanes")) return false;
+  if (record.schema !== SUPERVISOR_SCHEMA) return false;
+  if (typeof record.updatedAt !== "string" || !isSupervisorTimestamp(record.updatedAt)) return false;
+  if (!record.lanes || typeof record.lanes !== "object" || Array.isArray(record.lanes)) return false;
+  for (const [unit, lane] of Object.entries(record.lanes as Record<string, unknown>)) {
+    if (!kxmResourceIdentifier(unit) || !isLane(lane)) return false;
+  }
+  return true;
+}
+
+/** Read `supervisor.json`. A missing file is empty state. A malformed file or
+ * an unknown schema is refused and is not replaced. */
+export function loadSupervisorState(stateDir: string, now: string): SupervisorState | SupervisorLoadError {
+  const path = supervisorStatePath(stateDir);
+  if (!existsSync(path)) return emptySupervisorState(now);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return "supervisor_unreadable";
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return "supervisor_unreadable";
+  const schema = (parsed as { schema?: unknown }).schema;
+  if (schema !== SUPERVISOR_SCHEMA) return "supervisor_schema_unsupported";
+  if (!isState(parsed)) return "supervisor_unreadable";
+  return parsed;
+}
+
+export function saveSupervisorState(stateDir: string, state: SupervisorState): void {
+  const lanes: Record<string, SupervisorLane> = {};
+  for (const unit of Object.keys(state.lanes).sort()) {
+    const lane = state.lanes[unit];
+    if (!lane) continue;
+    const next: SupervisorLane = { inFlight: lane.inFlight };
+    if (lane.pr) next.pr = { number: lane.pr.number, mergeState: lane.pr.mergeState, seenAt: lane.pr.seenAt };
+    if (lane.ci) next.ci = { status: lane.ci.status, conclusion: lane.ci.conclusion, seenAt: lane.ci.seenAt };
+    if (lane.backoffUntil) next.backoffUntil = lane.backoffUntil;
+    lanes[unit] = next;
+  }
+  const body = `${JSON.stringify({ schema: SUPERVISOR_SCHEMA, updatedAt: state.updatedAt, lanes }, null, 2)}\n`;
+  mkdirSync(stateDir, { recursive: true });
+  const path = supervisorStatePath(stateDir);
+  const temporary = `${path}.tmp`;
+  writeFileSync(temporary, body, { encoding: "utf8", mode: 0o600 });
+  renameSync(temporary, path);
+  try { chmodSync(path, 0o600); } catch { /* Windows may not expose POSIX modes. */ }
+}
+
+export function applyObservation(
+  state: SupervisorState,
+  observation: SupervisorObservation,
+  now: string,
+): SupervisorState | "lane_unit_invalid" | "supervisor_pr_invalid" | "supervisor_ci_invalid" | "supervisor_backoff_invalid" {
+  if (!kxmResourceIdentifier(observation.unit)) return "lane_unit_invalid";
+  if (!isSupervisorTimestamp(now)) return "supervisor_backoff_invalid";
+  if (observation.pr) {
+    if (!Number.isInteger(observation.pr.number) || observation.pr.number <= 0 || !MERGE_STATE_RE.test(observation.pr.mergeState)) {
+      return "supervisor_pr_invalid";
+    }
+  }
+  if (observation.ci) {
+    if (!CI_TOKEN_RE.test(observation.ci.status) || !CI_TOKEN_RE.test(observation.ci.conclusion)) return "supervisor_ci_invalid";
+  }
+  if (observation.backoffMs !== undefined) {
+    if (!Number.isInteger(observation.backoffMs) || observation.backoffMs < 0 || observation.backoffMs > MAX_BACKOFF_MS) {
+      return "supervisor_backoff_invalid";
+    }
+  }
+  const prior = state.lanes[observation.unit];
+  const next: SupervisorLane = { inFlight: observation.inFlight };
+  if (observation.pr) next.pr = { number: observation.pr.number, mergeState: observation.pr.mergeState, seenAt: now };
+  else if (prior?.pr) next.pr = { ...prior.pr };
+  if (observation.ci) next.ci = { status: observation.ci.status, conclusion: observation.ci.conclusion, seenAt: now };
+  else if (prior?.ci) next.ci = { ...prior.ci };
+  if (observation.backoffMs === undefined) {
+    if (prior?.backoffUntil) next.backoffUntil = prior.backoffUntil;
+  } else if (observation.backoffMs > 0) {
+    next.backoffUntil = new Date(Date.parse(now) + observation.backoffMs).toISOString();
+  }
+  return {
+    schema: SUPERVISOR_SCHEMA,
+    updatedAt: now,
+    lanes: { ...state.lanes, [observation.unit]: next },
+  };
+}
+
+export interface SupervisorTick {
+  state: SupervisorState;
+  resumed: string[];
+  waiting: string[];
+}
+
+/** Keep every lane. A backoff that has elapsed is cleared so the lane can be
+ * acted on again. A backoff still in the future is left untouched. */
+export function resumeTick(state: SupervisorState, now: string): SupervisorTick {
+  const nowMs = Date.parse(now);
+  const lanes: Record<string, SupervisorLane> = {};
+  const resumed: string[] = [];
+  const waiting: string[] = [];
+  for (const unit of Object.keys(state.lanes).sort()) {
+    const lane = state.lanes[unit];
+    if (!lane) continue;
+    const until = lane.backoffUntil === undefined ? undefined : Date.parse(lane.backoffUntil);
+    const next: SupervisorLane = { inFlight: lane.inFlight };
+    if (lane.pr) next.pr = { ...lane.pr };
+    if (lane.ci) next.ci = { ...lane.ci };
+    if (until !== undefined && until > nowMs && lane.backoffUntil !== undefined) {
+      next.backoffUntil = lane.backoffUntil;
+      waiting.push(unit);
+    } else if (until !== undefined) {
+      resumed.push(unit);
+    }
+    lanes[unit] = next;
+  }
+  return {
+    state: { schema: SUPERVISOR_SCHEMA, updatedAt: now, lanes },
+    resumed,
+    waiting,
+  };
+}
+
+export function formatTickLine(now: string, resumed: readonly string[], waiting: readonly string[]): string {
+  const clock = now.slice(11, 16);
+  if (resumed.length === 0 && waiting.length === 0) {
+    return `[supervisor]: no change. No action. - (${clock})`;
+  }
+  const parts: string[] = [];
+  if (resumed.length > 0) parts.push(`resumed ${resumed.join(", ")}`);
+  if (waiting.length > 0) parts.push(`waiting ${waiting.join(", ")}`);
+  const acted = resumed.length > 0 ? `Acted: resume ${resumed.join(", ")}` : "No action";
+  return `[supervisor]: ${parts.join("; ")}. ${acted}. - (${clock})`;
+}