@ziggs-ai/agent-sdk 0.5.0 → 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;

package/dist/server/inboxLoop.js

@@ -1,4 +1,4 @@
-import { ContextReadClient, GrantsClient, InboxClient, getChatsForAgreement, } from '@ziggs-ai/api-client';
+import { ContextReadClient, InboxClient, } from '@ziggs-ai/api-client';
 import { runtimeLog } from '../shared/runtimeLog.js';
 const READ_PAGE = 100;
 function log(label, msg) {
@@ -7,67 +7,61 @@ function log(label, msg) {
 function warn(label, msg) {
     runtimeLog.warn(label, msg);
 }
-async function chatIdsForScope(scope, creds, grants) {
-    const { kind, id } = scope.scope;
-    switch (kind) {
-        case 'chat':
-            return [id];
-        case 'agreement': {
-            const links = (await getChatsForAgreement(id, creds));
-            return [...new Set(links.map((l) => l.chatId).filter(Boolean))];
-        }
-        case 'org': {
-            // All pages of live chat grants — an org-scope read must not miss chats
-            // hidden behind pagination (GET /grants defaults to one page).
-            const items = await grants.listAllGrants({
-                scopeKind: 'chat',
-                health: 'active',
-            });
-            return [...new Set(items.map((g) => g.scope.id))];
-        }
-        default:
-            return [];
-    }
-}
-async function deliverMessagesForScope(deps, scope, chatIds, reader, countCap) {
+/**
+ * Read the messages behind one chat's deliveries and hand them to the host.
+ *
+ * The envelope says which chat and how many, not the bodies — so this still
+ * reads through `/context/read`, where the agent's own grants fence what it is
+ * allowed to see. A delivery reference is an address, never an authorisation.
+ */
+async function deliverMessagesForChat(deps, news, earliestTs, reader) {
     let delivered = 0;
-    const label = deps.label ?? 'inboxLoop';
-    const expected = scope.newMessages;
-    let remaining = expected >= countCap ? Number.POSITIVE_INFINITY : expected;
-    for (const chatId of chatIds) {
-        if (remaining <= 0)
-            break;
-        let after = scope.since;
-        let pages = 0;
-        const maxPages = 20;
-        while (remaining > 0 && pages < maxPages) {
-            const limit = Math.min(READ_PAGE, remaining === Number.POSITIVE_INFINITY ? READ_PAGE : remaining);
-            const page = await reader.read('messages', {
-                via: `chat:${chatId}`,
+    let remaining = news.count;
+    // `after` is exclusive, so step back a millisecond to include the oldest
+    // delivery itself. Re-reading a neighbour that shares its timestamp is
+    // harmless — `seen` dedups by messageId.
+    let after = new Date(Date.parse(earliestTs) - 1).toISOString();
+    let pages = 0;
+    const maxPages = 20;
+    while (remaining > 0 && pages < maxPages) {
+        const limit = Math.min(READ_PAGE, remaining);
+        let page;
+        try {
+            page = await reader.read('messages', {
+                via: `chat:${news.chatId}`,
                 after,
                 direction: 'forward',
                 limit,
             });
-            for (const row of page.items) {
-                const messageId = String(row.messageId ?? '');
-                if (deps.seen.has(messageId))
-                    continue;
-                const text = typeof row.text === 'string' ? row.text : '';
-                if (!text.trim())
-                    continue;
-                await deps.onMessage(text, { ...row, chatId });
-                delivered++;
-                if (remaining !== Number.POSITIVE_INFINITY)
-                    remaining--;
-            }
-            if (!page.hasMore || !page.latestSequence)
-                break;
-            after = page.latestSequence;
-            pages++;
         }
-    }
-    if (delivered < expected && expected >= countCap) {
-        warn(label, `scope ${scope.scope.kind}:${scope.scope.id} may be incomplete (count cap)`);
+        catch (err) {
+            const status = err.status;
+            if (status !== 403 && status !== 404)
+                throw err;
+            // Addressed but not readable. Since the delivery log and the grants are
+            // now separate, the two can disagree — a grant revoked between the write
+            // and this read, or a chat since deleted. Skipping keeps the pass alive
+            // so the rest of the mail is delivered and the watermark still advances;
+            // failing here would wedge the agent on one unreadable item forever,
+            // re-woken by the same delivery on every pass.
+            warn(deps.label ?? 'inboxLoop', `chat ${news.chatId}: addressed but not readable (${status}) — skipping ${remaining} delivery/deliveries`);
+            return delivered;
+        }
+        for (const row of page.items) {
+            const messageId = String(row.messageId ?? '');
+            if (deps.seen.has(messageId))
+                continue;
+            const text = typeof row.text === 'string' ? row.text : '';
+            if (!text.trim())
+                continue;
+            await deps.onMessage(text, { ...row, chatId: news.chatId });
+            delivered++;
+            remaining--;
+        }
+        if (!page.hasMore || !page.latestSequence)
+            break;
+        after = page.latestSequence;
+        pages++;
     }
     return delivered;
 }
@@ -81,51 +75,77 @@ export async function pollInboxOnce(deps, waitSeconds = 0) {
     const label = deps.label ?? 'inboxLoop';
     const inbox = new InboxClient(deps.creds.operatorKey, deps.creds.agentId, deps.baseUrl);
     const reader = new ContextReadClient(deps.creds.operatorKey, deps.creds.agentId, deps.baseUrl);
-    const grants = new GrantsClient(deps.creds.operatorKey, deps.creds.agentId, deps.baseUrl);
     const envelope = await inbox.getInbox(waitSeconds > 0 ? { waitSeconds } : {});
-    const countCap = envelope.countCap;
     let messagesDelivered = 0;
     let resourceEvents = 0;
-    const toAck = [];
-    if (envelope.truncatedScopes > 0) {
-        // Informational only — does NOT block acking the scopes returned below.
-        // truncatedScopes just means the caller's total reach exceeded the server's
-        // per-call scope cap; each returned scope is still an independently accurate,
-        // safe-to-ack unit of news. Never acking here would make a busy agent
-        // (reach > cap) re-deliver its whole backlog every pass forever.
-        warn(label, `inbox truncatedScopes=${envelope.truncatedScopes} (reach exceeds per-call cap — examined scopes are still acked normally)`);
+    let tasksDelivered = 0;
+    if (envelope.deliveriesCapped) {
+        // Informational only — does NOT block acking what WAS handed over. The
+        // tail stays unacked and arrives on the next pass; never acking here would
+        // make a badly backed-up agent replay its whole backlog forever.
+        warn(label, 'inbox deliveriesCapped (more mail than one envelope carries — the tail follows on the next pass)');
     }
-    for (const scope of envelope.scopes) {
-        const chatIds = await chatIdsForScope(scope, deps.creds, grants);
-        if (!chatIds.length && (scope.newMessages > 0 || scope.newArtifacts > 0)) {
-            warn(label, `no chat ids for scope ${scope.scope.kind}:${scope.scope.id} (${scope.newMessages} msgs)`);
-        }
-        if (scope.newMessages > 0 && chatIds.length) {
-            const n = await deliverMessagesForScope(deps, scope, chatIds, reader, countCap);
-            messagesDelivered += n;
-            log(label, `scope ${scope.scope.kind}:${scope.scope.id} delivered ${n} message(s)`);
-        }
-        if (scope.newArtifacts > 0) {
-            for (const chatId of chatIds) {
-                await deps.onResourceEvent({
-                    kind: 'artifact',
-                    ts: scope.latestAt ?? new Date().toISOString(),
-                    resourceId: chatId,
-                    chatId,
-                    change: 'created',
-                });
-                resourceEvents++;
-            }
-        }
-        if (scope.latestAt && (scope.newMessages > 0 || scope.newArtifacts > 0)) {
-            toAck.push({
-                kind: scope.scope.kind,
-                id: scope.scope.id,
-                upTo: scope.latestAt,
-            });
+    // Oldest delivery per chat: where to start reading that chat's messages.
+    const earliestByChat = new Map();
+    for (const d of envelope.deliveries) {
+        if (!d.chatId)
+            continue;
+        const seen = earliestByChat.get(d.chatId);
+        if (!seen || d.ts < seen)
+            earliestByChat.set(d.chatId, d.ts);
+    }
+    for (const news of envelope.chats) {
+        const earliest = earliestByChat.get(news.chatId) ?? news.latestAt;
+        const n = await deliverMessagesForChat(deps, news, earliest, reader);
+        messagesDelivered += n;
+        if (n > 0)
+            log(label, `chat ${news.chatId} delivered ${n} message(s)`);
+    }
+    // Everything that is not chat text is handed over as a resource event, from
+    // the delivery itself — the reference already carries the ids the host needs,
+    // so nothing has to be re-derived to name what changed.
+    for (const d of envelope.deliveries) {
+        if (d.kind === 'message')
+            continue;
+        const key = `delivery:${d.kind}:${d.resourceId}:${d.ts}`;
+        if (deps.seen.has(key))
+            continue;
+        deps.seen.mark(key);
+        await deps.onResourceEvent({
+            kind: d.kind,
+            ts: d.ts,
+            resourceId: d.resourceId,
+            ...(d.chatId ? { chatId: d.chatId } : {}),
+            ...(d.agreementId ? { agreementId: d.agreementId } : {}),
+            ...(d.taskId ? { taskId: d.taskId } : {}),
+            change: 'created',
+        });
+        resourceEvents++;
+    }
+    // ZIG-973: the work channel. An open assigned task is redelivered on every
+    // pass until it closes (that IS the durable-wait contract), so dedup on
+    // taskId+updatedAt — a genuinely touched task wakes again, an untouched one
+    // doesn't storm the lane every long-poll.
+    for (const task of envelope.tasksAwaitingMe ?? []) {
+        const key = `task:${task.taskId}:${task.updatedAt ?? ''}`;
+        if (deps.seen.has(key))
+            continue;
+        deps.seen.mark(key);
+        if (deps.onTask) {
+            await deps.onTask(task);
+            tasksDelivered++;
         }
     }
+    if (envelope.truncatedTasks) {
+        warn(label, `inbox truncatedTasks=${envelope.truncatedTasks} (more assigned tasks than one pass surfaces — they appear as earlier ones close)`);
+    }
+    // Pending decisions are standing state, not deliveries: they keep appearing
+    // until answered, so dedup them the same way tasks are deduped.
     for (const proposal of envelope.proposalsAwaitingMe) {
+        const key = `proposal:${proposal.agreementId}`;
+        if (deps.seen.has(key))
+            continue;
+        deps.seen.mark(key);
         await deps.onResourceEvent({
             kind: 'agreement',
             ts: proposal.proposedAt ?? new Date().toISOString(),
@@ -136,18 +156,21 @@ export async function pollInboxOnce(deps, waitSeconds = 0) {
         });
         resourceEvents++;
     }
-    let acked = 0;
-    if (toAck.length) {
-        await inbox.ack(toAck);
-        acked = toAck.length;
-        log(label, `acked ${acked} scope(s)`);
+    // Act, then ack: everything above has been handed to the host, so the
+    // watermark may now move past it. A crash before this point redelivers.
+    let acked = false;
+    if (envelope.ackTo) {
+        await inbox.ack(envelope.ackTo);
+        acked = true;
+        log(label, `acked up to ${envelope.ackTo}`);
     }
     return {
-        scopes: envelope.scopes.length,
+        deliveries: envelope.deliveries.length,
         messagesDelivered,
         resourceEvents,
+        tasksDelivered,
         acked,
-        truncated: envelope.truncatedScopes > 0,
+        truncated: envelope.deliveriesCapped,
     };
 }
 const DEFAULT_WAIT_SECONDS = 25;
@@ -160,18 +183,25 @@ function sleep(ms) {
  * 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 function runInboxLoop(deps, opts = {}) {
     const label = deps.label ?? 'inboxLoop';
     const waitSeconds = opts.waitSeconds ?? DEFAULT_WAIT_SECONDS;
     let running = true;
     let consecutiveErrors = 0;
+    let first = true;
     const done = (async () => {
         while (running) {
             try {
-                await pollInboxOnce(deps, waitSeconds);
+                await pollInboxOnce(deps, first ? 0 : waitSeconds);
+                first = false;
                 consecutiveErrors = 0;
             }
             catch (err) {

package/dist/server/runLauncher.js

@@ -82,11 +82,17 @@ async function runFleet(configs, { operatorKey, wsUrl = process.env.WS_URL, port
         }
     }
     if (preStart.length > 0) {
-        await Promise.all(preStart.map(id => pool.startAgent(id)
-            .then(() => runtimeLog.debug(label, `Pre-started "${id}"`))
+        // Pinned: these agents are up because the operator named them
+        // (WAKE_AGENTS), not because work arrived, so the idle sweep must not
+        // retire them. It used to: an empty long-poll isn't "activity", so a quiet
+        // pre-started agent was torn down after idleTimeoutMs and only lazy start
+        // could bring it back — which at fleet size it cannot (ZIG-965 tail).
+        await Promise.all(preStart.map(id => pool.startAgent(id, { pinned: true })
+            .then(() => runtimeLog.debug(label, `Pre-started "${id}" (pinned)`))
             .catch(err => runtimeLog.warn(label, `Could not pre-start "${id}": ${err.message}`))));
     }
-    runtimeLog.info(label, `Ready — ${pool.size} agent(s) registered, ${pool.listActive().length} connected`);
+    runtimeLog.info(label, `Ready — ${pool.size} agent(s) registered, ${pool.listActive().length} connected` +
+        (pool.listPinned().length ? ` (${pool.listPinned().length} pinned)` : ''));
     process.on('SIGTERM', async () => {
         runtimeLog.info(label, 'SIGTERM — shutting down');
         pool.stopControl();

package/dist/server/staleBacklogGate.d.ts

@@ -18,7 +18,7 @@
  * `pool.startAgent()` / preStart are untouched, and an agent with ANY fresh item
  * starts normally (its own inbox loop then drains the stale backlog too).
  */
-import type { InboxEnvelope, InboxOperatorAgentEntry } from '@ziggs-ai/api-client';
+import type { InboxOperatorAgentEntry } from '@ziggs-ai/api-client';
 export declare const DEFAULT_REPLAY_MAX_AGE_MS: number;
 export interface ReplayPolicy {
     /** Skip slices whose newest actionable item is older than this. */
@@ -33,11 +33,15 @@ export interface ReplayPolicy {
 export declare function parseReplayMaxAge(raw: string): number | null;
 export declare function resolveReplayPolicy(env?: NodeJS.ProcessEnv): ReplayPolicy;
 /**
- * Newest actionable timestamp across an agent's slice: scope activity,
- * proposals, and connection/MCP requests. Null when nothing carries a
- * timestamp (e.g. a joined-but-idle chat) — age unprovable, treated as fresh.
+ * Newest actionable instant for an agent, from its operator-sweep entry.
+ *
+ * The sweep hands this over directly now — it is the agent's delivery
+ * watermark — where this used to fold together the max timestamp across every
+ * channel of a whole envelope. An agent surfaced only for open work carries no
+ * delivery instant: age is unprovable, so it is treated as fresh and started.
+ * Stale-skipping a half-finished task would strand it.
  */
-export declare function newestActionableAt(inbox: InboxEnvelope): number | null;
+export declare function newestActionableAt(entry: InboxOperatorAgentEntry): number | null;
 export declare function formatAge(ms: number): string;
 export interface StaleBacklogGateOptions extends ReplayPolicy {
     label?: string;

package/dist/server/staleBacklogGate.js

@@ -30,39 +30,19 @@ export function resolveReplayPolicy(env = process.env) {
     return { maxAgeMs, replayAll };
 }
 /**
- * Newest actionable timestamp across an agent's slice: scope activity,
- * proposals, and connection/MCP requests. Null when nothing carries a
- * timestamp (e.g. a joined-but-idle chat) — age unprovable, treated as fresh.
+ * Newest actionable instant for an agent, from its operator-sweep entry.
+ *
+ * The sweep hands this over directly now — it is the agent's delivery
+ * watermark — where this used to fold together the max timestamp across every
+ * channel of a whole envelope. An agent surfaced only for open work carries no
+ * delivery instant: age is unprovable, so it is treated as fresh and started.
+ * Stale-skipping a half-finished task would strand it.
  */
-export function newestActionableAt(inbox) {
-    let newest = null;
-    const consider = (iso) => {
-        if (!iso)
-            return;
-        const t = Date.parse(iso);
-        if (!Number.isNaN(t) && (newest == null || t > newest))
-            newest = t;
-    };
-    for (const scope of inbox.scopes ?? [])
-        consider(scope.latestAt);
-    for (const p of inbox.proposalsAwaitingMe ?? [])
-        consider(p.proposedAt);
-    for (const r of inbox.connectionRequestsAwaitingMe ?? [])
-        consider(r.requestedAt);
-    for (const r of inbox.mcpServerRequestsAwaitingMe ?? [])
-        consider(r.requestedAt);
-    return newest;
-}
-/** Unread items in a slice, for the summary line. Counts are backend-capped. */
-function countItems(inbox) {
-    let items = 0;
-    for (const scope of inbox.scopes ?? []) {
-        items += (scope.newMessages ?? 0) + (scope.newArtifacts ?? 0);
-    }
-    items += (inbox.proposalsAwaitingMe ?? []).length;
-    items += (inbox.connectionRequestsAwaitingMe ?? []).length;
-    items += (inbox.mcpServerRequestsAwaitingMe ?? []).length;
-    return items;
+export function newestActionableAt(entry) {
+    if (!entry.deliveredUpTo)
+        return null;
+    const t = Date.parse(entry.deliveredUpTo);
+    return Number.isNaN(t) ? null : t;
 }
 export function formatAge(ms) {
     if (ms >= 86_400_000)
@@ -86,7 +66,6 @@ export function createStaleBacklogGate({ maxAgeMs, replayAll, label = 'launcher'
     const emit = log ?? ((line) => runtimeLog.warn(label, line));
     const announced = new Set();
     let pendingAgents = [];
-    let pendingItems = 0;
     let flushScheduled = false;
     // One envelope's entries are gated synchronously; a microtask-deferred
     // flush turns a whole boot flood into a single summary line.
@@ -96,20 +75,21 @@ export function createStaleBacklogGate({ maxAgeMs, replayAll, label = 'launcher'
             return;
         const preview = pendingAgents.slice(0, 5).join(', ');
         const more = pendingAgents.length > 5 ? `, +${pendingAgents.length - 5} more` : '';
-        emit(`startup backlog policy: skipped ${pendingItems} stale item(s) across ${pendingAgents.length} agent(s) older than ${formatAge(maxAgeMs)} (${preview}${more}) — set FLEET_REPLAY_STALE=1 to replay them`);
+        emit(`startup backlog policy: skipped ${pendingAgents.length} agent(s) whose newest mail is older than ${formatAge(maxAgeMs)} (${preview}${more}) — set FLEET_REPLAY_STALE=1 to replay them`);
         pendingAgents = [];
-        pendingItems = 0;
     };
     return (entry) => {
         if (replayAll)
             return true;
-        const newest = newestActionableAt(entry.inbox);
+        // Open work always starts, however old: the task is unfinished, not stale.
+        if (entry.hasOpenTasks)
+            return true;
+        const newest = newestActionableAt(entry);
         if (newest == null || now() - newest <= maxAgeMs)
             return true;
         if (!announced.has(entry.agentId)) {
             announced.add(entry.agentId);
             pendingAgents.push(entry.agentId);
-            pendingItems += countItems(entry.inbox);
             if (!flushScheduled) {
                 flushScheduled = true;
                 queueMicrotask(flush);

package/dist/server/tools/tier1/protocolTools.js

@@ -19,14 +19,14 @@ function handlerFor(operation) {
         return result;
     };
 }
-export const agreementProposeTool = defineTool('agreement_propose', { description: { type: 'string', required: true }, proposedTo: { type: 'string', required: true }, engagementKind: { type: 'string', enum: ['hire', 'service'], description: 'Contract type. Defaults to service when omitted.' }, parentAgreementId: 'string', parentTaskId: 'string', providerId: { type: 'string', description: 'Who does the work — required on direct proposals, forbidden on broadcasts (the claiming agent fills the open side). Pass your own id when YOU are offering to do the work, or the proposedTo id when you are commissioning the RECIPIENT. Naming any other third party requires that party to have a matching published offer. The payer is always derived as the non-providing side.' }, price: 'number', lifecycle: 'string', expiresAt: 'string', maxExecutions: 'number', agreementDescription: 'string', plan: { type: 'object' }, planReviewTiming: 'string', requireMidWorkPlanAck: 'boolean' }, handlerFor('agreement-propose'), { description: 'Propose a contract to a user, agent, or as an open broadcast. Direction is stated, never guessed: providerId = your own id ("I work, you pay") or providerId = proposedTo ("you work, I pay"). Required on direct proposals; omit it only for a broadcast — proposedTo="everyone" (fully public — any agent may claim) or proposedTo="org" (scoped to your org). engagementKind defaults to service.', isAgreementCreation: true });
+export const agreementProposeTool = defineTool('agreement_propose', { description: { type: 'string', required: true }, proposedTo: { type: 'string', required: true }, engagementKind: { type: 'string', enum: ['hire', 'service'], description: 'Contract type. Defaults to service when omitted.' }, parentAgreementId: 'string', parentTaskId: 'string', providerId: { type: 'string', description: 'Who does the work — required on direct proposals, forbidden on broadcasts (the claiming agent fills the open side). Pass your own id when YOU are offering to do the work, or the proposedTo id when you are commissioning the RECIPIENT. Naming any other third party requires that party to have a matching published offer. The payer is always derived as the non-providing side.' }, price: 'number', lifecycle: 'string', expiresAt: 'string', maxExecutions: 'number', billing: { type: 'string', enum: ['total', 'per_task'], description: "How price reads: 'total' (default, escrowed and paid at the end) or 'per_task' (a rate settled as each task completes — standing agreements only, and the default for a hire)." }, agreementDescription: 'string', plan: { type: 'object' }, planReviewTiming: 'string', requireMidWorkPlanAck: 'boolean' }, handlerFor('agreement-propose'), { description: 'Propose a contract to a user, agent, or as an open broadcast. Direction is stated, never guessed: providerId = your own id ("I work, you pay") or providerId = proposedTo ("you work, I pay"). Required on direct proposals; omit it only for a broadcast — proposedTo="everyone" (fully public — any agent may claim) or proposedTo="org" (scoped to your org). engagementKind defaults to service. Agreements are STANDING by default (no expiry, unlimited tasks under one agreement); set expiresAt or maxExecutions only when the engagement should end on its own.', isAgreementCreation: true });
 export const agreementSubcontractTool = defineTool('agreement_subcontract', { description: { type: 'string', required: true }, executorId: { type: 'string', required: true }, parentAgreementId: { type: 'string', required: true }, parentTaskId: 'string', payerId: 'string', price: 'number', lifecycle: 'string', expiresAt: 'string', maxExecutions: 'number', agreementDescription: 'string', plan: { type: 'object' }, planReviewTiming: 'string', requireMidWorkPlanAck: 'boolean' }, handlerFor('agreement-subcontract'), { description: 'Delegate work to another agent under an existing parent agreement. Requires parentAgreementId.', isAgreementCreation: true });
 export const agreementRespondTool = defineTool('agreement_respond', { agreementId: { type: 'string', required: true }, action: { type: 'string', required: true, enum: ['approve', 'reject'] } }, handlerFor('agreement-respond'), { description: 'Approve or reject a pending agreement proposal.' });
 export const taskUpdateTool = defineTool('task_update', { taskId: { type: 'string', required: true }, status: { type: 'string', required: true, enum: ['completed', 'failed', 'cancelled'] }, result: 'string' }, handlerFor('task-update'), { description: 'Transition a task to completed, failed, or cancelled. Include a result string for completed tasks.' });
 export const agreementCounterProposalTool = defineTool('agreement_counter_proposal', { agreementId: { type: 'string', required: true }, price: 'number', agreementDescription: 'string', expiresAt: 'string', lifecycle: 'string', maxExecutions: 'number', description: 'string', plan: { type: 'object' }, planReviewTiming: 'string', requireMidWorkPlanAck: 'boolean' }, handlerFor('agreement-counter-proposal'), { description: 'Counter a pending proposal with revised terms instead of approving or rejecting. Check status first with agreement_check_proposal.' });
 export const agreementCheckProposalTool = defineTool('agreement_check_proposal', { agreementId: { type: 'string', required: true } }, handlerFor('agreement-check-proposal'), { description: 'Read the current proposal status for an agreement (pending, approved, rejected, countered, expired).' });
 export const agreementRevokeTool = defineTool('agreement_revoke', { agreementId: { type: 'string', required: true } }, handlerFor('agreement-revoke'), { description: 'Revoke a pending proposal you created so it can no longer be approved. Use when the user has clearly moved on to a different request before responding to the previous proposal card.' });
-export const agreementFulfillTool = defineTool('agreement_fulfill', { agreementId: { type: 'string', required: true } }, handlerFor('agreement-fulfill'), { description: 'Mark an agreement you provide as fulfilled (complete) once its work is delivered — closes the engagement so it no longer reads as in-progress. Use on your hire after the final deliverable is done and delivered to the human.' });
+export const agreementFulfillTool = defineTool('agreement_fulfill', { agreementId: { type: 'string', required: true } }, handlerFor('agreement-fulfill'), { description: 'END an agreement you provide — permanently. Fulfilling terminates the whole relationship, not one deliverable: every grant it conferred is revoked, its shared space is torn down, and it cannot be reopened. Finished WORK is reported via task_update (the task closes; the agreement stays standing for the next task). Only fulfill when the engagement\'s full scope is delivered and nothing more is expected — never a standing hire that just finished a task.' });
 export const taskUpdatePlanStepTool = defineTool('task_update_plan_step', { taskId: { type: 'string', required: true }, stepId: { type: 'string', required: true }, status: { type: 'string', required: true }, result: 'string' }, handlerFor('task-update-plan-step'), { description: "Update the status of a single step within a task's plan." });
 export const taskSpawnTool = defineTool('task_spawn', { agreementId: { type: 'string', required: true }, description: { type: 'string', required: true }, parentTaskId: 'string', assigneeId: { type: 'string', description: 'Explicitly hand this task to one specific agent (e.g. a worker your orchestrator selected via agent search) instead of leaving it unassigned. Must be a party on the agreement (payer, provider, creator, or creator agent).' }, inputArtifactIds: { type: 'array', items: { type: 'string' }, description: 'ZIG-734: prior-step output artifact handles for structured input links.' }, plan: { type: 'object' }, planReviewTiming: 'string', requireMidWorkPlanAck: 'boolean' }, handlerFor('task-spawn'), { description: 'Spawn a new task under an existing approved agreement. Use when the contract is already in place. Pass assigneeId to delegate the task to a specific agent rather than leaving it open.' });
 export const PROTOCOL_TOOLS = [

package/dist/types.d.ts

@@ -313,8 +313,9 @@ export interface ContextSnapshot {
      * The session's chat no longer resolves on the backend (messages read
      * 404'd) — deleted or never visible to this agent. Message-triggered wakes
      * check this and skip the LLM instead of reasoning over a fabricated empty
-     * history. Agreement-keyed lanes also set it (their sessionId is not a
-     * chat), so it only gates message wakes, never task lanes.
+     * history. Only gates message wakes. A bare agreementId as sessionId also
+     * trips it (ZIG-975) — that is a mis-keyed lane, not a legitimate task lane;
+     * task wakes should key on the agreement's origin/notification chat.
      */
     chatMissing?: boolean;
     /** Index signature so PromptBuilder's `ServerContext` can accept it directly. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "type": "module",
   "main": "dist/index.js",
@@ -26,7 +26,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.204",
     "@anthropic-ai/sdk": "^0.110.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "^0.4.0",
+    "@ziggs-ai/api-client": "^0.5.0",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0",