omp-conductor 0.3.18 → 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. */
@@ -73,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 {
@@ -169,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}.
@@ -195,6 +310,18 @@ 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 raw GraphQL response, or undefined when the issue has
  * no parent. Throws when the issue or claimed parent is malformed — admission
@@ -329,6 +456,16 @@ export function makeTracker(p: ProjectConfig, runGh: typeof gh = gh): 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
@@ -347,5 +484,36 @@ export function makeTracker(p: ProjectConfig, runGh: typeof gh = gh): 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,
 };

package/src/unblock.ts

@@ -22,10 +22,9 @@
  * 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.
+ * run row, so the store has nothing to say here. Leaving history alone keeps
+ * both budgets honest: a block consumes an operational continuation, while a
+ * real implementation failure consumes the separate failed-attempt budget.
  */
 
 import { LIVE_STATES } from "./store.ts";
@@ -35,8 +34,10 @@ import type { Caps, ProjectConfig, RunRecord, Store, Tracker } from "./types.ts"
 export interface UnblockOutcome {
   /** State labels the tracker was asked to drop. */
   cleared: string[];
-  /** Attempts this issue has already spent. Unchanged by the unblock. */
+  /** Total run segments, retained for history and sequence numbering. */
   attemptsUsed: number;
+  failuresUsed: number;
+  continuationsUsed: number;
   /** Newest attempt, when the store has one for this issue at all. */
   latest?: RunRecord;
 }
@@ -72,6 +73,8 @@ export async function unblockIssue(
   return {
     cleared,
     attemptsUsed: store.attemptsFor(project.name, issue),
+    failuresUsed: store.failuresFor(project.name, issue),
+    continuationsUsed: store.continuationsFor(project.name, issue),
     ...(latest === undefined ? {} : { latest }),
   };
 }
@@ -82,17 +85,21 @@ export async function unblockIssue(
  * 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 {
+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");
+    lines.push("  runs       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",
-    );
+    lines.push(`  runs       ${o.attemptsUsed}, newest ${latest.state}`);
+    lines.push(`  failures   ${o.failuresUsed} of ${caps.maxAttemptsPerIssue}`);
+    lines.push(`  continuations ${o.continuationsUsed} of ${caps.maxContinuationsPerIssue}`);
   }
 
   if (latest !== undefined && LIVE_STATES.includes(latest.state)) {
@@ -100,10 +107,15 @@ export function formatUnblock(issue: number, o: UnblockOutcome, project: Project
       `  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) {
+  } else if (o.failuresUsed >= caps.maxAttemptsPerIssue) {
+    lines.push(
+      `  next tick  not eligible: all ${caps.maxAttemptsPerIssue} failed attempts are spent. ` +
+        "Rewrite the issue or raise maxAttemptsPerIssue.",
+    );
+  } else if (o.continuationsUsed > caps.maxContinuationsPerIssue) {
     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.",
+      `  next tick  not eligible: the ${caps.maxContinuationsPerIssue}-continuation budget was exceeded. ` +
+        "Inspect progress or raise maxContinuationsPerIssue.",
     );
   } else {
     lines.push(`  next tick  eligible again, as long as the issue still carries "${project.queueLabel}"`);