la-machina-engine 0.21.0 → 0.22.0

package/dist/index.cjs

@@ -2291,39 +2291,7 @@ var AISdkAdapter = class {
       ...request.toolChoice === "required" ? { toolChoice: "required" } : {},
       maxRetries: this.options.maxRetries ?? 2
     });
-    for await (const event of result.fullStream) {
-      switch (event.type) {
-        case "text-delta":
-          yield {
-            type: "text",
-            index: 0,
-            text: event.text ?? event.textDelta ?? ""
-          };
-          break;
-        case "tool-call":
-          yield {
-            type: "tool_use",
-            index: 0,
-            id: event.toolCallId ?? "",
-            name: event.toolName ?? "",
-            // AI SDK v4: tool args are in `event.input` (not `event.args`)
-            input: event.input ?? event.args ?? {}
-          };
-          break;
-        case "finish": {
-          const usage = event.totalUsage ?? event.usage ?? {};
-          yield {
-            type: "message_stop",
-            stopReason: mapFinishReason(event.finishReason),
-            usage: {
-              input: usage.inputTokens ?? usage.promptTokens ?? 0,
-              output: usage.outputTokens ?? usage.completionTokens ?? 0
-            }
-          };
-          break;
-        }
-      }
-    }
+    yield* normalizeAiSdkStream(result.fullStream);
   }
   async getModel() {
     if (this.model !== null) return this.model;
@@ -2368,6 +2336,53 @@ var AISdkAdapter = class {
     return this.model;
   }
 };
