omp-conductor 0.19.7 → 0.20.1

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.`
         : "",

package/src/setup.ts

@@ -21,12 +21,14 @@
  * `src/gh.ts` exposing `gh()` (throwing) over `ghTry()` (classifying).
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, relative } from "node:path";
 import { parse as parseYaml } from "yaml";
 import {
+  AGENTS_BRIEF_NAME,
   COMPOSE_BANNER,
+  CONSOLE_BRIEF_NAME,
   ORCHESTRATOR_BRIEF_NAME,
   POLICY_BRIEF_NAME,
   composeOrchestrator,
@@ -51,6 +53,7 @@ import {
 } from "./config.ts";
 import { graphProjectPath, graphRepos } from "./graph.ts";
 import { modelRolesIn, ompSettingsOverlay } from "./omp-settings.ts";
+import { shellQuote } from "./shell.ts";
 import {
   CONFIG_VERSION,
   DEFAULT_ARM_PROOF,
@@ -168,6 +171,12 @@ export interface SetupAnswers {
    * to survive an amend of some other area (#369).
    */
   groomBelow?: GroomTrigger;
+  /**
+   * The OMP model role the daemon's own grooming scouts run under (#1041).
+   * Hand-edited like {@link groomBelow} — the wizard never asks — so it exists
+   * here only to survive an amend of some other area (#369).
+   */
+  groomRole?: string;
   /**
    * Ordered fallback worker models and the provider-failure threshold that
    * starts them. The wizard never asks for either — they are hand-edited —
@@ -583,7 +592,7 @@ export const PROMOTION_DUTIES: { readonly [K in AuthorityHolder]: string } = {
     "operator can take it back by editing this paragraph.",
 };
 
-export { ORCHESTRATOR_BRIEF_NAME, POLICY_BRIEF_NAME };
+export { AGENTS_BRIEF_NAME, CONSOLE_BRIEF_NAME, ORCHESTRATOR_BRIEF_NAME, POLICY_BRIEF_NAME };
 
 /** Shipped floor template — duties, tiers, hard boundaries, Learning loop. */
 const ORCHESTRATOR_TEMPLATE_PATH = join(import.meta.dir, "briefs", "orchestrator.md");
@@ -591,6 +600,13 @@ const ORCHESTRATOR_TEMPLATE_PATH = join(import.meta.dir, "briefs", "orchestrator
 /** Shipped POLICY.md scaffold — Releases, Project context, Reporting, Amendments. */
 const POLICY_TEMPLATE_PATH = join(import.meta.dir, "briefs", "policy.md");
 
+/**
+ * Shipped console floor — the operator console's role, delivery contract,
+ * authority and boundaries. Render-only: it has no `POLICY.md` half, is never
+ * composed, and is never classified by `inspectBriefLayout`.
+ */
+const CONSOLE_TEMPLATE_PATH = join(import.meta.dir, "briefs", "console.md");
+
 /**
  * `repo` writes labels and closes issues; `project` moves cards on the board.
  * Both are load-bearing for an unattended loop, so a missing one is reported
@@ -1014,6 +1030,10 @@ export function buildProject(a: SetupAnswers): ProjectConfig {
       : {}),
     // A documented hand-edited key, so an unrelated amend must not delete it.
     ...(a.groomBelow === undefined ? {} : { groomBelow: a.groomBelow }),
+    // Same contract for the daemon's grooming-scout role: hand-edited, and an
+    // amend that dropped it would silently move grooming back to the harness
+    // default model (#1041).
+    ...(a.groomRole === undefined ? {} : { groomRole: a.groomRole }),
     // The failover chain is hand-edited too: dropping it on an unrelated amend
     // would pin every run of the project onto a dead provider again (#286).
     ...(a.modelFallbacks === undefined ? {} : { modelFallbacks: [...a.modelFallbacks] }),
@@ -1256,6 +1276,7 @@ export function answersFromProject(p: ProjectConfig): SetupAnswers {
   // what keeps the rewritten config identical to the one that was read.
   if (p.workerModel !== undefined) answers.workerModel = p.workerModel;
   if (p.groomBelow !== undefined) answers.groomBelow = p.groomBelow;
+  if (p.groomRole !== undefined) answers.groomRole = p.groomRole;
   if (p.modelFallbacks !== undefined) answers.modelFallbacks = [...p.modelFallbacks];
   if (p.modelFallbackThreshold !== undefined) answers.modelFallbackThreshold = p.modelFallbackThreshold;
   if (p.workerEscalationModel !== undefined) answers.workerEscalationModel = p.workerEscalationModel;
@@ -1365,6 +1386,205 @@ export function renderPolicyForProject(p: ProjectConfig): string {
   return renderBriefTemplate(shippedPolicyTemplate(), briefVarsForProject(p));
 }
 
+// ------------------------------------------------------- the operator console
+//
+// The console is the second session of the two-session split: the tick brain
+// keeps its pane and never receives an operator turn, and this one owns the
+// Telegram conversation 24/7. Everything below provisions its workspace, and
+// the whole point of the shape is what it does NOT do:
+//
+//  - **No tick config.** The tick extension activates only when
+//    `.conductor-tick.json` exists in the session cwd, so a console cwd
+//    without one is inert by construction rather than by a runtime check that
+//    could be got wrong. Nothing here ever writes that file.
+//  - **No POLICY.md, no compose, no layout classification.** The floor is
+//    rendered and written; there is no operator half to merge, so
+//    `refreshComposedBrief` and `inspectBriefLayout` never see this file.
+//  - **Derived, never stamped.** The cwd is a function of the state dir and
+//    the project name, in TypeScript here and in the same shape in
+//    `recover.sh`. A config key would be a second copy of the answer, and the
+//    copy nobody updated is the one a pane would `cd` into.
+
+/**
+ * The console session's own directory: `<stateDir>/console/<project>`.
+ *
+ * Under the state root rather than beside the project's worktrees because the
+ * console is a fleet surface, not a checkout — and because a directory the
+ * worker machinery never touches cannot be force-removed by a re-claim.
+ */
+export function consoleCwdForProject(p: ProjectConfig): string {
+  return join(stateDir(), "console", p.name);
+}
+
+/** The rendered console floor inside {@link consoleCwdForProject}. */
+export function consoleBriefPathForProject(p: ProjectConfig): string {
+  return join(consoleCwdForProject(p), CONSOLE_BRIEF_NAME);
+}
+
+/** Shipped console floor template, placeholders and all. */
+export function shippedConsoleTemplate(): string {
+  return readFileSync(CONSOLE_TEMPLATE_PATH, "utf8");
+}
+
+/**
+ * Rendered console floor for a configured project.
+ *
+ * The same `briefVarsForProject` coordinates the orchestrator floor gets, so a
+ * placeholder either template names is filled from one table — a console that
+ * shipped a literal `{{PROJECT}}` to a session would be reading a template,
+ * not a brief.
+ */
+export function renderConsoleForProject(p: ProjectConfig): string {
+  return renderBriefTemplate(shippedConsoleTemplate(), briefVarsForProject(p));
+}
+
+/**
+ * The shell line that launches the console pane, produced here so
+ * `omp-conductor console` and `recover.sh` cannot print two different commands
+ * for one surface.
+ *
+ * `dmOwner` is the Telegram DM force-claim, and it is a host-level judgement,
+ * not a preference: one state dir may have exactly one DM owner, so a host
+ * with several fleet cwds launches its consoles without it and lets inbound
+ * messages arrive by forum-topic routing instead. Nothing else in this package
+ * sets `OMP_TELEGRAM_DM_OWNER`.
+ */
+export function consolePaneCommand(opts: { cwd: string; dmOwner: boolean }): string {
+  // Quoted because the reader copies what a surface prints: a state root under
+  // a path with a space or a `$` must still `cd` where it says.
+  return `cd ${shellQuote(opts.cwd)} && ${opts.dmOwner ? "OMP_TELEGRAM_DM_OWNER=1 " : ""}omp`;
+}
+
+/**
+ * The `AGENTS.md` link in the console cwd and what provisioning will do about
+ * it, with the same never-clobber discipline the fleet pane's link gets: an
+ * already-correct symlink is kept, a stale one is replaced, and a **regular
+ * file** is an operator's own brief — reported and left untouched.
+ */
+export interface ConsoleLinkPlan {
+  path: string;
+  /** Relative target inside the symlink — `CONSOLE.md`, its own directory. */
+  target: string;
+  action: "create" | "update" | "keep" | "skip";
+  /** Why {@link action} is `skip`; present only then. */
+  skippedReason?: string;
+}
+
+/** What provisioning the console workspace will write, before it writes it. */
+export interface ConsolePlan {
+  /** The directory the console pane runs in. Created by the write. */
+  cwd: string;
+  /** The rendered floor: `create` on a fresh cwd, `keep` when already current. */
+  brief: { path: string; content: string; action: "create" | "update" | "keep" };
+  link: ConsoleLinkPlan;
+}
+
+/**
+ * Plans the console workspace for a project. Pure: reads the filesystem,
+ * writes nothing, so `setup host` can show the whole thing before consent and
+ * `omp-conductor console` can report what it did.
+ */
+export function planConsole(p: ProjectConfig): ConsolePlan {
+  const cwd = consoleCwdForProject(p);
+  const briefPath = consoleBriefPathForProject(p);
+  const content = renderConsoleForProject(p);
+  const linkPath = join(cwd, AGENTS_BRIEF_NAME);
+  // Relative, and inside the same directory, so the whole console cwd stays
+  // movable — the same reason the fleet pane's link is relative.
+  const target = relative(dirname(linkPath), briefPath);
+  // An unreadable existing brief is planned as `update`: rewriting it is the
+  // repair, and a plan that reported `keep` on a file it could not read would
+  // leave the console without a floor.
+  let live: string | undefined;
+  try {
+    live = readFileSync(briefPath, "utf8");
+  } catch {
+    live = undefined;
+  }
+  return {
+    cwd,
+    brief: {
+      path: briefPath,
+      content,
+      action: live === undefined ? (existsSync(briefPath) ? "update" : "create") : live === content ? "keep" : "update",
+    },
+    link: planConsoleLink(linkPath, target),
+  };
+}
+
+function planConsoleLink(path: string, target: string): ConsoleLinkPlan {
+  let st;
+  try {
+    st = lstatSync(path);
+  } catch {
+    // ENOENT, and any unreadable parent, both collapse to a best-effort
+    // create; a filesystem that refuses the link surfaces at write time.
+    return { path, target, action: "create" };
+  }
+  if (st.isSymbolicLink()) {
+    return { path, target, action: readlinkSync(path, "utf8") === target ? "keep" : "update" };
+  }
+  return {
+    path,
+    target,
+    action: "skip",
+    skippedReason: `an existing file at ${path} is not ours to overwrite; left untouched`,
+  };
+}
+
+/** What {@link writeConsole} wrote, plus anything it could not. */
+export interface ConsoleWrite {
+  wrote: string[];
+  /** Best-effort failures the caller surfaces; provisioning continues. */
+  warnings: string[];
+}
+
+/**
+ * Materialises a planned console workspace. Idempotent: a `keep` brief and a
+ * `keep` link touch nothing, so re-running `omp-conductor console` or
+ * `setup host` rewrites nothing and reports an empty write.
+ *
+ * The link is re-`lstat`ed here rather than trusted from the plan, because the
+ * entry can change across the consent gap: an operator who drops their own
+ * `AGENTS.md` where a stale symlink was planned for replacement must keep it.
+ */
+export function writeConsole(plan: ConsolePlan): ConsoleWrite {
+  const wrote: string[] = [];
+  const warnings: string[] = [];
+  mkdirSync(plan.cwd, { recursive: true });
+  if (plan.brief.action !== "keep") {
+    writeFileSync(plan.brief.path, plan.brief.content);
+    wrote.push(plan.brief.path);
+  }
+  if (plan.link.action === "create" || plan.link.action === "update") {
+    const { path, target } = plan.link;
+    try {
+      let existing;
+      try {
+        existing = lstatSync(path);
+      } catch {
+        existing = undefined;
+      }
+      if (existing !== undefined && !existing.isSymbolicLink()) {
+        warnings.push(
+          `${path} is a regular file, not ours to overwrite; console AGENTS.md link skipped`,
+        );
+      } else if (existing !== undefined && readlinkSync(path, "utf8") === target) {
+        // Already correct, however the plan read it.
+      } else {
+        if (existing !== undefined) rmSync(path, { force: true });
+        symlinkSync(target, path);
+        wrote.push(path);
+      }
+    } catch (err) {
+      warnings.push(
+        `could not link ${path} -> ${target}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+  return { wrote, warnings };
+}
+
 /**
  * Composed session brief: rendered floor + shared policy (when present) +
  * POLICY scaffold (or a caller's policy).
@@ -1811,6 +2031,12 @@ export function summarisePlan(
       `  ${"cap escalation".padEnd(CAPS_PLAN_KEY_PAD)}${a.workerEscalationModel.trim()}  (hand-edited)`,
     );
   }
+  // The daemon spends real money grooming unattended (#1041), so which role it
+  // spends it under belongs on the plan a human approves — hand-edited, like
+  // the cap-escalation tier above it, and silent when nobody answered.
+  if (a.groomRole !== undefined && a.groomRole.trim().length > 0) {
+    lines.push(`  ${"groom role".padEnd(CAPS_PLAN_KEY_PAD)}${a.groomRole.trim()}  (hand-edited)`);
+  }
 
   lines.push("", "escalation");
   if (a.telegramChatId !== undefined && a.telegramChatId.trim().length > 0) {