omp-conductor 0.16.0 → 0.16.2

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,
     };

package/src/depends-on.ts

@@ -1,34 +1,50 @@
 /**
- * The `Depends-on:` declaration parser (epic #321, slice #419).
+ * The `Depends-on:` declaration parser (epic #321, slices #419/#420).
  *
- * A candidate issue can declare same-repo prerequisites it must not be
- * dispatched before: `Depends-on: #123` (repeatable, one or more per line).
- * Admission reads every referenced issue's live tracker state and holds the
- * candidate while any prerequisite is open, so a worker is never sent at work
- * whose base is not yet merged.
+ * A candidate issue can declare prerequisites it must not be dispatched
+ * before: `Depends-on: #123` (a same-repo issue) or `Depends-on:
+ * owner/repo#123` (an issue in a routed repository), repeatable one or more
+ * per line. Admission reads every referenced issue's live tracker state and
+ * holds the candidate while any prerequisite is open, so a worker is never
+ * sent at work whose base is not yet merged.
  *
  * The parser is deliberately small and strict, the two halves of the contract:
  * the *marker* is matched case-insensitively (so `DEPENDS-ON`, `Depends-On`,
- * `depends-on` all declare), while the *references* are strict bare issue
- * numbers (`#123`). A marker line that carries no strict reference — an empty
- * `Depends-on:`, or a bare non-numeric `Depends-on: #abc` — is never a usable
- * prerequisite, so it is reported as `malformed` for the grooming flag rather
- * than guessed at, and the declaration it belongs to is ignored.
+ * `depends-on` all declare), while the *references* are strict — a bare issue
+ * number (`#123`) or a qualifying `owner/repo#123` with exactly two path
+ * segments glued to the number. A marker line that carries no strict
+ * reference — an empty `Depends-on:`, a bare non-numeric `Depends-on: #abc`,
+ * or a slashed-but-unqualified form that is not `owner/repo#n` — is never a
+ * usable prerequisite, so it is reported as `malformed` for the grooming flag
+ * rather than guessed at, and the declaration it belongs to is ignored.
  *
- * Cross-repo references (a qualifying `owner/repo#n` or `repo#n` form) and
- * graph cycles are later slices (#420/#421) and are deliberately out of scope
- * here: only plain `#<n>` same-repo forms are resolved.
+ * Graph cycles are a later slice (#421) and stay out of scope here.
  */
 
 export interface DependsOnDecl {
-  /** Referenced prerequisite issue numbers, deduplicated, first-seen order. */
+  /** Referenced same-repo prerequisite issue numbers, deduplicated,
+   *  first-seen order. */
   readonly refs: readonly number[];
-  /** Marker-bearing lines that carried no strict `#<n>` reference (e.g.
+  /** Referenced cross-repo prerequisites (`owner/repo#n`), deduplicated,
+   *  first-seen order. Admission resolves these against the fleet's routed
+   *  repositories, never against the candidate's own repo (#420). */
+  readonly crossRefs: readonly DependsOnCrossRef[];
+  /** Marker-bearing lines that carried no strict reference (e.g.
    *  `Depends-on: #abc`). Bounded to what the body actually said, for the
    *  grooming flag's detail. */
   readonly malformed: readonly string[];
 }
 
+/**
+ * A strict cross-repo reference. `repo` is the canonical `owner/repo` spelling
+ * from the body, untouched, so admission can match it by identity against the
+ * fleet's routed repositories rather than by guess.
+ */
+export interface DependsOnCrossRef {
+  readonly repo: string;
+  readonly issue: number;
+}
+
 /**
  * How a line is spelled: `depends-on`/`depends on`, optional whitespace, then
  * a `:` or `=` separator. The marker is matched case-insensitively; the value
@@ -38,13 +54,29 @@ export interface DependsOnDecl {
  */
 const MARKER = /^depends[-\s]?on\s*[:=]\s*(.*)$/i;
 
-/** A strict reference is a bare `#` followed by digits — no repo qualifier,
- *  no words. Everything else is not a prerequisite this slice resolves. */
-const REF = /#(\d+)/g;
+/** A strict same-repo reference is a bare `#` followed by digits — no repo
+ *  qualifier, no words. The negative lookbehind means a `#<n>` glued to a
+ *  word (e.g. `web#7` or `issue#5`) is not a bare reference: without the
+ *  `owner/` segment it is neither a valid cross-repo ref nor a valid
+ *  same-repo one, so it is flagged malformed rather than silently resolved in
+ *  the candidate's own repo. */
+const REF = /(?<![A-Za-z0-9._/-])#(\d+)/g;
+
+/**
+ * A strict cross-repo reference is `owner/repo#<n>` — exactly two path
+ * segments (each a GitHub owner/repository charset run) glued to a bare issue
+ * number, no whitespace. Scanned before {@link REF} and blanked out of the
+ * value, so the trailing `#<n>` is never re-read as a *same-repo* reference:
+ * the whole point of the qualified form is that it names a different
+ * repository, and resolving it in the candidate's own repo is the #420 fake.
+ */
+const CROSS_REF = /([A-Za-z0-9][A-Za-z0-9._-]*)\/([A-Za-z0-9][A-Za-z0-9._-]*)#(\d+)/g;
 
 export function parseDependsOn(body: string): DependsOnDecl {
   const refs: number[] = [];
   const seen = new Set<number>();
+  const crossRefs: DependsOnCrossRef[] = [];
+  const seenCross = new Set<string>();
   const malformed: string[] = [];
   for (const raw of body.split("\n")) {
     const line = raw.trim();
@@ -52,22 +84,39 @@ export function parseDependsOn(body: string): DependsOnDecl {
     const match = MARKER.exec(line);
     if (match === null) continue;
     const value = match[1] ?? "";
+
+    // Cross-repo references first, blanked out of the value so their `#<n>`
+    // cannot also be collected as a same-repo reference below.
+    let lineHadRef = false;
+    const masked = value.replace(CROSS_REF, (whole, owner, name, number) => {
+      const repo = `${owner}/${name}`;
+      const n = Number(number);
+      if (Number.isSafeInteger(n) && !seenCross.has(`${repo}#${n}`)) {
+        seenCross.add(`${repo}#${n}`);
+        crossRefs.push({ repo, issue: n });
+      }
+      lineHadRef = true;
+      return " ".repeat(whole.length);
+    });
+
     REF.lastIndex = 0;
-    const found = [...value.matchAll(REF)];
-    if (found.length === 0) {
-      // A marker line with no strict reference is a malformed declaration:
-      // never crash, never silently claim — the declaration is ignored and
-      // surfaced for grooming.
-      malformed.push(line);
-      continue;
-    }
+    const found = [...masked.matchAll(REF)];
     for (const group of found) {
       const n = Number(group[1]!);
       if (Number.isSafeInteger(n) && !seen.has(n)) {
         seen.add(n);
         refs.push(n);
       }
+      lineHadRef = true;
+    }
+
+    if (!lineHadRef) {
+      // A marker line with no strict reference — same-repo or cross-repo — is
+      // a malformed declaration: never crash, never silently claim — the
+      // declaration is ignored and surfaced for grooming.
+      malformed.push(line);
+      continue;
     }
   }
-  return { refs, malformed };
+  return { refs, crossRefs, malformed };
 }