pi-claude-supervisor 0.5.2 → 0.5.3

package/src/types.ts

@@ -6,6 +6,7 @@ export type SupervisorState =
   | "paused"
   | "verifying"
   | "completed"
+  | "blocked"
   | "failed"
   | "stopped";
 
@@ -55,6 +56,11 @@ export interface WorkerStartInput {
   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 {
@@ -166,6 +172,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 +188,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 +222,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

@@ -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(),
   };
 }

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,168 @@ 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.
+ */
+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");
+  }
+  return [
+    ...args,
+    "--settings",
+    JSON.stringify({
+      sandbox: {
+        enabled: true,
+        failIfUnavailable: true,
+        allowUnsandboxedCommands: false,
+        network: { allowedDomains: [] },
+      },
+    }),
+  ];
+}
+
+/**
+ * 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);
+}

package/src/worker/process-adapter.ts

@@ -172,6 +172,21 @@ export class ProcessWorkerAdapter implements WorkerAdapter {
     const launch = cgroupPath
       ? cgroupBootstrapLaunch(input.command, args, input.cwd, workerEnv, cgroupPath)
       : { command: input.command, args, env: workerEnv };
+    try {
+      // This is the last asynchronous operation before spawn. Automatic mode
+      // uses it for an exact repository HEAD assertion; adapters that add
+      // setup work must invoke the hook only after that work is complete.
+      await input.preSpawnCheck?.();
+    } catch (error) {
+      if (cgroupPath) await rm(cgroupPath, { recursive: true, force: true }).catch(() => {});
+      throw error;
+    }
+    const finalAbortReason = input.startupToken ? this.#pendingStartupAborts.get(input.startupToken) : undefined;
+    if (input.startupToken) this.#pendingStartupAborts.delete(input.startupToken);
+    if (input.abortSignal?.aborted || finalAbortReason !== undefined) {
+      if (cgroupPath) await rm(cgroupPath, { recursive: true, force: true }).catch(() => {});
+      throw new Error(`worker startup aborted${finalAbortReason ? `: ${finalAbortReason}` : " before spawn"}`);
+    }
     let child: ChildProcess;
     try {
       child = spawn(launch.command, launch.args, {