omp-conductor 0.2.2 → 0.3.2

package/src/setup.ts

@@ -26,10 +26,12 @@ import { dirname, join } from "node:path";
 import { configPath, resolveCaps, stateDir } from "./config.ts";
 import {
   CONFIG_VERSION,
+  DEFAULT_AUTHORITY,
   DEFAULT_CAPS,
   DEFAULT_REPORT_SCOPE,
   type Caps,
   type ConductorConfig,
+  type OrchestratorMode,
   type ProjectConfig,
   type ReportScope,
   type RepoTarget,
@@ -67,6 +69,20 @@ export interface SetupAnswers {
    * prompt that asked it to the step that acts on it.
    */
   writeOrchestratorBrief: boolean;
+  /**
+   * Who lands green PRs and who cuts releases. Both default to the human — see
+   * {@link DEFAULT_AUTHORITY} — and the answer is what the rendered brief's
+   * Releases paragraph states, so the session can never read a delegation the
+   * config does not grant.
+   */
+  authority: ProjectConfig["authority"];
+  /**
+   * Whether the daemon runs its own triage session, or an operator already runs
+   * one elsewhere. `external` on a host where the orchestrator is a visible TUI
+   * session: the daemon then posts tier-1 escalations as issue comments for
+   * that session to drain, rather than starting a second brain.
+   */
+  orchestratorMode: OrchestratorMode;
 }
 
 /** What `gh auth status` says the active token may do. */
@@ -93,6 +109,10 @@ export const SETUP_DEFAULTS = {
   stateLabels: { inProgress: "agent:in-progress", blocked: "agent:blocked", failed: "agent:failed" },
   routingLabelPrefix: "repo:",
   defaultBranch: "main",
+  /** Both authorities start with the human; the wizard asks to move each one. */
+  authority: DEFAULT_AUTHORITY,
+  /** The daemon runs its own triage session unless an operator already runs one. */
+  orchestratorMode: "embedded",
 } as const;
 
 /**
@@ -114,6 +134,57 @@ export const REPORT_SCOPE_CHOICES: readonly { scope: ReportScope; label: string;
   },
 ];
 
+/**
+ * The Releases paragraph the brief opens with, one per authority combination.
+ *
+ * Rendered rather than written by hand for the reason the standing orders are
+ * worded from the same config: an operator who delegated merging in setup and a
+ * brief that still says "you do not merge" is a session that has been given two
+ * answers and will act on whichever it read last.
+ *
+ * A mapped type over both holders, so adding a third holder fails to compile
+ * here instead of rendering `undefined` into somebody's standing prompt.
+ */
+export const RELEASES_DEFAULTS: {
+  readonly [K in `${ProjectConfig["authority"]["merge"]}/${ProjectConfig["authority"]["release"]}`]: string;
+} = {
+  "human/human":
+    '**Default: humans release, and you do not merge.** Work ends at a green PR;\n' +
+    "merging is a separate human action, and releasing is a separate human action after\n" +
+    'that. "This needs releasing" is something you report, never something you take on.',
+  "orchestrator/orchestrator":
+    "**Delegated in setup: you merge, and you release.** Merge green PRs one at a\n" +
+    "time, re-checked against the base branch first. Cut releases per the procedure\n" +
+    "your operator writes below — do not cut one before the seven specifics are\n" +
+    "filled in.",
+  "orchestrator/human":
+    "**Delegated in setup: you merge; humans release.** Merge green PRs one at a\n" +
+    'time, re-checked against the base branch first. "This needs releasing" is\n' +
+    "something you report, never something you take on.",
+  "human/orchestrator":
+    "**Delegated in setup: humans merge; you release.** You cut releases from work a\n" +
+    "human has already merged, per the procedure your operator writes below.",
+};
+
+/**
+ * Duty 1's "the PR is green" branch, worded from `authority.merge`.
+ *
+ * The duty has to name an action, and which action depends on the grant. A
+ * session told "merging is yours" in its standing orders and told "you do not
+ * merge it" three sections into its own brief will do whichever it read last,
+ * which is the failure this whole key exists to prevent. The bullet marker is
+ * part of the value so the template line is nothing but the placeholder.
+ */
+export const MERGE_DUTY: { readonly [K in ProjectConfig["authority"]["merge"]]: string } = {
+  human:
+    "- **It is already done.** The PR is green and waiting on a human merge. Note it,\n" +
+    "  with the link, and move on. You do not merge it.",
+  orchestrator:
+    "- **It is already done.** The PR is green, and merging is yours. Re-check it\n" +
+    "  against the base branch, merge it, and note the link. One PR at a time — that\n" +
+    "  one is a hard boundary, not a preference.",
+};
+
 /** The operator's own brief, rendered into the project's workspace root. */
 export const ORCHESTRATOR_BRIEF_NAME = "ORCHESTRATOR.md";
 
@@ -336,7 +407,10 @@ function buildProject(a: SetupAnswers): ProjectConfig {
     };
   }
 
