@ziggs-ai/agent-sdk 0.4.1 → 0.6.0

package/dist/AgentHost.d.ts

@@ -40,6 +40,19 @@ export declare const DEFAULT_MODEL = "claude-haiku-4-5";
  * could bucket by taskId, cron agents by schedule id, etc.
  */
 export type SessionResolver = (normalized: NormalizedEvent, ownAgentId: string) => string | null;
+/**
+ * ZIG-975: one lane key per unit of work, derived the same way as inbox wakes.
+ *
+ * Inbox deliveries key on `chatId` (DEFAULT_SESSION_RESOLVER). Bootstrap used to
+ * prefer bare `agreementId`, which opened a second lane for the same task and
+ * made the snapshot read treat the agreement id as a chat (`chatMissing: true`,
+ * empty context). Prefer the origin chat when present; otherwise the agreement's
+ * notification chat (`agrn-<agreementId>`), which is always linked after ZIG-966.
+ */
+export declare function laneSessionIdForTask(task: {
+    originChatId?: string | null;
+    agreementId?: string | null;
+}): string;
 interface LlmAdapter {
     chatMessages(messages: unknown[], tools?: unknown[], options?: Record<string, unknown>): Promise<unknown>;
 }
@@ -104,6 +117,14 @@ export interface AgentHostOptions {
     sessionStore?: SessionStore;
     /** Observability tap: called after every effect with the effect and its response. */
     effectTap?: (effect: import('./types.js').Effect, response: unknown) => void;
+    /**
+     * Liveness signal: called whenever the host receives or processes work (an
+     * inbox message or resource event delivered to a lane). Hosting pools use it
+     * to reset their idle-eviction timer — without it a host that is actively
+     * working (but never addressed via pool.sendTo) is torn down mid-stream at
+     * the idle timeout, discarding lane state, Claude session ids, and timers.
+     */
+    onActivity?: () => void;
     /** Observability tap: called on every FSM state transition, no-match, depth-guard, or error-escape (ZIG-442). */
     transitionTap?: (event: import('./runtime/AgentMachine.js').TransitionEvent) => void;
     /**

package/dist/AgentHost.js

@@ -36,6 +36,24 @@ async function loadConnectionPool() {
     return mod.ConnectionPool;
 }
 const DEFAULT_SESSION_RESOLVER = (normalized) => normalized.chatId;
+/**
+ * ZIG-975: one lane key per unit of work, derived the same way as inbox wakes.
+ *
+ * Inbox deliveries key on `chatId` (DEFAULT_SESSION_RESOLVER). Bootstrap used to
+ * prefer bare `agreementId`, which opened a second lane for the same task and
+ * made the snapshot read treat the agreement id as a chat (`chatMissing: true`,
+ * empty context). Prefer the origin chat when present; otherwise the agreement's
+ * notification chat (`agrn-<agreementId>`), which is always linked after ZIG-966.
+ */
+export function laneSessionIdForTask(task) {
+    if (typeof task.originChatId === 'string' && task.originChatId) {
+        return task.originChatId;
+    }
+    if (typeof task.agreementId === 'string' && task.agreementId) {
+        return `agrn-${task.agreementId}`;
+    }
+    return 'default';
+}
 function createToolManager(options) {
     const toolManager = new ToolManager();
     const userTools = options.tools || options.services?.tools || [];
@@ -147,7 +165,15 @@ export class AgentHost {
         };
         this.inboxLoopEnabled = options.inboxCatchUp !== false;
         this.sessionResolver = options.sessionResolver || DEFAULT_SESSION_RESOLVER;
-        this.tickTimeoutMs = options.tickTimeoutMs ?? 120_000;
+        // A Claude-brain wake legitimately runs long (multi-turn query, prose
+        // deliverables) — 120s watchdogged real spec-writing wakes mid-flight,
+        // which then redelivered and re-ran (ZIG-924 dogfood, 2026-07-26). FSM
+        // turns stay on the tight default.
+        this.tickTimeoutMs =
+            options.tickTimeoutMs ??
+                (isClaudeCognition(options.cognition)
+                    ? Number(process.env.CLAUDE_SDK_TICK_TIMEOUT_MS ?? 300_000)
+                    : 120_000);
         this.memory = options.memory ?? new InMemoryStore();
         this.sessionStore = options.sessionStore ?? null;
         this._validate();
@@ -375,11 +401,19 @@ export class AgentHost {
         // armed pinned one live 2-minute timer per tick (and kept short-lived
         // processes/tests alive until it fired).
         let tickWatchdog;
+        // Aborting on timeout is load-bearing: Promise.race only abandons the tick
+        // promise. A Claude-brain tick left unaborted keeps its query() running as
+        // a zombie — burning tokens and racing the redelivered retry of the same
+        // event (duplicate sends, runaway per-wake input).
+        const tickAbort = new AbortController();
         try {
             const result = await Promise.race([
-                this.agent.tick({ event: frame, ctx: session.ctx, state: session.state, identity, eff: this.eff, memory: this.memory, transitionTap: this.options.transitionTap }),
+                this.agent.tick({ event: frame, ctx: session.ctx, state: session.state, identity, eff: this.eff, memory: this.memory, transitionTap: this.options.transitionTap, signal: tickAbort.signal }),
                 new Promise((_, reject) => {
-                    tickWatchdog = setTimeout(() => reject(new Error('tick timeout')), this.tickTimeoutMs);
+                    tickWatchdog = setTimeout(() => {
+                        tickAbort.abort(new Error('tick timeout'));
+                        reject(new Error('tick timeout'));
+                    }, this.tickTimeoutMs);
                 }),
             ]);
             session.ctx = result.ctx;
@@ -475,8 +509,26 @@ export class AgentHost {
                 ownAgentId: this.options.agentId,
                 seen: this.seenMessages,
                 label,
-                onMessage: (text, metadata) => this.handleMessage(text, metadata),
-                onResourceEvent: (event) => this.handleResourceEvent(event),
+                onMessage: (text, metadata) => {
+                    this.options.onActivity?.();
+                    return this.handleMessage(text, metadata);
+                },
+                onResourceEvent: (event) => {
+                    this.options.onActivity?.();
+                    return this.handleResourceEvent(event);
+                },
+                // ZIG-973: work delivered by the inbox's task channel, not by a chat
+                // row — this is what reaches a task under a chat-less agreement or one
+                // the agent assigned to itself.
+                onTask: async (task) => {
+                    this.options.onActivity?.();
+                    try {
+                        await this.wakeTaskAssignment(task.taskId);
+                    }
+                    catch (err) {
+                        runtimeLog.warn(this.options.name || 'agent', `inbox task ${task.taskId} could not be woken: ${err.message}`);
+                    }
+                },
             });
         }
         return this;
@@ -509,9 +561,7 @@ export class AgentHost {
             const state = String(full.state ?? '');
             if (state !== 'active' && state !== 'in-progress')
                 continue;
-            const sessionId = full.agreementId ||
-                full.originChatId ||
-                'default';
+            const sessionId = laneSessionIdForTask(full);
             const laneKey = `${agentId}:${sessionId}`;
             if (!this.sessions.has(laneKey)) {
                 this.sessions.set(laneKey, { sessionId, ownAgentId: agentId });
@@ -525,7 +575,7 @@ export class AgentHost {
                     state,
                     providerIsYou: true,
                 },
-                chatId: full.originChatId,
+                chatId: sessionId,
             }, laneKey);
         }
     }
