pi-claude-supervisor 0.5.2 → 0.5.4

package/src/policy.ts

@@ -1,3 +1,6 @@
+import { lstatSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+
 export type PolicyDecision = "allow" | "review" | "deny";
 
 export interface PolicyResult {
@@ -5,18 +8,97 @@ export interface PolicyResult {
   reason: string;
 }
 
-export function evaluatePermission(toolName: string, input: unknown): PolicyResult {
-  if (toolName === "AskUserQuestion") return { decision: "review", reason: "Claude requested an interactive product decision" };
-  if (toolName !== "Bash") return { decision: "review", reason: `unknown Claude tool requires review: ${toolName}` };
+/**
+ * Permission decisions are autonomous for local development. A denial is a
+ * hard capability boundary, not a request for a human to approve the next
+ * turn. AskUserQuestion is denied so the Worker can restate the question as
+ * ordinary text and the Decision Worker can answer it from task evidence.
+ */
+const allowedWorkerTools = new Set(["Bash", "Edit", "Glob", "Grep", "Read", "Write", "NotebookEdit"]);
+
+export function evaluatePermission(toolName: string, input: unknown, cwd = process.cwd()): PolicyResult {
+  if (toolName === "AskUserQuestion") return { decision: "deny", reason: "interactive questions are converted to ordinary Worker text" };
+  if (!allowedWorkerTools.has(toolName)) return { decision: "deny", reason: `Worker tool is outside the automatic allowlist: ${toolName}` };
+  if (toolName === "Edit" || toolName === "Write" || toolName === "NotebookEdit") {
+    const paths = fileToolPaths(input);
+    if (paths.length === 0) return { decision: "deny", reason: `${toolName} request has no recognizable file path` };
+    if (paths.some((path) => isGitMetadataPath(path, cwd))) return { decision: "deny", reason: "Worker cannot write Git metadata or protected branch refs" };
+    return { decision: "allow", reason: `local Claude file tool is allowed by the task policy: ${toolName}` };
+  }
+  if (toolName !== "Bash") return { decision: "allow", reason: `local Claude tool is allowed by the task policy: ${toolName}` };
   const command = input && typeof input === "object" && typeof (input as { command?: unknown }).command === "string"
     ? (input as { command: string }).command
     : "";
-  if (!command) return { decision: "review", reason: "Bash request has no recognizable command" };
+  if (!command) return { decision: "deny", reason: "Bash request has no recognizable command" };
+  if (containsNestedClaude(command)) {
+    return { decision: "deny", reason: "Worker cannot start a nested Claude or background Reviewer" };
+  }
   return evaluateCommand("bash", ["-lc", command]);
 }
 
+function fileToolPaths(input: unknown): string[] {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return [];
+  const value = input as Record<string, unknown>;
+  return ["file_path", "filePath", "path", "notebook_path", "notebookPath"]
+    .map((key) => value[key])
+    .filter((path): path is string => typeof path === "string" && path.trim().length > 0);
+}
+
+function isGitMetadataPath(value: string, cwd: string): boolean {
+  if (value.replaceAll("\\", "/").split("/").some((segment) => segment.toLowerCase() === ".git")) return true;
+  let root: string;
+  try { root = realpathSync(cwd); }
+  catch { return true; }
+  const raw = value.replaceAll("\\", "/");
+  const canonicalRoot = root.replaceAll("\\", "/").replace(/\/+$/u, "") || "/";
+  let components: string[];
+  if (isAbsolute(value)) {
+    const prefix = canonicalRoot === "/" ? "/" : `${canonicalRoot}/`;
+    if (raw !== canonicalRoot && !raw.startsWith(prefix)) return true;
+    components = raw === canonicalRoot ? [] : raw.slice(prefix.length).split("/");
+  } else {
+    components = raw.split("/");
+  }
+  const normalized: string[] = [];
+  for (const segment of components) {
+    if (!segment || segment === ".") continue;
+    if (segment === "..") {
+      if (normalized.length === 0) return true;
+      normalized.pop();
+      continue;
+    }
+    if (segment.toLowerCase() === ".git") return true;
+    const candidate = join(root, ...normalized, segment);
+    try {
+      const info = lstatSync(candidate);
+      if (info.isSymbolicLink()) return true;
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== "ENOENT" && code !== "ENOTDIR") return true;
+    }
+    normalized.push(segment);
+  }
+  const absolute = join(root, ...normalized);
+  try {
+    const info = statSync(absolute);
+    // A regular file with multiple links may be an alias for a Git ref or
+    // other metadata file even when its pathname contains no `.git` segment.
+    if (info.isFile() && info.nlink > 1) return true;
+    const resolved = realpathSync(absolute);
+    if (resolved.replaceAll("\\", "/").split("/").some((segment) => segment.toLowerCase() === ".git")) return true;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code !== "ENOENT" && code !== "ENOTDIR") return true;
+  }
+  return false;
+}
+
 const deniedPatterns = [
-  /--dangerously-skip-permissions\b/iu,
+  /\b(?:npm|pnpm|yarn)\b[\s\S]*\bpublish\b/iu,
+  /\b(?:ssh|scp|sftp|rsync)\b/iu,
+  /\b(?:curl|wget)\b[\s\S]*(?:-X\s*(?:POST|PUT|PATCH|DELETE)|--method(?:=|\s+)(?:POST|PUT|PATCH|DELETE)|https?:\/\/(?:api\.)?(?:github|gitlab|bitbucket|registry\.npmjs)\.)/iu,
+  /(?:\$\{?[^\s`}]+\}?|`[^`]*`|\$\([^)]*\))[\s\S]*\b(?:push|merge|publish)\b|\b(?:push|merge|publish)\b[\s\S]*(?:\$\{?[^\s`}]+\}?|`[^`]*`|\$\([^)]*\))/iu,
+  /--(?:allow-)?dangerously-skip-permissions\b/iu,
   /--permission-mode\s+(?:bypasspermissions|dontask)\b/iu,
   /\brm\s+-rf\s+\//iu,
   /\bmkfs(?:\.|\s)/iu,
@@ -25,37 +107,227 @@ const deniedPatterns = [
   /\b(shutdown|reboot|poweroff)\b/iu,
 ];
 
-const reviewPatterns = [
-  /\bgit\s+push\b/iu,
-  /\bgit\s+reset\s+--hard\b/iu,
-  /\bgit\s+(merge|rebase)\b/iu,
-  /\b(npm|pnpm|yarn)\s+publish\b/iu,
-  /\b(curl|wget)\b.*\|\s*(?:\/[\w./-]+\/)?(?:sh|bash|zsh)\b/iu,
-  /\b(chmod|chown)\b/iu,
-];
+interface ShellToken {
+  value: string;
+  operator: boolean;
+  dynamic: boolean;
+}
+
+const protectedBranches = new Set(["main", "master", "trunk", "integration", "develop"]);
+const protectedBranchOperations = new Set(["checkout", "switch", "branch", "reset", "restore", "worktree", "update-ref", "symbolic-ref"]);
+const remoteOperations = new Set(["push", "merge", "send-pack", "receive-pack", "update-ref"]);
 
 export function evaluateCommand(command: string, args: readonly string[] = []): PolicyResult {
-  const normalized = [command, ...args].join(" ").trim();
+  const normalized = command.trim();
+  if (!normalized) return { decision: "deny", reason: "empty command" };
+  const lexical = lexShell(normalized);
+  if (lexical.error) return { decision: "deny", reason: `command could not be safely parsed: ${lexical.error}` };
+  const literalArgs = args.map((value) => ({ value, operator: false, dynamic: false }));
+  return evaluateTokens([...lexical.tokens, ...literalArgs], 0);
+}
+
+function evaluateRepositoryBoundary(tokens: readonly ShellToken[], canonical: string, depth: number): PolicyResult | undefined {
+  const values = tokens.filter((token) => !token.operator).map((token) => token.value);
+  const lower = values.map((value) => value.toLowerCase());
+  const hasGit = values.some((value) => /(?:^|[\\/])git$/iu.test(value) || /^(?:git-(?:send|receive|upload)-pack)$/iu.test(value));
+  const hasGitTransport = lower.some((value) => /^(?:git-(?:send|receive|upload)-pack)$/u.test(value));
+  const hasRemoteOperation = lower.some((value) => remoteOperations.has(value));
+  const hasGhRemote = lower.some((value) => value === "gh" || value === "glab" || value === "hub")
+    && lower.some((value) => value === "api" || value === "release" || value === "pull-request" || value === "pr" || value === "mr");
+  const hasPackagePublication = lower.some((value) => value === "npm" || value === "pnpm" || value === "yarn") && lower.includes("publish");
+  const hasGitAliasConfiguration = hasGit && lower.some((value) => /^alias\.[^=]*(?:=|$)/u.test(value));
+  if (depth < 4) {
+    for (const nested of nestedShellCommands(lower, values)) {
+      const nestedResult = evaluateCommandInternal(nested, depth + 1);
+      if (nestedResult.decision === "deny") return nestedResult;
+    }
+  }
+  const hasDynamicArgument = tokens.some((token) => !token.operator && token.dynamic);
+  const hasProtectedBranch = lower.some((value) => protectedBranches.has(value))
+    || /(?:^|\s)(?:[^\s]*\.git[\\/]refs[\\/]heads[\\/]|[^\s]*refs[\\/]heads[\\/])(?:main|master|trunk|integration|develop)(?:$|\s)/iu.test(canonical);
+  const gitOperation = lower.find((value) => protectedBranchOperations.has(value));
+
+  if (hasDynamicArgument) {
+    return { decision: "deny", reason: "dynamic shell arguments cannot be capability-checked safely" };
+  }
+  if (/\bgit\b[\s\S]*\b(?:push|merge|send-pack|receive-pack|update-ref)\b/iu.test(canonical)
+    || /\bgit-(?:send|receive|upload)-pack\b/iu.test(canonical)
+    || /\b(?:gh|glab|hub)\b[\s\S]*\b(?:api|pr|mr|pull-request|release)\b/iu.test(canonical)) {
+    return { decision: "deny", reason: "Worker has no remote repository or main/integration merge authority" };
+  }
+  if (hasGit && (hasRemoteOperation || hasGitTransport) || hasGhRemote) {
+    return { decision: "deny", reason: "Worker has no remote repository or main/integration merge authority" };
+  }
+  if (hasGitAliasConfiguration) {
+    return { decision: "deny", reason: "Worker cannot redefine Git command aliases" };
+  }
+  if (hasGit && gitOperation && hasProtectedBranch) {
+    return { decision: "deny", reason: "Worker cannot switch to or mutate a protected integration branch" };
+  }
+  const directRefWrite = tokens.some((token) => token.operator && (token.value === ">" || token.value === ">>"))
+    || ["cp", "echo", "install", "mv", "printf", "sed", "tee"].includes(lower[0] ?? "");
+  if (/\.git[\\/](?:HEAD|packed-refs|refs[\\/]heads[\\/])/iu.test(canonical)
+    || (directRefWrite && hasProtectedBranch && /refs[\\/]heads[\\/]/iu.test(canonical))) {
+    return { decision: "deny", reason: "Worker cannot write protected Git branch refs directly" };
+  }
+  if (hasPackagePublication) {
+    return { decision: "deny", reason: "package publication belongs to the protected release workflow" };
+  }
+  const unsafePermissionMode = (value: string): boolean => value.replace(/[-_]/gu, "") === "bypasspermissions" || value.replace(/[-_]/gu, "") === "dontask";
+  if (lower.some((value) => value.startsWith("--permission-mode=") && unsafePermissionMode(value.slice("--permission-mode=".length)))
+    || (lower.includes("--permission-mode") && lower.some((value) => unsafePermissionMode(value)))) {
+    return { decision: "deny", reason: "Worker cannot bypass Claude permission prompts" };
+  }
+  return undefined;
+}
+
+function containsNestedClaude(command: string, depth = 0): boolean {
+  // Bash can hand an opaque quoted program to Python, Node, eval, env,
+  // command, or another interpreter. Once this permission boundary sees a
+  // Claude executable reference, fail closed rather than trying to prove which
+  // wrapper will eventually exec it. This intentionally rejects harmless prose
+  // mentions too; false positives cannot grant a nested Worker capability.
+  if (/\b(?:claude(?:\.exe)?|review(?:er)?|code[-_ ]?review|read[-_ ]?only[-_ ]?review|independent[-_ ]?review|codex|cursor(?:-agent)?|aider|opencode|gemini)\b/iu.test(command)) return true;
+  if (depth > 4) return false;
+  const lexical = lexShell(command);
+  if (lexical.error) return true;
+  for (const token of lexical.tokens) {
+    if (token.operator) continue;
+    const executable = token.value.split(/[\\/]/u).at(-1)?.toLowerCase();
+    if (executable === "claude" || executable === "claude.exe") return true;
+    // Quote concatenation such as c'l'a'u'd'e is normalized by the shell
+    // lexer into one token. Recurse into quoted interpreter payloads too.
+    if (/\s/u.test(token.value) && containsNestedClaude(token.value, depth + 1)) return true;
+  }
+  return false;
+}
+
+function nestedShellCommands(lower: readonly string[], values: readonly string[]): string[] {
+  const nested: string[] = [];
+  const shellNames = new Set(["sh", "bash", "dash", "zsh", "fish", "ksh"]);
+  for (let index = 0; index < lower.length; index += 1) {
+    const executable = lower[index]!.split(/[\\/]/u).at(-1);
+    if (executable && shellNames.has(executable)) {
+      for (let option = index + 1; option < lower.length; option += 1) {
+        if (["-c", "--command"].includes(lower[option]!)) {
+          const command = values.slice(option + 1).join(" ").trim();
+          if (command) nested.push(command);
+          break;
+        }
+      }
+    }
+    if (lower[index] === "eval") {
+      const command = values.slice(index + 1).join(" ").trim();
+      if (command) nested.push(command);
+    }
+  }
+  return nested;
+}
+
+function evaluateCommandInternal(command: string, depth: number): PolicyResult {
+  const normalized = command.trim();
   if (!normalized) return { decision: "deny", reason: "empty command" };
-  if (deniedPatterns.some((pattern) => pattern.test(normalized))) {
+  const lexical = lexShell(normalized);
+  if (lexical.error) return { decision: "deny", reason: `command could not be safely parsed: ${lexical.error}` };
+  return evaluateTokens(lexical.tokens, depth);
+}
+
+function evaluateTokens(tokens: readonly ShellToken[], depth: number): PolicyResult {
+  const canonical = tokens.map((token) => token.value).join(" ").trim();
+  if (!canonical) return { decision: "deny", reason: "empty command" };
+  const boundary = evaluateRepositoryBoundary(tokens, canonical, depth);
+  if (boundary) return boundary;
+  if (deniedPatterns.some((pattern) => pattern.test(canonical))) {
+    if (/\b(?:curl|wget)\b[\s\S]*(?:github|gitlab|bitbucket|registry\.npmjs)\b/iu.test(canonical)) {
+      return { decision: "deny", reason: "Worker has no remote repository or main/integration merge authority" };
+    }
+    if (/\bgit\b[\s\S]*\b(?:checkout|switch|branch|reset|restore|worktree|update-ref|symbolic-ref)\b[\s\S]*\b(?:main|master|trunk|integration|develop)\b/iu.test(canonical)) {
+      return { decision: "deny", reason: "Worker cannot switch to or mutate a protected integration branch" };
+    }
+    if (/\b(?:npm|pnpm|yarn)\b[\s\S]*\bpublish\b/iu.test(canonical)) {
+      return { decision: "deny", reason: "package publication belongs to the protected release workflow" };
+    }
     return { decision: "deny", reason: "command matches a prohibited destructive pattern" };
   }
-  if (reviewPatterns.some((pattern) => pattern.test(normalized))) {
-    return { decision: "review", reason: "command requires explicit human approval" };
+  return { decision: "allow", reason: "command is allowed for unattended local development" };
+}
+
+function lexShell(input: string): { tokens: ShellToken[]; error?: string } {
+  const tokens: ShellToken[] = [];
+  let value = "";
+  let dynamic = false;
+  let started = false;
+  let quote: "single" | "double" | undefined;
+  const flush = (): void => {
+    if (!started) return;
+    tokens.push({ value, operator: false, dynamic });
+    value = "";
+    dynamic = false;
+    started = false;
+  };
+  const pushOperator = (operator: string): void => {
+    flush();
+    tokens.push({ value: operator, operator: true, dynamic: false });
+  };
+  for (let index = 0; index < input.length; index += 1) {
+    const character = input[index]!;
+    const next = input[index + 1];
+    if (quote === "single") {
+      if (character === "'") quote = undefined;
+      else value += character;
+      started = true;
+      continue;
+    }
+    if (quote === "double") {
+      if (character === '"') quote = undefined;
+      else if (character === "\\" && next === "\n") index += 1;
+      else if (character === "\\" && next !== undefined && /[\\"$`]/u.test(next)) { value += next; index += 1; }
+      else { value += character; if (character === "$" || character === "`") dynamic = true; }
+      started = true;
+      continue;
+    }
+    if (character === "'") { quote = "single"; started = true; continue; }
+    if (character === '"') { quote = "double"; started = true; continue; }
+    if (character === "\\") {
+      if (next === "\n") index += 1;
+      else if (next !== undefined) { value += next; index += 1; }
+      started = true;
+      continue;
+    }
+    if (/\s/u.test(character)) { flush(); continue; }
+    if (character === "$" || character === "`") { dynamic = true; value += character; started = true; continue; }
+    // Brace, tilde and pathname expansion can change command names, targets or
+    // Git refs after this lexical pass. Treat all unquoted expansion markers as
+    // dynamic rather than attempting to model Bash's expansion order.
+    if ("*?[]{}~".includes(character)) { dynamic = true; value += character; started = true; continue; }
+    if (";&|<>".includes(character)) {
+      const operator = next && ((character === "&" && next === "&") || (character === "|" && next === "|") || (character === ">" && next === ">") || (character === "<" && next === "<"))
+        ? `${character}${next}`
+        : character;
+      pushOperator(operator);
+      if (operator.length === 2) index += 1;
+      continue;
+    }
+    value += character;
+    started = true;
   }
-  return { decision: "allow", reason: "command is outside the default high-risk set" };
+  if (quote) return { tokens, error: "unterminated quote" };
+  flush();
+  return { tokens };
 }
 
+/**
+ * Keep the approval argument for persisted v0.5.x records and embedding API
+ * compatibility. It is intentionally not required for local review patterns;
+ * only hard-denied capability boundaries fail this assertion.
+ */
 export function assertSafeWorkerCommand(
   command: string,
   args: readonly string[] = [],
-  approval?: { actor: "human"; reason: string },
+  _approval?: { actor: "human"; reason: string },
 ): void {
   const result = evaluateCommand(command, args);
   if (result.decision === "deny") {
     throw new Error(`Worker command blocked by policy (deny): ${result.reason}`);
   }
-  if (result.decision === "review" && (!approval || approval.actor !== "human" || !approval.reason.trim())) {
-    throw new Error(`Worker command blocked by policy (review): ${result.reason}`);
-  }
 }

package/src/reviewer.ts

@@ -1,4 +1,5 @@
 import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager } from "@earendil-works/pi-coding-agent";
+import { isDeepStrictEqual } from "node:util";
 import { redactSensitive } from "./redaction.ts";
 import type { AcceptanceReport, ReviewFinding, ReviewReport, TaskSpec } from "./types.ts";
 import type { RepositoryEvidence } from "./verifier.ts";
@@ -130,7 +131,16 @@ ${boundedJson(input.acceptance)}
 REPOSITORY STATUS:
 ${boundText(redactText(input.evidence.status), 8_000)}
 
-REPOSITORY DIFF (HEAD-RELATIVE, UNTRUSTED):
+REPOSITORY BASE:
+${redactText(input.evidence.baseRef ?? "(unavailable; review current evidence)")}
+
+LOCAL BRANCH:
+${redactText(input.evidence.branch ?? "(detached or unavailable)")}
+
+COMMITS AFTER BASELINE (UNTRUSTED):
+${boundText(redactText(input.evidence.commits ?? "(none)"), 8_000)}
+
+REPOSITORY DIFF (BASELINE-RELATIVE, UNTRUSTED):
 ${boundText(redactText(input.evidence.diff), 16_000)}
 
 UNTRACKED FILE EVIDENCE (UNTRUSTED):
@@ -138,7 +148,7 @@ ${boundText(redactText(input.evidence.untracked ?? "(none)"), 16_000)}
 
 EVIDENCE COMPLETE:
 ${String(input.evidence.complete !== false && input.evidence.truncated !== true)}
-If repository evidence is incomplete or truncated, do not return pass; return human and explain which evidence is unavailable.
+DISPLAY NOTE: fields below may end with [DISPLAY_TRUNCATED] because the prompt has a bounded presentation window. This is presentation-only and is not evidence loss. If EVIDENCE COMPLETE is true, do not return human merely because a displayed field is shortened; inspect the repository with the read-only tools instead. If EVIDENCE COMPLETE is false, do not return pass; return human and explain which evidence is unavailable.
 
 WORKER OUTPUT (UNTRUSTED):
 ${boundTailText(redactSensitive(input.workerOutput ?? "(none)"), 8_000)}
@@ -159,20 +169,40 @@ function textFromMessage(content: unknown): string {
     .join("");
 }
 
+export function normalizeReviewReport(value: unknown, round: number): ReviewReport {
+  try {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return invalidReview("invalid Reviewer output: result must be an object", round, new Date().toISOString());
+    }
+    const report = value as { verdict?: unknown; summary?: unknown; findings?: unknown };
+    if (typeof report.verdict !== "string" || typeof report.summary !== "string" || !report.summary.trim() || !Array.isArray(report.findings)) {
+      return invalidReview("invalid Reviewer output: result must include verdict, summary and findings", round, new Date().toISOString());
+    }
+    const encoded = JSON.stringify(value);
+    return parseReview(encoded ?? "", round);
+  } catch (error) {
+    return invalidReview(`invalid Reviewer output: ${error instanceof Error ? error.message : String(error)}`, round, new Date().toISOString());
+  }
+}
+
 export function parseReview(text: string, round: number): ReviewReport {
   const checkedAt = new Date().toISOString();
   if (Buffer.byteLength(text, "utf8") > MAX_REVIEW_RESPONSE_BYTES) return invalidReview(`Reviewer response exceeded ${MAX_REVIEW_RESPONSE_BYTES} bytes`, round, checkedAt);
-  const candidate = text.trim();
-  if (!candidate) return invalidReview("Reviewer returned no JSON object", round, checkedAt);
+  if (!text.trim()) return invalidReview("Reviewer returned no JSON object", round, checkedAt);
   try {
-    const value = JSON.parse(candidate) as Record<string, unknown>;
+    const objects = extractJsonObjects(text);
+    if (objects.length === 0) throw new Error("Reviewer output did not contain a JSON object");
+    if (objects.slice(1).some((value) => !isDeepStrictEqual(value, objects[0]))) {
+      throw new Error("Reviewer output contained multiple distinct JSON objects");
+    }
+    const value = objects[0] as Record<string, unknown>;
     if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Reviewer output must be a JSON object");
     const verdict = value.verdict;
     if (verdict !== "pass" && verdict !== "revise" && verdict !== "human") throw new Error("unsupported verdict");
     const summary = typeof value.summary === "string" && value.summary.trim() ? value.summary.trim() : "no summary provided";
-    if (value.findings !== undefined && !Array.isArray(value.findings)) throw new Error("findings must be an array");
-    if (Array.isArray(value.findings) && value.findings.length > MAX_REVIEW_FINDINGS) throw new Error(`findings exceed the limit of ${MAX_REVIEW_FINDINGS}`);
-    const findings = (value.findings ?? []).map((finding, index) => parseFinding(finding, index));
+    if (!Array.isArray(value.findings)) throw new Error("findings must be an array");
+    if (value.findings.length > MAX_REVIEW_FINDINGS) throw new Error(`findings exceed the limit of ${MAX_REVIEW_FINDINGS}`);
+    const findings = value.findings.map((finding, index) => parseFinding(finding, index));
     if (verdict === "revise" && findings.length === 0) throw new Error("revise verdict requires at least one finding");
     return { verdict, summary: boundText(summary, 4_000), findings, round, checkedAt };
   } catch (error) {
@@ -180,6 +210,56 @@ export function parseReview(text: string, round: number): ReviewReport {
   }
 }
 
+/**
+ * Claude occasionally wraps its answer in a fence, a sentence, or repeats
+ * the same JSON object. Extract one bounded object while rejecting conflicting
+ * objects: prose is harmless, but ambiguity must remain non-publishable.
+ */
+function extractJsonObjects(text: string): unknown[] {
+  const objects: unknown[] = [];
+  let offset = 0;
+  while (offset < text.length) {
+    const start = text.indexOf("{", offset);
+    if (start < 0) break;
+    const end = balancedObjectEnd(text, start);
+    if (end < 0) {
+      offset = start + 1;
+      continue;
+    }
+    const candidate = text.slice(start, end + 1);
+    try {
+      const value = JSON.parse(candidate) as unknown;
+      if (value && typeof value === "object" && !Array.isArray(value)) objects.push(value);
+      offset = end + 1;
+    } catch {
+      offset = start + 1;
+    }
+  }
+  return objects;
+}
+
+function balancedObjectEnd(text: string, start: number): number {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let index = start; index < text.length; index += 1) {
+    const character = text[index];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (character === "\\") escaped = true;
+      else if (character === '"') inString = false;
+      continue;
+    }
+    if (character === '"') {
+      inString = true;
+      continue;
+    }
+    if (character === "{") depth += 1;
+    else if (character === "}" && --depth === 0) return index;
+  }
+  return -1;
+}
+
 function parseFinding(value: unknown, index: number): ReviewFinding {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`finding ${index} must be an object`);
   const source = value as Record<string, unknown>;
@@ -248,11 +328,11 @@ async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: str
 function boundTailText(value: unknown, maxBytes: number): string {
   const text = String(value);
   if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
-  return `[TRUNCATED]\n${Buffer.from(text, "utf8").subarray(-maxBytes).toString("utf8")}`;
+  return `[DISPLAY_TRUNCATED]\n${Buffer.from(text, "utf8").subarray(-maxBytes).toString("utf8")}`;
 }
 
 function boundText(value: unknown, maxBytes: number): string {
   const text = String(value);
   if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
-  return `${Buffer.from(text, "utf8").subarray(0, maxBytes).toString("utf8")}\n[TRUNCATED]`;
+  return `${Buffer.from(text, "utf8").subarray(0, maxBytes).toString("utf8")}\n[DISPLAY_TRUNCATED]`;
 }

package/src/state.ts

@@ -2,14 +2,15 @@ import type { SupervisorState } from "./types.ts";
 
 const transitions: Record<SupervisorState, readonly SupervisorState[]> = {
   idle: ["starting"],
-  starting: ["running", "failed", "stopped"],
-  running: ["waiting", "paused", "verifying", "failed", "stopped"],
-  waiting: ["running", "paused", "verifying", "failed", "stopped"],
-  paused: ["running", "stopped", "failed"],
-  verifying: ["completed", "running", "failed", "stopped"],
+  starting: ["running", "blocked", "failed", "stopped"],
+  running: ["waiting", "paused", "verifying", "blocked", "failed", "stopped"],
+  waiting: ["running", "paused", "verifying", "blocked", "failed", "stopped"],
+  paused: ["running", "blocked", "stopped", "failed"],
+  verifying: ["completed", "running", "blocked", "failed", "stopped"],
   completed: ["idle"],
+  blocked: ["idle"],
   failed: ["idle"],
-  stopped: ["idle"],
+  stopped: ["idle", "blocked"],
 };
 
 export class InvalidTransitionError extends Error {