-  const escalation: ProjectConfig["escalation"] = { fallbackToIssueComment: a.fallbackToIssueComment };
+  const escalation: ProjectConfig["escalation"] = {
+    fallbackToIssueComment: a.fallbackToIssueComment,
+    orchestrator: a.orchestratorMode,
+  };
   if (a.telegramChatId !== undefined && a.telegramChatId.trim().length > 0) {
     escalation.telegramChatId = a.telegramChatId.trim();
   }
@@ -359,6 +433,7 @@ function buildProject(a: SetupAnswers): ProjectConfig {
       ? { workerModel: a.workerModel.trim() }
       : {}),
     escalation,
+    authority: { ...a.authority },
     reporting: { scope: a.reportScope },
     // Both under the state dir so one `rm -rf ~/.omp/conductor` is a complete
     // uninstall, and neither can land in a repo the daemon then tries to commit.
@@ -415,9 +490,10 @@ export function shippedBriefTemplate(): string {
 /**
  * The shipped template with a configured project's real values in it.
  *
- * Only the coordinates and the chosen scope are substituted: the policy text is
- * left exactly as shipped, because from here on the file is the operator's to
- * edit and nothing in this package reads it back.
+ * Only the coordinates, the chosen scope and the authority paragraph are
+ * substituted: the rest of the policy text is left exactly as shipped, because
+ * from here on the file is the operator's to edit and nothing in this package
+ * reads it back.
  *
  * Takes a `ProjectConfig` rather than answers so that a *later* upgrade check can
  * reproduce the same render from what is on disk, months after the wizard's
@@ -428,6 +504,8 @@ export function renderBriefForProject(p: ProjectConfig): string {
     PROJECT: p.name,
     TRACKER_REPO: p.tracker.repo,
     QUEUE_LABEL: p.queueLabel,
+    RELEASES_DEFAULT: RELEASES_DEFAULTS[`${p.authority.merge}/${p.authority.release}`],
+    MERGE_DUTY: MERGE_DUTY[p.authority.merge],
     REPORT_SCOPE: p.reporting?.scope ?? DEFAULT_REPORT_SCOPE,
   });
 }
@@ -641,6 +719,22 @@ export function summarisePlan(
     );
   }
   lines.push(`  fallback       ${a.fallbackToIssueComment ? "comment on the issue as well" : "disabled"}`);
+  lines.push(
+    `  triage         ${
+      a.orchestratorMode === "external"
+        ? "external — the daemon starts no session; an operator's own drains tier 1 off the tracker"
+        : "embedded — the daemon runs its own orchestrator session"
+    }`,
+  );
+
+  const delegated = a.authority.merge === "orchestrator" || a.authority.release === "orchestrator";
+  lines.push(
+    "",
+    `authority      merge=${a.authority.merge}  release=${a.authority.release}`,
+    delegated
+      ? "               the brief tells that session so, and it must spell the procedure out before acting"
+      : "               humans do both; workers and the conductor stop at a green PR",
+  );
 
   const chosen = REPORT_SCOPE_CHOICES.find((c) => c.scope === a.reportScope);
   const briefPath = orchestratorBriefPath(a);

package/src/store.ts

@@ -18,8 +18,12 @@ import type { RunRecord, RunState, Store } from "./types.ts";
 /**
  * States backed by a worker process. These are what worker capacity counts:
  * a slot is a process, and only a claimed or running attempt has one.
+ *
+ * Exported because it is also the answer to "is anything still writing to this
+ * run's transcript?" — `omp-conductor tail` needs that and must not re-derive
+ * it, or the two definitions drift the first time a state is added.
  */
-const LIVE_STATES: readonly RunState[] = ["claimed", "running"];
+export const LIVE_STATES: readonly RunState[] = ["claimed", "running"];
 
 /**
  * States that keep an *issue* occupied. `pushed-green` belongs here but not in
@@ -182,6 +186,16 @@ export function openStore(dbPath: string): Store {
   const countAttempts = db.query<{ n: number }, [string, number]>(
     `SELECT COUNT(*) AS n FROM runs WHERE project = ? AND issue = ?`,
   );
+  // Newest attempt for one issue. `startedAt` is millisecond-resolution and two
+  // attempts could in principle share one, so rowid breaks the tie by insertion
+  // order — a `tail` that attached to the older of two same-millisecond attempts
+  // would follow a transcript nobody is writing to any more.
+  const selectLatestRun = db.query<RunRow, [string, number]>(
+    `SELECT * FROM runs
+      WHERE project = ? AND issue = ?
+      ORDER BY startedAt DESC, rowid DESC
+      LIMIT 1`,
+  );
   const countStartedSince = db.query<{ n: number }, [string, number]>(
     `SELECT COUNT(*) AS n FROM runs WHERE project = ? AND startedAt >= ?`,
   );
@@ -255,6 +269,11 @@ export function openStore(dbPath: string): Store {
       return countAttempts.get(project, issue)?.n ?? 0;
     },
 
+    latestRun(project: string, issue: number): RunRecord | undefined {
+      const row = selectLatestRun.get(project, issue);
+      return row ? toRecord(row) : undefined;
+    },
+
     runsStartedSince(project: string, sinceEpochMs: number): number {
       return countStartedSince.get(project, sinceEpochMs)?.n ?? 0;
     },

package/src/tracker/github.ts

@@ -10,7 +10,7 @@
  * ~200-400ms) and failure classification by matching human-readable stderr
  * instead of reading a status code. Upgrade path when either bites: replace the
  * body of `gh()` with `fetch("https://api.github.com/...")` using a token from
- * `gh auth token`; the six Tracker methods above it stay untouched.
+ * `gh auth token`; the seven Tracker methods above it stay untouched.
  */
 
 import type { ProjectConfig, ReadyIssue, Tracker } from "../types.ts";
@@ -26,6 +26,47 @@ interface GhIssue {
   updatedAt: string;
 }
 
+/**
+ * Pull requests that would close an issue, with the one field that decides it.
+ *
+ * `gh issue view <n> --json closedByPullRequestsReferences` returns `id`,
+ * `number`, `repository` and `url` and no state, so a guard built on it holds an
+ * issue forever on a reference that is merged or closed-unmerged — which is
+ * exactly what a reopened issue looks like. GraphQL is the only spelling that
+ * yields `state`, so it is the spelling used.
+ *
+ * `includeClosedPrs:false` is deliberately not passed: it is not the filter it
+ * sounds like. Measured on gh 2.86.0 (2026-08-06), `veltro#260` returned a
+ * MERGED reference with the argument both true and false. The state is filtered
+ * in this consumer instead.
+ *
+ * ponytail: one page of ten. An issue closed by more than ten PRs is not a
+ * dispatch problem, and the first OPEN one already answers the question.
+ */
+const CLOSERS_QUERY = `query($owner:String!,$repo:String!,$n:Int!){
+  repository(owner:$owner,name:$repo){
+    issue(number:$n){
+      closedByPullRequestsReferences(first:10){
+        nodes{ number state isDraft url repository{ nameWithOwner } }
+      }
+    }
+  }
+}`;
+
+/** The `gh api graphql` envelope for {@link CLOSERS_QUERY}. Every level is
+ *  nullable: a deleted or wrong-numbered issue answers `null`, not an error. */
+interface ClosersResponse {
+  data?: {
+    repository?: {
+      issue?: {
+        closedByPullRequestsReferences?: {
+          nodes?: ({ state: string; isDraft: boolean; url: string } | null)[] | null;
+        } | null;
+      } | null;
+    } | null;
+  } | null;
+}
+
 /** Carries the captured stderr so callers can classify a failure without
  *  re-running the command or parsing the message text of a plain Error. */
 class GhError extends Error {
@@ -74,17 +115,45 @@ async function gh(argv: string[], stdin?: string): Promise<string> {
  * True when a label edit failed only because the requested end state already
  * holds. Adding a label is idempotent server-side, but removing one that is not
  * present is a 404, and a concurrent daemon restart can easily race into both.
+ *
+ * The quoted form is gh's own, and it is why the two operations are classified
+ * separately: `gh issue edit --remove-label x` on a label the *repository* does
+ * not define exits 1 with `'x' not found` (2.97.0), which for a removal is the
+ * end state already holding — a label nobody defined cannot be on an issue —
+ * while for an add it is a genuine failure. Removing a label the repo defines
+ * but the issue does not carry is already a silent success, so this path is
+ * reached only by the undefined-label case, most often a state label an
+ * operator declined to create at setup.
  */
 function isLabelNoop(err: unknown, op: "add" | "remove"): boolean {
   if (!(err instanceof GhError)) return false;
   const stderr = err.stderr;
   return op === "add"
     ? /already (?:has|had|exists|applied|added)|label .* already/i.test(stderr)
-    : /label does not exist|not labeled|does not have (?:that|the|this) label|label .* not found|not found on (?:this )?issue/i.test(
+    : /label does not exist|not labeled|does not have (?:that|the|this) label|label .* not found|not found on (?:this )?issue|'[^']+' not found/i.test(
         stderr,
       );
 }
 
+/**
+ * The URL of the first OPEN closer in a `gh api graphql` reply, if any.
+ *
+ * Split from the call so the state filter — the only real logic in this file —
+ * is pinned against recorded payloads instead of a live repo.
+ *
+ * A draft counts. `isDraft` is selected because the API offers it, not because
+ * it changes the answer: draft means "not ready to review", not "not pushed",
+ * and the branch behind a draft still holds the only copy of the work. Sending
+ * a second worker at it duplicates that work exactly as much as a ready PR
+ * would, so OPEN is the whole test.
+ */
+export function firstOpenCloser(raw: string): string | undefined {
+  const nodes =
+    (JSON.parse(raw) as ClosersResponse).data?.repository?.issue?.closedByPullRequestsReferences
+      ?.nodes ?? [];
+  return nodes.find((n) => n !== null && n.state === "OPEN")?.url;
+}
+
 export function makeTracker(p: ProjectConfig): Tracker {
   const repo = p.tracker.repo;
 
@@ -156,5 +225,28 @@ export function makeTracker(p: ProjectConfig): Tracker {
       // maintaining a second index of it.
       await gh(["issue", "edit", String(parent), "--repo", repo, "--add-sub-issue", String(child)]);
     },
+
+    async openCloserFor(issue: number): Promise<string | undefined> {
+      // GraphQL wants the halves of `owner/repo` separately. Config validates
+      // that spelling, so an empty half means a hand-edited config: `gh` then
+      // errors and the caller holds the candidate rather than guessing.
+      const [owner = "", name = ""] = repo.split("/");
+      const raw = await gh([
+        "api",
+        "graphql",
+        "-f",
+        `query=${CLOSERS_QUERY}`,
+        "-F",
+        `owner=${owner}`,
+        "-F",
+        `repo=${name}`,
+        // -F, not -f: the query declares $n as Int! and a string would be a
+        // type error rather than a coerced number.
+        "-F",
+        `n=${issue}`,
+      ]);
+
+      return firstOpenCloser(raw);
+    },
   };
 }

package/src/types.ts

@@ -13,7 +13,7 @@
  * counts turns, wall clock and dollars itself and kills anything over the line.
  */
 export interface Caps {
-  /** Parallel omp sessions. Two, because the homelab only has 3 CI runners and
+  /** Parallel omp sessions. Two by default: on a small self-hosted runner pool
    *  a third worker would starve its own PR checks. */
   maxConcurrentWorkers: number;
   /** Rolling-day spend ceiling; the loop stops claiming work once it is hit. */
@@ -65,6 +65,33 @@ export type ReportScope = (typeof REPORT_SCOPES)[number];
  */
 export const DEFAULT_REPORT_SCOPE: ReportScope = "material";
 
+/**
+ * Who holds an authority the daemon itself never exercises. Declared as data
+ * for the same reason as {@link REPORT_SCOPES}: the validator, the wizard and
+ * the brief renderer all enumerate the same two holders, so a third one cannot
+ * be added while any of them still knows only two.
+ */
+export const AUTHORITY_HOLDERS = ["human", "orchestrator"] as const;
+
+export type AuthorityHolder = (typeof AUTHORITY_HOLDERS)[number];
+
+/**
+ * What a project that never answered the question gets: humans keep both. A
+ * default that delegated merging would hand a fresh fleet write access to its
+ * own main branch on the strength of an unread config file.
+ */
+export const DEFAULT_AUTHORITY: ProjectConfig["authority"] = { merge: "human", release: "human" };
+
+/**
+ * Where the session that triages escalations lives. `embedded` is the daemon's
+ * own child session; `external` means an operator already runs one — a visible
+ * TUI session, say — and the daemon must not start a second brain that would
+ * re-triage the same issues from a different transcript.
+ */
+export const ORCHESTRATOR_MODES = ["embedded", "external"] as const;
+
+export type OrchestratorMode = (typeof ORCHESTRATOR_MODES)[number];
+
 /**
  * Everything the dispatcher needs to service one product: where work comes
  * from, where code goes, and what it may spend doing it. Config is per project
@@ -91,8 +118,18 @@ export interface ProjectConfig {
    * answered the question wants.
    */
   workerModel?: string;
-  /** How a stuck run reaches a human, and what to do when it cannot. */
-  escalation: { telegramChatId?: string; fallbackToIssueComment: boolean };
+  /**
+   * How a stuck run reaches a human, what to do when it cannot, and who runs
+   * the session that triages it. See {@link ORCHESTRATOR_MODES}.
+   */
+  escalation: { telegramChatId?: string; fallbackToIssueComment: boolean; orchestrator: OrchestratorMode };
+  /**
+   * Who lands green PRs and who cuts releases. The daemon never acts on this
+   * itself — it words the orchestrator's standing orders and the rendered brief
+   * scaffold with it, so config and prompt can never disagree about which of
+   * them is holding the merge button.
+   */
+  authority: { merge: AuthorityHolder; release: AuthorityHolder };
   /**
    * How loud the orchestrator is. Optional on disk — a config written before
    * this key existed loads as {@link DEFAULT_REPORT_SCOPE} — so read it through
@@ -156,6 +193,18 @@ export interface Tracker {
   /** Records that a worker split its issue, so follow-up work stays traceable
    *  to the request that spawned it. */
   linkParent(child: number, parent: number): Promise<void>;
+  /**
+   * The URL of an OPEN pull request that already closes `issue`, or undefined
+   * when none does.
+   *
+   * Admission has to ask the tracker because the store cannot answer. The busy
+   * set is built from run rows, so it only knows work *this* database recorded:
+   * a migration onto the daemon, a wiped or relocated state directory, a
+   * restore onto a new host, or simply a database younger than the PRs all
+   * present pushed-and-open work as an untouched queue item. The tracker is the
+   * only party that remembers across all of those.
+   */
+  openCloserFor(issue: number): Promise<string | undefined>;
 }
 
 /**
@@ -214,6 +263,10 @@ export interface Store {
   /** Runs backed by a worker process — what capacity counts. Subset of {@link Store.activeRuns}. */
   liveRuns(project: string): RunRecord[];
   attemptsFor(project: string, issue: number): number;
+  /** Newest attempt for one issue, whatever state it reached. `omp-conductor
+   *  tail` resolves an issue number to a transcript through this; the number is
+   *  what an operator has, the run id is not. */
+  latestRun(project: string, issue: number): RunRecord | undefined;
   runsStartedSince(project: string, sinceEpochMs: number): number;
   spendSince(project: string, sinceEpochMs: number): number;
   /** Idempotence guard so a retry loop cannot page a human repeatedly for the

package/src/unblock.ts

@@ -0,0 +1,113 @@
+/**
+ * Giving an answered block a way back into the queue.
+ *
+ * A blocked or failed run leaves its state label on the issue, and eligibility
+ * treats any state label as disqualifying (`routing.isEligible`). That is the
+ * right interlock — it is what stops a second worker landing on live work
+ * across a daemon restart — but until this verb existed it had no exit: the
+ * orchestrator's brief tells it never to hand-edit a state label, so an issue
+ * whose question it had just answered could only be left labelled, which means
+ * never re-claimed and the answer inert. Nothing surfaces that either: the
+ * issue does not fail, it simply stops existing as far as dispatch is
+ * concerned.
+ *
+ * So the clearing is a daemon-owned act, through the same tracker port the
+ * dispatcher writes labels with, and the brief's rule stays absolute. That
+ * absoluteness is worth more than the exception it replaces: orphan detection
+ * is only trustworthy while every state label on the tracker was written by
+ * this package.
+ *
+ * Nothing here writes to the store, and that is a decision rather than an
+ * omission. `RunState` describes what a worker process did; an answer is the
+ * one event that happens outside every run, so no member fits it — folding it
+ * into `merged` or `killed` would make `status` describe a run that never
+ * reached either. Eligibility is read off the tracker's labels and never off a
+ * run row, so the store has nothing to say here. Leaving the history alone is
+ * also what keeps `maxAttemptsPerIssue` honest: an answered block still spent a
+ * worker's whole budget, and the same question answered twice is a loop the cap
+ * exists to stop.
+ */
+
+import { LIVE_STATES } from "./store.ts";
+import type { Caps, ProjectConfig, RunRecord, Store, Tracker } from "./types.ts";
+
+/** What one `unblock` did, and the state it found around it. */
+export interface UnblockOutcome {
+  /** State labels the tracker was asked to drop. */
+  cleared: string[];
+  /** Attempts this issue has already spent. Unchanged by the unblock. */
+  attemptsUsed: number;
+  /** Newest attempt, when the store has one for this issue at all. */
+  latest?: RunRecord;
+}
+
+/**
+ * Drop both terminal state labels, whichever the issue is actually carrying.
+ *
+ * Both unconditionally, because the tracker is the only source of truth for
+ * which one is set and this process cannot read that back through the Tracker
+ * port — inferring it from the newest run row would be a guess that goes wrong
+ * exactly when a human has relabelled something by hand. Removing a label an
+ * issue does not carry is a no-op: `gh issue edit --remove-label` exits 0 on an
+ * absent label (verified against gh 2.97.0), and the adapter swallows the 404
+ * older paths return for one.
+ *
+ * `agent:in-progress` is deliberately not in the set. It means a worker process
+ * exists, which is not something an operator can answer away, and clearing it
+ * from under a live run is how two workers end up on one issue.
+ */
+export async function unblockIssue(
+  project: ProjectConfig,
+  tracker: Tracker,
+  store: Store,
+  issue: number,
+): Promise<UnblockOutcome> {
+  const cleared: string[] = [];
+  for (const label of new Set([project.stateLabels.blocked, project.stateLabels.failed])) {
+    await tracker.removeLabel(issue, label);
+    cleared.push(label);
+  }
+
+  const latest = store.latestRun(project.name, issue);
+  return {
+    cleared,
+    attemptsUsed: store.attemptsFor(project.name, issue),
+    ...(latest === undefined ? {} : { latest }),
+  };
+}
+
+/**
+ * What the operator reads back. It promises a re-claim only when one can
+ * actually happen: a live run still owns the issue through `agent:in-progress`,
+ * and a spent attempt budget makes the next tick escalate rather than dispatch.
+ * Either promised blindly would send someone away believing work had resumed.
+ */
+export function formatUnblock(issue: number, o: UnblockOutcome, project: ProjectConfig, caps: Caps): string {
+  const latest = o.latest;
+  const lines = [`#${issue}: cleared ${o.cleared.join(", ")}`];
+
+  if (latest === undefined) {
+    lines.push("  attempts   none recorded — the labels were cleared anyway; eligibility is read off the tracker");
+  } else {
+    lines.push(
+      `  attempts   ${o.attemptsUsed} of ${caps.maxAttemptsPerIssue} used, newest ${latest.state} — ` +
+        "unchanged, an answered block still spent a worker",
+    );
+  }
+
+  if (latest !== undefined && LIVE_STATES.includes(latest.state)) {
+    lines.push(
+      `  in flight  attempt ${latest.attempt} is ${latest.state}, so the issue keeps ` +
+        `"${project.stateLabels.inProgress}" until it ends — nothing is re-claimed before then`,
+    );
+  } else if (o.attemptsUsed >= caps.maxAttemptsPerIssue) {
+    lines.push(
+      `  next tick  not eligible: all ${caps.maxAttemptsPerIssue} attempts are spent, so the next tick escalates ` +
+        "instead of re-claiming. Raise maxAttemptsPerIssue with /conductor setup, or rewrite the issue.",
+    );
+  } else {
+    lines.push(`  next tick  eligible again, as long as the issue still carries "${project.queueLabel}"`);
+  }
+
+  return lines.join("\n");
+}

package/src/worker.ts

@@ -43,6 +43,15 @@ export interface WorkerOpts {
    */
   model?: string;
   onTurn?: (n: number) => void;
+  /**
+   * The transcript path, handed over the moment the session opens it rather
+   * than at the end with {@link WorkerResult.sessionFile}. Both report the same
+   * path; only this one arrives while there is still something to watch, which
+   * is what `omp-conductor tail` attaches to. Never called for a session that
+   * opened no transcript — there is no path to report, and an empty string
+   * would be a path that fails to open rather than an absence.
+   */
+  onSessionFile?: (path: string) => void;
 }
 
 /**
@@ -145,6 +154,11 @@ export async function runWorker(
     ...(o.model === undefined ? {} : { model: o.model }),
   });
 
+  // Before the first turn, not after the last: a caller that only learns the
+  // transcript path from the result learns it once the run it wanted to watch
+  // is already over.
+  if (session.sessionFile !== undefined) o.onSessionFile?.(session.sessionFile);
+
   // Every exit below reports the session's own facts the same way: the
   // transcript it actually opened, and any model downgrade it announced. Read at
   // return time so a session that materialises either late is still reported