omp-conductor 0.15.13 → 0.16.1

package/src/commands/tail.ts

@@ -7,24 +7,146 @@
  */
 
 import type { CommandContext } from "./context.ts";
-import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { closeSync, openSync, readdirSync, readSync, statSync } from "node:fs";
+import { join } from "node:path";
 import { findProject, loadConfig } from "../config.ts";
 import { dbPath, LIVE_STATES, openStore } from "../store.ts";
-import { formatTranscriptLine } from "../transcript.ts";
+import { formatTranscriptLine, prop } from "../transcript.ts";
+import type { Store } from "../types.ts";
 
-/** How often `tail` re-stats the transcript it is following. */
+/** How often `tail` re-stats the transcripts it is following. */
 const TAIL_POLL_MS = 1_000;
 
 /**
- * How long the transcript must stay unchanged, after its run has left the live
+ * How long the transcripts must stay unchanged, after its run has left the live
  * states, before `tail` calls it over. The state flips from the daemon's thread
  * while the harness may still be flushing its last message, so exiting on the
  * state alone truncates the ending an operator ran this command to watch.
  */
 const TAIL_QUIET_MS = 5_000;
 
+/** The harness records advisor turns under this reserved stem. */
+const ADVISOR_TRANSCRIPT_PREFIX = "__advisor";
+
+/**
+ * One followed file: its open descriptor, how many bytes have been rendered,
+ * and whatever byte tail did not end on a newline yet. Holding the partial line
+ * across polls is what stops a UTF-8 sequence straddling a read boundary (or
+ * the newline itself) from being mangled by decoding each chunk on its own.
+ */
+interface FollowedStream {
+  fd: number;
+  offset: number;
+  pending: Buffer;
+}
+
 /**
- * Follow one run's transcript the way `tail -f` follows a log.
+ * Return the complete lines appended to `file` since the last poll, plus
+ * whether any bytes changed at all (the quiet-timer needs the latter even when
+ * a delta rendered no displayable line). A file that shrank (truncated or
+ * replaced) restarts from zero; a final line without a newline stays in
+ * `pending` until its newline lands.
+ */
+function followLines(
+  state: FollowedStream,
+  file: string,
+): { lines: Buffer[]; changed: boolean } {
+  const lines: Buffer[] = [];
+  let changed = false;
+  let size = 0;
+  try {
+    size = statSync(file).size;
+  } catch {
+    // A transcript that vanishes mid-follow is not worth crashing over.
+    return { lines, changed };
+  }
+  // Shorter than what we have already read means truncated or replaced;
+  // resuming from the old offset would read the middle of another file.
+  if (size < state.offset) {
+    state.offset = 0;
+    state.pending = Buffer.alloc(0);
+  }
+  if (size > state.offset) {
+    const chunk = Buffer.allocUnsafe(size - state.offset);
+    const read = readSync(state.fd, chunk, 0, chunk.length, state.offset);
+    state.offset += read;
+    state.pending = Buffer.concat([state.pending, chunk.subarray(0, read)]);
+    for (;;) {
+      const nl = state.pending.indexOf(0x0a);
+      if (nl < 0) break;
+      lines.push(state.pending.subarray(0, nl));
+      state.pending = state.pending.subarray(nl + 1);
+    }
+    changed = read > 0;
+  }
+  return { lines, changed };
+}
+
+/**
+ * One advisor-transcript line rendered for the watcher, or `undefined` for the
+ * lines not worth a row. An advisor speaks in two forms, and an operator
+ * watching a run wants both:
+ *
+ *   - plain assistant text, rendered exactly like the primary transcript's
+ *     (one spelling, so the two cannot drift), and
+ *   - `advise` tool calls — the reviewer's actual advisory, whose note and
+ *     severity live in the call arguments and would otherwise be invisible.
+ *
+ * The reviewer's other tool calls (`glob`/`read` probes into the workspace)
+ * render nothing: they are the investigation, not the advice. Every rendered
+ * line is marked so the watcher can tell which reviewer produced it. Exported
+ * so a unit test pins the surface without a store.
+ */
+export function renderAdvisorLine(line: string): string | undefined {
+  let entry: unknown;
+  try {
+    entry = JSON.parse(line);
+  } catch {
+    return undefined;
+  }
+  if (prop(entry, "type") !== "message") return undefined;
+  const message = prop(entry, "message");
+  if (prop(message, "role") !== "assistant") return undefined;
+
+  const content = prop(message, "content");
+  // A string-typed message is one plain text block — the same shape the
+  // primary transcript's formatter accepts, so an advisor advisory written as
+  // a bare string is not silently dropped.
+  if (typeof content === "string") {
+    return content.trim() === "" ? undefined : `[advisor] assistant: ${content.trim()}`;
+  }
+  const blocks: readonly unknown[] = Array.isArray(content) ? content : [];
+  const out: string[] = [];
+  for (const block of blocks) {
+    const type = prop(block, "type");
+    if (type === "text") {
+      const text = prop(block, "text");
+      if (typeof text === "string" && text.trim() !== "") out.push(`assistant: ${text.trim()}`);
+    } else if (type === "toolCall" && prop(block, "name") === "advise") {
+      let args = prop(block, "arguments");
+      if (typeof args === "string") {
+        try {
+          args = JSON.parse(args);
+        } catch {
+          continue;
+        }
+      }
+      const note = prop(args, "note");
+      if (typeof note === "string" && note.trim() !== "") {
+        const severity = prop(args, "severity");
+        const label = typeof severity === "string" && severity !== "" ? severity : "nit";
+        out.push(`${label}: ${note.trim()}`);
+      }
+    }
+  }
+  return out.length === 0 ? undefined : `[advisor] ${out.join("\n")}`;
+}
+
+/**
+ * Follow one run's transcripts the way `tail -f` follows a log: the worker's
+ * own transcript plus any `__advisor*.jsonl` sitting beside it (the mid-run
+ * reviewer's turns, #542), so an advisory the reviewer raised is visible in
+ * the same stream as the work it reacted to.
  *
  * Reads from byte zero rather than from the end: attaching to a worker that is
  * already ten turns in and then showing nothing until turn eleven is not
@@ -36,10 +158,24 @@ const TAIL_QUIET_MS = 5_000;
  * here is buffered, and a handler could only add a poll interval of latency to
  * every Ctrl-C.
  */