+async function* normalizeAiSdkStream(fullStream) {
+  let sawFinish = false;
+  for await (const event of fullStream) {
+    switch (event.type) {
+      case "text-delta":
+        yield {
+          type: "text",
+          index: 0,
+          text: event.text ?? event.textDelta ?? ""
+        };
+        break;
+      case "tool-call":
+        yield {
+          type: "tool_use",
+          index: 0,
+          id: event.toolCallId ?? "",
+          name: event.toolName ?? "",
+          // AI SDK v4: tool args are in `event.input` (not `event.args`)
+          input: event.input ?? event.args ?? {}
+        };
+        break;
+      case "error": {
+        const status = extractStatus(event.error);
+        const message = errorMessage(event.error);
+        throw new ApiError(status !== null ? `${status} ${message}` : message, status);
+      }
+      case "finish": {
+        sawFinish = true;
+        const usage = event.totalUsage ?? event.usage ?? {};
+        yield {
+          type: "message_stop",
+          stopReason: mapFinishReason(event.finishReason),
+          usage: {
+            input: usage.inputTokens ?? usage.promptTokens ?? 0,
+            output: usage.outputTokens ?? usage.completionTokens ?? 0
+          }
+        };
+        break;
+      }
+    }
+  }
+  if (!sawFinish) {
+    throw new StreamIncompleteError(
+      "AI SDK stream ended without a finish event; assistant output is partial"
+    );
+  }
+}
 function mapFinishReason(reason) {
   switch (reason) {
     case "stop":
@@ -2380,6 +2395,23 @@ function mapFinishReason(reason) {
       return "end_turn";
   }
 }
+function errorMessage(err) {
+  if (err instanceof Error) return err.message;
+  if (typeof err === "string") return err;
+  try {
+    return JSON.stringify(err);
+  } catch {
+    return String(err);
+  }
+}
+function extractStatus(err) {
+  if (err !== null && typeof err === "object") {
+    const o = err;
+    const s = o.statusCode ?? o.status;
+    if (typeof s === "number") return s;
+  }
+  return null;
+}
 
 // src/model/factory.ts
 function createModelAdapter(config, options = {}) {
@@ -2858,7 +2890,28 @@ function normalizeMessages(messages) {
   }
   return ensureToolResultPairing(fixed);
 }
-function ensureToolResultPairing(messages) {
+function ensureToolResultPairing(input) {
+  const allToolUseIds = /* @__PURE__ */ new Set();
+  for (const msg of input) {
+    if (!Array.isArray(msg.content)) continue;
+    for (const b of msg.content) {
+      const block = b;
+      if (block.type === "tool_use" && block.id) allToolUseIds.add(block.id);
+    }
+  }
+  const isOrphanResult = (b) => {
+    const x = b;
+    return x.type === "tool_result" && x.tool_use_id !== void 0 && !allToolUseIds.has(x.tool_use_id);
+  };
+  const messages = [];
+  for (const msg of input) {
+    if (!Array.isArray(msg.content) || !msg.content.some(isOrphanResult)) {
+      messages.push(msg);
+      continue;
+    }
+    const filtered = msg.content.filter((b) => !isOrphanResult(b));
+    if (filtered.length > 0) messages.push({ ...msg, content: filtered });
+  }
   const pendingToolUseIds = /* @__PURE__ */ new Set();
   for (const msg of messages) {
     if (!Array.isArray(msg.content)) continue;
@@ -2899,15 +2952,45 @@ init_cjs_shims();
 
 // src/compact/dropMiddle.ts
 init_cjs_shims();
+
+// src/compact/grouping.ts
+init_cjs_shims();
+function groupByRound(messages) {
+  if (messages.length === 0) return [];
+  const groups = [];
+  let current = [];
+  for (const msg of messages) {
+    if (msg.role === "assistant" && current.length > 0) {
+      groups.push(current);
+      current = [];
+    }
+    current.push(msg);
+  }
+  if (current.length > 0) groups.push(current);
+  return groups;
+}
+function trailingRounds(messages, minMessages) {
+  if (messages.length === 0) return { tail: [], start: 0 };
+  const groups = groupByRound(messages);
+  let count = 0;
+  let g = groups.length;
+  while (g > 0 && count < minMessages) {
+    g--;
+    count += groups[g].length;
+  }
+  const tail = groups.slice(g).flat();
+  return { tail, start: messages.length - tail.length };
+}
+
+// src/compact/dropMiddle.ts
 function dropMiddle(messages, keepLast) {
   const firstUserIndex = messages.findIndex((m) => m.role === "user");
   if (firstUserIndex === -1) {
     return { messages: [...messages], strategy: "drop-middle", dropped: 0 };
   }
-  const tailStart = Math.max(messages.length - keepLast, firstUserIndex + 1);
-  const tail = messages.slice(tailStart);
-  const middleStart = firstUserIndex + 1;
-  const droppedCount = Math.max(0, tailStart - middleStart);
+  const body = messages.slice(firstUserIndex + 1);
+  const { tail } = trailingRounds(body, keepLast);
+  const droppedCount = body.length - tail.length;
   if (droppedCount === 0) {
     return { messages: [...messages], strategy: "drop-middle", dropped: 0 };
   }
@@ -3047,15 +3130,16 @@ REMINDER: Do NOT call any tools. Respond with plain text only \u2014 an <analysi
 }
 
 // src/compact/summarize.ts
+var SUMMARY_TIMEOUT_MS = 6e4;
 async function summarizeCompact(options) {
-  const { messages, config, client, system } = options;
+  const { messages, config, client, system, signal } = options;
   const firstUserIndex = messages.findIndex((m) => m.role === "user");
   if (firstUserIndex === -1) {
     return { messages: [...messages], strategy: "summarize", dropped: 0 };
   }
-  const tailStart = Math.max(messages.length - config.keepLast, firstUserIndex + 1);
-  const tail = messages.slice(tailStart);
-  const middle = messages.slice(firstUserIndex + 1, tailStart);
+  const body = messages.slice(firstUserIndex + 1);
+  const { tail } = trailingRounds(body, config.keepLast);
+  const middle = body.slice(0, body.length - tail.length);
   const droppedCount = middle.length;
   if (droppedCount === 0) {
     return { messages: [...messages], strategy: "summarize", dropped: 0 };
@@ -3070,7 +3154,13 @@ async function summarizeCompact(options) {
   ];
   let summaryText;
   try {
-    summaryText = await generateSummary(client, system, summaryMessages, config.summaryMaxTokens);
+    summaryText = await generateSummary(
+      client,
+      system,
+      summaryMessages,
+      config.summaryMaxTokens,
+      signal
+    );
   } catch {
     const marker = {
       role: "user",
@@ -3095,13 +3185,16 @@ ${summaryText}`
     summaryLength: summaryText.length
   };
 }
-async function generateSummary(client, system, messages, maxTokens) {
+async function generateSummary(client, system, messages, maxTokens, signal) {
   const pieces = [];
+  const timeoutSignal = AbortSignal.timeout(SUMMARY_TIMEOUT_MS);
+  const abortSignal = signal !== void 0 ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
   for await (const event of client.streamMessage({
     messages,
     system,
     maxTokens,
-    temperature: 0
+    temperature: 0,
+    abortSignal
   })) {
     if (event.type === "text") {
       pieces.push(event.text);
@@ -3117,8 +3210,8 @@ async function generateSummary(client, system, messages, maxTokens) {
 
 // src/compact/compactor.ts
 async function compactIfNeeded(options) {
-  const { messages, usage, contextLimit, config, client, system } = options;
-  const used = usage.input + usage.output + (usage.cacheReadInput ?? 0) + (usage.cacheCreationInput ?? 0);
+  const { messages, usage, contextLimit, config, client, system, signal, liveContextTokens } = options;
+  const used = liveContextTokens !== void 0 && liveContextTokens > 0 ? liveContextTokens : usage.input + usage.output + (usage.cacheReadInput ?? 0) + (usage.cacheCreationInput ?? 0);
   const ratio = used / contextLimit;
   if (ratio <= config.threshold) {
     if (config.microcompact && messages.length > config.keepLast + 4) {
@@ -3132,10 +3225,10 @@ async function compactIfNeeded(options) {
     }
     return { compacted: false, result: null, messages: [...messages] };
   }
-  const result = await executeStrategy(messages, config, client, system);
-  return { compacted: true, result, messages: result.messages };
+  const result = await executeStrategy(messages, config, client, system, signal);
+  return { compacted: result.dropped > 0, result, messages: result.messages };
 }
-async function executeStrategy(messages, config, client, system) {
+async function executeStrategy(messages, config, client, system, signal) {
   let workingMessages = [...messages];
   if (config.microcompact) {
     const mcResult = microcompact({
@@ -3152,14 +3245,16 @@ async function executeStrategy(messages, config, client, system) {
         messages: workingMessages,
         config,
         client,
-        system
+        system,
+        ...signal !== void 0 ? { signal } : {}
       });
     case "session-memory":
       return summarizeCompact({
         messages: workingMessages,
         config,
         client,
-        system
+        system,
+        ...signal !== void 0 ? { signal } : {}
       });
     case "auto":
     default:
@@ -3168,7 +3263,8 @@ async function executeStrategy(messages, config, client, system) {
           messages: workingMessages,
           config,
           client,
-          system
+          system,
+          ...signal !== void 0 ? { signal } : {}
         });
       } catch {
         return dropMiddle(workingMessages, config.keepLast);
@@ -3333,7 +3429,8 @@ async function agentLoop(options) {
   let recoveryCount = 0;
   let maxTokensEscalated = false;
   let escalatedMaxTokens;
-  let compactedThisTurn = false;
+  const MAX_EMERGENCY_413 = 1;
+  let emergency413Count = 0;
   const MAX_API_RETRIES = 3;
   const BASE_BACKOFF_MS = 1e3;
   let apiRetryCount = 0;
@@ -3352,7 +3449,6 @@ async function agentLoop(options) {
     }
   };
   for (; ; ) {
-    compactedThisTurn = false;
     const turnStartedAt = Date.now();
     const turnStartTokens = { ...ctx.getTokensUsed() };
     if (options.runSignal?.aborted === true) {
@@ -3403,7 +3499,7 @@ async function agentLoop(options) {
       });
     }
     let messages = ctx.getMessages();
-    const mightCompact = ctx.getTokensUsed().input + ctx.getTokensUsed().output > contextLimit * compactionConfig.threshold;
+    const mightCompact = ctx.getLastPromptTokens() > contextLimit * compactionConfig.threshold;
     if (mightCompact) await fireProgress("compacting");
     const compactResult = await compactIfNeeded({
       messages,
@@ -3411,7 +3507,10 @@ async function agentLoop(options) {
       contextLimit,
       config: compactionConfig,
       client,
-      system
+      system,
+      liveContextTokens: ctx.getLastPromptTokens(),
+      // WS-3b — live, not cumulative
+      ...options.runSignal !== void 0 ? { signal: options.runSignal } : {}
     });
     if (compactResult.compacted) {
       messages = compactResult.messages;
@@ -3459,6 +3558,7 @@ async function agentLoop(options) {
     const normalizedMessages = normalizeMessages(
       messagesForApi
     );
+    const effectiveToolChoice = options.toolChoice === "required" && cumulativeToolCalls > 0 ? "auto" : options.toolChoice;
     try {
       for await (const event of client.streamMessage({
         messages: normalizedMessages,
@@ -3466,7 +3566,7 @@ async function agentLoop(options) {
         tools: anthropicTools,
         ...options.runSignal !== void 0 ? { abortSignal: options.runSignal } : {},
         ...escalatedMaxTokens !== void 0 ? { maxTokens: escalatedMaxTokens } : {},
-        ...options.toolChoice !== void 0 ? { toolChoice: options.toolChoice } : {}
+        ...effectiveToolChoice !== void 0 ? { toolChoice: effectiveToolChoice } : {}
       })) {
         const handled = consumeEvent(event);
         if (handled.text !== void 0) textBlocks.push(handled.text);
@@ -3481,8 +3581,17 @@ async function agentLoop(options) {
       if (isAbortSignalAborted(options.runSignal)) {
         return failed(new RunTimeoutError(options.runTimeoutMs ?? 0), transcript);
       }
-      if (isPromptTooLong(err) && !compactedThisTurn) {
-        compactedThisTurn = true;
+      if (isPromptTooLong(err)) {
+        if (emergency413Count >= MAX_EMERGENCY_413) {
+          return failed(
+            new EngineError(
+              "ERR_PROMPT_TOO_LONG",
+              "Prompt exceeds the model context window even after emergency compaction"
+            ),
+            transcript
+          );
+        }
+        emergency413Count++;
         const emergency = await compactIfNeeded({
           messages,
           usage: ctx.getTokensUsed(),
@@ -3490,9 +3599,11 @@ async function agentLoop(options) {
           // force below threshold
           config: { ...compactionConfig, threshold: 0, keepLast: 4 },
           client,
-          system
+          system,
+          ...options.runSignal !== void 0 ? { signal: options.runSignal } : {}
         });
-        if (emergency.compacted) {
+        const madeProgress = emergency.compacted && emergency.messages.length < messages.length;
+        if (madeProgress) {
           await options.inspect?.appendEvent({
             type: "compaction_413",
             turn: ctx.getTurnCount(),
@@ -3508,6 +3619,13 @@ async function agentLoop(options) {
           });
           continue;
         }
+        return failed(
+          new EngineError(
+            "ERR_PROMPT_TOO_LONG",
+            "Prompt too long and compaction could not reduce it"
+          ),
+          transcript
+        );
       }
       if (isRetryable(err) && apiRetryCount < MAX_API_RETRIES) {
         apiRetryCount++;
@@ -3979,6 +4097,15 @@ var RunContext = class {
   messages = [];
   turnCount = 0;
   tokensUsed = { input: 0, output: 0 };
+  /**
+   * Engine 056 / WS-3b — size of the most recent request's prompt
+   * (`input + cacheReadInput` from the last `message_stop`). This is the
+   * LIVE context size, used to decide compaction. `tokensUsed` is a
+   * cumulative BILLING counter that grows ~quadratically over a long run
+   * (each turn re-sends the whole context), so using it for the threshold
+   * triggered compaction far too early and then re-summarized every turn.
+   */
+  lastPromptTokens = 0;
   lastUuid = null;
   /**
    * Plan 019 — names of tools whose capability-stub returned an
@@ -4133,6 +4260,13 @@ var RunContext = class {
   getTokensUsed() {
     return this.tokensUsed;
   }
+  /**
+   * Engine 056 / WS-3b — live context size: `input + cacheReadInput` of
+   * the most recent request. 0 before the first response of a run/resume.
+   */
+  getLastPromptTokens() {
+    return this.lastPromptTokens;
+  }
   /** Plan 019 — record that a capability-stubbed tool fired during this run. */
   recordCapabilityMissing(toolName) {
     this.capabilitiesMissing.add(toolName);
@@ -4187,6 +4321,7 @@ var RunContext = class {
     if (usage.cacheReadInput !== void 0) {
       this.tokensUsed.cacheReadInput = (this.tokensUsed.cacheReadInput ?? 0) + usage.cacheReadInput;
     }
+    this.lastPromptTokens = usage.input + (usage.cacheReadInput ?? 0);
   }
   // ---------- internal ----------
   async writeEntry(entry) {
@@ -4511,13 +4646,18 @@ var TranscriptWriter = class {
       await writeMeta(this.storage, this.logPath, this.meta);
     }
   }
-  flushLog() {
-    if (this.flushInFlight) return this.flushInFlight;
-    if (this.buffer.length === 0) return Promise.resolve();
-    this.flushInFlight = this.doFlush().finally(() => {
-      this.flushInFlight = null;
-    });
-    return this.flushInFlight;
+  async flushLog() {
+    for (; ; ) {
+      if (this.flushInFlight !== null) {
+        await this.flushInFlight;
+        continue;
+      }
+      if (this.buffer.length === 0) return;
+      this.flushInFlight = this.doFlush().finally(() => {
+        this.flushInFlight = null;
+      });
+      await this.flushInFlight;
+    }
   }
   async setStatus(status) {
     this.meta = {
@@ -4530,9 +4670,7 @@ var TranscriptWriter = class {
   async close() {
     if (this.closed) return;
     this.clearIdleTimer();
-    if (this.buffer.length > 0) {
-      await this.flushLog();
-    }
+    await this.flushLog();
     this.closed = true;
   }
   // ---------- internals ----------
@@ -4589,8 +4727,16 @@ function formatShardName(index) {
 async function loadWriterState(storage, logPath) {
   const existing = await readMeta(storage, logPath);
   if (existing === null) return null;
-  const nextShardIndex = existing.lastShardIndex === null ? 0 : existing.lastShardIndex + 1;
-  return { nextShardIndex, meta: existing };
+  let maxShard = existing.lastShardIndex ?? -1;
+  try {
+    const names = await storage.listDir(logPath);
+    for (const name of names) {
+      const m = /^(\d{6})\.jsonl$/.exec(name);
+      if (m !== null) maxShard = Math.max(maxShard, parseInt(m[1], 10));
+    }
+  } catch {
+  }
+  return { nextShardIndex: maxShard + 1, meta: existing };
 }
 
 // src/subagent/runner.ts
@@ -7007,7 +7153,14 @@ var McpClient = class {
     }
     let tools;
     try {
-      const response = await client.listTools();
+      const response = await withTimeout(
+        client.listTools(),
+        this.options.connectTimeoutMs,
+        () => new McpConnectionError(
+          this.serverName,
+          `tools/list did not complete within ${this.options.connectTimeoutMs}ms`
+        )
+      );
       tools = normalizeToolList(response, this.serverName);
     } catch (err) {
       await safeClose(client);
@@ -7016,6 +7169,9 @@ var McpClient = class {
     this.sdkClient = client;
     this.toolCache = tools;
     this.connected = true;
+    client.onclose = () => {
+      this.connected = false;
+    };
     this.options.logger.info("mcp.connect ok", {
       server: this.serverName,
       type: this.options.config.type,
@@ -7054,12 +7210,22 @@ var McpClient = class {
   }
   async close() {
     const client = this.sdkClient;
+    const pid = this.childPid;
     this.sdkClient = null;
     this.connected = false;
     this.toolCache = null;
     this.childPid = null;
     if (client !== null) {
-      await safeClose(client);
+      try {
+        await safeClose(client);
+      } finally {
+        if (pid !== null) {
+          try {
+            process.kill(pid, "SIGKILL");
+          } catch {
+          }
+        }
+      }
     }
   }
   /**
@@ -7681,7 +7847,6 @@ function buildPermissionPolicy(config) {
   const rules = parseRules(config.rules);
   return {
     check: (toolName) => {
-      if (isSafeTool(toolName)) return ALLOW;
       for (const rule of rules) {
         if (matchesRule(toolName, rule)) {
           if (rule.action === "allow") return ALLOW;
@@ -7691,6 +7856,7 @@ function buildPermissionPolicy(config) {
           };
         }
       }
+      if (isSafeTool(toolName)) return ALLOW;
       return {
         allowed: false,
         reason: `Permission denied: "${toolName}" \u2014 no matching rule (mode: rules, fall-closed)`
@@ -8091,7 +8257,7 @@ function getMcpSection(options) {
   if (options.mcpTools.length === 0) return null;
   const byServer = /* @__PURE__ */ new Map();
   for (const tool of options.mcpTools) {
-    const match = tool.name.match(/^mcp__([^_]+)__(.+)$/);
+    const match = tool.name.match(/^mcp__(.+?)__(.+)$/);
     if (!match) continue;
     const server = match[1];
     const toolName = match[2];
@@ -8442,6 +8608,7 @@ init_contract();
 var ALL_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
 var DEFAULT_MAX_BODY_BYTES = 256 * 1024;
 var DEFAULT_MAX_RESPONSE_BYTES = 100 * 1024;
+var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_PAGES = 5;
 var MAX_PAGES_HARD_CAP = 50;
 var DEFAULT_MAX_ITEMS = 500;
@@ -8473,6 +8640,7 @@ function createApiCallTool(opts) {
   }
   const fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
   const maxResponseBytes = opts.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+  const requestTimeoutMs = opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
   const inputSchema19 = import_zod23.z.object({
     service: import_zod23.z.enum(serviceNames),
     method: import_zod23.z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
@@ -8534,6 +8702,7 @@ function createApiCallTool(opts) {
           input,
           fetchFn,
           maxResponseBytes,
+          requestTimeoutMs,
           env: opts.env,
           resolveAuth: opts.resolveAuth,
           resolveBaseUrl: opts.resolveBaseUrl,
@@ -8621,14 +8790,18 @@ function createApiCallTool(opts) {
             ...authHeaders
             // wins last — model cannot override
           },
-          ...bodyText !== void 0 ? { body: bodyText } : {}
+          ...bodyText !== void 0 ? { body: bodyText } : {},
+          signal: AbortSignal.timeout(requestTimeoutMs)
+          // WS-5c
         });
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         return errResult(`network error: ${msg}`);
       }
+      const tooLarge = responseTooLarge(res);
+      if (tooLarge !== null) return errResult(tooLarge);
       const raw = await res.text();
-      const content = raw.length > maxResponseBytes ? raw.slice(0, maxResponseBytes) + "\n\u2026[TRUNCATED]" : raw;
+      const content = byteLength2(raw) > maxResponseBytes ? raw.slice(0, maxResponseBytes) + "\n\u2026[TRUNCATED]" : raw;
       await invokeHook(opts.onResponse, {
         service: svc.name,
         method: input.method,
@@ -8648,7 +8821,21 @@ function createApiCallTool(opts) {
 function errResult(msg) {
   return { content: msg, isError: true };
 }
+function hasDotDotSegment(path) {
+  let decoded = path;
+  for (let i = 0; i < 2; i++) {
+    try {
+      const next = decodeURIComponent(decoded);
+      if (next === decoded) break;
+      decoded = next;
+    } catch {
+      break;
+    }
+  }
+  return /(^|[/\\])\.\.([/\\]|$)/.test(decoded);
+}
 function pathAllowed(path, allowed) {
+  if (hasDotDotSegment(path)) return false;
   if (!allowed || allowed.length === 0) return true;
   for (const a of allowed) {
     if (typeof a === "string") {
@@ -8680,6 +8867,25 @@ function resolveAllowedPaths(svc) {
   }
   return void 0;
 }
+var RESPONSE_HARD_CAP_BYTES = 25 * 1024 * 1024;
+function resolveSameOriginLink(nextLink, base) {
+  try {
+    const resolved = new URL(nextLink, base);
+    if (resolved.origin !== new URL(base).origin) return null;
+    return resolved.toString();
+  } catch {
+    return null;
+  }
+}
+function responseTooLarge(res) {
+  const cl = res.headers.get("content-length");
+  if (cl === null) return null;
+  const declared = Number.parseInt(cl, 10);
+  if (Number.isFinite(declared) && declared > RESPONSE_HARD_CAP_BYTES) {
+    return `ERR_API_RESPONSE_TOO_LARGE: upstream declared ${declared} bytes (hard cap ${RESPONSE_HARD_CAP_BYTES})`;
+  }
+  return null;
+}
 function byteLength2(s) {
   return new TextEncoder().encode(s).byteLength;
 }
@@ -8900,7 +9106,16 @@ async function executeAutoPaginated(args) {
         pageQuery[p.request.cursorParam] = nextCursor;
       }
     } else if (p.mode === "link-header") {
-      if (nextLink !== null) pageUrl = nextLink;
+      if (nextLink !== null) {
+        const safe = resolveSameOriginLink(nextLink, effectiveBaseUrl);
+        if (safe === null) break;
+        try {
+          if (!pathAllowed(new URL(safe).pathname, resolveAllowedPaths(svc))) break;
+        } catch {
+          break;
+        }
+        pageUrl = safe;
+      }
     }
     const url = pageUrl ?? buildUrl(effectiveBaseUrl, input.path, pageQuery);
     await invokeHook(args.onRequest, {
@@ -8917,7 +9132,9 @@ async function executeAutoPaginated(args) {
           ...svc.defaultHeaders ?? {},
           ...userHeaders,
           ...authHeaders
-        }
+        },
+        signal: AbortSignal.timeout(args.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS)
+        // WS-5c
       });
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
@@ -8930,6 +9147,16 @@ async function executeAutoPaginated(args) {
       });
     }
     lastStatus = res.status;
+    const tooLargePage = responseTooLarge(res);
+    if (tooLargePage !== null) {
+      return paginationErr({
+        code: "ERR_API_PAGINATION_PAGE_FAILED",
+        message: `${input.method} ${input.path} page ${pagesFetched + 1}: ${tooLargePage}`,
+        pagesFetched,
+        itemsFetched: aggregated.length,
+        partialItems: aggregated
+      });
+    }
     const raw = await res.text();
     const captured = raw.length > maxResponseBytes ? raw.slice(0, maxResponseBytes) + "\n\u2026[TRUNCATED]" : raw;
     await invokeHook(args.onResponse, {
@@ -10658,7 +10885,15 @@ var R2BindingStorageAdapter = class {
 var ENGINE_DATA_FOLDER = ".claude";
 var WORKSPACES_FOLDER = "workspaces";
 var KNOWLEDGE_FOLDER = "knowledge";
+function assertSafeWorkspaceId(workspaceId) {
+  if (!/^[A-Za-z0-9._-]+$/.test(workspaceId) || workspaceId === "." || workspaceId === "..") {
+    throw new StorageError(
+      `Invalid storage.workspaceId "${workspaceId}": must be non-empty and match [A-Za-z0-9._-] with no path separators or "."/".." traversal`
+    );
+  }
+}
 async function createEngineStorage(config, options = {}) {
+  assertSafeWorkspaceId(config.workspaceId);
   switch (config.provider) {
     case "local":
       return createLocalStorage(config, options);
@@ -10670,7 +10905,12 @@ async function createEngineStorage(config, options = {}) {
 }
 async function createLocalStorage(config, options) {
   const path = await import("path");
-  const tenantRoot = path.join(config.rootPath, WORKSPACES_FOLDER, config.workspaceId);
+  let rootPath = config.rootPath;
+  if (rootPath === "~" || rootPath.startsWith("~/")) {
+    const os = await import("os");
+    rootPath = path.join(os.homedir(), rootPath.slice(1));
+  }
+  const tenantRoot = path.join(rootPath, WORKSPACES_FOLDER, config.workspaceId);
   const workspaceRoot = path.join(tenantRoot, ENGINE_DATA_FOLDER);
   const out = { workspace: new LocalStorageAdapter(workspaceRoot) };
   if (options.withKnowledge) {
@@ -11153,7 +11393,7 @@ function extractPausedData(pending) {
 
 // src/engine/state.ts
 init_cjs_shims();
-var RunStateManager = class {
+var RunStateManager = class _RunStateManager {
   constructor(storage) {
     this.storage = storage;
   }
@@ -11161,9 +11401,24 @@ var RunStateManager = class {
   path(runId, nodeId) {
     return `projects/${runId}/nodes/${nodeId}/state.json`;
   }
+  /** A terminal status is final — once set it must never be overwritten. */
+  static isTerminal(status) {
+    return status === "done" || status === "failed" || status === "cancelled";
+  }
+  /**
+   * Persist a full state. Returns the persisted state so mutators can
+   * forward it. Deliberately NO read-before-write: `write` is on the hot
+   * path (heartbeat + every async-timing patch), so it must stay a single
+   * I/O — adding a read here measurably slowed the async lifecycle and
+   * widened existing read-modify-write windows. Terminal-status
+   * precedence (Engine 056 / WS-1c) lives in `finalize` instead — the
+   * only path that writes a terminal status, and one that already reads
+   * `current`, so the guard costs nothing extra there.
+   */
   async write(state) {
     const content = JSON.stringify(state, null, 2);
     await this.storage.writeFile(this.path(state.runId, state.nodeId), content);
+    return state;
   }
   async read(runId, nodeId) {
     try {
@@ -11184,8 +11439,7 @@ var RunStateManager = class {
       throw new Error(`RunStateManager.update: no state found for ${runId}/${nodeId}`);
     }
     const next = { ...current, ...patch };
-    await this.write(next);
-    return next;
+    return this.write(next);
   }
   /**
    * Merge async lifecycle timing fields into the durable state.
@@ -11201,8 +11455,7 @@ var RunStateManager = class {
       ...current,
       asyncTiming: { ...current.asyncTiming ?? {}, ...patch }
     };
-    await this.write(next);
-    return next;
+    return this.write(next);
   }
   async appendManualWebhookRetry(runId, nodeId, row) {
     const current = await this.read(runId, nodeId);
@@ -11216,8 +11469,7 @@ var RunStateManager = class {
       ...current,
       manualWebhookRetries: [...retries, row]
     };
-    await this.write(next);
-    return next;
+    return this.write(next);
   }
   /**
    * Update just the heartbeat + progress (cheap, called every turn).
@@ -11234,13 +11486,32 @@ var RunStateManager = class {
   }
   /**
    * Mark terminal state with response. Used at end of run/resume.
+   *
+   * Engine 056 / WS-1c: create-or-overwrite — does NOT throw when prior
+   * state is missing (a transient read failure in the start() catch path
+   * must still be able to record a terminal state rather than leaving the
+   * run stranded). When state exists its fields (webhook config, timing)
+   * are merged; otherwise a minimal base is synthesized.
+   *
+   * Also sets the `webhookPending` outbox marker (WS-1b) in the same write
+   * iff a webhook is configured and this status is a subscribed event.
    */
   async finalize(runId, nodeId, response) {
-    return this.update(runId, nodeId, {
-      status: response.status === "done" ? "done" : response.status === "paused" ? "paused" : "failed",
+    const status = response.status === "done" ? "done" : response.status === "paused" ? "paused" : "failed";
+    const current = await this.read(runId, nodeId);
+    if (current !== null && _RunStateManager.isTerminal(current.status) && current.status !== status) {
+      return current;
+    }
+    const base = current ?? _RunStateManager.initial(runId, nodeId);
+    const webhookPending = base.webhook !== void 0 && base.webhook.events.includes(status);
+    const next = {
+      ...base,
+      status,
       lastHeartbeat: Date.now(),
-      response
-    });
+      response,
+      webhookPending
+    };
+    return this.write(next);
   }
   /**
    * List all state files under a runId (one per node). Returns empty array
@@ -11263,6 +11534,14 @@ var RunStateManager = class {
   /**
    * Scan all state files and return those with stale heartbeats.
    * Used by recoverOrphanedRuns().
+   *
+   * Engine 056 / WS-1a: includes stale `queued` as well as `running`. A
+   * run can be stranded in `queued` when the initial `running` write (or
+   * the scheduled background work) fails after `start()` returns — its
+   * heartbeat never advances past creation, so a `queued` state older than
+   * the threshold is orphaned and must be recoverable. `paused` is
+   * intentionally excluded (human-in-the-loop waits are legitimately
+   * long-lived; the orchestrator reconciles those separately).
    */
   async findOrphaned(staleThresholdMs) {
     const projectsRoot = "projects";
@@ -11273,7 +11552,8 @@ var RunStateManager = class {
       for (const runId of runIds) {
         const states = await this.scanRun(runId);
         for (const state of states) {
-          if (state.status === "running" && now - state.lastHeartbeat > staleThresholdMs) {
+          const recoverable = state.status === "running" || state.status === "queued";
+          if (recoverable && now - state.lastHeartbeat > staleThresholdMs) {
             orphaned.push(state);
           }
         }
@@ -11340,8 +11620,12 @@ var NodeBackgroundExecutor = class {
 // src/engine/webhook.ts
 init_cjs_shims();
 var RETRY_DELAYS_MS = [
-  0
-  // attempt 1: immediate (Plan 046 — single attempt only)
+  0,
+  // attempt 1: immediate
+  300,
+  // attempt 2: +300ms
+  1200
+  // attempt 3: +1.2s
 ];
 var MAX_ATTEMPTS = RETRY_DELAYS_MS.length;
 async function signPayload(secret, timestamp, body) {
@@ -11443,6 +11727,41 @@ var WebhookDispatcher = class {
 };
 
 // src/engine/engine.ts
+var HANDOFF_POST_TIMEOUT_MS = 3e4;
+function buildUnpairedSiblingResults(messages, pendingId) {
+  let lastAssistant;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i]?.role === "assistant") {
+      lastAssistant = messages[i];
+      break;
+    }
+  }
+  if (lastAssistant === void 0 || !Array.isArray(lastAssistant.content)) return [];
+  const toolUseIds = [];
+  for (const block of lastAssistant.content) {
+    const b = block;
+    if (b.type === "tool_use" && typeof b.id === "string") toolUseIds.push(b.id);
+  }
+  const resolved = /* @__PURE__ */ new Set();
+  for (const m of messages) {
+    if (!Array.isArray(m.content)) continue;
+    for (const block of m.content) {
+      const b = block;
+      if (b.type === "tool_result" && typeof b.tool_use_id === "string") resolved.add(b.tool_use_id);
+    }
+  }
+  const blocks = [];
+  for (const id of toolUseIds) {
+    if (id === pendingId || resolved.has(id)) continue;
+    blocks.push({
+      type: "tool_result",
+      tool_use_id: id,
+      content: "[not executed \u2014 the run paused on a sibling tool call in the same turn; this tool was never dispatched]",
+      is_error: true
+    });
+  }
+  return blocks;
+}
 var Engine = class {
   config;
   internals;
@@ -11656,6 +11975,18 @@ var Engine = class {
         logPath,
         ...capabilitiesMissing.length > 0 ? { capabilitiesMissing } : {}
       });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      await writer.setStatus("failed").catch(() => {
+      });
+      return {
+        runId,
+        status: "failed",
+        data: null,
+        meta: { nodeId: options.nodeId, durationMs: Date.now() - startTime },
+        errors: [{ code: "ERR_RUN_FAILED", message }],
+        timestamp: Date.now()
+      };
     } finally {
       runTimeout.clear();
       await writer.close();
@@ -11814,6 +12145,7 @@ var Engine = class {
       });
       if (snapshot.pendingToolCall) {
         const pending = snapshot.pendingToolCall;
+        const siblingBlocks = buildUnpairedSiblingResults(ctx.getMessages(), pending.toolUseId);
         if (snapshot.pauseReason === "awaiting_tool_result") {
           if (options.toolResult === void 0) {
             throw new EngineError(
@@ -11827,14 +12159,33 @@ var Engine = class {
               `toolResult.id "${options.toolResult.id}" does not match pending toolUseId "${pending.toolUseId}" \u2014 resume aborted`
             );
           }
-          await ctx.addToolResult(
-            pending.toolUseId,
-            options.toolResult.content,
-            options.toolResult.isError ?? false
-          );
+          if (siblingBlocks.length === 0) {
+            await ctx.addToolResult(
+              pending.toolUseId,
+              options.toolResult.content,
+              options.toolResult.isError ?? false
+            );
+          } else {
+            await ctx.addMixedUserMessage([
+              {
+                type: "tool_result",
+                tool_use_id: pending.toolUseId,
+                content: options.toolResult.content,
+                ...options.toolResult.isError === true ? { is_error: true } : {}
+              },
+              ...siblingBlocks
+            ]);
+          }
         } else if (options.gateAnswer !== void 0) {
           const answer = typeof options.gateAnswer === "string" ? options.gateAnswer : JSON.stringify(options.gateAnswer);
-          await ctx.addToolResult(pending.toolUseId, answer, false);
+          if (siblingBlocks.length === 0) {
+            await ctx.addToolResult(pending.toolUseId, answer, false);
+          } else {
+            await ctx.addMixedUserMessage([
+              { type: "tool_result", tool_use_id: pending.toolUseId, content: answer },
+              ...siblingBlocks
+            ]);
+          }
         } else {
           const inputJson = JSON.stringify(pending.input ?? {}, null, 2);
           await ctx.addMixedUserMessage([
@@ -11843,6 +12194,7 @@ var Engine = class {
               tool_use_id: pending.toolUseId,
               content: `APPROVAL_GATE_RELEASED: the prior ${pending.toolName} call was paused for human approval and has now been approved. Retry is required.`
             },
+            ...siblingBlocks,
             {
               type: "text",
               text: `The human has approved the paused ${pending.toolName} tool call. You MUST now re-issue the EXACT same tool call to complete the work \u2014 do not change the arguments, do not answer in text, do not declare the task done. Approved arguments (copy verbatim):
@@ -11983,8 +12335,8 @@ ${inputJson}
         backgroundStartedAt: Date.now()
       });
       if (signal.aborted) return;
-      await stateManager.update(runId, options.nodeId, { status: "running" });
       try {
+        await stateManager.update(runId, options.nodeId, { status: "running" });
         await this.recordAsyncTiming(stateManager, runId, options.nodeId, {
           runCallStartedAt: Date.now()
         });
@@ -12329,12 +12681,12 @@ ${inputJson}
         completedAt: Date.now()
       });
     } catch (err) {
-      const errorMessage = err instanceof Error ? err.message : String(err);
+      const errorMessage2 = err instanceof Error ? err.message : String(err);
       await this.recordManualWebhookRetry(stateManager, runId, targetNodeId, {
         deliveryId,
         startedAt: retryStartedAt,
         completedAt: Date.now(),
-        errorMessage
+        errorMessage: errorMessage2
       });
       throw err;
     }
@@ -12409,7 +12761,8 @@ ${inputJson}
         body: JSON.stringify({
           runId,
           workspaceId: this.config.storage.workspaceId
-        })
+        }),
+        signal: AbortSignal.timeout(HANDOFF_POST_TIMEOUT_MS)
       });
       if (!res.ok) {
         return {
@@ -12457,11 +12810,29 @@ ${inputJson}
     } catch {
     }
   }
