pi-claude-supervisor 0.9.2 → 0.10.0

package/src/decision-worker.ts

@@ -89,6 +89,12 @@ export interface DecisionWorkerOptions {
   compactionTokens?: number;
   /** Token accounting for every model call made by this session. */
   onUsage?: (usage: PiUsageSample) => void;
+  /** A decision request failed transiently and will be asked again after `delayMs`. */
+  onRetry?: (event: WorkerEvent, info: { attempt: number; delayMs: number; error: unknown }) => void;
+  /** True once a later event has made this one moot: it is then dropped, neither retried nor failed. */
+  isSuperseded?: (event: WorkerEvent) => boolean;
+  /** A moot event was dropped while its decision was failing (for the audit log). */
+  onSuperseded?: (event: WorkerEvent, error: unknown) => void;
 }
 
 export type PiModel = NonNullable<NonNullable<Parameters<typeof createAgentSession>[0]>["model"]>;
@@ -105,6 +111,58 @@ export const STALE_VERIFICATION_TURNS = 3;
 const DEFAULT_DECISION_RETRY_BACKOFF_MS = 5_000;
 const MAX_DECISION_RETRY_BACKOFF_MS = 60_000;
 
+/**
+ * Errors no amount of waiting fixes: rejected, missing or expired
+ * credentials, an exhausted account, a model that does not exist. Matched on
+ * words, not bare status codes, which also turn up inside request ids, URLs
+ * and wrapped upstream errors.
+ */
+const CONFIGURATION_ERROR = /(?:account|organi[sz]ation)[^\n]{0,40}(?:terminated|disabled|suspended|deactivated)|authentication|unauthori[sz]ed|incorrect api key|token has expired|invalid[_ ]?x?-?api[_ -]?key|api[_ ]key[_ ](?:not[_ ]valid|expired|invalid)|no api key found|security token[^\n]{0,40}invalid|UnrecognizedClient|ExpiredToken|AccessDenied|permission[_ ]denied|permission_error|payment[_ ]required|credit[_ ]balance|insufficient[_ ]quota|billing_error|not_found_error|models?\b[^\n]{0,80}\b(?:not[_ ]found|does not exist|is invalid)|model identifier is invalid|unsupported[_ ]model|invalid[_ ]model/iu;
+
+/**
+ * Errors that pass by themselves: provider load and rate limits (including a
+ * quota that resets, whose Gemini message also mentions "billing"), 5xx,
+ * gateway and network failures. Based on pi-ai's own retryable list. Anything
+ * matching neither list, such as a prompt that is too long, a corrupted
+ * session or this worker's own request timeout, fails the same way every time
+ * and stays bounded by maxDecisionRetries.
+ */
+const TRANSIENT_ERROR = /overloaded|rate.?limit|too many requests|resource.?exhausted|retry in \d|quota exceeded for metric|exceeded your current quota|\b(?:429|500|502|503|504|524|529)\b|service.?unavailable|temporarily unavailable|server.?error|internal.?error|provider.?returned.?error|network.?error|connection.?(?:error|refused|lost|reset)|other side closed|fetch failed|getaddrinfo|ENOTFOUND|EAI_AGAIN|ECONNRESET|ETIMEDOUT|upstream.?connect|reset before headers|socket hang up|socket connection was closed|gateway.?time.?out|websocket.?(?:closed|error)|ended without|stream ended before|http2 request did not get a response|you can retry your request|try your request again|please retry your request|try again in|timed? ?out|timeout|terminated|premature close|\b408\b/iu;
+
+/** The Decision Worker's own per-request timeout: the model ran the whole budget. */
+const OWN_TIMEOUT = /^Decision Worker [^\n]* timed out after \d+ms$/u;
+
+export type DecisionErrorClass = "configuration" | "transient" | "other";
+
+export function classifyDecisionError(error: unknown): DecisionErrorClass {
+  if (!(error instanceof Error)) return "other";
+  if (error.name === "DecisionWorkerConfigError") return "configuration";
+  if (OWN_TIMEOUT.test(error.message)) return "other";
+  // Judge the provider's own text, not this worker's "… model request failed:" wrapper.
+  const text = error.message.replace(/^[^\n:]*model request failed: /u, "");
+  if (CONFIGURATION_ERROR.test(text)) return "configuration";
+  // A provider's error turn (pi-ai reports it as a stop reason, not a throw).
+  if (error.name === "DecisionWorkerApiError" && TRANSIENT_ERROR.test(text)) return "transient";
+  // A thrown transport failure before any provider answered.
+  if (/fetch failed|getaddrinfo|ENOTFOUND|EAI_AGAIN|ECONNRESET|ETIMEDOUT|socket hang up|network.?error/iu.test(text)) return "transient";
+  return "other";
+}
+
+export function isDecisionConfigurationError(error: unknown): boolean {
+  return classifyDecisionError(error) === "configuration";
+}
+
+function configurationError(error: Error): Error {
+  const wrapped = new Error(`Decision Worker configuration error (credentials, billing or model): ${error.message}`, { cause: error });
+  wrapped.name = "DecisionWorkerConfigError";
+  return wrapped;
+}
+
+/** Marks an error thrown while the Supervisor applied an action, as opposed to one from the model. */
+export function isDecisionActionError(error: unknown): boolean {
+  return Boolean(error && typeof error === "object" && (error as { decisionActionFailed?: unknown }).decisionActionFailed === true);
+}
+
 /**
  * A persistent Pi SDK session used only for supervision decisions.
  * It has read-only repository tools and can request typed actions, but it
@@ -122,6 +180,7 @@ export class PiDecisionWorker implements DecisionWorkerLike {
   readonly #timeoutMs: number;
   /** Ends a startup retry backoff early; set only while one is waiting. */
   #wakeStartupBackoff?: () => void;
