@ziggs-ai/agent-sdk 0.10.8 → 0.11.1

package/dist/adapters/McpAdapter.js

@@ -1,11 +1,11 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
-import { ConnectionsClient } from '@ziggs-ai/api-client';
+import { ConnectionsClient, getBackendUrl } from '@ziggs-ai/api-client';
 import { AgentHost } from '../AgentHost.js';
 import { thinkingDefaults } from '../runtime/defaults.js';
 /**
- * Typed failure from the Ziggs MCP gateway (ZIG-702). `code` is the stable
+ * Typed failure from the Ziggs MCP gateway. `code` is the stable
  * machine-readable reason — e.g. `GRANT_REVOKED`, `GRANT_EXPIRED`,
  * `GRANT_HOLDER_MISMATCH`, `GRANT_CONNECTION_MISMATCH` — so agent code can
  * branch ("revoked → tell the user and stop retrying" vs "network blip →
@@ -56,10 +56,15 @@ export function resolveZiggsGatewayTarget(config, defaults = {}) {
     if (!agentId) {
         throw new Error('ziggs MCP transport requires an agentId to impersonate (X-Agent-Id)');
     }
+    // Explicit overrides still win, but the LAST resort is `getBackendUrl()` —
+    // the resolution every other SDK call uses — not `localhost:3000`. A deployment
+    // that sets none of BACKEND_URL / ZIGGS_BACKEND_URL would otherwise have every
+    // gateway call silently point at localhost inside its own container: the
+    // requests never reach the backend, and the agent reports it as unreachable.
     const baseUrl = (config.baseUrl ||
-        process.env.BACKEND_URL ||
         process.env.ZIGGS_BACKEND_URL ||
-        'http://localhost:3000').replace(/\/$/, '');
+        process.env.BACKEND_URL ||
+        getBackendUrl()).replace(/\/$/, '');
     return {
         url: new URL(`${baseUrl}/connections/${encodeURIComponent(config.connectionId)}/mcp`),
         headers: {
@@ -70,7 +75,7 @@ export function resolveZiggsGatewayTarget(config, defaults = {}) {
     };
 }
 /**
- * Resolve the per-user gateway URL + headers (ZIG-771). No connectionId/grantId —
+ * Resolve the per-user gateway URL + headers. No connectionId/grantId —
  * the gateway resolves the invoking user's own connection + grant from
  * `x-on-behalf-of-user` + the impersonated agent.
  */
