omp-conductor 0.3.17 → 0.3.19

package/src/tracker/github.ts

@@ -10,10 +10,17 @@
  * ~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 nine Tracker methods above it stay untouched.
+ * `gh auth token`; the eleven Tracker methods above it stay untouched.
  */
 
-import type { PrState, ProjectConfig, ReadyIssue, Tracker } from "../types.ts";
+import type {
+  IssueState,
+  PrState,
+  PrVerification,
+  ProjectConfig,
+  ReadyIssue,
+  Tracker,
+} from "../types.ts";
 
 /** The subset of `gh issue list --json` output this adapter reads. Fields the
  *  API can return as null are typed as such so the mapping has to handle it. */
@@ -53,6 +60,12 @@ const CLOSERS_QUERY = `query($owner:String!,$repo:String!,$n:Int!){
   }
 }`;
 
+const PARENT_QUERY = `query($owner:String!,$repo:String!,$n:Int!){
+  repository(owner:$owner,name:$repo){
+    issue(number:$n){ parent{ number } }
+  }
+}`;
+
 /** 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 {
@@ -67,6 +80,23 @@ interface ClosersResponse {
   } | null;
 }
 
+interface GhCheck {
+  __typename?: string;
+  name?: string;
+  context?: string;
+  status?: string;
+  conclusion?: string;
+  state?: string;
+  detailsUrl?: string;
+}
+
+interface GhPrVerification {
+  state?: string;
+  isDraft?: boolean;
+  headRefOid?: string;
+  statusCheckRollup?: GhCheck[] | 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 {
@@ -163,7 +193,98 @@ export function firstOpenCloser(raw: string): string | undefined {
  * be answered, confidently, about some other repository's pull request. A
  * settle sweep that acted on that answer would mark the wrong run merged.
  */
