omp-conductor 0.19.7 → 0.20.0

package/src/ready-gate.ts

@@ -0,0 +1,267 @@
+/**
+ * The ready gate (#1040, #1041): the one pure answer to "may this durable
+ * PROMOTABLE verdict become a queue label without a human looking at it".
+ *
+ * Promotion used to be an orchestrator act, so the checks that made it safe
+ * lived wherever the act happened — the lane comparison inside the promotion
+ * verb (#1036), the rest in the orchestrator's own judgement. Phase 2 makes
+ * promotion mechanical: the daemon promotes a passing verdict itself and wakes
+ * dispatch, and the tick audits afterwards. A judgement that is about to run
+ * without a reader has to be one function, testable in isolation, and it has
+ * to name everything it refuses for — a gate that reports only the first
+ * problem turns one grooming pass into four.
+ *
+ * Pure and IO-free on purpose. The caller supplies the issue text, its comment
+ * thread and its labels; the gate reads nothing, fetches nothing and has no
+ * clock. That is what lets the same function run inside the promotion verb
+ * (which already read the issue for its lane echo) and inside the daemon's
+ * grooming pass (which has the snapshot in hand) without either growing a
+ * second copy of the policy.
+ *
+ * Fail-closed, unlike admission. Admission fails *open* on a lane it cannot
+ * parse — it must never refuse work for wanting a declaration, because a
+ * human queued that work deliberately. Nothing here was queued by a human, so
+ * every unknown is a refusal: an unreadable issue, a write-lane heading that
+ * parsed to nothing, a routing label that resolves nowhere. The failure mode
+ * of a fail-open promotion gate is dispatching a worker at an unverified
+ * brief, which is exactly the incident (#1036) that produced the lane
+ * comparison in the first place.
+ */
+
+import { effectiveLane, writeLaneSectionHeading } from "./admission.ts";
+import { repoSlugFor } from "./gitops.ts";
+import type { ToSpecResult } from "./to-spec.ts";
+import type { IssueComment, ProjectConfig } from "./types.ts";
+
+/**
+ * Everything the gate judges, and nothing it could fetch itself.
+ *
+ * `comments` distinguishes "the thread is empty" from "the thread could not be
+ * read": behind a durable promotable verdict the second is a refusal, not an
+ * empty lane (#1036). `"unread"` means the whole read failed — body included —
+ * so the gate reports that and stops rather than judging a blank issue.
+ */
+export interface ReadyGateInput {
+  result: ToSpecResult;
+  issueBody: string;
+  comments: readonly IssueComment[] | "unread";
+  labels: readonly string[];
+  project: ProjectConfig;
+}
+
+/** Pass, or every element that is missing — one short human-readable reason
+ *  each, in a fixed order, so a refusal reads the same twice. */
+export type ReadyGateVerdict = { ok: true } | { ok: false; missing: string[] };
+
+/**
+ * The acceptance-criteria section of an issue: the heading plus the contiguous
+ * bullet run beneath it. Deliberately the same grammar as admission's
+ * write-lane section ({@link writeLaneSectionHeading}) — a `##`-to-`######`
+ * heading whose text is exactly the section name, optional trailing colon, and
+ * a bullet run that any non-bullet line ends. One discipline for both sections
+ * means an issue that renders correctly for one renders correctly for both.
+ *
+ * It lives here rather than in admission.ts because admission has no business
+ * with acceptance criteria: it gates dispatch on lanes and budgets, and a
+ * human-queued issue without checkable criteria is still dispatched. Only
+ * mechanical promotion needs to know.
+ *
+ * Returns `undefined` when there is no such heading, and an empty `criteria`
+ * when the heading is there but nothing checkable is under it — the two are
+ * different refusals.
+ */
+export function acceptanceCriteriaSection(text: string): { heading: string; criteria: string[] } | undefined {
+  const lines = text.split("\n");
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^[ \t]*#{1,6}[ \t]+acceptance[-\s]criteria[ \t]*[:.]?[ \t]*$/i.test(lines[i]!)) {
+      start = i;
+      break;
+    }
+  }
+  if (start < 0) return undefined;
+  const criteria: string[] = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (line.trim() === "") continue;
+    // A markdown bullet marker (`- `, `* `, `+ `, `1. `), with an optional task
+    // checkbox — the shape GitHub renders as a checklist. Anything else ends
+    // the run, so a caveat paragraph or the next section bounds the section.
+    const marker = line.match(/^[ \t]*(?:[-*+]|\d+[.)])[ \t]+(?:\[[ xX]\][ \t]+)?/);
+    if (marker === null) break;
+    const rest = line.slice(marker[0].length).trim();
+    if (rest.length > 0) criteria.push(rest);
+  }
+  return { heading: lines[start]!.trim(), criteria };
+}
+
+/** Trimmed non-empty strings out of a value the type system claims is a string
+ *  array. Defensive because the gate is the last thing between a hand-edited
+ *  store row and a dispatched worker: a malformed field is a refusal, never a
+ *  throw. */
+function strings(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  const out: string[] = [];
+  for (const item of value) {
+    if (typeof item !== "string") continue;
+    const trimmed = item.trim();
+    if (trimmed.length > 0) out.push(trimmed);
+  }
+  return out;
+}
+
+/**
+ * May this verdict be promoted mechanically?
+ *
+ * Every check is one named miss. The order is fixed — verdict, readability,
+ * acceptance criteria, write lane, proof commands, sizing evidence,
+ * dependencies, premise, routing, state labels — so the same input always
+ * produces the same list and a digest line is stable across ticks.
+ *
+ * Two checks short-circuit, because everything after them would be noise: a
+ * verdict that is not PROMOTABLE is not a partly-ready spec, and an unreadable
+ * issue tells you nothing about criteria, lanes or labels.
+ */
+export function readyGate(input: ReadyGateInput): ReadyGateVerdict {
+  const { result, project } = input;
+
+  if (result.verdict !== "PROMOTABLE") {
+    return {
+      ok: false,
+      missing: [`the durable verdict is ${result.verdict}, and only PROMOTABLE may be promoted mechanically`],
+    };
+  }
+  if (input.comments === "unread") {
+    return {
+      ok: false,
+      missing: [
+        "the issue could not be read, so neither its acceptance criteria nor its write lane can be compared with the verdict",
+      ],
+    };
+  }
+
+  const body = typeof input.issueBody === "string" ? input.issueBody : "";
+  const comments = [...input.comments];
+  const missing: string[] = [];
+
+  // Acceptance criteria may arrive in the body or later in the thread — the
+  // same two surfaces the lane declaration reads. Presence is the bar: a gate
+  // cannot judge whether a criterion is a good one, only whether the worker
+  // will be handed something to check itself against.
+  const sections = [body, ...comments.map((comment) => comment.body)]
+    .map((text) => acceptanceCriteriaSection(text))
+    .filter((section) => section !== undefined);
+  // A later section with real bullets beats an earlier empty one; an empty one
+  // is still reported (as its own miss) when nothing better exists.
+  const criteria = sections.find((section) => section.criteria.length > 0) ?? sections[0];
+  if (criteria === undefined) {
+    missing.push(
+      "no acceptance-criteria section: add an `## Acceptance criteria` heading with one checkable bullet per criterion",
+    );
+  } else if (criteria.criteria.length === 0) {
+    missing.push(
+      `the acceptance-criteria section (${criteria.heading}) has no bullets under it, so the worker has nothing to check itself against`,
+    );
+  }
+
+  // The lane admission will enforce, against the lane the verdict was computed
+  // over — exact in both directions, order-insensitive (#1036). Both sides go
+  // through `strings` so they dedupe and trim in lockstep: a set comparison
+  // whose halves normalize differently lies silently.
+  //
+  // A write-lane heading that parsed nothing gets its own miss rather than
+  // reading as an empty lane. Admission fails open on exactly this shape
+  // (#825) because it must never refuse human-queued work; a mechanical
+  // promotion has no such excuse, and the actionable fact is the syntax, not
+  // the set difference.
+  const verdictLane = [...new Set(strings(result.fileLane))].sort();
+  const lane = effectiveLane(body, comments);
+  const heading =
+    lane !== undefined
+      ? undefined
+      : (writeLaneSectionHeading(body) ??
+        comments.map((comment) => writeLaneSectionHeading(comment.body)).find((found) => found !== undefined));
+  if (verdictLane.length === 0) {
+    // The schema requires at least one path, so this is a hand-edited or
+    // corrupt row. An empty lane on both sides would otherwise *match*, and
+    // match into a dispatch with nothing to serialise concurrent work on.
+    missing.push("the verdict names no file lane, so admission would have nothing to serialise concurrent work on");
+  } else if (heading !== undefined) {
+    missing.push(
+      `the write-lane section (${heading}) parsed no path-like files — name them as backticked bullets directly under the heading`,
+    );
+  } else {
+    const declared = lane === undefined ? [] : [...new Set(strings(lane.files))].sort();
+    if (declared.length !== verdictLane.length || declared.some((path, index) => path !== verdictLane[index])) {
+      missing.push(
+        `the issue's write lane [${declared.join(", ")}] disagrees with the verdict's file lane [${verdictLane.join(", ")}]`,
+      );
+    }
+  }
+
+  if (strings(result.proofCommands).length === 0) {
+    missing.push("the verdict names no proof commands, so nothing would prove the work");
+  }
+  if (typeof result.sizingEvidence !== "string" || result.sizingEvidence.trim().length === 0) {
+    missing.push(
+      "the verdict carries no sizingEvidence: the one-budget claim has nothing behind it that could falsify it (#1041)",
+    );
+  }
+
+  const dependencies = Array.isArray(result.dependencies)
+    ? result.dependencies.filter((dep) => typeof dep === "number" || (typeof dep === "string" && dep.trim().length > 0))
+    : [];
+  if (dependencies.length > 0) {
+    missing.push(`open prerequisites are still named: ${dependencies.join(", ")}`);
+  }
+  // A verdict that says later work retired the premise cannot also be a
+  // promotion: the schema allows the combination because a groomer may want to
+  // record what it found, and nothing else reads it (#883). Mechanically,
+  // promoting it dispatches a worker at work the verdict itself disowned.
+  if (result.laterWorkInvalidates) {
+    missing.push("the verdict reports that later work invalidated the candidate's premise, so it must be re-groomed, not promoted");
+  }
+
+  const { labelPrefix, repos } = project.routing;
+  const labels = strings(input.labels);
+  const matched = [...new Set(labels.filter((label) => label.startsWith(labelPrefix)))];
+  if (matched.length === 0) {
+    missing.push(`no ${labelPrefix}* routing label, so dispatch could not pick a checkout`);
+  } else if (matched.length > 1) {
+    missing.push(`${matched.length} routing labels (${matched.join(", ")}) — exactly one is routable`);
+  } else {
+    const key = matched[0]!.slice(labelPrefix.length);
+    // hasOwn, not truthiness: a `repo:constructor` label would otherwise
+    // resolve off Object.prototype and route work into a bogus target
+    // (routing.ts:route).
+    if (!Object.hasOwn(repos, key)) {
+      const known = Object.keys(repos).map((name) => `${labelPrefix}${name}`).join(", ");
+      missing.push(`routing label ${matched[0]} names no repository ${project.name} routes (${known || "none"})`);
+    } else {
+      const slug = repoSlugFor(repos[key]!);
+      if (slug !== result.routing) {
+        missing.push(
+          result.routing === "MULTI"
+            ? `the verdict routes to MULTI, a split across repositories that no single ${labelPrefix}* label can carry — file the split as children first`
+            : `routing label ${matched[0]} routes to ${slug}, but the verdict routed this work to ${result.routing}`,
+        );
+      }
+    }
+  }
+
+  // The queue label is about to land, so the gate owes the other half of
+  // eligibility (routing.ts:isEligible): a state label already on the issue
+  // would make the promotion a no-op the daemon silently skips, and the park
+  // label beats the queue label outright (#734).
+  const { inProgress, blocked, failed, backlog } = project.stateLabels;
+  const held = [inProgress, blocked, failed, backlog].filter(
+    // The typeof guard is runtime armour, not typing: an older config file can
+    // reach here without every state label set.
+    (label) => typeof label === "string" && label.length > 0 && labels.includes(label),
+  );
+  if (held.length > 0) {
+    missing.push(`the issue still carries ${held.join(", ")}, which would keep it ineligible once the queue label lands`);
+  }
+
+  return missing.length === 0 ? { ok: true } : { ok: false, missing };
+}

