@noesis-brain/mcp-server 2.1.3 → 2.3.1

package/dist/agent/runner.js

@@ -15,10 +15,25 @@
  */
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
+import { checkWebFetchUrl, webFetchEnvWarnings } from './webGuard.js';
+import { resolveIdentity } from './identity.js';
+import { TokenGate, applyStartupCheck, checkToken, classifyRefusal } from './tokenState.js';
 const POLL_INTERVAL_MS = 2000; // idle poll cadence
 const CHUNK_FLUSH_MS = 500; // batch streamed deltas before POST /events
 const KEEPALIVE_MS = 30_000; // hold the lease during quiet stretches (< server's 120s stale)
 const MAX_CONCURRENCY = 2;
+function parseFakeMode(raw) {
+    const v = (raw || '').trim().toLowerCase();
+    if (v === '1' || v === 'canned')
+        return 'canned';
+    if (v === 'rate_limit' || v === 'auth')
+        return v;
+    return undefined;
+}
+function nonNegative(raw, fallback) {
+    const n = Number(raw);
+    return raw !== undefined && raw !== '' && Number.isFinite(n) && n >= 0 ? n : fallback;
+}
 export function resolveAgentConfig() {
     const apiBaseUrl = (process.env.NOESIS_API_URL || '').replace(/\/$/, '');
     const apiToken = process.env.NOESIS_API_TOKEN || '';
@@ -30,7 +45,16 @@ export function resolveAgentConfig() {
         concurrency = 1;
     if (concurrency > MAX_CONCURRENCY)
         concurrency = MAX_CONCURRENCY;
-    return { apiBaseUrl, apiToken, concurrency, fake: process.env.NOESIS_AGENT_FAKE === '1' };
+    const fakeMode = parseFakeMode(process.env.NOESIS_AGENT_FAKE);
+    return {
+        apiBaseUrl,
+        apiToken,
+        concurrency,
+        fake: fakeMode !== undefined,
+        fakeMode,
+        fakeResetAt: Date.now() + nonNegative(process.env.NOESIS_AGENT_FAKE_RESET_MIN, 3) * 60_000,
+        fakeWordMs: nonNegative(process.env.NOESIS_AGENT_FAKE_WORD_MS, 15),
+    };
 }
 /**
  * The ONLY tools the server may pre-approve — a literal allowlist, not a namespace
@@ -47,6 +71,16 @@ const ALLOWED_TOOLS = new Set([
     'mcp__noesis__get_note',
     'mcp__noesis__list_notes',
 ]);
+/**
+ * Claude Code built-ins a server may request: network-only, no filesystem access. This is
+ * the ONLY route by which the SDK's `tools` option is ever non-empty (see buildQueryOptions).
+ *
+ * A separate list from ALLOWED_TOOLS on purpose, and never pre-approved: every call goes
+ * through buildCanUseTool, where a WebFetch URL must pass webGuard, because this daemon
+ * runs on the user's own machine and "fetch http://192.168.1.1" would reach their LAN.
+ * The backend asks for these only for a Navi whose Web Search toggle is on.
+ */
+const ALLOWED_WEB_TOOLS = ['WebFetch', 'WebSearch'];
 /** Highest turn budget a server may request; a tool loop otherwise burns the subscription. */
 const MAX_TURNS_CEILING = 12;
 /** Drop anything the server asked for that is not on the read-only allowlist. */
@@ -59,6 +93,12 @@ export function clampAllowedTools(raw) {
         console.error(`[noesis-agent] dropped ${dropped} tool name(s) not on the read-only allowlist`);
     return kept;
 }
+/** The web built-ins this job asked for, in a fixed order. Nothing else can come out. */
+export function clampWebTools(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return ALLOWED_WEB_TOOLS.filter((t) => raw.includes(t));
+}
 /** Clamp the server-requested turn budget into a sane range. */
 export function clampMaxTurns(raw) {
     const n = typeof raw === 'number' && Number.isFinite(raw) ? Math.floor(raw) : 1;
@@ -102,13 +142,58 @@ export function agentVersion() {
         return '0.0.0';
     }
 }
-async function claim(cfg, workerId) {
-    const res = await api(cfg, '/api/agent/jobs/claim', { workerId, agentVersion: agentVersion() });
+let identity = null;
+/** This process's machine identity, resolved once (daemonId is stable; bootId is per process). */
+function daemonIdentity() {
+    identity ??= resolveIdentity();
+    return identity;
+}
+/**
+ * What every claim sends. The server keeps one health record per machine (daemonId), tells
+ * a restart from a second process by bootId, and shows label/platform in Settings. Older
+ * servers read only workerId + agentVersion and ignore the rest.
+ */
+export function claimBody(workerId, id) {
+    return { workerId, agentVersion: agentVersion(), daemonId: id.daemonId, bootId: id.bootId, label: id.label, platform: id.platform };
+}
+/** The token state every worker shares (see tokenState.ts). */
+const tokenGate = new TokenGate();
+/**
+ * Read a claim answer. A 401 means the server refused this daemon's API token (expired,
+ * revoked or unknown): the shared gate explains it once and the workers back off, instead
+ * of retrying silently every 2 s. Any accepted answer clears that state and feeds the
+ * token-expiry warning.
+ */
+export async function handleClaimResponse(res, gate) {
+    if (res.status === 401) {
+        gate.refused(classifyRefusal(await res.json().catch(() => ({}))));
+        return null;
+    }
     if (!res.ok)
         return null;
+    gate.accepted();
+    gate.expiryHeader(res.headers.get('x-noesis-token-expires'));
     const data = (await res.json());
     return data.job ?? null;
 }
+async function claim(cfg, workerId) {
+    const res = await api(cfg, '/api/agent/jobs/claim', claimBody(workerId, daemonIdentity()));
+    return handleClaimResponse(res, tokenGate);
+}
+/** Sleep, but wake at once on shutdown — the refused-token backoff is a minute long. */
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted)
+            return resolve();
+        const timer = setTimeout(done, ms);
+        function done() {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', done);
+            resolve();
+        }
+        signal?.addEventListener('abort', done, { once: true });
+    });
+}
 /** Buffers streamed text and flushes it as lease-fenced chunk events + keepalives. */
 class EventSink {
     cfg;
@@ -208,23 +293,164 @@ export function buildSdkPrompt(prompt, images) {
         return singleUserMessage(buildImageContent(prompt, images));
     return prompt;
 }
+/**
+ * SECOND, INDEPENDENT LAYER on the tool boundary.
+ *
+ * The `tools` option below (`[]`, or at most the two web tools) is the primary control, but
+ * it works by way of the CLI's `--tools` flag, whose handling lives in a minified `cli.js`
+ * we cannot audit. This callback is a
+ * gate we own outright: the SDK routes every permission request through it
+ * (`--permission-prompt-tool stdio`), and the request carries an `agentID`, so calls made
+ * by a spawned `Task` SUBAGENT are covered too — which matters, because a subagent, not
+ * the main loop, did the file reading in the 2026-08-14 incident.
+ *
+ * Deliberately fed from ALLOWED_TOOLS / ALLOWED_WEB_TOOLS (via the per-job clamps) so the
+ * daemon has ONE definition of what may run.
+ *
+ * DO NOT DELETE THIS AS DEAD CODE. It is the ONLY daemon-owned control over MCP tools.
+ * `tools: []` governs the SDK's BUILT-IN set and nothing else; the Noesis MCP server we
+ * spawn registers ~55 tools, and their definitions are not filtered by `allowedTools`, so
+ * the model can see and attempt every one of them — including `pull_notes`, which writes
+ * to an arbitrary local path, plus `add_root`, `sync_notes`, `trash_note`, `move_note`.
+ * For those, this callback is the whole boundary.
+ *
+ * MEASURED (30 runs, 2026-08-15), correcting an earlier comment that said the opposite:
+ * the gate DOES fire — it denied `mcp__noesis__list_roots` and `mcp__noesis__list_codebases`
+ * in real traffic, and the model received `is_error` results naming the refusal. An earlier
+ * 2-job sample saw zero firings and wrongly concluded the gate was inert; a permission tool
+ * is simply not consulted for calls that are already pre-approved, and that sample happened
+ * to exercise only pre-approved tools.
+ *
+ * KNOWN GAP, stated rather than glossed: the SDK's cache-warming sidechain
+ * (`isSidechain: true`) is a real model turn that emits genuine `Bash`/`Glob` calls against
+ * the daemon's cwd, with only the RESULT stubbed. `tools: []` does not reach it and this
+ * callback is never consulted there. Nothing executes — but that is Claude Code internal
+ * behaviour we neither own nor test, which is why the daemon is rooted at a neutral cwd
+ * (`scripts/start-agent.sh`), so the warmup probes an empty directory, not a source tree.
+ *
+ * WEB TOOLS: a permitted WebFetch is still refused unless its URL passes webGuard (public
+ * http(s) host only). The job's permitted set is checked FIRST, so a job never cleared
+ * for web cannot fetch even a public page. WebSearch needs no address check: the search
+ * runs on Anthropic's side, not from this machine. One exception the gate cannot see: the
+ * CLI itself pre-approves ~85 public documentation hosts for WebFetch and never asks. Those
+ * are public by definition, and executeJob logs every tool call from the stream anyway.
+ */
+export function buildCanUseTool(
+/**
+ * The tools permitted for THIS job — i.e. the output of `clampAllowedTools`, not the
+ * module-wide `ALLOWED_TOOLS`. Required, deliberately: an earlier version closed over
+ * `ALLOWED_TOOLS` and so turned a per-job clamp into a union. `clampAllowedTools`
+ * narrows to (what the server asked for ∩ ALLOWED_TOOLS); the gate then re-allowed all
+ * four regardless, so a job clamped to `get_note` could still execute `search_semantic`.
+ * The sets happen to coincide for chat today, which is exactly why it would have gone
+ * unnoticed until the first job kind with a narrower allowlist.
+ */
+permitted, onDecision = logToolDecision, checkUrl = checkWebFetchUrl) {
+    const permittedSet = new Set(permitted);
+    return async (toolName, input, ctx) => {
+        if (!permittedSet.has(toolName)) {
+            onDecision(toolName, false, ctx?.agentID);
+            return { behavior: 'deny', message: `Tool "${toolName}" is not permitted for a Noesis job.` };
+        }
+        const args = (input ?? {});
+        if (toolName === 'WebFetch') {
+            const verdict = await checkUrl(args.url);
+            if (!verdict.ok) {
+                onDecision(toolName, false, ctx?.agentID, `${String(args.url)} (${verdict.reason})`);
+                return {
+                    behavior: 'deny',
+                    message: `WebFetch refused: ${verdict.reason}. Only public internet addresses can be fetched.`,
+                };
+            }
+        }
+        onDecision(toolName, true, ctx?.agentID, toolCallDetail(toolName, args));
+        return { behavior: 'allow', updatedInput: args };
+    };
+}
+/** The URL or query a web tool call is about, for the log; undefined for other tools. */
+function toolCallDetail(toolName, args) {
+    const value = toolName === 'WebFetch' ? args.url : toolName === 'WebSearch' ? args.query : undefined;
+    return typeof value === 'string' ? value.slice(0, 300) : undefined;
+}
+/** Default sink: stderr, so the daemon log is the evidence for whether the gate ever fires. */
+function logToolDecision(toolName, allowed, agentID, detail) {
+    console.error(`[noesis-agent] canUseTool ${allowed ? 'ALLOW' : 'DENY'} ${toolName}${detail ? ` ${detail}` : ''}${agentID ? ` (agent=${agentID})` : ''}`);
+}
+/**
+ * The `options` object handed to sdk.query() — extracted, like buildSdkPrompt above, so
+ * the tool boundary is asserted by a test instead of resting on a comment. `tools` is the
+ * security-relevant field: see the note at its assignment. Takes the MCP-server
+ * factory as an argument so a test can supply a stub instead of a real spawn config.
+ */
+export function buildQueryOptions(payload, mcpServersFor) {
+    const requested = Array.isArray(payload.allowedTools) ? payload.allowedTools : [];
+    const webTools = clampWebTools(requested);
+    // Web names have their own clamp; keeping them out of this one stops it logging them as
+    // "dropped" on every web job. What it keeps is unchanged: the four read-only lookups.
+    const allowedTools = clampAllowedTools(requested.filter((t) => !webTools.includes(t)));
+    return {
+        ...(payload.system ? { systemPrompt: payload.system } : {}),
+        // Suppress the SDK's built-in tool set (`--tools <list>`) down to at most the two web
+        // tools. Without the option the CLI defaults to ALL built-ins — Bash, Read, Write,
+        // Edit, Grep, WebSearch — and ALLOWED_TOOLS above does NOT stop them: `allowedTools`
+        // is a PERMISSION allowlist, so unlisted tools are un-pre-approved, not absent, and
+        // their definitions still reach the model. Worse, the read-only built-ins need no
+        // approval at all, so they actually EXECUTE headless: on 2026-08-14 an English-coach
+        // Navi grepped this daemon's cwd and returned ~100 strings from the user's source tree
+        // (jobs 527/528); only the follow-up file Write stopped, at the permission gate.
+        // So this is `[]` for every job that did not ask for web, and never more than
+        // ALLOWED_WEB_TOOLS — network-only, no filesystem access. A server-supplied payload
+        // still can never ask for a filesystem primitive. MCP tools travel a separate channel
+        // (`--mcp-config`) and are unaffected: a `use_knowledge_base` Navi still calls
+        // search_notes (verified).
+        tools: webTools,
+        // Independent second layer — see buildCanUseTool. Covers subagent (`Task`) calls too.
+        // Web tools are deliberately left out of `allowedTools` below (never pre-approved),
+        // so every WebFetch reaches this gate and its URL check.
+        canUseTool: buildCanUseTool([...allowedTools, ...webTools]),
+        allowedTools,
+        // Only spawn the Noesis MCP server when a tool actually survived clamping.
+        ...(allowedTools.length > 0 ? { mcpServers: mcpServersFor() } : {}),
+        maxTurns: clampMaxTurns(payload.maxTurns),
+        includePartialMessages: true,
+    };
+}
+/** The prompt text for a job, with the fallback used when a payload carries none. */
+export function resolveJobPrompt(payload, kindLabel) {
+    return payload.prompt ?? `(${kindLabel} job with empty prompt)`;
+}
+/**
+ * The ONE place the SDK is invoked. Exported so a test can pass a fake `sdk` and assert
+ * what actually reaches `query()`.
+ *
+ * This exists because of a real gap: the suite pinned `buildQueryOptions` with a
+ * power-set mutation battery, but NOTHING pinned the call. Restoring the pre-fix inline
+ * options literal here — deleting `tools: []` and `canUseTool` outright — reverted the
+ * entire tool boundary with all 79 tests still green. The builder being correct is
+ * worthless if the caller stops using it, so both the seam below and the source-fitness
+ * test in `agentToolClamp.test.ts` guard this.
+ */
+export function runSdkQuery(sdk, payload, kindLabel, mcpServersFor) {
+    return sdk.query({
+        prompt: buildSdkPrompt(resolveJobPrompt(payload, kindLabel), payload.images),
+        options: buildQueryOptions(payload, mcpServersFor),
+    });
+}
 /**
  * Execute a claimed job and stream its output through the sink. Returns the final
  * text. Real mode runs the Claude Agent SDK on the user's subscription; fake mode
  * emits a canned response so the queue plumbing can be verified without a login.
  */
 async function executeJob(cfg, job, sink) {
-    const prompt = job.payload.prompt ?? `(${job.kind} job with empty prompt)`;
-    const images = job.payload.images;
+    const prompt = resolveJobPrompt(job.payload, job.kind);
     if (cfg.fake) {
-        const canned = `Noesis local agent (fake mode) processed a "${job.kind}" job. Prompt was: ${prompt.slice(0, 80)}`;
-        for (const word of canned.split(' ')) {
-            if (sink.isClosed())
-                break;
-            sink.push(word + ' ');
-            await new Promise((r) => setTimeout(r, 15));
-        }
-        return canned;
+        const fake = fakeSdk(cfg.fakeMode ?? 'canned', {
+            kind: job.kind,
+            promptText: prompt,
+            resetAt: cfg.fakeResetAt ?? 0,
+            wordMs: cfg.fakeWordMs ?? 15,
+        });
+        return consumeAgentStream(runSdkQuery(fake, job.payload, job.kind, () => ({})), sink);
     }
     // Real path: the Agent SDK uses the ambient Claude Code subscription login.
     // Dynamically imported via a NON-LITERAL specifier so tsc doesn't require the
@@ -235,47 +461,170 @@ async function executeJob(cfg, job, sink) {
     const sdk = await import(sdkModule).catch(() => {
         throw new Error('Install @anthropic-ai/claude-agent-sdk to run the Noesis local agent (real mode).');
     });
+    const stream = runSdkQuery(sdk, job.payload, job.kind, () => noesisMcpServers(cfg));
+    return consumeAgentStream(stream, sink);
+}
+/**
+ * Appended when the SDK stops a run at maxTurns. Without it the saved reply would be only
+ * the narration that came before the tool calls ("let me check the official page…"), with
+ * nothing saying the answer was cut off.
+ */
+export const TURN_LIMIT_NOTE = '\n\n_(Stopped at the step limit before finishing. Ask me to continue.)_';
+/**
+ * Turn one SDK message stream into the reply text, pushing it to `out` as it arrives.
+ * Extracted from executeJob so these rules are testable against a fake stream:
+ *  - With includePartialMessages the stream carries BOTH incremental `stream_event` deltas
+ *    AND a terminal `assistant` message holding the whole reply. Taking both would emit the
+ *    answer twice, so deltas win and the terminal message is only a fallback for a stream
+ *    that produced none (older SDK, or partials unsupported).
+ *  - A multi-turn run (every web fetch or note lookup) gets a paragraph break between turns,
+ *    so narration does not run into the answer. Only when the next turn actually has text,
+ *    so a tool-only turn adds nothing.
+ *  - Every tool call is logged, including WebFetch calls to the hosts the CLI pre-approves
+ *    itself, which never reach canUseTool.
+ *  - Hitting maxTurns appends TURN_LIMIT_NOTE.
+ */
+export async function consumeAgentStream(stream, out, logToolCall = logStreamToolCall) {
     let finalText = '';
     let sawDelta = false;
     let terminalText = '';
-    const allowedTools = clampAllowedTools(job.payload.allowedTools);
-    const stream = sdk.query({
-        prompt: buildSdkPrompt(prompt, images),
-        options: {
-            ...(job.payload.system ? { systemPrompt: job.payload.system } : {}),
-            allowedTools,
-            // Only spawn the Noesis MCP server when a tool actually survived clamping.
-            ...(allowedTools.length > 0 ? { mcpServers: noesisMcpServers(cfg) } : {}),
-            maxTurns: clampMaxTurns(job.payload.maxTurns),
-            includePartialMessages: true,
-        },
-    });
-    // With includePartialMessages the stream carries BOTH incremental `stream_event`
-    // deltas AND a terminal `assistant` message holding the whole reply. Taking both
-    // would emit the answer twice, so deltas win and the terminal message is only a
-    // fallback for a stream that produced none (older SDK, or partials unsupported).
-    for await (const message of stream) {
-        if (sink.isClosed())
-            break;
-        const delta = extractStreamDelta(message);
-        if (delta) {
-            sawDelta = true;
-            sink.push(delta);
-            finalText += delta;
-            continue;
+    let breakPending = false;
+    let hitTurnLimit = false;
+    // An API failure (usage limit, revoked login, …) arrives as an assistant message
+    // carrying `error`, then a result with is_error, then the CLI exits 1 and the SDK
+    // throws a bare "Claude Code process exited with code 1". Keep the failure's own text
+    // and code — the server routes on them — and never let it become the reply.
+    let apiError = null;
+    let failedResultText = null;
+    let succeeded = false;
+    const emit = (text) => {
+        out.push(text);
+        finalText += text;
+    };
+    const failure = () => {
+        if (apiError)
+            return new AgentRunError(apiError.text, apiError.code, apiError.resetsAt);
+        if (failedResultText !== null)
+            return new AgentRunError(failedResultText || 'Claude run failed', 'unknown');
+        return null;
+    };
+    try {
+        for await (const message of stream) {
+            if (out.isClosed())
+                break;
+            const err = extractApiError(message);
+            if (err) {
+                apiError = err;
+                continue;
+            }
+            const outcome = resultOutcome(message);
+            if (outcome?.isError)
+                failedResultText = outcome.text;
+            else if (outcome)
+                succeeded = true;
+            if (isMessageStart(message)) {
+                if (finalText)
+                    breakPending = true;
+                continue;
+            }
+            const delta = extractStreamDelta(message);
+            if (delta) {
+                sawDelta = true;
+                if (breakPending) {
+                    breakPending = false;
+                    const gap = paragraphGap(finalText);
+                    if (gap)
+                        emit(gap);
+                }
+                emit(delta);
+                continue;
+            }
+            for (const call of extractToolUses(message))
+                logToolCall(call.name, call.detail);
+            if (isTurnLimitResult(message))
+                hitTurnLimit = true;
+            // Concatenate, don't overwrite: with tools the run is multi-turn, and a
+            // stream that produced no deltas would otherwise keep only the LAST turn.
+            const whole = extractTerminalText(message);
+            if (whole)
+                terminalText += (terminalText ? paragraphGap(terminalText) : '') + whole;
         }
-        // Concatenate, don't overwrite: with tools the run is multi-turn, and a
-        // stream that produced no deltas would otherwise keep only the LAST turn.
-        const whole = extractTerminalText(message);
-        if (whole)
-            terminalText += whole;
+    }
+    catch (e) {
+        throw failure() ?? e;
+    }
+    if (!succeeded) {
+        const f = failure();
+        if (f)
+            throw f;
     }
     if (!sawDelta && terminalText) {
-        sink.push(terminalText);
+        out.push(terminalText);
         finalText = terminalText;
     }
+    if (hitTurnLimit && !out.isClosed())
+        emit(finalText ? TURN_LIMIT_NOTE : TURN_LIMIT_NOTE.trimStart());
     return finalText;
 }
+/** A Claude API failure the daemon reports with its own text and SDK error code. */
+export class AgentRunError extends Error {
+    code;
+    resetsAt;
+    constructor(message, code, resetsAt) {
+        super(message);
+        this.code = code;
+        this.resetsAt = resetsAt;
+        this.name = 'AgentRunError';
+    }
+}
+/** An assistant message the SDK marked as an API failure (`error` set), or null. */
+function extractApiError(message) {
+    const m = message;
+    if (m?.type !== 'assistant' || typeof m.error !== 'string' || !m.error)
+        return null;
+    const text = extractTerminalText(m) || `Claude API error (${m.error})`;
+    const resetsAt = [m.resetsAt, m.message?.resetsAt, m.quotaLimits?.resetsAt, m.rateLimit?.resetsAt].find((v) => typeof v === 'number' && Number.isFinite(v) && v > 0);
+    return { code: m.error, text, ...(resetsAt ? { resetsAt } : {}) };
+}
+/** A terminal `result` message: did the run fail, and with what text? Null for anything else. */
+function resultOutcome(message) {
+    const m = message;
+    if (m?.type !== 'result')
+        return null;
+    if (m.is_error !== true)
+        return { isError: false, text: '' };
+    const text = typeof m.result === 'string' ? m.result : Array.isArray(m.errors) ? m.errors.join('; ') : '';
+    return { isError: true, text };
+}
+/** What to insert after `text` so the next turn starts a new paragraph. */
+function paragraphGap(text) {
+    if (text.endsWith('\n\n'))
+        return '';
+    return text.endsWith('\n') ? '\n' : '\n\n';
+}
+/** The start of a new model turn: one `message_start` per assistant message. */
+function isMessageStart(message) {
+    const m = message;
+    return m?.type === 'stream_event' && m.event?.type === 'message_start';
+}
+/** The SDK's terminal `result` when the run was stopped by maxTurns. */
+function isTurnLimitResult(message) {
+    const m = message;
+    return m?.type === 'result' && m.subtype === 'error_max_turns';
+}
+/** Tool calls in a complete `assistant` message, with the URL or query each is about. */
+function extractToolUses(message) {
+    const m = message;
+    if (m?.type !== 'assistant' || !Array.isArray(m.message?.content))
+        return [];
+    return m.message.content
+        .filter((b) => b?.type === 'tool_use' && typeof b.name === 'string')
+        .map((b) => ({ name: b.name, detail: toolCallDetail(b.name, b.input ?? {}) }));
+}
+/** Default sink: stderr, next to the canUseTool lines. */
+function logStreamToolCall(name, detail) {
+    console.error(`[noesis-agent] tool_use ${name}${detail ? ` ${detail}` : ''}`);
+}
 /**
  * Text carried by one streamed partial. Verified against the SDK (0.1.x): partials
  * arrive as `{type:'stream_event', event:{type:'content_block_delta',
@@ -310,6 +659,62 @@ function extractTerminalText(message) {
     }
     return '';
 }
+/** The /complete body for a failed job: the message, plus the SDK's code when known. */
+export function completionErrorBody(lease, err) {
+    const body = { lease, error: err instanceof Error ? err.message : String(err) };
+    if (err instanceof AgentRunError) {
+        body.errorCode = err.code;
+        if (err.resetsAt)
+            body.resetsAt = err.resetsAt;
+    }
+    return body;
+}
+/**
+ * A stand-in for the Agent SDK that emits the message sequences a real run does, so the
+ * fake modes exercise consumeAgentStream exactly like real traffic.
+ */
+export function fakeSdk(mode, opts) {
+    return { query: () => fakeStream(mode, opts) };
+}
+async function* fakeStream(mode, opts) {
+    const now = (opts.now ?? Date.now)();
+    if (mode !== 'canned' && now < opts.resetAt) {
+        const text = mode === 'rate_limit'
+            ? `You've hit your session limit · resets ${formatResetLikeCli(opts.resetAt, opts.timeZone, now)}`
+            : 'OAuth token revoked · Please run /login';
+        yield { type: 'system', subtype: 'init' };
+        yield { type: 'assistant', message: { content: [{ type: 'text', text }] }, error: mode === 'rate_limit' ? 'rate_limit' : 'authentication_failed' };
+        yield { type: 'result', subtype: 'success', is_error: true, result: text };
+        if (opts.throwAtEnd !== false)
+            throw new Error('Claude Code process exited with code 1');
+        return;
+    }
+    const canned = `Noesis local agent (fake mode) processed a "${opts.kind}" job. Prompt was: ${opts.promptText.slice(0, 80)}`;
+    yield { type: 'stream_event', event: { type: 'message_start', message: {} } };
+    const words = canned.split(' ');
+    for (let i = 0; i < words.length; i++) {
+        yield { type: 'stream_event', event: { type: 'content_block_delta', delta: { type: 'text_delta', text: (i ? ' ' : '') + words[i] } } };
+        if (opts.wordMs > 0)
+            await new Promise((r) => setTimeout(r, opts.wordMs));
+    }
+    yield { type: 'assistant', message: { content: [{ type: 'text', text: canned }] } };
+    yield { type: 'result', subtype: 'success', is_error: false, result: canned };
+}
+/**
+ * A reset time the way the Claude CLI prints it in its limit message: "3pm (Zone)",
+ * "3:07pm (Zone)", or "Oct 12, 3pm (Zone)" when more than a day away — minutes, no seconds.
+ */
+export function formatResetLikeCli(atMs, timeZone, nowMs = Date.now()) {
+    const zone = timeZone || Intl.DateTimeFormat().resolvedOptions().timeZone;
+    const parts = new Intl.DateTimeFormat('en-US', {
+        timeZone: zone, month: 'short', day: 'numeric', hour: 'numeric', minute: '2-digit', hour12: true,
+    }).formatToParts(new Date(atMs));
+    const get = (t) => parts.find((p) => p.type === t)?.value ?? '';
+    const minute = get('minute');
+    const time = `${get('hour')}${minute && minute !== '00' ? `:${minute}` : ''}${get('dayPeriod').toLowerCase()}`;
+    const date = atMs - nowMs > 24 * 60 * 60 * 1000 ? `${get('month')} ${get('day')}, ` : '';
+    return `${date}${time} (${zone})`;
+}
 async function runJob(cfg, job) {
     const sink = new EventSink(cfg, job.jobId, job.lease);
     sink.start();
@@ -324,12 +729,17 @@ async function runJob(cfg, job) {
         await sink.finish();
         if (sink.isClosed())
             return;
-        await api(cfg, `/api/agent/jobs/${job.jobId}/complete`, {
-            lease: job.lease,
-            error: err instanceof Error ? err.message : String(err),
-        });
+        await api(cfg, `/api/agent/jobs/${job.jobId}/complete`, completionErrorBody(job.lease, err));
     }
 }
+/**
+ * The daemon's startup banner line — pulled out of runAgentDaemon() so the printed
+ * version string is directly unit-testable without starting the real (infinite) loop.
+ */
+export function startupBanner(cfg) {
+    const fake = cfg.fake ? `, FAKE mode${cfg.fakeMode && cfg.fakeMode !== 'canned' ? ` (${cfg.fakeMode})` : ''}` : '';
+    return `[noesis-agent] v${agentVersion()} started (concurrency=${cfg.concurrency}${fake}) → ${cfg.apiBaseUrl}`;
+}
 /** Run the daemon loop until aborted. */
 export async function runAgentDaemon(cfg, signal) {
     // Footgun guard: keep billing on the subscription, not the metered API.
@@ -337,7 +747,12 @@ export async function runAgentDaemon(cfg, signal) {
         console.error('[noesis-agent] WARNING: ANTHROPIC_API_KEY is set — unsetting it so the Claude Agent SDK uses your subscription, not the metered API.');
         delete process.env.ANTHROPIC_API_KEY;
     }
-    console.error(`[noesis-agent] started (concurrency=${cfg.concurrency}${cfg.fake ? ', FAKE mode' : ''}) → ${cfg.apiBaseUrl}`);
+    for (const warning of webFetchEnvWarnings(process.env))
+        console.error(warning);
+    console.error(startupBanner(cfg));
+    // Confirm the API token before polling: an expired token is explained and waited out
+    // (it recovers after an Extend); a revoked or unknown one ends the process here.
+    applyStartupCheck(await checkToken(cfg.apiBaseUrl, cfg.apiToken), tokenGate);
     const workers = Array.from({ length: cfg.concurrency }, (_, i) => workerLoop(cfg, `worker-${i + 1}`, signal));
     await Promise.all(workers);
 }
@@ -355,7 +770,7 @@ async function workerLoop(cfg, workerId, signal) {
             await runJob(cfg, job);
         }
         else {
-            await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+            await sleep(tokenGate.waitMs(POLL_INTERVAL_MS), signal);
         }
     }
 }