+  #wakeRetryBackoff?: () => void;
   readonly #retryBackoffMs: number;
   readonly #compactionTokens: number;
   /** Set after a compaction; the next primary decision prompt re-sends the startup instructions once. */
@@ -187,7 +246,7 @@ export class PiDecisionWorker implements DecisionWorkerLike {
           if (this.#closed) throw closedDuringStartup();
           // Only a provider error is worth another attempt: a timeout already
           // spent the whole prompt budget and would only multiply it.
-          const retryable = error instanceof Error && error.name === "DecisionWorkerApiError";
+          const retryable = error instanceof Error && error.name === "DecisionWorkerApiError" && classifyDecisionError(error) !== "configuration";
           if (attempt >= maxRetries || !retryable) {
             try { await this.#options.onStartupFailure?.(error); } catch { /* preserve the original startup failure */ }
             throw error;
@@ -259,11 +318,34 @@ export class PiDecisionWorker implements DecisionWorkerLike {
       } catch (error) {
         if (this.#closed) return;
         if (error instanceof Error && error.name === "AbortError") throw error;
-        if (attempt >= maxRetries) throw error;
+        // A later event made this one moot: its failure decides nothing, and
+        // failing it would park a task whose current turn is still undecided.
+        if (this.#dropIfSuperseded(event, error)) return;
+        const kind = classifyDecisionError(error);
+        // Waiting does not fix credentials, billing or a missing model: park now, with that reason.
+        if (kind === "configuration") throw configurationError(error as Error);
+        // A transient provider or network outage on a completed turn is
+        // waited out rather than parking the task: nobody is there to resume
+        // it, and the Supervisor's idle watchdog verifies the Worker's
+        // finished work if no decision ever lands. Nothing like that backs up
+        // any other event: a permission request blocks the Worker mid-turn
+        // (on some transports nothing else answers it), and after an exit
+        // only this decision starts verification. Those, a turn a later event
+        // has made moot, and anything that fails the same way on every
+        // attempt stay bounded.
+        const waitOut = kind === "transient" && event.type === "turn_completed";
+        if (!waitOut && attempt >= maxRetries) throw error;
         attempt += 1;
         // 429/529 overloads last minutes, not seconds: 15s, 45s, then 60s.
-        await new Promise<void>((resolveWait) => setTimeout(resolveWait, Math.min(MAX_DECISION_RETRY_BACKOFF_MS, this.#retryBackoffMs * 3 ** attempt)));
+        const delayMs = Math.min(MAX_DECISION_RETRY_BACKOFF_MS, this.#retryBackoffMs * 3 ** Math.min(attempt, 10));
+        try { this.#options.onRetry?.(event, { attempt, delayMs, error }); } catch { /* observability only */ }
+        await new Promise<void>((resolveWait) => {
+          const timer = setTimeout(() => { this.#wakeRetryBackoff = undefined; resolveWait(); }, delayMs);
+          // close() wakes this wait, so a stop does not sit out the backoff.
+          this.#wakeRetryBackoff = () => { clearTimeout(timer); this.#wakeRetryBackoff = undefined; resolveWait(); };
+        });
         if (!this.#session || this.#closed) return;
+        if (this.#dropIfSuperseded(event, error)) return;
         continue;
       }
       if (this.#closed) return;
@@ -285,8 +367,14 @@ export class PiDecisionWorker implements DecisionWorkerLike {
         continue;
       }
       // An action handler may stop or close the session. Do not replay an
-      // already-decoded action if the handler itself fails.
-      await this.#options.onAction(action, event);
+      // already-decoded action if the handler itself fails, and do not let
+      // its failure read as a model failure.
+      try {
+        await this.#options.onAction(action, event);
+      } catch (error) {
+        if (error && typeof error === "object") (error as { decisionActionFailed?: boolean }).decisionActionFailed = true;
+        throw error;
+      }
       await this.#maybeCompact();
       return;
     }
@@ -327,11 +415,23 @@ export class PiDecisionWorker implements DecisionWorkerLike {
     return Boolean(this.#options.sessionFile && this.#sessionFile === this.#options.sessionFile);
   }
 
+  #dropIfSuperseded(event: WorkerEvent, error: unknown): boolean {
+    if (this.#options.isSuperseded?.(event) !== true) return false;
+    try { this.#options.onSuperseded?.(event, error); } catch { /* observability only */ }
+    return true;
+  }
+
+  /** Resolves once every queued decision has finished or given up (shutdown and tests). */
+  async settled(): Promise<void> {
+    await this.#tail.catch(() => {});
+  }
+
   async close(): Promise<void> {
     // Do not await #tail here: onAction may be closing the worker from inside
     // the same queued decision, which would otherwise deadlock shutdown.
     this.#closed = true;
     this.#wakeStartupBackoff?.();
+    this.#wakeRetryBackoff?.();
     const session = this.#session;
     this.#session = undefined;
     if (session) await session.abort().catch(() => {});

package/src/hooks/relay.ts

@@ -12,6 +12,14 @@ import { shellQuote } from "../policy.ts";
  * with empty stdout, so a relay bug never blocks Claude Code. The fast path
  * (no Supervisor listening for this cwd) never requires "net", matching the
  * expectation that it costs about a millisecond.
+ *
+ * Routing prefers `CLAUDE_PROJECT_DIR`, which Claude Code sets on every hook
+ * command to the directory the session was launched in, over the event's
+ * `cwd`, which follows a persisted Bash `cd` into a subdirectory. Routing by
+ * `cwd` alone silently drops every later event (Stop, PreToolUse,
+ * PermissionRequest) of a Worker that changed directory. A nested Claude
+ * sets its own project directory, so it is not routed to its parent's
+ * Supervisor by this.
  */
 export const HOOK_RELAY_SCRIPT = `
 (function () {
@@ -73,22 +81,26 @@ export const HOOK_RELAY_SCRIPT = `
   var hookDir = process.env.PI_CLAUDE_SUPERVISOR_HOOK_DIR
     || (/[\\/]relay\.js$/.test(scriptPath) ? path.dirname(scriptPath) : "")
     || path.join(os.homedir(), ".pi", "agent", "claude-supervisor", "hooks");
-  var canonicalCwd = event.cwd;
-  try {
-    canonicalCwd = fs.realpathSync(event.cwd);
-  } catch (e) { /* fall back to the raw cwd */ }
-  var hash = crypto.createHash("sha256").update(canonicalCwd).digest("hex");
-  var socketPath = path.join(hookDir, "by-cwd", hash);
-
-  // Fast path: no Supervisor owns this cwd. Check before requiring "net" so
-  // the common case (no hooks configured / no owning Supervisor) is cheap.
-  var socketInfo;
-  try {
-    socketInfo = fs.statSync(socketPath);
-  } catch (e) {
-    return;
+  function socketFor(dir) {
+    if (typeof dir !== "string" || !path.isAbsolute(dir)) return undefined;
+    var canonical = dir;
+    try {
+      canonical = fs.realpathSync(dir);
+    } catch (e) { /* fall back to the raw path */ }
+    var candidate = path.join(hookDir, "by-cwd", crypto.createHash("sha256").update(canonical).digest("hex"));
+    try {
+      return fs.statSync(candidate).isSocket() ? { socketPath: candidate, routeCwd: canonical } : undefined;
+    } catch (e) {
+      return undefined;
+    }
   }
-  if (!socketInfo.isSocket()) return;
+
+  // Fast path: no Supervisor owns the project directory or the cwd. Check
+  // before requiring "net" so the common case (no hooks configured / no
+  // owning Supervisor) is cheap.
+  var route = socketFor(process.env.CLAUDE_PROJECT_DIR) || socketFor(event.cwd);
+  if (!route) return;
+  var socketPath = route.socketPath;
 
   var BLOCKING_EVENTS = ${JSON.stringify([...BLOCKING_HOOK_EVENTS])};
   var blocking = BLOCKING_EVENTS.indexOf(event.hook_event_name) !== -1;
@@ -97,6 +109,7 @@ export const HOOK_RELAY_SCRIPT = `
     pid: process.pid,
     ppid: process.ppid,
     tmuxPane: process.env.TMUX_PANE,
+    routeCwd: route.routeCwd,
     event: event,
   }) + "\\n";
 

package/src/hooks/server.ts

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { createServer, type Server, type Socket } from "node:net";
 import { chmod, lstat, mkdir, readdir, readlink, realpath, rename, rm, symlink, unlink } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import { tmpdir } from "node:os";
 import { CLAUDE_HOOK_EVENT_NAMES, type ClaudeHookEvent, type ClaudeHookEventName, type HookEventSource, type HookRelayReply, type HookRelayRequest } from "./types.ts";
 
@@ -33,7 +33,7 @@ export function hookSocketRuntimeDirectory(env: NodeJS.ProcessEnv = process.env)
 
 /**
  * One socket per Pi process, with a per-cwd symlink under `by-cwd/` so a
- * relay only needs the event's cwd to find its Supervisor. See
+ * relay only needs the task directory to find its Supervisor. See
  * src/hooks/types.ts for the full routing contract.
  */
 export class HookServer implements HookEventSource {
@@ -197,7 +197,7 @@ export class HookServer implements HookEventSource {
     try {
       const request = parseRequest(line);
       if (request) {
-        const handler = this.#handlers.get(hashCwd(await canonicalize(request.event.cwd)));
+        const handler = this.#handlers.get(hashCwd(await canonicalize(request.routeCwd ?? request.event.cwd)));
         if (handler) reply = (await handler(request)) ?? {};
       }
     } catch {
@@ -243,6 +243,7 @@ function parseRequest(line: string): HookRelayRequest | undefined {
   const request = value as Partial<HookRelayRequest>;
   if (request.version !== 1) return undefined;
   if (typeof request.pid !== "number" || typeof request.ppid !== "number") return undefined;
+  if (request.routeCwd !== undefined && (typeof request.routeCwd !== "string" || !isAbsolute(request.routeCwd))) return undefined;
   const event = request.event as Partial<ClaudeHookEvent> | undefined;
   if (!event || typeof event !== "object") return undefined;
   if (typeof event.cwd !== "string" || !event.cwd) return undefined;

package/src/hooks/settings.ts

@@ -13,15 +13,20 @@ interface HookCommandEntry {
 
 export interface HookSettingsDocument {
   hooks: Record<ClaudeHookEventName, Array<{ hooks: HookCommandEntry[] }>>;
+  /**
+   * Off for a supervised session: a suggestion is ghost text in the input
+   * box, which reads as leftover input and holds every send back.
+   */
+  promptSuggestionEnabled: false;
 }
 
-/** A Claude Code settings document that runs `relayCommand` for every hook event the relay supports. */
+/** A Claude Code settings document for a supervised session: runs `relayCommand` for every hook event the relay supports. */
 export function hookSettingsDocument(relayCommand: string): HookSettingsDocument {
   const hooks = {} as HookSettingsDocument["hooks"];
   for (const name of HOOK_EVENT_NAMES) {
     hooks[name] = [{ hooks: [{ type: "command", command: relayCommand, timeout: HOOK_TIMEOUT_SECONDS }] }];
   }
-  return { hooks };
+  return { hooks, promptSuggestionEnabled: false };
 }
 
 /** Writes a standalone settings file (e.g. for `--settings <path>` on an owned interactive session). */

package/src/hooks/types.ts

@@ -59,6 +59,13 @@ export interface HookRelayRequest {
   ppid: number;
   /** Inherited from Claude's environment when it runs inside tmux. */
   tmuxPane?: string;
+  /**
+   * The canonical directory the relay routed by: Claude's `CLAUDE_PROJECT_DIR`
+   * when a Supervisor owns it, else the event's `cwd`. The server routes by
+   * this when present, so a Worker that `cd`s into a subdirectory stays
+   * supervised. Absent from older relays, which routed by `cwd`.
+   */
+  routeCwd?: string;
   event: ClaudeHookEvent;
 }
 
@@ -84,10 +91,11 @@ export const HOOK_TIMEOUT_SECONDS = 180;
 /**
  * Socket routing: one socket per Pi process under `<stateDir>/hooks/`, plus a
  * per-cwd symlink `<stateDir>/hooks/by-cwd/<sha256(cwd)>` created when the
- * Supervisor takes the cwd lease, so a relay only needs the cwd to find its
- * supervisor and a cwd with no supervisor is a no-op.
+ * Supervisor takes the cwd lease, so a relay only needs the task directory
+ * (Claude's `CLAUDE_PROJECT_DIR`, else the event's `cwd`) to find its
+ * supervisor and a directory with no supervisor is a no-op.
  */
 export interface HookEventSource {
-  /** Route every event whose canonical cwd matches to this handler until unsubscribed. */
+  /** Route every event whose canonical routing directory (`routeCwd`, else `event.cwd`) matches to this handler until unsubscribed. */
   subscribe(cwd: string, handler: (request: HookRelayRequest) => Promise<HookRelayReply | undefined>): Promise<() => Promise<void>>;
 }

package/src/index.ts

@@ -12,7 +12,7 @@ import { TmuxWorkerAdapter, attachCommand, sweepDeadTmuxSockets } from "./worker
 import { Supervisor, extendedDeadlineMs, type DecisionSessionClosedInfo, type HumanInterventionNotice, type SupervisorProgress, type SupervisorTokenUsage } from "./supervisor.ts";
 import { evaluateCommand } from "./policy.ts";
 import { HumanWebhookNotifier } from "./notifications.ts";
-import { autoInstallHooks, autonomyDefaults, closeWorkerOnCompletion, deadlineGraceMs, deadlineMs, deadlineWarningMs, decisionCompactionTokens, decisionModel, decisionSessionRetentionDays, eventLogMaxBytes, formatDurationMs, loadSupervisorEnvironment, noOutputTimeoutMs, parseDurationMs, progressHeartbeatMs, reviewTimeoutMs, reviewerModel, tmuxMode, workerAutocompactTokens, workerMcpConfigPath, workerModel } from "./config.ts";
+import { autoInstallHooks, autonomyDefaults, closeWorkerOnCompletion, deadlineGraceMs, deadlineMs, deadlineWarningMs, decisionCompactionTokens, decisionModel, decisionSessionRetentionDays, eventLogMaxBytes, formatDurationMs, humanIdleResumeMs, loadSupervisorEnvironment, noOutputTimeoutMs, parseDurationMs, progressHeartbeatMs, reviewTimeoutMs, reviewerModel, tmuxMode, workerAutocompactTokens, workerMcpConfigPath, workerModel } from "./config.ts";
 import { DecisionSessionStore, type DecisionSessionRecord } from "./decision-session-store.ts";
 import { CwdLeaseStore, type CwdLeaseHandle, leaseOwnerLive, pathsOverlap, workerIdentity } from "./cwd-lease.ts";
 import { normalizeTaskSpec } from "./acceptance.ts";
@@ -478,6 +478,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
                 deadlineGraceMs: deadlineGraceMs(),
                 deadlineWarningMs: deadlineWarningMs(),
                 noOutputTimeoutMs: noOutputTimeoutMs(),
+                humanIdleResumeMs: humanIdleResumeMs(),
                 hookSource: interactive ? hookServer : undefined,
                 hookSettingsPath,
                 keepWorkerOnCompletion: interactive ? !closeWorkerOnCompletion() : undefined,
@@ -825,6 +826,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
                 deadlineGraceMs: deadlineGraceMs(),
                 deadlineWarningMs: deadlineWarningMs(),
                 noOutputTimeoutMs: record.noOutputTimeoutMs,
+                humanIdleResumeMs: humanIdleResumeMs(),
                 startedAt: record.startedAt,
                 baseCommit: record.baseCommit,
                 baseBranch: record.baseBranch,