@kal-elsam/kairo-runtime 0.10.0 → 0.12.0

package/src/global/runtime/alerts/alert-cli.js

@@ -0,0 +1,31 @@
+import { resolveHomeDir } from "../../paths.js";
+import { printJson } from "../../json-output.js";
+import { commandHeader } from "../../brand/index.js";
+import { formatCliCommand } from "../../brand/cli.js";
+import { controlledDismissAlert, controlledResolveAlert } from "./controlled-alert-actions.js";
+
+export async function runGlobalAlerts(options) {
+  const homeDir = resolveHomeDir();
+  const action = options.alertsAction;
+  const alertId = options.alertId;
+  if ((action !== "resolve" && action !== "dismiss") || !alertId) {
+    throw new Error(`Use: ${formatCliCommand("alerts resolve|dismiss <alertId> --confirm-…")}`);
+  }
+  const isResolve = action === "resolve";
+  const confirmed = Boolean(isResolve ? options.confirmResolve : options.confirmDismiss);
+  const result = await (isResolve ? controlledResolveAlert : controlledDismissAlert)({
+    alertId, confirmed, source: "cli", homeDir
+  });
+  if (options.json) {
+    printJson({
+      ok: result.ok, code: result.code, alertId, state: result.alert?.state ?? null,
+      permissionAuthority: result.permissionAuthority, diagnostics: result.diagnostics
+    });
+  } else if (result.ok) {
+    console.log(`${commandHeader(`alerts ${action}`)}\n${alertId} → ${result.alert.state}`);
+  } else {
+    console.error(`alerts ${action} failed (${result.code}).`);
+  }
+  if (!result.ok) process.exitCode = 2;
+  return result;
+}

package/src/global/runtime/alerts/alert-store.js

@@ -10,6 +10,11 @@ import {
   createAlertFingerprint
 } from "./alert-types.js";
 import { assertAlertSecretFree } from "./alert-validate.js";
+import {
+  PermissionAuthorityError,
+  UNSAFE_OPERATIONS,
+  assertUnsafePermissionAuthority
+} from "../run-permissions.js";
 
 const TERMINAL_ALERT_STATES = new Set([ALERT_STATES.RESOLVED, ALERT_STATES.DISMISSED]);
 
@@ -190,7 +195,7 @@ export async function listAlerts({ homeDir, state = null, limit = null } = {}) {
   return Number.isInteger(limit) && limit >= 0 ? filtered.slice(0, limit) : filtered;
 }
 
