@awak-app/simy-cli 0.5.72 → 0.5.74

package/src/orchestrator/outcome-monitor.js

@@ -1,6 +1,8 @@
 import { createHash } from "node:crypto";
 
-import { acceptanceCriterionRows, hasUserOutcomeProof } from "./completion-contract.js";
+import { acceptanceCriterionRows } from "./completion-contract.js";
+import { evaluateOutcomeProgress } from "./outcome-progress.js";
+import { independentAuditEvidenceIdentity } from "./pr-preparation.js";
 
 function objective(charter) {
   return {
@@ -27,11 +29,12 @@ function canonicalValue(value) {
   return value;
 }
 
-function digest(value, algorithm) {
+export function objectiveValueDigest(value, algorithm) {
   return createHash("sha256").update(JSON.stringify(
     algorithm === CANONICAL_DIGEST ? canonicalValue(value) : value,
   )).digest("hex");
 }
+const digest = objectiveValueDigest;
 
 export function freezeObjective(charter) {
   const value = objective(charter);
@@ -98,57 +101,74 @@ export function verifyObjective(charter) {
 
 // The monitor reads independent criterion assessments, not executor test counts.
 // It records insufficient evidence when the independent review was not reached.
-export function assessOutcomeProgress(charter, attempt, previousAttempt = null, { resetUnavailableCount = false } = {}) {
-  const criteria = acceptanceCriterionRows(charter);
+export function assessOutcomeProgress(charter, attempt, previousAttempt = null, options = {}) {
   const assessment = attempt.independent_audit;
-  const results = Array.isArray(assessment?.criterion_results)
-    ? assessment.criterion_results : [];
-  const completeAssessment = Boolean(attempt.audit?.passed === true && assessment &&
-    criteria.every((criterion) => results.filter((row) => row.criterion_id === criterion.id).length === 1) &&
-    results.length === criteria.length &&
-    !(assessment.findings || []).some((finding) => finding.code === "INDEPENDENT_AUDIT_UNAVAILABLE"));
-  const reviewed = new Set();
-  for (const criterion of criteria) {
-    const matches = results.filter((row) => row.criterion_id === criterion.id);
-    const row = matches[0];
-    if (matches.length === 1 && row.passed === true && row.verification_method &&
-        row.observed_result && Array.isArray(row.evidence_refs) && row.evidence_refs.length > 0) {
-      reviewed.add(criterion.id);
-    }
+  const objectiveState = verifyObjective(charter);
+  const contract = charter.thread_state?.objective_contract;
+  const objectiveDigest = contract?.current_digest || null;
+  const boundObjective = assessment?.objective_digest || attempt.outcome_progress?.objective_digest;
+  let assessmentReason = null;
+  if (!objectiveState.valid) assessmentReason = "objective_contract_invalid";
+  else if (boundObjective && boundObjective !== objectiveDigest ||
+      assessment?.objective_version != null && assessment.objective_version !== contract?.version) {
+    assessmentReason = "independent_objective_stale";
+  } else if (assessment?.objective_digest && !assessment.evidence_identity_sha256) {
+    assessmentReason = "independent_candidate_unbound";
+  } else if (assessment?.evidence_identity_sha256 &&
+      assessment.evidence_identity_sha256 !== independentAuditEvidenceIdentity(attempt)) {
+    assessmentReason = "independent_candidate_stale";
+  } else if (!assessment || (assessment.findings || []).some((finding) =>
+    finding.code === "INDEPENDENT_AUDIT_UNAVAILABLE")) {
+    assessmentReason = "independent_assessment_unavailable";
   }
-  if (hasUserOutcomeProof(assessment?.coverage_review)) {
-    reviewed.add("USER-GOAL");
+  const result = evaluateOutcomeProgress({
+    criteria: acceptanceCriterionRows(charter),
+    objectiveDigest,
+    objectiveVersion: contract?.version || null,
+    criterionResults: assessment?.criterion_results,
+    userOutcome: assessment?.coverage_review?.user_outcome,
+    assessmentAvailable: assessmentReason === null,
+    assessmentReason,
+    findings: [...(attempt.audit?.findings || []), ...(assessment?.findings || [])],
+    previous: previousAttempt?.outcome_progress || null,
+    maxNoProgressAttempts: options.maxNoProgressAttempts ?? 3,
+  });
+  // Existing runs keep their original stopping policy until the controller opts
+  // into progress continuation. The richer measurement is persisted in both.
+  if (options.policy !== "progress") {
+    const criteria = acceptanceCriterionRows(charter);
+    const rows = Array.isArray(assessment?.criterion_results) ? assessment.criterion_results : [];
+    const completeAssessment = assessmentReason === null && attempt.audit?.passed === true &&
+      rows.length === criteria.length && criteria.every((criterion) =>
+        rows.filter((row) => row.criterion_id === criterion.id).length === 1);
+    const previous = previousAttempt?.outcome_progress;
+    result.status = completeAssessment ? "assessed" : "insufficient_evidence";
+    result.stalled = Boolean(completeAssessment && previous?.status === "assessed" &&
+      previous.objective_digest === result.objective_digest && result.unproven_ids.length > 0 &&
+      result.assessed_ids.every((id) => previous.assessed_ids.includes(id)) &&
+      result.unproven_ids.every((id) => previous.unproven_ids.includes(id)));
+    result.stall_reason = result.stalled ? "no_new_verified_outcome" : null;
+    result.next_actions = result.next_actions.filter((action) => action !== "reassess_approach");
+    if (result.stalled) result.next_actions.push("reassess_approach");
+    result.next_action = result.stalled ? "reassess_approach" : result.next_actions[0] || "repair_or_verify";
   }
-  const result = {
-    objective_digest: charter.thread_state?.objective_contract?.current_digest || null,
-    status: completeAssessment ? "assessed" : "insufficient_evidence",
-    assessed_ids: [...reviewed].sort(),
-    unproven_ids: ["USER-GOAL", ...criteria.map((row) => row.id)].filter((id) => !reviewed.has(id)),
-    evidence_identity: assessment?.evidence_identity_sha256 || null,
-    stalled: false,
-  };
+  result.evidence_identity = assessment?.evidence_identity_sha256 || null;
+  const completeAssessment = result.status === "assessed";
   const previous = previousAttempt?.outcome_progress;
   const sameObjective = previous?.objective_digest === result.objective_digest;
-  const previousUnavailableCount = !resetUnavailableCount && sameObjective && previous?.status === "insufficient_evidence"
+  const previousUnavailableCount = !options.resetUnavailableCount && sameObjective && previous?.status === "insufficient_evidence"
     ? previous.consecutive_unassessed_attempts || 1 : 0;
   result.consecutive_unassessed_attempts = completeAssessment ? 0 : previousUnavailableCount + 1;
   result.unavailable_reason = completeAssessment ? null : attempt.audit?.passed !== true
     ? "local_verification_incomplete" : "independent_assessment_incomplete";
-  const previousMissingAssessments = !resetUnavailableCount && sameObjective &&
+  const previousMissingAssessments = !options.resetUnavailableCount && sameObjective &&
     previous?.unavailable_reason === "independent_assessment_incomplete"
     ? previous.consecutive_unavailable_assessments || 1 : 0;
   result.consecutive_unavailable_assessments = result.unavailable_reason === "independent_assessment_incomplete"
     ? previousMissingAssessments + 1 : 0;
   // Local repair can improve without reaching independent review. Only a repeatedly
   // missing independent assessment after local readiness opens this recovery gate.
-  result.assessment_unavailable = result.consecutive_unavailable_assessments >= 2;
-  result.stalled = Boolean(
-    completeAssessment && previous?.status === "assessed" &&
-    previous.objective_digest === result.objective_digest &&
-    result.unproven_ids.length > 0 &&
-    result.assessed_ids.every((id) => previous.assessed_ids.includes(id)) &&
-    result.unproven_ids.every((id) => previous.unproven_ids.includes(id))
-  );
+  result.assessment_unavailable = options.policy !== "progress" && result.consecutive_unavailable_assessments >= 2;
   attempt.outcome_progress = result;
   return result;
 }

package/src/orchestrator/outcome-progress.js

@@ -0,0 +1,2 @@
+// The installed provider plugins use the same dependency-free implementation.
+export { evaluateOutcomeProgress } from "../codex-plugins/simy/hooks/outcome-progress.mjs";

package/src/purpose-local-proof.js

@@ -0,0 +1,380 @@
+import { createHash, sign, verify } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, realpath, readdir } from "node:fs/promises";
+import path from "node:path";
+import { homedir } from "node:os";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import crossSpawn from "cross-spawn";
+import { canonicalize } from "./sqm/canonical.js";
+import { loadDeviceSigningIdentity } from "./device-signing-identity.js";
+import { normalizeGitHubRemote } from "./workspace-context.js";
+import { signalExecutorProcess } from "./runner.js";
+
+export const PURPOSE_VERIFICATION_VERSION = "purpose_host_verification.v1";
+const SHA = /^[a-f0-9]{64}$/;
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+const MAX_BYTES = 10 * 1024 * 1024;
+const MAX_REPOSITORY_BYTES = 100 * 1024 * 1024;
+const MAX_FILES = 10000;
+const operations = new WeakMap();
+const workspaceOperations = new Map();
+const execFileAsync = promisify(execFile);
+
+export function purposeSigningKeyPath(root) {
+  return process.env.SIMY_SQM_SIGNING_KEY_PATH || path.join(root || process.env.SIMY_HOME?.trim() || path.join(homedir(), ".simy"), "sqm", "run-signing-key.json");
+}
+
+export async function purposeVerificationCapability(keyPath, { create = false } = {}) {
+  const identity = await loadDeviceSigningIdentity(keyPath, { create });
+  return identity ? { algorithm: "ed25519", key_id: identity.keyId, public_key: identity.publicKeyDer.toString("base64") } : null;
+}
+
+export function purposeDigest(value) {
+  return createHash("sha256").update(canonicalize(value)).digest("hex");
+}
+
+export function normalizePurposeVerification(value) {
+  if (value == null) return null;
+  closed(value, ["schema_version", "run_id", "org_id", "auth_user_id", "node_id", "attempt_number", "client_request_id", "objective_digest", "recipes_digest", "claimed_at", "repository", "recipes", "key_id"]);
+  if (value.schema_version !== PURPOSE_VERIFICATION_VERSION || !text(value.run_id, 256) ||
+      ![value.org_id, value.auth_user_id, value.node_id, value.client_request_id].every(id => UUID.test(id)) ||
+      !integer(value.attempt_number, 1, 50) || !SHA.test(value.objective_digest) || !SHA.test(value.recipes_digest) ||
+      !/^sha256:[a-f0-9]{64}$/.test(value.key_id) || !Number.isFinite(Date.parse(value.claimed_at)) ||
+      !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(value.repository) || !Array.isArray(value.recipes) ||
+      value.recipes.length < 1 || value.recipes.length > 32) throw invalid();
+  const recipes = value.recipes.map(recipe => {
+    const common = ["criterion_id", "statement", "kind"];
+    closed(recipe, recipe.kind === "command" ? [...common, "argv", "cwd", "timeout_ms", "protected_paths"] : [...common, "path", "format", "min_bytes", "protected_paths"]);
+    if (!/^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(recipe.criterion_id) || !text(recipe.statement, 1000)) throw invalid();
+    const protectedPaths = recipe.protected_paths ?? [];
+    if (!Array.isArray(protectedPaths) || protectedPaths.length > 32 || !protectedPaths.every(item => safeRelative(item))) throw invalid();
+    const normalized = { criterion_id: recipe.criterion_id, statement: recipe.statement, kind: recipe.kind, protected_paths: [...protectedPaths] };
+    if (recipe.kind === "command") {
+      if (!Array.isArray(recipe.argv) || recipe.argv.length < 1 || recipe.argv.length > 32 || !recipe.argv.every(arg => text(arg, 1000))) throw invalid();
+      const cwd = recipe.cwd ?? ".", timeout = recipe.timeout_ms ?? 120000;
+      if (!safeRelative(cwd, true) || !integer(timeout, 1000, 300000)) throw invalid();
+      return { ...normalized, argv: [...recipe.argv], cwd, timeout_ms: timeout };
+    }
+    if (recipe.kind !== "file" || !safeRelative(recipe.path) || !["regular_file", "json"].includes(recipe.format ?? "regular_file") || !integer(recipe.min_bytes ?? 1, 0, MAX_BYTES)) throw invalid();
+    return { ...normalized, path: recipe.path, format: recipe.format ?? "regular_file", min_bytes: recipe.min_bytes ?? 1 };
+  });
+  if (new Set(recipes.map(item => item.criterion_id)).size !== recipes.length || purposeDigest(recipes) !== value.recipes_digest || Buffer.byteLength(canonicalize(value)) > 65536) throw invalid();
+  return structuredClone({ ...value, recipes });
+}
+
+export function assertPurposeActor(context, session, apiOrigin, task, clientRequestId) {
+  if (!context) return;
+  if (context.org_id !== session?.organization_id || context.auth_user_id !== session?.account_id ||
+      context.node_id !== session?.device_id || context.client_request_id !== clientRequestId ||
+      (task && (task.repository !== context.repository || task.workspace_mode !== "repository")) ||
+      (task?.purpose_verification_state?.api_origin && task.purpose_verification_state.api_origin !== apiOrigin)) {
+    throw Object.assign(new Error("Purpose verification actor or task binding changed."), { code: "purpose_verification_scope_changed", status: 403 });
+  }
+}
+
+// Runs before the provider; protected inputs are local hashes, never source text.
+export async function preparePurposeVerification(task, { session, apiOrigin, clientRequestId, keyPath, authorize = async () => {} } = {}) {
+  const context = normalizePurposeVerification(task.purpose_verification);
+  if (!context) return;
+  assertPurposeActor(context, session, apiOrigin, task, clientRequestId);
+  await authorize();
+  const identity = await loadDeviceSigningIdentity(keyPath);
+  if (!identity || identity.keyId !== context.key_id) throw Object.assign(new Error("Purpose signer does not match the reserved device key."), { code: "purpose_verification_key_changed", status: 409 });
+  const root = await approvedRoot(task.workspace_path);
+  const baselines = {};
+  for (const recipe of context.recipes) {
+    try { baselines[recipe.criterion_id] = await protectedDigest(root, recipe.protected_paths); }
+    catch { baselines[recipe.criterion_id] = null; }
+  }
+  await authorize();
+  task.purpose_verification = context;
+  task.purpose_verification_state = { api_origin: apiOrigin, workspace_root: root, client_request_id: clientRequestId, protected_baselines: baselines };
+}
+
+export function purposeWorkspaceBusy(workspace) { return workspaceOperations.has(workspace); }
+
+export async function verifyPurposeLocalTask(task, options = {}) {
+  if (operations.has(task)) return operations.get(task);
+  const workspace = task?.purpose_verification_state?.workspace_root;
+  if (workspace && workspaceOperations.has(workspace)) throw Object.assign(new Error("Another verification owns this workspace."), { code: "purpose_verification_workspace_busy", status: 409 });
+  if (workspace) workspaceOperations.set(workspace, task);
+  const operation = executeVerification(task, options).finally(() => {
+    operations.delete(task);
+    if (workspaceOperations.get(workspace) === task) workspaceOperations.delete(workspace);
+  });
+  operations.set(task, operation);
+  return operation;
+}
+
+async function executeVerification(task, { session, apiOrigin, keyPath, authorize = async () => {}, persist = async () => {},
+  repositorySnapshot = inspectPurposeRepository, spawn = crossSpawn, now = Date.now, signal } = {}) {
+  const context = normalizePurposeVerification(task?.purpose_verification);
+  if (!context || !task.purpose_verification_state) throw Object.assign(new Error("This task has no frozen verification plan."), { code: "purpose_verification_unavailable", status: 409 });
+  const check = async () => {
+    await authorize();
+    assertPurposeActor(context, session, apiOrigin, task, task.purpose_verification_state.client_request_id);
+    if (task.status !== "succeeded" || task.stop_requested || task.child || task.operation_promise || signal?.aborted) throw Object.assign(new Error("Purpose verification requires a confirmed completed task."), { code: "purpose_verification_task_not_ready", status: 409 });
+    const root = await approvedRoot(task.workspace_path);
+    if (root !== task.purpose_verification_state.workspace_root) throw Object.assign(new Error("Purpose workspace changed."), { code: "purpose_verification_repository_changed", status: 409 });
+    return root;
+  };
+  const root = await check();
+  const identity = await loadDeviceSigningIdentity(keyPath);
+  if (!identity || identity.keyId !== context.key_id) throw Object.assign(new Error("Purpose signer changed."), { code: "purpose_verification_key_changed", status: 409 });
+  const snapshot = async () => {
+    try {
+      const repository = await repositorySnapshot(root, context.repository);
+      const inputs = [];
+      for (const recipe of context.recipes) {
+        const protectedValue = await protectedDigest(root, recipe.protected_paths).catch(() => null);
+        let artifact = null;
+        if (recipe.kind === "file") artifact = await readSafeFile(root, recipe.path).then(value => hash(value.bytes)).catch(() => null);
+        inputs.push([recipe.criterion_id, protectedValue, artifact]);
+      }
+      return { ...repository, worktree_digest: purposeDigest({ worktree: repository.worktree_digest, verification_inputs: inputs }) };
+    }
+    catch { throw Object.assign(new Error("Purpose repository could not be independently verified."), { code: "purpose_verification_repository_unavailable", status: 409 }); }
+  };
+  const before = await snapshot();
+  await check();
+  let previousReceiptDigest = null;
+  if (task.purpose_verification_state.in_progress) throw Object.assign(new Error("The previous check has an unknown result; do not replay it."), { code: "purpose_verification_recovery_required", status: 409 });
+  if (task.host_verification) {
+    const saved = task.host_verification;
+    const expected = { run_id: context.run_id, org_id: context.org_id, auth_user_id: context.auth_user_id, node_id: context.node_id,
+      attempt_number: context.attempt_number, client_request_id: context.client_request_id, objective_digest: context.objective_digest,
+      recipes_digest: context.recipes_digest, local_task_id: task.id, repository: context.repository, task_terminal_status: "succeeded" };
+    if (saved.schema_version !== PURPOSE_VERIFICATION_VERSION || saved.integrity?.algorithm !== "ed25519" || saved.integrity?.key_id !== identity.keyId ||
+        Object.entries(expected).some(([key, value]) => saved.payload?.[key] !== value) ||
+        !verify(null, Buffer.from(purposeDigest(saved.payload), "hex"), identity.publicKeyDer.length ? { key: identity.publicKeyDer, format: "der", type: "spki" } : null, Buffer.from(saved.integrity.signature || "", "base64"))) {
+      throw Object.assign(new Error("Saved Purpose proof was modified."), { code: "purpose_verification_receipt_invalid", status: 409 });
+    }
+    if (task.host_verification.payload.head_sha !== before.head_sha || task.host_verification.payload.worktree_digest !== before.worktree_digest) throw Object.assign(new Error("Saved proof no longer matches this repository."), { code: "purpose_verification_repository_changed", status: 409 });
+    const finishedAt = Date.parse(saved.payload.finished_at);
+    if (!Number.isFinite(finishedAt) || finishedAt > now() + 60000) throw Object.assign(new Error("Saved Purpose proof time is invalid."), { code: "purpose_verification_receipt_invalid", status: 409 });
+    if (now() - finishedAt < 9 * 60000) return saved; // Fresh POSTs are idempotent; GET never executes checks.
+    // A confirmed old receipt may be explicitly refreshed, unlike an unknown check.
+    previousReceiptDigest = purposeDigest(saved.payload);
+  }
+  // Persist the claim before any command: a crash/unknown effect cannot replay it.
+  if (task.purpose_verification_state.started_at && !task.host_verification) throw Object.assign(new Error("The previous check has an unknown result; do not replay it."), { code: "purpose_verification_recovery_required", status: 409 });
+  if ((task.purpose_verification_state.verification_count || 0) >= 3) throw Object.assign(new Error("This task reached its independent check refresh limit."), { code: "purpose_verification_refresh_limit", status: 409 });
+  if (previousReceiptDigest) { task.purpose_verification_state.receipt_history ||= []; task.purpose_verification_state.receipt_history.push(previousReceiptDigest); }
+  const started = now();
+  if (Date.parse(context.claimed_at) > started + 60000) throw invalid();
+  task.purpose_verification_state.started_at = new Date(started).toISOString();
+  task.purpose_verification_state.in_progress = true;
+  task.purpose_verification_state.verification_count = (task.purpose_verification_state.verification_count || 0) + 1;
+  await persist(task);
+  const deadline = started + 299000;
+  const results = [];
+  for (const recipe of context.recipes) {
+    await check();
+    let result = { criterion_id: recipe.criterion_id, recipe_digest: purposeDigest(recipe), status: "unassessed", reason_code: "verification_unavailable" };
+    if (now() >= deadline) result.reason_code = "verification_deadline";
+    else if (task.purpose_verification_state.protected_baselines?.[recipe.criterion_id] !== await protectedDigest(root, recipe.protected_paths).catch(() => null) || !task.purpose_verification_state.protected_baselines?.[recipe.criterion_id]) result.reason_code = "protected_verification_inputs_changed";
+    else if (recipe.kind === "file") {
+      try {
+        const file = await readSafeFile(root, recipe.path);
+        const validFormat = recipe.format !== "json" || parsesJson(file.bytes);
+        result = { ...result, status: file.bytes.length >= recipe.min_bytes && validFormat ? "passed" : "failed",
+          reason_code: !validFormat ? "file_format_invalid" : file.bytes.length < recipe.min_bytes ? "file_too_small" : "file_verified",
+          artifact_digest: hash(file.bytes), size_bytes: file.bytes.length };
+      } catch { result.reason_code = "file_unavailable_or_unsafe"; }
+    } else if (task.permission_mode !== "workspace_write" || !allowedCommand(recipe.argv)) result.reason_code = "command_not_authorized";
+    else {
+      try {
+        const baseline = task.purpose_verification_state.protected_baselines?.[recipe.criterion_id];
+        if (!baseline || baseline !== await protectedDigest(root, recipe.protected_paths)) result.reason_code = "protected_verification_inputs_changed";
+        else {
+          const cwd = await safePath(root, recipe.cwd, true);
+          const execution = await executeCommand(recipe.argv, cwd, Math.min(recipe.timeout_ms, deadline - now()), { spawn, check, signal });
+          result = { ...result, ...execution };
+        }
+      } catch (error) {
+        if (error?.code?.startsWith("purpose_verification_")) throw error;
+        result.reason_code = "command_unavailable_or_unsafe";
+      }
+    }
+    results.push(result);
+  }
+  const after = await snapshot();
+  await check();
+  if (before.head_sha !== after.head_sha || before.worktree_digest !== after.worktree_digest) {
+    for (const result of results) if (result.status === "passed") { result.status = "unassessed"; result.reason_code = "repository_changed_during_verification"; }
+  }
+  const finished = now();
+  if (finished - started > 300000) throw Object.assign(new Error("Purpose verification exceeded its overall deadline."), { code: "purpose_verification_deadline", status: 409 });
+  const payload = { run_id: context.run_id, org_id: context.org_id, auth_user_id: context.auth_user_id, node_id: context.node_id,
+    attempt_number: context.attempt_number, client_request_id: context.client_request_id, objective_digest: context.objective_digest,
+    recipes_digest: context.recipes_digest, local_task_id: task.id, repository: context.repository,
+    head_sha: after.head_sha, worktree_digest: after.worktree_digest, task_terminal_status: task.status,
+    started_at: new Date(started).toISOString(), finished_at: new Date(finished).toISOString(), results };
+  await check();
+  // Re-read the key so replacement during a long check cannot produce a receipt.
+  const finalIdentity = await loadDeviceSigningIdentity(keyPath);
+  if (finalIdentity?.keyId !== identity.keyId) throw Object.assign(new Error("Purpose signer changed."), { code: "purpose_verification_key_changed", status: 409 });
+  await check();
+  task.host_verification = { schema_version: PURPOSE_VERIFICATION_VERSION, payload,
+    integrity: { algorithm: "ed25519", key_id: identity.keyId, signature: sign(null, Buffer.from(purposeDigest(payload), "hex"), identity.privateKey).toString("base64") } };
+  task.purpose_verification_state.in_progress = false;
+  task.purpose_verification_state.completed_at = payload.finished_at;
+  await persist(task);
+  await check();
+  return task.host_verification;
+}
+
+export async function inspectPurposeRepository(root, repository) {
+  const git = async args => (await execFileAsync("git", ["-c", "core.fsmonitor=false", ...args], { cwd: root,
+    env: commandEnvironment(), timeout: 10000, maxBuffer: 2 * 1024 * 1024, windowsHide: true })).stdout.trimEnd();
+  const top = await realpath(await git(["rev-parse", "--show-toplevel"]));
+  if (top !== root || normalizeGitHubRemote(await git(["remote", "get-url", "origin"])) !== repository) throw new Error("Purpose repository is not the approved checkout.");
+  const head = await git(["rev-parse", "HEAD"]);
+  if (!/^[a-f0-9]{40}$/.test(head)) throw new Error("Purpose checkout has no confirmed HEAD.");
+  const files = [...new Set((await git(["ls-files", "-z", "--cached", "--others", "--exclude-standard"])).split("\0").filter(Boolean))].sort();
+  if (files.length > MAX_FILES) throw new Error("Purpose checkout exceeds verification bounds.");
+  let total = 0;
+  const entries = [];
+  for (const relative of files) {
+    if (!safeRelative(relative)) throw new Error("Unsafe repository path.");
+    try {
+      const value = await readSafeFile(root, relative);
+      total += value.bytes.length;
+      if (total > MAX_REPOSITORY_BYTES) throw new Error("Purpose checkout exceeds verification bounds.");
+      entries.push([relative, hash(value.bytes)]);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      entries.push([relative, null]);
+    }
+  }
+  return { head_sha: head, worktree_digest: purposeDigest(entries) };
+}
+
+async function executeCommand(argv, cwd, timeout, { spawn, check, signal }) {
+  if (timeout <= 0) return { status: "unassessed", reason_code: "verification_deadline" };
+  await check();
+  return new Promise((resolve, reject) => {
+    let child, timer, monitor, killTimer, checking = false, settled = false, reason = null, bytes = 0;
+    const digests = [createHash("sha256"), createHash("sha256")];
+    const stop = code => { reason ||= code; if (child) { signalExecutorProcess(child, "SIGTERM"); killTimer ||= setTimeout(() => signalExecutorProcess(child, "SIGKILL"), 1000); killTimer.unref?.(); } };
+    const abort = () => stop("verification_cancelled");
+    const finish = (exitCode, error) => {
+      if (settled) return;
+      settled = true; clearTimeout(timer); clearTimeout(killTimer); clearInterval(monitor); signal?.removeEventListener("abort", abort);
+      if (error?.code?.startsWith("purpose_verification_")) { reject(error); return; }
+      resolve({ status: reason || error ? "unassessed" : exitCode === 0 ? "passed" : "failed",
+        reason_code: reason || (error ? "command_start_failed" : exitCode === 0 ? "command_exit_zero" : "command_exit_nonzero"),
+        ...(Number.isInteger(exitCode) ? { exit_code: exitCode } : {}), output_digest: purposeDigest(digests.map(digest => digest.digest("hex"))) });
+    };
+    try { child = spawn(argv[0], argv.slice(1), { cwd, env: commandEnvironment(), shell: false, windowsHide: true, detached: process.platform !== "win32", stdio: ["ignore", "pipe", "pipe"] }); }
+    catch (error) { finish(null, error); return; }
+    for (const [index, stream] of [child.stdout, child.stderr].entries()) stream?.on("data", chunk => {
+      bytes += chunk.length;
+      if (bytes > 256 * 1024) { stop("command_output_limit"); return; }
+      digests[index].update(chunk);
+    });
+    child.once("error", error => finish(null, error)); child.once("close", code => finish(code));
+    timer = setTimeout(() => stop("command_timeout"), timeout);
+    monitor = setInterval(async () => {
+      if (checking || settled) return;
+      checking = true;
+      try { await check(); } catch { stop("verification_scope_or_task_changed"); }
+      finally { checking = false; }
+    }, 250);
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) abort();
+  });
+}
+
+function allowedCommand(argv) {
+  if (!argv.every(value => /^[A-Za-z0-9_./:@=,+-]+$/.test(value))) return false;
+  if (["npm", "pnpm", "yarn"].includes(argv[0])) {
+    const script = argv[1] === "run" ? argv[2] : argv[1];
+    return /^(test|build|check|lint)(?:[.:_-][A-Za-z0-9_.:-]+)?$/.test(script || "") &&
+      !argv.some(arg => /^(?:--prefix|--cwd|--dir|--workspace|--global|--script-shell|--userconfig|--globalconfig|--registry|--config|-g)(?:=|$)/.test(arg)) &&
+      (argv[1] === "run" ? argv.length >= 3 : ["test", "build", "check", "lint"].includes(argv[1]));
+  }
+  return argv[0] === "node" && argv[1] === "--test" && argv.slice(2).every(arg => safeRelative(arg) && !arg.startsWith("-"));
+}
+
+function commandEnvironment() {
+  // Do not hand provider credentials, NODE_OPTIONS or Git redirections to checks.
+  const names = new Set(["PATH", "PATHEXT", "SystemRoot", "SYSTEMROOT", "WINDIR", "COMSPEC", "HOME", "USERPROFILE", "TMPDIR", "TMP", "TEMP", "LANG", "LC_ALL"]);
+  return { ...Object.fromEntries(Object.entries(process.env).filter(([name]) => names.has(name))), CI: "true", GIT_TERMINAL_PROMPT: "0" };
+}
+
+async function approvedRoot(value) {
+  const details = await lstat(value);
+  if (!details.isDirectory() || details.isSymbolicLink()) throw new Error("Unsafe Purpose workspace.");
+  return realpath(value);
+}
+
+async function safePath(root, relative, directory = false) {
+  if (!safeRelative(relative, directory)) throw new Error("Unsafe verification path.");
+  let target = root;
+  for (const part of relative.split("/").filter(item => item !== ".")) {
+    target = path.join(target, part);
+    const details = await lstat(target);
+    if (details.isSymbolicLink()) throw new Error("Verification path contains a symlink.");
+  }
+  const resolved = await realpath(target);
+  const rel = path.relative(root, resolved);
+  if (rel.startsWith("..") || path.isAbsolute(rel) || (directory && !(await lstat(target)).isDirectory())) throw new Error("Verification path escaped its workspace.");
+  return target;
+}
+
+async function readSafeFile(root, relative) {
+  const target = await safePath(root, relative);
+  const listed = await lstat(target);
+  if (!listed.isFile() || listed.size > MAX_BYTES || listed.nlink !== 1) throw new Error("Unsafe or oversized verification file.");
+  // O_NONBLOCK also makes a regular-file-to-FIFO race fail without waiting for a writer.
+  const handle = await open(target, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
+  try {
+    const before = await handle.stat();
+    if (!before.isFile() || before.size > MAX_BYTES || before.nlink !== 1) throw new Error("Unsafe or oversized verification file.");
+    const buffer = Buffer.alloc(before.size + 1);
+    let count = 0;
+    while (count < buffer.length) {
+      const { bytesRead } = await handle.read(buffer, count, buffer.length - count, count);
+      if (!bytesRead) break;
+      count += bytesRead;
+    }
+    const bytes = buffer.subarray(0, count);
+    const after = await handle.stat();
+    await safePath(root, relative);
+    const final = await lstat(target);
+    if (after.size !== before.size || bytes.length !== before.size || after.mtimeMs !== before.mtimeMs || final.ino !== before.ino || final.dev !== before.dev) throw new Error("Verification file changed during the read.");
+    return { bytes };
+  } finally { await handle.close(); }
+}
+
+async function protectedDigest(root, paths) {
+  const entries = [];
+  let total = 0, visited = 0;
+  const walk = async relative => {
+    if (++visited > MAX_FILES) throw new Error("Protected verification inputs exceed bounds.");
+    const target = await safePath(root, relative, relative === ".");
+    const details = await lstat(target);
+    if (details.isDirectory()) {
+      for (const name of (await readdir(target)).sort()) await walk(`${relative}/${name}`);
+    } else {
+      const value = await readSafeFile(root, relative); total += value.bytes.length;
+      if (total > MAX_REPOSITORY_BYTES) throw new Error("Protected verification inputs exceed bounds.");
+      entries.push([relative, hash(value.bytes)]);
+    }
+  };
+  for (const relative of paths) await walk(relative);
+  return purposeDigest(entries);
+}
+
+function safeRelative(value, dot = false) {
+  return typeof value === "string" && value.length <= 1024 && !/[\\\x00-\x1f\x7f:]/.test(value) &&
+    !value.startsWith("/") && (dot && value === "." || value.split("/").every(part => part && part !== "." && part !== ".." && part !== ".git"));
+}
+function closed(value, keys) { if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some(key => !keys.includes(key))) throw invalid(); }
+function text(value, max) { return typeof value === "string" && value.length > 0 && value.length <= max && !/[\x00-\x1f\x7f]/.test(value); }
+function integer(value, min, max) { return Number.isSafeInteger(value) && value >= min && value <= max; }
+function invalid() { return Object.assign(new Error("Purpose verification plan is invalid."), { code: "purpose_verification_plan_invalid", status: 400 }); }
+function parsesJson(bytes) { try { JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)); return true; } catch { return false; } }
+function hash(bytes) { return createHash("sha256").update(bytes).digest("hex"); }