@ziggs-ai/agent-sdk 0.15.0 → 0.17.0

package/dist/{AgentHost.js → Agent.js}

@@ -1,30 +1,34 @@
+import { agreementLaneId, agreementIdFromLane } from '@ziggs-ai/api-client';
+import { createDeclaredPollRunner } from './platform/polls/declaredPollRunner.js';
 import { randomUUID } from 'node:crypto';
-import { Agent } from './agent/Agent.js';
-import { ClaudeSdkAgent } from './agent/ClaudeSdkAgent.js';
-import { applyBrainToHostOptions, isClaudeCognition, } from './brain/index.js';
-import { CLAUDE_SDK_TOOLS } from './agent/claudeSdkTools.js';
-import { resolveClaudeModel } from './agent/claudeCognition.js';
-import { CHAT_TOOLS } from './server/tools/tier2/chatTools.js';
-import { EventQueue } from './server/EventQueue.js';
-import { StateTimers } from './server/StateTimers.js';
-import { createZiggsEffectHandler } from './server/ZiggsEffectHandler.js';
+import { ZiggsBrain } from './brain/ZiggsBrain.js';
+import { ClaudeBrain } from './brain/ClaudeBrain.js';
+import { applyBrainToAgentOptions, isClaudeCognition, } from './brain/index.js';
+import { CLAUDE_SDK_TOOLS } from './brain/claudeSdkTools.js';
+import { resolveClaudeModel } from './brain/claudeCognition.js';
+import { CHAT_TOOLS } from './platform/tools/tier2/chatTools.js';
+import { EventQueue } from './platform/EventQueue.js';
+import { StateTimers } from './platform/StateTimers.js';
+import { createZiggsEffectHandler } from './platform/ZiggsEffectHandler.js';
 import { normalizeIncomingEvent } from './ingress/normalizeIncoming.js';
 import { PromptBuilder } from './runtime/PromptBuilder.js';
-import { InMemoryStore } from './memory/MemoryStore.js';
+import { InMemoryStore, memorySectionForWake, partitionMemoryStore, } from './memory/MemoryStore.js';
 import { ToolManager } from './tools/ToolManager.js';
 import { toolName } from './tools/defineTool.js';
-import { PROTOCOL_TOOLS } from './server/tools/tier1/protocolTools.js';
-import { marketplaceViewTool } from './server/tools/tier2/marketplaceTools.js';
+import { PROTOCOL_TOOLS } from './platform/tools/tier1/protocolTools.js';
+import { marketplaceViewTool } from './platform/tools/tier2/marketplaceTools.js';
 import { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
 import { AnthropicAdapter } from './adapters/AnthropicAdapter.js';
 import { ArtifactsClient, ConnectionsClient, ContextReadClient, TelemetryClient, sendChatMessage, } from '@ziggs-ai/api-client';
 import { normalizeNeeds, unmetNeeds, unmetNeedsMessage, } from './tools/needs.js';
-import { TaskService } from './server/tasks/TaskService.js';
-import { AgreementService } from './server/agreements/AgreementService.js';
-import { runInboxLoop } from './server/inboxLoop.js';
-import { requestExactMatch } from './server/requestMatch.js';
-import { SeenMessages } from './server/SeenMessages.js';
+import { TaskService } from './platform/tasks/TaskService.js';
+import { AgreementService } from './platform/agreements/AgreementService.js';
+import { runInboxLoop } from './platform/inboxLoop.js';
+import { requestExactMatch } from './platform/requestMatch.js';
+import { SeenMessages } from './platform/SeenMessages.js';
 import { runtimeLog } from './shared/runtimeLog.js';
+import { isTelemetryIngestEnabled, sendTelemetry, } from './platform/telemetryIngest.js';
+import { buildWakeOutcomePayload, classifyWakeOutcome, } from './runtime/wakeOutcome.js';
 /**
  * The single fleet-wide default model — the one place the fallback lives.
  * Change this (or set `LLM_MODEL`) to move the whole fleet; nothing hardcodes a
@@ -34,9 +38,9 @@ import { runtimeLog } from './shared/runtimeLog.js';
  */
 export const DEFAULT_MODEL = 'claude-haiku-4-5';
 // ConnectionPool lives in a separate module; resolved via a computed-path
-// dynamic import to avoid a circular import with AgentHost.
+// dynamic import to avoid a circular import with Agent.
 async function loadConnectionPool() {
-    const modPath = './server/ConnectionPool.js';
+    const modPath = './platform/ConnectionPool.js';
     const mod = await import(/* @vite-ignore */ modPath);
     return mod.ConnectionPool;
 }
@@ -55,10 +59,30 @@ export function laneSessionIdForTask(task) {
         return task.originChatId;
     }
     if (typeof task.agreementId === 'string' && task.agreementId) {
-        return `agrn-${task.agreementId}`;
+        return agreementLaneId(task.agreementId);
     }
     return 'default';
 }
