@piagent/platform 1.6.1 → 1.7.1

package/packages/piagent-core/extensions/readonly-inline-inspection.ts

@@ -0,0 +1,378 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { externalExecutableIndex } from "./guard-shell-analysis.ts";
+import { shellHasFileWriteRedirection } from "./shell-write-targets.js";
+
+// Inline interpreters are treated as ordinary mutation-capable executables
+// unless this module can prove both read-only authority and bounded termination.
+const READ_ONLY_INLINE_INTERPRETERS = new Set(["node", "nodejs", "python", "python3"]);
+const MAX_INLINE_INSPECTION_FILE_BYTES = 8 * 1024 * 1024;
+
+function simpleQuotedLiteral(value: string): string | undefined {
+  const match = value.trim().match(/^(['"])([^'"\\\r\n]+)\1$/);
+  return match?.[2];
+}
+
+function projectLocalInspectionPath(cwd: string, value: string): string | undefined {
+  const target = path.resolve(cwd, value);
+  const relative = path.relative(cwd, target);
+  if (relative === "" || relative === ".") return target;
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return undefined;
+  return target;
+}
+
+function isBoundedInspectionFile(cwd: string, value: string): boolean {
+  const target = projectLocalInspectionPath(cwd, value);
+  if (!target) return false;
+  try {
+    const relative = path.relative(cwd, target);
+    let current = cwd;
+    for (const segment of relative.split(path.sep).filter(Boolean)) {
+      current = path.join(current, segment);
+      if (fs.lstatSync(current).isSymbolicLink()) return false;
+    }
+    const stats = fs.lstatSync(target);
+    if (!stats.isFile() || stats.size > MAX_INLINE_INSPECTION_FILE_BYTES) return false;
+    const realCwd = fs.realpathSync(cwd);
+    const realTarget = fs.realpathSync(target);
+    const realRelative = path.relative(realCwd, realTarget);
+    return realRelative !== ".." && !realRelative.startsWith(`..${path.sep}`) && !path.isAbsolute(realRelative);
+  } catch {
+    return false;
+  }
+}
+
+function wordsWithoutShellRedirections(words: string[]): string[] | undefined {
+  const result: string[] = [];
+  for (let index = 0; index < words.length; index += 1) {
+    const word = words[index];
+    // Here-documents carry executable source outside the token Pi gives the
+    // policy. They cannot be proved read-only from this word list.
+    if (/^\d*<<</.test(word) || /^\d*<</.test(word)) return undefined;
+    const redirect = word.match(/^(?:\d*(?:<>|>>|>\||>|<)|&>>?)(.*)$/);
+    if (!redirect) {
+      result.push(word);
+      continue;
+    }
+    if (!redirect[1]) {
+      if (!words[index + 1]) return undefined;
+      index += 1;
+    }
+  }
+  return result;
+}
+
+function maskInlineScriptLiteralsAndComments(source: string, language: "javascript" | "python"): string {
+  let result = "";
+  let quote = "";
+  let escaped = false;
+  let lineComment = false;
+  let blockComment = false;
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index];
+    const next = source[index + 1];
+    if (lineComment) {
+      if (char === "\n") { lineComment = false; result += "\n"; }
+      else result += " ";
+      continue;
+    }
+    if (blockComment) {
+      if (char === "*" && next === "/") { result += "  "; index += 1; blockComment = false; }
+      else result += char === "\n" ? "\n" : " ";
+      continue;
+    }
+    if (quote) {
+      result += char === "\n" ? "\n" : " ";
+      if (escaped) escaped = false;
+      else if (char === "\\") escaped = true;
+      else if (char === quote) quote = "";
+      continue;
+    }
+    if (char === "'" || char === '"') {
+      quote = char;
+      result += " ";
+      continue;
+    }
+    if (language === "javascript" && char === "/" && next === "/") {
+      result += "  "; index += 1; lineComment = true; continue;
+    }
+    if (language === "javascript" && char === "/" && next === "*") {
+      result += "  "; index += 1; blockComment = true; continue;
+    }
+    if (language === "python" && char === "#") {
+      result += " "; lineComment = true; continue;
+    }
+    result += char;
+  }
+  return quote || blockComment ? "" : result;
+}
+
+function isReadOnlyNodeInlineScript(source: string, cwd: string): boolean {
+  // Template interpolation and dynamic module loading make the effective code
+  // different from the literal source inspected here. Keep them fail closed.
+  if (!source.trim() || source.includes("`")) return false;
+  let rewritten = source;
+  let invalidRequire = false;
+  rewritten = rewritten.replace(/\brequire\s*\(\s*(['"])([^'"\\\r\n]+)\1\s*\)/g, (_match, _quote, request) => {
+    if (request === "fs" || request === "node:fs") return "PIAGENT_FS_CAPABILITY";
+    if (request === "path" || request === "node:path") return "PIAGENT_PATH_CAPABILITY";
+    if (/^(?:\.\.?\/|\/)[^\0]*\.json$/i.test(request) && isBoundedInspectionFile(cwd, request)) return "PIAGENT_JSON_VALUE";
+    invalidRequire = true;
+    return "PIAGENT_INVALID_REQUIRE";
+  });
+  const rawFsAliases = new Set<string>(["PIAGENT_FS_CAPABILITY"]);
+  for (const match of rewritten.matchAll(/\bconst\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*PIAGENT_FS_CAPABILITY\b/g)) {
+    rawFsAliases.add(match[1]);
+  }
+  if (!nodeReadCallsAreBounded(rewritten, rawFsAliases, cwd)) return false;
+  let code = maskInlineScriptLiteralsAndComments(rewritten, "javascript");
+  if (!code || invalidRequire || /\brequire\b/.test(code) || /\\(?:u\{?[0-9a-f]|x[0-9a-f])/i.test(code)) return false;
+
+  const fsAliases = new Set<string>(["PIAGENT_FS_CAPABILITY"]);
+  code = code.replace(/\bconst\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*PIAGENT_FS_CAPABILITY\b/g, (_match, alias) => {
+    fsAliases.add(alias);
+    return "const PIAGENT_FS_ALIAS_DECLARATION = 0";
+  });
+  const syncReads = "accessSync|existsSync|lstatSync|readFileSync|readlinkSync|realpathSync|statSync";
+  const asyncReads = "access|lstat|readFile|readlink|realpath|stat";
+  for (const alias of fsAliases) {
+    const escapedAlias = alias.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    code = code
+      .replace(new RegExp(`\\b${escapedAlias}\\s*\\.\\s*promises\\s*\\.\\s*(?:${asyncReads})\\s*\\(`, "g"), "PIAGENT_READ_OPERATION(")
+      .replace(new RegExp(`\\b${escapedAlias}\\s*\\.\\s*(?:${syncReads})\\s*\\(`, "g"), "PIAGENT_READ_OPERATION(")
+      .replace(new RegExp(`\\b${escapedAlias}\\s*\\.\\s*constants\\s*\\.\\s*(?:F_OK|R_OK)\\b`, "g"), "PIAGENT_READ_CONSTANT");
+    if (new RegExp(`\\b${escapedAlias}\\b`).test(code)) return false;
+  }
+
+  code = code
+    .replace(/\bprocess\s*\.\s*(?:cwd|memoryUsage|resourceUsage|uptime)\s*\(\s*\)/g, "PIAGENT_PROCESS_READ")
+    .replace(/\bprocess\s*\.\s*(?:arch|argv|platform|version|versions)\b/g, "PIAGENT_PROCESS_READ")
+    .replace(/\bprocess\s*\.\s*(?:stdout|stderr)\s*\.\s*write\b/g, "PIAGENT_OUTPUT_OPERATION");
+  if (/\bprocess\b/.test(code)) return false;
+
+  if (
+    /=>|[*]{2}|<<|>>|\b(?:Array|Atomics|Buffer|Promise|SharedArrayBuffer|Worker|class|do|for|function|get|new|queueMicrotask|set|setImmediate|setInterval|setTimeout|while)\b/.test(code)
+    || /\.\s*(?:apply|bind|call|copyWithin|fill|padEnd|padStart|repeat)\b/.test(code)
+    || /\/(?![/*])/.test(code)
+    || /\b[A-Za-z_$][A-Za-z0-9_$]*\s*\([^)]*\)\s*\{/.test(code)
+  ) return false;
+
+  // With module access reduced to JSON, path helpers, and the fs read methods
+  // above, these remaining escape hatches are the ways arbitrary inline code
+  // could regain mutation or external-process authority.
+  return !/\b(?:Bun|Deno|EventSource|Function|Proxy|Reflect|WebAssembly|WebSocket|XMLHttpRequest|child_process|cluster|constructor|eval|exports|fetch|global|globalThis|import|module|process|getBuiltinModule|prototype|this|__proto__|vm|worker_threads)\b/.test(code);
+}
+
+function splitTopLevelArguments(value: string): string[] | undefined {
+  const parts: string[] = [];
+  let current = "", quote = "", escaped = false, depth = 0;
+  for (const char of value) {
+    if (quote) {
+      current += char;
+      if (escaped) escaped = false;
+      else if (char === "\\") escaped = true;
+      else if (char === quote) quote = "";
+      continue;
+    }
+    if (char === "'" || char === '"') { quote = char; current += char; continue; }
+    if ("([{".includes(char)) { depth += 1; current += char; continue; }
+    if (")]}".includes(char)) { depth -= 1; if (depth < 0) return undefined; current += char; continue; }
+    if (char === "," && depth === 0) { parts.push(current.trim()); current = ""; continue; }
+    current += char;
+  }
+  if (quote || depth !== 0) return undefined;
+  parts.push(current.trim());
+  return parts;
+}
+
+function callArgumentsAt(source: string, start: number): string[] | undefined {
+  let quote = "", escaped = false, depth = 1;
+  for (let index = start; index < source.length; index += 1) {
+    const char = source[index];
+    if (quote) {
+      if (escaped) escaped = false;
+      else if (char === "\\") escaped = true;
+      else if (char === quote) quote = "";
+      continue;
+    }
+    if (char === "'" || char === '"') { quote = char; continue; }
+    if (char === "(") depth += 1;
+    else if (char === ")" && --depth === 0) return splitTopLevelArguments(source.slice(start, index));
+  }
+  return undefined;
+}
+
+function nodeReadCallsAreBounded(source: string, aliases: Set<string>, cwd: string): boolean {
+  const aliasPattern = [...aliases]
+    .map((alias) => alias.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join("|");
+  if (!aliasPattern) return true;
+  const calls = new RegExp(`\\b(?:${aliasPattern})\\s*\\.\\s*(?:(promises)\\s*\\.\\s*)?(access|accessSync|existsSync|lstat|lstatSync|readFile|readFileSync|readlink|readlinkSync|realpath|realpathSync|stat|statSync)\\s*\\(`, "g");
+  for (const match of source.matchAll(calls)) {
+    const args = callArgumentsAt(source, (match.index ?? 0) + match[0].length);
+    const target = args?.[0] ? simpleQuotedLiteral(args[0]) : undefined;
+    if (!target || !projectLocalInspectionPath(cwd, target)) return false;
+    if (/^readFile/.test(match[2]) && !isBoundedInspectionFile(cwd, target)) return false;
+  }
+  return true;
+}
+
+function pythonOpenCallsAreReadOnly(source: string, cwd: string): boolean {
+  const matches = [...source.matchAll(/\bopen\s*\(/g)];
+  for (const match of matches) {
+    const start = (match.index ?? 0) + match[0].length;
+    const args = callArgumentsAt(source, start);
+    if (!args || !args[0]) return false;
+    const target = simpleQuotedLiteral(args[0]);
+    if (!target || !isBoundedInspectionFile(cwd, target)) return false;
+    const positionalMode = args[1] && !args[1].includes("=") ? args[1] : undefined;
+    const keywordMode = args.slice(1).find((arg) => /^mode\s*=/.test(arg))?.replace(/^mode\s*=\s*/, "");
+    for (const mode of [positionalMode, keywordMode].filter((entry): entry is string => Boolean(entry))) {
+      if (!/^(['"])(?:r|rt|tr|rb|br)\1$/.test(mode.trim())) return false;
+    }
+    for (const arg of args.slice(positionalMode ? 2 : 1)) {
+      const key = arg.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=/)?.[1];
+      if (key && !["buffering", "encoding", "errors", "mode", "newline"].includes(key)) return false;
+    }
+  }
+  return true;
+}
+
+function pythonPathCallsAreBounded(source: string, cwd: string): boolean {
+  for (const match of source.matchAll(/\bPath\s*\(/g)) {
+    const args = callArgumentsAt(source, (match.index ?? 0) + match[0].length);
+    const target = args?.length === 1 ? simpleQuotedLiteral(args[0]) : undefined;
+    if (!target || !projectLocalInspectionPath(cwd, target)) return false;
+  }
+  const allReads = [...source.matchAll(/\.\s*(?:read_bytes|read_text)\s*\(/g)].length;
+  const boundedReads = [...source.matchAll(/\bPath\s*\(\s*(['"])([^'"\\\r\n]+)\1\s*\)\s*\.\s*(?:read_bytes|read_text)\s*\(/g)]
+    .filter((match) => isBoundedInspectionFile(cwd, match[2])).length;
+  return allReads === boundedReads;
+}
+
+function isReadOnlyPythonInlineScript(source: string, cwd: string): boolean {
+  if (
+    !source.trim()
+    || source.includes("\n")
+    || !pythonOpenCallsAreReadOnly(source, cwd)
+    || !pythonPathCallsAreBounded(source, cwd)
+  ) return false;
+  let code = maskInlineScriptLiteralsAndComments(source, "python");
+  if (!code) return false;
+  code = code
+    .replace(/(?:^|;)\s*import\s+json\s*(?=;|$)/g, ";")
+    .replace(/(?:^|;)\s*from\s+pathlib\s+import\s+Path\s*(?=;|$)/g, ";");
+  // No reflection/dynamic import, process or network modules, or filesystem
+  // write primitives. File handles are accepted only when every open() mode is
+  // read-only, as checked above.
+  return !/(?:=>|[*]|<<|>>|__|\b(?:async|await|breakpoint|bytearray|class|compile|ctypes|def|delattr|eval|exec|for|getattr|globals|help|import|importlib|input|iter|lambda|locals|next|openers?|os|pow|range|requests|resource|setattr|shutil|sleep|socket|subprocess|sys|threading|time|urllib|while|yield)\b|\.\s*(?:center|chmod|glob|hardlink_to|iterdir|lchmod|link|ljust|mkdir|open|remove|rename|replace|rglob|rjust|rmdir|symlink_to|touch|truncate|unlink|walk|write|write_bytes|write_text|writelines|zfill)\b)/.test(code);
+}
+
+function isProvablyReadOnlyInlineInterpreter(words: string[], cwd: string): boolean {
+  const commandWords = wordsWithoutShellRedirections(words);
+  if (!commandWords || commandWords.length < 3) return false;
+  const executable = path.basename(commandWords[0] ?? "").toLowerCase();
+  if (!READ_ONLY_INLINE_INTERPRETERS.has(executable)) return false;
+  const args = commandWords.slice(1);
+  if (executable === "node" || executable === "nodejs") {
+    let index = 0;
+    while (index < args.length && (
+      ["--no-deprecation", "--no-warnings", "--trace-warnings"].includes(args[index])
+      || /^--disable-warning=[A-Za-z0-9_-]+$/.test(args[index])
+      || /^--input-type=(?:commonjs|module)$/.test(args[index])
+    )) index += 1;
+    const flag = args[index];
+    let source: string | undefined;
+    if (["-e", "--eval", "-p", "--print"].includes(flag)) source = args[index + 1];
+    else source = flag?.match(/^--(?:eval|print)=(.*)$/s)?.[1];
+    const consumed = ["-e", "--eval", "-p", "--print"].includes(flag) ? 2 : 1;
+    return Boolean(source && index + consumed === args.length && isReadOnlyNodeInlineScript(source, cwd));
+  }
+  return args.length === 2 && args[0] === "-c" && isReadOnlyPythonInlineScript(args[1], cwd);
+}
+
+
+type ReadOnlyShellSegmentInspection = {
+  commandWords: string[];
+  boundedInlineInterpreter: boolean;
+};
+
+function inspectReadOnlyShellSegment(
+  words: string[],
+  cwd: string
+): ReadOnlyShellSegmentInspection | undefined {
+  const commandWords = wordsWithoutShellRedirections(words);
+  if (!commandWords || commandWords.length === 0) return undefined;
+  return {
+    commandWords,
+    boundedInlineInterpreter: isProvablyReadOnlyInlineInterpreter(words, cwd)
+  };
+}
+
+export function isReadOnlyTaskShellCommand(
+  command: string,
+  segments: Array<{ words: string[] }>,
+  cwd: string
+): boolean {
+  if (/`|\$\(/.test(command) || shellHasFileWriteRedirection(command)) return false;
+  const safeCommands = new Set(["pwd", "ls", "find", "rg", "grep", "cat", "sed", "head", "tail", "wc", "stat", "file", "test", "[", "which", "printf", "sort"]);
+  const safeGitSubcommands = new Set(["status", "diff", "log", "show", "ls-files", "rev-parse"]);
+  return segments.length > 0 && segments.every((segment) => {
+    const inspection = inspectReadOnlyShellSegment(segment.words.filter(Boolean), cwd);
+    if (!inspection) return false;
+    if (inspection.boundedInlineInterpreter) return true;
+    const words = inspection.commandWords;
+    const executable = path.basename(words[0] ?? "");
+    if (executable === "sed" && words.some((word) => /^-.*i/.test(word))) return false;
+    if (executable === "find" && words.some((word) => ["-delete", "-exec", "-execdir", "-ok", "-okdir", "-fprint", "-fprint0", "-fprintf", "-fls"].includes(word))) return false;
+    if (executable === "sort" && words.slice(1).some((word) => (
+      word === "--output"
+      || word.startsWith("--output=")
+      || /^-[^-]*o/.test(word)
+    ))) return false;
+    if (safeCommands.has(executable)) return true;
+    if (executable === "git") return safeGitSubcommands.has(words[1] ?? "");
+    if (executable === "command") return words[1] === "-v";
+    return false;
+  });
+}
+
+const PROJECT_MUTATING_EXECUTABLES = new Set([
+  "apply_patch", "bash", "bun", "chmod", "chown", "cp", "dd", "deno", "install", "ln", "make", "mkdir", "mv", "prename", "rename",
+  "node", "nodejs", "patch", "perl", "php", "python", "python3", "rm", "rmdir", "rsync", "ruby", "scp", "sh",
+  "tee", "touch", "truncate", "zsh"
+]);
+
+export function isProjectMutatingShellCommand(
+  command: string,
+  segments: Array<{ words: string[] }>,
+  cwd: string
+): boolean {
+  if (shellHasFileWriteRedirection(command)) return true;
+  const noAliases = new Map<string, string>();
+  for (const segment of segments) {
+    const words = segment.words.filter(Boolean);
+    if (words.length === 0) continue;
+    const mutatingExecutable = externalExecutableIndex(words, PROJECT_MUTATING_EXECUTABLES, noAliases);
+    if (mutatingExecutable !== undefined) {
+      const inspection = inspectReadOnlyShellSegment(words, cwd);
+      if (mutatingExecutable !== 0 || !inspection?.boundedInlineInterpreter) return true;
+    }
+    const executable = path.basename(words[0] ?? "").toLowerCase();
+    if (executable === "find" && words.some((word) => ["-delete", "-exec", "-execdir", "-ok", "-okdir", "-fprint", "-fprint0", "-fprintf", "-fls"].includes(word))) return true;
+    if (executable === "sed" && words.some((word) => /^-[^-]*i/.test(word) || word === "--in-place" || word.startsWith("--in-place="))) return true;
+    if (executable === "git") {
+      const subcommand = words.slice(1).find((word, index, values) => {
+        if (!word.startsWith("-")) return index === 0 || !["-C", "-c", "--git-dir", "--work-tree"].includes(values[index - 1]);
+        return false;
+      });
+      if (["apply", "checkout", "clean", "mv", "reset", "restore", "rm", "switch"].includes(subcommand ?? "")) return true;
+    }
+    if (["npm", "pnpm", "yarn", "bun"].includes(executable)) {
+      const subcommand = words.find((word, index) => index > 0 && !word.startsWith("-"));
+      if (["add", "ci", "install", "link", "remove", "uninstall", "update", "upgrade"].includes(subcommand ?? "")) return true;
+    }
+  }
+  return false;
+}

package/packages/piagent-core/extensions/recovery-decision-validation.ts

@@ -0,0 +1,92 @@
+import { FAILURE_CATEGORIES } from "./failure-types.ts";
+import { TRAJECTORY_PHASES } from "./trajectory-contract.ts";
+
+export const RECOVERY_POLICY_VERSION = "recovery-v1" as const;
+export const RECOVERY_ACTIONS = Object.freeze(["repair", "retry", "fresh-session", "ask-operator", "handoff", "blocked"] as const);
+export const RECOVERY_CEILINGS = Object.freeze({
+  sourceRepairPasses: 1, transientVerifierRetries: 1, unknownDiagnosticPasses: 1, providerRetries: 1
+} as const);
+export const RECOVERY_REASON_CODES = Object.freeze([
+  "feature-disabled", "invalid-input", "terminal-phase", "handoff-already-observed", "no-failure",
+  "stale-verifier-evidence", "source-repair-eligible", "dependency-mutation-not-authorized", "read-only-task",
+  "repair-ceiling-reached", "repeated-hypothesis", "operator-environment-action", "provider-transient-retry",
+  "provider-retry-exhausted", "permission-expansion-forbidden", "protected-path-forbidden", "scope-replan-required",
+  "transient-verifier-retry", "transient-retry-unavailable", "unknown-diagnostic-pass", "unknown-diagnostic-exhausted",
+  "deterministic-adapter-proof-required", "independent-acceptance-proof-required", "source-acceptance-proof-required",
+  "independent-execution-cancelled", "independent-execution-reconciliation-required", "independent-verifier-unsupported", "independent-verification-halted",
+  "global-continuation-budget-exhausted", "repeated-progress-signature", "continuation-journal-unavailable", "manual-lifecycle-handoff"
+] as const);
+export type RecoveryReasonCode = typeof RECOVERY_REASON_CODES[number];
+
+const HASH = /^[a-f0-9]{64}$/;
+const REF = /^[a-z0-9][a-z0-9:._-]{0,255}$/i;
+const FIELDS = new Set(["policyVersion", "taskId", "taskRunId", "taskAttempt", "evidenceDigest", "failureCategory", "currentPhase", "action", "continuation", "nextPhase", "sourceMutationAllowed", "reasonCodes", "counts", "ceilings", "hypothesisRef"]);
+const COUNTERS = new Set(["sourceRepairPasses", "transientVerifierRetries", "unknownDiagnosticPasses", "providerRetries"]);
+const TERMINAL_OVERRIDES = new Set(["global-continuation-budget-exhausted", "repeated-progress-signature", "continuation-journal-unavailable", "manual-lifecycle-handoff"]);
+const ACTIONS_BY_REASON: Record<string, readonly string[]> = {
+  "feature-disabled": ["handoff"], "invalid-input": ["blocked"], "terminal-phase": ["blocked"],
+  "handoff-already-observed": ["handoff"], "no-failure": ["handoff"], "stale-verifier-evidence": ["retry"],
+  "source-repair-eligible": ["repair"], "dependency-mutation-not-authorized": ["ask-operator"], "read-only-task": ["handoff"],
+  "repair-ceiling-reached": ["handoff"], "repeated-hypothesis": ["handoff"], "operator-environment-action": ["ask-operator"],
+  "provider-transient-retry": ["retry"], "provider-retry-exhausted": ["fresh-session", "handoff"],
+  "permission-expansion-forbidden": ["ask-operator"], "protected-path-forbidden": ["handoff"],
+  "scope-replan-required": ["ask-operator", "handoff"], "transient-verifier-retry": ["retry"],
+  "transient-retry-unavailable": ["handoff"], "unknown-diagnostic-pass": ["retry"], "unknown-diagnostic-exhausted": ["handoff"],
+  "deterministic-adapter-proof-required": ["handoff"], "independent-acceptance-proof-required": ["handoff"],
+  "source-acceptance-proof-required": ["handoff"],
+  "independent-execution-cancelled": ["handoff"], "independent-execution-reconciliation-required": ["ask-operator"], "independent-verifier-unsupported": ["handoff"], "independent-verification-halted": ["handoff"],
+  "global-continuation-budget-exhausted": ["handoff"], "repeated-progress-signature": ["handoff"],
+  "continuation-journal-unavailable": ["handoff"], "manual-lifecycle-handoff": ["handoff"]
+};
+const CATEGORIES_BY_REASON: Record<string, readonly string[]> = {
+  "no-failure": ["passed"], "source-repair-eligible": ["compile-typecheck", "test-assertion", "lint-format", "dependency-config"],
+  "dependency-mutation-not-authorized": ["dependency-config"], "repair-ceiling-reached": ["compile-typecheck", "test-assertion", "lint-format", "dependency-config"],
+  "repeated-hypothesis": ["compile-typecheck", "test-assertion", "lint-format", "dependency-config"],
+  "operator-environment-action": ["environment"], "provider-transient-retry": ["provider-network"], "provider-retry-exhausted": ["provider-network"],
+  "permission-expansion-forbidden": ["permission-policy"], "protected-path-forbidden": ["scope-protected-path"],
+  "scope-replan-required": ["scope-protected-path"], "transient-verifier-retry": ["flaky-infrastructure"],
+  "unknown-diagnostic-pass": ["unknown"], "unknown-diagnostic-exhausted": ["unknown"], "independent-acceptance-proof-required": ["unknown"],
+  "source-acceptance-proof-required": ["unknown"],
+  "independent-execution-cancelled": ["unknown"], "independent-execution-reconciliation-required": ["environment"], "independent-verifier-unsupported": ["unknown"], "independent-verification-halted": ["unknown"]
+};
+
+function record(value: unknown): Record<string, any> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, any> : undefined;
+}
+
+function exactFields(value: Record<string, any>, fields: Set<string>): boolean {
+  return Object.keys(value).every((field) => fields.has(field)) && [...fields].every((field) => field in value);
+}
+
+export function recoveryDecisionValidationErrors(input: unknown): string[] {
+  const value = record(input);
+  if (!value) return ["recovery decision must be an object"];
+  const errors: string[] = [];
+  if (!exactFields(value, FIELDS)) errors.push("recovery decision fields are invalid");
+  if (value.policyVersion !== RECOVERY_POLICY_VERSION || typeof value.taskId !== "string" || !REF.test(value.taskId)
+    || typeof value.taskRunId !== "string" || !REF.test(value.taskRunId) || !Number.isInteger(value.taskAttempt) || value.taskAttempt < 1
+    || typeof value.evidenceDigest !== "string" || !HASH.test(value.evidenceDigest) || !FAILURE_CATEGORIES.includes(value.failureCategory)
+    || !TRAJECTORY_PHASES.includes(value.currentPhase) || !RECOVERY_ACTIONS.includes(value.action)) errors.push("recovery decision identity is invalid");
+  if (!['none', 'same-session', 'fresh-session', 'operator'].includes(String(value.continuation))
+    || (value.nextPhase !== null && !TRAJECTORY_PHASES.includes(value.nextPhase)) || typeof value.sourceMutationAllowed !== "boolean") errors.push("recovery continuation is invalid");
+  const reasons = Array.isArray(value.reasonCodes) ? value.reasonCodes : [];
+  if (reasons.length < 1 || reasons.length > 20 || new Set(reasons).size !== reasons.length
+    || reasons.some((reason) => typeof reason !== "string" || !RECOVERY_REASON_CODES.includes(reason as RecoveryReasonCode))) errors.push("recovery reasonCodes are invalid");
+  const counts = record(value.counts), ceilings = record(value.ceilings);
+  if (!counts || !exactFields(counts, COUNTERS) || [...COUNTERS].some((field) => !Number.isInteger(counts[field]) || counts[field] < 0 || counts[field] > RECOVERY_CEILINGS[field])) errors.push("recovery counts are invalid");
+  if (!ceilings || !exactFields(ceilings, COUNTERS) || [...COUNTERS].some((field) => ceilings[field] !== RECOVERY_CEILINGS[field])) errors.push("recovery ceilings are invalid");
+  if (value.hypothesisRef !== null && (typeof value.hypothesisRef !== "string" || !REF.test(value.hypothesisRef))) errors.push("recovery hypothesisRef is invalid");
+  const continuationCoherent = value.action === "repair" ? value.continuation === "same-session" && value.nextPhase === "repair" && value.sourceMutationAllowed === true
+    : value.action === "retry" ? value.continuation === "same-session" && value.nextPhase !== null && value.sourceMutationAllowed === false
+      : value.action === "fresh-session" ? value.continuation === "fresh-session" && value.nextPhase === null && value.sourceMutationAllowed === false
+        : value.action === "ask-operator" ? value.continuation === "operator" && value.nextPhase === null && value.sourceMutationAllowed === false
+          : value.continuation === "none" && value.nextPhase === null && value.sourceMutationAllowed === false;
+  if (!continuationCoherent) errors.push("recovery action and continuation conflict");
+  const terminalOverride = reasons.some((reason) => TERMINAL_OVERRIDES.has(reason));
+  if (reasons.some((reason) => !ACTIONS_BY_REASON[reason]?.includes(value.action) && !(terminalOverride && value.action === "handoff"))) errors.push("recovery reason and action conflict");
+  if (reasons.some((reason) => CATEGORIES_BY_REASON[reason] && !CATEGORIES_BY_REASON[reason].includes(value.failureCategory))) errors.push("recovery reason and category conflict");
+  if ((reasons.includes("terminal-phase") && value.currentPhase !== "terminal") || (reasons.includes("handoff-already-observed") && value.currentPhase !== "handoff")) errors.push("recovery reason and phase conflict");
+  if ((reasons.includes("repair-ceiling-reached") && counts?.sourceRepairPasses !== RECOVERY_CEILINGS.sourceRepairPasses)
+    || (reasons.includes("unknown-diagnostic-exhausted") && counts?.unknownDiagnosticPasses !== RECOVERY_CEILINGS.unknownDiagnosticPasses)) errors.push("recovery reason and counts conflict");
+  return errors;
+}

package/packages/piagent-core/extensions/shell-write-targets.js

@@ -11,6 +11,16 @@ const SOURCE_DESTINATION_COMMANDS = new Set(["cp", "install", "ln", "mv"]);
 const SHELL_INTERPRETERS = new Set(["bash", "sh", "zsh"]);
 const FIND_FILE_OUTPUT_ACTIONS = new Set(["-fprint", "-fprint0", "-fprintf", "-fls"]);
 
+// A redirect to the operating system's null device discards bytes; it does not
+// mutate the workspace. Keep this deliberately exact. Treating aliases,
+// variables, or lookalike paths as the null device would let an expansion such
+// as `${SINK:-/dev/null}` hide a real file target from the guard.
+function isNullDeviceRedirectionTarget(value) {
+  const candidate = String(value ?? "");
+  if (process.platform !== "win32") return candidate === "/dev/null";
+  return candidate.replace(/\\/g, "/").toLowerCase() === "//./nul";
+}
+
 function commandName(value) {
   return String(value ?? "").split("/").at(-1)?.toLowerCase() ?? "";
 }
@@ -32,24 +42,12 @@ function executableWords(words) {
   return words.slice(index);
 }
 
-function redirectionTargets(words) {
-  const targets = [];
-  for (let index = 0; index < words.length; index += 1) {
-    const token = words[index];
-    const match = token.match(/^\d*(>>?|>\|)(.*)$/);
-    if (!match || /^\d+$/.test(match[2])) continue;
-    const target = match[2] || words[index + 1];
-    if (target && !/^&?\d+$/.test(target)) targets.push(target);
-  }
-  return targets;
-}
-
 export function shellHasFileWriteRedirection(command) {
   return splitShellSegments(String(command ?? "")).some((segment) => (
     extractAttachedRedirectionPaths(segment)
       .filter((redirect) => redirect.writesFile)
       .flatMap(redirectionTargetWords)
-      .length > 0
+      .some((target) => !isNullDeviceRedirectionTarget(target.value))
   ));
 }
 
@@ -60,6 +58,7 @@ export function extractShellWritePathCandidates(command) {
   const assignments = new Map();
   const pending = splitShellSegments(String(command ?? "")).map((segment) => ({ segment, depth: 0 }));
   const add = (value) => {
+    if (isNullDeviceRedirectionTarget(value)) return;
     const normalized = normalizePathCandidate(expandAssignments(value, assignments));
     if (normalized) candidates.push(normalized);
   };
@@ -75,7 +74,9 @@ export function extractShellWritePathCandidates(command) {
       const assignment = word.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
       if (assignment) assignments.set(assignment[1], expandAssignments(assignment[2], assignments));
     }
-    for (const target of redirectionTargets(words)) add(target);
+    for (const target of extractAttachedRedirectionPaths(segment)
+      .filter((redirect) => redirect.writesFile)
+      .flatMap(redirectionTargetWords)) add(target.value);
     const executable = executableWords(words);
     const name = commandName(executable[0]);
     const operands = executable.slice(1).filter((word) => word && !word.startsWith("-") && !/^[<>]/.test(word));

package/packages/piagent-core/extensions/task-contract-view.js

@@ -4,17 +4,17 @@ import { runtimeLifecycleMode } from "./task-lifecycle.js";
 import { latestObservedVerificationEvidence, meaningfulVerificationCommands, verificationEvidenceProvesStableTree } from "./verification-intelligence.js";
 import { isCurrentWorkingTreeDigest, WORKING_TREE_DIGEST_ALGORITHM } from "./working-tree-digest.js";
 
-export function passingVerifyCommandsForDigest(task, digest) {
+export function passingVerifyCommandsForDigest(task, digest, workspaceRevisionDigest) {
   if (task?.workingTreeDigestAlgorithm !== WORKING_TREE_DIGEST_ALGORITHM || !isCurrentWorkingTreeDigest(digest)) return new Set();
   return new Set([...latestObservedVerificationEvidence(task?.verifyEvidence).values()]
-    .filter((evidence) => verificationEvidenceProvesStableTree(evidence, digest))
+    .filter((evidence) => verificationEvidenceProvesStableTree(evidence, digest, workspaceRevisionDigest))
     .map((evidence) => String(evidence.command ?? "").trim()));
 }
 
-export function allVerifyCommandsPassCurrentTree(task, digest) {
+export function allVerifyCommandsPassCurrentTree(task, digest, workspaceRevisionDigest) {
   const planned = meaningfulVerificationCommands(task?.verifyCommands ?? []);
   if (planned.length === 0) return false;
-  const passing = passingVerifyCommandsForDigest(task, digest);
+  const passing = passingVerifyCommandsForDigest(task, digest, workspaceRevisionDigest);
   return planned.every((command) => passing.has(command.trim()));
 }
 

package/packages/piagent-core/extensions/task-digest-migration.js

@@ -123,11 +123,11 @@ export function planUnversionedTaskDigestMigration(raw, options) {
   return { task, disposition: "refresh" };
 }
 
-export function completeTaskDigestRefresh(task, currentWorkingTreeDigest) {
+export function completeTaskDigestRefresh(task, currentWorkingTreeDigest, workspaceRevisionDigest) {
   if (task?.workingTreeDigestAlgorithm !== WORKING_TREE_DIGEST_ALGORITHM || !isCurrentWorkingTreeDigest(currentWorkingTreeDigest) || task?.workingTreeDigestMigration?.status !== "verification-refresh-required") return task;
   const commands = [...new Set((task.verifyCommands ?? []).map((value) => String(value).trim()).filter(Boolean))];
   const currentPassing = new Set([...latestObservedVerificationEvidence(task.verifyEvidence).values()]
-    .filter((entry) => verificationEvidenceProvesStableTree(entry, currentWorkingTreeDigest))
+    .filter((entry) => verificationEvidenceProvesStableTree(entry, currentWorkingTreeDigest, workspaceRevisionDigest))
     .map((entry) => String(entry.command).trim()));
   if (commands.length === 0 || commands.some((command) => !currentPassing.has(command))) return task;
   return {