@@ -540,9 +590,7 @@ export class AgentHost {
         if (state !== 'active' && state !== 'in-progress') {
             throw new Error(`wakeTaskAssignment: task ${taskId} is ${state}, not active`);
         }
-        const sessionId = full.agreementId ||
-            full.originChatId ||
-            'default';
+        const sessionId = laneSessionIdForTask(full);
         const laneKey = `${agentId}:${sessionId}`;
         if (!this.sessions.has(laneKey)) {
             this.sessions.set(laneKey, { sessionId, ownAgentId: agentId });
@@ -555,7 +603,7 @@ export class AgentHost {
                 state,
                 providerIsYou: true,
             },
-            chatId: full.originChatId,
+            chatId: sessionId,
         }, laneKey);
     }
     disconnect() { this.stateTimers.clearAll(); void this.inboxLoop?.stop(); this.inboxLoop = null; }

package/dist/agent/Agent.d.ts

@@ -27,6 +27,15 @@ export interface TickInput {
     memory?: MemoryStore;
     /** Optional tap for FSM transition events (ZIG-442). */
     transitionTap?: (event: TransitionEvent) => void;
+    /**
+     * Aborted by the host when the tick watchdog fires. A brain driving an
+     * external loop (the Claude Agent SDK query) MUST stop consuming it on
+     * abort — the host's Promise.race only abandons the tick promise, so
+     * without this the query keeps running as a zombie: burning tokens and
+     * racing its own redelivered retry (observed as duplicate kickoffs and a
+     * 363k-token wake, 2026-07-26).
+     */
+    signal?: AbortSignal;
 }
 export interface TickOutput {
     /** Updated ctx — Server persists this against the session. */

package/dist/agent/ClaudeSdkAgent.d.ts

@@ -39,5 +39,5 @@ export declare class ClaudeSdkAgent {
     private statelessPerWake;
     private queryFn;
     constructor(opts: ClaudeSdkAgentOptions);
-    tick({ event, ctx, state, identity, eff }: TickInput): Promise<TickOutput>;
+    tick({ event, ctx, state, identity, eff, signal }: TickInput): Promise<TickOutput>;
 }

package/dist/agent/ClaudeSdkAgent.js

@@ -163,7 +163,7 @@ export class ClaudeSdkAgent {
         this.statelessPerWake = opts.statelessPerWake ?? false;
         this.queryFn = opts.queryFn ?? query;
     }
-    async tick({ event, ctx, state, identity, eff }) {
+    async tick({ event, ctx, state, identity, eff, signal }) {
         if (!identity?.sessionId)
             throw new Error('ClaudeSdkAgent.tick: identity.sessionId is required');
         if (!eff)
@@ -199,16 +199,32 @@ export class ClaudeSdkAgent {
         // Same guard as the FSM's runTurn: a message wake for a chat the backend
         // 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.
-        // Task lanes (sessionId = agreementId) also trip chatMissing and must run.
-        if (contextSnap?.chatMissing === true && nextCtx.lastOutcome?.kind === 'message-received') {
-            runtimeLog.warn('ClaudeSdkAgent', `chat ${identity.sessionId} not found on backend — skipping message wake agent=${this.agentId}`);
-            return {
-                ctx: nextCtx,
-                state: state ?? DEFAULT_STATE,
-                parked: true,
-                stateTimeoutUnhandled: false,
-                metrics: { llmCalls: 0, tokens: { total: 0, input: 0, output: 0 } },
-            };
+        //
+        // ZIG-975: 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.
+        if (contextSnap?.chatMissing === true) {
+            const sessionId = identity.sessionId;
+            const looksLikeBareAgreement = typeof sessionId === 'string' &&
+                sessionId.startsWith('agr_') &&
+                !sessionId.startsWith('agrn-');
+            if (looksLikeBareAgreement) {
+                runtimeLog.warn('ClaudeSdkAgent', `chatMissing on non-chat sessionId=${sessionId} agent=${this.agentId} ` +
+                    `outcome=${nextCtx.lastOutcome?.kind ?? 'none'} — lane was keyed by ` +
+                    `agreementId instead of the agreement's origin/notification chat; ` +
+                    `wake continues with an empty snapshot`);
+            }
+            if (nextCtx.lastOutcome?.kind === 'message-received') {
+                runtimeLog.warn('ClaudeSdkAgent', `chat ${sessionId} not found on backend — skipping message wake agent=${this.agentId}`);
+                return {
+                    ctx: nextCtx,
+                    state: state ?? DEFAULT_STATE,
+                    parked: true,
+                    stateTimeoutUnhandled: false,
+                    metrics: { llmCalls: 0, tokens: { total: 0, input: 0, output: 0 } },
+                };
+            }
         }
         const roleBlock = [
             `## Your role`,
@@ -264,8 +280,24 @@ export class ClaudeSdkAgent {
         let metrics = { llmCalls: 0, tokens: { total: 0, input: 0, output: 0, cacheRead: 0, cacheCreation: 0 } };
         let sessionId = nextCtx.claudeSessionId;
         let spentInput = 0;
+        // Host watchdog abort (see TickInput.signal): stop consuming AND interrupt
+        // the query, so a timed-out wake never lingers as a token-burning zombie
+        // racing its own redelivered retry. Breaking the for-await returns the
+        // generator; interrupt() additionally stops a query blocked mid-turn.
+        const query = this.queryFn({ prompt, options: queryOptions });
+        const onAbort = () => {
+            void query.interrupt?.()?.catch(() => { });
+        };
+        if (signal?.aborted)
+            onAbort();
+        else
+            signal?.addEventListener('abort', onAbort, { once: true });
         try {
-            for await (const message of this.queryFn({ prompt, options: queryOptions })) {
+            for await (const message of query) {
+                if (signal?.aborted) {
+                    runtimeLog.warn('ClaudeSdkAgent', `host watchdog aborted wake session=${identity.sessionId} agent=${this.agentId} — stopping query`);
+                    break;
+                }
                 if ('session_id' in message && typeof message.session_id === 'string') {
                     sessionId = message.session_id;
                 }
@@ -312,6 +344,9 @@ export class ClaudeSdkAgent {
             runtimeLog.warn('ClaudeSdkAgent', `query failed session=${identity.sessionId}: ${err.message}`);
             throw err;
         }
+        finally {
+            signal?.removeEventListener('abort', onAbort);
+        }
         // 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
         // this wake's session for resume.

package/dist/agent/claudeSdkTools.js

@@ -26,7 +26,7 @@ export const ziggsContextSnapshotTool = defineTool('ziggs_context_snapshot', {
             maxMessages: args.maxMessages != null ? Number(args.maxMessages) : DEFAULT_SNAPSHOT_MAX_MESSAGES,
         },
     });
-}, { description: 'Read the chat snapshot: history, agreements, agents, and users for a session.' });
+}, { description: 'Read the chat snapshot: the NEWEST maxMessages of history (chronological order), plus agreements, agents, and users for a session.' });
 export const ziggsSendMessageTool = defineTool('ziggs_send_message', {
     chatId: { type: 'string', description: 'Chat id. Defaults to current session.' },
     receiverId: { type: 'string', description: 'Recipient user or agent id. Defaults to the sender of the event that woke you — omit when replying to them.' },

package/dist/defineAgent.d.ts

@@ -2,11 +2,16 @@ import type { AgentConfig, DefineAgentInput } from './types.js';
 /**
  * Validates the workflow synchronously, resolves merged tools and model, and
  * returns a frozen AgentConfig. Never mutates the input. `wait` defaults remain
- * the author's visible spread of `thinkingDefaults`. ONE default is injected (as
- * new objects): the agreement-kickoff state `kickingOff` plus a last-position
- * transition into it, appended to every state that does not already handle a
- * proposer-side proposal-resolved/approve outcome (runtime/kickoff.ts). The
- * state name 'kickingOff' is reserved; defining it throws.
+ * the author's visible spread of `thinkingDefaults`. TWO defaults are injected
+ * (as new objects), each appended LAST so author transitions always win:
+ *  - the agreement-kickoff state `kickingOff`, reached from every state that
+ *    does not already handle a proposer-side proposal-resolved/approve outcome
+ *    (runtime/kickoff.ts);
+ *  - the assigned-task-intake state `workingAssignedTask`, reached from every
+ *    state that does not already route a task-assigned outcome
+ *    (runtime/taskIntake.ts) — so a standing hire's task #2..N is never
+ *    silently dropped by a parked state.
+ * Both state names are reserved; defining either throws.
  *
  * Validation throws WorkflowValidationError on hard problems and logs warnings
  * on soft ones (e.g. missing wait fallthrough).

package/dist/defineAgent.js

@@ -1,16 +1,22 @@
 import { validateWorkflow } from './runtime/validateWorkflow.js';
 import { injectKickoffDefault } from './runtime/kickoff.js';
+import { injectTaskIntakeDefault } from './runtime/taskIntake.js';
 import { deriveRespondsToProposals } from './runtime/deriveRespondsToProposals.js';
 import { runtimeLog } from './shared/runtimeLog.js';
 import { DEFAULT_MODEL } from './AgentHost.js';
 /**
  * Validates the workflow synchronously, resolves merged tools and model, and
  * returns a frozen AgentConfig. Never mutates the input. `wait` defaults remain
- * the author's visible spread of `thinkingDefaults`. ONE default is injected (as
- * new objects): the agreement-kickoff state `kickingOff` plus a last-position
- * transition into it, appended to every state that does not already handle a
- * proposer-side proposal-resolved/approve outcome (runtime/kickoff.ts). The
- * state name 'kickingOff' is reserved; defining it throws.
+ * the author's visible spread of `thinkingDefaults`. TWO defaults are injected
+ * (as new objects), each appended LAST so author transitions always win:
+ *  - the agreement-kickoff state `kickingOff`, reached from every state that
+ *    does not already handle a proposer-side proposal-resolved/approve outcome
+ *    (runtime/kickoff.ts);
+ *  - the assigned-task-intake state `workingAssignedTask`, reached from every
+ *    state that does not already route a task-assigned outcome
+ *    (runtime/taskIntake.ts) — so a standing hire's task #2..N is never
+ *    silently dropped by a parked state.
+ * Both state names are reserved; defining either throws.
  *
  * Validation throws WorkflowValidationError on hard problems and logs warnings
  * on soft ones (e.g. missing wait fallthrough).
@@ -24,14 +30,15 @@ export function defineAgent(input) {
         throw new Error('[defineAgent] states is required');
     if (!input?.initial)
         throw new Error('[defineAgent] initial state is required');
-    // Agreement-kickoff default (see runtime/kickoff.ts): injected BEFORE
-    // validation so the injected state/transitions are validated too.
-    const workflow = injectKickoffDefault({
+    // Agreement-kickoff + assigned-task-intake defaults (runtime/kickoff.ts,
+    // runtime/taskIntake.ts): injected BEFORE validation so the injected
+    // states/transitions are validated too.
+    const workflow = injectTaskIntakeDefault(injectKickoffDefault({
         id: input.agentId,
         description: input.description,
         initial: input.initial,
         states: input.states,
-    });
+    }));
     const { warnings } = validateWorkflow(workflow);
     for (const w of warnings)
         runtimeLog.warn('defineAgent', w);

package/dist/runtime/runTurn.js

@@ -105,8 +105,18 @@ export async function runTurn(input) {
     // to this agent) has no world to decide over — deciding anyway means
     // reasoning about a fabricated empty history plus whatever stale scraps
     // other fetches returned. Skip the LLM and park. Gated on message wakes
-    // only: agreement-keyed task lanes (sessionId = agreementId) always trip
-    // chatMissing and must still run.
+    // only. ZIG-975: a bare agreement id as sessionId is a mis-keyed lane —
+    // loud-log the empty snapshot rather than staying silent.
+    if (ctxObj.chatMissing) {
+        const looksLikeBareAgreement = typeof sessionId === 'string' &&
+            sessionId.startsWith('agr_') &&
+            !sessionId.startsWith('agrn-');
+        if (looksLikeBareAgreement) {
+            runtimeLog.warn('runTurn', `chatMissing on non-chat sessionId=${sessionId} (state=${stateId}) — ` +
+                `lane was keyed by agreementId instead of the agreement's origin/notification chat; ` +
+                `wake continues with an empty snapshot`);
+        }
+    }
     if (ctxObj.chatMissing && ctx.lastOutcome?.kind === 'message-received') {
         runtimeLog.warn('runTurn', `chat ${sessionId} not found on backend — skipping message wake (state=${stateId})`);
         return {

package/dist/runtime/taskIntake.d.ts

@@ -0,0 +1,18 @@
+import type { ThinkingState, Workflow } from '../types.js';
+/** Reserved state name for the injected assigned-task-intake default. */
+export declare const TASK_INTAKE_STATE = "workingAssignedTask";
+export declare function buildTaskIntakeState(initial: string): ThinkingState;
+/**
+ * Assigned-task-intake default — the task-side twin of the agreement-kickoff
+ * default (kickoff.ts). For every state whose transitions do not already match
+ * a task-assigned outcome, append a transition to the injected
+ * `workingAssignedTask` state. Appended LAST so any user transition on the
+ * same outcome always wins (first match wins in
+ * AgentMachine._evaluateTransitions). Returns a NEW workflow — input states
+ * are not mutated.
+ *
+ * Why: a standing hire receives task #2, #3, … months after approval. Without
+ * this default a parked state with no task-assigned route (e.g. a hire parked
+ * in `engaged`) swallowed the wake and the task sat active forever.
+ */
+export declare function injectTaskIntakeDefault(workflow: Workflow): Workflow;

package/dist/runtime/taskIntake.js

@@ -0,0 +1,113 @@
+import { thinkingDefaults } from './defaults.js';
+import { KICKOFF_STATE } from './kickoff.js';
+import { PROBE_CTX } from './validateWorkflow.js';
+/** Reserved state name for the injected assigned-task-intake default. */
+export const TASK_INTAKE_STATE = 'workingAssignedTask';
+// Synthetic outcome used to ask "does this state already route an assigned
+// task?" — same probe pattern as kickoff.ts / validateWorkflow.
+const PROBE_TASK_ASSIGNED = {
+    kind: 'task-assigned',
+    task: { taskId: '__task_intake_probe__' },
+};
+const TASK_INTAKE_TRANSITION = {
+    to: TASK_INTAKE_STATE,
+    when: o => o.kind === 'task-assigned',
+};
+// A state "handles" task-assigned if some transition would fire for it. An
+// unconditional (when-less) transition counts — it catches every outcome, so
+// the intake transition appended LAST would be unreachable there anyway.
+function stateHandlesTaskAssigned(state) {
+    return state.transitions.some(t => {
+        if (!t.when)
+            return true;
+        try {
+            return !!t.when(PROBE_TASK_ASSIGNED, PROBE_CTX);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+export function buildTaskIntakeState(initial) {
+    const dflt = thinkingDefaults({ initial });
+    return {
+        kind: 'thinking',
+        prompt: {
+            role: 'A task was just assigned to you under one of your active agreements, and your workflow has no explicit route for it. This injected default exists so an assigned task is NEVER silently dropped — under a standing hire, new tasks keep arriving for the lifetime of the agreement.',
+            goal: 'Resolve the assigned task this turn: deliver the result if you can produce it, otherwise fail it with a reason.',
+            constraints: 'The task is in <event> (and as activeTaskId / activeAgreementId in <machine_context>). If the deliverable can be produced in this turn (an answer, summary, plan, draft — most representation work), call task_update with status "completed" and the deliverable as result — the result is what the counterparty consumes, so make it the actual deliverable, not a status note. If the task genuinely needs abilities or tools you do not have, call task_update with status "failed" and a one-line reason — a visible failure the counterparty can re-route beats a silent drop. Never leave the task dangling or answer with a chat message alone.',
+        },
+        actions: {
+            ...dflt.actions,
+            completeTask: {
+                prompt: {
+                    when: 'You can produce the deliverable for the assigned task in this turn.',
+                    instruction: 'Complete the assigned task, with the deliverable itself as the result.',
+                    format: '{"taskId": "<assigned task id from <event>>", "status": "completed", "result": "<the full deliverable>"}',
+                },
+                tool: 'task_update',
+                // Function form so a failed task_update surfaces as an error outcome
+                // (→ dflt error transition) instead of a phantom task-closed.
+                produces: (result) => {
+                    const r = result;
+                    const status = r?.task?.state ?? r?.state ?? r?.status;
+                    return status === 'completed' || status === 'failed' ? 'task-closed' : 'error';
+                },
+                terminatesLoop: true,
+            },
+            failTask: {
+                prompt: {
+                    when: 'The task needs abilities, tools, or information you cannot obtain this turn.',
+                    instruction: 'Fail the assigned task with a one-line reason so the counterparty can re-route it.',
+                    format: '{"taskId": "<assigned task id from <event>>", "status": "failed", "result": "<one-line reason>"}',
+                },
+                tool: 'task_update',
+                produces: (result) => {
+                    const r = result;
+                    const status = r?.task?.state ?? r?.state ?? r?.status;
+                    return status === 'completed' || status === 'failed' ? 'task-closed' : 'error';
+                },
+                terminatesLoop: true,
+            },
+        },
+        transitions: [
+            { to: initial, when: o => o.kind === 'task-closed' },
+            ...dflt.transitions, // wait / message-sent / error → initial
+        ],
+    };
+}
+/**
+ * Assigned-task-intake default — the task-side twin of the agreement-kickoff
+ * default (kickoff.ts). For every state whose transitions do not already match
+ * a task-assigned outcome, append a transition to the injected
+ * `workingAssignedTask` state. Appended LAST so any user transition on the
+ * same outcome always wins (first match wins in
+ * AgentMachine._evaluateTransitions). Returns a NEW workflow — input states
+ * are not mutated.
+ *
+ * Why: a standing hire receives task #2, #3, … months after approval. Without
+ * this default a parked state with no task-assigned route (e.g. a hire parked
+ * in `engaged`) swallowed the wake and the task sat active forever.
+ */
+export function injectTaskIntakeDefault(workflow) {
+    if (workflow.states[TASK_INTAKE_STATE]) {
+        throw new Error(`[defineAgent] state name "${TASK_INTAKE_STATE}" is reserved for the injected assigned-task-intake default — rename the state`);
+    }
+    const states = {};
+    let injected = false;
+    for (const [name, state] of Object.entries(workflow.states)) {
+        // Injected defaults never feed each other: the kickoff state's own lack of
+        // a task-assigned route must not force the intake state into a workflow
+        // whose author states all handle assignment.
+        if (name === KICKOFF_STATE || stateHandlesTaskAssigned(state)) {
+            states[name] = state;
+            continue;
+        }
+        states[name] = { ...state, transitions: [...state.transitions, TASK_INTAKE_TRANSITION] };
+        injected = true;
+    }
+    if (!injected)
+        return workflow; // every state routes task-assigned — nothing to add
+    states[TASK_INTAKE_STATE] = buildTaskIntakeState(workflow.initial);
+    return { ...workflow, states };
+}

package/dist/server/ConnectionPool.d.ts

@@ -11,7 +11,7 @@
  * This is how a single Node process serves a fleet of agents without
  * holding 1000 open sockets — typical config: 1000+ registered, ~50 live.
  */
-import { type InboxOperatorAgentEntry } from '@ziggs-ai/api-client';
+import { type InboxOperatorAgentEntry, type StartAgentOptions } from '@ziggs-ai/api-client';
 import { AgentHost, type AgentHostOptions } from '../AgentHost.js';
 interface ConnectionManagerMeta {
     domain?: string;
@@ -50,7 +50,14 @@ export declare class ConnectionPool {
      * `AgentHost` constructed + connected) the first time it's referenced.
      */
     register(configs: AgentHostOptions[], metaArr?: ConnectionManagerMeta[]): void;
-    startAgent(agentId: string): Promise<AgentHost>;
+    /**
+     * Start (or return) an agent's host. `pinned` keeps it up for the process's
+     * lifetime — no idle sweep, last to be evicted; use it for hosts the operator
+     * named rather than ones work happened to reach.
+     */
+    startAgent(agentId: string, opts?: StartAgentOptions): Promise<AgentHost>;
+    /** Agents kept up explicitly (launcher `preStart`), not by demand. */
+    listPinned(): string[];
     sleep(agentId: string): Promise<void>;
     disconnectAll(): Promise<void>;
     /**

package/dist/server/ConnectionPool.js

@@ -46,7 +46,14 @@ export class ConnectionPool {
                 const pool = this;
                 const host = new AgentHost({
                     ...cfg,
+                    // Inbox activity and in-flight effects both reset the idle timer:
+                    // previously only pool.sendTo() touched it, so a host woken by its
+                    // own inbox loop was torn down every idleTimeoutMs (default 60s)
+                    // regardless of the work it was doing — losing lane ctx, Claude
+                    // session ids, and armed timers each time.
+                    onActivity: () => pool.manager.touch(agentId),
                     effectTap(effect, response) {
+                        pool.manager.touch(agentId);
                         if (effect.kind === 'send-message') {
                             const listeners = pool.responseListeners.get(agentId);
                             if (listeners?.length)
@@ -64,8 +71,17 @@ export class ConnectionPool {
             }, metaByAgentId.get(agentId));
         }
     }
-    async startAgent(agentId) {
-        return await this.manager.startAgent(agentId);
+    /**
+     * Start (or return) an agent's host. `pinned` keeps it up for the process's
+     * lifetime — no idle sweep, last to be evicted; use it for hosts the operator
+     * named rather than ones work happened to reach.
+     */
+    async startAgent(agentId, opts = {}) {
+        return await this.manager.startAgent(agentId, opts);
+    }
+    /** Agents kept up explicitly (launcher `preStart`), not by demand. */
+    listPinned() {
+        return this.manager.listPinned();
     }
     async sleep(agentId) {
         return this.manager.sleep(agentId);

package/dist/server/inboxLoop.d.ts

@@ -1,13 +1,17 @@
-import { type Creds } from '@ziggs-ai/api-client';
+import { type InboxTaskRef, type Creds } from '@ziggs-ai/api-client';
 import { SeenMessages } from './SeenMessages.js';
 /**
  * Per-agent inbox long-poll loop (delivery law, phase 4). This is the ONLY way
- * a hosted agent consumes: `GET /inbox?wait=` → grant-fenced reads of the delta
- * → deliver into the host's lane/tick machinery → `POST /inbox/ack`. No socket,
- * no push, no separate catch-up channel — a crash-replay is just the next
- * iteration (the cursor is server-side), and writes carry idempotency keys so
- * re-processing a redelivered window is wasteful, never harmful. Act-before-ack
- * is the one ordering rule.
+ * a hosted agent consumes: `GET /inbox?wait=` → grant-fenced reads of what was
+ * addressed to it → deliver into the host's lane/tick machinery →
+ * `POST /inbox/ack`. No socket, no push, no separate catch-up channel — a
+ * crash-replay is just the next iteration (the watermark is server-side), and
+ * writes carry idempotency keys so re-processing a redelivered window is
+ * wasteful, never harmful. Act-before-ack is the one ordering rule.
+ *
+ * The envelope now names the chats directly, so this loop no longer expands
+ * scopes into chat ids itself — that cost an extra grant/agreement lookup per
+ * scope, per pass, purely to rediscover what the server already knew.
  */
 export interface InboxLoopDeps {
     creds: Creds;
@@ -16,13 +20,24 @@ export interface InboxLoopDeps {
     seen: SeenMessages;
     onMessage: (text: string, metadata: Record<string, unknown>) => Promise<void>;
     onResourceEvent: (event: Record<string, unknown>) => Promise<void>;
+    /**
+     * An open task assigned to this agent (ZIG-973). Delivered from the inbox's
+     * own task channel, so work reaches the agent even when no chat row exists
+     * for it (chat-less agreement, self-assigned task).
+     */
+    onTask?: (task: InboxTaskRef) => Promise<void>;
     label?: string;
 }
 export interface InboxPassResult {
-    scopes: number;
+    /** Delivery references this envelope carried. */
+    deliveries: number;
     messagesDelivered: number;
     resourceEvents: number;
-    acked: number;
+    /** Assigned open tasks delivered this pass (ZIG-973). */
+    tasksDelivered: number;
+    /** True when the watermark advanced this pass. */
+    acked: boolean;
+    /** True when there was more mail than one envelope carries. */
     truncated: boolean;
 }
 /**
@@ -42,8 +57,13 @@ export interface InboxLoopHandle {
  * Run {@link pollInboxOnce} forever (until stopped). Each iteration long-polls
  * for `waitSeconds`; a passing envelope returns instantly, an empty one holds.
  * Errors retry with exponential backoff + jitter and never exit the loop —
- * there is nothing to resynchronize (the cursor is server-side), so recovery is
- * just the next iteration.
+ * there is nothing to resynchronize (the watermark is server-side), so recovery
+ * is just the next iteration.
+ *
+ * The FIRST pass is an immediate read. A held poll only answers to new mail, so
+ * a host that just started (or restarted after a crash) would otherwise sit
+ * waiting while the work it was already assigned — open tasks, pending
+ * decisions — went unseen until something unrelated arrived.
  */
 export declare function runInboxLoop(deps: InboxLoopDeps, opts?: {
     waitSeconds?: number;