+/** Pull the cost-record keys off a wake event or session id. */
+export function workScopeFromWake(event, sessionId) {
+    const rec = event && typeof event === 'object' ? event : {};
+    const resource = rec.resource && typeof rec.resource === 'object'
+        ? rec.resource
+        : {};
+    const agreementId = (typeof rec.agreementId === 'string' && rec.agreementId) ||
+        (typeof resource.agreementId === 'string' && resource.agreementId) ||
+        agreementIdFromLane(rec.chatId) ||
+        agreementIdFromLane(resource.chatId) ||
+        agreementIdFromLane(sessionId) ||
+        undefined;
+    const taskId = (typeof rec.taskId === 'string' && rec.taskId) ||
+        (typeof resource.taskId === 'string' && resource.taskId) ||
+        undefined;
+    return {
+        ...(agreementId ? { agreementId } : {}),
+        ...(taskId ? { taskId } : {}),
+    };
+}
 function createToolManager(options) {
     const toolManager = new ToolManager();
     const userTools = options.tools || options.services?.tools || [];
@@ -105,7 +129,7 @@ export function warnOnShadowedPlatformTools(platformTools, ownTools, agentId) {
         .filter((name) => platform.has(name));
     if (shadowed.length === 0)
         return;
-    console.warn(`[AgentHost] ${agentId}: tool name(s) ${shadowed.join(', ')} shadow the platform tools of the same name — ` +
+    console.warn(`[Agent] ${agentId}: tool name(s) ${shadowed.join(', ')} shadow the platform tools of the same name — ` +
         'the agent will call yours, not Ziggs\'s. Rename them unless that is deliberate.');
 }
 function isLlmAdapter(v) {
@@ -151,19 +175,18 @@ function createBackendServices(options) {
     };
 }
 /**
- * AgentHost — the Server. Owns a pure {@link Agent}, an {@link EffectHandler},
- * a transport (Ziggs WebSocket), and the lane router (per-session FIFO queue
- * + in-memory session state).
- *
- *   transport (WS)  →  handleMessage  →  agent.tick(.. , eff)  →  ..
+ * One agent identity and its body: inbox, tools, contracts, memory and lanes.
+ * The brain decides on each wake; platform services perform its effects.
+ * connectAsync starts outbound inbox reads and declared external polls.
+ * An Agent never opens a listening socket.
  */
-export class AgentHost {
+export class Agent {
     options;
     toolManager;
     // Retained for external inspection. Undefined for the Claude brain, which
     // drives query() directly and needs no LLM adapter.
     llm;
-    agent;
+    brain;
     eff;
     eventQueue;
     sessions = new Map();
@@ -173,12 +196,15 @@ export class AgentHost {
     sessionStore;
     taskService;
     agreementService;
+    telemetryClient;
     messageSender;
     seenMessages = new SeenMessages();
     stateTimers;
     /** The per-agent inbox long-poll loop — this agent's sole wake source. */
     inboxLoop = null;
     inboxLoopEnabled;
+    started = false;
+    pollRunner;
     /** Short-lived grant-provider cache for the declared-needs gate. */
     /**
      * Lanes where an unmet-need refusal has already been allowed its one turn to
@@ -190,7 +216,7 @@ export class AgentHost {
     unmetTasksPendingAsk = new Map();
     grantProviderCache = null;
     constructor(options = {}) {
-        const resolved = applyBrainToHostOptions(options);
+        const resolved = applyBrainToAgentOptions(options);
         this.options = {
             openaiKey: resolved.openaiKey || process.env.OPENAI_API_KEY,
             anthropicKey: resolved.anthropicKey || process.env.ANTHROPIC_API_KEY,
@@ -223,6 +249,8 @@ export class AgentHost {
             inboxCatchUp: resolved.inboxCatchUp,
             telemetryIngest: resolved.telemetryIngest,
             brain: resolved.brain,
+            polls: resolved.polls,
+            pollKinds: resolved.pollKinds,
             cognition: resolved.cognition ?? 'fsm',
             claudeMaxTurns: resolved.claudeMaxTurns,
             claudeStatelessPerWake: resolved.claudeStatelessPerWake,
@@ -235,12 +263,15 @@ export class AgentHost {
         // default.
         this.tickTimeoutMs =
             options.tickTimeoutMs ??
-                (isClaudeCognition(options.cognition)
+                (isClaudeCognition(resolved.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();
+        this.pollRunner = createDeclaredPollRunner(this.options, {
+            sendTo: (_agentId, text, metadata) => this.handleMessage(text, metadata ?? {}),
+        });
         this._setup();
     }
     _validate() {
@@ -290,6 +321,7 @@ export class AgentHost {
         }, creds);
         this.taskService = services.taskService;
         this.agreementService = services.agreementService;
+        this.telemetryClient = services.telemetryClient;
         this.messageSender = messageSender;
         let workflow = this.options.workflow;
         if (!workflow && this.options.states) {
@@ -302,7 +334,7 @@ export class AgentHost {
         }
         if (!workflow?.states) {
             // The Claude brain has no FSM — it drives query() per wake and parks. It
-            // still plugs into the host's lane/timer machinery via a trivial parked
+            // still plugs into the agent's lane/timer machinery via a trivial parked
             // workflow, synthesized here so callers don't hand-write a dummy one.
             if (isClaudeCognition(this.options.cognition)) {
                 workflow = {
@@ -313,7 +345,7 @@ export class AgentHost {
                 };
             }
             else {
-                throw new Error('AgentHost: workflow (or states + initial) is required');
+                throw new Error('Agent: workflow (or states + initial) is required');
             }
         }
         this.eff = createZiggsEffectHandler({
@@ -330,8 +362,8 @@ export class AgentHost {
             telemetryIngest: this.options.telemetryIngest,
             effectTap: this.options.effectTap,
         });
-        this.agent = isClaudeCognition(this.options.cognition)
-            ? new ClaudeSdkAgent({
+        this.brain = isClaudeCognition(this.options.cognition)
+            ? new ClaudeBrain({
                 workflow,
                 toolManager: services.toolManager,
                 description: this.options.description,
@@ -347,7 +379,7 @@ export class AgentHost {
                 maxTurns: this.options.claudeMaxTurns,
                 statelessPerWake: this.options.claudeStatelessPerWake,
             })
-            : new Agent({
+            : new ZiggsBrain({
                 workflow,
                 toolManager: services.toolManager,
                 promptBuilder: services.promptBuilder,
@@ -358,7 +390,7 @@ export class AgentHost {
         // than left as an unhandled rejection (made enqueue reject).
         this.stateTimers = new StateTimers((ev, laneKey) => {
             void this.eventQueue.enqueue(ev, laneKey).catch((err) => {
-                runtimeLog.warn('AgentHost', `state-timer frame failed laneKey=${laneKey}: ${err?.message || err}`);
+                runtimeLog.warn('Agent', `state-timer frame failed laneKey=${laneKey}: ${err?.message || err}`);
             });
         });
     }
@@ -400,7 +432,7 @@ export class AgentHost {
                     event.resourceId) ||
                 null;
             if (agreementId)
-                sessionId = `agrn-${agreementId}`;
+                sessionId = agreementLaneId(agreementId);
         }
         if (!sessionId)
             return;
@@ -427,14 +459,14 @@ export class AgentHost {
     async handleMessage(text, metadata = {}) {
         const messageId = metadata.messageId;
         if (messageId && this.seenMessages.has(messageId)) {
-            runtimeLog.debug('AgentHost', `skip duplicate messageId=${messageId}`);
+            runtimeLog.debug('Agent', `skip duplicate messageId=${messageId}`);
             return;
         }
         if (messageId)
             this.seenMessages.mark(messageId);
         const ownAgentId = this._resolveOwnAgentId();
         if (!ownAgentId) {
-            runtimeLog.warn('AgentHost', 'handleMessage: ownAgentId missing — dropping event');
+            runtimeLog.warn('Agent', 'handleMessage: ownAgentId missing — dropping event');
             return;
         }
         let enrichedText = typeof text === 'string' ? text : '';
@@ -454,14 +486,14 @@ export class AgentHost {
         const normalized = normalizeIncomingEvent({ text: enrichedText, metadata, ownAgentId });
         const sessionId = this.sessionResolver(normalized, ownAgentId);
         if (!sessionId) {
-            runtimeLog.warn('AgentHost', `session resolver returned null ownAgentId=${ownAgentId} chatId=${normalized.chatId ?? 'null'}`);
+            runtimeLog.warn('Agent', `session resolver returned null ownAgentId=${ownAgentId} chatId=${normalized.chatId ?? 'null'}`);
             return;
         }
         const laneKey = `${ownAgentId}:${sessionId}`;
         if (!this.sessions.has(laneKey)) {
             this.sessions.set(laneKey, { sessionId, ownAgentId });
         }
-        // The inbox loop owns ack (act-before-ack, delivery law); the host only
+        // The inbox loop owns ack (act-before-ack, delivery law); the agent only
         // routes the event onto its lane. No live-path watermark ack — there is no
         // separate live/push channel to reconcile against anymore.
         //
@@ -494,10 +526,55 @@ export class AgentHost {
      * Failing open is deliberate. If the lookup errors we run the turn — a missed
      * suppression costs tokens, while a wrongly suppressed turn drops work.
      */
+    recordWakeOutcome(session, outcome, llmCalls = 0) {
+        const agentId = session.ownAgentId || this.options.agentId;
+        const laneKey = `${agentId}:${session.sessionId}`;
+        runtimeLog.info(this.options.name || 'agent', `wake-outcome agent=${agentId} lane=${laneKey} kind=${outcome.kind}` +
+            (outcome.reason ? ` reason=${outcome.reason}` : ''));
+        sendTelemetry(this.telemetryClient, buildWakeOutcomePayload({
+            agentId,
+            sessionId: session.sessionId,
+            laneKey,
+            outcome,
+            llmCalls,
+        }), isTelemetryIngestEnabled(this.options.telemetryIngest));
+    }
+    memoryForWake(session) {
+        return partitionMemoryStore(this.memory, memorySectionForWake({
+            sessionId: session.sessionId,
+            activeAgreementId: session.ctx
+                ?.activeAgreementId,
+        }));
+    }
+    /**
+     * A chat-lane session that still carries a cancelled hire from a previous
+     * engagement will agreement_get that dead row and stop. Drop it so this
+     * wake keys on the live room / hire.
+     */
+    async dropStaleCancelledAgreementSession(session) {
+        const ctx = session.ctx;
+        const pinned = ctx?.activeAgreementId;
+        if (!pinned || !this.agreementService)
+            return;
+        if (session.sessionId === agreementLaneId(pinned))
+            return;
+        try {
+            const agreement = await this.agreementService.get(pinned);
+            const status = String(agreement?.status ?? '');
+            if (status === 'cancelled' ||
+                status === 'refunded' ||
+                status === 'fulfilled') {
+                runtimeLog.info(this.options.name || 'agent', `dropping session pinned to terminal agreement ${pinned} lane=${session.sessionId}`);
+                ctx.activeAgreementId = null;
+                ctx.claudeSessionId = undefined;
+            }
+        }
+        catch {
+            // Fail open: a lookup error must not drop a live hire's session.
+        }
+    }
     async laneAgreementIsTerminal(sessionId) {
-        if (!sessionId.startsWith('agrn-'))
-            return false;
-        const agreementId = sessionId.slice('agrn-'.length);
+        const agreementId = agreementIdFromLane(sessionId);
         if (!agreementId || !this.agreementService)
             return false;
         try {
@@ -693,10 +770,12 @@ export class AgentHost {
             return;
         if (await this.laneAgreementIsTerminal(session.sessionId)) {
             runtimeLog.info(this.options.name || 'agent', `skipping wake on ${session.sessionId} — its agreement is terminal`);
+            this.recordWakeOutcome(session, { kind: 'no-op', reason: 'agreement_terminal' });
             return;
         }
         if (this.isSettledTaskEcho(event)) {
             runtimeLog.info(this.options.name || 'agent', `skipping wake on ${session.sessionId} — its task already reported a result`);
+            this.recordWakeOutcome(session, { kind: 'no-op', reason: 'task_already_settled' });
             return;
         }
         // Before the tick spends anything: work this agent declared it cannot do
@@ -722,14 +801,16 @@ export class AgentHost {
                 }
             }
             catch (err) {
-                runtimeLog.warn('AgentHost', `sessionStore.load failed laneKey=${laneKey}: ${err?.message || err}`);
+                runtimeLog.warn('Agent', `sessionStore.load failed laneKey=${laneKey}: ${err?.message || err}`);
             }
         }
+        await this.dropStaleCancelledAgreementSession(session);
         const identity = {
             agentId: session.ownAgentId || this.options.agentId,
             sessionId: session.sessionId,
             laneKey,
         };
+        const memory = this.memoryForWake(session);
         // Recorded here rather than after the tick: this is the last point where the
         // input is still exactly what the brain will see, and a wake that goes on to
         // throw is the one most worth replaying.
@@ -745,7 +826,7 @@ export class AgentHost {
                 });
             }
             catch (err) {
-                runtimeLog.warn('AgentHost', `wakeTap failed: ${err?.message || err}`);
+                runtimeLog.warn('Agent', `wakeTap failed: ${err?.message || err}`);
             }
         }
         // The watchdog timer must be cleared once the tick settles — leaving it
@@ -757,9 +838,20 @@ export class AgentHost {
         // a zombie — burning tokens and racing the redelivered retry of the same
         // event (duplicate sends, runaway per-wake input).
         const tickAbort = new AbortController();
+        const marks = { sent: 0, tasks: 0 };
+        const eff = async (effect) => {
+            if (effect.kind === 'send-message')
+                marks.sent += 1;
+            if (effect.kind === 'tool-call') {
+                const name = 'name' in effect ? String(effect.name) : '';
+                if (name.startsWith('task_'))
+                    marks.tasks += 1;
+            }
+            return this.eff(effect);
+        };
         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, signal: tickAbort.signal }),
+                this.brain.tick({ event: frame, ctx: session.ctx, state: session.state, identity, eff, memory, transitionTap: this.options.transitionTap, signal: tickAbort.signal }),
                 new Promise((_, reject) => {
                     tickWatchdog = setTimeout(() => {
                         tickAbort.abort(new Error('tick timeout'));
@@ -770,6 +862,13 @@ export class AgentHost {
             session.ctx = result.ctx;
             session.state = result.state;
             this.sessions.set(laneKey, session);
+            this.recordWakeOutcome(session, classifyWakeOutcome({
+                lastOutcomeKind: result.ctx
+                    ?.lastOutcome?.kind,
+                llmCalls: result.metrics?.llmCalls ?? 0,
+                sentMessage: marks.sent > 0,
+                taskWrite: marks.tasks > 0,
+            }), result.metrics?.llmCalls ?? 0);
             // One line per wake that actually spent LLM budget — the handle for
             // tracking a hosted agent live (grep `agent=<id>`). Parked no-op ticks
             // (FSM exits, wake-rate-skipped Claude wakes) report zero tokens and
@@ -777,7 +876,7 @@ export class AgentHost {
             // these lines for one lane. Tokens are billable input (incl. cache).
             const m = result.metrics;
             if (m && (m.tokens?.total ?? 0) > 0) {
-                runtimeLog.info('AgentHost', `wake agent=${identity.agentId} lane=${laneKey} llmCalls=${m.llmCalls} ` +
+                runtimeLog.info('Agent', `wake agent=${identity.agentId} lane=${laneKey} llmCalls=${m.llmCalls} ` +
                     `tokens_in=${m.tokens.input} tokens_out=${m.tokens.output} total=${m.tokens.total}`);
             }
             // Single source of truth for usage/cost: emit the tick's
@@ -791,15 +890,16 @@ export class AgentHost {
                         model: this.options.model ?? 'unknown',
                         cognition: this.options.cognition ?? 'fsm',
                         metrics: result.metrics,
+                        ...workScopeFromWake(event, session.sessionId),
                     });
                 }
                 catch (err) {
-                    runtimeLog.warn('AgentHost', `metricsTap failed: ${err?.message || err}`);
+                    runtimeLog.warn('Agent', `metricsTap failed: ${err?.message || err}`);
                 }
             }
             if (this.sessionStore) {
                 this.sessionStore.save(laneKey, { ctx: session.ctx, state: session.state }).catch((err) => {
-                    runtimeLog.warn('AgentHost', `sessionStore.save failed laneKey=${laneKey}: ${err?.message || err}`);
+                    runtimeLog.warn('Agent', `sessionStore.save failed laneKey=${laneKey}: ${err?.message || err}`);
                 });
             }
             // Arm only when the timeout was handled: an unhandled state-timeout must
@@ -824,12 +924,16 @@ export class AgentHost {
             }
         }
         catch (err) {
-            runtimeLog.warn('AgentHost', `tick failed laneKey=${laneKey}: ${err?.message || err}`);
+            this.recordWakeOutcome(session, {
+                kind: 'no-op',
+                reason: 'tick_failed',
+            });
+            runtimeLog.warn('Agent', `tick failed laneKey=${laneKey}: ${err?.message || err}`);
             // Deliberate re-arm on failure. Exact scenario: the tick timed out at
             // tickTimeoutMs (or sessionStore.load threw) leaving session.state at a
             // timed parked state — without re-arming, that lane would never wake
             // again unless a real event happens to arrive.
-            this._armIfTimedParked(laneKey, session.state ?? this.agent.workflow.initial);
+            this._armIfTimedParked(laneKey, session.state ?? this.brain.workflow.initial);
             // Best-effort: also notify the user so the conversation isn't silently
             // stuck. Complements the timer re-arm above — that recovers a
             // parked lane; this tells a waiting human.
@@ -855,12 +959,12 @@ export class AgentHost {
         }
     }
     /**
-     * Re-run one recorded wake against THIS host's agent, and nothing else.
+     * Re-run one recorded wake against THIS agent, and nothing else.
      *
      * The dev loop for a prompt: record a wake off a live run, edit the agent, and
      * see what it does differently in seconds instead of standing a world back up
      * for one turn. The brain, tools and effect handler are the real ones, so the
-     * turn is real — its tool calls hit the backend this host is pointed at, which
+     * turn is real — its tool calls hit the backend this agent is pointed at, which
      * is why it belongs against a disposable world and not a shared one.
      *
      * Deliberately NOT routed through `_processEvent`: everything that method does
@@ -876,19 +980,23 @@ export class AgentHost {
             sessionId: record.sessionId,
             laneKey: record.laneKey || record.sessionId,
         };
+        const memory = this.memoryForWake({
+            sessionId: record.sessionId,
+            ctx: record.ctx,
+        });
         // Same watchdog as a live wake, for the same reason: an unaborted Claude
         // query outlives the promise that abandoned it and keeps spending.
         const abort = new AbortController();
         let watchdog;
         try {
             const result = await Promise.race([
-                this.agent.tick({
+                this.brain.tick({
                     event: record.event,
                     ctx: record.ctx,
                     state: record.state,
                     identity,
                     eff: this.eff,
-                    memory: this.memory,
+                    memory,
                     transitionTap: this.options.transitionTap,
                     signal: abort.signal,
                 }),
@@ -907,10 +1015,11 @@ export class AgentHost {
                         model: this.options.model ?? 'unknown',
                         cognition: this.options.cognition ?? 'fsm',
                         metrics: result.metrics,
+                        ...workScopeFromWake(record.event, identity.sessionId),
                     });
                 }
                 catch (err) {
-                    runtimeLog.warn('AgentHost', `metricsTap failed: ${err?.message || err}`);
+                    runtimeLog.warn('Agent', `metricsTap failed: ${err?.message || err}`);
                 }
             }
             return result;
@@ -923,25 +1032,33 @@ export class AgentHost {
     _armIfTimedParked(laneKey, stateName) {
         if (!stateName)
             return;
-        const sd = this.agent.workflow.states[stateName];
+        const sd = this.brain.workflow.states[stateName];
         if (sd?.kind !== 'parked' || sd.timeoutMs === undefined)
             return;
         this.stateTimers.arm(laneKey, stateName, sd.timeoutMs);
     }
     _resolveOwnAgentId() {
-        // The host is constructed for exactly one agent; its own id is the only
+        // The body is constructed for exactly one identity; its own id is the only
         // source. (The socket-frame-era metadata fallbacks — self/agent/ziggsAgentId
         // — are gone: nothing on the inbox wire ever carried them.)
         return this.options.agentId || null;
     }
     async connectAsync(_timeout) {
-        // Bootstrap active assigned tasks once (HTTP pull → lane), then start the
-        // per-agent inbox long-poll loop — the agent's sole wake source. There is
-        // no socket to connect and no reconnect: a crash is just the loop's next
-        // iteration (the cursor is server-side). `_timeout` is accepted for
-        // backward-compatible call sites but no longer gates a handshake.
+        if (this.started)
+            return this;
+        // Start the per-agent inbox long-poll loop — the agent's sole wake source.
+        // There is no socket to connect and no reconnect: a crash is just the
+        // loop's next iteration (the cursor is server-side). `_timeout` is accepted
+        // for backward-compatible call sites but no longer gates a handshake.
+        //
+        // There is no separate catch-up sweep here any more. `tasksAwaitingMe` is
+        // re-derived from the collection on every pass and redelivers an open
+        // assigned task until it closes, so the loop's first pass IS the catch-up —
+        // a restarted agent sees its standing work with nothing extra to run. The
+        // sweep that used to sit here pulled the same list over
+        // `GET /agents/:id/tasks` and reached one gate the inbox does not, which is
+        // how a withheld join node got handed to its assignee before its turn.
         if (this.inboxLoopEnabled) {
-            await this._bootstrapAssignedActiveTasks();
             const label = this.options.name || 'agent';
             this.inboxLoop = runInboxLoop({
                 creds: {
@@ -974,10 +1091,12 @@ export class AgentHost {
                 },
             });
         }
+        this.pollRunner?.start();
+        this.started = true;
         return this;
     }
     /**
-     * plain string compare against {@link AgentHostOptions.requestMatchTags}
+     * plain string compare against {@link AgentOptions.requestMatchTags}
      * and `specialization`. No match → return (caller acks). Match → normal wake.
      */
     async triageRequestDelivery(request) {
@@ -997,52 +1116,6 @@ export class AgentHost {
             agreementId: request.agreementId,
         });
     }
-    async _bootstrapAssignedActiveTasks() {
-        const agentId = this.options.agentId;
-        if (!agentId || !this.taskService)
-            return;
-        let tasks = [];
-        try {
-            tasks = await this.taskService.getActiveTasksForAgent(agentId);
-        }
-        catch (err) {
-            runtimeLog.warn(this.options.name || 'agent', `active-task bootstrap skipped: ${err?.message ?? err}`);
-            return;
-        }
-        for (const row of tasks) {
-            const taskId = row.taskId;
-            if (!taskId)
-                continue;
-            if (row.assigneeId && row.assigneeId !== agentId)
-                continue;
-            let full;
-            try {
-                full = (await this.taskService.getTask(taskId));
-            }
-            catch {
-                continue;
-            }
-            const state = String(full.state ?? '');
-            if (state !== 'active' && state !== 'in-progress')
-                continue;
-            const sessionId = laneSessionIdForTask(full);
-            const laneKey = `${agentId}:${sessionId}`;
-            if (!this.sessions.has(laneKey)) {
-                this.sessions.set(laneKey, { sessionId, ownAgentId: agentId });
-            }
-            runtimeLog.info(this.options.name || 'agent', `bootstrap task-assigned ${taskId} (state=${state})`);
-            await this.eventQueue.enqueue({
-                type: 'task_result',
-                result: {
-                    ...full,
-                    taskId: full.taskId ?? taskId,
-                    state,
-                    providerIsYou: true,
-                },
-                chatId: sessionId,
-            }, laneKey);
-        }
-    }
     /** replay task-assigned for an existing active task (demo recovery). */
     async wakeTaskAssignment(taskId) {
         const agentId = this.options.agentId;
@@ -1070,7 +1143,13 @@ export class AgentHost {
             chatId: sessionId,
         }, laneKey);
     }
-    disconnect() { this.stateTimers.clearAll(); void this.inboxLoop?.stop(); this.inboxLoop = null; }
+    disconnect() {
+        this.started = false;
+        this.pollRunner?.stop();
+        this.stateTimers.clearAll();
+        void this.inboxLoop?.stop();
+        this.inboxLoop = null;
+    }
     /**
      * Waits for in-flight ticks to finish. Call before process.exit() on SIGTERM.
      * A timeout is returned, not thrown — the caller names it (lab verdict, fleet
@@ -1078,20 +1157,43 @@ export class AgentHost {
      */
     drain(timeoutMs = 30_000) { return this.eventQueue.waitForIdle(timeoutMs); }
     registerTool(tool) { return this.toolManager.register(tool); }
-    isConnected() { return this.inboxLoop?.running ?? false; }
+    isConnected() { return this.started && (!this.inboxLoopEnabled || (this.inboxLoop?.running ?? false)); }
+    /**
+     * Whether this agent is still reading its inbox, and when it last did. One
+     * signal, three readers: the store's online badge, an operator's health
+     * check, and monitoring. `lastPassAt` is the read itself; `lastAttemptAt`
+     * says the loop still turns when the server is the thing that is down.
+     * A `pollingInbox: false` agent (inboxCatchUp disabled, lab and eval paths)
+     * has nothing to be stale about and reports no timestamps.
+     */
+    inboxLiveness() {
+        return {
+            agentId: this.options.agentId,
+            connected: this.isConnected(),
+            pollingInbox: this.inboxLoopEnabled,
+            lastPassAt: this.inboxLoop?.lastPassAt ?? null,
+            lastAttemptAt: this.inboxLoop?.lastAttemptAt ?? null,
+        };
+    }
 }
 /**
- * createAgent(config)            → AgentHost
+ * createAgent(config)            → Agent
  * createAgentPool([cfg, ...])    → ConnectionPool (lazy fleet, async-loaded)
  */
 export function createAgent(options = {}) {
-    return new AgentHost(options);
+    return new Agent(options);
 }
 export async function createAgentPool(configs) {
     const ConnectionPool = await loadConnectionPool();
     const pool = new ConnectionPool();
     pool.register(configs);
-    await pool.connectAll();
-    return pool;
+    try {
+        await pool.connectAll();
+        return pool;
+    }
+    catch (err) {
+        await pool.shutdown();
+        throw err;
+    }
 }
-export default AgentHost;
+export default Agent;