omp-conductor 0.19.7 → 0.20.1

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,15 +19,23 @@ 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,
   deriveChangedLine,
 } from "./diff-flags.ts";
-import { SPINNING_CAP_CLASSES, classifyRun, normalise, type ClassifyFacts } from "./failure-class.ts";
+import {
+  SPINNING_CAP_CLASSES,
+  COMPOSE_DEPENDENCY_STARTUP_SIGNATURE,
+  classifyRun,
+  normalise,
+  type ClassifyFacts,
+} from "./failure-class.ts";
 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 +94,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 +598,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
@@ -1513,6 +1564,26 @@ export async function classifyAndRecover(d: SettlementDeps): Promise<number> {
           if (firstFailure?.link !== undefined) {
             facts.failingLog = await tracker.checkLog(firstFailure.link);
           }
+          // A Compose dependency-startup failure ("docker compose up" aborted
+          // because a dependency container failed its healthcheck) is only
+          // outside the diff when the PR touched no container configuration —
+          // a PR that breaks its own `docker-compose.yml` produces this exact
+          // sentence and must still charge its attempt (#1059). So the
+          // classifier needs the PR's changed-file list, derived from the
+          // diff this settlement already knows how to fetch
+          // (`Tracker.prDiff`, the same call the settlement audit uses) —
+          // one fetch, and only for a row whose log actually carries
+          // Compose's sentence; every other row pays nothing. A diff that
+          // cannot be read or was cut short (`truncated`) stays undefined: an
+          // unknown list must never waive an attempt.
+          if (
+            facts.failingLog !== undefined &&
+            facts.failingLog.toLowerCase().includes(COMPOSE_DEPENDENCY_STARTUP_SIGNATURE)
+          ) {
+            const diff = await tracker.prDiff(run.prUrl);
+            facts.changedFiles =
+              diff === undefined || diff.truncated ? undefined : diff.files.map((f) => f.path);
+          }
         }
       }
     } catch (err) {
@@ -1631,7 +1702,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 +1747,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 +1778,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 +1946,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;
@@ -1945,10 +2016,14 @@ async function recoverRun(
     return;
   }
 
-  // `hold` (orphan-dirty) and `none`: recorded, nothing performed. The existing
-  // unsalvaged-WIP admission hold already fails dispatch closed until an
-  // operator acknowledges the tree, which is the only safe move when the
-  // worktree holds the only copy of real work.
+  // `observe` (awaiting-observation), `hold` (orphan-dirty) and `none`:
+  // recorded, nothing performed here. `observe`'s recovery IS the later observation —
+  // the settle sweep re-offers the blocked row until its PR resolves and settles it
+  // the way it settles `settlement-stuck`, so no action exists to perform today and
+  // `recoveredAt` stays NULL by design (#1068). The existing unsalvaged-WIP
+  // admission hold already fails dispatch closed until an operator acknowledges
+  // the tree, which is the only safe move when the worktree holds the only copy
+  // of real work.
 }
 
 /**
@@ -2049,7 +2124,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 +2135,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 };
 }