-const PR_URL = /^https?:\/\/[^\s/]+\/[^\s/]+\/[^\s/]+\/pull\/\d+/;
+const PR_URL = /^https?:\/\/[^\s/]+\/[^\s/]+\/[^\s/]+\/pull\/\d+\/?$/;
+
+type CheckVerdict = PrVerification["status"];
+
+function checkName(check: GhCheck): string {
+  return check.name ?? check.context ?? "(unnamed check)";
+}
+
+function checkVerdict(check: GhCheck): CheckVerdict {
+  if (check.__typename === "StatusContext" || check.state !== undefined) {
+    if (check.state === "SUCCESS") return "green";
+    if (check.state === "PENDING" || check.state === "EXPECTED") return "pending";
+    return "failed";
+  }
+  if (check.status !== "COMPLETED") return "pending";
+  if (check.conclusion === "SUCCESS" || check.conclusion === "SKIPPED") return "green";
+  return "failed";
+}
+
+/**
+ * Verify one `gh pr view --json state,isDraft,headRefOid,statusCheckRollup`
+ * payload against the worker-observed head. A missing rollup is pending rather
+ * than green because GitHub may not have created the checks yet.
+ */
+export function prVerificationFrom(raw: string, expectedHead: string): PrVerification {
+  const pr = JSON.parse(raw) as GhPrVerification;
+  if (pr.state !== "OPEN") {
+    return { status: "failed", reason: `PR is ${pr.state ?? "unknown"}, expected OPEN` };
+  }
+  if (pr.isDraft !== false) {
+    return { status: "failed", reason: "PR is draft or draft state is unknown" };
+  }
+  if (pr.headRefOid?.toLowerCase() !== expectedHead.toLowerCase()) {
+    return {
+      status: "failed",
+      reason: `PR head changed: expected ${expectedHead}, found ${pr.headRefOid ?? "unknown"}`,
+    };
+  }
+
+  const checks = pr.statusCheckRollup ?? [];
+  if (checks.length === 0) {
+    return { status: "pending", reason: "GitHub has not reported any checks yet" };
+  }
+  const failed = checks.filter((check) => checkVerdict(check) === "failed");
+  if (failed.length > 0) {
+    return {
+      status: "failed",
+      reason: `Checks failed: ${failed.map((check) => `${checkName(check)} (${check.conclusion ?? check.state ?? "unknown"})`).join(", ")}`,
+    };
+  }
+  const pending = checks.filter((check) => checkVerdict(check) === "pending");
+  if (pending.length > 0) {
+    return {
+      status: "pending",
+      reason: `Checks pending: ${pending.map(checkName).join(", ")}`,
+    };
+  }
+  return { status: "green", reason: `${checks.length} checks succeeded or were skipped` };
+}
+
+function failedCheck(raw: string): GhCheck | undefined {
+  const checks = (JSON.parse(raw) as GhPrVerification).statusCheckRollup ?? [];
+  return checks.find((check) => checkVerdict(check) === "failed");
+}
+
+function runLogArgs(detailsUrl: string): string[] | undefined {
+  const match =
+    /^https:\/\/github\.com\/([^/]+\/[^/]+)\/actions\/runs\/(\d+)(?:\/job\/(\d+))?/.exec(
+      detailsUrl,
+    );
+  if (match?.[1] === undefined || match[2] === undefined) return undefined;
+  return [
+    "run",
+    "view",
+    match[2],
+    "--repo",
+    match[1],
+    ...(match[3] === undefined ? [] : ["--job", match[3]]),
+    "--log-failed",
+  ];
+}
+
+function conciseLog(raw: string): string | undefined {
+  const lines = raw
+    .replaceAll(/\u001b\[[0-9;]*m/g, "")
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .filter((line) => line.trim() !== "")
+    .slice(-8)
+    .map((line) => line.slice(0, 240));
+  return lines.length === 0 ? undefined : lines.join("\n");
+}
 
 /**
  * GitHub's PR state spelling mapped onto {@link PrState}.
@@ -189,28 +310,43 @@ export function prStateFrom(raw: string): PrState | undefined {
   }
 }
 
+/** GitHub's issue state spelling, kept fail-closed for cleanup decisions. */
+export function issueStateFrom(raw: string): IssueState | undefined {
+  switch (raw.trim()) {
+    case "OPEN":
+      return "open";
+    case "CLOSED":
+      return "closed";
+    default:
+      return undefined;
+  }
+}
+
 /**
- * Parent number from a `gh issue view --json parent` payload, or undefined
- * when the issue has no parent. Throws on a payload that claims a parent but
- * does not carry a usable number — admission would otherwise treat garbage as
- * "no parent" and skip the epic soft-cap.
+ * Parent number from a raw GraphQL response, or undefined when the issue has
+ * no parent. Throws when the issue or claimed parent is malformed — admission
+ * must not turn an unknown relationship into permission to run siblings.
  */
 export function parentNumberFrom(raw: string): number | undefined {
-  const parsed = JSON.parse(raw) as { parent: { number?: unknown } | null };
-  if (parsed.parent == null) return undefined;
-  const n = parsed.parent.number;
+  const parsed = JSON.parse(raw) as {
+    data?: { repository?: { issue?: { parent?: { number?: unknown } | null } | null } | null };
+  };
+  const issue = parsed.data?.repository?.issue;
+  if (issue == null) throw new Error("unexpected missing issue in parent response");
+  if (issue.parent == null) return undefined;
+  const n = issue.parent.number;
   if (typeof n !== "number" || !Number.isInteger(n) || n <= 0) {
     throw new Error(`unexpected parent number ${JSON.stringify(n)}`);
   }
   return n;
 }
 
-export function makeTracker(p: ProjectConfig): Tracker {
+export function makeTracker(p: ProjectConfig, runGh: typeof gh = gh): Tracker {
   const repo = p.tracker.repo;
 
   return {
     async listReady(): Promise<ReadyIssue[]> {
-      const raw = await gh([
+      const raw = await runGh([
         "issue",
         "list",
         "--repo",
@@ -246,7 +382,7 @@ export function makeTracker(p: ProjectConfig): Tracker {
 
     async addLabel(issue: number, label: string): Promise<void> {
       try {
-        await gh(["issue", "edit", String(issue), "--repo", repo, "--add-label", label]);
+        await runGh(["issue", "edit", String(issue), "--repo", repo, "--add-label", label]);
       } catch (err) {
         if (!isLabelNoop(err, "add")) throw err;
       }
@@ -254,7 +390,7 @@ export function makeTracker(p: ProjectConfig): Tracker {
 
     async removeLabel(issue: number, label: string): Promise<void> {
       try {
-        await gh(["issue", "edit", String(issue), "--repo", repo, "--remove-label", label]);
+        await runGh(["issue", "edit", String(issue), "--repo", repo, "--remove-label", label]);
       } catch (err) {
         if (!isLabelNoop(err, "remove")) throw err;
       }
@@ -263,25 +399,37 @@ export function makeTracker(p: ProjectConfig): Tracker {
     async comment(issue: number, body: string): Promise<void> {
       // `--body-file -` reads stdin, so the body is never shell- or argv-
       // mangled and has no length limit worth worrying about.
-      await gh(["issue", "comment", String(issue), "--repo", repo, "--body-file", "-"], body);
+      await runGh(["issue", "comment", String(issue), "--repo", repo, "--body-file", "-"], body);
     },
 
     async close(issue: number): Promise<void> {
-      await gh(["issue", "close", String(issue), "--repo", repo]);
+      await runGh(["issue", "close", String(issue), "--repo", repo]);
     },
 
     async linkParent(child: number, parent: number): Promise<void> {
       // Native sub-issue linkage rather than a body mention: it is what the
       // repo's own epic rollups read, so a human sees the split without us
       // maintaining a second index of it.
-      await gh(["issue", "edit", String(parent), "--repo", repo, "--add-sub-issue", String(child)]);
+      await runGh(["issue", "edit", String(parent), "--repo", repo, "--add-sub-issue", String(child)]);
     },
 
     async parentOf(issue: number): Promise<number | undefined> {
-      // Native sub-issue parent, not a body scrape. Verified on gh 2.97.0:
-      // `parent` is null with no link, otherwise `{ number, title, url, ... }`.
+      // gh 2.86 cannot expose `parent` through `issue view --json`; its raw
+      // GraphQL command can, and is already the adapter's path for PR closers.
+      const [owner = "", name = ""] = repo.split("/");
       return parentNumberFrom(
-        await gh(["issue", "view", String(issue), "--repo", repo, "--json", "parent"]),
+        await runGh([
+          "api",
+          "graphql",
+          "-f",
+          `query=${PARENT_QUERY}`,
+          "-F",
+          `owner=${owner}`,
+          "-F",
+          `repo=${name}`,
+          "-F",
+          `n=${issue}`,
+        ]),
       );
     },
 
@@ -290,7 +438,7 @@ export function makeTracker(p: ProjectConfig): Tracker {
       // 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([
+      const raw = await runGh([
         "api",
         "graphql",
         "-f",
@@ -308,6 +456,16 @@ export function makeTracker(p: ProjectConfig): Tracker {
       return firstOpenCloser(raw);
     },
 
+    async issueState(issue: number): Promise<IssueState | undefined> {
+      try {
+        return issueStateFrom(
+          await runGh(["issue", "view", String(issue), "--repo", repo, "--json", "state", "--jq", ".state"]),
+        );
+      } catch {
+        return undefined;
+      }
+    },
+
     async prState(url: string): Promise<PrState | undefined> {
       // No `--repo`: a full URL is self-locating, and verified so on gh 2.97.0
       // from a directory that is not a git repository at all — which is exactly
@@ -316,7 +474,7 @@ export function makeTracker(p: ProjectConfig): Tracker {
       // what the URL already says.
       if (!PR_URL.test(url)) return undefined;
       try {
-        return prStateFrom(await gh(["pr", "view", url, "--json", "state", "--jq", ".state"]));
+        return prStateFrom(await runGh(["pr", "view", url, "--json", "state", "--jq", ".state"]));
       } catch {
         // Never throws, per the port's contract. A deleted PR, a revoked token
         // and a flaky network all mean "could not tell", and the caller's whole
@@ -326,5 +484,36 @@ export function makeTracker(p: ProjectConfig): Tracker {
         return undefined;
       }
     },
+
+    async verifyPr(url: string, expectedHead: string): Promise<PrVerification | undefined> {
+      if (!PR_URL.test(url)) return undefined;
+      try {
+        const raw = await runGh([
+          "pr",
+          "view",
+          url,
+          "--json",
+          "state,isDraft,headRefOid,statusCheckRollup",
+        ]);
+        const verification = prVerificationFrom(raw, expectedHead);
+        if (verification.status !== "failed") return verification;
+
+        const detailsUrl = failedCheck(raw)?.detailsUrl;
+        const args = detailsUrl === undefined ? undefined : runLogArgs(detailsUrl);
+        if (args === undefined) return verification;
+        try {
+          const digest = conciseLog(await runGh(args));
+          return digest === undefined
+            ? verification
+            : { ...verification, reason: `${verification.reason}\n${digest}` };
+        } catch {
+          return verification;
+        }
+      } catch {
+        // Lookup or payload failure is not permission to accept success. The
+        // daemon records a pending row and asks again on a later tick.
+        return undefined;
+      }
+    },
   };
 }

package/src/transcript.ts

@@ -0,0 +1,45 @@
+/** Read one property off an unvalidated transcript entry. */
+function prop(source: unknown, key: string): unknown {
+  if (source === null || typeof source !== "object") return undefined;
+  return Reflect.get(source, key);
+}
+
+/**
+ * One transcript line rendered for somebody watching, or `undefined` for the
+ * lines not worth a row: thinking blocks, tool results, session metadata, and
+ * anything this parser does not recognise.
+ *
+ * Defensive throughout. The transcript is written by the harness, not by this
+ * package, so its shape is a peer dependency's business and can gain entry
+ * types without warning.
+ */
+export function formatTranscriptLine(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");
+  if (typeof content === "string") {
+    return content.trim() === "" ? undefined : `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") {
+      const name = prop(block, "name");
+      if (typeof name === "string" && name !== "") out.push(`tool: ${name}`);
+    }
+  }
+  return out.length === 0 ? undefined : out.join("\n");
+}

package/src/types.ts

@@ -27,9 +27,12 @@ export interface Caps {
   /** 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;
-  /** Retries per issue before it escalates (2): one clean retry recovers from
-   *  flaky CI, a third almost always means the issue itself is underspecified. */
+  /** Failed implementation/CI attempts allowed before escalation. Operational
+   *  continuations do not consume this budget. */
   maxAttemptsPerIssue: number;
+  /** Cap-kill, daemon-orphan and answered-block continuations allowed before a
+   *  crash/resume loop escalates independently of implementation failures. */
+  maxContinuationsPerIssue: number;
 }
 
 /**
@@ -93,6 +96,18 @@ export type ReportScope = (typeof REPORT_SCOPES)[number];
  */
 export const DEFAULT_REPORT_SCOPE: ReportScope = "material";
 
+/**
+ * Mechanical permission for release-shaped tool calls. `authority.release`
+ * says who owns the decision; this key is the enforcement gate that decides
+ * whether an autonomous session may invoke the tools at all.
+ */
+export const RELEASE_POLICIES = ["none", "operator-brief"] as const;
+
+export type ReleasePolicy = (typeof RELEASE_POLICIES)[number];
+
+/** Safe for old and partial configs: release/deploy tools stay closed. */
+export const DEFAULT_RELEASE_POLICY: ReleasePolicy = "none";
+
 /**
  * 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
@@ -158,6 +173,12 @@ export interface ProjectConfig {
    * them is holding the merge button.
    */
   authority: { merge: AuthorityHolder; release: AuthorityHolder };
+  /**
+   * Tool-call enforcement for releases and deploys. Optional only for configs
+   * written before the tripwire existed; omission resolves fail-closed to
+   * {@link DEFAULT_RELEASE_POLICY}.
+   */
+  releasePolicy?: ReleasePolicy;
   /**
    * 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
@@ -217,6 +238,15 @@ export interface ReadyIssue {
  */
 export type PrState = "merged" | "closed" | "open";
 
+/** Result of independently checking a worker's claimed green pull request. */
+export interface PrVerification {
+  status: "green" | "pending" | "failed";
+  reason: string;
+}
+
+/** Tracker lifecycle state for an issue. Undefined means the adapter could not tell. */
+export type IssueState = "open" | "closed";
+
 /**
  * Deliberately narrow so a Gitea or local-file tracker can drop in later.
  * Nothing here is GitHub-shaped; the GitHub adapter owns `gh` entirely.
@@ -252,6 +282,11 @@ export interface Tracker {
    * only party that remembers across all of those.
    */
   openCloserFor(issue: number): Promise<string | undefined>;
+  /**
+   * 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>;
   /**
    * 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.
@@ -265,6 +300,11 @@ export interface Tracker {
    * is how a PR a human rejected gets recorded as merged.
    */
   prState(url: string): Promise<PrState | 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.
+   */
+  verifyPr(url: string, expectedHead: string): Promise<PrVerification | undefined>;
 }
 
 /**
@@ -276,6 +316,8 @@ export type RunState =
   | "claimed"
   | "running"
   | "pushed-green"
+  /** Worker finished, but GitHub has not yet produced a terminal check verdict. */
+  | "pushed-pending"
   /** Its PR landed. Written by the tick's settle sweep, never by a worker: only
    *  the tracker knows, and it knows minutes to days after the run ended. */
   | "merged"
@@ -301,16 +343,93 @@ export interface RunRecord {
   /** 1-based attempt number, checked against `Caps.maxAttemptsPerIssue`. */
   attempt: number;
   turns: number;
+  /** Effective turn ceiling for this run; operators may only raise it. */
+  maxTurns: number;
   spendUsd: number;
   /** omp session transcript, so a human can read what the worker actually did. */
   sessionFile?: string;
   prUrl?: string;
+  /** Pull request head the worker observed after its deterministic CI watcher exited. */
+  headSha?: string;
   startedAt: number;
   endedAt?: number;
   /** Last failure text, surfaced verbatim in escalations. */
   lastError?: string;
 }
 
+export type AdmissionHoldReason =
+  | "capacity"
+  | "issue-active"
+  | "failed-attempts"
+  | "continuations"
+  | "parent-lookup-error"
+  | "sibling-active"
+  | "open-pr-lookup-error"
+  | "open-pr"
+  | "daily-spend-cap"
+  | "unroutable:no-repo-label"
+  | "unroutable:multiple-repo-labels"
+  | "unroutable:unknown-repo";
+
+/** One bounded reason group from the latest admission pass. */
+export interface AdmissionHoldSummary {
+  reason: AdmissionHoldReason;
+  count: number;
+  /** Queue-order sample, capped before persistence and rendering. */
+  issues: number[];
+}
+
+/** Persisted outcome of the latest completed dispatch tick. */
+export interface DispatchSummary {
+  completedAt: number;
+  ready: number;
+  routed: number;
+  admitted: number;
+  /** True only for system/API failures, never ordinary policy holds. */
+  degraded: boolean;
+  holds: AdmissionHoldSummary[];
+}
+
+/** Admission holds that indicate repairable friction rather than normal flow control. */
+export type FrictionAdmissionReason =
+  | "failed-attempts"
+  | "continuations"
+  | "parent-lookup-error"
+  | "open-pr-lookup-error"
+  | "unroutable:no-repo-label"
+  | "unroutable:multiple-repo-labels"
+  | "unroutable:unknown-repo";
+
+/** A mechanically observed or explicitly classified source of repeated friction. */
+export type FrictionKind =
+  | `admission:${FrictionAdmissionReason}`
+  | "feedback:escalation-should-digest"
+  | "feedback:report-noise"
+  | "feedback:report-surprise";
+
+/** One observation persisted into the daily friction rollup. */
+export interface FrictionObservation {
+  kind: FrictionKind;
+  /** Number of affected candidates/events represented by this observation. */
+  occurrences: number;
+  issues?: number[];
+  issue?: number;
+  /** Bounded human-readable evidence, never an unbounded error or transcript. */
+  sample?: string;
+  at: number;
+}
+
+/** A repeated signal eligible for the orchestrator's Learning loop. */
+export interface FrictionSignal {
+  kind: FrictionKind;
+  observations: number;
+  occurrences: number;
+  issues: number[];
+  samples: string[];
+  latestAt: number;
+}
+
+
 /**
  * Bookkeeping only — GitHub labels remain the source of truth. The store
  * exists to answer cap questions cheaply and to survive a restart; if it is
@@ -324,7 +443,17 @@ export interface Store {
   activeRuns(project: string): RunRecord[];
   /** Runs backed by a worker process — what capacity counts. Subset of {@link Store.activeRuns}. */
   liveRuns(project: string): RunRecord[];
+  /** Failed/killed/orphaned rows whose retained tree has not been reaped. */
+  retainedRuns(project: string): RunRecord[];
+  /** 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[];
+  /** Total run segments, used only for the monotonically increasing run number. */
   attemptsFor(project: string, issue: number): number;
+  /** Terminal implementation failures that consume `maxAttemptsPerIssue`. */
+  failuresFor(project: string, issue: number): number;
+  /** Operational stops that require a bounded continuation resume. */
+  continuationsFor(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. */
@@ -334,6 +463,19 @@ export interface Store {
   /** Idempotence guard so a retry loop cannot page a human repeatedly for the
    *  same event. */
   wasNotified(key: string): boolean;
+  recordDispatch(project: string, summary: DispatchSummary): void;
+  latestDispatch(project: string): DispatchSummary | undefined;
+  /** Add one bounded observation to the per-day friction rollup. */
+  recordFriction(project: string, observation: FrictionObservation): void;
+  /** Repeated signals not surfaced within the supplied cooldown window. */
+  pendingFriction(
+    project: string,
+    sinceEpochMs: number,
+    minimumObservations: number,
+    surfacedBeforeEpochMs: number,
+  ): FrictionSignal[];
+  /** Start the cooldown only after a tick carrying these signals was sent. */
+  markFrictionSurfaced(project: string, kinds: readonly FrictionKind[], at: number): void;
   markNotified(key: string): void;
   close(): void;
 }
@@ -367,4 +509,5 @@ export const DEFAULT_CAPS: Caps = {
   workerMaxTurns: 120,
   workerWallClockMs: 90 * 60 * 1000,
   maxAttemptsPerIssue: 2,
+  maxContinuationsPerIssue: 2,
 };