@ziggs-ai/agent-sdk 0.2.2 → 0.4.0

package/dist/server/ConnectionPool.d.ts

@@ -1,3 +1,17 @@
+/**
+ * ConnectionPool — multi-agent fleet manager.
+ *
+ * Holds N `AgentHostOptions` configs but only constructs/wakes an
+ * `AgentHost` (one WS connection) when needed. Idle hosts are slept after
+ * `idleTimeoutMs`. At most `maxActive` hosts are connected at a time; LRU
+ * eviction drops the oldest if the cap is reached. With `startControl`, a
+ * separate "launcher" socket receives backend-driven wake hints so the pool
+ * spins up the right host on demand.
+ *
+ * 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 { AgentHost, type AgentHostOptions } from '../AgentHost.js';
 interface ConnectionManagerMeta {
     domain?: string;
@@ -13,6 +27,11 @@ interface QueryFilter {
 export interface PoolOptions {
     maxActive?: number;
     idleTimeoutMs?: number;
+    /**
+     * Gate on the operator-poll lazy start (ZIG-910): return false to leave an
+     * actionable agent's host down this pass. Explicit startAgent()s are not gated.
+     */
+    shouldLazyStart?: (entry: InboxOperatorAgentEntry) => boolean;
 }
 export interface SendToOptions {
     timeoutMs?: number;
@@ -25,17 +44,17 @@ export declare class ConnectionPool {
     private readonly manager;
     private readonly configs;
     private readonly responseListeners;
-    constructor({ maxActive, idleTimeoutMs }?: PoolOptions);
+    constructor({ maxActive, idleTimeoutMs, shouldLazyStart }?: PoolOptions);
     /**
-     * Register N agent configs. Each will be lazily woken (a fresh
+     * Register N agent configs. Each will be lazily started (a fresh
      * `AgentHost` constructed + connected) the first time it's referenced.
      */
     register(configs: AgentHostOptions[], metaArr?: ConnectionManagerMeta[]): void;
-    wake(agentId: string): Promise<AgentHost>;
+    startAgent(agentId: string): Promise<AgentHost>;
     sleep(agentId: string): Promise<void>;
     disconnectAll(): Promise<void>;
     /**
-     * Wake the named agent, deliver a message, and wait for its first outbound
+     * Start the named agent, deliver a message, and wait for its first outbound
      * `send-message` effect — i.e. the agent's reply. Returns the reply text.
      *
      * The effectTap injected in `register` drains a per-agent listener queue;
@@ -44,7 +63,7 @@ export declare class ConnectionPool {
      */
     requestFrom(agentId: string, text: string, metadata?: Record<string, unknown>, { timeoutMs }?: SendToOptions): Promise<string>;
     /**
-     * Wake the named agent and deliver one wire frame to it. Returns once the
+     * Start the named agent and deliver one wire frame to it. Returns once the
      * host has finished processing.
      *
      * Note: does not return the agent's response. For request/response
@@ -52,11 +71,14 @@ export declare class ConnectionPool {
      */
     sendTo(agentId: string, text: string, metadata?: Record<string, unknown>, { timeoutMs }?: SendToOptions): Promise<null>;
     /**
-     * Open a launcher (control) socket that the backend uses to push wake
-     * hints for any of the registered agents. Pool spins up the right host
-     * lazily when a hint arrives.
+     * Start the fleet lazy-start loop (delivery law, phase 4): the manager
+     * long-polls `GET /inbox/operator` with this operator key and starts the host
+     * for any owned agent whose slice has actionable content. Each started host
+     * then consumes via its own per-agent inbox loop — this is ordinary lazy
+     * process management, not a pushed signal. `wsUrl` is accepted for
+     * back-compat but unused (the poll is HTTP).
      */
-    startControl({ wsUrl, operatorKey }?: ControlOptions): void;
+    startControl({ operatorKey }?: ControlOptions): void;
     stopControl(): void;
     query(filter: QueryFilter): string[];
     list(): string[];

package/dist/server/ConnectionPool.js

@@ -19,11 +19,11 @@ export class ConnectionPool {
     configs = new Map();
     // Listeners enqueued by requestFrom — drained on outbound send-message effects.
     responseListeners = new Map();
-    constructor({ maxActive = 50, idleTimeoutMs = 60_000 } = {}) {
-        this.manager = new ConnectionManager({ maxActive, idleTimeoutMs });
+    constructor({ maxActive = 50, idleTimeoutMs = 60_000, shouldLazyStart } = {}) {
+        this.manager = new ConnectionManager({ maxActive, idleTimeoutMs, shouldLazyStart });
     }
     /**
-     * Register N agent configs. Each will be lazily woken (a fresh
+     * Register N agent configs. Each will be lazily started (a fresh
      * `AgentHost` constructed + connected) the first time it's referenced.
      */
     register(configs, metaArr = []) {
@@ -56,7 +56,7 @@ export class ConnectionPool {
                     },
                 });
                 await host.connectAsync();
-                runtimeLog.debug('ConnectionPool', `woke "${agentId}" (active: ${this.manager.listActive().length}/${this.maxActive})`);
+                runtimeLog.debug('ConnectionPool', `started "${agentId}" (active: ${this.manager.listActive().length}/${this.maxActive})`);
                 return host;
             }, async (host) => {
                 host.disconnect();
@@ -64,8 +64,8 @@ export class ConnectionPool {
             }, metaByAgentId.get(agentId));
         }
     }
