omp-conductor 0.16.0 → 0.16.1

package/src/fleet.ts

@@ -26,10 +26,10 @@ import {
 } from "node:fs";
 import { createInterface } from "node:readline";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, sep } from "node:path";
 import { findProject, loadConfig, stateDir } from "./config.ts";
 import { clearArmChallenge, recordArmChallenge } from "./arm-challenge.ts";
-import { resolveProjectTopicId, sendTelegram } from "./escalate.ts";
+import { resolveClaimedSessionFile, resolveProjectTopicId, sendTelegram } from "./escalate.ts";
 import { readPlanUsage, sharedUsageSource } from "./usage.ts";
 import { readApprovalSurface, readDaemonProfile } from "./approval-surface.ts";
 import { inspectBriefLayout } from "./brief-upgrade.ts";
@@ -287,13 +287,22 @@ export interface ArmResult {
 export interface ArmDeps {
   sendChallenge?: (token: string, owner: string, text: string, topicId?: number) => Promise<void>;
   /**
-   * Waits for the challenge to appear as a user turn somewhere under the
-   * session directory. The waiter owns transcript discovery — not the caller —
+   * The orchestrator session file the live omp-telegram claim names for this
+   * project, or undefined when there is no (readable) claim. The default
+   * resolves the claim the same way the send does; tests inject a fixture.
+   * Absent → arm watches the cwd-derived session directory, the pre-claim
+   * behaviour.
+   */
+  claimedSessionFile?: () => string | undefined;
+  /**
+   * Waits for the challenge to appear as a user turn somewhere under the scan
+   * directories. The waiter owns transcript discovery — not the caller —
    * because the reply may land in a session that starts *after* the send, so a
    * path resolved before the challenge went out can be the wrong file by the
-   * time the operator answers (#142).
+   * time the operator answers (#142), and because the claimed session file can
+   * sit in a different directory than the tick cwd implies (#600).
    */
-  waitForUserTurn?: (dir: string, code: string, sentAt: number, timeoutMs: number) => Promise<boolean>;
+  waitForUserTurn?: (dirs: readonly string[], code: string, sentAt: number, timeoutMs: number) => Promise<boolean>;
   now?: () => number;
   sleep?: (ms: number) => Promise<void>;
   timeoutMs?: number;
@@ -332,10 +341,23 @@ export async function armTicks(projectName?: string, deps: ArmDeps = {}): Promis
     );
   }
 
