@uchibeke/gallivant 0.2.0 → 0.3.0

package/lib/control.mjs

@@ -1,3 +1,4 @@
+import { hostApi } from "./hosts.mjs";
 // Local operator requests. UI and CLI enqueue; the daemon is the only consumer.
 // One outstanding request per entry avoids competing resumes and needs no second runner.
 import { randomUUID } from "node:crypto";
@@ -5,7 +6,7 @@ import { needsAgentResume } from "./network_recovery.mjs";
 import { resolveHandle, STATES } from "./state.mjs";
 import { readDaemon, assertDaemonUsable } from "./daemon.mjs";
 import { nowIso } from "./time.mjs";
-import { NEEDS_LABEL, READY_LABEL } from "./gh.mjs";
+import { NEEDS_LABEL, READY_LABEL } from "./host_contract.mjs";
 import { adapterFor } from "./harness.mjs";
 import { executionRunner, unsubmittedInitialDispatch, PROVIDER_STATES } from "./execution.mjs";
 import { requestRunCancellation } from "./run.mjs";
@@ -163,21 +164,28 @@ export async function applyControl(ctx, id) {
   }
   const runner = executionRunner(ctx, id);
   if (runner.current()?.running) return false;
+  if (["message", "resume"].includes(request.action)) {
+    const health = ctx.providerHealth?.get(entry.harness, ctx.config.harness[entry.harness]?.account || "operator");
+    if (health?.pending) {
+      if (request.message !== "Waiting for the provider readiness check.") ctx.state.update(id, current => current.control?.id === request.id ? { control: { ...request, message: "Waiting for the provider readiness check." } } : {});
+      return true;
+    }
+  }
   ctx.state.update(id, { control: { ...request, status: "applying" } });
   try {
     if (entry.state === STATES.done) throw new Error("The task was closed or merged before this request ran.");
     if (entry.pr) {
-      const pr = await ctx.gh.prView(entry.repo, entry.pr);
+      const pr = await hostApi(ctx).prView(entry.repo, entry.pr);
       if (pr.state !== "OPEN") throw new Error("The PR is no longer open.");
     }
     let run = null, initialLaunch = false;
     if (request.action === "recheck") {
       if (needsAgentResume(entry)) throw Object.assign(new Error("The agent failure requires resume, not PR recheck."), { code: "AGENT_RESUME_REQUIRED" });
       if (executionResultCheckpoint(runner)?.phase === "blocked") throw Object.assign(new Error("Result publication needs an explicit corrective resume."), { code: "EXECUTION_RESULT_BLOCKED" });
-      await ctx.gh.removeLabel(entry.repo, entry.pr, READY_LABEL);
-      await ctx.gh.removeLabel(entry.repo, entry.pr, NEEDS_LABEL);
+      await hostApi(ctx).removeLabel(entry.repo, entry.pr, READY_LABEL);
+      await hostApi(ctx).removeLabel(entry.repo, entry.pr, NEEDS_LABEL);
       ctx.state.update(id, {
-        state: STATES.prOpen, reason: null, retry: null, labels_pending: false, public_fix: null,
+        state: STATES.prOpen, reason: null, retry: null, labels_pending: false, public_fix: null, review_next_at: 0,
         last: { ...entry.last, event: "operator requested PR recheck" }, updated_at: nowIso(ctx.clock),
       });
       // Preserve budgets, dispatch markers and the brief. Only the normal tick judges readiness.
@@ -187,13 +195,20 @@ export async function applyControl(ctx, id) {
       run = result.run;
       initialLaunch = result.initialLaunch === true;
       // A cosmetic label failure after spawning must not invite another resume.
-      if (entry.pr) await ctx.gh.removeLabel(entry.repo, entry.pr, NEEDS_LABEL).catch(e => ctx.log.warn(`${id}: could not remove stopped label: ${e.message}`));
+      if (entry.pr) await hostApi(ctx).removeLabel(entry.repo, entry.pr, NEEDS_LABEL).catch(e => ctx.log.warn(`${id}: could not remove stopped label: ${e.message}`));
     }
     finish({ status: "applied", run, message: initialLaunch ? "Started the initial run after repairing launch prerequisites." : request.action === "message"
       ? "Started the next run in the same session with your message."
       : run ? "Resumed the same agent session." : "Watching PR checks and review again." });
     return request.action !== "recheck"; // A recheck continues through normal judgement in this same tick.
   } catch (e) {
+    // PROVIDER_UNAVAILABLE is raised only before launch. Preserve the exact
+    // request when a due probe races with preparation; do not replay an
+    // ambiguous dispatch or turn a failed/auth check into automatic retries.
+    if (e.code === "PROVIDER_UNAVAILABLE" && e.retryableProviderPending === true) {
+      ctx.state.update(id, current => current.control?.id === request.id ? { control: { ...request, status: "queued", message: "Waiting for the provider readiness check." } } : {});
+      return true;
+    }
     ctx.log.warn(`${id}: operator ${request.action} failed: ${e.message}`);
     // Subprocess errors can carry credentials. Details stay in the local daemon log.
     finish({ status: "failed", message: controlFailure(e) });

package/lib/credential.mjs

@@ -1,3 +1,4 @@
+import { parseRemote, repositoryIdentity } from "./repository.mjs";
 // The one place a GitHub credential for a run is resolved.
 //
 // The defect this exists for. A run is sandboxed: it cannot reach the operator's macOS keyring, their Linux secret
@@ -46,15 +47,11 @@ export const SOURCES = Object.freeze({
  * The host a remote URL's credential belongs to. `gh` can be logged in to an enterprise host as well as
  * github.com, and the token for github.com is the wrong one for `github.acme.com`.
  *
- * Only the host is taken, and only from a URL shape we recognise. An SSH remote has no useful host for a token
- * (a token cannot authenticate SSH), so it reads as github.com and the caller's own remote check is what fails.
+ * The strict repository parser supplies the host for every accepted transport. Malformed input throws
+ * without reflecting URL userinfo. The host adapter decides which transport may actually use a token.
  */
 export function hostFromRemote(url) {
-  const s = String(url || "").trim();
-  const m = s.match(/^https?:\/\/(?:[^@/]*@)?([a-z0-9.-]+)/i);
-  if (m) return m[1].toLowerCase();
-  const ssh = s.match(/^(?:ssh:\/\/)?(?:[^@/]+@)([a-z0-9.-]+)[:/]/i);
-  return ssh ? ssh[1].toLowerCase() : "github.com";
+  return parseRemote(url).host;
 }
 
 /** True when a host is github.com itself rather than an enterprise install. */
@@ -111,6 +108,7 @@ export function noCredentialMessage(host = "github.com") {
  * putting a real token anywhere near a fixture.
  */
 export async function resolveCredential(config, { host = "github.com", env = process.env, exec = execFileAsyncQuiet } = {}) {
+  if (host.toLowerCase() === "bitbucket.org") throw new Error("GitHub credentials cannot authorize Bitbucket; resolve its selected credential through the host registry");
   // A configured file is an authority boundary, not merely the first candidate.
   // Missing, unreadable or blank must not silently widen to an ambient login.
   if (config?.github_token_file) {
@@ -134,12 +132,11 @@ export const describe = ({ token, source, host }) =>
   token ? `${source}${isDotCom(host) ? "" : ` for ${host}`} (${token.length} characters)` : "none";
 
 /**
- * The host a checkout's credential belongs to, from its `origin` remote. Failure reads as github.com, because a
- * checkout whose remote cannot be read has a bigger problem than which host its token is for and the caller's own
- * git operations will say so.
+ * The host a checkout's credential belongs to, from its verified origin. Unreadable origins throw before
+ * any credential is resolved; they never fall back to another host.
  */
 export async function hostForWorktree(git, dir) {
-  try { return hostFromRemote(await git.originOf(dir)); } catch { return "github.com"; }
+  return hostFromRemote(await git.originOf(dir));
 }
 
 /**
@@ -154,8 +151,17 @@ export async function hostForWorktree(git, dir) {
  * from the config alone, so a test that wants a credential sets `github_token_file` and one that wants none sets
  * nothing, and no test needs a `gh` on the machine.
  */
-export async function resolveCredentialFor(ctx, { worktree = null } = {}) {
-  const host = worktree && ctx.git ? await hostForWorktree(ctx.git, worktree) : "github.com";
+export async function resolveCredentialFor(ctx, { worktree = null, repo = null } = {}) {
+  let repository = repo ? repositoryIdentity(repo) : null;
+  if (worktree && ctx.git?.originOf) {
+    const actual = parseRemote(await ctx.git.originOf(worktree));
+    if (repository && actual.remoteIdentity !== repository.remoteIdentity) throw new Error("Checkout host/repository mismatch; restore the bound origin before resolving credentials");
+    repository = actual;
+  }
+  repository ??= repositoryIdentity("owner/name");
+  if (ctx.hosts) return ctx.hosts.credential(repository);
   const resolve = ctx.credential ?? (opts => resolveCredential(ctx.config, opts));
-  return resolve({ host });
+  const resolved = await resolve({ host: repository.host });
+  if (resolved?.host && resolved.host !== repository.host) throw new Error("Credential host mismatch");
+  return { ...resolved, host: repository.host, ...(repo || worktree ? { repository: repository.path } : {}) };
 }

package/lib/deliverable.mjs

@@ -35,6 +35,8 @@ export const provenance = (framework = null) => ({ ...(framework ? { framework }
 
 const RECEIPT_RE = new RegExp("^```(?:" + RECEIPT_TAGS.join("|") + ")\\s*\\n([\\s\\S]*?)\\n```[ \t]*\\r?(?=\\n|$)", "gm");
 const receiptMatches = body => [...String(body || "").matchAll(RECEIPT_RE)];
+/** A cross-host handoff must not carry the source task's machine receipt. */
+export const withoutReceipt = body => String(body || "").replace(RECEIPT_RE, "");
 export const publicTaskId = taskId => "task-" + createHash("sha256").update(String(taskId)).digest("hex").slice(0, 24);
 const FETCH_TIMEOUT_MS = 15_000;
 // The hosted route limits the whole JSON body to 256 KiB, including the passport and JSON escaping.

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");