@@ -79,17 +84,22 @@ export function resolvePerUserGatewayTarget(config, agentId, userId, onBehalfOfA
     if (!operatorKey) {
         throw new Error('ziggs-per-user MCP transport requires an operatorKey (or ZIGGS_OPERATOR_KEY)');
     }
+    // Explicit overrides still win, but the LAST resort is `getBackendUrl()` —
+    // the resolution every other SDK call uses — not `localhost:3000`. A deployment
+    // that sets none of BACKEND_URL / ZIGGS_BACKEND_URL would otherwise have every
+    // gateway call silently point at localhost inside its own container: the
+    // requests never reach the backend, and the agent reports it as unreachable.
     const baseUrl = (config.baseUrl ||
-        process.env.BACKEND_URL ||
         process.env.ZIGGS_BACKEND_URL ||
-        'http://localhost:3000').replace(/\/$/, '');
+        process.env.BACKEND_URL ||
+        getBackendUrl()).replace(/\/$/, '');
     return {
         url: new URL(`${baseUrl}/connections/mcp/relay`),
         headers: {
             authorization: `Bearer ${operatorKey}`,
             'x-agent-id': agentId,
             'x-on-behalf-of-user': userId,
-            // ZIG-831: when this call runs under a delegation, userId is the delegating
+            // when this call runs under a delegation, userId is the delegating
             // agent (senderId), not the end-user who owns the connection. The gateway
             // uses this agreement to resolve the delegation root's user.
             ...(onBehalfOfAgreementId ? { 'x-on-behalf-of-agreement': onBehalfOfAgreementId } : {}),
@@ -103,7 +113,7 @@ const CONTROL_TOOL_RESERVE = 4;
 /**
  * How many MCP tools may be bound to the LLM, given the provider cap and the
  * number of extra (non-MCP) tools the agent also carries. Always >= 1 so a
- * pathological config still binds something rather than nothing. ZIG-759.
+ * pathological config still binds something rather than nothing.
  */
 export function mcpToolBudget(maxTools, extraToolCount) {
     return Math.max(1, maxTools - CONTROL_TOOL_RESERVE - extraToolCount);
@@ -218,7 +228,7 @@ function buildDefaultWorkflow(description, mcpTools) {
  * that full block rides every turn. Keep the lead — what the tool does + how to
  * call it — and drop the embedded reference; agents fetch detail via dedicated
  * schema/help tools at call time. Tunable; big enough to preserve real guidance.
- * ZIG-759.
+ *.
  */
 export const MAX_TOOL_DESC_CHARS = 2000;
 /** Truncate one description at a sentence/newline boundary near the cap. */
@@ -230,7 +240,7 @@ export function trimDescription(desc) {
     const head = boundary > MAX_TOOL_DESC_CHARS * 0.6 ? slice.slice(0, boundary + 1) : slice;
     return `${head.trimEnd()} […description truncated; use the server's schema/help tools for full detail]`;
 }
-/** Trim oversized descriptions across the tool set (cost control, ZIG-759). */
+/** Trim oversized descriptions across the tool set (cost control). */
 function trimToolDescriptions(tools, agentId) {
     let trimmedCount = 0;
     let savedChars = 0;
@@ -243,14 +253,14 @@ function trimToolDescriptions(tools, agentId) {
         return { ...t, description: nextDesc };
     });
     if (trimmedCount > 0) {
-        console.warn(`[McpAdapter] ${agentId}: trimmed ${trimmedCount} oversized tool description(s) to ${MAX_TOOL_DESC_CHARS} chars, saving ~${Math.round(savedChars / 4 / 1000)}K tokens/turn. (ZIG-759)`);
+        console.warn(`[McpAdapter] ${agentId}: trimmed ${trimmedCount} oversized tool description(s) to ${MAX_TOOL_DESC_CHARS} chars, saving ~${Math.round(savedChars / 4 / 1000)}K tokens/turn.`);
     }
     return out;
 }
 /**
  * Keep only tools whose name matches one of the allowlist substrings
  * (case-insensitive). No allowlist → pass through unchanged. Applied before the
- * maxTools cap so a targeted agent binds exactly the tools it needs. ZIG-759.
+ * maxTools cap so a targeted agent binds exactly the tools it needs.
  */
 function filterToolsByAllowlist(tools, allowedTools, agentId) {
     if (!allowedTools || allowedTools.length === 0)
@@ -263,7 +273,7 @@ function filterToolsByAllowlist(tools, allowedTools, agentId) {
 /**
  * Cap the tool set bound to the LLM at the provider limit (OpenAI 128) —
  * truncate and log rather than crash — and trim oversized descriptions so the
- * bound schema doesn't ship a manual every turn. ZIG-759 Phase 1. Shared by the
+ * bound schema doesn't ship a manual every turn. Phase 1. Shared by the
  * boot-time (single-client) and per-user paths. When `allowedTools` is set the
  * server's tools are narrowed by name first, so the cap rarely bites.
  */
@@ -273,7 +283,7 @@ function capTools(tools, agentId, maxTools, extraToolCount, allowedTools) {
     const budget = mcpToolBudget(maxTools, extraToolCount);
     if (trimmed.length <= budget)
         return trimmed;
-    console.warn(`[McpAdapter] ${agentId}: MCP server exposes ${trimmed.length} tools, over the ${maxTools}-tool LLM cap; binding the first ${budget}, dropping ${trimmed.length - budget}. (ZIG-759 Phase 2 will select per query.)`);
+    console.warn(`[McpAdapter] ${agentId}: MCP server exposes ${trimmed.length} tools, over the ${maxTools}-tool LLM cap; binding the first ${budget}, dropping ${trimmed.length - budget}.`);
     return trimmed.slice(0, budget);
 }
 /**
@@ -311,7 +321,7 @@ function capTools(tools, agentId, maxTools, extraToolCount, allowedTools) {
  */
 export async function createMcpAgent(options) {
     const { transport: transportConfig, extraTools = [], workflow, maxTools = DEFAULT_MAX_TOOLS, allowedTools, toolSchema, ...hostOptions } = options;
-    // ── Per-user path (ZIG-771): no boot connection; one MCP client per invoking
+    // ── Per-user path: no boot connection; one MCP client per invoking
     // user, each carrying that user's on-behalf-of header for an isolated session.
     if (transportConfig.type === 'ziggs-per-user') {
         const agentId = transportConfig.agentId || hostOptions.agentId;
@@ -351,12 +361,12 @@ export async function createMcpAgent(options) {
         // When the invoking user hasn't connected this server, open a connection
         // request targeting THEM (X-On-Behalf-Of-User) so the consent prompt lands
         // in their inbox. The backend dedups pending requests, so retrying every
-        // turn is safe. ZIG-771.
+        // turn is safe.
         const backendBase = (transportConfig.baseUrl ||
             process.env.BACKEND_URL ||
             process.env.ZIGGS_BACKEND_URL ||
             'http://localhost:3000').replace(/\/$/, '');
-        // App URL for the user-facing connect link (ZIG-790): api.ziggsai.com → ziggsai.com.
+        // App URL for the user-facing connect link: api.ziggsai.com → ziggsai.com.
         const appUrl = backendBase.includes('localhost')
             ? 'http://localhost:1234'
             : backendBase.replace(/\/\/api\./, '//');
@@ -364,7 +374,7 @@ export async function createMcpAgent(options) {
             ? new URL(transportConfig.serverUrl).host
             : 'the external service';
         // Open a connection request for this user; returns its id so the caller can
-        // deep-link the user straight to it on the Connections page (ZIG-790).
+        // deep-link the user straight to it on the Connections page.
         const triggerConnectionRequest = async (userId) => {
             if (!transportConfig.serverUrl)
                 return null;
@@ -390,11 +400,11 @@ export async function createMcpAgent(options) {
             if (!userId) {
                 throw new Error('per-user MCP tool call requires an invoking user (context.senderId is missing)');
             }
-            // ZIG-831: for a delegated wake, senderId is the delegating agent, not the
+            // for a delegated wake, senderId is the delegating agent, not the
             // connection-owning end-user; pass the agreement so the gateway resolves
             // the delegation root's user.
             const onBehalfOfAgreementId = typeof context.onBehalfOfAgreementId === 'string' ? context.onBehalfOfAgreementId : undefined;
-            // ZIG-832 (B): per-user resolution is intermittently flaky even when the
+            // (B): per-user resolution is intermittently flaky even when the
             // connection is valid and resolvable — the same on-behalf call fails with
             // NO_USER_CONNECTION on one wake and succeeds on the next. clientFor never
             // caches a failed connect, so each attempt re-resolves from scratch. Retry

package/dist/adapters/OpenAIAdapter.js

@@ -137,7 +137,7 @@ export class OpenAIAdapter {
             stream: true,
             // Without this, a streamed completion never returns a usage block — the
             // streamed reply (often the largest output) would bill tokens that are
-            // counted nowhere (ZIG-813). The usage arrives on a final chunk whose
+            // counted nowhere. The usage arrives on a final chunk whose
             // `choices` is empty.
             stream_options: { include_usage: true },
             max_completion_tokens: maxCompletionTokensForModel(this.model),

package/dist/agent/Agent.d.ts

@@ -25,7 +25,7 @@ export interface TickInput {
      * choice — `counterparty:<id>`, `agreement:<id>:notes`, etc.
      */
     memory?: MemoryStore;
-    /** Optional tap for FSM transition events (ZIG-442). */
+    /** Optional tap for FSM transition events. */
     transitionTap?: (event: TransitionEvent) => void;
     /**
      * Aborted by the host when the tick watchdog fires. A brain driving an
@@ -49,7 +49,7 @@ export interface TickOutput {
     /**
      * Accumulated LLM call count and token usage for this tick.
      * `cacheRead` / `cacheCreation` are populated by the Claude brain (its usage
-     * exposes cache traffic, which is the bulk of real cost — ZIG-759/813); the
+     * exposes cache traffic, which is the bulk of real cost/813); the
      * FSM path leaves them undefined. `total` includes cache tokens when present.
      */
     metrics: {

package/dist/agent/ClaudeSdkAgent.d.ts

@@ -4,7 +4,7 @@ import type { ToolManager } from '../tools/ToolManager.js';
 import { type RawEvent } from '../runtime/buildOutcome.js';
 import type { TickInput, TickOutput } from './Agent.js';
 /**
- * ZIG-1035 / ZIG-1052: status notices must not spend a Claude turn answering
+ * status notices must not spend a Claude turn answering
  * nobody. Real work wakes arrive as chat `message`, synthetic `task_result`
  * from `wakeTaskAssignment`, or `agreement_lifecycle` (hire / proposal
  * resolution — the FSM kickoffs on the same event; Claude must act too).
@@ -28,7 +28,7 @@ export interface ClaudeSdkAgentOptions {
     toolManager: ToolManager;
     /** Store-facing one-liner. Used as the role block only when `systemPrompt` is absent. */
     description: string;
-    /** The agent's system prompt (ZIG-1080). Preferred over `description` for the role block. */
+    /** The agent's system prompt. Preferred over `description` for the role block. */
     systemPrompt?: string;
     specialization?: string | null;
     model: string;
@@ -36,7 +36,7 @@ export interface ClaudeSdkAgentOptions {
     operatorKey: string;
     agentId: string;
     maxTurns?: number;
-    /** ZIG-860: when true, never resume the prior Claude session — each wake is a
+    /** when true, never resume the prior Claude session — each wake is a
      *  fresh transcript. Keeps per-wake input flat on step-driven orchestrators
      *  whose wakes already carry their state. */
     statelessPerWake?: boolean;
@@ -44,7 +44,7 @@ export interface ClaudeSdkAgentOptions {
     queryFn?: typeof query;
 }
 /**
- * ZIG-1191 — "the transcript you asked me to resume is not here".
+ * "the transcript you asked me to resume is not here".
  *
  * Claude Code answers a `resume` of an unknown id with this, and it is the only
  * failure that a fresh session reliably fixes: the id is valid-looking but its
@@ -52,12 +52,21 @@ export interface ClaudeSdkAgentOptions {
  * that is all the CLI gives us — no code, no typed error — so keep it narrow
  * enough that a different failure never claims the retry.
  */
+/**
+ * "I ran out of turns", as Claude Code reports it.
+ *
+ * Turn exhaustion is not a crash: the wake did real work and stopped at a cap
+ * we set. It arrives as a thrown error result with no code and no type, so the
+ * message is all there is to match on — kept narrow so no other failure claims
+ * the handling.
+ */
+export declare function isMaxTurnsError(err: unknown): boolean;
 export declare function isMissingSessionError(err: unknown): boolean;
 /**
  * A Ziggs agent whose brain is the Claude Agent SDK. Same host, same `eff`
  * side channel, same tool surface as the FSM `Agent` — the ONLY difference is
  * the loop: instead of the FSM + `runTurn`, a wake drives a headless Claude
- * `query()` (see ZIG-784: "host is the product; the brain is how it decides").
+ * `query()` (see "host is the product; the brain is how it decides").
  */
 export declare class ClaudeSdkAgent {
     workflow: Workflow;
@@ -72,7 +81,7 @@ export declare class ClaudeSdkAgent {
     private statelessPerWake;
     private queryFn;
     /**
-     * ZIG-1120 #7 — tool set is fixed at host construction; rebuilding the
+     * #7 — tool set is fixed at host construction; rebuilding the
      * in-process MCP server (+ zod schema tree) every wake was pure waste.
      * A mutable holder supplies per-wake context without closing over `tick`.
      */

package/dist/agent/ClaudeSdkAgent.js

@@ -9,7 +9,7 @@ import { claudeQueryOptions, buildClaudeEventPrompt, summarizeContext, extractAs
 import { assertHostedAgentZiggsTools } from './hostedAgentConnection.js';
 import { runtimeLog } from '../shared/runtimeLog.js';
 /**
- * ZIG-1035 / ZIG-1052: status notices must not spend a Claude turn answering
+ * status notices must not spend a Claude turn answering
  * nobody. Real work wakes arrive as chat `message`, synthetic `task_result`
  * from `wakeTaskAssignment`, or `agreement_lifecycle` (hire / proposal
  * resolution — the FSM kickoffs on the same event; Claude must act too).
@@ -35,30 +35,34 @@ export function isNoticeOnlyWake(event, ownAgentId) {
 }
 const DEFAULT_STATE = 'ready';
 /**
- * Per-task turn cap. A wake drives one `query()` that may loop up to this many
- * internal turns; the tool schema + system prompt ride every turn, so this is
- * the direct multiplier on a task's token spend. 30 let a confused MCP agent
- * burn schema×30 per wake; brokered tasks (fetch → record → done) converge in a
- * handful of turns, so 12 is ample. Env-overridable (raise for genuinely long
- * agents). ZIG-759. */
-const DEFAULT_MAX_TURNS = Number(process.env.CLAUDE_SDK_MAX_TURNS ?? 12);
+ * Per-wake turn cap — a runaway backstop, NOT a budget.
+ *
+ * Cost is bounded by the priced spend guard below, so this only has to sit above
+ * the longest honest job, with room for a retry inside it. A job that gathers
+ * before it works — reading the engagement, listing grants, discovering a
+ * connection's tools, pulling the data — spends around ten turns before it
+ * starts on the work it was hired for, then needs several more to draft, record
+ * the artifact and close the task. Set below that, the cap ends wakes with the
+ * gathering done and nothing filed.
+ */
+const DEFAULT_MAX_TURNS = Number(process.env.CLAUDE_SDK_MAX_TURNS ?? 30);
 /**
  * Hard ceiling on billable input tokens (incl. cache read/write) a single wake
- * may spend before we abort the query. Defense-in-depth on the shared fleet key
+ * may spend before we abort the query. Defense-in-depth on the host's LLM key
  * against a runaway loop; set high enough that normal tasks never trip it. The
- * task ends unfinished (and logs loudly) rather than burning unbounded. ZIG-759. */
+ * task ends unfinished (and logs loudly) rather than burning unbounded. */
 const MAX_TASK_INPUT_TOKENS = Number(process.env.CLAUDE_SDK_MAX_INPUT_TOKENS ?? 500_000);
 /**
  * Per-lane wake-rate circuit breaker. The per-wake caps above bound one wake;
- * nothing bounded the NUMBER of wakes — the agent-private artifact echo drove
- * one wake per wake, forever. The echo is fixed at the source (backend
- * targeting never routes an agent its own writes), so this is a backstop for
- * any future echo path: a lane waking faster than real traffic plausibly drives it
- * skips the LLM (and logs loudly) instead of draining the fleet key. */
+ * nothing bounds the NUMBER of wakes. An echo path — anything that turns an
+ * agent's own write back into a delivery addressed to it — drives one wake per
+ * wake, forever. Targeting never routes an agent its own writes, so this is a
+ * backstop: a lane waking faster than real traffic plausibly drives it skips the
+ * LLM (and logs loudly) instead of draining the key. */
 const WAKE_WINDOW_MS = 10 * 60_000;
 const MAX_WAKES_PER_WINDOW = Number(process.env.CLAUDE_SDK_MAX_WAKES_PER_WINDOW ?? 40);
 /**
- * Resumed-transcript ceiling (ZIG-816). Each wake resumes the lane's Claude
+ * Resumed-transcript ceiling. Each wake resumes the lane's Claude
  * session, so the whole transcript (event prompts, tool results, summaries)
  * replays on every turn — mostly as cache reads, but it grows without bound on
  * a long-lived lane and dominates per-wake cost. When a wake's billable input
@@ -69,7 +73,7 @@ const MAX_WAKES_PER_WINDOW = Number(process.env.CLAUDE_SDK_MAX_WAKES_PER_WINDOW
  * before it can approach the per-wake abort. */
 const MAX_SESSION_RESUME_INPUT_TOKENS = Number(process.env.CLAUDE_SDK_MAX_SESSION_INPUT_TOKENS ?? 200_000);
 /**
- * ZIG-1191 — "the transcript you asked me to resume is not here".
+ * "the transcript you asked me to resume is not here".
  *
  * Claude Code answers a `resume` of an unknown id with this, and it is the only
  * failure that a fresh session reliably fixes: the id is valid-looking but its
@@ -77,6 +81,19 @@ const MAX_SESSION_RESUME_INPUT_TOKENS = Number(process.env.CLAUDE_SDK_MAX_SESSIO
  * that is all the CLI gives us — no code, no typed error — so keep it narrow
  * enough that a different failure never claims the retry.
  */
+/**
+ * "I ran out of turns", as Claude Code reports it.
+ *
+ * Turn exhaustion is not a crash: the wake did real work and stopped at a cap
+ * we set. It arrives as a thrown error result with no code and no type, so the
+ * message is all there is to match on — kept narrow so no other failure claims
+ * the handling.
+ */
+export function isMaxTurnsError(err) {
+    const message = err?.message;
+    return (typeof message === 'string' &&
+        /reached maximum number of turns/i.test(message));
+}
 export function isMissingSessionError(err) {
     const message = err?.message;
     return (typeof message === 'string' &&
@@ -90,6 +107,32 @@ function billableInput(usage) {
         (usage.cache_read_input_tokens ?? 0) +
         (usage.cache_creation_input_tokens ?? 0));
 }
+/**
+ * The same tokens, priced.
+ *
+ * A cache READ bills at ~0.1x base input and a cache WRITE at ~1.25x. The spend
+ * guard below exists to stop a runaway from draining the key, so it has to count
+ * what the key is actually charged — and counting a cache read as a full input
+ * token makes every multi-turn wake look like a runaway. The transcript replays
+ * on every turn, so a 40k context over ten turns reads as 400k of "spend" while
+ * costing about a tenth of that: unpriced, the guard fires on ordinary work long
+ * before any runaway would, and it fires mid-job — right after the gathering
+ * calls and before the deliverable, which is the whole of "the wake ends before
+ * it files anything".
+ *
+ * Weights, not prices: the ratio between the three input kinds is stable across
+ * Claude models even as the per-million rates change, so this stays right
+ * without tracking a price table.
+ */
+const CACHE_READ_WEIGHT = 0.1;
+const CACHE_WRITE_WEIGHT = 1.25;
+function costWeightedInput(usage) {
+    if (!usage)
+        return 0;
+    return ((usage.input_tokens ?? 0) +
+        (usage.cache_read_input_tokens ?? 0) * CACHE_READ_WEIGHT +
+        (usage.cache_creation_input_tokens ?? 0) * CACHE_WRITE_WEIGHT);
+}
 /**
  * Per-API-call usage. Only assistant turns carry it — the result message's
  * usage is the CUMULATIVE total of the whole query, so adding it on top of
@@ -106,12 +149,12 @@ function extractMetrics(message) {
         return null;
     const usage = message.usage;
     // Billable input includes cache reads/writes — that is what the Anthropic
-    // console counts and what the fleet key pays for. Reporting only the
-    // uncached slice made our telemetry read ~10-20x under the real usage.
+    // console counts and what the key is charged for. Reporting only the uncached
+    // slice understates real usage by more than an order of magnitude.
     const input = billableInput(usage);
     const output = usage?.output_tokens ?? 0;
     // Cache read/write are already folded into `input` above; surfaced separately
-    // here for per-tick visibility (metricsTap metadata / dashboards, ZIG-813).
+    // here for per-tick visibility (metricsTap metadata / dashboards).
     const cacheRead = usage?.cache_read_input_tokens ?? 0;
     const cacheCreation = usage?.cache_creation_input_tokens ?? 0;
     return {
@@ -121,8 +164,8 @@ function extractMetrics(message) {
     };
 }
 /**
- * Resolve the agreement this wake acts under, for a delegated per-user MCP call
- * (ZIG-831/832). Without it the gateway resolves the connection owner from
+ * Resolve the agreement this wake acts under, for a delegated per-user MCP
+ * call. Without it the gateway resolves the connection owner from
  * `senderId` — which, under a delegation, is the delegating agent (who owns no
  * connection) → a spurious NO_USER_CONNECTION even though the payer IS connected.
  *
@@ -130,7 +173,7 @@ function extractMetrics(message) {
  * `task_result` events. In practice the worker often fetches while reacting to
  * the proposal-approved / agreement-active lifecycle events, which carry the id
  * at the event top level rather than under `result`. Reading only
- * `result.agreementId` (the original ZIG-831 wiring) left those wakes with no
+ * `result.agreementId` (the original wiring) left those wakes with no
  * agreement → the false "authorize your connection" prompt. Resolve from every
  * reliable source instead:
  *   1. task_result events → `result.agreementId`
@@ -170,7 +213,7 @@ function resolveOnBehalfAgreementId(rawEvent, contextSnap, agentId, sessionId) {
  * A Ziggs agent whose brain is the Claude Agent SDK. Same host, same `eff`
  * side channel, same tool surface as the FSM `Agent` — the ONLY difference is
  * the loop: instead of the FSM + `runTurn`, a wake drives a headless Claude
- * `query()` (see ZIG-784: "host is the product; the brain is how it decides").
+ * `query()` (see "host is the product; the brain is how it decides").
  */
 export class ClaudeSdkAgent {
     workflow;
@@ -185,7 +228,7 @@ export class ClaudeSdkAgent {
     statelessPerWake;
     queryFn;
     /**
-     * ZIG-1120 #7 — tool set is fixed at host construction; rebuilding the
+     * #7 — tool set is fixed at host construction; rebuilding the
      * in-process MCP server (+ zod schema tree) every wake was pure waste.
      * A mutable holder supplies per-wake context without closing over `tick`.
      */
@@ -200,7 +243,7 @@ export class ClaudeSdkAgent {
             throw new Error('ClaudeSdkAgent: anthropicKey is required');
         this.workflow = opts.workflow;
         this.toolManager = opts.toolManager;
-        // ZIG-1080: the prompt and the store blurb are two different strings. Agents
+        // the prompt and the store blurb are two different strings. Agents
         // written before the split still carry the prompt in `description`, so fall
         // back to it rather than silently dropping their role.
         this.rolePrompt = opts.systemPrompt || opts.description;
@@ -249,7 +292,7 @@ export class ClaudeSdkAgent {
         }
         let contextSnap = null;
         try {
-            // ZIG-1120 #5: pre-read is for wake gating + summarizeContext (a count) +
+            // #5: pre-read is for wake gating + summarizeContext (a count) +
             // onBehalf agreement resolution — same 12-message cap as the tool path.
             // Uncapped pulls burned 35–47k input tokens/wake on long chats.
             contextSnap = await eff({
@@ -265,7 +308,7 @@ export class ClaudeSdkAgent {
         // no longer resolves (deleted / not visible) has no world to act in —
         // skip the query instead of burning a wake on a fabricated empty history.
         //
-        // ZIG-975: a bare agreement id (`agr_…`, not the `agrn-…` notification
+        // a bare agreement id (`agr_…`, not the `agrn-…` notification
         // chat) is not a chat. If a wake still keys the lane that way, read-context
         // returns chatMissing and used to continue on an empty snapshot with no
         // signal. Loud-log that mis-key; message wakes still skip below.
@@ -297,7 +340,7 @@ export class ClaudeSdkAgent {
             this.specialization ? `Specialization: ${this.specialization}` : '',
         ].filter(Boolean).join('\n');
         // Two blocks, not one string: the shared protocol first so its cache prefix
-        // is reachable by every hosted agent, this agent's role second (ZIG-788).
+        // is reachable by every hosted agent, this agent's role second.
         const systemPrompt = [CLAUDE_SDK_PROTOCOL, roleBlock];
         const runId = crypto.randomUUID();
         // Replay-stable write keys for this wake (runId is random and can't serve):
@@ -312,7 +355,7 @@ export class ClaudeSdkAgent {
             eff,
             senderId: rawEvent?.senderId != null ? String(rawEvent.senderId) : undefined,
             senderType: rawEvent?.senderType != null ? String(rawEvent.senderType) : undefined,
-            // ZIG-831/832: agreement this wake acts under → lets a delegated per-user
+            ///832: agreement this wake acts under → lets a delegated per-user
             // MCP call resolve the originating end-user (payer) rather than the
             // delegating agent (senderId). Resolved from every reliable wire source,
             // not just task_result events — see resolveOnBehalfAgreementId.
@@ -351,8 +394,17 @@ export class ClaudeSdkAgent {
         });
         let metrics = { llmCalls: 0, tokens: { total: 0, input: 0, output: 0, cacheRead: 0, cacheCreation: 0 } };
         let sessionId = nextCtx.claudeSessionId;
+        // Cost-weighted, cumulative: what this wake has charged the key so far.
         let spentInput = 0;
-        // ZIG-860: stateless-per-wake never resumes — each wake is a fresh
+        // The transcript's SIZE, which is a different question from spend and needs
+        // a different measure: the largest single turn's input, unweighted. On the
+        // cumulative sum a lane with a modest transcript crosses the resume ceiling
+        // simply by taking enough turns, and forgets its session after every wake —
+        // so each wake re-gathers from zero and stalls at the same step.
+        let peakTurnInput = 0;
+        // Why the wake stopped, when it stopped on a guard rather than on its own.
+        let abortedBy = null;
+        // stateless-per-wake never resumes — each wake is a fresh
         // transcript, so per-wake input stays flat instead of replaying the whole
         // lane history every turn.
         const resumeId = this.statelessPerWake ? undefined : nextCtx.claudeSessionId;
@@ -379,7 +431,7 @@ export class ClaudeSdkAgent {
                         sessionId = message.session_id;
                     }
                     // Surface the model's own prose so a hired Claude agent is as legible as
-                    // an FSM agent (ZIG-787). Each completed assistant turn's text is recorded
+                    // an FSM agent. Each completed assistant turn's text is recorded
                     // as a `thought` — the SAME agent-private channel the FSM uses for its
                     // reasoning (runTurn `emitThought` → record-event → recordThought), so it
                     // shows in the hired-agent view without cluttering the counterparty chat.
@@ -407,12 +459,23 @@ export class ClaudeSdkAgent {
                     if (message.type === 'result' && message.subtype !== 'success') {
                         runtimeLog.warn('ClaudeSdkAgent', `query ended without success subtype=${message.subtype} session=${identity.sessionId}`);
                     }
-                    // Runaway guard (ZIG-759): abort before an unbounded loop drains the
-                    // shared fleet key. Breaking the for-await calls the generator's return(),
+                    // Runaway guard: abort before an unbounded loop drains the
+                    // key. Breaking the for-await calls the generator's return(),
                     // which terminates the underlying query.
-                    spentInput += billableInput(usageOf(message));
+                    const turnUsage = usageOf(message);
+                    spentInput += costWeightedInput(turnUsage);
+                    peakTurnInput = Math.max(peakTurnInput, billableInput(turnUsage));
+                    // A wake that produced no per-turn usage still reports a cumulative
+                    // total on the result message. Divided by the turns it covers, that is
+                    // the average context per turn — a coarser read of the same transcript,
+                    // used only when the precise one is unavailable.
+                    if (message.type === 'result') {
+                        const turns = Math.max(1, message.num_turns ?? 1);
+                        peakTurnInput = Math.max(peakTurnInput, billableInput(message.usage) / turns);
+                    }
                     if (spentInput > MAX_TASK_INPUT_TOKENS) {
-                        runtimeLog.warn('ClaudeSdkAgent', `input-token budget exceeded (~${spentInput} > ${MAX_TASK_INPUT_TOKENS}) session=${identity.sessionId} agent=${this.agentId} — aborting query to cap spend (ZIG-759)`);
+                        abortedBy = 'input-budget';
+                        runtimeLog.warn('ClaudeSdkAgent', `input-token budget exceeded (~${Math.round(spentInput)} cost-weighted > ${MAX_TASK_INPUT_TOKENS}) session=${identity.sessionId} agent=${this.agentId} — aborting query to cap spend`);
                         break;
                     }
                 }
@@ -421,11 +484,35 @@ export class ClaudeSdkAgent {
                 signal?.removeEventListener('abort', onAbort);
             }
         };
+        /**
+         * Say, on the agent's own reasoning channel, that this wake stopped before
+         * it finished. Without the note a wake cut off by a guard is
+         * indistinguishable from one that delivered: the task stays `active` with
+         * `processing: false`, no artifact, no result, and nothing anywhere says
+         * why. The lane's history carries the reason instead, so a wedged-task
+         * detector has something to read.
+         */
+        const noteWakeCutShort = async (reason) => {
+            const text = `Wake stopped early: ${reason}. Work in progress was NOT filed — no ` +
+                `artifact was recorded and no task was closed by this wake.`;
+            await eff({
+                kind: 'record-event',
+                sessionId: identity.sessionId,
+                entry: { kind: 'thought', text },
+                idempotencyKey: writeKeys.artifactKey({ kind: 'thought', text }),
+            }).catch((err) => runtimeLog.warn('ClaudeSdkAgent', `record abort note failed session=${identity.sessionId}: ${err.message}`));
+        };
         try {
             await consumeQuery(resumeId);
         }
         catch (err) {
-            // ZIG-1191: the resumed transcript is gone. Claude Code stores transcripts
+            // Turn exhaustion arrives as a thrown error result, not a break, so it
+            // needs its own note before the throw propagates.
+            if (isMaxTurnsError(err)) {
+                abortedBy = 'max-turns';
+                await noteWakeCutShort(`the turn cap (${this.maxTurns}) was reached`);
+            }
+            // the resumed transcript is gone. Claude Code stores transcripts
             // on the container's own disk while the session id outlives it — persisted
             // per lane in the session store with a 24h TTL — so a redeployed agents
             // task inherits an id pointing at a file that no longer exists. Every wake
@@ -442,9 +529,15 @@ export class ClaudeSdkAgent {
                 throw err;
             }
             runtimeLog.info('ClaudeSdkAgent', `resumed Claude session ${resumeId} no longer exists (container replaced?) ` +
-                `session=${identity.sessionId} agent=${this.agentId} — retrying once on a fresh session (ZIG-1191)`);
+                `session=${identity.sessionId} agent=${this.agentId} — retrying once on a fresh session`);
             nextCtx.claudeSessionId = undefined;
             sessionId = undefined;
+            // The first attempt failed before any turn ran, so it spent nothing and
+            // left no transcript. Carrying its counters into the retry would halve the
+            // budget the real attempt gets to work with.
+            spentInput = 0;
+            peakTurnInput = 0;
+            abortedBy = null;
             try {
                 await consumeQuery(undefined);
             }
@@ -454,23 +547,31 @@ export class ClaudeSdkAgent {
             }
         }
         // Stateless-per-wake keeps no session id — clear any carried over from the
-        // prior ctx so the next wake starts fresh too (ZIG-860). Otherwise remember
+        // prior ctx so the next wake starts fresh too. Otherwise remember
         // this wake's session for resume.
         if (this.statelessPerWake)
             nextCtx.claudeSessionId = undefined;
         else if (sessionId)
             nextCtx.claudeSessionId = sessionId;
-        // ZIG-816: bound resumed-transcript growth. `metrics.tokens.input` is the
-        // wake's billable input off the result message (dominated by the resumed
-        // transcript's cache reads); `spentInput` covers an aborted wake that never
-        // produced a result. Past the ceiling, forget the session so the next wake
-        // starts fresh rather than paying an ever-larger replay.
-        const wakeInput = Math.max(metrics.tokens.input, spentInput);
-        if (nextCtx.claudeSessionId && wakeInput > MAX_SESSION_RESUME_INPUT_TOKENS) {
-            runtimeLog.info('ClaudeSdkAgent', `resetting Claude session (wake input ~${wakeInput} > ${MAX_SESSION_RESUME_INPUT_TOKENS}) ` +
-                `session=${identity.sessionId} agent=${this.agentId} — next wake starts fresh (ZIG-816)`);
+        // bound resumed-transcript growth. Past the ceiling, forget the session so
+        // the next wake starts fresh rather than paying an ever-larger replay.
+        //
+        // Measured as the largest SINGLE turn's input — that is the transcript,
+        // since every turn re-reads the whole thing. Summing the wake's turns
+        // instead measures how much WORK a wake did, not how much it carries: a lane
+        // whose transcript never leaves ~40k crosses the ceiling on turn five and
+        // drops its session on every wake. Resuming then never happens, so each wake
+        // re-reads the world from scratch and runs out of budget at the same step,
+        // and a standing job cannot advance.
+        if (nextCtx.claudeSessionId && peakTurnInput > MAX_SESSION_RESUME_INPUT_TOKENS) {
+            runtimeLog.info('ClaudeSdkAgent', `resetting Claude session (transcript ~${peakTurnInput} > ${MAX_SESSION_RESUME_INPUT_TOKENS}) ` +
+                `session=${identity.sessionId} agent=${this.agentId} — next wake starts fresh`);
             nextCtx.claudeSessionId = undefined;
         }
+        if (abortedBy === 'input-budget') {
+            await noteWakeCutShort(`the per-wake spend guard cut this run off (~${Math.round(spentInput)} ` +
+                `cost-weighted input tokens > ${MAX_TASK_INPUT_TOKENS})`);
+        }
         return {
             ctx: nextCtx,
             state: state ?? DEFAULT_STATE,