package/src/settlement.ts

@@ -19,6 +19,7 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { log, errText, safeEscalate } from "./log.ts";
 import { hasContinuationBudget } from "./admission.ts";
+import { appendKnowledge } from "./knowledge.ts";
 import {
   UNREADABLE_TREE_FLAG,
   analyseSettlement,
@@ -28,6 +29,7 @@ import { SPINNING_CAP_CLASSES, classifyRun, normalise, type ClassifyFacts } from
 import { GhPrMissingError } from "./tracker/github.ts";
 import { formatModelsTried, modelsTried } from "./model-fallback.ts";
 import { PR_LOOKUP_WINDOW_MS } from "./decisions.ts";
+import { wakeDispatch } from "./wake.ts";
 import {
   removeWorktree,
   salvageWip,
@@ -86,6 +88,14 @@ export interface SettlementDeps {
     provenance: { source: string; reason?: string },
     project?: string,
   ): void;
+  /**
+   * The dispatch wake fired after a queue-label hand-back (#1041). Production
+   * leaves it absent and {@link swapToQueue} calls the real loopback client;
+   * a test injects a spy, which is the only way to prove the wake fires — the
+   * mutation it follows already committed, so nothing about the store or the
+   * outbox records whether dispatch was woken.
+   */
+  wake?: (projectName: string) => Promise<string>;
 }
 
 /** What the settlement audit of one green run produced: the advisory flags
@@ -582,6 +592,41 @@ export function recordOperatorStop(
   ]);
 }
 
+/**
+ * File a settled worker's reported discoveries into the per-repo knowledge
+ * overlay (Phase 3 inner loop).
+ *
+ * The overlay exists because everything a worker learns about a repo — the real
+ * entry point, the gate that actually proves the change, the fake that looks
+ * like a test — used to die with its run row, so the next worker on the same
+ * repo rediscovered it at the cost of turns. `discoveries` is an optional field
+ * on the worker's own structured settlement, so a run that reports none appends
+ * nothing.
+ *
+ * A knowledge write can never fail a settlement, and that is the whole reason
+ * this is a function rather than an inline call: the settle path is what makes a
+ * run's outcome durable, and losing an outcome because an advisory markdown file
+ * could not be written would trade the fleet's record for a note. `appendKnowledge`
+ * already swallows its own IO faults; the catch here covers everything else
+ * (a path that cannot be resolved, a caller-supplied value that surprises it)
+ * so no future change to that module can reach back and break a settle.
+ */
+export function recordWorkerDiscoveries(
+  repo: string,
+  issue: number,
+  discoveries: readonly string[] | undefined,
+  at = Date.now(),
+): void {
+  if (discoveries === undefined || discoveries.length === 0) return;
+  try {
+    appendKnowledge(repo, discoveries, { issue, at });
+    const n = discoveries.length;
+    log(`#${issue} recorded ${n} repo ${n === 1 ? "discovery" : "discoveries"} into the ${repo} knowledge overlay`);
+  } catch (err) {
+    log(`#${issue} repo knowledge for ${repo} was not updated: ${errText(err)}`);
+  }
+}
+
 /**
  * What a salvage attempt contributes to the escalation: where the work went, or
  * that it went nowhere. Split from the effects below for the same reason
@@ -1631,7 +1676,7 @@ async function recoverRun(
       }
       const continuation = store.continuationsFor(project.name, run.issue);
       if (hasContinuationBudget(continuation, caps.maxContinuationsPerIssue)) {
-        swapToQueue(d, run.issue, project.stateLabels.failed);
+        await swapToQueue(d, run.issue, project.stateLabels.failed);
         store.updateRun(run.id, { recoveredAt: Date.now() });
         log(`#${run.issue} requeued for a wall-clock continuation: ${evidence}`);
       } else {
@@ -1676,7 +1721,7 @@ async function recoverRun(
       }
       const continuation = store.continuationsFor(project.name, run.issue);
       if (hasContinuationBudget(continuation, caps.maxContinuationsPerIssue)) {
-        swapToQueue(d, run.issue, project.stateLabels.failed);
+        await swapToQueue(d, run.issue, project.stateLabels.failed);
         store.updateRun(run.id, { recoveredAt: Date.now() });
         log(`#${run.issue} requeued after a provider empty-stop: ${evidence}`);
         return;
@@ -1707,7 +1752,7 @@ async function recoverRun(
     // recovery; the projector retries until the tracker takes the swap, and
     // while it is pending the eligibility overlay keeps the issue coherent
     // (#201).
-    swapToQueue(d, run.issue, inProgress);
+    await swapToQueue(d, run.issue, inProgress);
     store.updateRun(run.id, {
       state: "killed",
       lastError:
@@ -1875,7 +1920,7 @@ async function recoverRun(
       }
     }
     const label = cls === "orphan-clean" ? inProgress : project.stateLabels.failed;
-    swapToQueue(d, run.issue, label);
+    await swapToQueue(d, run.issue, label);
     store.updateRun(run.id, { recoveredAt: Date.now() });
     log(`#${run.issue} requeued from ${cls}: ${evidence}`);
     return;
@@ -2049,7 +2094,8 @@ async function escalateModelTier(
 }
 
 /**
- * Enqueue a state-label → queue-label swap for projection (#201).
+ * Enqueue a state-label → queue-label swap for projection (#201), then wake
+ * dispatch (#1041).
  *
  * The swap is two ops in id order — remove first, then add — which is the
  * atomicity the projector guarantees: the issue never sits newly eligible
@@ -2059,12 +2105,32 @@ async function escalateModelTier(
  * immediately and the projector retries the swap until the tracker takes it —
  * that closes the 0.4.4 hole where a refused label swap stranded the row
  * permanently under a log line promising a retry.
+ *
+ * The wake is why this is the chokepoint every requeue goes through. A
+ * continuation handed its queue label back and then waiting out the five-minute
+ * interval reads, from outside, exactly like a stalled queue — the same
+ * complaint #878 fixed for `unblock` and `resume`, on the paths that never
+ * used it. It runs AFTER the enqueue, never before: the wake shortens a sleep
+ * and the pass it prompts re-reads every gate, so a wake that arrives before
+ * the durable write would simply find nothing. And it can never fail the
+ * requeue — the label ops are already committed, the client answers a line for
+ * every outcome including "no daemon", and a thrown seam is logged as the
+ * degradation it is: the next scheduled pass claims.
  */
-export function swapToQueue(d: Pick<SettlementDeps, "project" | "store">, issue: number, label: string): void {
+export async function swapToQueue(
+  d: Pick<SettlementDeps, "project" | "store" | "wake">,
+  issue: number,
+  label: string,
+): Promise<void> {
   d.store.enqueueLabelOps(d.project.name, [
     { issue, op: "remove", label },
     { issue, op: "add", label: d.project.queueLabel },
   ]);
+  try {
+    log(`#${issue} back on the queue — ${await (d.wake ?? wakeDispatch)(d.project.name)}`);
+  } catch (err) {
+    log(`#${issue} back on the queue but the dispatch wake failed (${errText(err)}) — the next scheduled pass will claim`);
+  }
 }
 
 

package/src/setup-host.ts

@@ -4,7 +4,8 @@ import { homedir, userInfo } from "node:os";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { configPath, loadConfig, resolveCaps, stateDir } from "./config.ts";
 import { isPaused, runDaemon, statusSnapshot, type StatusSnapshot } from "./daemon.ts";
-import { ORCHESTRATOR_BRIEF_NAME } from "./brief-upgrade.ts";
+import { AGENTS_BRIEF_NAME, CONSOLE_BRIEF_NAME, ORCHESTRATOR_BRIEF_NAME } from "./brief-upgrade.ts";
+import { planConsole, writeConsole, type ConsolePlan } from "./setup.ts";
 import {
   DEFAULT_FLEET_AGENT_NAME,
   DEFAULT_HERDR_SESSION,
@@ -108,13 +109,6 @@ export interface HostRetirement {
   steps: readonly PrivilegedStep[];
 }
 
-/**
- * The symlink the session cwd loads as its brief. omp auto-loads `AGENTS.md`
- * from the session cwd, so the fleet pane's cwd needs a link at this name
- * resolving to the composed {@link ORCHESTRATOR_BRIEF_NAME}.
- */
-export const AGENTS_BRIEF_NAME = "AGENTS.md";
-
 export type PlannedWrite<T> = {
   path: string;
   action: "create" | "update" | "keep";
@@ -231,6 +225,14 @@ export interface HostRuntimePlan {
   tick?: PlannedWrite<TickConfig>;
   /** The `AGENTS.md` — composed-brief symlink — placed in the fleet cwd. */
   briefLink?: BriefLinkPlan;
+  /**
+   * The operator console's workspace: its own cwd under the state root, the
+   * rendered console floor, and the `AGENTS.md` link that makes the session
+   * load it. Planned per project like {@link briefLink}, and deliberately
+   * carrying no tick config — the console cwd must stay a directory the tick
+   * extension cannot activate in.
+   */
+  console?: ConsolePlan;
   /**
    * Set when an install ran with no project named (a host-global install):
    * the per-project tail was deliberately not written. Names the files and
@@ -1710,12 +1712,16 @@ export function planHostRuntime(
           // Host-global install: the per-project tail entities are not written,
           // and the plan says exactly which files and how to write them.
           noProject: {
-            skipped: [TICK_CONFIG_FILE, AGENTS_BRIEF_NAME],
+            skipped: [TICK_CONFIG_FILE, AGENTS_BRIEF_NAME, CONSOLE_BRIEF_NAME],
             how: "re-run `omp-conductor setup host <NAME>` (or --project NAME) to write them for one project",
           },
         }
       : {
           briefLink: planBriefLink(project),
+          // The console workspace is per-project like the brief link, and
+          // planned for every project — embedded or external. An embedded
+          // orchestrator still has an operator to answer.
+          console: planConsole(project),
           ...(project.escalation.orchestrator === "external"
             ? (() => {
                 const planned = planTick(project, telegramStateDir);
@@ -1802,6 +1808,14 @@ export function formatHostRuntimePlan(plan: HostRuntimePlan): string {
         : `  brief link     ${plan.briefLink.action} ${plan.briefLink.path} -> ${plan.briefLink.target}`,
     );
   }
+  if (plan.console !== undefined) {
+    lines.push(
+      `  console brief  ${plan.console.brief.action} ${plan.console.brief.path}`,
+      plan.console.link.action === "skip"
+        ? `  console link   ${plan.console.link.path} — ${plan.console.link.skippedReason}`
+        : `  console link   ${plan.console.link.action} ${plan.console.link.path} -> ${plan.console.link.target}`,
+    );
+  }
   lines.push("  install        staged only; the final result prints the systemd install commands");
   return lines.join("\n");
 }
@@ -1894,6 +1908,15 @@ export function writeHostRuntime(plan: HostRuntimePlan): HostRuntimeWrite {
       warnings.push(`could not link ${path} -> ${target}: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
+  // One writer for the console workspace, shared with `omp-conductor console`
+  // (see {@link writeConsole}): a second copy of the never-clobber link
+  // discipline is a second place for it to be got wrong. Warnings come back
+  // rather than throwing, exactly like the brief link above.
+  if (plan.console !== undefined) {
+    const written = writeConsole(plan.console);
+    wrote.push(...written.wrote);
+    warnings.push(...written.warnings);
+  }
   return { wrote, warnings };
 }
 

package/src/setup-wizard.ts

@@ -2147,17 +2147,27 @@ export async function ensureSetupArm(
   projectName: string,
   arm: typeof armTicks = armTicks,
   /**
-   * Where the arm proof's pending heartbeat goes while it waits (#861). Setup
-   * holds dispatch under its own fence across this call, so a silent wait here
-   * is the whole incident: the operator sees a stalled wizard and cannot tell
-   * a live handshake from a dead process.
+   * Where the ceremony's one line goes. Setup holds dispatch under its own
+   * fence across this call, so the send receipt has to be visible: an operator
+   * who sees nothing cannot tell a sent challenge from a stalled wizard (#861).
    */
   progress?: (line: string) => void,
 ): Promise<string> {
-  const armed = await arm(projectName, progress === undefined ? {} : { progress });
+  const result = await arm(projectName, progress === undefined ? {} : { progress });
+  // Arming is two steps now: the wizard can send the challenge, but only the
+  // operator's reply arms the heartbeat, and that reply lands in the console
+  // session rather than here. Reporting "armed" off a sent challenge would be a
+  // lie the operator only discovers when no tick ever fires.
+  if (result.outcome === "challenge-sent") {
+    return (
+      `arming challenge sent to owner ${result.owner}, valid for ${result.validFor} — NOT yet armed. ` +
+      `Finish it with: ${result.followUp}`
+    );
+  }
+  const armed = result.armed[0]!;
   return armed.alreadyArmed
-    ? `existing heartbeat arm revalidated for owner ${armed.owner} at ${armed.path}`
-    : `heartbeat armed for owner ${armed.owner} at ${armed.path}`;
+    ? `existing heartbeat arm revalidated for owner ${result.owner} at ${armed.path}`
+    : `heartbeat armed for owner ${result.owner} at ${armed.path}`;
 }
 
 /**
@@ -2608,6 +2618,12 @@ interface SetupInventory {
   runtime: CapturedPathState[];
   /** The AGENTS.md brief link the apply will create/update, when planned. */
   briefLink?: CapturedPathState;
+  /** The console floor and its AGENTS.md link, when the apply will write them.
+   *  Captured separately from {@link runtime} because the link is a symlink and
+   *  restores as one — and because a half-applied console left behind after a
+   *  failed apply is a session pointing at a brief this transaction rolled back. */
+  consoleBrief?: CapturedPathState;
+  consoleLink?: CapturedPathState;
   /** The run store: byte-consistent snapshot when it exists, absence on a first install. */
   store: StoreCapture;
   /** The daemon pidfile record the smoke/restart legs write. */
@@ -2690,6 +2706,18 @@ function captureInventory(
     (plan.runtime.briefLink.action === "create" || plan.runtime.briefLink.action === "update")
       ? capturePathState(plan.runtime.briefLink.path)
       : undefined;
+  // The console workspace: same "only what will be written" rule, and the link
+  // is captured only when the plan will touch it — a `skip` is an operator's
+  // own file the apply never writes, so it has no pre-entry state to restore.
+  const consoleBrief =
+    plan.runtime.console !== undefined && plan.runtime.console.brief.action !== "keep"
+      ? capturePathState(plan.runtime.console.brief.path)
+      : undefined;
+  const consoleLink =
+    plan.runtime.console !== undefined &&
+    (plan.runtime.console.link.action === "create" || plan.runtime.console.link.action === "update")
+      ? capturePathState(plan.runtime.console.link.path)
+      : undefined;
   const record = capturePathState(recordPath());
   const armMarker =
     plan.project.escalation.orchestrator === "external"
@@ -2702,6 +2730,8 @@ function captureInventory(
     ...briefs,
     ...runtime,
     ...(briefLink === undefined ? [] : [briefLink]),
+    ...(consoleBrief === undefined ? [] : [consoleBrief]),
+    ...(consoleLink === undefined ? [] : [consoleLink]),
     record,
     ...(armMarker === undefined ? [] : [armMarker]),
   ];
@@ -2719,6 +2749,9 @@ function captureInventory(
   const dirs = new Set<string>();
   if (answers.writeOrchestratorBrief) dirs.add(dirname(briefPathForProject(plan.project)));
   if (briefLink !== undefined) dirs.add(dirname(briefLink.path));
+  // The console cwd, created by the brief write or the link.
+  if (consoleBrief !== undefined) dirs.add(dirname(consoleBrief.path));
+  if (consoleLink !== undefined) dirs.add(dirname(consoleLink.path));
   if (plan.runtime.tick !== undefined && plan.runtime.tick.action !== "keep") {
     dirs.add(dirname(plan.runtime.tick.path));
   }
@@ -2729,6 +2762,8 @@ function captureInventory(
     briefs,
     runtime,
     ...(briefLink === undefined ? {} : { briefLink }),
+    ...(consoleBrief === undefined ? {} : { consoleBrief }),
+    ...(consoleLink === undefined ? {} : { consoleLink }),
     store: captureStore(dbPath()),
     record,
     ...(armMarker === undefined ? {} : { armMarker }),
@@ -2794,6 +2829,11 @@ async function restoreInventory(
   // operator's regular file that appeared mid-flight survives — reported as a
   // failure, because the prior state is then not coherent.
   restore(inventory.briefLink, { preserveRegularFile: true });
+  // The console floor, then its link, on the same terms: the floor is an
+  // ordinary file, and the link is a symlink that never displaces a regular
+  // file that appeared mid-flight.
+  restore(inventory.consoleBrief);
+  restore(inventory.consoleLink, { preserveRegularFile: true });
 
   // The run store: replace from the byte-consistent snapshot (or remove it
   // entirely on a first-install rollback).
@@ -3195,6 +3235,14 @@ export async function setup(
           : d.runtime.briefLink.action === "keep"
             ? `Keeps the brief link at ${d.runtime.briefLink.path}.`
             : `${d.runtime.briefLink.action === "create" ? "Creates" : "Replaces"} the brief link at ${d.runtime.briefLink.path} -> ${d.runtime.briefLink.target}.`,
+      // The console workspace is a mutation like the rest, so consent names it:
+      // an operator who picked "Apply" must have been told a second session's
+      // cwd and brief appear under the state root.
+      d.runtime.console === undefined
+        ? ""
+        : d.runtime.console.brief.action === "keep"
+          ? `Keeps the operator console brief at ${d.runtime.console.brief.path}.`
+          : `${d.runtime.console.brief.action === "create" ? "Creates" : "Updates"} the operator console workspace at ${d.runtime.console.cwd} (its brief, and an AGENTS.md link to it).`,
       answers.writeOrchestratorBrief
         ? `Writes ${orchestratorBriefPath(answers)}, which is then yours to edit.`
         : "",