pi-claude-supervisor 0.9.0 → 0.9.2

package/src/supervisor.ts

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { EventLog, type SupervisorEvent } from "./events.ts";
 import { SupervisorStateMachine } from "./state.ts";
 import { evaluatePermission, isCommitId, isProtectedBranch, isRoutinePermission, publishCommand, pullRequestCommand, type PermissionPolicyOptions, type PolicyResult, type RemoteGrant } from "./policy.ts";
-import { PiDecisionWorker, type DecisionAction, type DecisionContext, type DecisionDeadlineContext, type DecisionWorkerFactory, type DecisionWorkerLike, type PiModel } from "./decision-worker.ts";
+import { PiDecisionWorker, STALE_VERIFICATION_TURNS, type DecisionAction, type DecisionContext, type DecisionDeadlineContext, type DecisionWorkerFactory, type DecisionWorkerLike, type PiModel } from "./decision-worker.ts";
 import { DEFAULT_DEADLINE_GRACE_MS, DEFAULT_DEADLINE_MS, DEFAULT_DEADLINE_WARNING_MS, DEFAULT_NO_OUTPUT_TIMEOUT_MS, formatDurationMs } from "./config.ts";
 import { collectRepositoryEvidence, remoteBranchHead, remoteUrl, runReadOnly, repositoryBranch, repositoryCommitExists, repositoryHead, repositoryIsAncestor, repositoryWorkTree, verifyAll, repositoryClean, repositoryGitDirectoryIsLocal, repositorySlug, sameDestination, type RemoteBranchLookup, type RemoteDestination, type RepositoryEvidence, type VerificationCommand } from "./verifier.ts";
 import { normalizeTaskSpec } from "./acceptance.ts";
