pi-claude-supervisor 0.5.2 → 0.5.4

package/src/types.ts

@@ -6,6 +6,7 @@ export type SupervisorState =
   | "paused"
   | "verifying"
   | "completed"
+  | "blocked"
   | "failed"
   | "stopped";
 
@@ -51,10 +52,17 @@ export interface WorkerStartInput {
   };
   /** Adopted sessions must not replay the task as a new user message. */
   sendInitialInput?: boolean;
+  /** Automatic mode selects the structured tmux bridge instead of the manual TUI transport. */
+  automatic?: boolean;
   /** Cancel startup before a worker is fully returned to the supervisor. */
   abortSignal?: AbortSignal;
   /** Internal token that scopes out-of-band startup cancellation. */
   startupToken?: string;
+  /**
+   * Automatic-start repository assertion. Built-in adapters invoke this after
+   * all asynchronous setup and immediately before spawning the Worker.
+   */
+  preSpawnCheck?: () => Promise<void>;
 }
 
 export interface WorkerHandle {
@@ -105,7 +113,7 @@ export interface PermissionDecision {
 export interface WorkerAdapter {
   capabilities(): WorkerCapabilities;
   /** Validate host/transport prerequisites before starting a Worker. */
-  preflight?(input: Pick<WorkerStartInput, "cwd" | "command" | "args" | "env" | "approval">): Promise<void>;
+  preflight?(input: Pick<WorkerStartInput, "cwd" | "command" | "args" | "env" | "approval" | "automatic">): Promise<void>;
   start(input: WorkerStartInput): Promise<WorkerHandle>;
   /** Cancel adapter-owned startup work before a WorkerHandle is returned. */
   abortStart?(reason: string, startupToken?: string): Promise<void>;
@@ -166,6 +174,15 @@ export interface AcceptanceCheckResult {
   finishedAt: string;
 }
 
+export interface TaskAutonomy {
+  /** Local development continues without synchronous human approval. */
+  unattended: boolean;
+  /** The Worker should commit the candidate on its local branch before completion. */
+  requireLocalCommit: boolean;
+  /** Number of autonomous Decision Worker retries before parking a candidate. */
+  maxDecisionRetries: number;
+}
+
 export interface TaskSpec {
   goal: string;
   scope: string[];
@@ -173,8 +190,12 @@ export interface TaskSpec {
   forbidden: string[];
   acceptance: AcceptanceCheck[];
   maxRepairRounds: number;
+  autonomy: TaskAutonomy;
 }
 
+/** Public input shape; nested autonomy fields may be omitted and are defaulted. */
+export type TaskSpecInput = Partial<Omit<TaskSpec, "autonomy">> & { autonomy?: Partial<TaskAutonomy> };
+
 export type ReviewVerdict = "pass" | "revise" | "human";
 export type ReviewSeverity = "P0" | "P1" | "P2" | "P3";
 
@@ -203,6 +224,10 @@ export interface TaskContext {
   cwd: string;
   maxTurns: number;
   startedAt: string;
+  /** Repository HEAD before this task; used to review local commits as well as worktree changes. */
+  baseCommit?: string;
+  /** Non-protected local branch recorded before automatic work begins. */
+  baseBranch?: string;
   spec: TaskSpec;
   repairRound: number;
   lastFindingSignature?: string;

package/src/verifier.ts

@@ -1,6 +1,6 @@
 import { execFile } from "node:child_process";
 import { constants as fsConstants } from "node:fs";
-import { lstat, open, realpath } from "node:fs/promises";
+import { lstat, open, readlink, realpath } from "node:fs/promises";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import type { AcceptanceCheck, AcceptanceCheckResult, AcceptanceReport, VerificationResult } from "./types.ts";
@@ -38,11 +38,85 @@ export interface RepositoryEvidence {
   untracked?: string;
   /** False when a command/file could not be safely or completely collected. */
   complete?: boolean;
+  /** Commit summaries made after the task baseline. */
+  commits?: string;
+  /** Baseline HEAD used for the diff and commit range, when available. */
+  baseRef?: string;
+  /** Current branch used for the local candidate, when available. */
+  branch?: string;
   /** True when any evidence field was bounded or omitted. */
   truncated?: boolean;
   collectedAt: string;
 }
 
+/** Read the repository HEAD without invoking a shell. */
+export async function repositoryHead(cwd: string, signal?: AbortSignal): Promise<string | undefined> {
+  try {
+    const result = await execFileAsync("git", ["rev-parse", "--verify", "HEAD"], {
+      cwd,
+      timeout: 30_000,
+      maxBuffer: 1024,
+      signal,
+      env: workerEnvironment(process.env, { GIT_TERMINAL_PROMPT: "0" }),
+    });
+    const head = String(result.stdout).trim();
+    return /^[0-9a-f]{40,64}$/u.test(head) ? head : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Verify that a full commit object is still present without invoking a shell. */
+export async function repositoryCommitExists(cwd: string, commit: string, signal?: AbortSignal): Promise<boolean> {
+  if (!/^[0-9a-f]{40,64}$/iu.test(commit)) return false;
+  try {
+    const result = await execFileAsync("git", ["cat-file", "-e", `${commit}^{commit}`], {
+      cwd,
+      timeout: 30_000,
+      maxBuffer: 1024,
+      signal,
+      env: workerEnvironment(process.env, { GIT_TERMINAL_PROMPT: "0" }),
+    });
+    return result.stderr.length === 0;
+  } catch {
+    return false;
+  }
+}
+
+/** Determine whether cwd is a non-bare Git worktree without invoking a shell. */
+export async function repositoryWorkTree(cwd: string, signal?: AbortSignal): Promise<boolean | undefined> {
+  try {
+    const result = await execFileAsync("git", ["rev-parse", "--is-inside-work-tree"], {
+      cwd,
+      timeout: 30_000,
+      maxBuffer: 1024,
+      signal,
+      env: workerEnvironment(process.env, { GIT_TERMINAL_PROMPT: "0" }),
+    });
+    const value = String(result.stdout).trim();
+    return value === "true" ? true : value === "false" ? false : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Read the current symbolic branch without invoking a shell. */
+export async function repositoryBranch(cwd: string, signal?: AbortSignal): Promise<string | undefined> {
+  try {
+    const result = await execFileAsync("git", ["symbolic-ref", "--quiet", "--short", "HEAD"], {
+      cwd,
+      timeout: 30_000,
+      maxBuffer: 1024,
+      signal,
+      env: workerEnvironment(process.env, { GIT_TERMINAL_PROMPT: "0" }),
+    });
+    const branch = String(result.stdout).trim();
+    return branch && /^[A-Za-z0-9._/-]+$/u.test(branch) ? branch : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export async function verify(
   cwd: string,
   command: VerificationCommand = { command: "git", args: ["diff", "--check"] },
@@ -91,21 +165,29 @@ export async function verifyAll(cwd: string, checks: readonly AcceptanceCheck[],
 }
 
 /** Collect bounded repository evidence for the independent read-only Reviewer. */
-export async function collectRepositoryEvidence(cwd: string, options: Pick<VerificationOptions, "signal"> = {}): Promise<RepositoryEvidence> {
+export async function collectRepositoryEvidence(cwd: string, options: Pick<VerificationOptions, "signal"> & { baseRef?: string } = {}): Promise<RepositoryEvidence> {
   throwIfAborted(options.signal);
-  const [statusResult, diffResult, untrackedResult] = await Promise.all([
+  const baseRef = options.baseRef;
+  const diffRef = baseRef ?? "HEAD";
+  const commitArgs = baseRef ? ["log", "--format=%h %s", "--no-decorate", `${baseRef}..HEAD`, "--"] : ["log", "--format=%h %s", "--no-decorate", "-20", "--"];
+  const [statusResult, diffResult, commitsResult, branchResult, untrackedResult] = await Promise.all([
     readGitEvidence(cwd, ["status", "--short", "--untracked-files=all"], options.signal),
-    // HEAD-relative diff includes both staged and unstaged changes for tracked files.
-    readGitEvidence(cwd, ["diff", "--no-ext-diff", "--unified=3", "HEAD", "--"], options.signal),
+    // A baseline-relative diff includes committed, staged, and unstaged changes.
+    readGitEvidence(cwd, ["diff", "--no-ext-diff", "--unified=3", diffRef, "--"], options.signal),
+    readGitEvidence(cwd, commitArgs, options.signal),
+    readGitEvidence(cwd, ["symbolic-ref", "--quiet", "--short", "HEAD"], options.signal),
     collectUntrackedEvidence(cwd, options.signal),
   ]);
   throwIfAborted(options.signal);
   return {
     status: statusResult.text,
     diff: diffResult.text,
+    commits: commitsResult.text,
     untracked: untrackedResult.text,
-    complete: statusResult.complete && diffResult.complete && untrackedResult.complete,
-    truncated: statusResult.truncated || diffResult.truncated || untrackedResult.truncated,
+    ...(baseRef ? { baseRef } : {}),
+    ...(branchResult.text.trim() !== "(none)" ? { branch: branchResult.text.trim() } : {}),
+    complete: statusResult.complete && diffResult.complete && commitsResult.complete && branchResult.complete && untrackedResult.complete,
+    truncated: statusResult.truncated || diffResult.truncated || commitsResult.truncated || branchResult.truncated || untrackedResult.truncated,
     collectedAt: new Date().toISOString(),
   };
 }
@@ -228,6 +310,12 @@ async function collectUntrackedEvidence(cwd: string, signal?: AbortSignal): Prom
         sections.push(`--- ${JSON.stringify(path)} [non-regular file omitted]`);
         continue;
       }
+      if (opened.nlink > 1) {
+        complete = false;
+        sections.push(`--- ${JSON.stringify(path)} [hard-link file omitted]`);
+        continue;
+      }
+      await assertOpenedEvidencePath(root, handle.fd);
       const buffer = Buffer.alloc(MAX_UNTRACKED_FILE_BYTES + 1);
       const read = await handle.read(buffer, 0, buffer.length, 0);
       const bytes = buffer.subarray(0, read.bytesRead);
@@ -256,6 +344,17 @@ async function collectUntrackedEvidence(cwd: string, signal?: AbortSignal): Prom
   return { ...bounded, complete: complete && bounded.complete, truncated: truncated || bounded.truncated };
 }
 
+async function assertOpenedEvidencePath(root: string, fd: number): Promise<void> {
+  if (process.platform !== "linux") throw new Error("opened evidence identity cannot be verified on this platform");
+  const target = (await readlink(`/proc/self/fd/${fd}`)).replace(/ \(deleted\)$/u, "");
+  const normalizedTarget = target.replaceAll("\\", "/");
+  if (normalizedTarget.split("/").some((segment) => segment.toLowerCase() === ".git")) throw new Error("opened evidence path resolves into Git metadata");
+  const relativeTarget = relative(root, target);
+  if (isAbsolute(relativeTarget) || relativeTarget === ".." || relativeTarget.startsWith(`..${sep}`) || relativeTarget.startsWith(`..${"\\"}`)) {
+    throw new Error("opened evidence path escaped the repository root");
+  }
+}
+
 async function assertNoSymlinkComponents(root: string, relativePath: string): Promise<void> {
   const parts = relativePath.split(sep).filter(Boolean);
   let current = root;

package/src/worker/environment.ts

@@ -1,3 +1,7 @@
+import { constants as fsConstants } from "node:fs";
+import { access, realpath, stat } from "node:fs/promises";
+import { delimiter, dirname, join } from "node:path";
+
 const inheritedNames = [
   "PATH",
   "HOME",
@@ -29,3 +33,216 @@ export function workerEnvironment(
   }
   return result;
 }
+
+/**
+ * Restrict explicit variables supplied to an unattended Worker. This is not a
+ * network sandbox, but it removes common remote-repository credentials and
+ * disables the Git/package-manager credential helpers before command policy
+ * gets a chance to inspect a structured Bash request.
+ */
+export function automaticWorkerEnvironment(explicit: NodeJS.ProcessEnv = {}): NodeJS.ProcessEnv {
+  const result: NodeJS.ProcessEnv = {};
+  for (const [name, value] of Object.entries(explicit)) {
+    if (value !== undefined && isAutomaticAllowedName(name) && (!isRemoteCredentialName(name) || isProviderCredentialName(name))) result[name] = value;
+  }
+  result.GIT_CONFIG_NOSYSTEM = "1";
+  result.GIT_CONFIG_SYSTEM = process.platform === "win32" ? "NUL" : "/dev/null";
+  result.GIT_CONFIG_GLOBAL = process.platform === "win32" ? "NUL" : "/dev/null";
+  result.GIT_CONFIG_COUNT = "3";
+  result.GIT_CONFIG_KEY_0 = "credential.helper";
+  result.GIT_CONFIG_VALUE_0 = "";
+  result.GIT_CONFIG_KEY_1 = "http.proxy";
+  result.GIT_CONFIG_VALUE_1 = "http://127.0.0.1:9";
+  result.GIT_CONFIG_KEY_2 = "https.proxy";
+  result.GIT_CONFIG_VALUE_2 = "http://127.0.0.1:9";
+  result.GIT_TERMINAL_PROMPT = "0";
+  result.GIT_SSH_COMMAND = "false";
+  result.GH_CONFIG_DIR = process.platform === "win32" ? "NUL" : "/dev/null";
+  result.NPM_CONFIG_USERCONFIG = process.platform === "win32" ? "NUL" : "/dev/null";
+  result.npm_config_userconfig = result.NPM_CONFIG_USERCONFIG;
+  return result;
+}
+
+/**
+ * Ask Claude Code to sandbox Bash and its descendants. The API process keeps
+ * its provider connection, while Worker-launched commands get no outbound
+ * network and cannot silently fall back to an unsandboxed shell. Automatic mode
+ * admits only the direct Claude command name. Startup resolves and pins its
+ * operator-owned executable path so a custom path or writable replacement
+ * cannot silently omit this boundary.
+ */
+const automaticToolAllowlist = new Set([
+  "Bash",
+  "Edit",
+  "Glob",
+  "Grep",
+  "Read",
+  "Write",
+  "NotebookEdit",
+  "AskUserQuestion",
+]);
+
+/**
+ * The automatic Worker is the only Claude session allowed to drive the local
+ * lifecycle. Keep its tool surface explicit: nested agents/background tasks
+ * can start a second reviewer, outlive the Worker, or hide work from the
+ * Supervisor's event stream. The safe-mode and strict-MCP flags also prevent
+ * project/user customizations from reintroducing that capability.
+ */
+export function automaticClaudeArgs(command: string, args: readonly string[] = []): string[] {
+  if (!isDirectClaudeName(command)) {
+    throw new Error("automatic supervision requires the direct Claude executable command name; custom executable paths need their own host boundary");
+  }
+  if (args.some((arg) => arg === "--settings" || arg.startsWith("--settings="))) {
+    throw new Error("automatic Claude supervision controls --settings; remove the caller-provided settings override");
+  }
+  for (const option of ["--allowedTools", "--allowed-tools", "--agent", "--agents", "--plugin-dir", "--plugin-url", "--resume", "-r", "--continue", "-c", "--bg", "--background", "--remote-control", "--tmux", "--worktree", "-w"]) {
+    if (args.some((arg) => arg === option || arg.startsWith(`${option}=`))) {
+      throw new Error(`automatic Claude supervision controls ${option}; remove the caller-provided session or tool-extension override`);
+    }
+  }
+  const result = [...args];
+  const tools = requestedAutomaticTools(result);
+  if (tools === undefined) result.push("--tools", [...automaticToolAllowlist].join(","));
+  else if (tools.some((tool) => !automaticToolAllowlist.has(tool))) {
+    throw new Error("automatic Claude supervision permits only the bounded local tool allowlist; nested agents and background reviewers are disabled");
+  }
+  result.push(
+    "--safe-mode",
+    "--strict-mcp-config",
+    "--disallowed-tools",
+    "Task,TaskOutput,Agent,Skill,SendUserMessage",
+    "--settings",
+    JSON.stringify({
+      sandbox: {
+        enabled: true,
+        failIfUnavailable: true,
+        allowUnsandboxedCommands: false,
+        network: { allowedDomains: [] },
+      },
+    }),
+  );
+  return result;
+}
+
+function requestedAutomaticTools(args: string[]): string[] | undefined {
+  const index = args.findIndex((arg) => arg === "--tools" || arg.startsWith("--tools="));
+  if (index < 0) return undefined;
+  const values = args[index].startsWith("--tools=")
+    ? [args[index].slice("--tools=".length)]
+    : (() => {
+        const collected: string[] = [];
+        for (let cursor = index + 1; cursor < args.length && !args[cursor]!.startsWith("-"); cursor += 1) collected.push(args[cursor]!);
+        return collected;
+      })();
+  const tools = values.flatMap((value) => value.split(/[\s,]+/u)).map((value) => value.trim()).filter(Boolean);
+  if (tools.includes("default")) throw new Error("automatic Claude supervision requires an explicit tool allowlist; --tools default is not permitted");
+  return tools.map((tool) => tool.replace(/\(.*/u, ""));
+}
+
+/**
+ * Resolve and pin the executable used by automatic mode before preflight and
+ * spawn. A bare command is resolved from the supervisor's own PATH; explicit
+ * paths and writable/untrusted executable locations are rejected. Operators
+ * who do not want PATH to be the trust root can set
+ * PI_CLAUDE_SUPERVISOR_TRUSTED_CLAUDE to the expected executable path.
+ */
+export async function assertTrustedAutomaticClaudeExecutable(command: string, expectedPath?: string): Promise<string> {
+  if (!isDirectClaudeName(command)) {
+    throw new Error("automatic supervision requires the direct Claude executable command name; custom executable paths need their own host boundary");
+  }
+  const candidate = await resolveExecutable(command, process.env.PATH);
+  if (!candidate) throw new Error("automatic supervision could not resolve the trusted Claude executable from PATH");
+  const resolved = await realpath(candidate);
+  await assertSecureExecutablePath(resolved);
+  const configured = expectedPath?.trim() || process.env.PI_CLAUDE_SUPERVISOR_TRUSTED_CLAUDE?.trim();
+  if (configured) {
+    let expected: string;
+    try {
+      expected = await realpath(configured);
+      await assertSecureExecutablePath(expected);
+    } catch (error) {
+      if (error instanceof Error && /writable|owned|regular file/u.test(error.message)) throw error;
+      throw new Error("the expected Claude executable path is not a readable executable");
+    }
+    if (expected !== resolved) {
+      throw new Error("resolved Claude executable does not match the expected pinned identity");
+    }
+  }
+  return resolved;
+}
+
+function isDirectClaudeName(command: string): boolean {
+  if (command.includes("/") || command.includes("\\")) return false;
+  const executable = command.toLowerCase();
+  return executable === "claude" || executable === "claude.exe";
+}
+
+async function resolveExecutable(command: string, pathValue: string | undefined): Promise<string | undefined> {
+  for (const directory of (pathValue ?? "").split(delimiter).filter(Boolean)) {
+    const candidate = join(directory, command);
+    try {
+      await access(candidate, fsConstants.X_OK);
+      return candidate;
+    } catch {
+      // Continue to the next PATH entry.
+    }
+  }
+  return undefined;
+}
+
+async function assertSecureExecutablePath(path: string): Promise<void> {
+  await access(path, fsConstants.X_OK);
+  const executable = await stat(path);
+  if (!executable.isFile()) throw new Error("resolved Claude executable is not a regular file");
+  if (process.platform !== "win32") {
+    const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+    if ((executable.mode & 0o022) !== 0 || (uid !== undefined && executable.uid !== uid && executable.uid !== 0)) {
+      throw new Error("resolved Claude executable is writable by or owned by an untrusted user");
+    }
+    let directory = dirname(path);
+    while (true) {
+      const info = await stat(directory);
+      if ((info.mode & 0o022) !== 0 || (uid !== undefined && info.uid !== uid && info.uid !== 0)) {
+        throw new Error("a directory containing the resolved Claude executable is writable by or owned by an untrusted user");
+      }
+      const parent = dirname(directory);
+      if (parent === directory) break;
+      directory = parent;
+    }
+  }
+}
+
+const automaticEnvironmentAllowlist = new Set([
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_AUTH_TOKEN",
+  "ANTHROPIC_BASE_URL",
+  "CLAUDE_CODE_OAUTH_TOKEN",
+  "CLAUDE_CODE_USE_BEDROCK",
+  "CLAUDE_CODE_USE_VERTEX",
+  "CLAUDE_CODE_USE_FOUNDRY",
+  "AWS_PROFILE",
+  "AWS_REGION",
+  "AWS_DEFAULT_REGION",
+  "AWS_SDK_LOAD_CONFIG",
+  "GOOGLE_CLOUD_PROJECT",
+  "GOOGLE_CLOUD_REGION",
+  "CLOUD_ML_REGION",
+  "NO_COLOR",
+  "CI",
+]);
+
+function isAutomaticAllowedName(name: string): boolean {
+  return automaticEnvironmentAllowlist.has(name);
+}
+
+function isProviderCredentialName(name: string): boolean {
+  return name === "ANTHROPIC_API_KEY" || name === "ANTHROPIC_AUTH_TOKEN" || name === "CLAUDE_CODE_OAUTH_TOKEN";
+}
+
+export function isRemoteCredentialName(name: string): boolean {
+  if (isProviderCredentialName(name)) return false;
+  return /^(?:SSH_AUTH_SOCK|GIT_ASKPASS|GIT_SSH_COMMAND|GIT_CREDENTIAL_HELPER|GIT_CONFIG(?:_|$)|GH_CONFIG_DIR|NPM_CONFIG_USERCONFIG|AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY|AWS_SESSION_TOKEN|AZURE_CLIENT_ID|AZURE_CLIENT_SECRET|AZURE_TENANT_ID|GOOGLE_APPLICATION_CREDENTIALS|KUBECONFIG)$/iu.test(name)
+    || /(?:^|_)(?:GITHUB|GH|GITLAB|BITBUCKET|NPM|NODE_AUTH|CODEARTIFACT|HUGGINGFACE|DOCKER|AWS|AZURE|GOOGLE|CI_JOB)(?:_|$)/iu.test(name)
+    || /(?:^|_)(?:TOKEN|PASSWORD|PASSWD|SECRET|PRIVATE_KEY|ACCESS_KEY|AUTH_TOKEN|API_KEY|CREDENTIALS?)(?:_|$)/iu.test(name);
+}