@uchibeke/gallivant 0.2.1 → 0.3.0

package/lib/events.mjs

@@ -1,24 +1,22 @@
 // The rules for what counts as an event, written as pure functions over the data `gh` returns, so every rule in
 // PRD 6.8 has a unit test and the tick only orchestrates.
 //
-// Inputs are the raw shapes: `pr` from `gh pr view --json`, `reviews`, `inline` and `comments` from REST.
-import { actor, normalizeLogin, ROUND_MARKER, NUDGE_MARKER, RESET_MARKER } from "./gh.mjs";
+// Inputs are normalized host records; legacy event aliases remain readable for saved integrations.
+import { actor, normalizeLogin, ROUND_MARKER, NUDGE_MARKER, RESET_MARKER } from "./host_contract.mjs";
 import { hasMarker } from "./public-format.mjs";
 import { isAfter, isAtOrAfter, later, floorSecond } from "./time.mjs";
 
-const FAILING = new Set(["FAILURE", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED", "STARTUP_FAILURE"]);
-const GREEN = new Set(["SUCCESS", "NEUTRAL", "SKIPPED"]);
 const COMMAND = /^\s*(?:\/fix\b|@(?:work|gallivant)\s+fix\b)/i;
 export const isFixCommand = body => COMMAND.test(String(body ?? ""));
 
 export function makeTrust(config, ownLogin) {
   if (!ownLogin) throw new Error("trust rules need the daemon's own login");
   const trusted = new Set(config.trusted_authors.map(normalizeLogin));
-  const reviewer = config.reviewer ? normalizeLogin(config.reviewer.login) : null;
+  const reviewer = config.reviewer ? normalizeLogin(config.reviewer.actor_id ?? config.reviewer.login) : null;
   const own = normalizeLogin(ownLogin);
   return {
     isTrusted: a => trusted.has(a.login) && !a.bot,
-    isReviewer: a => reviewer !== null && a.bot && a.login === reviewer,
+    isReviewer: a => reviewer !== null && (config.reviewer.actor_id || a.bot) && a.login === reviewer && a.login !== own,
     isOwn: a => a.login === own,
   };
 }
@@ -42,6 +40,27 @@ export const eventKey = e => `${e.kind}:${e.id}`;
  *
  * Editing an item later does not make it new again: the comparison is on `created_at`, never on `updated_at`.
  */
+const recordId = record => record.id ?? record.eventId;
+const currentEvent = (record, head) => !record.deleted && !record.resolved && (record.headBinding !== "exact" || record.headSha === head);
+
+// PR-wide unresolved tasks/change requests stay blocking even after their one
+// fix round. An unbound finding must not be silently mistaken for a clean head.
+export function requiredFeedback({ reviews = [], inline = [], trust, headSha }) {
+  return [...reviews, ...inline].filter(r => !r.deleted && !r.resolved && !(r.replyTo && trust.isOwn(actor(r.actor ?? r.user))) &&
+    (r.required || trust.isTrusted(actor(r.actor ?? r.user)) || trust.isReviewer(actor(r.actor ?? r.user))) &&
+    (r.required || r.headBinding === "exact" && !r.headSha) &&
+    (r.headBinding !== "exact" || !r.headSha || r.headSha === headSha));
+}
+
+export async function readFeedback(host, repo, pr, inlineSince, commentSince) {
+  if (pr.feedback !== undefined) {
+    const f = pr.feedback;
+    if (!f || f.complete !== true || f.headSha !== pr.headRefOid || ![f.reviews, f.inline, f.comments].every(Array.isArray)) throw new Error("Incomplete or mismatched feedback snapshot; preserve cursor and retry");
+    return [f.reviews, f.inline, f.comments];
+  }
+  return Promise.all([host.reviews(repo, pr.number), host.inlineComments(repo, pr.number, inlineSince), host.issueComments(repo, pr.number, commentSince)]);
+}
+
 export function deriveEvents({ pr, reviews, inline, comments = [], entry, trust }) {
   const since = entry.cursor.since;
   const dispatched = new Set(entry.cursor.dispatched || []);
@@ -50,33 +69,33 @@ export function deriveEvents({ pr, reviews, inline, comments = [], entry, trust
 
   // Reviews our own login submitted, so an inline note hanging off one is recognised as the harness's own comment on
   // its own work rather than as feedback on it.
-  const ownReviews = new Set(reviews.filter(r => trust.isOwn(actor(r.user))).map(r => r.id));
+  const ownReviews = new Set(reviews.filter(r => trust.isOwn(actor(r.actor ?? r.user))).map(r => recordId(r)));
 
   const inlineByReview = new Map();
   for (const c of inline) {
-    const rid = c.pull_request_review_id;
+    const rid = (c.reviewId ?? c.pull_request_review_id);
     if (!inlineByReview.has(rid)) inlineByReview.set(rid, []);
     inlineByReview.get(rid).push(c);
   }
 
   for (const r of reviews) {
-    if (!isNew(r.submitted_at, "review", r.id)) continue;
-    const a = actor(r.user);
-    const attached = (inlineByReview.get(r.id) || []).filter(c => !c.in_reply_to_id);
+    if (!currentEvent(r, pr.headRefOid) || r.headBinding === "unbound" || !isNew((r.at ?? r.submitted_at), "review", recordId(r))) continue;
+    const a = actor(r.actor ?? r.user);
+    const attached = (inlineByReview.get(recordId(r)) || []).filter(c => currentEvent(c, pr.headRefOid) && (c.headBinding !== "exact" || isNew(c.at ?? c.created_at, "inline", recordId(c))) && !(c.replyTo ?? c.in_reply_to_id));
     const qualifies = (trust.isReviewer(a) && (r.state === "CHANGES_REQUESTED" || (r.state === "COMMENTED" && attached.length > 0)))
       || (trust.isTrusted(a) && r.state === "CHANGES_REQUESTED");
     if (!qualifies) continue;
-    out.push({ kind: "review", id: r.id, reviewId: r.id, author: a.login, state: r.state, body: r.body || "", at: r.submitted_at });
+    out.push({ kind: "review", id: recordId(r), reviewId: recordId(r), author: a.login, state: r.state, body: r.body || "", at: (r.at ?? r.submitted_at) });
     for (const c of attached) out.push(inlineEvent(c, a.login));
-    inlineByReview.delete(r.id);
+    inlineByReview.delete(recordId(r));
   }
 
   // Inline comments not attached to a dispatched review: standalone trusted comments, or later comments on a review
   // that was already handled. Replies by our own login are the harness's thread replies.
   for (const list of inlineByReview.values()) {
     for (const c of list) {
-      if (!isNew(c.created_at, "inline", c.id)) continue;
-      const a = actor(c.user);
+      if (!currentEvent(c, pr.headRefOid) || !isNew((c.at ?? c.created_at), "inline", recordId(c))) continue;
+      const a = actor(c.actor ?? c.user);
       // Our own login writes in two capacities and they have to be told apart, because on a one-operator install the
       // operator's login IS the daemon's: config.md says `trusted_authors` is where your own login belongs. The
       // operator leaving a standalone inline comment is the main feedback channel and must dispatch. The harness
@@ -84,17 +103,17 @@ export function deriveEvents({ pr, reviews, inline, comments = [], entry, trust
       // carrying `in_reply_to_id`, and as inline notes hanging off a review of its own, which is what
       // `gh pr review --comment` produces. Both are the daemon's own work explaining itself, and dispatching a round
       // to answer it is the loop feeding itself.
-      if (trust.isOwn(a) && (c.in_reply_to_id || ownReviews.has(c.pull_request_review_id))) continue;
+      if (trust.isOwn(a) && ((c.replyTo ?? c.in_reply_to_id) || ownReviews.has((c.reviewId ?? c.pull_request_review_id)))) continue;
       if (!(trust.isTrusted(a) || trust.isReviewer(a))) continue;
       out.push(inlineEvent(c, a.login));
     }
   }
 
   for (const c of comments) {
-    if (!isNew(c.created_at, "command", c.id) || isOwnComment(c.body)) continue;
-    const a = actor(c.user);
+    if (!currentEvent(c, pr.headRefOid) || c.replyTo && trust.isOwn(actor(c.actor ?? c.user)) || !isNew((c.at ?? c.created_at), "command", recordId(c)) || isOwnComment(c.body)) continue;
+    const a = actor(c.actor ?? c.user);
     if (!trust.isTrusted(a) || !isFixCommand(c.body)) continue;
-    out.push({ kind: "command", id: c.id, author: a.login, body: c.body.replace(COMMAND, "").trim(), at: c.created_at });
+    out.push({ kind: "command", id: recordId(c), author: a.login, body: c.body.replace(COMMAND, "").trim(), at: (c.at ?? c.created_at) });
   }
 
   if (pr.headRefOid && pr.headRefOid !== entry.cursor.checks_sha) {
@@ -106,36 +125,30 @@ export function deriveEvents({ pr, reviews, inline, comments = [], entry, trust
     }
   }
 
-  out.sort((x, y) => Date.parse(x.at) - Date.parse(y.at));
-  return { events: out, newest: out.length ? out[out.length - 1].at : null };
+  const unique = [...new Map(out.map(e => [e.kind === "check" ? `check:${e.name}` : eventKey(e), e])).values()];
+  unique.sort((x, y) => Date.parse(x.at) - Date.parse(y.at));
+  return { events: unique, newest: unique.length ? unique[unique.length - 1].at : null };
 }
 
 const inlineEvent = (c, login) => ({
-  kind: "inline", id: c.id, reviewId: c.pull_request_review_id ?? null, author: login,
-  path: c.path, line: c.line ?? c.original_line ?? null, body: c.body || "", at: c.created_at,
+  kind: "inline", id: recordId(c), reviewId: (c.reviewId ?? c.pull_request_review_id) ?? null, author: login,
+  path: c.path, line: c.line ?? c.original_line ?? null, body: c.body || "", at: (c.at ?? c.created_at),
 });
 
 /** CheckRun and StatusContext entries that failed, with the Actions run id when the URL carries one. */
 export function failingChecks(rollup = []) {
-  const out = [];
-  for (const c of rollup || []) {
-    if (c.__typename === "StatusContext") {
-      if (["FAILURE", "ERROR"].includes(c.state)) out.push({ name: c.context, url: c.targetUrl, runId: runIdFrom(c.targetUrl), at: c.createdAt });
-    } else if (c.status === "COMPLETED" && FAILING.has(c.conclusion)) {
-      out.push({ name: c.workflowName ? `${c.workflowName} / ${c.name}` : c.name, url: c.detailsUrl, runId: runIdFrom(c.detailsUrl), at: c.completedAt });
-    }
-  }
-  return out;
+  return (rollup || []).filter(c => c.outcome === "failed").map(c => ({ name: c.name, url: c.url, runId: c.runId, at: c.updatedAt }));
 }
 
-const runIdFrom = url => (String(url || "").match(/\/actions\/runs\/(\d+)/) || [])[1] ?? null;
-
-/** Every check concluded green. Pending checks are not green. No checks at all is green. */
-export function isGreen(rollup = []) {
-  const items = rollup || [];
-  return items.every(c => c.__typename === "StatusContext" ? c.state === "SUCCESS" : c.status === "COMPLETED" && GREEN.has(c.conclusion));
+/** Every complete check concluded green. Empty evidence is subject to the shared grace period. */
+export function isGreen(rollup = [], required = []) {
+  return Array.isArray(rollup) && required.every(name => rollup.some(c => c.name === name)) && rollup.every(c => c.outcome === "passed");
 }
 
+/** Newest verdict first, with stable exact-head sequence numbers breaking timestamp ties. */
+export const compareReviewRecency = (a, b) => Date.parse(b.at ?? b.submitted_at) - Date.parse(a.at ?? a.submitted_at) ||
+  (a.headBinding === "exact" && b.headBinding === "exact" && Number.isSafeInteger(a.sequence) && Number.isSafeInteger(b.sequence) ? b.sequence - a.sequence : 0);
+
 /**
  * The reviewer's verdict since the last request: "none" when no reviewer is configured, "waiting" when it has not
  * reviewed since `sinceIso`, "blocking" when the newest review requests changes or has a blocking inline comment,
@@ -148,10 +161,10 @@ export function isGreen(rollup = []) {
  * `dispatched` holds the event keys already handled at exactly the cursor's instant, so a review the daemon is
  * already fixing cannot also read as the reviewer clearing this head.
  */
-export function reviewerVerdict({ reviews, inline, comments = [], config, trust, sinceIso, headSha = null, dispatched = [] }) {
+export function reviewerVerdict({ reviews, inline, comments = [], config, trust, sinceIso, headSha = null, dispatched = [], includeIdentity = false }) {
   if (!config.reviewer) return { verdict: "none", note: "no reviewer configured" };
   const handled = new Set(dispatched);
-  const fromReviews = reviews.filter(r => trust.isReviewer(actor(r.user)) && isAtOrAfter(r.submitted_at, sinceIso) && !["PENDING", "DISMISSED"].includes(r.state) && !handled.has(eventKey({ kind: "review", id: r.id })));
+  const fromReviews = reviews.filter(r => trust.isReviewer(actor(r.actor ?? r.user)) && isAtOrAfter((r.at ?? r.submitted_at), sinceIso) && !["PENDING", "DISMISSED"].includes(r.state) && !handled.has(eventKey({ kind: "review", id: recordId(r) })));
 
   // A verdict the reviewer posted as a plain comment rather than as a review, normalised into the shape above so the
   // head guard and the blocking rules below judge it identically. Everything after this line is unchanged.
@@ -167,28 +180,58 @@ export function reviewerVerdict({ reviews, inline, comments = [], config, trust,
   // a commit in its body, which `reviewedCommit` already parses and which the existing guard then checks against the
   // head. Clean is never INFERRED from the absence of findings, because the reviewer says other things in comments and
   // a chatty bot must not be able to clear a pull request by mentioning it. No commit named, no verdict.
-  const fromComments = (comments || [])
-    .filter(c => trust.isReviewer(actor(c.user)) && isAtOrAfter(c.created_at, sinceIso) && reviewedCommit(c.body, config.reviewer.reviewed_commit_pattern))
-    .map(c => ({ id: c.id, body: c.body, user: c.user, submitted_at: c.created_at, state: "COMMENTED", commit_id: null, fromComment: true }));
+  const fromComments = (comments || []).flatMap(c => {
+    if (c.deleted || c.headBinding === "exact" || !trust.isReviewer(actor(c.actor ?? c.user))) return [];
+    // The GitHub adapter recognizes authenticated, exact-head structured code
+    // review summaries. Required CI and independent review policies remain
+    // separate gates; an optional security scan is not a code-review verdict.
+    const summary = c.source?.host === "github.com" ? c.reviewSummary : null;
+    if (Object.hasOwn(c, "reviewSummary") && !summary) return [];
+    const at = summary?.at ?? c.at ?? c.created_at;
+    if (!isAtOrAfter(at, sinceIso) || !summary && !reviewedCommit(c.body, config.reviewer.reviewed_commit_pattern)) return [];
+    return [{ id: recordId(c), body: c.body, actor: c.actor ?? actor(c.user), submitted_at: at,
+      state: "COMMENTED", commit_id: null, fromComment: true, ...summary, fromStructuredSummary: Boolean(summary) }];
+  });
 
-  const mine = [...fromReviews, ...fromComments].sort((a, b) => Date.parse(b.submitted_at) - Date.parse(a.submitted_at));
+  const mine = [...fromReviews, ...fromComments].sort(compareReviewRecency);
   if (!mine.length) return { verdict: "waiting", note: "waiting on reviewer" };
   const newest = mine[0];
   // Which commit was reviewed, from the reviewer's own body first and its `commit_id` second. A review that names no
   // commit at all is no answer about this head: `commit_id` is null once the reviewed commit is gone from the
   // repository, which is what a force-push plus garbage collection leaves, and a falsy value used to skip the guard
   // entirely and clear whatever the head happened to be. So an unknown reviewed commit is `waiting`, not `clear`.
-  const reviewed = reviewedCommit(newest.body, config.reviewer.reviewed_commit_pattern) || newest.commit_id || null;
+  const reviewed = newest.headBinding === "exact" ? newest.headSha : reviewedCommit(newest.body, config.reviewer.reviewed_commit_pattern) || newest.headSha || newest.commit_id || null;
   if (headSha && !reviewed) return { verdict: "waiting", note: "reviewer named no commit, so it cannot clear this head" };
-  if (headSha && !headSha.startsWith(reviewed) && !reviewed.startsWith(headSha)) return { verdict: "waiting", note: `reviewer looked at ${reviewed.slice(0, 7)}, head is ${headSha.slice(0, 7)}` };
+  if (headSha && (newest.headBinding === "exact" ? headSha !== reviewed : !headSha.startsWith(reviewed) && !reviewed.startsWith(headSha))) return { verdict: "waiting", note: `reviewer looked at ${reviewed.slice(0, 7)}, head is ${headSha.slice(0, 7)}` };
+  if (newest.headBinding === "exact" && !["clear", "blocking"].includes(newest.verdict)) return { verdict: "waiting", note: "waiting for an explicit current-head verdict" };
+  if (newest.verdict === "blocking") return { verdict: "blocking", note: "explicit blocking verdict" };
   if (newest.state === "CHANGES_REQUESTED") return { verdict: "blocking", note: "changes requested" };
   const re = new RegExp(config.reviewer.blocking_pattern);
-  if (re.test(newest.body || "")) return { verdict: "blocking", note: "blocking finding in reviewer message" };
+  // Authenticated structured summaries already carry the code-review verdict.
+  // Their body also contains optional security policy metadata (for example a
+  // P0 threshold), which is not a code finding. Plain reviews/receipts still
+  // use the configured severity pattern; required CI/security gates stay separate.
+  const structuredClear = newest.fromStructuredSummary === true && newest.headBinding === "exact" && newest.verdict === "clear";
+  if (!structuredClear && re.test(newest.body || "")) return { verdict: "blocking", note: "blocking finding in reviewer message" };
   // Inline findings belong to a REVIEW. A comment-borne verdict has no review to own them, and `newest.id` is a
   // comment id from a different id space, so matching on it could pair a verdict with another review's findings.
-  const hits = newest.fromComment ? [] : inline.filter(c => c.pull_request_review_id === newest.id && re.test(c.body || ""));
+  const hits = newest.fromComment ? [] : inline.filter(c => (c.reviewId ?? c.pull_request_review_id) === recordId(newest) && re.test(c.body || ""));
   if (hits.length) return { verdict: "blocking", note: `${hits.length} blocking finding${hits.length > 1 ? "s" : ""}` };
-  return { verdict: "clear", note: "no blocking findings" };
+  const nativeHead = newest.headSha ?? newest.commit_id;
+  return { verdict: "clear", note: "no blocking findings", ...(includeIdentity ? {
+    reviewedHead: /^[a-f0-9]{40,64}$/.test(nativeHead || "") && nativeHead.startsWith(reviewed) ? nativeHead : reviewed,
+  } : {}) };
+}
+
+/** New policies resolve abbreviated bot identities through the host; a prefix
+ * collision or unavailable lookup cannot establish exact-head clearance. */
+export async function exactReviewerVerdict(input, resolveHead) {
+  const result = reviewerVerdict({ ...input, includeIdentity: true });
+  if (result.verdict !== "clear" || result.reviewedHead === input.headSha) return result;
+  try {
+    if (typeof resolveHead === "function" && await resolveHead(result.reviewedHead) === input.headSha) return { ...result, reviewedHead: input.headSha };
+  } catch { /* preserve waiting: lookup failure is not clearance */ }
+  return { verdict: "waiting", note: "reviewer commit could not be resolved to the exact current head; restore host access or request a full commit identity" };
 }
 
 /**
@@ -236,8 +279,8 @@ export function reviewerClock({ config, pushedAt, previousAsk = null, floorAt })
 }
 
 const ownComments = (issueComments, ownLogin) => issueComments
-  .filter(c => actor(c.user ?? c.author).login === normalizeLogin(ownLogin))
-  .sort((a, b) => Date.parse(a.created_at ?? a.createdAt) - Date.parse(b.created_at ?? b.createdAt));
+  .filter(c => actor(c.actor ?? c.user ?? c.author).login === normalizeLogin(ownLogin))
+  .sort((a, b) => Date.parse(a.at ?? a.created_at ?? a.createdAt) - Date.parse(b.at ?? b.created_at ?? b.createdAt));
 
 /**
  * The iteration number: the daemon's own round comments since its last reset comment. Every round posts one
@@ -251,11 +294,11 @@ export function countRounds(issueComments, ownLogin) {
 }
 
 export const lastOwnCommentAt = (issueComments, ownLogin) => ownComments(issueComments, ownLogin)
-  .filter(c => isOwnComment(c.body)).map(c => c.created_at ?? c.createdAt).at(-1) ?? null;
+  .filter(c => isOwnComment(c.body)).map(c => (c.at ?? c.created_at) ?? c.createdAt).at(-1) ?? null;
 
 /** Whether the daemon already posted a comment carrying `marker` after `sinceIso`. */
 export const hasOwnComment = (issueComments, ownLogin, marker, sinceIso) => ownComments(issueComments, ownLogin)
-  .some(c => hasMarker(c.body, marker) && isAfter(c.created_at ?? c.createdAt, sinceIso));
+  .some(c => hasMarker(c.body, marker) && isAfter((c.at ?? c.created_at) ?? c.createdAt, sinceIso));
 
 /** Only the lines a diff adds, so the completion gate never judges context or removed text. */
 export const addedLines = diff => String(diff || "").split("\n").filter(l => l.startsWith("+") && !l.startsWith("+++")).map(l => l.slice(1)).join("\n");

package/lib/execution.mjs

@@ -2,6 +2,7 @@
 import { join } from "node:path";
 import { existsSync, readdirSync, rmSync } from "node:fs";
 import { randomUUID, createHash } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
 import { ensureDir, readJson, writeJsonAtomic } from "./fs.mjs";
 import { acquireProcessLock } from "./daemon.mjs";
 import { capabilitiesFor, adapterFor, preparationReceipt, isPreparationReceipt } from "./harness.mjs";
@@ -11,6 +12,7 @@ import { prepareLocalExecution } from "./execution_preparation.mjs";
 import { EXECUTION_LIMITS, boundedCall, nextAttempt, executionError, assertExecutionCursor, ownsProviderSession, assertTerminalOutcome, redact, redactResultMetadata } from "./execution_io.mjs";
 import { journalFor } from "./execution_journal.mjs";
 import { requestRunCancellation } from "./run.mjs";
+import { verifyReviewImageCopy } from "./review_image.mjs";
 
 export const EXECUTION_VERSION = 1;
 const exactIdentity = id => typeof id === "string" && !!id.trim();
@@ -29,6 +31,14 @@ const preparationFingerprint = input => {
   const { receipt: _receipt, ...prepared } = input.prepared || {};
   return digest({ environment: input.environment, ...(input.spec ? { spec: input.spec } : { prompt: input.prompt, prepared }) });
 };
+function verifyPreparedReviewImage(input, transport) {
+  const spec = input.spec, args = spec?.args, image = spec?.imageAttachment;
+  if (!Array.isArray(args)) return;
+  const flags = args.slice(0, -1).filter(arg => arg === "--image" || arg === "-i" || typeof arg === "string" && (arg.startsWith("--image=") || arg.startsWith("-i=")));
+  if (!image && flags.length === 0) return;
+  if (transport || input.kind !== "intake" || input.preparation?.boundary !== "codex-draft-sandbox-v1" || flags.length !== 1 || args.at(-4) !== "--image" || args.at(-3) !== image?.file || args.at(-2) !== "--" || !spec.options?.cwd) throw executionError("TASK_PREPARATION_BOUNDARY", "image attachment does not match the restricted prepared input");
+  verifyReviewImageCopy(spec.options.cwd, image.file, image.expected);
+}
 export const executionRunner = (ctx, id, provider = ctx.state.get(id)?.harness) => ctx.executionFor && provider ? ctx.executionFor(id, provider) : ctx.runnerFor(id);
 
 const epochFile = (root, epoch) => join(root, epoch ? `execution-${epoch}.json` : "execution.json");
@@ -319,6 +329,7 @@ export function makeExecution({ root, taskId, provider, account = "operator", tr
       if (prior.acceptance !== "accepted" || (transport && !ownedRemote(prior.job?.execution))) throw executionError("EXECUTION_UNKNOWN", `submission ${prior.runId} acceptance is unknown; reconcile its recorded idempotency key; no new dispatch`);
       return { ...prior.job };
     }
+    if (input.kind === "intake") verifyPreparedReviewImage(input, transport);
     if (s.learningContinuity?.pending && (method !== "submit" || input.sessionId)) throw executionError("EXECUTION_CONTINUATION", "retired advice requires a new provider session, not continuation");
     if (s.stopped) throw executionError("EXECUTION_STOPPED", `dispatch stopped: ${s.stopped}; late results remain quarantined`);
     if (s.current && executionLive(s.current)) throw executionError("BUSY", "previous provider work is not settled");
@@ -356,6 +367,7 @@ export function makeExecution({ root, taskId, provider, account = "operator", tr
     if (transport) project(s);
     let accepted;
     try {
+      if (!transport && input.kind === "intake") verifyPreparedReviewImage(input, transport);
       accepted = transport ? await call(method, { ...input, taskId, provider, account, runId: id, idempotencyKey: intent.idempotencyKey })
         : await runner.start(input.name, input.spec.cmd, input.spec.args, { ...input.spec.options, runId: id, privateOutput: { taskId, runId: id, provider } });
     } catch (e) {
@@ -400,6 +412,7 @@ export function makeExecution({ root, taskId, provider, account = "operator", tr
       if (!transport) runner.observe?.();
       if (!s.current) return current();
       if (!transport) {
+        const before = structuredClone(s);
         let job = runner.current();
         if (!job || job.id !== s.current.id) return current();
         if (s.current.execution.acceptance === "unknown") {
@@ -418,11 +431,23 @@ export function makeExecution({ root, taskId, provider, account = "operator", tr
           catch (error) { s.current.execution.recoveryAction = error.code || "local shutdown remains unverified"; }
           if (!job || job.id !== s.current.id) { save(s); return current(); }
         }
-        Object.assign(s.current.execution, { providerState: job.running ? s.stopped || job.killed ? "cancellation-requested" : "running" : s.current.execution.collected ? s.current.execution.providerState : "retrieving-results", observedAt: clock.now(), reconciledAt: clock.now() });
+        Object.assign(s.current.execution, { providerState: job.running ? s.stopped || job.killed ? "cancellation-requested" : "running" : s.current.execution.collected ? s.current.execution.providerState : "retrieving-results" });
         if (s.stopped && !job.running) confirmLocalStop(s, job);
         const { running: _running, ...record } = job;
         s.current = { ...record, ...(s.current.execution.quarantined ? { exit: s.current.exit, endedAt: s.current.endedAt } : {}), execution: s.current.execution };
-        save(s); runner.annotate?.(s.current.id, { execution: s.current.execution }); return current();
+        // Still observe liveness/output every tick. Persist real changes at
+        // once, but coalesce unchanged live observations to one per minute.
+        // Settled runs need no heartbeat. Never defer a launch or stop intent.
+        const ex = s.current.execution;
+        if (!isDeepStrictEqual(before, s) || job.running &&
+            (ex.reconciledAt == null || clock.now() - ex.reconciledAt >= 60_000)) {
+          Object.assign(ex, { observedAt: clock.now(), reconciledAt: clock.now() });
+          save(s);
+        }
+        // Repair a projection after an interrupted write without rewriting an
+        // already matching job.json on every poll.
+        if (!isDeepStrictEqual(job.execution, ex)) runner.annotate?.(s.current.id, { execution: ex });
+        return current();
       }
       const ex = s.current.execution;
       if (ex.collected && terminal(ex.providerState)) return current();
@@ -626,6 +651,7 @@ export function makeExecution({ root, taskId, provider, account = "operator", tr
     sanitize: (value, id, extraSecrets = []) => redact(value, [...secrets, ...(readJson(join(dirOf(id), "sensitive-redactions.json"))?.secrets || []), ...extraSecrets]),
     prepare: async (input, { build } = {}) => {
       authorize(input);
+      if (input.reviewImage != null && (transport || input.kind !== "intake" || provider !== "codex")) throw executionError("TASK_PREPARATION_BOUNDARY", "image review requires the restricted local reviewer; no fallback is available");
       if (input.kind !== "intake") return transport ? call("prepare", input) : input;
       authorizePreparation(read());
       const receipt = preparationReceipt(provider, capabilities, account);
@@ -701,7 +727,26 @@ export function makeExecution({ root, taskId, provider, account = "operator", tr
         return job;
       } finally { lock.release(); }
     },
-    kill: id => { if (transport) throw executionError("EXECUTION_CONTROL", "remote cancellation must be requested and confirmed by the coordinator"); return runner.kill(id); },
+    kill: id => {
+      if (transport) throw executionError("EXECUTION_CONTROL", "remote cancellation must be requested and confirmed by the coordinator");
+      ensureDir(root);
+      const lock = acquireProcessLock(join(root, "execution.lock"), "execution");
+      try {
+        const s = read();
+        if (s.current) {
+          if (s.current.id !== id) throw executionError("EXECUTION_OWNERSHIP", "interrupt does not own the current local run");
+          // First-turn sessions can be discovered in the stream before their
+          // terminal result. Retain that verified identity BEFORE stopping and
+          // quarantining the run; continuation must not depend on late output.
+          const sessionId = localSession(s, id, adapterFor(provider).sessionFrom(runner.lines(id)));
+          if (sessionId !== s.current.execution.sessionId) {
+            s.current.execution.sessionId = sessionId;
+            save(s); runner.annotate?.(id, { execution: s.current.execution });
+          }
+        }
+        return runner.kill(id);
+      } finally { lock.release(); }
+    },
     waitForKill: id => runner?.waitForKill(id), dirOf,
   };
 }

package/lib/execution_preparation.mjs

@@ -8,6 +8,7 @@ import { ensureDir } from "./fs.mjs";
 import { MAX_PREPARATION_PROMPT_BYTES } from "./task_contract.mjs";
 import { taskError } from "./task_store.mjs";
 import { boundedCall } from "./execution_io.mjs";
+import { copyReviewImage, REVIEW_IMAGE_LIMITS } from "./review_image.mjs";
 
 export async function prepareLocalExecution(provider, capabilities, account, input, build = buildPreparationRun, limits = {}) {
   const receipt = preparationReceipt(provider, capabilities, account);
@@ -25,5 +26,19 @@ export async function prepareLocalExecution(provider, capabilities, account, inp
   if (spec.configure) spec = await boundedCall(signal => spec.configure(spec, { cwd: input.cwd, env, signal }), limits);
   check(); // An adapter's final configuration cannot replace its authority.
   assertSafeEnv(env);
-  return { receipt, environment: input.environment, spec: { cmd: spec.cmd, args: spec.args, options: { cwd: input.cwd, env, inheritEnv: false } } };
+  let copy, imageAttachment;
+  try {
+    if (input.reviewImage != null) {
+      if (provider !== "codex" || spec.reviewImageBoundary !== "coordinator-copy-v1" || spec.boundary !== "codex-draft-sandbox-v1") throw taskError("TASK_PREPARATION_BOUNDARY", "image attachment requires the restricted reviewer boundary");
+      const { content, ...expected } = input.reviewImage;
+      if (typeof content !== "string" || !Number.isSafeInteger(expected.bytes) || expected.bytes < 1 || expected.bytes > REVIEW_IMAGE_LIMITS.individualBytes || content.length !== Math.ceil(expected.bytes / 3) * 4 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(content)) throw taskError("TASK_PREPARATION_BOUNDARY", "image attachment bytes are incomplete");
+      const bytes = Buffer.from(content, "base64");
+      if (bytes.length !== expected.bytes || bytes.toString("base64") !== content) throw taskError("TASK_PREPARATION_BOUNDARY", "image attachment bytes differ");
+      copy = copyReviewImage(input.cwd, bytes, expected);
+      spec.args = [...spec.args.slice(0, -1), "--image", copy.file, "--", spec.args.at(-1)];
+      imageAttachment = { file: copy.file, expected };
+      check();
+    }
+    return { receipt, environment: input.environment, spec: { cmd: spec.cmd, args: spec.args, options: { cwd: input.cwd, env, inheritEnv: false }, ...(imageAttachment ? { imageAttachment } : {}) } };
+  } catch (error) { copy?.cleanup(); throw error; }
 }

package/lib/execution_result.mjs

@@ -1,3 +1,6 @@
+import { publicationPolicyOf, assertPublicationPaths, workArtifactReason } from "./work_artifacts.mjs";
+import { assertAgentsCheckout } from "./openai_agents_sources.mjs";
+import { hostApi } from "./hosts.mjs";
 // Result transport ends here. Git/gh own the one publication path; the existing
 // tick still owns readiness, receipts, review rounds, conflicts and human merge.
 import { createHash } from "node:crypto";
@@ -7,7 +10,8 @@ import { unlinkSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { repositoryPath, repositoryRelativePath, assertRepositoryTargets, readRepositoryText, writeRepositoryText } from "./repository_files.mjs";
 import { isOurBranch, runEnv } from "./git.mjs";
 import { ensureDir, readJson, writeJsonAtomic } from "./fs.mjs";
-import { execFileAsync, remoteMatches } from "./gh.mjs";
+import { execFileAsync } from "./process.mjs";
+import { remoteMatches } from "./repository.mjs";
 import { parsePrd, verifyCommands } from "./prd.mjs";
 import { normalizePublicBody } from "./block.mjs";
 import { assertPublicText, assertNoNul } from "./public_output.mjs";
@@ -103,6 +107,8 @@ async function applyExecutionResult(ctx, { id, entry, result, dir, verify = exec
   // input requires an explicit corrective run, with no repeated application.
   const fail = (message, retryable = false) => { throw Object.assign(executionError("EXECUTION_RESULT", message), { publicationValidation: !retryable }); };
   const validate = fn => { try { return fn(); } catch (error) { if (error.code) throw error; fail(error.message); } };
+  const approvedBrief = ctx.readPrd(id) || "";
+  const publicationPolicy = validate(() => publicationPolicyOf(parsePrd(approvedBrief, `${id}.md`), { sources: entry.sources || [] }));
   const execution = ctx.executionFor?.(id, entry.harness);
   const assertNotStopped = () => {
     const current = ctx.state?.get(id) || entry;
@@ -149,7 +155,7 @@ async function applyExecutionResult(ctx, { id, entry, result, dir, verify = exec
     catch (error) { fail(error.message); }
   };
   if (result.pushedHead) {
-    if (result.files?.length || await ctx.gh.refSha(entry.repo, entry.branch) !== result.pushedHead || !await ctx.gh.containsCommit(entry.repo, entry.branch, result.inputHead)) fail("pushed result revision or input ancestry cannot be verified");
+    if (result.files?.length || await hostApi(ctx).refSha(entry.repo, entry.branch) !== result.pushedHead || !await hostApi(ctx).containsCommit(entry.repo, entry.branch, result.inputHead)) fail("pushed result revision or input ancestry cannot be verified");
     if (head !== result.pushedHead) fail("reconcile the exact pushed provider branch into its isolated checkout before collection");
     await validateTargets();
   } else {
@@ -161,6 +167,7 @@ async function applyExecutionResult(ctx, { id, entry, result, dir, verify = exec
       paths.add(path);
       changes.push({ ...file, path });
     }
+    validate(() => assertPublicationPaths(changes.filter(file => file.text !== null).map(file => file.path), publicationPolicy));
     await validateTargets(changes.map(file => file.path));
     let modesMatch;
     try { modesMatch = await ctx.git.resultModesMatch(entry.worktree, result.inputHead, [...paths]); }
@@ -191,6 +198,15 @@ async function applyExecutionResult(ctx, { id, entry, result, dir, verify = exec
     }
   }
   const appliedHead = verified ? prior.appliedHead : await ctx.git.head(entry.worktree);
+  // A provider may return an already-pushed branch or a resumed publication may
+  // contain earlier commits. Check the full branch, not only this turn's manifest.
+  let publicationPaths;
+  try { publicationPaths = await ctx.git.publicationPaths(entry.worktree, entry.base); }
+  catch { fail("complete branch publication paths unavailable; retrieve Git base metadata before publication", true); }
+  validate(() => assertPublicationPaths(publicationPaths, publicationPolicy));
+  const privateInputPaths = [...new Set([...publicationPolicy.inputFiles, ...(entry.prd ? [entry.prd] : [])])]
+    .filter(path => workArtifactReason(path, publicationPolicy));
+  const privateInputs = privateInputPaths.map(path => ({ path, text: path === entry.prd ? approvedBrief : ctx.readSource?.(id, path) }));
   const assertVerifiedTree = async () => {
     let revision, tree;
     try {
@@ -199,7 +215,12 @@ async function applyExecutionResult(ctx, { id, entry, result, dir, verify = exec
     } catch { block("verification-state-unavailable", "cannot verify the checkout revision and clean index/worktree", appliedHead); }
     if (revision !== appliedHead) block("verification-head-changed", "verification changed the input head; review that change before publishing", appliedHead);
     if (!tree || ![tree.modified, tree.untracked].every(count => Number.isInteger(count) && count >= 0)) block("verification-state-unavailable", "cannot verify clean index/worktree status", appliedHead);
-    if (tree.modified || tree.untracked) block("verification-dirty", "verification requires a clean index/worktree; preserve uncommitted files before correction", appliedHead);
+    if (privateInputs.length) {
+      try {
+        await assertAgentsCheckout({ worktree: entry.worktree, overlays: privateInputs, immutableOverlays: true });
+        if (await ctx.git.resultModesMatch(entry.worktree, result.inputHead, privateInputPaths) !== true) throw new Error("private input modes changed");
+      } catch { block("verification-dirty", "verification requires a clean index/worktree apart from unchanged approved private inputs; preserve uncommitted files before correction", appliedHead); }
+    } else if (tree.modified || tree.untracked) block("verification-dirty", "verification requires a clean index/worktree; preserve uncommitted files before correction", appliedHead);
   };
   await assertVerifiedTree();
   const evidenceFile = join(dir, "verification.json");
@@ -256,10 +277,10 @@ async function applyExecutionResult(ctx, { id, entry, result, dir, verify = exec
   try {
     assertNotStopped();
     if (execution?.current && execution.current()?.id !== result.runId) fail("publication root changed; reconcile the exact owned result before publishing", true);
-    await ctx.git.pushResult(entry.worktree, entry.branch);
+    await ctx.git.pushResult(entry.worktree, entry.branch, entry.repo);
     await assertVerifiedTree();
     assertNotStopped();
-    const pr = await ctx.gh.publishResultPr({ repo: entry.repo, branch: entry.branch, base: entry.base, title: result.pr.title, body });
+    const pr = await hostApi(ctx).publishResultPr({ repo: entry.repo, branch: entry.branch, base: entry.base, title: result.pr.title, body });
     writeJsonAtomic(checkpoint, { fingerprint, phase: "published", appliedHead, pr: pr.number, url: pr.url });
     return { head: appliedHead, pr, evidence };
   } finally { exclusion.release(); }