omp-conductor 0.17.1 → 0.18.0

package/src/worker.ts

@@ -30,6 +30,77 @@ const GITHUB_PR_URL_PATTERN = /https:\/\/github\.com\/([^/\s]+\/[^/\s]+)\/pull\/
 /** `{{KEY}}` placeholders in a brief template. */
 const PLACEHOLDER_PATTERN = /\{\{([A-Za-z0-9_]+)\}\}/g;
 
+/**
+ * The structured settlement a worker yields at the end of a run (#540).
+ *
+ * Fields decided here, not per project. The daemon stays the authority on
+ * green — it verifies the PR itself — so this is the worker's *claim*,
+ * cross-checked exactly as the prose report it replaces: a `green` claim
+ * must carry the PR URL and the head SHA the worker actually watched go
+ * green, and anything less fails closed.
+ */
+export interface WorkerSettlement {
+  status: "green" | "blocked" | "failed";
+  /** The run's pull request URL. Required with `status: "green"`. */
+  prUrl?: string;
+  /** The branch the PR was pushed from. */
+  branch?: string;
+  /** The 40-hex head SHA the green CI verdict was observed at. Required with `status: "green"`. */
+  headSha?: string;
+  /** What changed and why — the narrative a reviewer reads. */
+  summary: string;
+  /** What a decision or credential this run needed (blocked runs). */
+  blockers?: string[];
+  /** Commands run as evidence, exactly as executed. */
+  proof?: string[];
+}
+
+/**
+ * The JSON Schema form of {@link WorkerSettlement}, handed to the harness as
+ * the session's `outputSchema` (#540).
+ *
+ * Used two ways, and both must stay honest to the same contract:
+ * `requireYieldTool` puts the `yield` tool in front of the worker with this
+ * schema as its description, and `outputSchemaMode: "permissive"` means a
+ * violation is a fallback, never a lost report — the worker's text path must
+ * still settle a run whose yield does not parse.
+ */
+export const WORKER_SETTLEMENT_SCHEMA = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  type: "object",
+  description:
+    "The run's settlement: what this worker claims it achieved. The daemon verifies the PR itself; " +
+    "this is the claim, cross-checked like the settlement report it replaces.",
+  additionalProperties: false,
+  required: ["status", "summary"],
+  properties: {
+    status: {
+      type: "string",
+      enum: ["green", "blocked", "failed"],
+      description:
+        "green: pushed and the checks you watched are green. blocked: a decision, credential or " +
+        "repo fact is missing. failed: the run could not complete.",
+    },
+    prUrl: { type: "string", description: "The run's pull request URL — required with status green." },
+    branch: { type: "string", description: "The branch the PR was pushed from." },
+    headSha: {
+      type: "string",
+      description: "The 40-character head SHA you observed green — required with status green.",
+    },
+    summary: { type: "string", description: "One short paragraph: what changed and why." },
+    blockers: {
+      type: "array",
+      items: { type: "string" },
+      description: "What is missing or uncertain, one item per blocker (blocked runs).",
+    },
+    proof: {
+      type: "array",
+      items: { type: "string" },
+      description: "The commands you ran as evidence, exactly as executed.",
+    },
+  },
+} as const;
+
 function scheduleWallClock(callback: () => void, delayMs: number): () => void {
   const timer = setTimeout(callback, delayMs);
   return () => clearTimeout(timer);
@@ -88,7 +159,7 @@ export const REVIEW_REVISION_PROMPT =
   "The orchestrator reviewed your green pull request and found blocking findings. Continue this same session " +
   "on this same run: same branch, same pull request — do not close or reopen it, and do not open another. " +
   "Address exactly the findings below, push with conductor_push, verify the checks with conductor_pr_status, " +
-  "and finish with the same final-report contract as before (state: pushed-green, pr:, head:). " +
+  "and finish with the same final-report contract as before (yield your settlement: status green, prUrl, headSha). " +
   "Your original brief is already in this transcript; redo only what the findings implicate.";
 
 /**
@@ -205,6 +276,13 @@ export interface WorkerResult {
   headSha?: string;
   turns: number;
   spendUsd: number;
+  /**
+   * The run's settlement text. Today this is the worker's own last words; a
+   * run that yielded a structured {@link WorkerSettlement} instead carries the
+   * canonical rendering of that parsed object (#540) — the narrative lives in
+   * its `summary`, transcribed here field for field rather than regexed out of
+   * prose.
+   */
   report: string;
   /** In-session HTTP 429 responses the session recorded (stopReason "error",
    *  errorStatus 429), counted as the messages streamed in. A healthy run
@@ -277,12 +355,34 @@ export function renderBrief(template: string, vars: Record<string, string>): str
  * must carry both a PR URL and the head SHA observed after CI; the daemon then
  * asks the tracker to verify those facts independently. Missing or malformed
  * evidence fails closed.
+ *
+ * A parsed {@link WorkerSettlement} wins over the text whenever it is present
+ * (#540): the schema is the contract now, and a misleadingly regular-looking
+ * prose block must not out-vote the object the worker actually yielded. The
+ * text path is unchanged underneath, so a run that never yields settles
+ * exactly as it did before.
  */
-export function deriveResult(report: string, repoSlug?: string): {
+export function deriveResult(
+  report: string,
+  repoSlug?: string,
+  structured?: WorkerSettlement,
+): {
   state: RunState;
   prUrl?: string;
   headSha?: string;
 } {
+  if (structured !== undefined && (structured.status === "green" || structured.status === "blocked" || structured.status === "failed")) {
+    const prUrl = structured.prUrl;
+    const headSha = structured.headSha?.toLowerCase();
+    if (structured.status === "green" && prUrl !== undefined && headSha !== undefined) {
+      return { state: "pushed-green", prUrl, headSha };
+    }
+    return {
+      state: structured.status === "blocked" ? "blocked" : "failed",
+      ...(prUrl === undefined ? {} : { prUrl }),
+      ...(headSha === undefined ? {} : { headSha }),
+    };
+  }
   const structuredPrUrl = PR_URL_PATTERN.exec(report)?.[1];
   const headSha = HEAD_SHA_PATTERN.exec(report)?.[1]?.toLowerCase();
   if (PUSHED_GREEN_PATTERN.test(report) && structuredPrUrl !== undefined && headSha !== undefined) {
@@ -305,6 +405,81 @@ export function deriveResult(report: string, repoSlug?: string): {
   };
 }
 
+/**
+ * Parse a worker's structured settlement out of one assistant message's
+ * content (#540).
+ *
+ * The worker calls the `yield` tool with `{ result: { data: <settlement> } }`
+ * and the harness records that call as a `toolCall` content block on the
+ * assistant message — the same content `reportText` flattens. Parsed
+ * permissively on purpose: `outputSchemaMode` is permissive, so a yield the
+ * schema rejected must still fall back to the text path rather than vanish.
+ * The acceptance bar mirrors the schema's own `required`: a recognizable
+ * `status` and a string `summary`; every other field is adopted when it has
+ * the right type and dropped otherwise. Exported so the run loop's precedence
+ * (yield over prose) is pinned by a unit test.
+ */
+export function structuredSettlement(content: unknown): WorkerSettlement | undefined {
+  if (!Array.isArray(content)) return undefined;
+  let parsed: WorkerSettlement | undefined;
+  for (const block of content) {
+    if (field(block, "type") !== "toolCall") continue;
+    if (field(block, "name") !== "yield") continue;
+    const args = field(block, "arguments");
+    if (args === null || typeof args !== "object") continue;
+    const result = field(args, "result");
+    if (result === null || typeof result !== "object") continue;
+    const data = field(result, "data");
+    if (data === null || typeof data !== "object" || Array.isArray(data)) continue;
+    const record = data as Record<string, unknown>;
+    const status = record.status;
+    if (status !== "green" && status !== "blocked" && status !== "failed") continue;
+    const summary = record.summary;
+    if (typeof summary !== "string") continue;
+    const settlement: WorkerSettlement = { status, summary };
+    for (const key of ["prUrl", "branch", "headSha"] as const) {
+      const value = record[key];
+      if (typeof value === "string" && value !== "") settlement[key] = value;
+    }
+    for (const key of ["blockers", "proof"] as const) {
+      const value = record[key];
+      if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+        settlement[key] = value;
+      }
+    }
+    parsed = settlement;
+  }
+  return parsed;
+}
+
+/**
+ * Render a parsed {@link WorkerSettlement} as the run's stored report (#540).
+ *
+ * A worker that yields structured output may write little or no prose after
+ * the yield call, and the prose shape is no longer the contract — so the
+ * report the store keeps for such a run is this canonical rendering of the
+ * parsed object itself: the same fields a reviewer would have had to regex
+ * out of prose, derived from the object, field for field. The daemon's own
+ * postfixes — the PR-diff `changed:` line and the reliability sentence — are
+ * appended to it exactly as they are to a prose report.
+ */
+export function renderSettlement(settlement: WorkerSettlement): string {
+  const lines: string[] = [`status: ${settlement.status}`];
+  if (settlement.prUrl !== undefined) lines.push(`pr: ${settlement.prUrl}`);
+  if (settlement.branch !== undefined) lines.push(`branch: ${settlement.branch}`);
+  if (settlement.headSha !== undefined) lines.push(`head: ${settlement.headSha}`);
+  if (settlement.summary !== "") lines.push("", settlement.summary);
+  if (settlement.blockers !== undefined && settlement.blockers.length > 0) {
+    lines.push("", "blockers:");
+    for (const blocker of settlement.blockers) lines.push(`  - ${blocker}`);
+  }
+  if (settlement.proof !== undefined && settlement.proof.length > 0) {
+    lines.push("", "proof:");
+    for (const item of settlement.proof) lines.push(`  - ${item}`);
+  }
+  return lines.join("\n");
+}
+
 /**
  * Did this report state a verdict at all?
  *
@@ -380,6 +555,13 @@ export async function runWorker(
       ...(o.verbSocketPath === undefined ? {} : { verbSocketPath: o.verbSocketPath }),
       ...(o.onChildLog === undefined ? {} : { onChildLog: o.onChildLog }),
       ...(o.maySpawn === undefined ? {} : { maySpawn: o.maySpawn }),
+      // The structured settlement contract (#540): the worker's `yield` tool
+      // validates its `data` payload against this schema, permissively — an
+      // invalid or absent yield falls back to the text path, never a lost
+      // report. Always-on for workers: one schema, and no per-project shape.
+      outputSchema: WORKER_SETTLEMENT_SCHEMA,
+      outputSchemaMode: "permissive",
+      requireYieldTool: true,
     });
   } catch (err) {
     // The pre-spawn gate closed (#374): a daemon stop landed while the session
@@ -473,6 +655,10 @@ export async function runWorker(
   let spendUsd = 0;
   let provider429Count = 0;
   let report = "";
+  // The newest structured settlement the worker yielded (#540). A terminal
+  // `yield` ends the run, so anything parsed here is the run's own claim, and
+  // any later message is stale-polling chatter, never a newer verdict.
+  let structured: WorkerSettlement | undefined;
   // Which model/provider actually wrote the newest assistant message. Last
   // assistant message wins: that is the durable answer even for a run that
   // never failed over (#535 slice 1, read off the message field which is where
@@ -629,15 +815,22 @@ export async function runWorker(
   session.on("message_end", (event) => {
     const message = field(event, "message");
     if (field(message, "role") !== "assistant") return;
+    const content = field(message, "content");
     // Keep the newest non-empty assistant text: whatever the worker said last
     // is its report, whether it finished cleanly or was cut off.
-    const text = reportText(field(message, "content"));
+    const text = reportText(content);
     if (text !== "") {
       report = text;
-      const stated = deriveResult(text, o.repoSlug);
-      if (stated.state === "pushed-green" && stated.prUrl !== undefined && stated.headSha !== undefined) {
-        claim = { prUrl: stated.prUrl, headSha: stated.headSha };
-      }
+    }
+    // The structured settlement (#540): the `yield` tool call rides the same
+    // message's content as a `toolCall` block. Newest yield wins; the
+    // derivation itself prefers it over prose, so a yield and a misleadingly
+    // regular-looking text block on the same message agree in its favour.
+    const yielded = structuredSettlement(content);
+    if (yielded !== undefined) structured = yielded;
+    const stated = deriveResult(text, o.repoSlug, yielded);
+    if (stated.state === "pushed-green" && stated.prUrl !== undefined && stated.headSha !== undefined) {
+      claim = { prUrl: stated.prUrl, headSha: stated.headSha };
     }
 
     // Real cost lives on assistant messages as `usage.cost.total` (live hermes
@@ -802,6 +995,20 @@ export async function runWorker(
     }));
   }
 
+  // A structured yield is the run's settlement: it wins over the last text —
+  // the worker may have written nothing after the yield call, and the stored
+  // report is the canonical rendering of the parsed object, not prose the
+  // regex has to recover (#540).
+  if (structured !== undefined) {
+    return withMetrics(withSessionFacts({
+      ...deriveResult(report, o.repoSlug, structured),
+      turns,
+      spendUsd,
+      provider429Count,
+      report: renderSettlement(structured),
+    }));
+  }
+
   // An explicit later verdict always wins: a worker that pushed green and then
   // stopped to ask a question means the question. The earlier claim is only
   // restored when the last thing said was not a verdict at all.

package/src/worktree.ts

@@ -759,12 +759,87 @@ export async function removeWorktree(
 
 export type RetainedWorktreeCleanup =
   | { kind: "removed" }
-  | { kind: "retained"; reason: "dirty" | "unpushed" | "unknown"; detail: string };
+  | {
+      kind: "retained";
+      reason: "dirty" | "unpushed" | "unknown" | "quarantined";
+      detail: string;
+    };
+
+/**
+ * Repairs a run repository whose `objects/info/alternates` names a path that no
+ * longer exists, re-pointing the dangling entry at this project's current
+ * mirror. Worktrees created before mirrors moved into per-project roots keep
+ * the old flat path (`<home>/mirrors/<repo>.git`); the store they borrow from
+ * is gone, so any fetch against them dies on unresolved deltas (#728). The
+ * repair belongs here — in the code that discovers the stale entry — rather
+ * than in a one-off host edit, so the next layout migration heals itself too.
+ *
+ * Only missing entries are rewritten: a valid alternate is left alone and a
+ * worktree with no alternates file is already sound. When the store cannot be
+ * made sound — the git dir is unresolvable, the file cannot be read or
+ * written, or a missing path survives the rewrite — the caller must not fetch
+ * into the broken state; a quarantine detail is returned instead.
+ */
+async function repairAlternates(
+  worktreePath: string,
+  mirrorPath: string,
+): Promise<{ kind: "ok" } | { kind: "quarantine"; detail: string }> {
+  const common = await runGit(["rev-parse", "--git-common-dir"], worktreePath);
+  if (common.code !== 0) {
+    return {
+      kind: "quarantine",
+      detail: `cannot resolve the git dir: ${common.stderr.trim() || common.stdout.trim() || "no output"}`,
+    };
+  }
+  const raw = common.stdout.trim();
+  if (raw === "") {
+    return { kind: "quarantine", detail: "cannot resolve the git dir: git printed nothing" };
+  }
+  // `--git-common-dir` is relative for linked worktrees; resolve against the
+  // tree so bare-mirror layouts and plain clones both land on the alternates.
+  const commonDir = raw.startsWith("/") ? raw : join(worktreePath, raw);
+  const alternates = join(commonDir, "objects", "info", "alternates");
+  if (!existsSync(alternates)) return { kind: "ok" };
+
+  const current = join(mirrorPath, "objects");
+  let content: string;
+  try {
+    content = readFileSync(alternates, "utf8");
+  } catch (err) {
+    return { kind: "quarantine", detail: `${alternates} cannot be read: ${err instanceof Error ? err.message : String(err)}` };
+  }
+
+  let changed = false;
+  const rewritten = content.split("\n").map((line) => {
+    const candidate = line.trim();
+    if (candidate === "" || candidate === current || existsSync(candidate)) return line;
+    changed = true;
+    return current;
+  });
+  if (changed) {
+    try {
+      writeFileSync(alternates, rewritten.join("\n"));
+    } catch (err) {
+      return { kind: "quarantine", detail: `${alternates} cannot be rewritten: ${err instanceof Error ? err.message : String(err)}` };
+    }
+  }
+
+  const dangling = rewritten.map((line) => line.trim()).filter((path) => path !== "" && !existsSync(path));
+  if (dangling.length > 0) {
+    return {
+      kind: "quarantine",
+      detail: `${alternates} still names missing path(s): ${dangling.join(", ")}`,
+    };
+  }
+  return { kind: "ok" };
+}
 
 /**
  * Reap a terminal run's tree and local mirror branch without deleting the only
  * copy of work. Tracker state is proved by the caller; this function proves the
- * local half after refreshing remote refs. Any ambiguity retains everything.
+ * local half after refreshing remote refs. Any ambiguity retains everything;
+ * a remote read that failed is ambiguity, never a pushed/unpushed claim, and
+ * the unpushed verdicts below are reachable only from reads that succeeded.
  */
 export async function cleanupRetainedWorktree(
   mirrorPath: string,
@@ -779,6 +854,20 @@ export async function cleanupRetainedWorktree(
 
   try {
     if (existsSync(worktreePath)) {
+      // A run repo created before mirrors moved into per-project roots may
+      // borrow objects from a path that no longer exists. Fetching into it is
+      // a guaranteed failure, so repair the alternates first — and when the
+      // store cannot be made sound, quarantine the tree instead of fetching
+      // into the broken state.
+      const repair = await repairAlternates(worktreePath, mirrorPath);
+      if (repair.kind === "quarantine") {
+        return {
+          kind: "retained",
+          reason: "quarantined",
+          detail: `worktree quarantined: ${repair.detail}`,
+        };
+      }
+
       const dirty = await git(["status", "--porcelain"], worktreePath);
       if (dirty !== "") {
         return { kind: "retained", reason: "dirty", detail: "worktree has uncommitted changes" };
@@ -794,8 +883,18 @@ export async function cleanupRetainedWorktree(
     }
 
     // A deleted remote branch can make a pushed commit look local-only until
-    // the default branch is fetched. Failure is ambiguity, never permission.
-    await git(["fetch", "--prune", "origin"], mirrorPath);
+    // the default branch is fetched. A failed fetch is ambiguity, never
+    // permission: without fresh remote refs the unpushed verdicts below are
+    // unreachable and the run is retained on an explicit unknown.
+    try {
+      await git(["fetch", "--prune", "origin"], mirrorPath);
+    } catch (err) {
+      return {
+        kind: "retained",
+        reason: "unknown",
+        detail: `remote refs could not be refreshed: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
 
     const ref = `refs/heads/${branch}`;
 
@@ -806,10 +905,18 @@ export async function cleanupRetainedWorktree(
     // data loss #121 exists to prevent, reintroduced by the move to per-run
     // repositories, so it is checked where the objects actually are.
     if (existsSync(worktreePath)) {
-      await git(
-        ["fetch", "--no-tags", mirrorPath, "+refs/remotes/origin/*:refs/remotes/origin/*"],
-        worktreePath,
-      );
+      try {
+        await git(
+          ["fetch", "--no-tags", mirrorPath, "+refs/remotes/origin/*:refs/remotes/origin/*"],
+          worktreePath,
+        );
+      } catch (err) {
+        return {
+          kind: "retained",
+          reason: "unknown",
+          detail: `the run repository's remote refs could not be read: ${err instanceof Error ? err.message : String(err)}`,
+        };
+      }
       const runUnique = await git(["rev-list", ref, "--not", "--remotes"], worktreePath);
       if (runUnique !== "") {
         return {