snipara-companion 4.0.0 → 4.0.1

package/CHANGELOG.md

@@ -2,7 +2,13 @@
 
 Release notes for `snipara-companion`, newest first.
 
-## 4.0.0 — prepared candidate (unpublished)
+## 4.0.1
+
+- Delegate scoped local validation runs to Orchestrator for shared execution exclusion and freshly verified Sandbox receipt reuse. Preserve original run identity and report reuse separately.
+- Keep legacy unscoped execution available; require compatible Orchestrator for coordinated runs and never silently fall back after uncertain execution.
+- Match Sandbox's capability-bound scope v3 while preserving empty-capability v2 identities.
+
+## 4.0.0
 
 - Breaking CLI JSON contract: `workflow resume --json` returns a versioned compact overview by default. Existing full-payload consumers must add `--detail`; HTTP What Changed stays full by default. This migration requires a major Companion release.
 

package/dist/index.js

@@ -348,7 +348,7 @@ function expectedSandboxScope(requestFile, scope) {
   const raw = JSON.parse(text3);
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("Invalid request");
   const r = raw;
-  const known = /* @__PURE__ */ new Set(["schema_version", "workspace", "argv", "image", "profile", "cwd", "timeout_seconds", "cpus", "memory_mb", "pids", "disk_mb", "artifacts"]);
+  const known = /* @__PURE__ */ new Set(["schema_version", "workspace", "argv", "image", "profile", "cwd", "timeout_seconds", "cpus", "memory_mb", "pids", "disk_mb", "artifacts", "requirements"]);
   if (Object.keys(r).some((key) => !known.has(key))) throw new Error("Unknown request fields");
   const schema = r.schema_version === void 0 ? "snipara.sandbox.validation.v1" : r.schema_version;
   if (schema !== "snipara.sandbox.validation.v1" || typeof r.workspace !== "string" || !(0, import_node_path.isAbsolute)(r.workspace) || r.workspace.split("/").includes("..") || typeof r.image !== "string" || !r.image || r.image.startsWith("-") || /\s/.test(r.image)) throw new Error("Unsupported request identity");
@@ -368,6 +368,24 @@ function expectedSandboxScope(requestFile, scope) {
   const cpus = r.cpus === void 0 ? 2 : r.cpus;
   if (typeof cpus !== "number" || !Number.isFinite(cpus) || cpus < 0.01 || cpus > 8) throw new Error("Invalid CPU limit");
   const parts = ["snipara.validation.scope.v2", scope, schema, workspace, profile, r.image, import_node_path.posix.normalize(cwd).replace(/\/+$/, "") || ".", String(integer2("timeout_seconds", 120, 1, 900)), String(Math.trunc(cpus * 1e9)), String(integer2("memory_mb", 2048, 64, 8192)), String(integer2("pids", 128, 16, 512)), String(integer2("disk_mb", 2048, 16, 4096))];
+  const rawRequirements = r.requirements === void 0 ? {} : r.requirements;
+  if (!rawRequirements || typeof rawRequirements !== "object" || Array.isArray(rawRequirements)) throw new Error("Invalid requirements");
+  const requirements = rawRequirements;
+  const patterns = {
+    python_modules: /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/,
+    node_modules: /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/,
+    commands: /^[A-Za-z0-9][A-Za-z0-9._+-]*$/
+  };
+  if (Object.keys(requirements).some((name) => !Object.hasOwn(patterns, name))) throw new Error("Unknown requirements fields");
+  const names = ["python_modules", "node_modules", "commands"].map((name) => {
+    const values = requirements[name] === void 0 ? [] : requirements[name];
+    if (!Array.isArray(values) || values.length > 32 || values.some((value) => typeof value !== "string" || value.length > 128 || patterns[name].exec(value)?.[0] !== value)) throw new Error("Invalid requirement names");
+    return [...new Set(values)];
+  });
+  if (names.some((values) => values.length > 0)) {
+    parts[0] = "snipara.validation.scope.v3";
+    parts.push(...names.map((values) => JSON.stringify(values)));
+  }
   if (parts.some((value) => Buffer.from(value, "utf8").toString("utf8") !== value)) throw new Error("Invalid Unicode identity");
   return (0, import_node_crypto.createHash)("sha256").update(JSON.stringify(parts), "utf8").digest("hex");
 }
@@ -413,6 +431,9 @@ async function invokeSandboxValidation(action2, options) {
   if (options.probeTimeoutSeconds !== void 0 && (!diagnostic2 || !Number.isInteger(options.probeTimeoutSeconds) || options.probeTimeoutSeconds < 1 || options.probeTimeoutSeconds > MAX_PROBE_TIMEOUT_SECONDS)) {
     return { exitCode: 2, result: { ...sandboxUnavailable, stage: "adapter_input", reason_code: "invalid_probe_timeout", reason: "probeTimeoutSeconds is an integer from 1 to 60, supported only for diagnose and gate." } };
   }
+  if ((options.noReuse || options.orchestratorCommand !== void 0) && (action2 !== "run" || !options.scope?.trim()) || action2 === "run" && options.scope !== void 0 && !options.scope.trim()) {
+    return { exitCode: 2, result: { ...sandboxUnavailable, stage: "adapter_input", reason_code: "explicit_scope_required", reason: "Coordinated run controls require validation run with an explicit workflow or lot scope." } };
+  }
   if (process.platform === "win32") return { exitCode: 2, result: { ...sandboxUnavailable, reason: "Repository validation currently qualifies macOS/Linux Docker only." } };
   const requiresRequest = ["gate", "choose", "diagnose", "run", "verify"].includes(action2);
   const requiresRun = ["verify", "status", "cancel"].includes(action2);
@@ -420,37 +441,69 @@ async function invokeSandboxValidation(action2, options) {
     return { exitCode: 2, result: { ...sandboxUnavailable, reason: "Explicit request, workflow scope and valid run identity are required for the selected action." } };
   }
   if (action2 === "choose" && (!options.acknowledgeUserChoice || !["alternative", "install", "local", "skip"].includes(options.choice || "") || options.choice === "alternative" && !options.environment)) return { exitCode: 2, result: { ...sandboxUnavailable, reason: "An explicit acknowledged user choice is required." } };
+  const delegated = action2 === "run" && !!options.scope;
   const args = ["validation", action2];
-  for (const [flag, value] of Object.entries({ request: options.request, scope: options.scope, "run-id": options.runId, store: options.store, choice: options.choice, environment: options.environment })) {
+  const parameters = delegated ? { request: options.request, scope: options.scope, store: options.store, "sandbox-command": options.sandboxCommand } : { request: options.request, scope: action2 === "run" ? void 0 : options.scope, "run-id": options.runId, store: options.store, choice: options.choice, environment: options.environment };
+  for (const [flag, value] of Object.entries(parameters)) {
     if (value !== void 0) args.push(`--${flag}`, value);
   }
-  if (options.acknowledgeUserChoice) args.push("--acknowledge-user-choice");
+  if (delegated && options.noReuse) args.push("--no-reuse");
+  if (!delegated && options.acknowledgeUserChoice) args.push("--acknowledge-user-choice");
   if (options.probeTimeoutSeconds !== void 0) args.push("--probe-timeout-seconds", String(options.probeTimeoutSeconds));
   const env2 = {};
   for (const name of ["PATH", "HOME", "TMPDIR", "LANG", "LC_ALL", "DOCKER_HOST", "DOCKER_CONTEXT", "DOCKER_CONFIG"]) {
     if (process.env[name]) env2[name] = process.env[name];
   }
+  const command2 = delegated ? options.orchestratorCommand || "snipara-orchestrator" : options.sandboxCommand || "snipara-sandbox";
+  if (delegated) {
+    try {
+      const capability = await executeBounded(command2, ["validation", "run", "--help"], env2, 1e4);
+      if (capability.status !== 0 || !/(?:^|\s)--no-reuse(?:\s|,|$)/m.test(capability.stdout)) throw new Error("The Orchestrator validation run command does not expose --no-reuse.");
+    } catch (error) {
+      return { exitCode: 2, result: { status: "orchestrator_update_required", stage: "adapter_capability", reason_code: "orchestrator_update_required", reason: `Scoped validation requires Orchestrator 1.14 or newer with validation reuse support. ${redactDiagnostic(error.message)}`, execution_authorized_by_gate: false } };
+    }
+  }
   let child;
   const timeoutMs = diagnostic2 ? ((options.probeTimeoutSeconds ?? DEFAULT_PROBE_TIMEOUT_SECONDS) + DIAGNOSTIC_CONTROL_GRACE_SECONDS + ADAPTER_STARTUP_ALLOWANCE_SECONDS) * 1e3 : action2 === "run" ? 96e4 : 3e4;
   try {
-    child = await executeBounded(options.sandboxCommand || "snipara-sandbox", args, env2, timeoutMs);
+    child = await executeBounded(command2, args, env2, timeoutMs);
   } catch (error) {
     const failure = error;
+    if (delegated) return { exitCode: 2, result: { status: "validation_reuse_needs_review", work_reuse: { state: "needs_review" }, stage: "adapter_process", reason_code: failure.code === "ETIMEDOUT" ? "orchestrator_process_timeout" : failure.code === "EOUTPUT" ? "orchestrator_output_limit" : "orchestrator_process_failed", reason: redactDiagnostic(failure.message || "Orchestrator process failed."), adapter_timeout_seconds: timeoutMs / 1e3, execution_authorized_by_gate: false } };
     return { exitCode: 2, result: { ...sandboxUnavailable, stage: "adapter_process", reason_code: failure.code === "ETIMEDOUT" ? "sandbox_process_timeout" : failure.code === "EOUTPUT" ? "sandbox_output_limit" : "sandbox_process_failed", reason: redactDiagnostic(failure.message || "Sandbox process failed to start."), adapter_timeout_seconds: timeoutMs / 1e3 } };
   }
   try {
     const value = JSON.parse(child.stdout);
     if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid Sandbox response");
     const result = value;
+    const workReuse = result.work_reuse && typeof result.work_reuse === "object" && !Array.isArray(result.work_reuse) ? result.work_reuse : void 0;
+    if (delegated && workReuse?.state === "needs_review" && (result.status === "needs_user_choice" || result.status === "user_choice_recorded")) {
+      if (result.run_id !== void 0 || result.execution_authorized_by_gate !== false || result.sandbox_used !== void 0 && result.sandbox_used !== false || Array.from(options.scope).length > 256) throw new Error("Invalid nonexecution gate response");
+      const scope = result.scope_sha256 === void 0 ? void 0 : expectedSandboxScope(options.request, options.scope);
+      if (result.scope_sha256 !== scope) throw new Error("Invalid gate scope binding");
+      if (result.status === "needs_user_choice") {
+        const allowed = ["alternative", "install", "continue_without_sandbox"];
+        if (typeof result.prompt !== "string" || !result.prompt.trim() || result.prompt.length > 2e3 || !Array.isArray(result.choices) || result.choices.length < 1 || result.choices.length > allowed.length || new Set(result.choices).size !== result.choices.length || !result.choices.every((value2) => typeof value2 === "string" && allowed.includes(value2))) throw new Error("Invalid unavailable gate choices");
+        return { exitCode: 2, result: sanitizeDiagnostics({ ...result, prompt: redactDiagnostic(result.prompt) }) };
+      }
+      const choice2 = result.choice;
+      if (!scope || result.sandbox_used !== false || result.proof_requirement_waived !== false || !validChoice(choice2, scope) || choice2?.choice === "install") throw new Error("Invalid recorded gate choice");
+      return { exitCode: 2, result: sanitizeDiagnostics(result) };
+    }
+    if (delegated && result.run_id === void 0 && (result.status === "validation_in_progress" && workReuse?.state === "in_progress" || result.status === "validation_reuse_needs_review" && workReuse?.state === "needs_review")) {
+      return { exitCode: 2, result: sanitizeDiagnostics(result) };
+    }
+    if (delegated && (!workReuse || typeof workReuse.state !== "string" || !["executed", "reused", "needs_review"].includes(workReuse.state))) throw new Error("Invalid validation reuse metadata");
     const schema = result.schema_version === "snipara.sandbox.validation.v1";
     const identity = ["gate", "choose"].includes(action2) && typeof result.scope_sha256 === "string" && result.scope_sha256 === expectedSandboxScope(options.request, options.scope);
     const ready = result.readiness;
     const choice = result.choice;
     const valid = action2 === "gate" ? identity && result.sandbox_used === false && result.execution_authorized_by_gate === false && (result.status === "sandbox_ready" && ready?.schema_version === "snipara.sandbox.validation.v1" && ready.ready === true && ready.backend === "docker" && typeof ready.image_id === "string" && !!ready.image_id || result.status === "needs_user_choice" && result.execution_authorized_by_gate === false && Array.isArray(result.choices) && result.choices.length > 0 || result.status === "user_choice_recorded" && result.proof_requirement_waived === false && validChoice(choice, result.scope_sha256) && choice?.choice !== "install") : action2 === "choose" ? identity && validChoice(result, result.scope_sha256) && result.choice === options.choice && result.environment === (options.environment || "") : action2 === "diagnose" ? typeof result.ready === "boolean" && schema && result.backend === "docker" : action2 === "cancel" ? result.cancel_requested === true && result.run_id === options.runId : action2 === "verify" ? schema && typeof result.valid === "boolean" && result.run_id === options.runId && Array.isArray(result.reasons) && (result.valid === false || result.reasons.length === 0 && validVerifiedReceipt(result.receipt, options.runId)) : schema && typeof result.run_id === "string" && /^[a-f0-9]{32}$/.test(result.run_id) && (!options.runId || result.run_id === options.runId) && typeof result.status === "string" && ["preparing", "running", "passed", "failed", "timeout", "cancelled", "environment_incompatible", "artifact_error", "collection_error", "cleanup_failed", "error", "interrupted"].includes(String(result.status)) && typeof result.cleanup_complete === "boolean";
     if (!valid) throw new Error("Unsupported Sandbox response schema");
-    const failed = result.status === "needs_user_choice" || action2 === "verify" && result.valid !== true || action2 === "diagnose" && result.ready !== true || action2 === "run" && (result.status !== "passed" || result.cleanup_complete !== true);
+    const failed = result.status === "needs_user_choice" || action2 === "verify" && result.valid !== true || action2 === "diagnose" && result.ready !== true || action2 === "run" && (result.status !== "passed" || result.cleanup_complete !== true) || delegated && workReuse?.state === "needs_review";
     return { exitCode: failed ? 2 : child.status ?? 2, result: sanitizeDiagnostics(result) };
   } catch {
+    if (delegated) return { exitCode: 2, result: { status: "validation_reuse_needs_review", work_reuse: { state: "needs_review" }, stage: "adapter_response", reason_code: "orchestrator_response_invalid", reason: child.stderr ? redactDiagnostic(child.stderr) : "Orchestrator returned an unsupported or malformed response after execution was attempted; inspect its evidence before retrying.", execution_authorized_by_gate: false } };
     return { exitCode: 2, result: { ...sandboxUnavailable, stage: "adapter_response", reason_code: "sandbox_response_invalid", reason: child.stderr ? redactDiagnostic(child.stderr) : "Sandbox returned an unsupported or malformed response; update/configure it or select an alternative." } };
   }
 }
@@ -51417,6 +51470,9 @@ validation.command("preview").description("Read a bounded local request preview;
 });
 for (const action2 of ["gate", "choose", "diagnose", "run", "verify", "status", "cancel"]) {
   const validationCommand = validation.command(action2).option("--request <file>", "Standalone Sandbox validation request JSON").option("--scope <id>", "Authorized workflow or lot identity").option("--run-id <id>", "Sandbox run identity").option("--store <path>", "Durable Sandbox evidence directory").option("--choice <choice>", "Explicit user choice: alternative, install, local or skip").option("--environment <name>", "Name the chosen alternative environment").option("--acknowledge-user-choice", "Record an actual explicit user choice; never inferred").option("--sandbox-command <path>", "Explicit Sandbox executable; no shell interpolation");
+  if (action2 === "run") {
+    validationCommand.option("--no-reuse", "Request a fresh scoped run while retaining the shared validation lock").option("--orchestrator-command <path>", "Compatible Orchestrator executable for scoped validation");
+  }
   if (["gate", "diagnose"].includes(action2)) {
     validationCommand.option(
       "--probe-timeout-seconds <seconds>",
@@ -51425,7 +51481,7 @@ for (const action2 of ["gate", "choose", "diagnose", "run", "verify", "status",
     );
   }
   validationCommand.action(async (options) => {
-    const outcome = await invokeSandboxValidation(action2, options);
+    const outcome = await invokeSandboxValidation(action2, action2 === "run" ? { ...options, noReuse: options.reuse === false } : options);
     console.log(JSON.stringify(outcome.result));
     process.exitCode = outcome.exitCode;
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snipara-companion",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "description": "Local-first CLI that asks your repo what breaks before an AI coding agent edits it.",
   "main": "dist/index.js",
   "bin": {