-async function transitionAlert(alertId, nextState, { homeDir } = {}) {
+async function transitionAlert(alertId, nextState, { homeDir, permissionAuthority } = {}) {
   const current = await loadAlert(alertId, { homeDir });
   if (current.state !== ALERT_STATES.OPEN) return current;
   const now = new Date().toISOString();
@@ -198,7 +203,8 @@ async function transitionAlert(alertId, nextState, { homeDir } = {}) {
     ...current,
     state: nextState,
     updatedAt: now,
-    resolvedAt: now
+    resolvedAt: now,
+    permissionAuthority
   }, { homeDir });
   const indexPath = openIndexPath(homeDir, current.fingerprint);
   await unlink(indexPath).catch((error) => {
@@ -207,10 +213,27 @@ async function transitionAlert(alertId, nextState, { homeDir } = {}) {
   return updated;
 }
 
-export async function resolveAlert(alertId, { homeDir } = {}) {
-  return transitionAlert(alertId, ALERT_STATES.RESOLVED, { homeDir });
+function requireMutationAuthority(permissionAuthority, expectedOperation) {
+  try {
+    return assertUnsafePermissionAuthority(permissionAuthority, { expectedOperation });
+  } catch (error) {
+    if (error instanceof PermissionAuthorityError) {
+      throw new AlertStoreError(error.message, {
+        code: error.code ?? "permission_authority_required", details: error.details
+      });
+    }
+    throw error;
+  }
 }
 
-export async function dismissAlert(alertId, { homeDir } = {}) {
-  return transitionAlert(alertId, ALERT_STATES.DISMISSED, { homeDir });
+export async function resolveAlert(alertId, { homeDir, permissionAuthority } = {}) {
+  return transitionAlert(alertId, ALERT_STATES.RESOLVED, {
+    homeDir, permissionAuthority: requireMutationAuthority(permissionAuthority, UNSAFE_OPERATIONS.ALERT_RESOLVE)
+  });
+}
+
+export async function dismissAlert(alertId, { homeDir, permissionAuthority } = {}) {
+  return transitionAlert(alertId, ALERT_STATES.DISMISSED, {
+    homeDir, permissionAuthority: requireMutationAuthority(permissionAuthority, UNSAFE_OPERATIONS.ALERT_DISMISS)
+  });
 }

package/src/global/runtime/alerts/alert-validate.js

@@ -19,8 +19,10 @@ const FORBIDDEN_KEYS = new Set([
 ]);
 const ALLOWED = new Set([
   "version", "alertId", "kind", "severity", "title", "summary",
-  "source", "fingerprint", "state", "createdAt", "updatedAt", "resolvedAt"
+  "source", "fingerprint", "state", "createdAt", "updatedAt", "resolvedAt",
+  "permissionAuthority"
 ]);
+const PA_KEYS = new Set(["mode", "source", "consent", "operation"]);
 
 export class AlertValidationError extends Error {
   constructor(message, { code, details = null } = {}) {
@@ -102,6 +104,28 @@ export function assertAlertSecretFree(alert) {
       code: ALERT_VALIDATION_ERROR_CODES.INVALID_ALERT
     });
   }
+  if (alert.permissionAuthority != null) {
+    const pa = alert.permissionAuthority;
+    if (!pa || typeof pa !== "object" || Array.isArray(pa)) {
+      throw new AlertValidationError("Invalid alert.permissionAuthority.", {
+        code: ALERT_VALIDATION_ERROR_CODES.INVALID_ALERT
+      });
+    }
+    for (const key of Object.keys(pa)) {
+      if (!PA_KEYS.has(key) || typeof pa[key] !== "string" || !pa[key].trim()) {
+        throw new AlertValidationError(`Invalid alert.permissionAuthority.${key}.`, {
+          code: ALERT_VALIDATION_ERROR_CODES.INVALID_ALERT, details: { key }
+        });
+      }
+    }
+    for (const key of PA_KEYS) {
+      if (typeof pa[key] !== "string" || !pa[key].trim()) {
+        throw new AlertValidationError(`Missing alert.permissionAuthority.${key}.`, {
+          code: ALERT_VALIDATION_ERROR_CODES.INVALID_ALERT, details: { key }
+        });
+      }
+    }
+  }
   const expected = createAlertFingerprint({
     kind: alert.kind,
     source: alert.source,

package/src/global/runtime/alerts/controlled-alert-actions.js

@@ -0,0 +1,56 @@
+import {
+  CONSENT_TYPES,
+  PermissionAuthorityError,
+  UNSAFE_OPERATIONS,
+  authorizeUnsafeOperation as defaultAuthorize
+} from "../run-permissions.js";
+import { dismissAlert, resolveAlert } from "./alert-store.js";
+
+function fail(code, message, permissionAuthority = null) {
+  return { ok: false, code, message, alert: null, permissionAuthority, diagnostics: [code] };
+}
+
+async function runControlled({
+  operation, confirmed, source, consentType, alertId, homeDir,
+  authorizeUnsafeOperation = defaultAuthorize, mutate
+}) {
+  let permissionAuthority = null;
+  try {
+    ({ permissionAuthority } = authorizeUnsafeOperation({
+      operation, confirmed: Boolean(confirmed), source, consentType
+    }));
+  } catch (error) {
+    if (error instanceof PermissionAuthorityError) {
+      return fail(error.code ?? "unsafe_consent_required", error.message, null);
+    }
+    throw error;
+  }
+  const alert = await mutate(alertId, { homeDir, permissionAuthority });
+  return {
+    ok: true, code: "ok", message: null, alert, permissionAuthority, diagnostics: []
+  };
+}
+
+export async function controlledResolveAlert({
+  alertId, confirmed = false, source = "cli", consentType = null, homeDir,
+  authorizeUnsafeOperation, resolve = resolveAlert
+} = {}) {
+  return runControlled({
+    operation: UNSAFE_OPERATIONS.ALERT_RESOLVE, confirmed, source, consentType, alertId, homeDir,
+    authorizeUnsafeOperation,
+    mutate: (id, opts) => resolve(id, opts)
+  });
+}
+
+export async function controlledDismissAlert({
+  alertId, confirmed = false, source = "cli", consentType = null, homeDir,
+  authorizeUnsafeOperation, dismiss = dismissAlert
+} = {}) {
+  return runControlled({
+    operation: UNSAFE_OPERATIONS.ALERT_DISMISS, confirmed, source, consentType, alertId, homeDir,
+    authorizeUnsafeOperation,
+    mutate: (id, opts) => dismiss(id, opts)
+  });
+}
+
+export { CONSENT_TYPES, UNSAFE_OPERATIONS };

package/src/global/runtime/execution-adapters/claude.js

@@ -58,7 +58,8 @@ export default createExecutionAdapter({
     tokens: true,
     diff: false,
     cancel: true,
-    transcript: true
+    transcript: true,
+    permissionModes: ["force", "yolo"]
   },
   buildLaunch: buildClaudeLaunch,
   parseEventLine: parseClaudeEventLine

package/src/global/runtime/execution-adapters/codex.js

@@ -72,7 +72,8 @@ export default createExecutionAdapter({
     diff: false,
     cancel: true,
     transcript: true,
-    reviewCompatible: true
+    reviewCompatible: true,
+    permissionModes: ["yolo"]
   },
   buildLaunch: buildCodexLaunch,
   parseEventLine: parseCodexEventLine

package/src/global/runtime/execution-adapters/create-execution-adapter.js

@@ -1,4 +1,7 @@
 import { isExecutableAvailable } from "../../cli-probe.js";
+import { buildPermissionsArgs } from "../run-permissions.js";
+
+export { buildPermissionsArgs };
 
 export function createExecutionAdapter({
   id,
@@ -77,17 +80,3 @@ export function parseNdjsonLine(line) {
     return null;
   }
 }
-
-export function buildPermissionsArgs(permissions = []) {
-  const normalized = new Set(permissions.map((entry) => String(entry).toLowerCase()));
-
-  if (normalized.has("all") || normalized.has("force")) {
-    return ["--force"];
-  }
-
-  if (normalized.has("yolo") || normalized.has("dangerously-skip-permissions")) {
-    return ["--dangerously-skip-permissions"];
-  }
-
-  return [];
-}

package/src/global/runtime/execution-adapters/cursor.js

@@ -96,7 +96,8 @@ export default createExecutionAdapter({
     tokens: true,
     diff: false,
     cancel: true,
-    transcript: true
+    transcript: true,
+    permissionModes: ["force", "yolo"]
   },
   checkAvailability: checkCursorAvailability,
   buildLaunch: buildCursorLaunch,

package/src/global/runtime/execution-adapters/opencode.js

@@ -31,7 +31,8 @@ export default createExecutionAdapter({
     tokens: false,
     diff: false,
     cancel: true,
-    transcript: false
+    transcript: false,
+    permissionModes: ["force"]
   },
   buildLaunch: buildOpencodeLaunch,
   parseEventLine: null

package/src/global/runtime/execution-adapters/pi.js

@@ -186,7 +186,8 @@ export default createExecutionAdapter({
     diff: false,
     cancel: true,
     transcript: true,
-    reviewCompatible: true
+    reviewCompatible: true,
+    permissionModes: ["read-only"]
   },
   checkAvailability: checkPiAvailability,
   buildLaunch: buildPiLaunch,

package/src/global/runtime/review/index.js

@@ -6,7 +6,7 @@ export {
 } from "./review-types.js";
 export {
   resolveReviewSnapshot, fingerprintReviewSnapshot, detectReviewSnapshotDrift,
-  readReviewRegularFile
+  verifyStagedReviewReceipt, readReviewRegularFile
 } from "./review-git.js";
 export {
   REVIEW_PATCH_ERROR_CODES, filterDiffToAdmittedPaths, buildScopedReviewPatch

package/src/global/runtime/review/review-cli.js

@@ -5,10 +5,12 @@ import { formatCliCommand } from "../../brand/cli.js";
 import {
   isInteractiveTerminal, promptApplyConfirmation
 } from "../../apply-confirmation.js";
+import { exportGentleReviewBundle as defaultExportGentleReviewBundle } from "../../observability/gentle-bundle-export.js";
+import { importGentleReviewBundle as defaultImportGentleReviewBundle } from "../../observability/gentle-bundle-import.js";
 import {
   REVIEW_EXIT_CODES, REVIEW_SEVERITIES,
   assertReceiptSecretFree, assertSafeReviewId,
-  listReviewReceipts, loadReviewReceipt
+  listReviewReceipts, loadReviewReceipt, verifyStagedReviewReceipt
 } from "./index.js";
 import { runReview } from "./review-runner.js";
 
@@ -83,7 +85,8 @@ export async function runGlobalReview(options, packageManifest, deps = {}) {
 
     const result = await (deps.runReview ?? runReview)({
       cwd: options.cwd, agent: options.agent, base: options.base ?? null,
-      commit: options.commit ?? null, model: options.model ?? null,
+      commit: options.commit ?? null, staged: Boolean(options.staged),
+      model: options.model ?? null,
       includePrivate: Boolean(options.includePrivate),
       privateConfirmed: consent.privateConfirmed, failOn,
       homeDir, cliVersion: packageManifest?.version ?? null
@@ -138,7 +141,114 @@ export async function runGlobalReviews(options, _packageManifest, deps = {}) {
       else printReviewHuman(receipt, REVIEW_EXIT_CODES.OK);
       return { receipt };
     }
-    throw new Error(`Unknown reviews action "${action}". Use list or show.`);
+    if (action === "verify") {
+      if (!options.reviewId) {
+        throw new Error(`Missing review id. Use: ${formatCliCommand("reviews verify <reviewId> --staged")}`);
+      }
+      if (!options.staged) {
+        throw new Error(`Staged verification requires --staged. Use: ${formatCliCommand("reviews verify <reviewId> --staged")}`);
+      }
+      try { assertSafeReviewId(options.reviewId); }
+      catch { throw new Error(`Invalid review id "${options.reviewId}".`); }
+      let receipt;
+      try {
+        receipt = publicReceipt(await loadReviewReceipt(options.reviewId, { homeDir }));
+      } catch {
+        throw new Error(`Review receipt not found: ${options.reviewId}`);
+      }
+      const verified = await (deps.verifyStaged ?? verifyStagedReviewReceipt)(receipt, {
+        cwd: options.cwd ?? process.cwd()
+      });
+      const exitCode = verified.ok ? REVIEW_EXIT_CODES.OK : REVIEW_EXIT_CODES.ERROR;
+      if (options.json) {
+        printJson({
+          ok: verified.ok, exitCode, stale: verified.stale, reviewId: receipt.reviewId,
+          previousFingerprint: verified.previousFingerprint,
+          nextFingerprint: verified.nextFingerprint, headSha: verified.headSha
+        });
+      } else {
+        console.log(commandHeader(`reviews verify ${receipt.reviewId}`));
+        console.log(verified.ok ? "Staged candidate matches receipt." : "Staged candidate drifted; receipt invalid.");
+      }
+      process.exitCode = exitCode;
+      return { ...verified, exitCode, receipt };
+    }
+    if (action === "export") {
+      if (!options.lineage) {
+        throw new Error(
+          `Missing lineage. Use: ${formatCliCommand("reviews export <lineage> --out <path>")}`
+        );
+      }
+      if (!options.outPath) {
+        throw new Error(
+          `Missing --out. Use: ${formatCliCommand("reviews export <lineage> --out <path>")}`
+        );
+      }
+      const exported = await (deps.exportGentleReviewBundle ?? defaultExportGentleReviewBundle)({
+        lineage: options.lineage,
+        outPath: options.outPath,
+        cwd: options.cwd ?? process.cwd()
+      });
+      const exitCode = exported.ok ? REVIEW_EXIT_CODES.OK : REVIEW_EXIT_CODES.ERROR;
+      process.exitCode = exitCode;
+      if (options.json) {
+        printJson({
+          ok: exported.ok,
+          exitCode,
+          code: exported.code,
+          lineage: exported.lineage,
+          outPath: exported.outPath,
+          diagnostics: exported.diagnostics,
+          providerStatus: exported.providerStatus ?? null,
+          timedOut: Boolean(exported.timedOut)
+        });
+      } else {
+        console.log(commandHeader(`reviews export ${exported.lineage ?? options.lineage}`));
+        if (exported.ok) console.log(`Exported via Gentle AI → ${exported.outPath}`);
+        else {
+          console.error(`Export failed (${exported.code}).`);
+          for (const line of exported.diagnostics ?? []) console.error(`  ${line}`);
+        }
+      }
+      return { ...exported, exitCode };
+    }
+    if (action === "import") {
+      if (!options.bundlePath) {
+        throw new Error(
+          `Missing --bundle. Use: ${formatCliCommand("reviews import --bundle <path> --confirm-import")}`
+        );
+      }
+      const imported = await (deps.importGentleReviewBundle ?? defaultImportGentleReviewBundle)({
+        bundlePath: options.bundlePath,
+        cwd: options.cwd ?? process.cwd(),
+        confirmImport: Boolean(options.confirmImport)
+      });
+      const exitCode = imported.ok ? REVIEW_EXIT_CODES.OK : REVIEW_EXIT_CODES.ERROR;
+      process.exitCode = exitCode;
+      if (options.json) {
+        printJson({
+          ok: imported.ok,
+          exitCode,
+          code: imported.code,
+          mutationOutcome: imported.mutationOutcome,
+          bundlePath: imported.bundlePath,
+          cwd: imported.cwd,
+          diagnostics: imported.diagnostics,
+          providerStatus: imported.providerStatus ?? null,
+          timedOut: Boolean(imported.timedOut),
+          permissionAuthority: imported.permissionAuthority ?? null
+        });
+      } else {
+        console.log(commandHeader(`reviews import ${imported.bundlePath ?? options.bundlePath}`));
+        if (imported.ok) console.log("Imported via Gentle AI (provider-owned authority).");
+        else {
+          console.error(`Import failed (${imported.code}; mutation=${imported.mutationOutcome}).`);
+          for (const line of imported.diagnostics ?? []) console.error(`  ${line}`);
+        }
+      }
+      return { ...imported, exitCode };
+    }
+    throw new Error(`Unknown reviews action "${action}". Use list, show, verify, export, or import.`);
   } catch (error) {
     const exitCode = REVIEW_EXIT_CODES.ERROR;
     const message = String(error?.message ?? error);

package/src/global/runtime/review/review-git.js

@@ -91,24 +91,94 @@ function parseNameStatus(text) {
 function fingerprintPayload(s) {
   return {
     mode: s.mode, headSha: s.headSha, base: s.base ?? null, commit: s.commit ?? null,
-    files: s.files.map((f) => ({
-      path: f.path, sourcePath: f.sourcePath ?? null, status: f.status, hash: f.hash, changedLines: f.changedLines
-    })),
+    files: s.files.map((f) => {
+      const entry = {
+        path: f.path, sourcePath: f.sourcePath ?? null, status: f.status,
+        hash: f.hash, changedLines: f.changedLines
+      };
+      if (f.mode != null) entry.mode = f.mode;
+      return entry;
+    }),
     excluded: s.excluded.map((e) => ({ path: e.path, reason: e.reason }))
   };
 }
 
+function parseRawDiff(text) {
+  return text.split("\n").filter((l) => l.startsWith(":")).map((line) => {
+    const columns = line.slice(1).split("\t");
+    const parts = columns[0].trim().split(/\s+/);
+    const [oldMode, newMode, oldHash, newHash, status] = parts;
+    const pathParts = columns.slice(1).map(unquotePath);
+    if (pathParts.length >= 2) {
+      return {
+        oldMode, newMode, oldHash, newHash, status,
+        sourcePath: pathParts[0], path: pathParts[1]
+      };
+    }
+    return {
+      oldMode, newMode, oldHash, newHash, status,
+      sourcePath: null, path: pathParts[0]
+    };
+  });
+}
+
+async function resolveObjectIdLength(cwd, execFileImpl) {
+  try {
+    const format = (await git(cwd, ["rev-parse", "--show-object-format"], execFileImpl)).trim();
+    return format === "sha256" ? 64 : 40;
+  } catch {
+    return 40;
+  }
+}
+
+function assertFullObjectId(hash, expectedLength, { path, role = "blob" } = {}) {
+  if (hash == null || hash === "" || /^0+$/.test(hash)) {
+    throw new ReviewSnapshotError(
+      `Missing ${role} object ID for staged path "${path}".`,
+      {
+        code: REVIEW_SNAPSHOT_ERROR_CODES.TRUNCATED_OBJECT_ID,
+        details: { path, role, hash, expectedLength }
+      }
+    );
+  }
+  if (!new RegExp(`^[a-f0-9]{${expectedLength}}$`, "i").test(hash)) {
+    throw new ReviewSnapshotError(
+      `Truncated or invalid ${role} object ID for "${path}" `
+      + `(got length ${String(hash).length}, expected ${expectedLength}).`,
+      {
+        code: REVIEW_SNAPSHOT_ERROR_CODES.TRUNCATED_OBJECT_ID,
+        details: { path, role, hash, expectedLength }
+      }
+    );
+  }
+  return hash.toLowerCase();
+}
+
+async function blobIsBinary(cwd, blobHash, execFileImpl) {
+  if (!blobHash || /^0+$/.test(blobHash)) return false;
+  try {
+    const { stdout } = await execFileImpl("git", ["cat-file", "-p", blobHash], {
+      cwd, encoding: null, maxBuffer: 8 * 1024 * 1024
+    });
+    return isBinaryContent(Buffer.isBuffer(stdout) ? stdout : Buffer.from(stdout ?? ""));
+  } catch {
+    return false;
+  }
+}
+
 /** Bounded Git review snapshot via argv-only git (no shell, no repo writes). */
 export async function resolveReviewSnapshot({
-  cwd, base = null, commit = null, includePrivate = false, privateConfirmed = false,
+  cwd, base = null, commit = null, staged = false, includePrivate = false, privateConfirmed = false,
   execFileImpl = defaultExecFile
 } = {}) {
-  const mode = resolveReviewScopeMode({ base, commit });
+  const mode = resolveReviewScopeMode({ base, commit, staged });
   await assertGitRepo(cwd, execFileImpl);
   const headSha = (await git(cwd, ["rev-parse", "HEAD"], execFileImpl)).trim();
   let rawEntries = [];
   let numstat = new Map();
   let diffBytes = 0;
+  let rawIdentity = new Map();
+  let stagedObjectIdLength = null;
 
   if (mode === REVIEW_SCOPE_MODES.WORKING_TREE) {
     rawEntries = parsePorcelain(await git(cwd, ["status", "--porcelain=v1", "-uall"], execFileImpl));
@@ -118,6 +188,17 @@ export async function resolveReviewSnapshot({
     ]);
     diffBytes = Buffer.byteLength(await git(cwd, ["diff"], execFileImpl), "utf8")
       + Buffer.byteLength(await git(cwd, ["diff", "--cached"], execFileImpl), "utf8");
+  } else if (mode === REVIEW_SCOPE_MODES.STAGED) {
+    stagedObjectIdLength = await resolveObjectIdLength(cwd, execFileImpl);
+    rawEntries = parseNameStatus(await git(cwd, ["diff", "--cached", "--name-status"], execFileImpl));
+    numstat = parseNumstat(await git(cwd, ["diff", "--cached", "--numstat"], execFileImpl));
+    diffBytes = Buffer.byteLength(await git(cwd, ["diff", "--cached"], execFileImpl), "utf8");
+    const rawText = await git(cwd, [
+      "-c", "core.abbrev=no", "diff", "--cached", "--raw", "--full-index"
+    ], execFileImpl);
+    for (const entry of parseRawDiff(rawText)) {
+      rawIdentity.set(entry.path, entry);
+    }
   } else if (mode === REVIEW_SCOPE_MODES.BASE) {
     const range = `${base}...HEAD`;
     await git(cwd, ["rev-parse", "--verify", base], execFileImpl);
@@ -127,10 +208,10 @@ export async function resolveReviewSnapshot({
   } else {
     await git(cwd, ["rev-parse", "--verify", `${commit}^{commit}`], execFileImpl);
     rawEntries = parseNameStatus(
-      await git(cwd, ["diff-tree", "--no-commit-id", "--name-status", "-r", commit], execFileImpl)
+      await git(cwd, ["diff-tree", "--no-commit-id", "--name-status", "-r", "--root", commit], execFileImpl)
     );
     numstat = parseNumstat(
-      await git(cwd, ["diff-tree", "--no-commit-id", "--numstat", "-r", commit], execFileImpl)
+      await git(cwd, ["diff-tree", "--no-commit-id", "--numstat", "-r", "--root", commit], execFileImpl)
     );
     diffBytes = Buffer.byteLength(await git(cwd, ["show", "--format=", "--patch", commit], execFileImpl), "utf8");
   }
@@ -149,6 +230,7 @@ export async function resolveReviewSnapshot({
     }
 
     let hash;
+    let modeBits = null;
     let changedLines = numstat.get(path) ?? 0;
     let bytes = 0;
     const deleted = /D/.test(entry.status);
@@ -168,14 +250,37 @@ export async function resolveReviewSnapshot({
       bytes = buffer.length;
       if (!numstat.has(path)) changedLines = buffer.toString("utf8").split(/\r?\n/).length;
       if (entry.status === "??") diffBytes += bytes;
+    } else if (mode === REVIEW_SCOPE_MODES.STAGED) {
+      const identity = rawIdentity.get(path);
+      if (!identity) {
+        throw new ReviewSnapshotError(
+          `Missing staged raw identity for "${path}".`,
+          {
+            code: REVIEW_SNAPSHOT_ERROR_CODES.TRUNCATED_OBJECT_ID,
+            details: { path }
+          }
+        );
+      }
+      const blobHash = deleted ? identity.oldHash : identity.newHash;
+      modeBits = deleted ? identity.oldMode : identity.newMode;
+      if (modeBits === "000000") modeBits = identity.oldMode;
+      const fullHash = assertFullObjectId(blobHash, stagedObjectIdLength, { path });
+      if (await blobIsBinary(cwd, fullHash, execFileImpl)) {
+        excluded.push({ path, reason: "binary" });
+        continue;
+      }
+      hash = fullHash;
     } else {
-      try { hash = (await git(cwd, ["rev-parse", `HEAD:${path}`], execFileImpl)).trim(); }
+      const blobRef = mode === REVIEW_SCOPE_MODES.COMMIT ? `${commit}:${path}` : `HEAD:${path}`;
+      try { hash = (await git(cwd, ["rev-parse", blobRef], execFileImpl)).trim(); }
       catch { hash = createHash("sha256").update(`${entry.status}:${path}`).digest("hex"); }
     }
 
-    files.push({
+    const file = {
       path, sourcePath, status: entry.status.trim(), hash, changedLines, bytes
-    });
+    };
+    if (modeBits != null) file.mode = modeBits;
+    files.push(file);
   }
 
   requirePrivateConsent({ includePrivate, privateConfirmed, privatePaths: privateCandidates });
@@ -185,7 +290,8 @@ export async function resolveReviewSnapshot({
   assertWithinReviewLimits({ fileCount: files.length, changedLines, diffBytes });
 
   const snapshot = {
-    version: 1, mode, cwd, headSha, base: base ?? null, commit: commit ?? null,
+    version: mode === REVIEW_SCOPE_MODES.STAGED ? 2 : 1,
+    mode, cwd, headSha, base: base ?? null, commit: commit ?? null,
     files, excluded, totals: { fileCount: files.length, changedLines, diffBytes }, fingerprint: null
   };
   snapshot.fingerprint = canonicalFingerprint(fingerprintPayload(snapshot));
@@ -199,6 +305,7 @@ export function fingerprintReviewSnapshot(snapshot) {
 export async function detectReviewSnapshotDrift(previous, options = {}) {
   const next = await resolveReviewSnapshot({
     cwd: previous.cwd, base: previous.base, commit: previous.commit,
+    staged: previous.mode === REVIEW_SCOPE_MODES.STAGED,
     includePrivate: options.includePrivate ?? false,
     privateConfirmed: options.privateConfirmed ?? false,
     execFileImpl: options.execFileImpl
@@ -210,3 +317,27 @@ export async function detectReviewSnapshotDrift(previous, options = {}) {
     next
   };
 }
+
+/** Fail-closed staged candidate check against a receipt snapshot. */
+export async function verifyStagedReviewReceipt(receipt, {
+  cwd = null, includePrivate = false, privateConfirmed = false, execFileImpl = defaultExecFile
+} = {}) {
+  const snapshot = receipt?.snapshot;
+  if (!snapshot || snapshot.mode !== REVIEW_SCOPE_MODES.STAGED) {
+    throw new ReviewSnapshotError("Staged verification requires a staged review receipt.", {
+      code: REVIEW_SNAPSHOT_ERROR_CODES.INVALID_SCOPE,
+      details: { mode: snapshot?.mode ?? null }
+    });
+  }
+  const drift = await detectReviewSnapshotDrift(
+    { ...snapshot, cwd: cwd ?? snapshot.cwd },
+    { includePrivate, privateConfirmed, execFileImpl }
+  );
+  return {
+    ok: !drift.stale,
+    stale: drift.stale,
+    previousFingerprint: drift.previousFingerprint,
+    nextFingerprint: drift.nextFingerprint,
+    headSha: drift.next.headSha
+  };
+}

package/src/global/runtime/review/review-patch.js

@@ -101,6 +101,8 @@ export async function buildScopedReviewPatch(snapshot, { execFileImpl = defaultE
     raw = await gitDiff(
       cwd, ["show", "--format=", "--patch", snapshot.commit, "--", ...admitted], execFileImpl
     );
+  } else if (snapshot.mode === REVIEW_SCOPE_MODES.STAGED) {
+    raw = await gitDiff(cwd, ["diff", "--cached", "--", ...admitted], execFileImpl);
   } else {
     raw = [
       await gitDiff(cwd, ["diff", "--", ...admitted], execFileImpl),