agent-accelerator 0.5.1 → 0.5.3

package/src/tools/executor.ts

@@ -9,6 +9,7 @@ import { ConfigError } from "../types/errors.ts";
 import { isSubagentResult } from "./subagent-result.ts";
 import { isTruncatedArguments } from "../types/tool.ts";
 import { telemetryBus } from "../telemetry.ts";
+import type { ToolLogWriter } from "../session/tool-log.ts";
 
 export interface ExecuteToolsOptions {
   tools: Record<string, ToolDefinition>;
@@ -17,6 +18,10 @@ export interface ExecuteToolsOptions {
   parallel?: boolean;
   signal?: AbortSignal;
   sessionId?: string;
+  /** Called the moment EACH call finishes (before the whole batch does), so a caller can save a result before the next tool is done. Never throws into the run. */
+  onResult?: (result: ToolResultRecord) => void;
+  /** Opens the log file of one call (only when the Agent persists to a folder); the executor writes its steps into it and `ctx.log` writes through it. */
+  openToolLog?: (call: ToolCallRecord, sessionId: string | undefined) => ToolLogWriter | undefined;
   /** Forwards live sub-agent deltas (realtime worker thinking/text) to the caller. */
   onSubagentEvent?: (event: { trackingId: string; delta?: string; thinkingDelta?: string; partialText?: string; partialThinking?: string }) => void;
 }
@@ -52,6 +57,14 @@ export function normalizeToolName(name: string): string {
     .toLowerCase();
 }
 
+// Thrown by `ctx.stop(reason)` to unwind the tool's code at once; the executor turns it into a stopped result and never retries it.
+class ToolStopSignal extends Error {
+  constructor() {
+    super("The tool ended the run with ctx.stop()");
+    this.name = "ToolStopSignal";
+  }
+}
+
 /** Default cap for string tool results kept for model context. */
 export const DEFAULT_MAX_RESULT_CHARS = 20000;
 
@@ -467,7 +480,7 @@ async function executeAttempt(
 export async function executeToolCalls(
   options: ExecuteToolsOptions
 ): Promise<ToolResultRecord[]> {
-  const { tools, toolCalls, agentName, parallel = true, signal, sessionId, onSubagentEvent } = options;
+  const { tools, toolCalls, agentName, parallel = true, signal, sessionId, onSubagentEvent, onResult, openToolLog } = options;
   assertNoToolCollisions(tools);
   const globalSemaphore = new Semaphore(DEFAULT_TOOL_CONCURRENCY);
   const perToolSemaphores = new Map<string, Semaphore>();
@@ -485,8 +498,14 @@ export async function executeToolCalls(
   };
 
   const scope = { agentName, sessionId };
-  const runSingle = async (call: ToolCallRecord): Promise<ToolResultRecord> => {
+  const runSingle = async (call: ToolCallRecord, log: ToolLogWriter | undefined): Promise<ToolResultRecord> => {
     const startTime = nowMs();
+    // Every lifecycle step goes to the telemetry bus AND this call's log file.
+    const trace = (phase: string, level: "info" | "warn" | "error", data: Record<string, unknown> = {}): void => {
+      traceToolEvent(phase, level, call, scope, data);
+      log?.write({ phase, level, ...data });
+    };
+    log?.write({ phase: "input", name: call.name, input: toJsonSafe(call.arguments) });
     // Latest `ctx.emit({ type: "progress", ... })` snapshot: what the tool had finished before any failure.
     let progress: unknown;
     let attempts = 0;
@@ -497,7 +516,7 @@ export async function executeToolCalls(
     // finishReason here — return a synthetic error so the model retries with
     // complete JSON.
     if (isTruncatedToolCall(call)) {
-      traceToolEvent("call_blocked", "warn", call, scope, { reason: "truncated_arguments" });
+      trace("call_blocked", "warn", { reason: "truncated_arguments" });
       return {
         id: call.id,
         name: call.name,
@@ -513,7 +532,7 @@ export async function executeToolCalls(
     const toolDef = resolved.definition;
 
     if (!toolDef) {
-      traceToolEvent("call_blocked", "warn", call, scope, { reason: "tool_not_found", suggestion: resolved.suggestion });
+      trace("call_blocked", "warn", { reason: "tool_not_found", suggestion: resolved.suggestion });
       const suffix = resolved.suggestion ? ` Did you mean '${resolved.suggestion}'?` : "";
       return {
         id: call.id,
@@ -527,6 +546,12 @@ export async function executeToolCalls(
     let releaseGlobal: (() => void) | undefined;
     let releaseTool: (() => void) | undefined;
     let executionStartTime = startTime;
+    // Set by `ctx.stop(reason)`: the call's result becomes the reason and the run ends after this batch.
+    let stopReason: string | undefined;
+    const stoppedResult = (): ToolResultRecord => {
+      trace("call_stopped", "warn", { reason: stopReason, attempts, durationMs: elapsedMs(executionStartTime) });
+      return { id: call.id, name: resolved.name, result: stopReason, isError: false, stopped: true, durationMs: elapsedMs(executionStartTime) };
+    };
 
     try {
       if (signal?.aborted) {
@@ -542,9 +567,14 @@ export async function executeToolCalls(
         signal,
         sessionId,
         onSubagentEvent,
+        stop: (reason: string): never => {
+          stopReason ??= String(reason);
+          throw new ToolStopSignal();
+        },
+        log: (message, data) => log?.write({ phase: "log", message, ...(data !== undefined ? { data: toJsonSafe(data) } : {}) }),
         emit: (event) => {
           if (event?.type === "progress") progress = event;
-          traceToolEvent(event?.type === "progress" ? "progress" : "event", "info", call, scope, { event: capJson(event) });
+          trace(event?.type === "progress" ? "progress" : "event", "info", { event: capJson(event) });
         },
       };
 
@@ -565,7 +595,7 @@ export async function executeToolCalls(
           const hint = expectedParams
             ? ` Expected parameters: ${expectedParams}.`
             : "";
-          traceToolEvent("call_blocked", "warn", call, scope, { reason: "schema_validation", detail: parseRes.error.message });
+          trace("call_blocked", "warn", { reason: "schema_validation", detail: parseRes.error.message });
           return {
             id: call.id,
             name: call.name,
@@ -597,20 +627,21 @@ export async function executeToolCalls(
       executionStartTime = nowMs();
       let rawResult: unknown;
       let attempt = 0;
-      traceToolEvent("call_started", "info", call, scope, { maxAttempts, timeoutMs });
+      trace("call_started", "info", { maxAttempts, timeoutMs });
       while (true) {
         attempt++;
         attempts = attempt;
-        traceToolEvent("attempt_started", "info", call, scope, { attempt, maxAttempts });
+        trace("attempt_started", "info", { attempt, maxAttempts });
         try {
           rawResult = await executeAttempt(toolDef, parsedInput, context, timeoutMs);
           break;
         } catch (err: any) {
           if (signal?.aborted) throw new Error("Tool execution aborted");
+          if (stopReason !== undefined) throw err; // ctx.stop: not a failure, never retried
           timedOut = err?.toolTimeout === true;
           const willRetry =
             isTransientError(err) && attempt < maxAttempts && !(err?.code === "ETIMEDOUT" && (!configuredTries || configuredTries <= 0));
-          traceToolEvent("attempt_failed", "warn", call, scope, { attempt, maxAttempts, willRetry, error: describeError(err), progress: capJson(progress) });
+          trace("attempt_failed", "warn", { attempt, maxAttempts, willRetry, error: describeError(err), progress: capJson(progress) });
           if (!isTransientError(err) || attempt >= maxAttempts) throw err;
           // A timeout is a deliberate per-attempt deadline, not a parent
           // cancellation (which rejects via the abort signal instead and is
@@ -620,15 +651,19 @@ export async function executeToolCalls(
           // tool body, but a tool that ignores the signal still resolves.
           if (err?.code === "ETIMEDOUT" && (!configuredTries || configuredTries <= 0)) throw err;
           const delayMs = Math.min(30_000, 250 * 2 ** Math.min(attempt - 1, 7));
-          traceToolEvent("retry_scheduled", "info", call, scope, { attempt, nextAttempt: attempt + 1, delayMs });
+          trace("retry_scheduled", "info", { attempt, nextAttempt: attempt + 1, delayMs });
           await waitForRetry(delayMs, signal);
         }
       }
 
+      if (stopReason !== undefined) return stoppedResult(); // the tool caught the stop signal but the run still stops
+
       // Undefined means "no value", serialized null-safe as "null" (changed
       // from the legacy "Success" marker so model context stays valid JSON).
+      // The log keeps the full result (the model gets a capped copy below).
+      log?.write({ phase: "result", result: isSubagentResult(rawResult) ? rawResult.xml : toJsonSafe(rawResult) });
       const finishOk = (resultChars: number): void =>
-        traceToolEvent("call_succeeded", "info", call, scope, { attempts: attempt, durationMs: elapsedMs(executionStartTime), resultChars });
+        trace("call_succeeded", "info", { attempts: attempt, durationMs: elapsedMs(executionStartTime), resultChars });
       if (rawResult === undefined) {
         finishOk(4);
         return {
@@ -676,8 +711,9 @@ export async function executeToolCalls(
       // scrubbed message plus what the tool finished before failing, so it repairs
       // only the remainder instead of repeating completed side effects.
       const aborted = signal?.aborted === true;
+      if (stopReason !== undefined && !aborted) return stoppedResult();
       const done = err?.context?.progress ?? progress;
-      traceToolEvent(aborted ? "call_aborted" : timedOut ? "call_timed_out" : "call_failed", "error", call, scope, {
+      trace(aborted ? "call_aborted" : timedOut ? "call_timed_out" : "call_failed", "error", {
         attempts,
         durationMs: elapsedMs(executionStartTime),
         error: describeError(err),
@@ -726,14 +762,35 @@ export async function executeToolCalls(
     }
   };
 
+  // Runs one call and reports its result at once; a throwing observer must not fail the run.
+  const runAndReport = async (call: ToolCallRecord): Promise<ToolResultRecord> => {
+    let log: ToolLogWriter | undefined;
+    try {
+      log = openToolLog?.(call, sessionId);
+    } catch {
+      log = undefined; // logging is best effort: the call runs without a log
+    }
+    let result: ToolResultRecord;
+    try {
+      result = await runSingle(call, log);
+    } finally {
+      log?.close();
+    }
+    if (log) result.logFile = log.file;
+    try {
+      onResult?.(result);
+    } catch {
+      // why: observers (persistence) are best-effort.
+    }
+    return result;
+  };
   if (parallel && toolCalls.length > 1) {
-    const results = await Promise.all(toolCalls.map((tc) => runSingle(tc)));
-    return results;
+    return Promise.all(toolCalls.map((tc) => runAndReport(tc)));
   }
 
   const results: ToolResultRecord[] = [];
   for (const tc of toolCalls) {
-    results.push(await runSingle(tc));
+    results.push(await runAndReport(tc));
   }
   return results;
 }

package/src/tools/tool.ts

@@ -143,11 +143,6 @@ export interface CreateToolOptions<TInput = any, TOutput = any> {
   retry?: { maxRetries?: number; baseDelayMs?: number; maxDelayMs?: number };
   /** Free-form tags for grouping/filtering tools (e.g. `["web", "readonly"]`). */
   tags?: string[];
-  /**
-   * When true, the host must approve this call before execution. Stored only;
-   * enforcement is wired by the host, default open.
-   */
-  needsApproval?: boolean;
   /**
    * Optional output schema (Zod or JSON Schema, stored as `unknown` so `zod`
    * stays optional for type-only consumers).
@@ -208,7 +203,6 @@ export function tool<TInput = any, TOutput = any>(
     ...(options.redact !== undefined ? { redact: options.redact } : {}),
     ...(options.retry !== undefined ? { retry: options.retry } : {}),
     ...(options.tags !== undefined ? { tags: options.tags } : {}),
-    ...(options.needsApproval !== undefined ? { needsApproval: options.needsApproval } : {}),
     ...(options.output !== undefined ? { output: options.output } : {}),
     ...(options.maxAttempts !== undefined ? { maxAttempts: options.maxAttempts } : {}),
   } as ToolDefinition<TInput, TOutput>;

package/src/types/agent.ts

@@ -133,6 +133,21 @@ export interface AgentConfig {
    * Writes are atomic and never fail a turn.
    */
   persist?: { dir?: string; file?: string };
+  /**
+   * How many times a run that FAILED for a transient reason (provider down or overloaded, timeouts, a cut stream, after
+   * the provider layer's own `retry` gave up) is tried again from where it stopped, with a growing wait (5 s, 15 s, 45 s,
+   * then 60 s). Default 3; `0` turns it off. Finished tool calls are not repeated. Never for aborts, bad config or input
+   * (401/400/...), budgets or limits. Applies to `run()` and queued runs, not to `stream()`. The final response also reports the
+   * tool calls, results, turns and token usage of the failed attempts (they happened and cost money).
+   */
+  runRetries?: number;
+  /**
+   * What happens to a run a crash cut off (needs `persist: { dir }` and the SAME `sessionId` after the restart).
+   * `"automatic"` (default): the Agent continues it as soon as it is constructed (tool calls that already have a saved
+   * result are not run again), then runs any prompts that were waiting. `"explicit"`: nothing runs until you call
+   * `agent.resume()`; `agent.interrupted()` lists what was cut off.
+   */
+  resume?: "automatic" | "explicit";
   /**
    * Folder for everything Agent Accelerator writes to disk (`sessions/`,
    * `scheduled_actions/`, `telemetry/`). Defaults to `setHome()`, then the `AGENT_ACCEL_HOME` env var, then `.agent-accel/` in the working directory.
@@ -214,6 +229,17 @@ export interface AgentConfig {
   limits?: AgentRunLimits;
 }
 
+/** A run that a crash cut off (see {@link Agent.interrupted}). */
+export interface InterruptedRun {
+  runId: string;
+  /** Epoch ms when the run began. */
+  startedAt: number;
+  /** Preview of the prompt that started it. */
+  prompt: string;
+  /** Names of tool calls it had asked for that have no result yet. */
+  pendingToolCalls: string[];
+}
+
 /** Per-request + run limits (Q-22). */
 export interface AgentRunLimits {
   maxTurns?: number;

package/src/types/message.ts

@@ -9,6 +9,9 @@ export interface TextPart {
   thoughtSignature?: string;
 }
 
+/** Detail level a provider spends on one image or video (more detail = more input tokens). Google only; other providers ignore it with a warning. */
+export type MediaResolution = "low" | "medium" | "high" | "ultra_high";
+
 /** Image content accepted as a URL, data, path, or binary value. */
 export interface ImagePart {
   type: "image";
@@ -17,6 +20,8 @@ export interface ImagePart {
    */
   image: string | Uint8Array | ArrayBuffer;
   mimeType?: string;
+  /** Detail level for this image (Google: `low` 280, `medium` 560, `high` 1120, `ultra_high` 2240 tokens). */
+  resolution?: MediaResolution;
 }
 
 /** Audio content accepted as a URL, data, path, or binary value. */
@@ -48,6 +53,8 @@ export interface VideoPart {
    */
   video: string | Uint8Array | ArrayBuffer;
   mimeType?: string;
+  /** Detail level per frame (Google: `low`/`medium` 70, `high` 280 tokens). */
+  resolution?: MediaResolution;
 }
 
 /** Assistant-generated structured tool invocation. */
@@ -78,6 +85,10 @@ export interface ToolResultPart {
   name: string;
   result: unknown;
   isError?: boolean;
+  /** This call's log file, relative to the session folder (see `ToolExecutionContext.log`). */
+  logFile?: string;
+  /** The tool ended the run with `ctx.stop(reason)` (see `ToolExecutionContext.stop`). */
+  stopped?: boolean;
 }
 
 /** Provider reasoning/thinking content. */
@@ -100,12 +111,20 @@ export type ContentPart =
 
 export type MessageRole = "system" | "user" | "assistant" | "tool";
 
+/** A provider's raw output steps for one assistant turn, kept to replay history byte-exact (only the tagged provider reads them). */
+export interface ProviderSteps {
+  provider: string;
+  steps: unknown[];
+}
+
 /** Normalized conversation message. */
 export interface Message {
   role: MessageRole;
   content: string | ContentPart[];
   name?: string;
   thoughtSignature?: string;
+  /** Raw provider output steps of an assistant turn (opaque; e.g. Google `steps`). */
+  providerSteps?: ProviderSteps;
 }
 
 /**

package/src/types/model.ts

@@ -1,5 +1,5 @@
 import type { ThinkingConfig, CacheOption, ServiceTier, TokenUsage } from "./core.ts";
-import type { ProviderContext } from "./message.ts";
+import type { ProviderContext, ProviderSteps } from "./message.ts";
 import type { StandardToolDeclaration, ToolCallRecord } from "./tool.ts";
 import type { AssistantMessageEventStream } from "../streaming/event-stream.ts";
 
@@ -226,6 +226,8 @@ export interface ProviderGenerateResult {
   provider: ProviderId;
   raw: ProviderRawData;
   durationMs: number;
+  /** Raw output steps for exact history replay (stored on the assistant message). */
+  providerSteps?: ProviderSteps;
 }
 
 /** Provider contract implemented by native REST transports. */
@@ -244,4 +246,6 @@ export interface Provider {
     context: ProviderContext,
     options?: ProviderRequestOptions
   ): AssistantMessageEventStream;
+  /** True when this call may legitimately run far past the request timeouts (e.g. Google long decode); the loop then leaves timing to the adapter's own per-request timeouts. */
+  isLongRunning?(model: string | ModelSpec, options?: ProviderRequestOptions): boolean;
 }

package/src/types/response.ts

@@ -1,6 +1,7 @@
 import type { TokenUsage } from "./core.ts";
 import type { ToolCallRecord, ToolResultRecord } from "./tool.ts";
 import type { ProviderRawData, ProviderId } from "./model.ts";
+import type { ProviderSteps } from "./message.ts";
 
 /** One logged step inside a sub-agent worker run (surfaced via `agent.track(id)`). */
 export interface SubAgentStep {
@@ -59,6 +60,7 @@ export type FinishReason =
   | "content_filter"
   | "refusal"
   | "max_turns"
+  | "stopped"
   | "error"
   | (string & {});
 
@@ -87,6 +89,7 @@ export function normalizeFinishReason(raw?: string): {
     length: "length",
     max_tokens: "length",
     max_turns: "max_turns",
+    stopped: "stopped",
     content_filter: "content_filter",
     refusal: "refusal",
     refused: "refusal",
@@ -142,6 +145,8 @@ export class AgentResponse {
   readonly durationMs: number;
   readonly raw: ProviderRawData;
   readonly turns: number;
+  /** Raw provider output steps of a single streamed turn (history replay only; not in `toJSON`). */
+  readonly providerSteps?: ProviderSteps;
 
   /**
    * Constructs a normalized response. Agent runs create this automatically;
@@ -167,6 +172,7 @@ export class AgentResponse {
     durationMs: number;
     raw: ProviderRawData;
     turns?: number;
+    providerSteps?: ProviderSteps;
   }) {
     this.text = data.text;
     if (data.parsed !== undefined) (this as { parsed?: unknown }).parsed = data.parsed;
@@ -184,6 +190,7 @@ export class AgentResponse {
     this.durationMs = data.durationMs;
     this.raw = data.raw;
     this.turns = data.turns ?? 1;
+    if (data.providerSteps) this.providerSteps = data.providerSteps;
   }
 
   /** Returns the final assistant text. */

package/src/types/tool.ts

@@ -29,6 +29,20 @@ export interface ToolExecutionContext {
   emit?: ToolEmitFn;
   /** Structured logger for tool implementations (defaults to no-op). */
   logger?: ToolLogger;
+  /**
+   * Writes one line to this call's log file (`tool-logs/<n>-<tool>.ndjson` in the session folder), flushed at once, so
+   * after a crash it shows how far the call got: `ctx.log("uploaded 3 of 5 files", { done: 3 })`. Only written when the
+   * Agent persists to a folder (`persist: { dir }`); otherwise a no-op. For developers, never sent to the model.
+   */
+  log: (message: string, data?: unknown) => void;
+  /**
+   * Ends the whole run from inside a tool, for example when your own permission check says no:
+   * `if (!(await askUser("Pay $50?"))) ctx.stop("user declined the payment")`. It throws, so the code after it never runs
+   * (even if you forget `return`). The reason is saved as this call's result; the other tool calls of the same batch
+   * still run to completion; then the run ends with `finishReason: "stopped"` and NO further model turn, and the agent
+   * waits for the next user message. `timeoutMs` counts the time spent waiting for your check.
+   */
+  stop: (reason: string) => never;
 }
 
 export type ToolExecuteFn<TInput = any, TOutput = any> = (
@@ -92,12 +106,6 @@ export interface ToolDefinition<TInput = any, TOutput = any> {
   redact?: (err: unknown) => string;
   /** Free-form tags for grouping/filtering tools (e.g. `["web", "readonly"]`). */
   tags?: string[];
-  /**
-   * When true, the host must approve this call before execution (human-in-the-
-   * loop). The loop reads via `(toolDef as any).needsApproval`; enforcement
-   * is wired by the host, default open (undefined = no gate).
-   */
-  needsApproval?: boolean;
   /**
    * Optional output schema (Zod or JSON Schema) used to validate/coerce the
    * tool's return value before it reaches model context. Stored as `unknown`
@@ -135,6 +143,10 @@ export interface ToolResultRecord {
   result: unknown;
   isError?: boolean;
   durationMs?: number;
+  /** This call's log file, relative to the session folder (only when the Agent persists to a folder). */
+  logFile?: string;
+  /** The tool ended the run with `ctx.stop(reason)`; `result` is the reason. */
+  stopped?: boolean;
 }
 
 /**

package/src/utils/durable.ts

@@ -0,0 +1,218 @@
+/**
+ * How the SDK writes state to disk safely. One writer for sessions, scheduled
+ * actions and the catalog cache: a crash or a power cut leaves either the old
+ * file or the new one, never a torn mix, and the last good version is kept as
+ * `<file>.bak`. Also the one-process-per-folder lock and the stale temp-file sweep.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { ConfigError } from "../types/errors.ts";
+
+/** Flushes a folder's entries (a new or renamed file) to disk; best effort because some platforms cannot open a folder. */
+export function fsyncFolder(dir: string): void {
+  let fd: number | undefined;
+  try {
+    fd = fs.openSync(dir, "r");
+    fs.fsyncSync(fd);
+  } catch {
+    // why: Windows (and some filesystems) refuse to open or fsync a folder; the file itself is already flushed.
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // why: closing a read-only folder handle cannot lose data.
+      }
+    }
+  }
+}
+
+/**
+ * Durable atomic write: temp file (0600) -> fsync -> previous version kept as `<file>.bak` (hard link, no copy)
+ * -> rename -> fsync of the folder. Throws on failure; the temp file is removed. `backup: false` skips the `.bak`.
+ */
+export function writeFileDurable(filePath: string, content: string | Uint8Array, opts: { backup?: boolean } = {}): void {
+  const dir = path.dirname(filePath);
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  } catch {
+    // why: a missing folder surfaces as the open() error below, with a clearer path.
+  }
+  const rand = globalThis.crypto?.randomUUID?.().slice(0, 8) ?? Math.random().toString(36).slice(2, 8);
+  const tmp = `${filePath}.tmp-${process.pid}-${rand}`;
+  try {
+    const fd = fs.openSync(tmp, "wx", 0o600);
+    try {
+      fs.writeFileSync(fd, content);
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    if (opts.backup !== false) {
+      try {
+        fs.rmSync(`${filePath}.bak`, { force: true });
+        fs.linkSync(filePath, `${filePath}.bak`); // the old inode survives the rename below
+      } catch {
+        // why: no previous version (first write) or no hard links on this filesystem: the write still goes ahead.
+      }
+    }
+    fs.renameSync(tmp, filePath);
+  } catch (err) {
+    try {
+      fs.rmSync(tmp, { force: true });
+    } catch {
+      // why: the original error is the one worth reporting.
+    }
+    throw err;
+  }
+  fsyncFolder(dir);
+}
+
+/**
+ * Reads `file`; when `isValid` rejects it, falls back to `<file>.bak`. `undefined` when the file is missing (a deleted
+ * file is never resurrected from its backup). When both are invalid the primary text comes back, `fromBackup: false`.
+ */
+export function readWithBackup(file: string, isValid: (text: string) => boolean): { text: string; fromBackup: boolean } | undefined {
+  let text: string;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch {
+    return undefined;
+  }
+  if (isValid(text)) return { text, fromBackup: false };
+  try {
+    const backup = fs.readFileSync(`${file}.bak`, "utf8");
+    if (isValid(backup)) return { text: backup, fromBackup: true };
+  } catch {
+    // why: no backup to fall back to.
+  }
+  return { text, fromBackup: false };
+}
+
+// ---------------------------------------------------------------------------
+// One process per folder
+// ---------------------------------------------------------------------------
+
+/** Folders this process already holds (the lock is re-entrant: many Agents share one home). */
+const heldFolders = new Set<string>();
+let exitHookInstalled = false;
+
+// Blocks the thread for `ms` (a lock file being written by another process is the only reason to wait); in: a short delay, out: nothing.
+function pause(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+// True while process `pid` exists (EPERM means it exists but belongs to someone else); in: a pid from a lock file, out: lockFolder's stale check.
+function processAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return (err as { code?: string }).code === "EPERM";
+  }
+}
+
+// Removes the locks this process still holds when it exits normally; a killed process leaves its lock for the next start to detect as stale.
+function installExitHook(): void {
+  if (exitHookInstalled) return;
+  exitHookInstalled = true;
+  process.once("exit", () => {
+    for (const dir of heldFolders) {
+      try {
+        fs.rmSync(path.join(dir, ".lock"), { force: true });
+      } catch {
+        // why: nothing can be reported while exiting; a leftover lock is detected as stale.
+      }
+    }
+  });
+}
+
+// Deletes leftover `<file>.tmp-<pid>-<rand>` files of writes that never finished; only safe while holding the folder lock; in: a locked folder, out: nothing.
+function sweepTempFiles(dir: string): void {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) sweepTempFiles(full);
+    else if (/\.tmp-\d+-[0-9a-z]+$/.test(entry.name)) {
+      try {
+        fs.rmSync(full, { force: true });
+      } catch {
+        // why: an undeletable leftover is harmless.
+      }
+    }
+  }
+}
+
+/**
+ * Takes the one-process lock of a folder (`<dir>/.lock` = pid, host, start time) and sweeps the temp files of writes
+ * that never finished. Re-entrant inside one process. Throws `ConfigError` at once when another live process holds it;
+ * a lock left by a dead process (same host, pid gone) or an unreadable one is taken over. Local disks only.
+ */
+export function lockFolder(folder: string): void {
+  const dir = path.resolve(folder);
+  if (heldFolders.has(dir)) return;
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const lockFile = path.join(dir, ".lock");
+  const mine = JSON.stringify({ pid: process.pid, host: os.hostname(), startedAt: new Date().toISOString() });
+  let unreadable = 0;
+  for (;;) {
+    try {
+      const fd = fs.openSync(lockFile, "wx", 0o600);
+      try {
+        fs.writeFileSync(fd, mine);
+      } finally {
+        fs.closeSync(fd);
+      }
+      heldFolders.add(dir);
+      installExitHook();
+      sweepTempFiles(dir);
+      return;
+    } catch (err) {
+      if ((err as { code?: string }).code !== "EEXIST") throw err;
+    }
+    let text = "";
+    try {
+      text = fs.readFileSync(lockFile, "utf8");
+    } catch {
+      continue; // released between the open and the read: try again
+    }
+    let owner: { pid?: unknown; host?: unknown; startedAt?: unknown } | undefined;
+    try {
+      owner = JSON.parse(text);
+    } catch {
+      owner = undefined;
+    }
+    if (typeof owner?.pid !== "number") {
+      // Empty or garbage: another process may be mid-write. Give it a moment, then treat it as stale.
+      if (++unreadable <= 5) {
+        pause(40);
+        continue;
+      }
+    } else if (owner.pid !== process.pid) {
+      if (owner.host !== os.hostname()) {
+        throw new ConfigError(
+          `[Agent Accelerator] Folder "${dir}" is locked by host "${String(owner.host)}" (process ${owner.pid}). Only local disks are supported: use a folder on this machine.`
+        );
+      }
+      if (processAlive(owner.pid)) {
+        throw new ConfigError(
+          `[Agent Accelerator] Folder "${dir}" is already in use by process ${owner.pid} (started ${String(owner.startedAt)}). ` +
+            `Only one process may use it at a time: stop that process or use another folder (Agent \`home\`, setHome(), AGENT_ACCEL_HOME). ` +
+            `If that process is gone, delete "${lockFile}".`
+        );
+      }
+    }
+    // Stale (dead owner, our own pid from an earlier life, or unreadable): take it over, but only if nobody replaced it meanwhile.
+    try {
+      if (fs.readFileSync(lockFile, "utf8") === text) fs.rmSync(lockFile, { force: true });
+    } catch {
+      // why: it vanished: the next loop turn creates it.
+    }
+  }
+}

package/src/utils/headers.ts

@@ -23,7 +23,7 @@ export function getPackageVersion(): string {
     const v = (globalThis as any).process?.env?.npm_package_version;
     if (typeof v === "string" && v) return v;
   } catch {}
-  return "0.5.1";
+  return "0.5.3";
 }
 
 function getAgentAccelUserAgent(): string {