-async function tailRun(project: string, issue: number): Promise<void> {
-  // Read-only in practice: the store is opened WAL with a busy timeout, so this
-  // never contends with the daemon writing the same rows.
-  const store = openStore(dbPath());
+export async function tailRun(
+  project: string,
+  issue: number,
+  deps: {
+    /** Read-only in practice: opened WAL with a busy timeout. Tests inject one. */
+    store?: Store;
+    /** How often the transcripts are re-statted (tests shrink it). */
+    pollMs?: number;
+    /** How long a terminal run must stay quiet before the watcher exits. */
+    quietMs?: number;
+    /** Where rendered lines go; the CLI writes to stdout, tests capture. */
+    write?: (line: string) => void;
+  } = {},
+): Promise<void> {
+  const store = deps.store ?? openStore(dbPath());
+  const write = deps.write ?? ((line: string) => process.stdout.write(`${line}\n`));
+  const pollMs = deps.pollMs ?? TAIL_POLL_MS;
+  const quietMs = deps.quietMs ?? TAIL_QUIET_MS;
   try {
     const run = store.latestRun(project, issue);
     if (run === undefined) throw new Error(`no run recorded for #${issue}`);
@@ -47,56 +183,80 @@ async function tailRun(project: string, issue: number): Promise<void> {
     // Claimed but not yet started, or an attempt whose session never opened one.
     if (path === undefined) throw new Error(`no transcript yet (state: ${run.state})`);
 
-    const fd = openSync(path, "r");
+    const primary: FollowedStream = { fd: openSync(path, "r"), offset: 0, pending: Buffer.alloc(0) };
+    // Advisor transcripts live in the directory named after the primary
+    // transcript stem; the harness writes them there beside the session file.
+    const advisorDir = path.endsWith(".jsonl") ? path.slice(0, -".jsonl".length) : undefined;
+    const advisors = new Map<string, FollowedStream>();
     try {
-      let offset = 0;
-      let pending = Buffer.alloc(0);
       let lastChange = Date.now();
 
       for (;;) {
-        let size = offset;
-        try {
-          size = statSync(path).size;
-        } catch {
-          // A transcript that vanishes mid-follow is not worth crashing over.
-          // The run's own state, below, is what decides when this command ends.
+        let changed = false;
+        const primaryDelta = followLines(primary, path);
+        changed = primaryDelta.changed || changed;
+        for (const raw of primaryDelta.lines) {
+          const rendered = formatTranscriptLine(raw.toString("utf8"));
+          if (rendered !== undefined) write(rendered);
         }
-        // Shorter than what we have already read means truncated or replaced;
-        // resuming from the old offset would read the middle of another file.
-        if (size < offset) {
-          offset = 0;
-          pending = Buffer.alloc(0);
-        }
-        if (size > offset) {
-          const chunk = Buffer.allocUnsafe(size - offset);
-          const read = readSync(fd, chunk, 0, chunk.length, offset);
-          offset += read;
-          // Split on newlines as bytes, not as text: a UTF-8 sequence straddling
-          // a read boundary would be mangled by decoding each chunk on its own.
-          pending = Buffer.concat([pending, chunk.subarray(0, read)]);
-          for (;;) {
-            const nl = pending.indexOf(0x0a);
-            if (nl < 0) break;
-            const rendered = formatTranscriptLine(pending.subarray(0, nl).toString("utf8"));
-            pending = pending.subarray(nl + 1);
-            if (rendered !== undefined) process.stdout.write(`${rendered}\n`);
+
+        // Follow every advisor transcript that appears beside the primary one.
+        // Files land mid-run (the reviewer's first turn), so each poll re-lists
+        // the directory and opens whatever is new.
+        if (advisorDir !== undefined) {
+          let names: string[] = [];
+          try {
+            names = readdirSync(advisorDir).filter(
+              (name) =>
+                name.startsWith(ADVISOR_TRANSCRIPT_PREFIX) &&
+                name.endsWith(".jsonl"),
+            );
+          } catch {
+            // No advisor directory — nothing to surface.
+          }
+          for (const name of names) {
+            const file = join(advisorDir, name);
+            let state = advisors.get(file);
+            if (state === undefined) {
+              try {
+                state = { fd: openSync(file, "r"), offset: 0, pending: Buffer.alloc(0) };
+                advisors.set(file, state);
+              } catch {
+                continue;
+              }
+            }
+            const advisorDelta = followLines(state, file);
+            changed = advisorDelta.changed || changed;
+            for (const raw of advisorDelta.lines) {
+              const rendered = renderAdvisorLine(raw.toString("utf8"));
+              if (rendered !== undefined) write(rendered);
+            }
+          }
+          // Drop watched files that vanished (mid-run rotation is rare, but a
+          // stale descriptor would otherwise pin the old inode forever).
+          for (const [file, state] of advisors) {
+            if (!names.includes(file.slice(advisorDir.length + 1))) {
+              closeSync(state.fd);
+              advisors.delete(file);
+            }
           }
-          if (read > 0) lastChange = Date.now();
         }
+        if (changed) lastChange = Date.now();
 
         // Re-read this exact run every poll — not `latestRun`, which would jump
         // to a retry started meanwhile and report its state against the wrong
         // transcript. The daemon writes the row from another process, so looking
         // is the only way to notice the run finished.
         const state = store.getRun(run.id)?.state ?? run.state;
-        if (!LIVE_STATES.includes(state) && Date.now() - lastChange >= TAIL_QUIET_MS) {
-          process.stdout.write(`run ended: ${state}\n`);
+        if (!LIVE_STATES.includes(state) && Date.now() - lastChange >= quietMs) {
+          write(`run ended: ${state}`);
           return;
         }
-        await new Promise<void>((resolve) => setTimeout(resolve, TAIL_POLL_MS));
+        await new Promise<void>((resolve) => setTimeout(resolve, pollMs));
       }
     } finally {
-      closeSync(fd);
+      closeSync(primary.fd);
+      for (const state of advisors.values()) closeSync(state.fd);
     }
   } finally {
     store.close();
@@ -104,6 +264,6 @@ async function tailRun(project: string, issue: number): Promise<void> {
 }
 
 export async function tailCommand(ctx: CommandContext): Promise<void> {
-const issue = ctx.issueArg("tail", ctx.argv[1]);
-await tailRun(findProject(loadConfig(), ctx.projectFlag).name, issue);
+  const issue = ctx.issueArg("tail", ctx.argv[1]);
+  await tailRun(findProject(loadConfig(), ctx.projectFlag).name, issue);
 }

package/src/commands/unfreeze.ts

@@ -0,0 +1,56 @@
+/**
+ * `unfreeze <repo>` — the operator's sanctioned override for a base-red-freeze.
+ *
+ * A base-red-freeze is a mechanical gate: `prMergeVerb` refuses every
+ * `conductor_pr_merge` to a repo whose base is red, and the floor binds even
+ * the orchestrator to that refusal. This verb is the *one* sanctioned way to
+ * lift it early — after the operator has judged the base repaired (or the
+ * merge warranted anyway) — and it is ledger-recorded: the freeze row keeps
+ * `clearedBy`/`clearedReason`/`clearedAt` as its durable override audit, and a
+ * material event names the override for the queue digest. It is deliberately
+ * not label surgery or a raw DB edit, and it does not re-arm — a still-red base
+ * will re-freeze the repo on the next watch observation.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { findProject, loadConfig } from "../config.ts";
+import { dbPath, openStore } from "../store.ts";
+
+export async function unfreezeCommand(ctx: CommandContext): Promise<void> {
+  const repo = ctx.argv[1];
+  if (repo === undefined || repo.length === 0 || repo.startsWith("-")) {
+    process.stderr.write("omp-conductor: unfreeze needs the routed repo name, e.g. `omp-conductor unfreeze api`\n");
+    process.exit(2);
+  }
+  const reason = ctx.flag("--reason") ?? "operator-override";
+  const cfg = loadConfig();
+  const project = findProject(cfg, ctx.projectFlag);
+  const store = openStore(dbPath());
+  try {
+    const now = Date.now();
+    const lifted = store.clearBaseFreeze(project.name, repo, "operator", reason, now);
+    if (!lifted) {
+      process.stdout.write(
+        `unfreeze: ${repo} has no active base-red freeze in ${project.name} (merges already allowed). Nothing to lift.\n`,
+      );
+      return;
+    }
+    store.recordMaterialEvent({
+      project: project.name,
+      category: "unfreeze",
+      summary: `operator unfroze merges to ${repo} (${reason})`,
+      evidence:
+        `An operator lifted the base-red-freeze on ${repo} with reason "${reason}". ` +
+        "This is the sanctioned override path — the freeze re-arms automatically if the base is " +
+        "observed red again.",
+      occurredAt: now,
+      recordedAt: now,
+    });
+    process.stdout.write(
+      `unfreeze: ${repo} base-red freeze lifted in ${project.name} (reason: ${reason}). ` +
+        "Merges to this repo resume; a still-red base will re-freeze on the next watch observation.\n",
+    );
+  } finally {
+    store.close();
+  }
+}

package/src/commands/watch.ts

@@ -0,0 +1,77 @@
+/**
+ * `watch` — set a condition for the orchestrator itself, with no human in the
+ * loop (#459).
+ *
+ * The split exists because the old `decision open --resolves-when` kept
+ * producing rows rendered as questions put to the operator — the fleet looked
+ * like it was waiting on a person when it was waiting on GitHub. A watch is a
+ * row the orchestrator opened for itself: either a condition the daemon checks
+ * (`--resolves-when`) that wakes the next tick when met, or a carry note the
+ * next tick should read, neither of which ever needs an operator answer. It is
+ * distinguished durably by its `kind`, never by whether it carries a
+ * condition — a real question may carry one too.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { findProject, loadConfig } from "../config.ts";
+import { CONDITION_FORMS, parseCondition } from "../decisions.ts";
+import { dbPath, openStore } from "../store.ts";
+
+export async function watchCommand(ctx: CommandContext): Promise<void> {
+  const sub = ctx.argv[1];
+  const project = findProject(loadConfig(), ctx.projectFlag);
+  const store = openStore(dbPath());
+  try {
+    if (sub === "add") {
+      const note = ctx.flag("note")?.trim();
+      if (note === undefined || note.length === 0 || note.startsWith("--")) {
+        process.stderr.write("omp-conductor: watch add needs --note with what the next tick should know\n");
+        process.exit(2);
+      }
+      const condition = ctx.flag("resolves-when")?.trim();
+      if (condition !== undefined && parseCondition(condition) === undefined) {
+        process.stderr.write(
+          `omp-conductor: --resolves-when must be one of:\n${CONDITION_FORMS.map((f) => `  ${f}`).join("\n")}\n`,
+        );
+        process.exit(2);
+      }
+      const blocks = ctx.flag("blocks")?.trim();
+      const watch = store.createDecision({
+        project: project.name,
+        question: note,
+        kind: "watch",
+        ...(blocks === undefined || blocks.length === 0 ? {} : { blocks }),
+        ...(condition === undefined ? {} : { condition }),
+        at: Date.now(),
+      });
+      const wake = condition === undefined ? "read by the next tick" : "the daemon wakes the next tick when it is met";
+      process.stdout.write(`watch ${watch.id} added — ${wake} (no operator answer needed)\n`);
+      return;
+    }
+
+    if (sub === "list" || sub === undefined) {
+      const watches = store.openDecisions(project.name).filter((d) => d.kind === "watch");
+      if (watches.length === 0) {
+        process.stdout.write("no watches\n");
+        return;
+      }
+      const now = Date.now();
+      for (const d of watches) {
+        const condition =
+          d.condition === undefined ? "-" : d.conditionMetAt === undefined ? "pending" : "met";
+        const hours = Math.max(0, Math.round((now - d.askedAt) / 3_600_000));
+        process.stdout.write(
+          `${d.id}  ${hours}h  blocks:${d.blocks ?? "-"}  condition:${condition}  ${d.question}\n`,
+        );
+      }
+      return;
+    }
+
+    process.stderr.write(
+      `omp-conductor: unknown watch subcommand "${sub}" — expected add or list\n`,
+    );
+    process.exit(2);
+  } finally {
+    store.close();
+  }
+}

package/src/config-schema.ts

@@ -321,6 +321,14 @@ const projectSchema = z
     // usable, exactly like `workerModel`.
     modelFallbacks: z.unknown().optional(),
     modelFallbackThreshold: z.unknown().optional(),
+    // The fleet-owned omp settings overlay (#537): an opaque map omp's own
+    // schema owns. Conductor validates YAML shape only — the loader keeps it
+    // when it is a mapping and drops anything else, like `modelFallbacks`.
+    ompSettings: z.unknown().optional(),
+    // Opt-in omp advisor on workers (#542). Only the literal boolean `true`
+    // opts in (it stages `advisor.enabled: true` into the omp settings
+    // overlay); anything else is dropped by the loader, like `workerModel`.
+    workerAdvisor: z.unknown().optional(),
     escalation: escalationSchema.optional(),
     authority: authoritySchema.optional(),
     releasePolicy: releasePolicySchema.optional(),
@@ -344,6 +352,11 @@ const configSchema = z
     $schema: z.string().optional().describe("Path to the shipped config.schema.json"),
     version: z.number().describe(`The config format version (${READABLE_CONFIG_VERSIONS.join(" or ")})`),
     defaults: capsSchema.optional(),
+    dbBackupDir: z
+      .string()
+      .min(1, "must name a directory")
+      .optional()
+      .describe("Absolute directory for restorable conductor.db snapshots; defaults to <stateDir>/backups/db"),
     projects: z.array(projectSchema).min(1, `"projects" must be a non-empty array — the dispatcher has nothing to service otherwise`),
   })
   .loose()

package/src/config.ts

@@ -124,6 +124,18 @@ export function configBackupDir(): string {
   return join(stateDir(), "backups", "config");
 }
 
+/**
+ * Where restorable `conductor.db` snapshots land: the configured `dbBackupDir`,
+ * or the state-root default `<stateDir()>/backups/db` beside the config
+ * backups when the field is absent. A `~/`-prefixed configured value is
+ * expanded like every other hand-written path field.
+ */
+export function dbBackupDirFor(cfg: Pick<ConductorConfig, "dbBackupDir"> | undefined): string {
+  const configured = cfg?.dbBackupDir;
+  const dir = configured !== undefined && configured.trim() !== "" ? expandHome(configured) : join(stateDir(), "backups", "db");
+  return dir;
+}
+
 /**
  * Where per-run worktrees and bare mirrors live when a project names neither.
  *
@@ -1099,6 +1111,47 @@ function finalizeProject(
       ? rawThreshold
       : undefined;
 
+  // The fleet-owned omp settings overlay (#537): an opaque map omp's own schema
+  // owns, so the loader validates YAML shape only — a non-mapping is dropped
+  // like an unusable `modelFallbacks` entry rather than failing the load, and
+  // an absent field keeps today's dispatch byte for byte. Everything inside the
+  // map is omp's to interpret, never conductor's.
+  const rawOmpSettings = p["ompSettings"];
+  const ompSettings =
+    typeof rawOmpSettings === "object" && rawOmpSettings !== null && !Array.isArray(rawOmpSettings)
+      ? (rawOmpSettings as Record<string, unknown>)
+      : undefined;
+
+  // Opt-in omp advisor on this project's workers (#542). `workerAdvisor: true`
+  // stages `advisor.enabled: true` into the omp settings overlay — the same
+  // #537 channel everything else uses — so the advisor's own behaviour (roster,
+  // model, tools) stays omp's to resolve from the staged or global config, and
+  // conductor never names a model or grants a tool. Only the literal boolean
+  // `true` opts in; anything else (absent, false, a string) is dropped like an
+  // unusable `modelFallbacks` entry, keeping today's dispatch byte for byte.
+  const workerAdvisor = p["workerAdvisor"] === true;
+  const effectiveOmpSettings =
+    workerAdvisor || ompSettings !== undefined
+      ? {
+          ...(ompSettings === undefined ? {} : ompSettings),
+          ...(workerAdvisor
+            ? {
+                // Merge, not replace: an operator's own `ompSettings.advisor`
+                // block (roster or model overrides) survives; only `enabled` is
+                // forced on, because that is the point of the opt-in.
+                advisor: {
+                  ...(typeof ompSettings?.advisor === "object" &&
+                  ompSettings.advisor !== null &&
+                  !Array.isArray(ompSettings.advisor)
+                    ? (ompSettings.advisor as Record<string, unknown>)
+                    : {}),
+                  enabled: true,
+                },
+              }
+            : {}),
+        }
+      : undefined;
+
   // Marked critical-base/safety markers (commit SHAs or refs). A continuation
   // branch must contain every one before the dispatcher may reattach it;
   // unusable entries are dropped like `modelFallbacks` and an absent or empty
@@ -1128,6 +1181,7 @@ function finalizeProject(
     ...(workerModel === undefined ? {} : { workerModel }),
     ...(modelFallbacks.length === 0 ? {} : { modelFallbacks }),
     ...(modelFallbackThreshold === undefined ? {} : { modelFallbackThreshold }),
+    ...(effectiveOmpSettings === undefined ? {} : { ompSettings: effectiveOmpSettings }),
     escalation,
     authority,
     releasePolicy,