+  /**
+   * Engine 056 / WS-1b: read state.json with a few retries. `read` maps
+   * ALL errors (incl. transient storage failures) to `null`; at webhook
+   * time the terminal state was just written by `finalize`, so a `null`
+   * here is far more likely a transient read than a genuinely-absent
+   * state. Without this, a single blip silently drops the webhook with no
+   * trace — a stuck node. Returns `null` only if every attempt comes back
+   * empty (then the run is left terminal + `webhookPending` for the
+   * caller's reconciler).
+   */
+  async readStateResilient(stateManager, runId, nodeId, attempts = 3) {
+    for (let i = 0; i < attempts; i++) {
+      const s = await stateManager.read(runId, nodeId);
+      if (s !== null) return s;
+      if (i < attempts - 1) await new Promise((r) => setTimeout(r, 100));
+    }
+    return null;
+  }
   async maybeFireWebhook(stateManager, runId, nodeId, response) {
     await this.recordAsyncTiming(stateManager, runId, nodeId, {
       webhookCheckStartedAt: Date.now()
     });
-    const state = await stateManager.read(runId, nodeId);
+    const state = await this.readStateResilient(stateManager, runId, nodeId);
     if (state === null || state.webhook === void 0) return;
     const event = response.status === "done" ? "done" : response.status === "paused" ? "paused" : "failed";
     if (!state.webhook.events.includes(event)) return;
@@ -12500,7 +12871,10 @@ ${inputJson}
           ...latest.webhook,
           deliveries: [...latest.webhook.deliveries, result.delivery]
         };
-        await stateManager.update(runId, nodeId, { webhook: updated });
+        await stateManager.update(runId, nodeId, {
+          webhook: updated,
+          webhookPending: result.delivery.status !== "delivered"
+        });
         await this.recordAsyncTiming(stateManager, runId, nodeId, {
           webhookStatePersistedAt: Date.now()
         });