@@ -214,11 +214,17 @@ export class Supervisor {
   #lastObservedBranch?: string;
   #handle?: WorkerHandle;
   #lastVerification?: AcceptanceReport;
+  /** The Worker turn the last verification judged; later turns are not reflected in it. */
+  #lastVerificationTurn?: number;
+  /** Set when a Decision Worker `stop` became a verification: no repair turn may follow it. */
+  #stopVerification?: string;
   #workerOutput = "";
   #lastWorkerResult?: Record<string, unknown>;
   #lastTurnCompleted?: WorkerEvent;
   /** Key of the completed turn whose decision is still in flight; the deadline must not verify underneath it. */
   #pendingDecisionKey?: string;
+  /** When the pending decision was requested; bounds how long an idle timeout defers to it. */
+  #pendingDecisionSince = 0;
   /**
    * Publish phase. Authority exists only between "acceptance and Reviewer
    * passed" and "the publish turn completed", and only for `#verifiedHead` on
@@ -275,6 +281,7 @@ export class Supervisor {
   #usageRecordedEvents = new Set<string>();
   #pendingPermissions = new Map<string, WorkerPermissionRequest>();
   #humanRequired = false;
+  #watchdogTickPending = false;
   #humanGate: "permission" | "other" | undefined;
   #candidateParked = false;
   #stopRequested?: string;
@@ -315,6 +322,9 @@ export class Supervisor {
   get task() { return this.#task; }
   get handle() { return this.#handle; }
   get lastVerification() { return this.#lastVerification; }
+  /** Worker turns sent so far (the task's own opening turn is 0). */
+  get turn() { return this.#turn; }
+  get repairRound() { return this.#repairRound; }
   /** True only after an explicit takeover, never for ordinary uncertainty. */
   get humanRequired() { return this.#humanRequired; }
   get candidateParked() { return this.#candidateParked; }
@@ -346,6 +356,8 @@ export class Supervisor {
     this.#handle = undefined;
     this.#lastObservedBranch = undefined;
     this.#lastVerification = undefined;
+    this.#lastVerificationTurn = undefined;
+    this.#stopVerification = undefined;
     this.#workerOutput = "";
     this.#lastWorkerResult = undefined;
     this.#lastTurnCompleted = undefined;
@@ -1076,6 +1088,8 @@ export class Supervisor {
       }
       if (action.action === "continue" || action.action === "redirect" || action.action === "answer") {
         if (await this.#decisionIsStale(event)) return;
+        if (await this.#verifyOnTurnBudget(handle, event, action)) return;
+        if (await this.#verifyStaleFailure(handle, event, action)) return;
         await this.#sendInternal(action.message);
         return;
       }
@@ -1106,6 +1120,10 @@ export class Supervisor {
         return;
       }
       if (action.action === "verify") {
+        // Background work can re-invoke the Worker while this decision was in
+        // flight; verifying then would judge a tree that is still changing
+        // and stop a busy Worker. Its next completed turn is decided afresh.
+        if (await this.#decisionIsStale(event)) return;
         await this.#startVerification(handle, event, "Decision Worker");
         return;
       }
@@ -1125,17 +1143,81 @@ export class Supervisor {
         return;
       }
       if (action.action === "stop") {
+        if (await this.#verifyStop(handle, event, action)) return;
         await this.#stopInternal(`Decision Worker: ${action.reason}`);
         return;
       }
       if (action.action === "retry") {
-        if (!action.message?.trim()) { await this.#parkCandidate(`Retry requires a concrete corrective instruction: ${action.reason}`, event); return; }
+        // The prompt invites a bare retry after a Worker API error; resume the
+        // turn rather than parking a task over a single transient failure.
+        const message = action.message?.trim() ? action.message : RETRY_RESUME_MESSAGE;
         if (await this.#decisionIsStale(event)) return;
-        await this.#sendInternal(action.message);
+        if (await this.#verifyOnTurnBudget(handle, event, action)) return;
+        if (await this.#verifyStaleFailure(handle, event, action)) return;
+        await this.#sendInternal(message);
       }
     });
   }
 
+  /**
+   * The turn budget is spent: another message would only throw (and park the
+   * task as a "Decision Worker failure"). Judge the work that exists instead.
+   */
+  async #verifyOnTurnBudget(handle: WorkerHandle, event: WorkerEvent, action: DecisionAction): Promise<boolean> {
+    const maxTurns = this.#task?.maxTurns ?? 100;
+    if (this.#turn + 1 <= maxTurns) return false;
+    await this.#appendEvent({ type: "decision_overridden", taskId: this.#task?.taskId, workerId: handle.id, data: { action: action.action, override: "verify", reason: `turn budget of ${maxTurns} is exhausted`, eventType: event.type } }).catch(() => {});
+    await this.#startVerification(handle, event, "turn budget");
+    return true;
+  }
+
+  /**
+   * A verification failed and the Worker has since taken several turns with
+   * no new one: judge the work as it is now instead of sending more guidance
+   * based on the old failure. Another failure goes through the ordinary
+   * repair-round budget, so a stuck task parks instead of running to its
+   * deadline.
+   */
+  async #verifyStaleFailure(handle: WorkerHandle, event: WorkerEvent, action: DecisionAction): Promise<boolean> {
+    if (event.type !== "turn_completed" || !this.#lastVerification || this.#lastVerification.ok || this.#lastVerificationTurn === undefined) return false;
+    // A turn cut short by the Worker's own API error is half-done work: let
+    // the Decision Worker resume it rather than judging it.
+    if (event.result.is_error === true || event.result.subtype === "error") return false;
+    const turnsSince = this.#turn - this.#lastVerificationTurn;
+    if (turnsSince < STALE_VERIFICATION_TURNS) return false;
+    await this.#appendEvent({ type: "decision_overridden", taskId: this.#task?.taskId, workerId: handle.id, data: { action: action.action, override: "verify", reason: `${turnsSince} Worker turns since the last failed verification`, eventType: event.type } }).catch(() => {});
+    await this.#startVerification(handle, event, "stale failed verification");
+    return true;
+  }
+
+  /**
+   * An unattended `stop` on a finished turn: models reach for it when they
+   * believe the work is done, and a plain stop would end the task unverified
+   * with its work unreported. The stop still happens first — the Worker is
+   * stopped and never kept open — and then its finished work is judged
+   * (acceptance and the Reviewer only read): a failure blocks the candidate
+   * rather than starting a repair round. A stop elsewhere (a pending
+   * permission, a turn the Worker has already resumed) or on a task that may
+   * publish stays a plain stop.
+   */
+  async #verifyStop(handle: WorkerHandle, event: WorkerEvent, action: DecisionAction): Promise<boolean> {
+    const task = this.#task;
+    if (!task || !this.#automation || this.#humanRequired || event.type !== "turn_completed" || this.#machine.state !== "waiting") return false;
+    if (task.spec.autonomy.remoteAuthority !== "none") return false;
+    if (await this.#decisionIsStale(event)) return false;
+    this.#stopVerification = action.reason;
+    await this.#appendEvent({ type: "decision_overridden", taskId: task.taskId, workerId: handle.id, data: { action: action.action, override: "verify", reason: "the Worker is stopped and its finished work verified before the task ends; no further Worker turns", decisionReason: action.reason, eventType: event.type } }).catch(() => {});
+    await this.#adapter.stop(handle, `Decision Worker: ${action.reason}`);
+    await this.#pollInternal(true);
+    // Re-read after the awaits: the poll moves the stopped Worker on.
+    const after: string = this.#machine.state;
+    // An operator stop arrived meanwhile: it owns the outcome ("stopped").
+    if (this.#stopRequested !== undefined) return true;
+    if (after === "verifying") await this.#verifyInternal();
+    else await this.#parkCandidate(`Decision Worker stop left the task in state ${after} before verification`, event);
+    return true;
+  }
+
   /**
    * Move an idle Worker into verification the way a `verify` decision does:
    * in place when the transport supports it, otherwise by stopping the
@@ -1163,7 +1245,10 @@ export class Supervisor {
     // nothing must be marked as pending on its account.
     if (replay && !this.#decision.replay) return;
     this.#decision.updateContext(this.#decisionContextPatch());
-    if (event.type === "turn_completed") this.#pendingDecisionKey = workerEventKey(event);
+    if (event.type === "turn_completed") {
+      this.#pendingDecisionKey = workerEventKey(event);
+      this.#pendingDecisionSince = Date.now();
+    }
     if (replay) this.#decision.replay!(event);
     else this.#decision.notify(event);
   }
@@ -1379,6 +1464,10 @@ export class Supervisor {
     const nextTurn = this.#turn + 1;
     if (nextTurn > (this.#task?.maxTurns ?? 100)) throw new Error("supervisor turn budget exhausted");
     await this.#adapter.send(handle, message, `${taskId}:turn:${nextTurn}`);
+    // The silence being timed starts now, not at the Worker's last output: a
+    // repair or publish turn follows an acceptance/Review run that can easily
+    // outlast the no-output timeout on its own.
+    this.#noOutputBaselineAt = Date.now();
     this.#turn = nextTurn;
     if (this.#machine.state === "waiting") this.#machine.transition("running");
     await this.#appendEvent({ type: "worker_message_sent", taskId, workerId: handle.id, idempotencyKey: `${taskId}:turn:${this.#turn}`, data: { message } });
@@ -1603,6 +1692,7 @@ export class Supervisor {
     if (!this.#task) throw new Error("no active task");
     if (this.#machine.state === "waiting" && canRepairInPlace(this.#adapter)) this.#machine.transition("verifying");
     if (this.#machine.state !== "verifying") throw new Error(`cannot verify from ${this.#machine.state}`);
+    this.#lastVerificationTurn = this.#turn;
     const verificationAbortController = new AbortController();
     this.#verificationAbortController = verificationAbortController;
 
@@ -1757,6 +1847,9 @@ export class Supervisor {
       this.#reportProgress("review", "collecting repository evidence and running independent Reviewer", true);
       let review: ReviewReport;
       let reviewUsageReceived = false;
+      // Until this round finishes, #lastVerification still holds the round
+      // whose findings the Worker was just asked to repair.
+      const previousFindings = this.#repairRound > 0 ? this.#lastVerification?.review?.findings : undefined;
       try {
         const evidence = repositoryEvidence ?? redactRepositoryEvidence(await collectRepositoryEvidence(this.#task.cwd, { signal: verificationAbortController.signal, baseRef: this.#task.baseCommit }));
         judgedEvidence = evidence;
@@ -1769,6 +1862,7 @@ export class Supervisor {
           workerOutput: String(redactSensitive(this.#workerOutput)),
           workerResult: this.#lastWorkerResult ? redactSensitive(this.#lastWorkerResult) as Record<string, unknown> : undefined,
           round: this.#repairRound,
+          ...(previousFindings?.length ? { previousFindings } : {}),
           signal: verificationAbortController.signal,
           onUsage: (sample) => { reviewUsageReceived = true; this.#recordPiUsage(sample); },
         } satisfies ReviewInput), this.#reviewTimeoutMs + 30_000, "independent Reviewer", verificationAbortController.signal);
@@ -1781,8 +1875,12 @@ export class Supervisor {
         if (error instanceof Error && error.name === "TimeoutError") verificationAbortController.abort(error.message);
         review = { verdict: "human" as const, summary: `independent Reviewer failed: ${safeMessage(error)}`, findings: [], round: this.#repairRound, checkedAt: new Date().toISOString() };
       }
+      // A P0/P1 finding blocks a pass, but it is a repair input like any other
+      // concrete finding: the bounded repair loop is where serious, fixable
+      // defects get fixed. Only a `human` verdict (or an exhausted/repeating
+      // repair loop) parks the candidate.
       const hasBlockingFinding = review.findings.some((finding) => finding.severity === "P0" || finding.severity === "P1");
-      if (hasBlockingFinding) review = { ...review, verdict: "human" as const, summary: `${review.summary}; blocking findings require human review` };
+      if (hasBlockingFinding && review.verdict === "pass") review = { ...review, verdict: "revise" as const, summary: `${review.summary}; blocking findings must be repaired before the candidate can pass` };
       if (review.verdict === "revise") {
         const signature = findingSignature(review);
         if (signature === this.#lastFindingSignature) {
@@ -2153,6 +2251,10 @@ export class Supervisor {
     const task = this.#task;
     const handle = this.#handle;
     if (!task || !this.#automation || this.#humanRequired) return false;
+    if (this.#stopVerification !== undefined) {
+      await this.#appendEvent({ type: "candidate_blocked", taskId: task.taskId, workerId: handle?.id, data: { reason: `${reason}; the Decision Worker chose stop, so no repair round is sent` } });
+      return false;
+    }
     if (this.#repairRound >= task.spec.maxRepairRounds) {
       await this.#appendEvent({ type: "repair_round_exhausted", taskId: task.taskId, workerId: handle?.id, data: { maxRepairRounds: task.spec.maxRepairRounds, reason } });
       await this.#appendEvent({ type: "candidate_blocked", taskId: task.taskId, workerId: handle?.id, data: { reason: `${reason}; automatic repair budget is exhausted` } });
@@ -2222,7 +2324,7 @@ export class Supervisor {
     // A completed interactive task may keep its persistent session open for
     // the operator instead of tearing it down; a stop requested mid-verify or
     // a blocked/failed outcome always falls back to today's stop behavior.
-    const keepOpen = !stopRequested && outcome === "completed" && result.ok
+    const keepOpen = !stopRequested && this.#stopVerification === undefined && outcome === "completed" && result.ok
       && this.#keepWorkerOnCompletion && Boolean(this.#adapter.release) && Boolean(this.#handle);
     let cleanupError: unknown;
     let releasedInteractive = false;
@@ -2373,7 +2475,16 @@ export class Supervisor {
 
   #armWatchdog(): void {
     if (!this.#automation && this.#deadlineMs <= 0 && this.#noOutputTimeoutMs <= 0) return;
-    this.#watchdog = setInterval(() => { void this.#checkWatchdog().catch(() => { /* lifecycle state is retained for the next explicit operation */ }); }, 1_000);
+    // One tick at a time: a tick queues behind #exclusive, so while a long
+    // acceptance/Review run holds it, un-guarded ticks would pile up by the
+    // thousand and then all run back to back.
+    this.#watchdog = setInterval(() => {
+      if (this.#watchdogTickPending) return;
+      this.#watchdogTickPending = true;
+      void this.#checkWatchdog()
+        .catch(() => { /* lifecycle state is retained for the next explicit operation */ })
+        .finally(() => { this.#watchdogTickPending = false; });
+    }, 1_000);
     this.#watchdog.unref();
   }
 
@@ -2428,7 +2539,9 @@ export class Supervisor {
     // for the grace period as well (an empty grace keeps the old immediate stop).
     const reason = deadlineReached && elapsed >= this.#deadlineMs + this.#deadlineGraceMs
       ? "worker deadline exceeded"
-      : this.#machine.state !== "paused" && this.#noOutputTimeoutMs > 0 && now - lastOutputAt >= this.#noOutputTimeoutMs
+      // Under human takeover (including every recovered task until
+      // resume-auto) an idle Worker is waiting for the operator, not stuck.
+      : this.#machine.state !== "paused" && !this.#humanRequired && this.#noOutputTimeoutMs > 0 && now - lastOutputAt >= this.#noOutputTimeoutMs
         ? "worker produced no output before timeout"
         : undefined;
     if (!reason) {
@@ -2438,6 +2551,40 @@ export class Supervisor {
       }
       return;
     }
+    // An *idle* automatic Worker that stayed silent is not hung: it finished a
+    // turn and is waiting (typically on background work that never came
+    // back). Judge the work instead of killing it and discarding the chance
+    // of a candidate; a Worker silent in the middle of a turn is still stopped.
+    // A Worker that never completed a turn under this Supervisor (recovered,
+    // or adopted) still reads `running`; classify it first, as the close-out does.
+    if (reason === "worker produced no output before timeout" && this.#automation && this.#machine.state === "running" && !status.activeRequests) {
+      await this.#pollInternal();
+      // The Worker exited in between: the poll has already classified it.
+      // As at the top of this function, a classified exit is verified here
+      // too, in case its `exited` event (which normally drives it) was lost.
+      const polled: string = this.#machine.state;
+      if (polled !== "running" && polled !== "waiting") {
+        if (polled === "verifying" && !this.#verificationAbortController) {
+          try {
+            await this.#verifyInternal();
+          } catch (error) {
+            await this.#appendEvent({ type: "worker_event_error", taskId, workerId, data: { error: safeMessage(error), eventType: "watchdog_verify" } }).catch(() => {});
+          }
+        }
+        return;
+      }
+    }
+    if (reason === "worker produced no output before timeout" && this.#automation && this.#machine.state === "waiting" && !status.activeRequests) {
+      // A decision about this idle Worker is still being made (it may be
+      // backing off a provider outage); let it land rather than race it —
+      // but not forever: one that has not landed within another timeout
+      // period never will.
+      if (this.#pendingDecisionKey && now - this.#pendingDecisionSince < this.#noOutputTimeoutMs) return;
+      this.#clearWaitTimer();
+      await this.#appendEvent({ type: "worker_idle_timeout", taskId, workerId, data: { reason, action: "verify", noOutputTimeoutMs: this.#noOutputTimeoutMs } }).catch(() => {});
+      await this.#startVerification(this.#handle, this.#lastTurnCompleted, "no-output timeout");
+      return;
+    }
     // A close-out window that was skipped entirely (a task recovered past its
     // budget) still leaves the deadline notice ahead of the stop in the log.
     if (deadlineReached && this.#deadlineGraceMs > 0) await this.#noteDeadlineReached(elapsed).catch(() => {});
@@ -2486,7 +2633,17 @@ export class Supervisor {
   /** The per-event context refresh sent to the Decision Worker before every notification or replay. */
   #decisionContextPatch(): Partial<DecisionContext> {
     const deadline = this.#deadlineContext();
-    return { state: this.#machine.state, turn: this.#turn, repairRound: this.#repairRound, ...(deadline ? { deadline } : {}) };
+    const verification = this.#lastVerification;
+    // The Worker's own repair prompt carries these; without them the Decision
+    // Worker judges a repair turn only by Claude's claim that it is done.
+    const lastVerification = verification ? {
+      ok: verification.ok,
+      ...(this.#lastVerificationTurn !== undefined ? { atTurn: this.#lastVerificationTurn } : {}),
+      failedChecks: verification.checks.filter((check) => check.check.required && !check.ok).map((check) => check.check.id).slice(0, 16),
+      ...(verification.review ? { reviewVerdict: verification.review.verdict } : {}),
+      findings: bySeverity(verification.review?.findings ?? []).slice(0, 8).map((finding) => `${finding.id} [${finding.severity}] ${finding.message}`.slice(0, 200)),
+    } : undefined;
+    return { state: this.#machine.state, turn: this.#turn, repairRound: this.#repairRound, ...(deadline ? { deadline } : {}), ...(lastVerification ? { lastVerification } : {}) };
   }
 
   /**
@@ -2823,11 +2980,13 @@ function removeFlagWithValue(args: readonly string[], flag: string): string[] {
 /**
  * The deadline (in ms since the task started) that grants `extendMs` more
  * from now: measured from the later of the current deadline and the present,
- * so extending an expired task by 30 minutes means 30 minutes from now, and
- * extending by 0 opens its close-out immediately.
+ * so extending an expired task by 30 minutes means 30 minutes from now.
+ * Extending by 0 means "close out now" for any task, expired or not: the
+ * deadline lands on the present so the close-out opens at once.
  */
 export function extendedDeadlineMs(currentDeadlineMs: number, elapsedMs: number, extendMs: number): number {
-  return Math.max(currentDeadlineMs, elapsedMs) + Math.max(0, extendMs);
+  if (extendMs <= 0) return elapsedMs;
+  return Math.max(currentDeadlineMs, elapsedMs) + extendMs;
 }
 
 function canRepairInPlace(adapter: WorkerAdapter): boolean {
@@ -2905,15 +3064,37 @@ function cancelledAcceptanceReport(reason: string): AcceptanceReport {
   };
 }
 
+function tailText(value: string, maxChars: number): string {
+  return value.length <= maxChars ? value : `[…${value.length - maxChars} earlier characters omitted]\n${value.slice(-maxChars)}`;
+}
+
+const RETRY_RESUME_MESSAGE = "Your previous turn stopped before finishing. Resume the task where you left off.";
+
+/** Findings with the most severe first, keeping the Reviewer's order within a severity. */
+function bySeverity<T extends { severity: string }>(findings: readonly T[]): T[] {
+  const rank = (severity: string) => { const at = ["P0", "P1", "P2", "P3"].indexOf(severity); return at === -1 ? 4 : at; };
+  return [...findings].sort((a, b) => rank(a.severity) - rank(b.severity));
+}
+
 function repairInstruction(result: AcceptanceReport, reason: string, round: number): string {
+  // Each check keeps the *end* of its output: that is where test runners
+  // print the failure summary, while the head is usually progress noise.
   const failedChecks = result.checks
     .filter((check) => check.check.required && !check.ok)
-    .map((check) => `${check.check.id}: ${check.output}`)
+    .map((check) => `${check.check.id}: ${tailText(check.output, 4_000)}`)
     .join("\n");
-  const findings = result.review?.findings
-    .map((finding) => `${finding.id} [${finding.severity}] ${finding.message}${finding.requiredFix ? `; required fix: ${finding.requiredFix}` : ""}`)
+  // Findings carry their location and evidence: they are what points the
+  // Worker at the fix. They go first so the 16 KB bound never cuts them, and
+  // the most severe lead, so long lesser findings cannot crowd out a P0.
+  const findings = bySeverity(result.review?.findings ?? [])
+    .map((finding) => {
+      const location = finding.file ? ` ${finding.file}${finding.line ? `:${finding.line}` : ""}` : "";
+      const fix = finding.requiredFix ? `; required fix: ${finding.requiredFix}` : "";
+      const evidence = finding.evidence ? `; evidence: ${tailText(finding.evidence, 1_000)}` : "";
+      return `${finding.id} [${finding.severity}]${location}: ${finding.message}${fix}${evidence}`;
+    })
     .join("\n") ?? "";
-  const evidence = [failedChecks ? `Failed acceptance checks:\n${failedChecks}` : "", findings ? `Reviewer findings:\n${findings}` : ""].filter(Boolean).join("\n\n");
+  const evidence = [findings ? `Reviewer findings:\n${findings}` : "", failedChecks ? `Failed acceptance checks:\n${failedChecks}` : ""].filter(Boolean).join("\n\n");
   const commitRequirement = reason.includes("local commit") || reason.includes("uncommitted")
     ? "Before reporting completion, inspect the final diff, run the relevant checks, and create a local git commit on the task branch. Do not push, merge, publish, or modify main/integration."
     : "";

package/src/worker/process-adapter.ts

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { spawn, type ChildProcess } from "node:child_process";
 import { constants as fsConstants, readFileSync } from "node:fs";
-import { access, mkdir, readFile, readdir, rmdir, stat, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, readdir, rmdir, stat, statfs, writeFile } from "node:fs/promises";
 import { delimiter, isAbsolute, join } from "node:path";
 import type {
   WorkerAdapter,
@@ -59,6 +59,8 @@ interface ProcessRecord {
   seenResultIds: Set<string>;
   seenPermissionRequestIds: Set<string>;
   protocolBuffer: string;
+  /** Byte length of protocolBuffer, kept incrementally so a long line is not re-measured per chunk. */
+  protocolBufferBytes: number;
   discardProtocolLine: boolean;
   exitCode?: number | null;
   signal?: NodeJS.Signals;
@@ -114,7 +116,11 @@ export class ProcessWorkerAdapter implements WorkerAdapter {
     this.#killGraceMs = boundedDelay(options.killGraceMs ?? 500);
     this.#maxOutputChunks = boundedPositiveInteger(options.maxOutputChunks ?? 10_000, "maxOutputChunks");
     this.#maxOutputBytes = boundedPositiveInteger(options.maxOutputBytes ?? 8 * 1024 * 1024, "maxOutputBytes");
-    this.#maxProtocolBufferBytes = boundedPositiveInteger(options.maxProtocolBufferBytes ?? 256 * 1024, "maxProtocolBufferBytes");
+    // One JSONL record, not the stream: a permission request for a Write of a
+    // large file, or a long final result, is a single line. A dropped
+    // control_request leaves Claude waiting forever for its answer and a
+    // dropped result never ends the turn, so the bound only guards memory.
+    this.#maxProtocolBufferBytes = boundedPositiveInteger(options.maxProtocolBufferBytes ?? 32 * 1024 * 1024, "maxProtocolBufferBytes");
     this.#inputWriteTimeoutMs = boundedDelay(options.inputWriteTimeoutMs ?? 10_000);
     this.#cgroupMode = options.cgroupMode ?? "auto";
     this.#cgroupParentPath = options.cgroupParentPath;
@@ -258,6 +264,7 @@ export class ProcessWorkerAdapter implements WorkerAdapter {
       seenResultIds: new Set(),
       seenPermissionRequestIds: new Set(),
       protocolBuffer: "",
+      protocolBufferBytes: 0,
       discardProtocolLine: false,
       exited,
       resolveExit,
@@ -300,6 +307,12 @@ export class ProcessWorkerAdapter implements WorkerAdapter {
       this.#emit(record, { type: "output", handle: record.handle, chunk: outputChunk });
       if (stream === "stdout" && this.#mode === "claude-jsonl") this.#observeJsonl(record, text);
     };
+    // A stream decoder keeps a multi-byte character that straddles two pipe
+    // reads intact; String(buffer) per chunk turned it into U+FFFD, and a
+    // permission `updatedInput` echoed back from that text then wrote the
+    // corruption into the Worker's files.
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
     child.stdout?.on("data", capture("stdout"));
     child.stderr?.on("data", capture("stderr"));
     child.stdin?.on("error", (error) => {
@@ -602,28 +615,33 @@ export class ProcessWorkerAdapter implements WorkerAdapter {
         if (newline < 0) return;
         record.discardProtocolLine = false;
         record.protocolBuffer = "";
+        record.protocolBufferBytes = 0;
         offset = newline + 1;
         continue;
       }
       const newline = chunk.indexOf("\n", offset);
       if (newline < 0) {
         const tail = chunk.slice(offset);
-        if (Buffer.byteLength(record.protocolBuffer, "utf8") + Buffer.byteLength(tail, "utf8") > this.#maxProtocolBufferBytes) {
+        const tailBytes = Buffer.byteLength(tail, "utf8");
+        if (record.protocolBufferBytes + tailBytes > this.#maxProtocolBufferBytes) {
           record.protocolBuffer = "";
+          record.protocolBufferBytes = 0;
           record.discardProtocolLine = true;
           record.outputTruncated = true;
         } else {
           record.protocolBuffer += tail;
+          record.protocolBufferBytes += tailBytes;
         }
         return;
       }
       const linePart = chunk.slice(offset, newline);
-      if (Buffer.byteLength(record.protocolBuffer, "utf8") + Buffer.byteLength(linePart, "utf8") > this.#maxProtocolBufferBytes) {
+      if (record.protocolBufferBytes + Buffer.byteLength(linePart, "utf8") > this.#maxProtocolBufferBytes) {
         record.outputTruncated = true;
       } else {
         this.#processJsonlLine(record, `${record.protocolBuffer}${linePart}`.trim());
       }
       record.protocolBuffer = "";
+      record.protocolBufferBytes = 0;
       offset = newline + 1;
     }
   }
@@ -983,10 +1001,24 @@ async function assertExecutable(command: string, pathValue: string | undefined):
   throw new Error(`worker executable preflight failed (ENOENT): ${command}`);
 }
 
+/** statfs(2) f_type of a cgroup v2 mount (CGROUP2_SUPER_MAGIC). */
+const CGROUP2_SUPER_MAGIC = 0x63677270;
+
 export async function currentCgroupPath(): Promise<string> {
   const contents = await readFile("/proc/self/cgroup", "utf8");
   const match = contents.match(/^0::([^\n]*)$/mu);
   if (!match) throw new Error("cgroup v2 is not active");
+  // A hybrid (v1 + v2) host also lists a `0::` line, but its unified
+  // hierarchy is not mounted at /sys/fs/cgroup — that is a tmpfs holding the
+  // v1 controllers. Creating a "cgroup" there only makes an ordinary directory
+  // with no controls, so require the real cgroup2 filesystem first.
+  let type: number;
+  try {
+    type = (await statfs("/sys/fs/cgroup")).type;
+  } catch (error) {
+    throw new Error(`cgroup v2 is not mounted at /sys/fs/cgroup: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+  if (type !== CGROUP2_SUPER_MAGIC) throw new Error("cgroup v2 is not mounted at /sys/fs/cgroup (a cgroup v1 or hybrid host)");
   // /proc/self/cgroup uses the same escaped component spelling as the cgroup
   // filesystem (for example, a literal `\\x2d` in a systemd scope name).
   return `/sys/fs/cgroup${match[1]}`;
@@ -1043,7 +1075,10 @@ export async function preflightCgroupContainment(parentPath?: string): Promise<v
     throw new Error(`required cgroup preflight failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
   } finally {
     if (probePath) {
-      try { await writeFile(`${probePath}/cgroup.kill`, "1" + String.fromCharCode(10)); } catch {}
+      // O_WRONLY without O_CREAT: kill through an existing control file only.
+      // The default `w` flag would create a regular file in a directory that
+      // turned out not to be a cgroup, and that file then blocks its rmdir.
+      try { await writeFile(`${probePath}/cgroup.kill`, "1" + String.fromCharCode(10), { flag: fsConstants.O_WRONLY }); } catch {}
     }
     const child = probeChild;
     if (child && child.exitCode === null) {