omp-conductor 0.16.0 → 0.16.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "type": "module",
   "license": "MIT",
   "description": "A 24/7 dispatcher that takes ready GitHub issues to green, mergeable PRs using omp coding sessions, with tiered escalation first to an orchestrator session and then to a human.",

package/schema/config.schema.json

@@ -305,6 +305,7 @@
           "modelFallbacks": {},
           "modelFallbackThreshold": {},
           "ompSettings": {},
+          "workerAdvisor": {},
           "escalation": {
             "type": "object",
             "properties": {

package/src/admission.ts

@@ -29,6 +29,7 @@ import type {
 } from "./types.ts";
 import { readPlanUsage, type PlanUsageStatus, type UsageSource } from "./usage.ts";
 import type { CriticalBaseProbe, CriticalBaseVerdict, RunLaneProbe } from "./gitops.ts";
+import { repoSlugFor } from "./gitops.ts";
 import { branchName, type Routed } from "./routing.ts";
 import { parseDependsOn } from "./depends-on.ts";
 
@@ -51,6 +52,17 @@ export interface AdmissionDeps {
   escalate(e: Escalation): Promise<void>;
   probeCriticalBase?: CriticalBaseProbe;
   probeWorktreeLane?: RunLaneProbe;
+  /**
+   * Reads one issue's tracker state in a repository the admission tracker is
+   * NOT bound to — the cross-repo half of the Depends-on interlock (#420).
+   * The tracker bound to `project.tracker.repo` can only answer same-repo
+   * references; a `owner/repo#n` prerequisite naming a different routed repo
+   * goes through this. Undefined means "could not tell" (same posture as
+   * {@link Tracker.issueSnapshot}); a routed prerequisite it cannot answer
+   * fails that candidate closed. Unset, admission fails a routed cross-repo
+   * prerequisite closed too — the daemon always wires it.
+   */
+  probeIssueIn?: (repo: string, issue: number) => Promise<IssueSnapshot | undefined>;
 }
 /** `stops` are the operational ends that each require one resume. */
 export function hasContinuationBudget(stops: number, maxContinuations: number): boolean {
@@ -190,6 +202,22 @@ function isPathLike(token: string): boolean {
   return token !== "" && !/\s/.test(token) && (token.includes("/") || /\.[A-Za-z0-9]{1,10}$/.test(token));
 }
 
+/**
+ * Where a `owner/repo` cross-repo reference can be read. Only repositories
+ * routed in THIS fleet are resolvable (#420): the issue source repo
+ * (`project.tracker.repo`) is answered by the existing tracker, and any routed
+ * work repo by {@link AdmissionDeps.probeIssueIn}. Anything else is unresolved
+ * — the caller fails closed rather than guess which repo was meant, and never
+ * silently resolves the reference against the candidate's own repo.
+ */
+function crossRepoTarget(project: ProjectConfig, ownerRepo: string): "tracker" | "routed" | undefined {
+  if (ownerRepo === project.tracker.repo) return "tracker";
+  for (const routed of Object.values(project.routing.repos)) {
+    if (repoSlugFor(routed) === ownerRepo) return "routed";
+  }
+  return undefined;
+}
+
 /**
  * Which routed candidates get a worker this tick — in queue order, never more
  * than `slots` of them. Every non-admission receives a stable reason code.
@@ -623,13 +651,14 @@ export async function admitCandidates(
       continue;
     }
 
-    // The Depends-on interlock (#419): a candidate declares the same-repo
-    // issues it must not be dispatched before, and any *open* prerequisite
-    // holds it until every referenced issue is closed. Prerequisite state is
-    // read fresh from the tracker at claim time, every pass — never cached
-    // across ticks — so a prerequisite that reopens re-holds on the next tick.
-    // Only same-repo `#<n>` references are resolved here; cross-repo
-    // references and graph cycles are later slices (#420/#421).
+    // The Depends-on interlock (#419/#420): a candidate declares the issues it
+    // must not be dispatched before — same-repo (`#123`) or cross-repo
+    // (`owner/repo#123`) — and any *open* prerequisite holds it until every
+    // referenced issue is closed. Prerequisite state is read fresh from the
+    // tracker at claim time, every pass — never cached across ticks — so a
+    // prerequisite that reopens re-holds on the next tick. Cross-repo
+    // references resolve only against repositories routed in this fleet;
+    // graph cycles are a later slice (#421).
     const dependsOn = parseDependsOn(r.issue.body);
     if (dependsOn.malformed.length > 0) {
       // A marker line with no strict `#<n>` reference (e.g. `Depends-on:
@@ -686,6 +715,81 @@ export async function admitCandidates(
         continue;
       }
     }
+    if (dependsOn.crossRefs.length > 0) {
+      // The cross-repo half (#420): each `owner/repo#n` is read from the repo
+      // it names. The fully qualified form travels in the `detail` string, so
+      // status/digest render it as `blocked by owner/repo#123` while same-repo
+      // refs stay compact `blocked by #5`.
+      let blocking: string | undefined;
+      let unreadable: string | undefined;
+      let unresolved: string | undefined;
+      for (const ref of dependsOn.crossRefs) {
+        const where = crossRepoTarget(project, ref.repo);
+        const full = `${ref.repo}#${ref.issue}`;
+        if (where === undefined) {
+          unresolved = full;
+          break;
+        }
+        let state: IssueSnapshot | undefined;
+        try {
+          if (where === "tracker") {
+            // The qualified form of the candidate's own tracker repo: the
+            // same state read the same-repo interlock uses.
+            state = await tracker.issueSnapshot(ref.issue);
+          } else if (d.probeIssueIn === undefined) {
+            // No resolver wired — fail closed, never guess the issue's state.
+            state = undefined;
+          } else {
+            state = await d.probeIssueIn(ref.repo, ref.issue);
+          }
+        } catch {
+          state = undefined;
+        }
+        if (state?.state === "open") {
+          blocking = full;
+          break;
+        }
+        if (state === undefined) {
+          unreadable = full;
+          break;
+        }
+      }
+      // Same fail-closed posture as same-repo refs: an open prerequisite
+      // holds, an unreadable one holds (the next tick rereads it fresh), and
+      // an unresolved repo holds because the dispatcher cannot verify the
+      // dependency — it is never silently treated as closed. Only the
+      // unresolved repo also surfaces one material event for grooming, and it
+      // follows the malformed-declaration escalation's stable-summary
+      // dedupe, so repeated ticks page once, not per tick.
+      if (blocking !== undefined) {
+        hold(issue, "depends-on", `blocked by ${blocking}`);
+        log(`#${issue} held (depends-on): cross-repo prerequisite ${blocking} is open`);
+        continue;
+      }
+      if (unreadable !== undefined) {
+        hold(issue, "depends-on", `prerequisite ${unreadable} state unreadable`);
+        log(`#${issue} held (depends-on): cross-repo prerequisite ${unreadable} state unreadable`);
+        continue;
+      }
+      if (unresolved !== undefined) {
+        hold(issue, "depends-on", `blocked by ${unresolved} — repo not routed in this fleet`);
+        log(`#${issue} held (depends-on): cross-repo prerequisite ${unresolved} is not a routed repo`);
+        await safeEscalate(d, {
+          tier: 1,
+          project: project.name,
+          issue,
+          summary: `#${issue} depends on ${unresolved}, a repo not routed in this fleet — held until groomed`,
+          detail: [
+            r.issue.title,
+            r.issue.url,
+            `Unroutable prerequisite: ${unresolved}`,
+            "Depends-on cross-repo references must name a repository routed in this project",
+            "(`routing.repos` or the tracker repo). Groom the body or route the repo.",
+          ].join("\n"),
+        });
+        continue;
+      }
+    }
 
     // The file-lane interlock (#555): a candidate whose declared lane overlaps
     // a live run's *actual* lane is held until that run's work has merged, so

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/config-schema.ts

@@ -325,6 +325,10 @@ const projectSchema = z
     // 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(),

package/src/config.ts

@@ -1122,6 +1122,36 @@ function finalizeProject(
       ? (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
@@ -1151,7 +1181,7 @@ function finalizeProject(
     ...(workerModel === undefined ? {} : { workerModel }),
     ...(modelFallbacks.length === 0 ? {} : { modelFallbacks }),
     ...(modelFallbackThreshold === undefined ? {} : { modelFallbackThreshold }),
-    ...(ompSettings === undefined ? {} : { ompSettings }),
+    ...(effectiveOmpSettings === undefined ? {} : { ompSettings: effectiveOmpSettings }),
     escalation,
     authority,
     releasePolicy,

package/src/daemon.ts

@@ -296,6 +296,13 @@ interface Deps {
    * probe the way `criticalBase` does.
    */
   probeWorktreeLane?: RunLaneProbe;
+  /**
+   * Reads one issue's tracker state in a repository the admission tracker is
+   * not bound to — the cross-repo Depends-on interlock (#420). Wired by
+   * `runDaemon` to a repo-scoped tracker; a test injects a fake. Absent,
+   * admission fails a routed cross-repo prerequisite closed.
+   */
+  probeIssueIn?: (repo: string, issue: number) => Promise<IssueSnapshot | undefined>;
 }
 
 /**
@@ -5584,6 +5591,15 @@ export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
       probeCriticalBase: (repo, markers, branch) =>
         probeCriticalBase(project, repo, branch, markers),
       probeWorktreeLane: (input) => probeRunLane(input),
+      // A cross-repo Depends-on prerequisite reads through the same GitHub
+      // credential/accounting seams as the project tracker — a fresh tracker
+      // scoped to the referenced repo, reusing the daemon's gh hooks so API
+      // spend and refusals are counted exactly as the main tracker's are.
+      probeIssueIn: (ownerRepo, issue) =>
+        makeTracker({ ...project, tracker: { kind: "github", repo: ownerRepo } }, undefined, {
+          onCall: () => store.bumpGhCalls?.(utcDay(), "daemon"),
+          onRefusal: (at) => store.recordGhRefusal?.(at),
+        }).issueSnapshot(issue),
       ...(verbPeerReader === undefined ? {} : { verbPeerReader }),
       verbActions,
     };