-    async wake(agentId) {
-        return await this.manager.wake(agentId);
+    async startAgent(agentId) {
+        return await this.manager.startAgent(agentId);
     }
     async sleep(agentId) {
         return this.manager.sleep(agentId);
@@ -74,7 +74,7 @@ export class ConnectionPool {
         return this.manager.sleepAll();
     }
     /**
-     * Wake the named agent, deliver a message, and wait for its first outbound
+     * Start the named agent, deliver a message, and wait for its first outbound
      * `send-message` effect — i.e. the agent's reply. Returns the reply text.
      *
      * The effectTap injected in `register` drains a per-agent listener queue;
@@ -82,7 +82,7 @@ export class ConnectionPool {
      * does not reply within `timeoutMs` (default 60 s for LLM agents).
      */
     async requestFrom(agentId, text, metadata = {}, { timeoutMs = 60_000 } = {}) {
-        const host = await this.wake(agentId);
+        const host = await this.startAgent(agentId);
         return new Promise((resolve, reject) => {
             let settled = false;
             const timer = setTimeout(() => {
@@ -123,39 +123,36 @@ export class ConnectionPool {
         });
     }
     /**
-     * Wake the named agent and deliver one wire frame to it. Returns once the
+     * Start the named agent and deliver one wire frame to it. Returns once the
      * host has finished processing.
      *
      * Note: does not return the agent's response. For request/response
      * semantics use `requestFrom`.
      */
     async sendTo(agentId, text, metadata = {}, { timeoutMs = 30_000 } = {}) {
-        const host = await this.wake(agentId);
+        const host = await this.startAgent(agentId);
         const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error(`sendTo timeout for "${agentId}" after ${timeoutMs}ms`)), timeoutMs));
         await Promise.race([host.handleMessage(text, metadata), timeoutPromise]);
         this.manager.touch(agentId);
         return null;
     }
     /**
-     * Open a launcher (control) socket that the backend uses to push wake
-     * hints for any of the registered agents. Pool spins up the right host
-     * lazily when a hint arrives.
+     * Start the fleet lazy-start loop (delivery law, phase 4): the manager
+     * long-polls `GET /inbox/operator` with this operator key and starts the host
+     * for any owned agent whose slice has actionable content. Each started host
+     * then consumes via its own per-agent inbox loop — this is ordinary lazy
+     * process management, not a pushed signal. `wsUrl` is accepted for
+     * back-compat but unused (the poll is HTTP).
      */
-    startControl({ wsUrl, operatorKey } = {}) {
-        if (!wsUrl || !operatorKey) {
-            runtimeLog.warn('ConnectionPool', 'startControl: wsUrl and operatorKey are required — skipping');
+    startControl({ operatorKey } = {}) {
+        if (!operatorKey) {
+            runtimeLog.warn('ConnectionPool', 'startControl: operatorKey is required — skipping');
             return;
         }
-        // ConnectionManager only accepts `control` at construction; mutating its
-        // private field is the smallest way to add it later. (Cleaner fix lives
-        // in api-client: expose a `setControl` setter.)
-        this.manager['_controlOpts'] = { wsUrl, operatorKey };
-        this.manager.start();
+        this.manager.start(operatorKey);
     }
     stopControl() {
-        const m = this.manager;
-        m['_controlHandle']?.close?.();
-        m['_controlHandle'] = null;
+        void this.manager.stop();
     }
     query(filter) { return this.manager.query(filter); }
     list() { return this.manager.list(); }

package/dist/server/ZiggsEffectHandler.js

@@ -69,7 +69,7 @@ function previewToolArgs(args) {
  * Chat timeline: `Message.tsx` parses `entryType: artifact`, `content_type: operation` with
  * `operation_*:{json}` where json includes `state` and `tool`.
  */
-async function emitToolOperationArtifact(client, chatId, phase, payload) {
+async function emitToolOperationArtifact(client, chatId, phase, payload, idempotencyKey) {
     const prefix = phase === 'started' ? 'operation_started' : phase === 'completed' ? 'operation_completed' : 'operation_error';
     const text = `${prefix}:${JSON.stringify(payload)}`;
     try {
@@ -78,6 +78,7 @@ async function emitToolOperationArtifact(client, chatId, phase, payload) {
             text,
             content_type: 'operation',
             visibility: 'agent-private',
+            idempotencyKey,
         });
     }
     catch (e) {
@@ -108,7 +109,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
         state: 'started',
         tool: effect.name,
         ...(argsPreview ? { args: argsPreview } : {}),
-    });
+    }, effect.wakeKeys?.artifactKey());
     try {
         const lastUser = roster.users.find((u) => u.userId || u.id);
         // Accumulate token usage from any nested LLM call the tool makes (llmTool),
@@ -141,6 +142,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
             senderType: effect.senderType ?? (lastUser ? 'USER' : undefined),
             onBehalfOfAgreementId: effect.onBehalfOfAgreementId,
             memory: effect.memory,
+            wakeKeys: effect.wakeKeys,
             reportUsage,
             turnScratch: {},
         });
@@ -148,7 +150,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
             state: 'completed',
             tool: effect.name,
             result: clipForOperationArtifact(result),
-        });
+        }, effect.wakeKeys?.artifactKey());
         sendTelemetry(deps.telemetryClient, buildToolIngestPayload({
             sessionId: effect.sessionId,
             tool: effect.name,
@@ -166,7 +168,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
             state: 'failed',
             tool: effect.name,
             error: errMsg,
-        });
+        }, effect.wakeKeys?.artifactKey());
         sendTelemetry(deps.telemetryClient, buildToolIngestPayload({
             sessionId: effect.sessionId,
             tool: effect.name,
@@ -242,13 +244,13 @@ export function createZiggsEffectHandler(deps) {
                 let usage;
                 if (deps.llm.chatMessagesStream) {
                     const streamed = await deps.llm.chatMessagesStream(messages, (chunk) => {
-                        // Live-stream display is best-effort. The transport's send rejects
-                        // empty/whitespace-only content (WebSocketClient: content.trim() === ''),
-                        // and a whitespace-only chunk (e.g. a leading newline) is truthy yet
-                        // still throws — which, uncaught, aborts the whole stream and loses the
-                        // entire reply (e.g. a composer's final synthesis). Swallow chunk-send
-                        // failures; `text` accumulates independently and the final send-message
-                        // (below, in runTurn) carries the full reply regardless.
+                        // Live-token display is best-effort and optional. Hosted agents wire
+                        // no chunkSender (delivery law, phase 4: no agent socket, no live
+                        // chunk transport), so partials are simply dropped — `text`
+                        // accumulates independently and the final send-message (below, in
+                        // runTurn) carries the full reply as one whole HTTP message. Any
+                        // chunk-send failure is swallowed so a display hiccup never aborts
+                        // the stream and loses the reply.
                         try {
                             if (chunk && chunk.trim())
                                 deps.chunkSender?.(sessionId, receiverId, chunk, messageId);
@@ -288,7 +290,9 @@ export function createZiggsEffectHandler(deps) {
                 // visible to this agent across turns, not to other chat parties.
                 try {
                     if (effect.entry.kind === 'thought' && typeof effect.entry.text === 'string') {
-                        await deps.artifactsClient.recordThought(effect.sessionId, effect.entry.text);
+                        await deps.artifactsClient.recordThought(effect.sessionId, effect.entry.text, {
+                            idempotencyKey: effect.idempotencyKey,
+                        });
                     }
                     else {
                         await deps.artifactsClient.write({
@@ -296,6 +300,7 @@ export function createZiggsEffectHandler(deps) {
                             text: JSON.stringify(effect.entry),
                             content_type: String(effect.entry.kind ?? 'event'),
                             visibility: 'agent-private',
+                            idempotencyKey: effect.idempotencyKey,
                         });
                     }
                 }

package/dist/server/createHealthServer.js

@@ -19,11 +19,11 @@ function readJsonBody(req) {
 export function createHealthServer({ port = Number(process.env.PORT) || 8080, label = 'agents', pool, } = {}) {
     const server = createServer(async (req, res) => {
         const url = req.url ?? '/';
-        const wakeMatch = url.match(/^\/fleet-wake\/([^/?]+)/);
-        if (req.method === 'POST' && wakeMatch && pool) {
-            const agentId = decodeURIComponent(wakeMatch[1]);
+        const startMatch = url.match(/^\/fleet-wake\/([^/?]+)/);
+        if (req.method === 'POST' && startMatch && pool) {
+            const agentId = decodeURIComponent(startMatch[1]);
             try {
-                await pool.wake(agentId);
+                await pool.startAgent(agentId);
                 res.writeHead(200, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ ok: true, agentId, active: pool.listActive().includes(agentId) }));
             }
@@ -45,7 +45,7 @@ export function createHealthServer({ port = Number(process.env.PORT) || 8080, la
                     res.end(JSON.stringify({ ok: false, error: 'agentId, chatId, text, senderId required' }));
                     return;
                 }
-                const host = (await pool.wake(agentId));
+                const host = (await pool.startAgent(agentId));
                 await host.handleMessage(text, {
                     chatId,
                     entryType: 'message',

package/dist/server/inboxLoop.d.ts

@@ -0,0 +1,50 @@
+import { 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.
+ */
+export interface InboxLoopDeps {
+    creds: Creds;
+    ownAgentId: string;
+    baseUrl?: string;
+    seen: SeenMessages;
+    onMessage: (text: string, metadata: Record<string, unknown>) => Promise<void>;
+    onResourceEvent: (event: Record<string, unknown>) => Promise<void>;
+    label?: string;
+}
+export interface InboxPassResult {
+    scopes: number;
+    messagesDelivered: number;
+    resourceEvents: number;
+    acked: number;
+    truncated: boolean;
+}
+/**
+ * One long-poll pass: hold up to `waitSeconds` for new inbox content, then read
+ * the deltas, deliver them into the host, and ack. Returns what it delivered.
+ * Reused each iteration of {@link runInboxLoop}; also usable as a single catch-up
+ * read (`waitSeconds: 0`) at bootstrap.
+ */
+export declare function pollInboxOnce(deps: InboxLoopDeps, waitSeconds?: number): Promise<InboxPassResult>;
+export interface InboxLoopHandle {
+    /** Stop the loop after the current pass; resolves when it has fully exited. */
+    stop(): Promise<void>;
+    /** True while the loop is running. */
+    readonly running: boolean;
+}
+/**
+ * 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.
+ */
+export declare function runInboxLoop(deps: InboxLoopDeps, opts?: {
+    waitSeconds?: number;
+}): InboxLoopHandle;

package/dist/server/{InboxCatchUp.js → inboxLoop.js}

@@ -1,4 +1,4 @@
-import { ContextReadClient, GrantsClient, InboxClient, getChatsForAgreement, getAgreementStatus, } from '@ziggs-ai/api-client';
+import { ContextReadClient, GrantsClient, InboxClient, getChatsForAgreement, } from '@ziggs-ai/api-client';
 import { runtimeLog } from '../shared/runtimeLog.js';
 const READ_PAGE = 100;
 function log(label, msg) {
@@ -7,47 +7,7 @@ function log(label, msg) {
 function warn(label, msg) {
     runtimeLog.warn(label, msg);
 }
-const TERMINAL_AGREEMENT_STATUSES = new Set(['fulfilled', 'cancelled', 'refunded']);
-/** ZIG-832 P4: is this agreement finished (so its backlog must not be re-run)? */
-async function isTerminalAgreement(agreementId, creds) {
-    try {
-        const res = (await getAgreementStatus(agreementId, creds));
-        const status = res?.status ?? res?.agreement?.status;
-        return status != null && TERMINAL_AGREEMENT_STATUSES.has(status);
-    }
-    catch {
-        // On lookup failure, don't skip — fall through to normal delivery.
-        return false;
-    }
-}
-/** Map Mongo message row → wire metadata for normalizeIncomingEvent. */
-function rowToMetadata(row, chatId) {
-    const senderRaw = row.sender;
-    const senderId = String(senderRaw?.agentId ?? senderRaw?.id ?? '');
-    const receiver = row.receiver;
-    const senderType = senderRaw?.type ??
-        (receiver?.type === 'agent' ? 'agent' : 'user');
-    return {
-        chatId,
-        chat_id: chatId,
-        messageId: row.messageId,
-        sender: { id: senderId, type: senderType },
-        senderId,
-        senderType: String(senderType).toUpperCase(),
-        receiver: receiver ?? null,
-        receiverId: receiver?.id ?? null,
-        entryType: row.entryType ?? 'message',
-        content_type: row.content_type ?? row.contentType ?? 'text',
-        contentType: row.content_type ?? row.contentType ?? 'text',
-        task: row.task ?? null,
-        agreement: row.agreement ?? null,
-        operation: row.operation ?? null,
-        agreementId: row.agreementId ?? null,
-        timestamp: row.timestamp,
-        text: row.text,
-    };
-}
-async function chatIdsForScope(scope, creds, baseUrl, grants) {
+async function chatIdsForScope(scope, creds, grants) {
     const { kind, id } = scope.scope;
     switch (kind) {
         case 'chat':
@@ -57,8 +17,8 @@ async function chatIdsForScope(scope, creds, baseUrl, grants) {
             return [...new Set(links.map((l) => l.chatId).filter(Boolean))];
         }
         case 'org': {
-            // All pages of live chat grants — an org-scope catch-up must not miss
-            // chats hidden behind pagination (GET /grants defaults to one page).
+            // 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',
@@ -71,7 +31,7 @@ async function chatIdsForScope(scope, creds, baseUrl, grants) {
 }
 async function deliverMessagesForScope(deps, scope, chatIds, reader, countCap) {
     let delivered = 0;
-    const label = deps.label ?? 'InboxCatchUp';
+    const label = deps.label ?? 'inboxLoop';
     const expected = scope.newMessages;
     let remaining = expected >= countCap ? Number.POSITIVE_INFINITY : expected;
     for (const chatId of chatIds) {
@@ -95,8 +55,7 @@ async function deliverMessagesForScope(deps, scope, chatIds, reader, countCap) {
                 const text = typeof row.text === 'string' ? row.text : '';
                 if (!text.trim())
                     continue;
-                const metadata = rowToMetadata(row, chatId);
-                await deps.onMessage(text, metadata);
+                await deps.onMessage(text, { ...row, chatId });
                 delivered++;
                 if (remaining !== Number.POSITIVE_INFINITY)
                     remaining--;
@@ -113,49 +72,31 @@ async function deliverMessagesForScope(deps, scope, chatIds, reader, countCap) {
     return delivered;
 }
 /**
- * Pull-based recovery after reconnect (ZIG-434 / ZIG-446 / ZIG-454).
- * Inbox → read message deltas → deliver → ack. Push remains a hint;
- * this path survives backend restarts that drop in-memory pending queues.
+ * One long-poll pass: hold up to `waitSeconds` for new inbox content, then read
+ * the deltas, deliver them into the host, and ack. Returns what it delivered.
+ * Reused each iteration of {@link runInboxLoop}; also usable as a single catch-up
+ * read (`waitSeconds: 0`) at bootstrap.
  */
-export async function runInboxCatchUp(deps) {
-    const label = deps.label ?? 'InboxCatchUp';
+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();
+    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 actually
-        // returned below. truncatedScopes just means the caller's total reach
-        // exceeded the server's per-call scope cap (backend/src/inbox/inbox.service.ts,
-        // INBOX_MAX_SCOPES); each entry in envelope.scopes is still an
-        // independently accurate, safe-to-ack unit of news for that scope. Never
-        // acking here meant a busy long-lived agent (reach > cap) would never ack
-        // anything and re-deliver its entire backlog on every reconnect forever.
+        // 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)`);
     }
     for (const scope of envelope.scopes) {
-        // ZIG-832 P4: a re-host runs catch-up from the server watermark and would
-        // re-deliver an already-finished agreement's backlog, re-running a completed
-        // pipeline and burning tokens. If this is an agreement scope that has reached
-        // a terminal status, ack it (so it drops out of future catch-ups) and skip
-        // re-delivery. Only agreement scopes — chat scopes may carry genuinely new
-        // conversation, so those are never skipped on status. (The deeper fix, acking
-        // the watermark on the live-push path so nothing re-delivers, is tracked
-        // separately.)
-        if (scope.scope.kind === 'agreement' &&
-            (scope.newMessages > 0 || scope.newArtifacts > 0) &&
-            (await isTerminalAgreement(scope.scope.id, deps.creds))) {
-            if (scope.latestAt) {
-                toAck.push({ kind: scope.scope.kind, id: scope.scope.id, upTo: scope.latestAt });
-            }
-            log(label, `scope agreement:${scope.scope.id} terminal — acked, not re-delivered`);
-            continue;
-        }
-        const chatIds = await chatIdsForScope(scope, deps.creds, deps.baseUrl, grants);
+        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)`);
         }
@@ -201,9 +142,6 @@ export async function runInboxCatchUp(deps) {
         acked = toAck.length;
         log(label, `acked ${acked} scope(s)`);
     }
-    if (messagesDelivered > 0 || resourceEvents > 0) {
-        log(label, `catch-up complete: ${messagesDelivered} message(s), ${resourceEvents} resource hint(s)`);
-    }
     return {
         scopes: envelope.scopes.length,
         messagesDelivered,
@@ -212,3 +150,48 @@ export async function runInboxCatchUp(deps) {
         truncated: envelope.truncatedScopes > 0,
     };
 }
+const DEFAULT_WAIT_SECONDS = 25;
+const ERROR_BACKOFF_BASE_MS = 1_000;
+const ERROR_BACKOFF_MAX_MS = 30_000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, 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.
+ */
+export function runInboxLoop(deps, opts = {}) {
+    const label = deps.label ?? 'inboxLoop';
+    const waitSeconds = opts.waitSeconds ?? DEFAULT_WAIT_SECONDS;
+    let running = true;
+    let consecutiveErrors = 0;
+    const done = (async () => {
+        while (running) {
+            try {
+                await pollInboxOnce(deps, waitSeconds);
+                consecutiveErrors = 0;
+            }
+            catch (err) {
+                if (!running)
+                    break;
+                consecutiveErrors++;
+                const backoff = Math.min(ERROR_BACKOFF_MAX_MS, ERROR_BACKOFF_BASE_MS * 2 ** (consecutiveErrors - 1));
+                const jitter = backoff * (0.5 + (consecutiveErrors % 7) / 14); // deterministic-ish, no Math.random
+                warn(label, `inbox loop pass failed (#${consecutiveErrors}): ${err?.message ?? err} — retrying in ~${Math.round(jitter)}ms`);
+                await sleep(jitter);
+            }
+        }
+    })();
+    return {
+        get running() {
+            return running;
+        },
+        async stop() {
+            running = false;
+            await done.catch(() => { });
+        },
+    };
+}

package/dist/server/runLauncher.d.ts

@@ -18,7 +18,7 @@ interface FleetOptions extends SingleOptions {
     wsUrl?: string;
     agentMeta?: Record<string, unknown>[];
     primary?: AgentConfig | ((pool: ConnectionPool) => AgentConfig);
-    preWake?: string[];
+    preStart?: string[];
     poolOptions?: {
         maxActive?: number;
         idleTimeoutMs?: number;

package/dist/server/runLauncher.js

@@ -1,6 +1,8 @@
 import { ConnectionPool } from './ConnectionPool.js';
 import { AgentHost } from '../AgentHost.js';
 import { createHealthServer } from './createHealthServer.js';
+import { createStaleBacklogGate, resolveReplayPolicy } from './staleBacklogGate.js';
+import { boundKeyFleetWarning } from '../shared/operatorKeyClaims.js';
 import { runtimeLog } from '../shared/runtimeLog.js';
 export async function runLauncher(configOrConfigs, opts = {}) {
     if (Array.isArray(configOrConfigs))
@@ -34,8 +36,14 @@ async function runSingle(config, { operatorKey, label = 'agent', port = process.
     });
     return { agent, healthServer: server ?? undefined };
 }
-async function runFleet(configs, { operatorKey, wsUrl = process.env.WS_URL, port = process.env.PORT || 8080, healthServer = true, label = 'launcher', agentMeta, primary: primaryConfig, preWake = [], poolOptions, onShutdown, } = {}) {
-    const pool = new ConnectionPool(poolOptions);
+async function runFleet(configs, { operatorKey, wsUrl = process.env.WS_URL, port = process.env.PORT || 8080, healthServer = true, label = 'launcher', agentMeta, primary: primaryConfig, preStart = [], poolOptions, onShutdown, } = {}) {
+    // ZIG-910: don't resurrect stale backlogs at bootstrap. Env-driven default
+    // (FLEET_REPLAY_MAX_AGE / FLEET_REPLAY_STALE); an explicit
+    // poolOptions.shouldLazyStart wins.
+    const pool = new ConnectionPool({
+        shouldLazyStart: createStaleBacklogGate({ ...resolveReplayPolicy(), label }),
+        ...poolOptions,
+    });
     const effectiveKey = operatorKey ?? process.env.ZIGGS_OPERATOR_KEY;
     const decoratedConfigs = effectiveKey
         ? configs.map(c => (c.operatorKey ? c : { ...c, operatorKey: effectiveKey }))
@@ -50,10 +58,15 @@ async function runFleet(configs, { operatorKey, wsUrl = process.env.WS_URL, port
     }
     const controlKey = effectiveKey ?? configs.find(c => c.operatorKey)?.operatorKey ?? resolvedPrimaryConfig?.operatorKey;
     if (controlKey) {
+        // ZIG-911: an agent-bound key half-works in a confusing way — say the big
+        // thing once at startup instead of letting N-1 per-agent loops 403.
+        const boundWarning = boundKeyFleetWarning(controlKey, pool.size);
+        if (boundWarning)
+            runtimeLog.warn(label, boundWarning);
         pool.startControl({ wsUrl, operatorKey: controlKey });
     }
     else {
-        runtimeLog.warn(label, 'No operatorKey provided — skipping control socket');
+        runtimeLog.warn(label, 'No operatorKey provided — skipping fleet inbox poll (no agents will be lazily started)');
     }
     let primary = null;
     if (resolvedPrimaryConfig) {
@@ -68,10 +81,10 @@ async function runFleet(configs, { operatorKey, wsUrl = process.env.WS_URL, port
             runtimeLog.warn(label, `Primary agent "${resolvedPrimaryConfig.name || resolvedPrimaryConfig.ownAgentId || 'primary'}" failed to connect at startup: ${err.message} — will retry`);
         }
     }
-    if (preWake.length > 0) {
-        await Promise.all(preWake.map(id => pool.wake(id)
-            .then(() => runtimeLog.debug(label, `Pre-woke "${id}"`))
-            .catch(err => runtimeLog.warn(label, `Could not pre-wake "${id}": ${err.message}`))));
+    if (preStart.length > 0) {
+        await Promise.all(preStart.map(id => pool.startAgent(id)
+            .then(() => runtimeLog.debug(label, `Pre-started "${id}"`))
+            .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`);
     process.on('SIGTERM', async () => {