omp-conductor 0.12.0 → 0.13.0

package/src/types.ts

@@ -61,6 +61,9 @@ export interface Caps {
   /** Turn ceiling for one worker — catches loops that are burning tokens
    *  without converging. */
   workerMaxTurns: number;
+  /** Maximum turn budget an operator may assign to one issue's next attempt.
+   * Defaults to twice that issue's effective `workerMaxTurns`. */
+  workerMaxTurnsCeiling: number;
   /** Wall-clock ceiling for one worker (90 min): a session that is merely
    *  stuck spends no turns, so turns alone cannot detect it. */
   workerWallClockMs: number;
@@ -358,6 +361,8 @@ export const RELEASE_REQUIREMENTS = [
   "no-open-prs",
   /** Nothing still carries the queue label: the batch is finished, not paused. */
   "queue-drained",
+  /** The newest observed post-merge check for the released repo's base branch is green. */
+  "base-branch-green",
   /** The epic this release closes has no open children left. */
   "epic-children-closed",
 ] as const;
@@ -661,6 +666,8 @@ export type PrState = "merged" | "closed" | "open";
 /** Result of independently checking a worker's claimed green pull request. */
 export interface PrVerification {
   status: "green" | "pending" | "failed";
+  /** Full live head SHA read in the same tracker request as the verdict. */
+  headSha: string;
   reason: string;
 }
 
@@ -711,6 +718,10 @@ export const SETTLEMENT_FLAG_KINDS = [
   "assertions-removed",
   /** A named timeout in a test file went up. */
   "test-timeout-raised",
+  /** A terminal run recovered an OPEN PR by exact issue, repo and branch identity. */
+  "pr-adopted",
+  /** A workflow on the merge commit's base branch failed after settlement. */
+  "base-branch-red",
 ] as const;
 
 export type SettlementFlagKind = (typeof SETTLEMENT_FLAG_KINDS)[number];
@@ -722,7 +733,8 @@ export type SettlementFlagKind = (typeof SETTLEMENT_FLAG_KINDS)[number];
  */
 export interface SettlementFlag {
   kind: SettlementFlagKind;
-  /** Repo-relative path, or `(report)` for a finding about the report itself. */
+  /** Repo-relative path, `(report)` for report evidence, or `(base branch)` for
+   *  a post-merge workflow result. */
   file: string;
   /** 1-based line in the side of the diff the evidence came from: the
    *  post-image for an added line, the pre-image for a removed one. */
@@ -736,24 +748,52 @@ export interface SettlementFlag {
 /** Tracker lifecycle state for an issue. Undefined means the adapter could not tell. */
 export type IssueState = "open" | "closed";
 
+/** Read-after-write issue facts used to validate an eventually-consistent queue candidate. */
+export interface IssueSnapshot {
+  readonly state: IssueState;
+  readonly labels: readonly string[];
+}
+
 /**
  * An OPEN pull request that already closes an issue, as admission sees it.
  *
- * The head branch travels with the URL because admission has two different
- * questions to answer about the same PR, and only one of them the URL can
- * answer. "Is there finished work here" is a URL question. "Is this *our*
- * retained work, resumed" is a branch question, because a run can retain a
- * branch and never produce a PR: on 2026-08-09T00:47Z veltro#324 attempt 1 was
- * killed at the turns cap before its worker opened one, and the PR that later
- * appeared on that exact branch (chad#438) could never be matched by URL
- * equality against a `prUrl` the terminal run never recorded (#50).
+ * The repository travels with the URL because recovery has to prove three
+ * independent identities before adopting a PR onto a terminal run: closing
+ * issue, retained branch, and routed repository (#245). Admission needs only
+ * the URL/branch pair, but weakening the shared answer would make recovery
+ * parse provenance back out of a presentation URL.
+ *
+ * The head branch recognises a continuation the store never saw a PR for: on
+ * 2026-08-09T00:47Z veltro#324 attempt 1 was killed at the turns cap before its
+ * worker opened one, and the PR that later appeared on that exact branch
+ * (chad#438) could never be matched by URL equality against a `prUrl` the
+ * terminal run never recorded (#50).
  */
 export interface OpenCloser {
   url: string;
   /** Head branch of the open PR, for retained-continuation identity. */
   headRefName: string;
+  /** Canonical `owner/repo` identity supplied by the tracker. */
+  repo: string;
+}
+/** The merge identity needed to observe the exact base-branch push it produced. */
+export interface MergedPrInfo {
+  mergeSha: string;
+  baseRef: string;
+}
+
+/** One GitHub Actions workflow run, normalised before it crosses the tracker port. */
+export interface WorkflowRun {
+  id: number;
+  workflowId: number;
+  name: string;
+  status: string;
+  conclusion?: string;
+  url: string;
+  createdAt: string;
 }
 
+
 /**
  * Deliberately narrow so a Gitea or local-file tracker can drop in later.
  * Nothing here is GitHub-shaped; the GitHub adapter owns `gh` entirely.
@@ -786,44 +826,64 @@ export interface Tracker {
    */
   parentOf(issue: number): Promise<number | undefined>;
   /**
-   * The OPEN pull request that already closes `issue`, or undefined when none
-   * does.
+   * The first 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.
-   *
-   * Returns {@link OpenCloser} rather than a bare URL because the branch is the
-   * half admission needs to recognise a continuation the store never saw a PR
-   * for; see that type for the veltro#324 case that forced the widening.
+   * Admission asks this any-open question because the store only knows work
+   * recorded in this database. A migrated daemon, restored host, or younger
+   * database can otherwise dispatch duplicate work onto an issue whose PR is
+   * already open.
    */
   openCloserFor(issue: number): Promise<OpenCloser | undefined>;
+  /**
+   * Every OPEN pull request that closes `issue`.
+   *
+   * Salvage recovery must inspect the full answer: an unrelated closer may be
+   * listed before the PR whose branch and repository exactly match the
+   * recovered run. An empty array means no OPEN closer; a thrown lookup remains
+   * fail-closed.
+   */
+  openClosersFor(issue: number): Promise<OpenCloser[]>;
   /**
    * Whether an issue is still open, or undefined when tracker/network state is
    * ambiguous. Cleanup must never interpret undefined as permission to delete.
    */
   issueState(issue: number): Promise<IssueState | undefined>;
+  /**
+   * Direct REST state and labels for final admission validation, or undefined
+   * when either fact cannot be read safely.
+   */
+  issueSnapshot(issue: number): Promise<IssueSnapshot | undefined>;
   /**
    * The state of one specific pull request, or undefined when this adapter
    * could not tell — a network failure, a deleted PR, a URL it cannot parse.
    * Undefined never means "no".
    *
-   * Deliberately separate from {@link Tracker.openCloserFor}, which answers a
-   * different question: that one asks "should this candidate be admitted", and
-   * answers undefined for merged, closed-unmerged, no PR at all and a deleted
-   * PR alike, because admission treats all four the same. This one asks "did
+   * Deliberately separate from {@link Tracker.openCloserFor}, which asks
+   * whether any OPEN closing PR exists and answers undefined for merged,
+   * closed-unmerged, no PR at all and a deleted PR alike. This one asks "did
    * *this* run's PR land", where those answers are opposites. Collapsing them
    * is how a PR a human rejected gets recorded as merged.
    */
   prState(url: string): Promise<PrState | undefined>;
+  /** The merge commit and base ref for a merged pull request. */
+  mergedPrInfo(url: string): Promise<MergedPrInfo | undefined>;
+  /** Workflow runs GitHub associated with one exact commit SHA. */
+  workflowRunsAt(repo: string, sha: string): Promise<WorkflowRun[] | undefined>;
+  /** The newest run of this workflow on the base branch before `before`.
+   *  `null` means no earlier run; `undefined` means the history could not be read. */
+  previousWorkflowRun(
+    repo: string,
+    workflowId: number,
+    branch: string,
+    before: string,
+  ): Promise<WorkflowRun | null | undefined>;
   /**
-   * Verify that a worker's pull request is open, ready, still at the reported
-   * head, and has a non-empty terminal-success check rollup.
+   * Verify that a pull request is open, ready, and has a non-empty
+   * terminal-success check rollup. When `expectedHead` is supplied, also
+   * require the live head to match it.
    */
-  verifyPr(url: string, expectedHead: string): Promise<PrVerification | undefined>;
+  verifyPr(url: string, expectedHead?: string): Promise<PrVerification | undefined>;
   /**
    * The pull request's diff, or undefined when this adapter could not produce
    * one — an unparseable URL, a deleted PR, a flaky network.
@@ -923,11 +983,23 @@ export const RECOVERY_ACTIONS = [
 
 export type RecoveryAction = (typeof RECOVERY_ACTIONS)[number];
 
+/** What the daemon learned about workflows on a mediated merge's base commit. */
+export const BASE_CHECK_STATES = [
+  "pending",
+  "green",
+  "red",
+  "red-preexisting",
+  "unknown",
+] as const;
+
+export type BaseCheckState = (typeof BASE_CHECK_STATES)[number];
+
 /**
  * Execution state is separate from the tracker's own labels on purpose: labels
  * are coarse and human-editable, while the loop needs to distinguish "pushed
  * and green, waiting on merge" from "merged" to decide what to do on restart.
  */
+
 export type RunState =
   | "claimed"
   | "running"
@@ -940,6 +1012,9 @@ export type RunState =
   | "blocked"
   | "failed"
   | "killed"
+  /** Terminal operator action. The worker cannot resume and the attempt does
+   *  not consume implementation-failure or continuation budgets. */
+  | "stopped"
   /** In flight when its daemon process died; reconciled at the next startup. */
   | "orphaned";
 
@@ -967,6 +1042,12 @@ export interface RunRecord {
   prUrl?: string;
   /** Pull request head the worker observed after its deterministic CI watcher exited. */
   headSha?: string;
+  /** Merge commit and actual base ref read from the merged pull request. */
+  mergeSha?: string;
+  baseRef?: string;
+  /** Post-merge workflow verdict. Pending is revisited by the tick sweep. */
+  baseCheck?: BaseCheckState;
+  baseCheckAt?: number;
   /** Commit this run's uncommitted work was preserved as before its worktree
    *  was removed, on the run's own branch. Absent means the daemon found
    *  nothing to save, or never looked — see {@link RunRecord.salvageError}. */
@@ -1005,11 +1086,22 @@ export interface RunRecord {
   recoveredAt?: number;
 }
 
+/** A one-shot turn budget waiting for one issue's next claimed attempt. */
+export interface TurnOverride {
+  project: string;
+  issue: number;
+  maxTurns: number;
+  setAt: number;
+}
+
 export type AdmissionHoldReason =
   | "capacity"
   | "issue-active"
   | "failed-attempts"
   | "continuations"
+  | "issue-closed"
+  | "issue-state-lookup-error"
+  | "issue-dequeued"
   | "parent-lookup-error"
   | "sibling-active"
   | "repo-active"
@@ -1049,6 +1141,7 @@ export type FrictionAdmissionReason =
   | "failed-attempts"
   | "continuations"
   | "parent-lookup-error"
+  | "issue-state-lookup-error"
   | "open-pr-lookup-error"
   | "unroutable:no-repo-label"
   | "unroutable:multiple-repo-labels"
@@ -1251,6 +1344,7 @@ export interface LabelOp {
  * the two disagree.
  */
 export interface Store {
+  /** A claimed run atomically consumes and applies its issue's pending turn override. */
   createRun(r: Omit<RunRecord, "id">): RunRecord;
   updateRun(id: string, patch: Partial<RunRecord>): void;
   getRun(id: string): RunRecord | undefined;
@@ -1263,6 +1357,10 @@ export interface Store {
   /** Newest attempt per issue for the live board. Non-merged work remains
    * visible; merged rows are bounded by the supplied recent-history cutoff. */
   recentRuns(project: string, mergedSinceEpochMs: number): RunRecord[];
+  /** Merged rows whose post-merge workflow verdict is still pending, oldest first. */
+  runsNeedingBaseCheck(project: string, limit?: number): RunRecord[];
+  /** Newest checked merge per routed repository inside the supplied history window. */
+  latestBaseChecks(project: string, sinceEpochMs: number): RunRecord[];
   /** Newest attempt per issue that preserved work or failed to, so `status`
    *  can name every WIP tip a re-claim would build on and every tree that is
    *  still the only copy. */
@@ -1281,6 +1379,17 @@ export interface Store {
    *  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;
+  /** Persist a one-shot ceiling and append the operator action to its audit ledger. */
+  setTurnOverride(project: string, issue: number, maxTurns: number, setAt?: number): void;
+  turnOverride(project: string, issue: number): number | undefined;
+  /** Administrative deletion; claimed runs consume inside `createRun`'s transaction. */
+  clearTurnOverride(project: string, issue: number): void;
+  listTurnOverrides(project: string): TurnOverride[];
+  /** Durable override actions, newest first; consumption never removes these rows. */
+  turnOverrideLedger(
+    project: string,
+    opts?: { issue?: number; limit?: number },
+  ): TurnOverride[];
   /** Every attempt of one issue that settled with a report, in attempt order.
    *  The settlement audit pools these as prior disclosures when a later
    *  attempt is reconciled (#199). Rows with no report (pre-#199, or killed
@@ -1468,6 +1577,9 @@ export interface Escalation {
    *  escalation pages now or is held for the digest under the project's
    *  `reporting.interruptOn` policy (#229). */
   category?: InterruptCategory;
+  /** Deliver now even when policy would defer this category to the digest.
+   *  Used only when the digest's own orchestrator loop is unavailable. */
+  urgent?: true;
 }
 
 /** A tier-2 escalation the project's interrupt policy deferred to the digest. */
@@ -1501,6 +1613,7 @@ export const DEFAULT_CAPS: Caps = {
   // guard silently watches the wrong meter (#110).
   planUsage: null,
   workerMaxTurns: 120,
+  workerMaxTurnsCeiling: 240,
   workerWallClockMs: 90 * 60 * 1000,
   maxAttemptsPerIssue: 2,
   maxContinuationsPerIssue: 2,

package/src/verbs/actions.ts

@@ -14,8 +14,9 @@
  * enough to actually write.
  */
 
-import { credentialedEnv, openRunPr, pushRunBranch, repoSlugFor } from "../gitops.ts";
-import type { ProjectConfig, ReleaseShape } from "../types.ts";
+import { credentialedEnv, openRunPr, pushRunBranch, repoSlugFor, scrubUserinfo } from "../gitops.ts";
+import { ensureMirror } from "../worktree.ts";
+import type { ProjectConfig, ReleaseShape, RepoTarget } from "../types.ts";
 import type { ActionOutcome, ReleaseExecution, VerbActions } from "./server.ts";
 
 /**
@@ -47,6 +48,25 @@ export type CommandRunner = (
   opts: { cwd?: string; env?: Record<string, string> },
 ) => Promise<CommandRun>;
 
+export type MirrorPreparer = (repo: RepoTarget, mirrorRoot: string) => Promise<string>;
+
+type CommitOutcome = { ok: true; sha: string } | { ok: false; stderr: string };
+
+const FULL_COMMIT = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i;
+const RELEASE_TAG_CONFIG = [
+  "-c",
+  "user.name=conductor",
+  "-c",
+  "user.email=conductor@invalid",
+  "-c",
+  "tag.gpgSign=false",
+];
+
+function commitFrom(stdout: string): string | undefined {
+  const value = stdout.trim().split(/\s+/, 1)[0];
+  return value !== undefined && FULL_COMMIT.test(value) ? value.toLowerCase() : undefined;
+}
+
 const spawnCommand: CommandRunner = async (argv, opts) => {
   const proc = Bun.spawn(argv, {
     // Always a closed stream, matching the tracker adapter: a command that does
@@ -65,8 +85,11 @@ const spawnCommand: CommandRunner = async (argv, opts) => {
   return { ok: code === 0 && !proc.signalCode, stdout, stderr };
 };
 
-function failed(run: CommandRun, argv: string[]): ActionOutcome {
-  return { ok: false, stderr: run.stderr.trim() || `\`${argv.join(" ")}\` failed with no stderr` };
+function failed(run: CommandRun, argv: string[]): { ok: false; stderr: string } {
+  return {
+    ok: false,
+    stderr: scrubUserinfo(run.stderr.trim() || `\`${argv.join(" ")}\` failed with no stderr`),
+  };
 }
 
 /**
@@ -75,7 +98,11 @@ function failed(run: CommandRun, argv: string[]): ActionOutcome {
  * `run` is injected so the release and tracker paths can be exercised without
  * a live repository; production callers never pass it.
  */
-export function githubVerbActions(project: ProjectConfig, run: CommandRunner = spawnCommand): VerbActions {
+export function githubVerbActions(
+  project: ProjectConfig,
+  run: CommandRunner = spawnCommand,
+  prepareMirror: MirrorPreparer = ensureMirror,
+): VerbActions {
   const env = (): Record<string, string> => credentialedEnv();
 
   const gh = async (argv: string[], cwd?: string): Promise<ActionOutcome> => {
@@ -84,6 +111,45 @@ export function githubVerbActions(project: ProjectConfig, run: CommandRunner = s
     return result.ok ? { ok: true, detail: result.stdout.trim() || undefined } : failed(result, full);
   };
 
+  const git = async (mirror: string, args: string[]): Promise<{ argv: string[]; result: CommandRun }> => {
+    const argv = ["git", "-C", mirror, ...args];
+    return { argv, result: await run(argv, { env: env() }) };
+  };
+
+  const readCommit = async (mirror: string, args: string[], fact: string): Promise<CommitOutcome> => {
+    const { argv, result } = await git(mirror, args);
+    if (!result.ok) return failed(result, argv);
+    const sha = commitFrom(result.stdout);
+    return sha === undefined
+      ? { ok: false, stderr: `${fact} returned no full commit SHA` }
+      : { ok: true, sha };
+  };
+
+  const liveDefaultHead = (mirror: string, repo: RepoTarget): Promise<CommitOutcome> =>
+    readCommit(
+      mirror,
+      ["ls-remote", "origin", `refs/heads/${repo.defaultBranch}`],
+      `live ${repo.defaultBranch} lookup`,
+    );
+
+  const releaseTargetMoved = (repo: RepoTarget, target: string, live: string): { ok: false; stderr: string } => ({
+    ok: false,
+    stderr:
+      `refusing release: target ${target} is behind live ${repo.defaultBranch} ${live}. ` +
+      "Refresh the release status and retry so the tag contains every merged change.",
+  });
+
+  const releaseMirror = async (repo: RepoTarget): Promise<{ ok: true; path: string } | { ok: false; stderr: string }> => {
+    try {
+      return { ok: true, path: await prepareMirror(repo, project.mirrorRoot) };
+    } catch (err) {
+      return {
+        ok: false,
+        stderr: `could not refresh ${repo.name}'s release mirror: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+  };
+
   return {
     releasableShapes: GITHUB_RELEASABLE_SHAPES,
 
@@ -133,18 +199,64 @@ export function githubVerbActions(project: ProjectConfig, run: CommandRunner = s
       if (execution.shape === "github-release") {
         return gh(["release", "create", tag, "--repo", slug, "--generate-notes"]);
       }
-      // The two git shapes act on the project's mirror of the repo, which is
-      // the only checkout the daemon owns. A tag is cut against the mirror's
-      // view of the default branch and pushed from there.
-      const mirror = `${project.mirrorRoot}/${execution.repo.name}.git`;
+      // The two git shapes act on the project's serialized, freshly fetched
+      // mirror. The live read on either side of tag creation closes the stale
+      // mirror and branch-moved-during-release windows (#258); the push path
+      // repeats the guard because a branch may move between the two verbs.
+      const prepared = await releaseMirror(execution.repo);
+      if (!prepared.ok) return prepared;
+      const mirror = prepared.path;
       if (execution.shape === "git-tag") {
-        const argv = ["git", "-C", mirror, "tag", "-a", tag, "-m", `release ${tag}`, `origin/${execution.repo.defaultBranch}`];
-        const result = await run(argv, { env: env() });
-        return result.ok ? { ok: true, detail: `tagged ${tag}` } : failed(result, argv);
+        const target = await readCommit(
+          mirror,
+          ["rev-parse", `refs/remotes/origin/${execution.repo.defaultBranch}^{commit}`],
+          `refreshed ${execution.repo.defaultBranch}`,
+        );
+        if (!target.ok) return target;
+        const liveBefore = await liveDefaultHead(mirror, execution.repo);
+        if (!liveBefore.ok) return liveBefore;
+        if (target.sha !== liveBefore.sha) return releaseTargetMoved(execution.repo, target.sha, liveBefore.sha);
+
+        // An unattended daemon cannot depend on a host-level Git identity or a
+        // signing key with an interactive passphrase.
+        const tagged = await git(mirror, [
+          ...RELEASE_TAG_CONFIG,
+          "tag",
+          "-a",
+          tag,
+          "-m",
+          `release ${tag}`,
+          target.sha,
+        ]);
+        if (!tagged.result.ok) return failed(tagged.result, tagged.argv);
+
+        const liveAfter = await liveDefaultHead(mirror, execution.repo);
+        if (!liveAfter.ok || liveAfter.sha !== target.sha) {
+          const removed = await git(mirror, ["tag", "-d", tag]);
+          const reason = liveAfter.ok
+            ? releaseTargetMoved(execution.repo, target.sha, liveAfter.sha).stderr
+            : `created ${tag} at ${target.sha}, but could not verify the live default branch: ${liveAfter.stderr}`;
+          return {
+            ok: false,
+            stderr:
+              reason +
+              (removed.result.ok
+                ? " The unpushed local tag was deleted."
+                : ` WARNING: the unpushed local tag could not be deleted: ${failed(removed.result, removed.argv).stderr}`),
+          };
+        }
+        return { ok: true, sha: target.sha, detail: `tagged ${tag} at ${target.sha}` };
       }
-      const argv = ["git", "-C", mirror, "push", "origin", `refs/tags/${tag}`];
-      const result = await run(argv, { env: env() });
-      return result.ok ? { ok: true, detail: `pushed refs/tags/${tag}` } : failed(result, argv);
+
+      const target = await readCommit(mirror, ["rev-parse", `refs/tags/${tag}^{commit}`], `tag ${tag}`);
+      if (!target.ok) return target;
+      const live = await liveDefaultHead(mirror, execution.repo);
+      if (!live.ok) return live;
+      if (target.sha !== live.sha) return releaseTargetMoved(execution.repo, target.sha, live.sha);
+      const pushed = await git(mirror, ["push", "origin", `refs/tags/${tag}`]);
+      return pushed.result.ok
+        ? { ok: true, sha: target.sha, detail: `pushed refs/tags/${tag} at ${target.sha}` }
+        : failed(pushed.result, pushed.argv);
     },
   };
 }

package/src/verbs/protocol.ts

@@ -293,9 +293,10 @@ export const VERB_SPECS: Readonly<Record<VerbName, VerbSpec>> = {
     mutating: false,
     allowedRoles: ["worker", "orchestrator"],
     description:
-      "Read one pull request's live state: is it open, is its head still the sha you pushed, and are " +
-      "its checks green. This is the daemon's own merge-gate verdict, not a summary of it. A poll, not " +
-      "a watcher — call it again after waiting. A worker may omit prUrl and gets its own run's.",
+      "Read one pull request's live state and current head: is it open and are its checks green. " +
+      "Optionally compare that head with one the caller already observed. This is the daemon's own " +
+      "merge-gate verdict, not a summary of it. A poll, not a watcher — call it again after waiting. " +
+      "A worker may omit prUrl and gets its own run's.",
     args: {
       prUrl: {
         type: "string",
@@ -304,10 +305,10 @@ export const VERB_SPECS: Readonly<Record<VerbName, VerbSpec>> = {
       },
       headSha: {
         type: "string",
-        required: true,
+        required: false,
         description:
-          "The head you believe is on the branch — the sha conductor_push returned. If the branch has " +
-          "moved, the answer names both shas.",
+          "Optional: an expected head to compare against; omit it to read the current head. If the " +
+          "branch has moved, the answer names both shas.",
       },
     },
     roleRefusalText: (role) => `conductor_pr_status is not open to a ${role} session.`,