-  const dir = sessionDirForCwd(tick.cwd);
-  if (!existsSync(dir)) {
+  // One bot, one chat, and — once a host runs more than one fleet — more than
+  // one pane that can ask. The challenge names which one, or the operator is
+  // answering a question they cannot attribute.
+  const named = tick.config.project ?? projectName;
+
+  // Resolve the orchestrator's live session file *before* the challenge goes
+  // out — the same claim the send follows (#600). A pane resumed from a
+  // session created elsewhere (herdr pins it to the original transcript)
+  // writes a session file outside the directory the tick cwd implies, and a
+  // cwd-derived scan would poll the one place the reply is guaranteed not to
+  // be. A claim outside the session tree arm scans can never be answered, so
+  // that is a stop, not five minutes of polling.
+  const claimed = deps.claimedSessionFile !== undefined ? deps.claimedSessionFile() : claimedOrchestratorSessionFile(named);
+  const dirs = armSessionScanDirs(tick.cwd, claimed);
+  if (dirs.every((d) => !existsSync(d))) {
     throw new Error(
-      `no orchestrator session directory at ${dir} — ` +
+      `no orchestrator session directory under ${dirs.join(" or ")} — ` +
         `the inbound proof is read from a user turn in a transcript there. Start the pane orchestrator, let it settle, then arm again`,
     );
   }
@@ -347,10 +369,6 @@ export async function armTicks(projectName?: string, deps: ArmDeps = {}): Promis
   const arm = resolveArmState(path, tick.config.project ?? projectName);
   const alreadyArmed = arm.armed;
   const code = makeChallengeCode();
-  // One bot, one chat, and — once a host runs more than one fleet — more than
-  // one pane that can ask. The challenge names which one, or the operator is
-  // answering a question they cannot attribute.
-  const named = tick.config.project ?? projectName;
   const text =
     `Fleet arming check${named === undefined ? "" : ` — project ${named}`}. ` +
     `Reply to this chat with exactly:\n${code}\n` +
@@ -391,25 +409,37 @@ export async function armTicks(projectName?: string, deps: ArmDeps = {}): Promis
 
   const injected = deps.waitForUserTurn;
   const scan: SessionScan = injected
-    ? { seen: await injected(dir, code, sentAt, timeoutMs), scanned: [], ignored: [] }
-    : await waitForChallengeInSessions(dir, code, sentAt, timeoutMs, deps);
+    ? { seen: await injected(dirs, code, sentAt, timeoutMs), scanned: [], ignored: [] }
+    : await waitForChallengeInSessions(dirs, code, sentAt, timeoutMs, deps);
   if (!scan.seen) {
     // The proof missed its window: a lookalike reply must not stay classifiable
     // after arming gave up, so the record is cleared before the failure lands.
     clearArmChallenge(named);
+    // The claimed session file is named before the bridge/token/chat block: a
+    // rotation under the window is visible from this error alone, and on the
+    // host this guard exists for the claimed file is the one that held the
+    // answer (#600).
     const listing = [
-      `session dir: ${dir}`,
+      ...(claimed === undefined
+        ? []
+        : [
+            `claimed orchestrator session file: ${claimed}` +
+              (dirs.includes(dirname(claimed))
+                ? " (watched)"
+                : ` (NOT under any watched dir — a reply there can never be seen)`),
+          ]),
+      `session dir: ${dirs.join(", ")}`,
       ...scan.scanned.map((f) => `  watched: ${f}`),
       ...scan.ignored.map((f) => `  ignored (stale, last written before the challenge): ${f}`),
     ].join("\n");
     throw new Error(
       `arm: the challenge never arrived as a user turn in time — NOT armed.\n` +
-        `Inbound Telegram is not reaching the omp session. Check, in order:\n` +
+        listing +
+        `\nInbound Telegram is not reaching the omp session. Check, in order:\n` +
         `  * is the bridge polling?      attach and run: /telegram status\n` +
         `  * is another process holding this bot token? Telegram allows exactly one\n` +
         `    getUpdates consumer and rejects the second with HTTP 409.\n` +
-        `  * did you reply in the DM with the bot, not another chat?\n` +
-        listing,
+        `  * did you reply in the DM with the bot, not another chat?\n`,
     );
   }
 
@@ -1605,6 +1635,56 @@ export function sessionDirForCwd(cwd: string): string {
   return join(home, ".omp", "agent", "sessions", slug.replaceAll("/", "-"));
 }
 
+/** The session tree arm scans: every transcript under it, whatever the cwd slug. */
+export function sessionsRoot(): string {
+  return join(homedir(), ".omp", "agent", "sessions");
+}
+
+/**
+ * The orchestrator session file omp-telegram's live claim names for this
+ * project — the transcript a resumed/restored pane actually writes, which can
+ * live in a different session directory than the tick cwd implies (#600).
+ * Never throws: no claim, or an unreadable config, means undefined and arm
+ * falls back to the cwd-derived directory.
+ */
+function claimedOrchestratorSessionFile(named: string | undefined): string | undefined {
+  if (named === undefined) return undefined;
+  try {
+    return resolveClaimedSessionFile(findProject(loadConfig(), named));
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The session directories `arm` watches for the reply — the cwd-derived one
+ * plus, when the live claim's file lives elsewhere, that file's directory.
+ *
+ * The cwd-derived directory is where a *fresh* session started from the tick
+ * cwd writes; the claimed file's directory is where the *restored* pane keeps
+ * writing (herdr pins it to the original transcript). Watching both covers a
+ * resumed session, a rotated one, and a session that starts after the send.
+ *
+ * A claim outside the session tree is a stop, not a slower failure: arm polls
+ * only transcripts under {@link sessionsRoot}, so a claimed file elsewhere can
+ * never satisfy the challenge, and five minutes of polling cannot discover a
+ * file that is not in the search set. The throw names both paths.
+ */
+function armSessionScanDirs(cwd: string, claimed: string | undefined): string[] {
+  const cwdDir = sessionDirForCwd(cwd);
+  if (claimed === undefined) return [cwdDir];
+  const root = sessionsRoot();
+  const claimDir = dirname(claimed);
+  if (claimDir !== root && !claimDir.startsWith(join(root, sep))) {
+    throw new Error(
+      `arm: the orchestrator's claimed session file ${claimed} is outside the session tree arm scans (${root}) — ` +
+        `no transcript there can satisfy the challenge. Resume the pane under ${root}, or start it from ${cwd}; ` +
+        `arm would otherwise poll ${cwdDir} until the timer runs out`,
+    );
+  }
+  return claimDir === cwdDir ? [cwdDir] : [cwdDir, claimDir];
+}
+
 function makeChallengeCode(): string {
   const bytes = new Uint8Array(4);
   crypto.getRandomValues(bytes);
@@ -1631,20 +1711,23 @@ interface SessionScan {
 }
 
 /**
- * Polls the session directory — re-read on every pass, never snapshotted —
+ * Polls the session directories — re-read on every pass, never snapshotted —
  * until the challenge shows up as a user turn or the deadline passes.
  *
  * Discovery lives here because the reply can land in a transcript that does not
  * exist yet when the challenge is sent: a rotated session, or the first one of
- * a pane started right after arming (#142). A waiter handed one path polls a
- * file the answer will never be written to, and arming becomes impossible.
+ * a pane started right after arming (#142). And the scan set can be two
+ * directories when the live claim's session file lives outside the tick-cwd
+ * directory: the restored pane keeps writing the claimed file, so its
+ * directory is watched alongside the cwd-derived one (#600).
  *
  * Files untouched since just before the send are named, not parsed: an append
  * bumps mtime, so a transcript older than the challenge cannot hold the reply,
- * and skipping it keeps a large stale session out of every 5 s pass.
+ * and skipping it keeps a large stale session out of every 5 s pass. A missing
+ * directory is not an error — it can vanish under a rotation and reappear.
  */
 async function waitForChallengeInSessions(
-  dir: string,
+  dirs: readonly string[],
   code: string,
   sentAt: number,
   timeoutMs: number,
@@ -1656,28 +1739,30 @@ async function waitForChallengeInSessions(
   for (;;) {
     const scanned: string[] = [];
     const ignored: string[] = [];
-    let names: string[] = [];
-    try {
-      names = readdirSync(dir);
-    } catch {
-      /* the directory can go away under a rotation; the next pass re-reads it */
-    }
-    for (const name of names.sort()) {
-      if (!name.endsWith(".jsonl")) continue;
-      const path = join(dir, name);
-      let mtimeMs: number;
+    for (const dir of dirs) {
+      let names: string[] = [];
       try {
-        mtimeMs = statSync(path).mtimeMs;
+        names = readdirSync(dir);
       } catch {
-        continue; /* race */
+        /* the directory can go away under a rotation; the next pass re-reads it */
       }
-      const label = `${name} (mtime ${new Date(mtimeMs).toISOString()})`;
-      if (mtimeMs < sentAt - 1_000) {
-        ignored.push(label);
-        continue;
+      for (const name of names.sort()) {
+        if (!name.endsWith(".jsonl")) continue;
+        const path = join(dir, name);
+        let mtimeMs: number;
+        try {
+          mtimeMs = statSync(path).mtimeMs;
+        } catch {
+          continue; /* race */
+        }
+        const label = `${name} (mtime ${new Date(mtimeMs).toISOString()})`;
+        if (mtimeMs < sentAt - 1_000) {
+          ignored.push(label);
+          continue;
+        }
+        scanned.push(label);
+        if (await transcriptHasUserCode(path, code)) return { seen: true, scanned, ignored };
       }
-      scanned.push(label);
-      if (await transcriptHasUserCode(path, code)) return { seen: true, scanned, ignored };
     }
     if (now() >= deadline) return { seen: false, scanned, ignored };
     await sleep(5_000);

package/src/transcript.ts

@@ -1,5 +1,5 @@
 /** Read one property off an unvalidated transcript entry. */
-function prop(source: unknown, key: string): unknown {
+export function prop(source: unknown, key: string): unknown {
   if (source === null || typeof source !== "object") return undefined;
   return Reflect.get(source, key);
 }

package/src/worker.ts

@@ -10,6 +10,8 @@
  * sliding into a merge queue.
  */
 
+import { mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { createSession, disposeSession, SessionAdmissionClosedError, type AgentSessionLike } from "./omp.ts";
 import type { GateShape, ReleaseBlockContext } from "./release-policy.ts";
 import type { Caps, ResolvedGrants, RunState } from "./types.ts";
@@ -321,6 +323,17 @@ export async function runWorker(
   const schedule = deps.schedule ?? scheduleWallClock;
 
   let session: AgentSessionLike;
+  // The per-issue reviewer brief (#542): when the staged omp settings turn the
+  // advisor on, drop a WATCHDOG.md rendered from this brief's own acceptance
+  // criteria into the worktree before the session exists — the advisor's
+  // watchdog discovery runs at session start, rooted at cwd, and a file that
+  // appears afterwards is a reviewer flying blind. The managed exclude block
+  // ignores that exact path (never `.omp/`), so it cannot reach the PR diff or
+  // a salvage commit. Best-effort: a reviewer brief is advisory, and a staging
+  // failure must not cost the run.
+  if (o.resume === undefined && o.ompSettingsFile !== undefined) {
+    stageIssueWatchdog(o.cwd, o.brief, o.ompSettingsFile);
+  }
   try {
     session = await deps.createSession({
       cwd: o.cwd,
@@ -384,12 +397,33 @@ export async function runWorker(
     | "modelRecoveries"
     | "autoRetryCount"
     | "autoCompactionCount";
+  // Folded once, on whichever exit path actually runs: every return below
+  // passes through `withSessionFacts`, so the advisor's separately-recorded
+  // spend (#542) is added to exactly one result and reported to the daemon
+  // exactly once.
+  let advisorSpendFolded = false;
   const withSessionFacts = (
     result: Omit<WorkerResult, ReliabilityKeys>,
   ): Omit<WorkerResult, ReliabilityKeys> => {
     const { sessionFile, modelFallbackMessage } = session;
+    if (!advisorSpendFolded) {
+      advisorSpendFolded = true;
+      // Advisor turns live in their own `__advisor*.jsonl` and never surface
+      // as primary `message_end`s, so without this read the run's spend — and
+      // therefore `caps.dailySpendUsd` — silently under-counts real provider
+      // consumption (the #46 shape). Read at the very end: the advisor's
+      // review of the final turn may still be landing.
+      const extra = advisorSpendUsd(sessionFile);
+      if (extra > 0) {
+        spendUsd += extra;
+        o.onSpend?.(spendUsd);
+      }
+    }
     return {
       ...result,
+      // Override whatever the exit path spelled: its literal captured the
+      // pre-fold `spendUsd`, and the advisor fold happened after.
+      spendUsd,
       ...(sessionFile === undefined ? {} : { sessionFile }),
       ...(modelFallbackMessage === undefined ? {} : { modelFallbackMessage }),
     };
@@ -807,6 +841,168 @@ function field(source: unknown, key: string): unknown {
   return Reflect.get(source, key);
 }
 
+/** Advisor transcripts are recorded under this reserved stem beside the session's. */
+const ADVISOR_TRANSCRIPT_PREFIX = "__advisor";
+
+/**
+ * Whether a staged omp-settings overlay (the file `materializeOmpSettings`
+ * writes under the run's session directory) turns the omp advisor on.
+ *
+ * The overlay is conductor's own YAML — written by `yaml.stringify` over a map
+ * this package controls — so this is deliberately not a general YAML parser:
+ * it scans for an `advisor:` mapping and asks whether one of its direct
+ * `enabled:` keys reads the literal `true`. Handles both the block form the
+ * overlay is written in (`advisor:\n  enabled: true`) and an inline flow map
+ * (`advisor: { enabled: true }`); everything else — `enabled: false`, no
+ * `advisor` key, an absent overlay — answers false. The staged settings are
+ * what the harness itself resolves, so this is the same truth the session
+ * acts on, not a parallel decode. Exported so the staging decision in
+ * {@link runWorker} is pinned by a unit test.
+ */
+export function overlayEnablesAdvisor(overlayText: string): boolean {
+  const lines = overlayText.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const match = /^(\s*)advisor\s*:\s*(.*)$/.exec(lines[i] ?? "");
+    if (match === null) continue;
+    if (/\benabled\s*:\s*true\b/.test(match[2] ?? "")) return true;
+    const indent = match[1] ?? "";
+    for (let j = i + 1; j < lines.length; j++) {
+      const line = lines[j];
+      if (line === undefined || line.trim() === "") continue;
+      // A line at or shallower than `advisor`'s own indent ends its block.
+      if (!line.startsWith(`${indent} `) && !line.startsWith(`${indent}\t`)) break;
+      if (/^\s*enabled\s*:\s*true\s*$/.test(line)) return true;
+    }
+  }
+  return false;
+}
+
+/** A heading that begins a brief's acceptance section, whatever the brief's casing. */
+const ACCEPTANCE_HEADING = /^#{1,4}\s+acceptance\s+criteri(?:a|on)\s*$/im;
+
+/**
+ * Render the per-issue reviewer brief (#542): the acceptance section of one
+ * worker brief, wrapped so the omp advisor checks the primary against *this
+ * run's own* criteria rather than generic taste. Returns `undefined` when the
+ * brief carries no acceptance section — nothing useful to review against.
+ *
+ * The section runs from the first heading mentioning acceptance criteria to
+ * the next heading of any level (or the end of the brief). Exported so a unit
+ * test can pin the rendering without standing up a session.
+ */
+export function renderIssueWatchdog(brief: string): string | undefined {
+  const lines = brief.split(/\r?\n/);
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (ACCEPTANCE_HEADING.test(lines[i] ?? "")) {
+      start = i + 1;
+      break;
+    }
+  }
+  if (start === -1) return undefined;
+  const body: string[] = [];
+  for (let i = start; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === undefined || /^#{1,4}\s/.test(line)) break;
+    body.push(line);
+  }
+  const trimmed = body.join("\n").replace(/\n{3,}/g, "\n\n").trim();
+  if (trimmed === "") return undefined;
+  return (
+    "# Issue watchdog (rendered from this run's brief)\n\n" +
+    "This run's own acceptance criteria. Review the worker against these — not generic taste: " +
+    "a criterion is met only when the transcript or workspace shows it actually verified, and a " +
+    "worker claiming completion without evidence is a concern at least.\n\n" +
+    "## Acceptance criteria\n\n" +
+    `${trimmed}\n`
+  );
+}
+
+/**
+ * Stage the per-issue `WATCHDOG.md` into the worktree when the staged omp
+ * settings turn the advisor on (#542).
+ *
+ * The omp advisor's watchdog discovery is cwd-rooted, so per-issue guidance
+ * cannot ride the out-of-tree settings overlay: it must live inside the
+ * worktree, at `<cwd>/.omp/WATCHDOG.md`, which the managed exclude block
+ * ignores by that exact path (never the `.omp/` directory) so it can never
+ * reach the diff a worker ships or a salvage commit. Best-effort on purpose:
+ * a reviewer brief is advisory, and a worktree too broken to take it will fail
+ * the run on its own terms. Exported so the runWorker staging decision is
+ * testable without a session.
+ */
+export function stageIssueWatchdog(cwd: string, brief: string, overlayFile: string): boolean {
+  let overlayText: string;
+  try {
+    overlayText = readFileSync(overlayFile, "utf8");
+  } catch {
+    return false;
+  }
+  if (!overlayEnablesAdvisor(overlayText)) return false;
+  const watchdog = renderIssueWatchdog(brief);
+  if (watchdog === undefined) return false;
+  try {
+    const dir = join(cwd, ".omp");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "WATCHDOG.md"), watchdog);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Total USD cost of one run's advisor turns (#542).
+ *
+ * Advisor turns are recorded to a separate `__advisor*.jsonl` beside the
+ * session transcript — the primary session never sees them as `message_end`s —
+ * so without this a run with an advisor under-counts `spendUsd` and the daily
+ * cap is theater, the #46 failure mode. Reads every advisor transcript in the
+ * session's advisor directory and sums the same `usage.cost` blocks
+ * {@link costUsdFromMessage} reads off primary messages: one spelling, so the
+ * two cannot drift. Unreadable or absent transcripts bill nothing — the run
+ * with no advisor stays a zero, and a corrupt advisor log must not crash the
+ * settlement.
+ */
+export function advisorSpendUsd(sessionFile: string | undefined): number {
+  if (sessionFile === undefined || !sessionFile.endsWith(".jsonl")) return 0;
+  // The harness records advisor transcripts in the directory named after the
+  // primary transcript stem (`<dir>/<stem>/__advisor*.jsonl`); slicing the
+  // suffix is exactly what the harness's own cost loader does.
+  const dir = sessionFile.slice(0, -".jsonl".length);
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return 0;
+  }
+  let total = 0;
+  for (const name of names) {
+    if (!name.startsWith(ADVISOR_TRANSCRIPT_PREFIX) || !name.endsWith(".jsonl")) continue;
+    let text: string;
+    try {
+      text = readFileSync(join(dir, name), "utf8");
+    } catch {
+      continue;
+    }
+    for (const line of text.split("\n")) {
+      if (line.trim() === "") continue;
+      let entry: unknown;
+      try {
+        entry = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (field(entry, "type") !== "message") continue;
+      const message = field(entry, "message");
+      if (field(message, "role") !== "assistant") continue;
+      const cost = costUsdFromMessage(message);
+      if (cost !== undefined) total += cost;
+    }
+  }
+  return total;
+}
+
 /** Flatten an assistant message's content blocks to their plain text. */
 /**
  * The newest assistant text, flattened out of whatever block shape the harness

package/src/worktree.ts

@@ -156,8 +156,20 @@ const EXCLUDE_END = "# <<< omp-conductor";
  * the 2026-08-07 incident's exact shape (`.scratch82/env.sh`). Broader
  * conventions belong in a repo's own `.gitignore`, where its operator chooses
  * them, rather than being imposed by whatever dispatcher happens to be driving.
+ *
+ * The advisor watchdog (`#542`) is the deliberate exception, and the exact-path
+ * spelling is the whole point: with the advisor on, the dispatcher writes a
+ * per-issue `<worktree>/.omp/WATCHDOG.md` from the brief's acceptance criteria
+ * so the mid-run reviewer checks the worker against its own issue — and that
+ * file must never reach the diff a worker ships or the salvage commit. The
+ * standing rule says an ignored *new* file is invisible to salvage, so a name
+ * that could plausibly be a deliverable must never appear; `.omp/WATCHDOG.md`
+ * is the narrowest name that can. Only this exact file is excluded, never the
+ * `.omp/` directory — a directory-wide ignore would hide any future
+ * deliverable an operator legitimately places under `.omp/` (the very trap the
+ * `.scratch*` history describes), and the blind spot stays one path wide.
  */
-const LOCAL_EXCLUDE = [".scratch*/"];
+const LOCAL_EXCLUDE = [".scratch*/", ".omp/WATCHDOG.md"];
 
 /**
  * Adds the managed block to an `info/exclude`, preserving everything else.