From 134cd01b16cd5077366de9286415fa7db54391ba Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 12 Oct 2026 11:17:56 +0000
Subject: [PATCH 01/11] fix(cli): kits load under plain node, dev reloads local
 helpers, import hints

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BG6n8mwoFq1jmay9zCPS6n
---
 docs/cli.md                               |  13 +--
 registry/dist/items/inbox-triage.json     |  12 +--
 registry/inbox-triage/approve.ts          |   2 +-
 registry/inbox-triage/channels/inbound.ts |   2 +-
 registry/inbox-triage/hooks.ts            |   2 +-
 registry/inbox-triage/memory/senders.ts   |   2 +-
 registry/inbox-triage/tools/inbox.ts      |   2 +-
 registry/inbox-triage/tools/replies.ts    |   2 +-
 src/agentDir/importModule.test.ts         |  55 ++++++++++++
 src/agentDir/importModule.ts              | 105 ++++++++++++++++++++--
 src/agentDir/loadAgentDir.test.ts         |  31 +++++++
 src/cli/defaultRegistry.test.ts           |  28 ++++++
 12 files changed, 233 insertions(+), 23 deletions(-)
 create mode 100644 src/agentDir/importModule.test.ts

diff --git a/docs/cli.md b/docs/cli.md
index e0f80afb8..0eb458d1a 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -30,7 +30,7 @@ lousho dev <spec.yaml|spec.json|agent-dir|agent.ts> [--port N] [--host H] [--all
 lousho chat <spec.yaml|spec.json|agent-dir|agent.ts> [--model provider/model] [--session id] [--store sqlite:<file>] [--traces[=dir]]
 lousho acp <spec.yaml|spec.json|agent-dir|agent.ts> [--model provider/model]
 lousho add <name> [--registry <url-or-path>] [--dir <agent-dir>] [--yes] [--allow <list>] [--overwrite] [--dry-run]    (or --list)
-lousho build <agent-dir|spec> --target=<node-server|cloudflare-worker|docker> [--out=<dir>]    (or --agent=<path>)
+lousho build <agent-dir|spec|agent.ts> --target=<node-server|cloudflare-worker|docker> [--out=<dir>]    (or --agent=<path>)
 lousho studio [--port N] [--host H] [--prod|--dev]
 lousho mcp <agent.yaml|json|agent-dir|agent.ts> [--http --port N --host H]
 lousho doctor [agent.yaml|json|agent-dir] [--json] [--ping]
@@ -41,8 +41,8 @@ lousho --version
 
 Every command parses its flags the same way (Node's `parseArgs`, strict):
 `--flag value` and `--flag=value` both work, the last of a repeated flag wins
-(`--tag` accumulates), `--` ends the flags, and `-h` / `--help` prints the
-command's usage and exits 0. An unknown flag, a flag without its value (it
+(`--tag` accumulates), `--` ends the flags, and `-h` / `--help` (or `lousho help
+<command>`) prints the command's usage and flags and exits 0. An unknown flag, a flag without its value (it
 never takes the next flag as its value) or an extra argument fails with
 `LOUSHO_CONFIG_INVALID` and the usage line. A value that starts with `-` needs
 the `=` form: `--model=-x`. `--traces` is the one flag whose value is optional:
@@ -147,8 +147,10 @@ without restarting the server or dropping the port:
   `require` specifiers, found once at startup; no bundler).
 
 Directory and module files are imported with a `?t=<time>` cache-busting query,
-so an edited tool or agent file is re-evaluated. A file *imported by* that file
-(a shared helper) stays cached by Node: restart `lousho dev` after editing one.
+so an edited tool or agent file is re-evaluated, and so are the local files it
+imports by relative specifier (a shared `./lib/helper.ts`): the query is passed
+on to them. Packages under `node_modules` stay cached; restart `lousho dev`
+after changing one.
 The console logs what reloaded. The new agent is built (and `ready()`, so MCP
 servers connect) before it replaces the old one, and the old one is then
 `close()`d. If the rebuild fails, the last good agent keeps answering, the error
@@ -242,6 +244,7 @@ scripted lines and a `mockModel` agent and no terminal.
 ```bash
 npx lousho build --target=node-server --agent=agent.yaml        # or docker / cloudflare-worker
 npx lousho build ./my-agent --target=node-server                # an agent directory (node-server, docker)
+npx lousho build src/agent.ts --target=node-server              # an agent module (node-server, docker)
 ```
 
 Writes the artifact to `--out` (default `.lousho/build/<target>`) and prints
diff --git a/registry/dist/items/inbox-triage.json b/registry/dist/items/inbox-triage.json
index ab076f492..d0c5f629e 100644
--- a/registry/dist/items/inbox-triage.json
+++ b/registry/dist/items/inbox-triage.json
@@ -9,11 +9,11 @@
     },
     {
       "path": "approve.ts",
-      "content": "import type { ApproveToolCall } from '@lousho/build-ai-agent';\nimport { autoApproveSenders, findDraft, getMessage } from './lib/mailstore';\n\n/**\n * An OPTIONAL standing-policy approver, deliberately NOT wired into\n * agent.json: the kit's contract is that a human reviews every send. With no\n * approver, the `ask` permission on `send_reply` pauses the run and the human\n * decides through `agent.approvals.resolve()`, a channel's\n * `/channels/<name>/approvals/:id` route, or the chat REPL's [y/N] prompt.\n *\n * A headless deployment that wants autonomy can add `\"approve\": \"approve.ts\"`\n * to agent.json. This approver then decides every pause: `send_reply` goes\n * out only to addresses or domains on the standing allowlist\n * (`data/auto-approve.json` or INBOX_TRIAGE_AUTO_APPROVE, comma-separated);\n * everything else is refused to the model, which reports \"held for human\n * review\" instead. An approver cannot abstain - whatever it returns IS the\n * decision - so wire it in only when that trade-off is intended.\n */\n\n/** Who a send_reply would reach: the draft's recipient, else the original message's sender. */\nasync function recipientOf(args: Record<string, unknown>): Promise<string> {\n  if (typeof args.draftId === 'string') {\n    const draft = await findDraft(args.draftId);\n    if (draft) return draft.to.toLowerCase();\n  }\n  if (typeof args.messageId === 'string') {\n    try {\n      return (await getMessage(args.messageId)).from.toLowerCase();\n    } catch {\n      return '';\n    }\n  }\n  return '';\n}\n\n/** Whether `to` matches an allowlist entry (a full address or a '@domain' / bare domain). */\nfunction allowlisted(to: string, entries: readonly string[]): boolean {\n  return entries.some((entry) => {\n    const normalized = entry.startsWith('@') ? entry.slice(1) : entry;\n    return normalized.includes('@') ? to === normalized : to.endsWith(`@${normalized}`);\n  });\n}\n\nconst approve: ApproveToolCall = async ({ toolName, args }) => {\n  if (toolName !== 'send_reply') return false;\n  const to = await recipientOf(args);\n  return to !== '' && allowlisted(to, await autoApproveSenders());\n};\n\nexport default approve;\n"
+      "content": "import type { ApproveToolCall } from '@lousho/build-ai-agent';\nimport { autoApproveSenders, findDraft, getMessage } from './lib/mailstore.ts';\n\n/**\n * An OPTIONAL standing-policy approver, deliberately NOT wired into\n * agent.json: the kit's contract is that a human reviews every send. With no\n * approver, the `ask` permission on `send_reply` pauses the run and the human\n * decides through `agent.approvals.resolve()`, a channel's\n * `/channels/<name>/approvals/:id` route, or the chat REPL's [y/N] prompt.\n *\n * A headless deployment that wants autonomy can add `\"approve\": \"approve.ts\"`\n * to agent.json. This approver then decides every pause: `send_reply` goes\n * out only to addresses or domains on the standing allowlist\n * (`data/auto-approve.json` or INBOX_TRIAGE_AUTO_APPROVE, comma-separated);\n * everything else is refused to the model, which reports \"held for human\n * review\" instead. An approver cannot abstain - whatever it returns IS the\n * decision - so wire it in only when that trade-off is intended.\n */\n\n/** Who a send_reply would reach: the draft's recipient, else the original message's sender. */\nasync function recipientOf(args: Record<string, unknown>): Promise<string> {\n  if (typeof args.draftId === 'string') {\n    const draft = await findDraft(args.draftId);\n    if (draft) return draft.to.toLowerCase();\n  }\n  if (typeof args.messageId === 'string') {\n    try {\n      return (await getMessage(args.messageId)).from.toLowerCase();\n    } catch {\n      return '';\n    }\n  }\n  return '';\n}\n\n/** Whether `to` matches an allowlist entry (a full address or a '@domain' / bare domain). */\nfunction allowlisted(to: string, entries: readonly string[]): boolean {\n  return entries.some((entry) => {\n    const normalized = entry.startsWith('@') ? entry.slice(1) : entry;\n    return normalized.includes('@') ? to === normalized : to.endsWith(`@${normalized}`);\n  });\n}\n\nconst approve: ApproveToolCall = async ({ toolName, args }) => {\n  if (toolName !== 'send_reply') return false;\n  const to = await recipientOf(args);\n  return to !== '' && allowlisted(to, await autoApproveSenders());\n};\n\nexport default approve;\n"
     },
     {
       "path": "channels/inbound.ts",
-      "content": "/**\n * The inbound channel (the kit's second intake, next to the poll schedule):\n * a webhook that accepts `POST /channels/inbound` with a JSON\n * `{ from, subject?, body }`, files the message into the kit's inbox store\n * and hands the agent a triage turn keyed to the sender - the sender is the\n * session key and the verified principal, so the 'senders' memory slot scopes\n * to whoever wrote in.\n *\n * Set INBOUND_TOKEN to require `Authorization: Bearer <token>`; unset, every\n * request is accepted (fine for a local demo, not for the public internet).\n * A paused turn replies 200 with the pending `approval`; decide it at\n * `POST /channels/inbound/approvals/<id>` like every channel.\n */\nimport { defineChannel } from '@lousho/build-ai-agent';\nimport { addMessage } from '../lib/mailstore';\n\nexport default defineChannel({\n  name: 'inbound',\n  async verify(req) {\n    const expected = process.env.INBOUND_TOKEN;\n    if (expected === undefined || expected === '') return true;\n    return req.headers.authorization === `Bearer ${expected}`;\n  },\n  async parse(req) {\n    const payload = JSON.parse(req.text || '{}') as { from?: unknown; subject?: unknown; body?: unknown };\n    if (typeof payload.from !== 'string' || payload.from === '' || typeof payload.body !== 'string' || payload.body === '') {\n      throw new SyntaxError(\"POST /channels/inbound wants a JSON body with 'from' and 'body' strings (optionally 'subject').\");\n    }\n    const message = await addMessage({\n      from: payload.from,\n      subject: typeof payload.subject === 'string' && payload.subject !== '' ? payload.subject : '(no subject)',\n      body: payload.body,\n    });\n    return {\n      sessionKey: message.from,\n      input:\n        `A new message just arrived in the inbox: id ${message.id}, from ${message.from}, ` +\n        `subject \"${message.subject}\". Triage it now: read_message, classify_message, ` +\n        'recall what you know about the sender (recall_senders), draft_reply if it needs an answer ' +\n        'and call send_reply once - it pauses for human review. mark_processed when done.',\n      principal: { id: message.from, type: 'user', authenticator: 'inbound' },\n      metadata: { sender: message.from },\n      replyTo: null,\n      event: { messageId: message.id },\n    };\n  },\n  async reply({ inbound, sessionId, text, result, approval, respond }) {\n    respond?.(200, { ok: true, sessionId, messageId: (inbound.event as { messageId?: string })?.messageId, text, finishReason: result?.finishReason, approval });\n  },\n});\n"
+      "content": "/**\n * The inbound channel (the kit's second intake, next to the poll schedule):\n * a webhook that accepts `POST /channels/inbound` with a JSON\n * `{ from, subject?, body }`, files the message into the kit's inbox store\n * and hands the agent a triage turn keyed to the sender - the sender is the\n * session key and the verified principal, so the 'senders' memory slot scopes\n * to whoever wrote in.\n *\n * Set INBOUND_TOKEN to require `Authorization: Bearer <token>`; unset, every\n * request is accepted (fine for a local demo, not for the public internet).\n * A paused turn replies 200 with the pending `approval`; decide it at\n * `POST /channels/inbound/approvals/<id>` like every channel.\n */\nimport { defineChannel } from '@lousho/build-ai-agent';\nimport { addMessage } from '../lib/mailstore.ts';\n\nexport default defineChannel({\n  name: 'inbound',\n  async verify(req) {\n    const expected = process.env.INBOUND_TOKEN;\n    if (expected === undefined || expected === '') return true;\n    return req.headers.authorization === `Bearer ${expected}`;\n  },\n  async parse(req) {\n    const payload = JSON.parse(req.text || '{}') as { from?: unknown; subject?: unknown; body?: unknown };\n    if (typeof payload.from !== 'string' || payload.from === '' || typeof payload.body !== 'string' || payload.body === '') {\n      throw new SyntaxError(\"POST /channels/inbound wants a JSON body with 'from' and 'body' strings (optionally 'subject').\");\n    }\n    const message = await addMessage({\n      from: payload.from,\n      subject: typeof payload.subject === 'string' && payload.subject !== '' ? payload.subject : '(no subject)',\n      body: payload.body,\n    });\n    return {\n      sessionKey: message.from,\n      input:\n        `A new message just arrived in the inbox: id ${message.id}, from ${message.from}, ` +\n        `subject \"${message.subject}\". Triage it now: read_message, classify_message, ` +\n        'recall what you know about the sender (recall_senders), draft_reply if it needs an answer ' +\n        'and call send_reply once - it pauses for human review. mark_processed when done.',\n      principal: { id: message.from, type: 'user', authenticator: 'inbound' },\n      metadata: { sender: message.from },\n      replyTo: null,\n      event: { messageId: message.id },\n    };\n  },\n  async reply({ inbound, sessionId, text, result, approval, respond }) {\n    respond?.(200, { ok: true, sessionId, messageId: (inbound.event as { messageId?: string })?.messageId, text, finishReason: result?.finishReason, approval });\n  },\n});\n"
     },
     {
       "path": "data/inbox.json",
@@ -21,7 +21,7 @@
     },
     {
       "path": "hooks.ts",
-      "content": "import type { AgentHook } from '@lousho/build-ai-agent';\nimport { findDraft } from './lib/mailstore';\n\n/**\n * The kit's hooks (pointed at by `agent.json`'s `hooks`):\n *\n * - loop-guard: denies a tool call the model already made twice with the same\n *   arguments (ported from coding-kit);\n * - output-cap: cuts long tool results so a fat newsletter can't flood the\n *   context;\n * - no-placeholder-send: triage-specific guardrail - refuses a `send_reply`\n *   whose effective body still contains a `[PLACEHOLDER]` before the approval\n *   pause even happens, so a human is never asked to approve half-finished\n *   mail.\n */\n\n/**\n * Deny a tool call the model already made `maxRepeats` times with the same\n * arguments. `exempt` names approval-gated tools: `send_reply` pauses for a\n * human and its preToolCall fires again when the approved call resumes, so\n * counting it would let the guard overrule a human's explicit approval.\n */\nexport function loopGuard(maxRepeats = 2, exempt: readonly string[] = []): AgentHook {\n  const seen = new Map<string, number>();\n  const skip = new Set(exempt);\n  return {\n    name: 'loop-guard',\n    preToolCall(ctx) {\n      if (skip.has(ctx.toolName)) return undefined;\n      const key = `${ctx.sessionId ?? ''}:${ctx.toolName}:${JSON.stringify(ctx.args)}`;\n      const count = (seen.get(key) ?? 0) + 1;\n      seen.set(key, count);\n      if (count > maxRepeats) {\n        return { deny: `You already called ${ctx.toolName} with these arguments ${maxRepeats} times. Try something else.` };\n      }\n      return undefined;\n    },\n  };\n}\n\n/** Cut long tool results so they do not flood the context. */\nexport function outputCap(maxChars = 4_000): AgentHook {\n  return {\n    name: 'output-cap',\n    postToolCall(_ctx, result) {\n      const text = typeof result.result === 'string' ? result.result : JSON.stringify(result.result ?? '');\n      if (text.length <= maxChars) return undefined;\n      return { result: `${text.slice(0, maxChars)}\\n[output cut at ${maxChars} of ${text.length} chars]` };\n    },\n  };\n}\n\n/** The body a send_reply would actually send: the inline `body`, else the referenced draft's. */\nasync function outgoingBody(args: Record<string, unknown>): Promise<string> {\n  if (typeof args.body === 'string') return args.body;\n  if (typeof args.draftId === 'string') return (await findDraft(args.draftId))?.body ?? '';\n  return '';\n}\n\nconst PLACEHOLDER = /\\[[A-Za-z][A-Za-z _-]{1,40}\\]/;\n\n/** Refuse a send whose body still has a [PLACEHOLDER] or is empty - before the approval pause. */\nexport function noPlaceholderSend(): AgentHook {\n  return {\n    name: 'no-placeholder-send',\n    async preToolCall(ctx) {\n      if (ctx.toolName !== 'send_reply') return undefined;\n      const body = await outgoingBody(ctx.args);\n      const placeholder = PLACEHOLDER.exec(body);\n      if (body.trim() === '') {\n        return { deny: 'send_reply has no body. Write the reply with draft_reply first, or pass a complete body.' };\n      }\n      if (placeholder) {\n        return {\n          deny: `The reply still contains the placeholder ${placeholder[0]}. Fill it in (or remove it) and ask again - a human should not be paged for half-finished mail.`,\n        };\n      }\n      return undefined;\n    },\n  };\n}\n\nexport default [loopGuard(2, ['send_reply']), noPlaceholderSend(), outputCap()];\n"
+      "content": "import type { AgentHook } from '@lousho/build-ai-agent';\nimport { findDraft } from './lib/mailstore.ts';\n\n/**\n * The kit's hooks (pointed at by `agent.json`'s `hooks`):\n *\n * - loop-guard: denies a tool call the model already made twice with the same\n *   arguments (ported from coding-kit);\n * - output-cap: cuts long tool results so a fat newsletter can't flood the\n *   context;\n * - no-placeholder-send: triage-specific guardrail - refuses a `send_reply`\n *   whose effective body still contains a `[PLACEHOLDER]` before the approval\n *   pause even happens, so a human is never asked to approve half-finished\n *   mail.\n */\n\n/**\n * Deny a tool call the model already made `maxRepeats` times with the same\n * arguments. `exempt` names approval-gated tools: `send_reply` pauses for a\n * human and its preToolCall fires again when the approved call resumes, so\n * counting it would let the guard overrule a human's explicit approval.\n */\nexport function loopGuard(maxRepeats = 2, exempt: readonly string[] = []): AgentHook {\n  const seen = new Map<string, number>();\n  const skip = new Set(exempt);\n  return {\n    name: 'loop-guard',\n    preToolCall(ctx) {\n      if (skip.has(ctx.toolName)) return undefined;\n      const key = `${ctx.sessionId ?? ''}:${ctx.toolName}:${JSON.stringify(ctx.args)}`;\n      const count = (seen.get(key) ?? 0) + 1;\n      seen.set(key, count);\n      if (count > maxRepeats) {\n        return { deny: `You already called ${ctx.toolName} with these arguments ${maxRepeats} times. Try something else.` };\n      }\n      return undefined;\n    },\n  };\n}\n\n/** Cut long tool results so they do not flood the context. */\nexport function outputCap(maxChars = 4_000): AgentHook {\n  return {\n    name: 'output-cap',\n    postToolCall(_ctx, result) {\n      const text = typeof result.result === 'string' ? result.result : JSON.stringify(result.result ?? '');\n      if (text.length <= maxChars) return undefined;\n      return { result: `${text.slice(0, maxChars)}\\n[output cut at ${maxChars} of ${text.length} chars]` };\n    },\n  };\n}\n\n/** The body a send_reply would actually send: the inline `body`, else the referenced draft's. */\nasync function outgoingBody(args: Record<string, unknown>): Promise<string> {\n  if (typeof args.body === 'string') return args.body;\n  if (typeof args.draftId === 'string') return (await findDraft(args.draftId))?.body ?? '';\n  return '';\n}\n\nconst PLACEHOLDER = /\\[[A-Za-z][A-Za-z _-]{1,40}\\]/;\n\n/** Refuse a send whose body still has a [PLACEHOLDER] or is empty - before the approval pause. */\nexport function noPlaceholderSend(): AgentHook {\n  return {\n    name: 'no-placeholder-send',\n    async preToolCall(ctx) {\n      if (ctx.toolName !== 'send_reply') return undefined;\n      const body = await outgoingBody(ctx.args);\n      const placeholder = PLACEHOLDER.exec(body);\n      if (body.trim() === '') {\n        return { deny: 'send_reply has no body. Write the reply with draft_reply first, or pass a complete body.' };\n      }\n      if (placeholder) {\n        return {\n          deny: `The reply still contains the placeholder ${placeholder[0]}. Fill it in (or remove it) and ask again - a human should not be paged for half-finished mail.`,\n        };\n      }\n      return undefined;\n    },\n  };\n}\n\nexport default [loopGuard(2, ['send_reply']), noPlaceholderSend(), outputCap()];\n"
     },
     {
       "path": "instructions.md",
@@ -41,7 +41,7 @@
     },
     {
       "path": "memory/senders.ts",
-      "content": "/**\n * Per-sender memory (\"remember per-sender facts\"): who prefers a terse reply,\n * whose timezone is UTC+2, which alias the billing contact answers to.\n *\n * Scope: a run that acts for a verified sender (the inbound channel sets the\n * principal; callers can also pass `metadata.sender` to send()) gets that\n * sender's own file. Batch runs - the poll schedule, a bare `agent.send` -\n * share the 'shared' scope, so facts there are written per sender inside the\n * text (\"priya@acme.com - prefers ...\") and visible on every sweep.\n *\n * The provider wraps fileMemory() so `dir` is resolved on each call: the same\n * INBOX_TRIAGE_HOME the mail store uses, under `memory/`.\n */\nimport path from 'node:path';\nimport { defineMemory, fileMemory, type MemoryProvider } from '@lousho/build-ai-agent';\nimport { home } from '../lib/mailstore';\n\nconst backing = (): MemoryProvider => fileMemory({ dir: path.join(home(), 'memory') });\n\nconst provider: MemoryProvider = {\n  list: (scopeKey, options) => backing().list(scopeKey, options),\n  add: (scopeKey, item) => backing().add(scopeKey, item),\n  remove: (scopeKey, id) => backing().remove(scopeKey, id),\n};\n\nexport default defineMemory({\n  name: 'senders',\n  description:\n    'Facts about the people who write in: how they like to be addressed, tone, time zone, role, past decisions. In shared-scope runs, start each item with the sender address.',\n  scope: (ctx) => {\n    const claimed = ctx.principal?.id ?? (typeof ctx.metadata?.sender === 'string' ? ctx.metadata.sender : undefined);\n    // issuer and authenticator together name where the id came from (channels set authenticator).\n    const via = ctx.principal?.issuer ?? ctx.principal?.authenticator ?? 'inbox';\n    return claimed === undefined ? 'shared' : `sender:${via}:${claimed}`;\n  },\n  provider,\n});\n"
+      "content": "/**\n * Per-sender memory (\"remember per-sender facts\"): who prefers a terse reply,\n * whose timezone is UTC+2, which alias the billing contact answers to.\n *\n * Scope: a run that acts for a verified sender (the inbound channel sets the\n * principal; callers can also pass `metadata.sender` to send()) gets that\n * sender's own file. Batch runs - the poll schedule, a bare `agent.send` -\n * share the 'shared' scope, so facts there are written per sender inside the\n * text (\"priya@acme.com - prefers ...\") and visible on every sweep.\n *\n * The provider wraps fileMemory() so `dir` is resolved on each call: the same\n * INBOX_TRIAGE_HOME the mail store uses, under `memory/`.\n */\nimport path from 'node:path';\nimport { defineMemory, fileMemory, type MemoryProvider } from '@lousho/build-ai-agent';\nimport { home } from '../lib/mailstore.ts';\n\nconst backing = (): MemoryProvider => fileMemory({ dir: path.join(home(), 'memory') });\n\nconst provider: MemoryProvider = {\n  list: (scopeKey, options) => backing().list(scopeKey, options),\n  add: (scopeKey, item) => backing().add(scopeKey, item),\n  remove: (scopeKey, id) => backing().remove(scopeKey, id),\n};\n\nexport default defineMemory({\n  name: 'senders',\n  description:\n    'Facts about the people who write in: how they like to be addressed, tone, time zone, role, past decisions. In shared-scope runs, start each item with the sender address.',\n  scope: (ctx) => {\n    const claimed = ctx.principal?.id ?? (typeof ctx.metadata?.sender === 'string' ? ctx.metadata.sender : undefined);\n    // issuer and authenticator together name where the id came from (channels set authenticator).\n    const via = ctx.principal?.issuer ?? ctx.principal?.authenticator ?? 'inbox';\n    return claimed === undefined ? 'shared' : `sender:${via}:${claimed}`;\n  },\n  provider,\n});\n"
     },
     {
       "path": "schedules/poll-inbox.ts",
@@ -49,11 +49,11 @@
     },
     {
       "path": "tools/inbox.ts",
-      "content": "/**\n * The read side of the triage pipeline: list and read messages, record a\n * classification, mark a message handled. `delete_message` exists so the\n * permission manifest has something real to deny - the agent.json rule\n * refuses it (\"triage never deletes\"), which is the kit's guardrail story.\n */\nimport { z } from 'zod';\nimport { defineTool } from '@lousho/build-ai-agent';\nimport { getMessage, listMessages, updateMessage, type MessageStatus } from '../lib/mailstore';\n\nconst STATUS = z.enum(['new', 'triaged', 'replied', 'processed', 'trashed']);\n\nconst list = defineTool({\n  name: 'list_messages',\n  description:\n    \"List inbox messages, newest first: id, sender, subject, status and a short body snippet. 'status' filters; 'all' shows everything. Start triage with status 'new'.\",\n  input: z.object({\n    status: STATUS.or(z.literal('all')).default('new').describe(\"Which messages to list; 'all' shows the whole inbox\"),\n  }),\n  annotations: { readOnlyHint: true, destructiveHint: false },\n  async execute({ status }) {\n    const messages = await listMessages(status === 'all' ? undefined : (status as MessageStatus));\n    return messages.map(({ body, ...message }) => ({ ...message, snippet: body.slice(0, 160) }));\n  },\n});\n\nconst read = defineTool({\n  name: 'read_message',\n  description: 'Read one inbox message in full (the listing only shows a snippet).',\n  input: z.object({ id: z.string().describe('The message id from list_messages') }),\n  annotations: { readOnlyHint: true, destructiveHint: false },\n  async execute({ id }) {\n    return getMessage(id);\n  },\n});\n\nconst classify = defineTool({\n  name: 'classify_message',\n  description:\n    \"Record the triage classification of a message: 'urgent' (time-critical, reply today), 'reply-needed' (a real person expects an answer), 'fyi' (worth reading, no reply) or 'spam' (junk). Classifying moves the message to 'triaged'.\",\n  input: z.object({\n    id: z.string().describe('The message id from list_messages'),\n    category: z.enum(['urgent', 'reply-needed', 'fyi', 'spam']),\n    reason: z.string().describe('One sentence on why, kept on the message for the human reviewing the triage'),\n  }),\n  async execute({ id, category, reason }) {\n    return updateMessage(id, { category, categoryReason: reason, status: 'triaged' });\n  },\n});\n\nconst markProcessed = defineTool({\n  name: 'mark_processed',\n  description:\n    \"Mark a message fully handled - read, classified and (when it needed one) replied to or deliberately not answered. Processed messages leave the 'new'/'triaged' queues.\",\n  input: z.object({ id: z.string().describe('The message id from list_messages') }),\n  async execute({ id }) {\n    return updateMessage(id, { status: 'processed' });\n  },\n});\n\nconst del = defineTool({\n  name: 'delete_message',\n  description:\n    \"Move a message to 'trashed'. The kit's permission rules deny this - triage never deletes; classify junk as 'spam' and mark it processed instead.\",\n  input: z.object({ id: z.string().describe('The message id from list_messages') }),\n  annotations: { destructiveHint: true },\n  async execute({ id }) {\n    return updateMessage(id, { status: 'trashed' });\n  },\n});\n\nexport default [list, read, classify, markProcessed, del];\n"
+      "content": "/**\n * The read side of the triage pipeline: list and read messages, record a\n * classification, mark a message handled. `delete_message` exists so the\n * permission manifest has something real to deny - the agent.json rule\n * refuses it (\"triage never deletes\"), which is the kit's guardrail story.\n */\nimport { z } from 'zod';\nimport { defineTool } from '@lousho/build-ai-agent';\nimport { getMessage, listMessages, updateMessage, type MessageStatus } from '../lib/mailstore.ts';\n\nconst STATUS = z.enum(['new', 'triaged', 'replied', 'processed', 'trashed']);\n\nconst list = defineTool({\n  name: 'list_messages',\n  description:\n    \"List inbox messages, newest first: id, sender, subject, status and a short body snippet. 'status' filters; 'all' shows everything. Start triage with status 'new'.\",\n  input: z.object({\n    status: STATUS.or(z.literal('all')).default('new').describe(\"Which messages to list; 'all' shows the whole inbox\"),\n  }),\n  annotations: { readOnlyHint: true, destructiveHint: false },\n  async execute({ status }) {\n    const messages = await listMessages(status === 'all' ? undefined : (status as MessageStatus));\n    return messages.map(({ body, ...message }) => ({ ...message, snippet: body.slice(0, 160) }));\n  },\n});\n\nconst read = defineTool({\n  name: 'read_message',\n  description: 'Read one inbox message in full (the listing only shows a snippet).',\n  input: z.object({ id: z.string().describe('The message id from list_messages') }),\n  annotations: { readOnlyHint: true, destructiveHint: false },\n  async execute({ id }) {\n    return getMessage(id);\n  },\n});\n\nconst classify = defineTool({\n  name: 'classify_message',\n  description:\n    \"Record the triage classification of a message: 'urgent' (time-critical, reply today), 'reply-needed' (a real person expects an answer), 'fyi' (worth reading, no reply) or 'spam' (junk). Classifying moves the message to 'triaged'.\",\n  input: z.object({\n    id: z.string().describe('The message id from list_messages'),\n    category: z.enum(['urgent', 'reply-needed', 'fyi', 'spam']),\n    reason: z.string().describe('One sentence on why, kept on the message for the human reviewing the triage'),\n  }),\n  async execute({ id, category, reason }) {\n    return updateMessage(id, { category, categoryReason: reason, status: 'triaged' });\n  },\n});\n\nconst markProcessed = defineTool({\n  name: 'mark_processed',\n  description:\n    \"Mark a message fully handled - read, classified and (when it needed one) replied to or deliberately not answered. Processed messages leave the 'new'/'triaged' queues.\",\n  input: z.object({ id: z.string().describe('The message id from list_messages') }),\n  async execute({ id }) {\n    return updateMessage(id, { status: 'processed' });\n  },\n});\n\nconst del = defineTool({\n  name: 'delete_message',\n  description:\n    \"Move a message to 'trashed'. The kit's permission rules deny this - triage never deletes; classify junk as 'spam' and mark it processed instead.\",\n  input: z.object({ id: z.string().describe('The message id from list_messages') }),\n  annotations: { destructiveHint: true },\n  async execute({ id }) {\n    return updateMessage(id, { status: 'trashed' });\n  },\n});\n\nexport default [list, read, classify, markProcessed, del];\n"
     },
     {
       "path": "tools/replies.ts",
-      "content": "/**\n * The write side of the triage pipeline: drafts, then the one externally\n * visible action - `send_reply`. `send_reply` carries `needsApproval` in the\n * tool itself AND an `ask` permission rule in agent.json: either way, the run\n * pauses and a human decides before anything lands in the outbox.\n */\nimport { z } from 'zod';\nimport { defineTool } from '@lousho/build-ai-agent';\nimport { appendOutbox, findDraft, getMessage, listDrafts, addDraft, updateDraft, updateMessage } from '../lib/mailstore';\n\nconst list = defineTool({\n  name: 'list_drafts',\n  description: 'List reply drafts, optionally for one message. Use it to find the draft to pass to send_reply.',\n  input: z.object({ messageId: z.string().optional().describe('Only drafts replying to this message') }),\n  annotations: { readOnlyHint: true, destructiveHint: false },\n  async execute({ messageId }) {\n    return listDrafts(messageId);\n  },\n});\n\nconst draft = defineTool({\n  name: 'draft_reply',\n  description:\n    \"Write a reply draft to a message: it is saved for human review, nothing is sent. The recipient and 'Re:' subject come from the message; pass 'subject' only to override. Write the final text - no [placeholders]; a hook refuses half-written drafts at send time.\",\n  input: z.object({\n    messageId: z.string().describe('The message id being replied to'),\n    body: z.string().describe('The full reply body, ready to send as-is'),\n    subject: z.string().optional().describe(\"Defaults to 'Re: <original subject>'\"),\n  }),\n  async execute({ messageId, body, subject }) {\n    const message = await getMessage(messageId);\n    return addDraft({ messageId, to: message.from, subject: subject ?? `Re: ${message.subject}`, body });\n  },\n});\n\nconst send = defineTool({\n  name: 'send_reply',\n  description:\n    'Send a reply: the draft (draftId) or an inline body lands in the outbox and the message is marked replied. Every call pauses for human approval - call it once, with the final text, after the human has had a chance to review the draft.',\n  input: z\n    .object({\n      messageId: z.string().describe('The message id being replied to'),\n      draftId: z.string().optional().describe('A draft from draft_reply to send as-is'),\n      body: z.string().optional().describe('An inline reply body when there is no draft'),\n      subject: z.string().optional().describe('Subject for an inline reply; defaults to the draft\\'s or \"Re: <original>\"'),\n    })\n    .refine((args) => (args.draftId !== undefined) !== (args.body !== undefined), {\n      message: \"pass exactly one of 'draftId' (send the reviewed draft) or 'body' (inline reply)\",\n    }),\n  needsApproval: true,\n  annotations: { readOnlyHint: false, openWorldHint: true },\n  async execute({ messageId, draftId, body, subject }) {\n    const message = await getMessage(messageId);\n    const draftBody = draftId === undefined ? undefined : await findDraft(draftId);\n    if (draftId !== undefined && (draftBody === undefined || draftBody.messageId !== messageId)) {\n      throw new Error(`no draft '${draftId}' for message '${messageId}' - call list_drafts for the current draft ids`);\n    }\n    if (draftBody?.status === 'sent') throw new Error(`draft '${draftId}' was already sent`);\n    const entry = await appendOutbox({\n      messageId,\n      ...(draftId !== undefined && { draftId }),\n      to: draftBody?.to ?? message.from,\n      subject: subject ?? draftBody?.subject ?? `Re: ${message.subject}`,\n      body: draftBody?.body ?? (body as string),\n    });\n    if (draftBody) await updateDraft(draftBody.id, { status: 'sent' });\n    await updateMessage(messageId, { status: 'replied' });\n    return { sent: true, outboxId: entry.id, to: entry.to, subject: entry.subject };\n  },\n});\n\nexport default [list, draft, send];\n"
+      "content": "/**\n * The write side of the triage pipeline: drafts, then the one externally\n * visible action - `send_reply`. `send_reply` carries `needsApproval` in the\n * tool itself AND an `ask` permission rule in agent.json: either way, the run\n * pauses and a human decides before anything lands in the outbox.\n */\nimport { z } from 'zod';\nimport { defineTool } from '@lousho/build-ai-agent';\nimport { appendOutbox, findDraft, getMessage, listDrafts, addDraft, updateDraft, updateMessage } from '../lib/mailstore.ts';\n\nconst list = defineTool({\n  name: 'list_drafts',\n  description: 'List reply drafts, optionally for one message. Use it to find the draft to pass to send_reply.',\n  input: z.object({ messageId: z.string().optional().describe('Only drafts replying to this message') }),\n  annotations: { readOnlyHint: true, destructiveHint: false },\n  async execute({ messageId }) {\n    return listDrafts(messageId);\n  },\n});\n\nconst draft = defineTool({\n  name: 'draft_reply',\n  description:\n    \"Write a reply draft to a message: it is saved for human review, nothing is sent. The recipient and 'Re:' subject come from the message; pass 'subject' only to override. Write the final text - no [placeholders]; a hook refuses half-written drafts at send time.\",\n  input: z.object({\n    messageId: z.string().describe('The message id being replied to'),\n    body: z.string().describe('The full reply body, ready to send as-is'),\n    subject: z.string().optional().describe(\"Defaults to 'Re: <original subject>'\"),\n  }),\n  async execute({ messageId, body, subject }) {\n    const message = await getMessage(messageId);\n    return addDraft({ messageId, to: message.from, subject: subject ?? `Re: ${message.subject}`, body });\n  },\n});\n\nconst send = defineTool({\n  name: 'send_reply',\n  description:\n    'Send a reply: the draft (draftId) or an inline body lands in the outbox and the message is marked replied. Every call pauses for human approval - call it once, with the final text, after the human has had a chance to review the draft.',\n  input: z\n    .object({\n      messageId: z.string().describe('The message id being replied to'),\n      draftId: z.string().optional().describe('A draft from draft_reply to send as-is'),\n      body: z.string().optional().describe('An inline reply body when there is no draft'),\n      subject: z.string().optional().describe('Subject for an inline reply; defaults to the draft\\'s or \"Re: <original>\"'),\n    })\n    .refine((args) => (args.draftId !== undefined) !== (args.body !== undefined), {\n      message: \"pass exactly one of 'draftId' (send the reviewed draft) or 'body' (inline reply)\",\n    }),\n  needsApproval: true,\n  annotations: { readOnlyHint: false, openWorldHint: true },\n  async execute({ messageId, draftId, body, subject }) {\n    const message = await getMessage(messageId);\n    const draftBody = draftId === undefined ? undefined : await findDraft(draftId);\n    if (draftId !== undefined && (draftBody === undefined || draftBody.messageId !== messageId)) {\n      throw new Error(`no draft '${draftId}' for message '${messageId}' - call list_drafts for the current draft ids`);\n    }\n    if (draftBody?.status === 'sent') throw new Error(`draft '${draftId}' was already sent`);\n    const entry = await appendOutbox({\n      messageId,\n      ...(draftId !== undefined && { draftId }),\n      to: draftBody?.to ?? message.from,\n      subject: subject ?? draftBody?.subject ?? `Re: ${message.subject}`,\n      body: draftBody?.body ?? (body as string),\n    });\n    if (draftBody) await updateDraft(draftBody.id, { status: 'sent' });\n    await updateMessage(messageId, { status: 'replied' });\n    return { sent: true, outboxId: entry.id, to: entry.to, subject: entry.subject };\n  },\n});\n\nexport default [list, draft, send];\n"
     }
   ],
   "permissions": {
diff --git a/registry/inbox-triage/approve.ts b/registry/inbox-triage/approve.ts
index 91335feef..92bbeb37c 100644
--- a/registry/inbox-triage/approve.ts
+++ b/registry/inbox-triage/approve.ts
@@ -1,5 +1,5 @@
 import type { ApproveToolCall } from '@lousho/build-ai-agent';
-import { autoApproveSenders, findDraft, getMessage } from './lib/mailstore';
+import { autoApproveSenders, findDraft, getMessage } from './lib/mailstore.ts';
 
 /**
  * An OPTIONAL standing-policy approver, deliberately NOT wired into
diff --git a/registry/inbox-triage/channels/inbound.ts b/registry/inbox-triage/channels/inbound.ts
index f0dd77e88..1dd2db24b 100644
--- a/registry/inbox-triage/channels/inbound.ts
+++ b/registry/inbox-triage/channels/inbound.ts
@@ -12,7 +12,7 @@
  * `POST /channels/inbound/approvals/<id>` like every channel.
  */
 import { defineChannel } from '@lousho/build-ai-agent';
-import { addMessage } from '../lib/mailstore';
+import { addMessage } from '../lib/mailstore.ts';
 
 export default defineChannel({
   name: 'inbound',
diff --git a/registry/inbox-triage/hooks.ts b/registry/inbox-triage/hooks.ts
index 42b6d06fc..75f796eb6 100644
--- a/registry/inbox-triage/hooks.ts
+++ b/registry/inbox-triage/hooks.ts
@@ -1,5 +1,5 @@
 import type { AgentHook } from '@lousho/build-ai-agent';
-import { findDraft } from './lib/mailstore';
+import { findDraft } from './lib/mailstore.ts';
 
 /**
  * The kit's hooks (pointed at by `agent.json`'s `hooks`):
diff --git a/registry/inbox-triage/memory/senders.ts b/registry/inbox-triage/memory/senders.ts
index 96a1f482f..8af1fedb1 100644
--- a/registry/inbox-triage/memory/senders.ts
+++ b/registry/inbox-triage/memory/senders.ts
@@ -13,7 +13,7 @@
  */
 import path from 'node:path';
 import { defineMemory, fileMemory, type MemoryProvider } from '@lousho/build-ai-agent';
-import { home } from '../lib/mailstore';
+import { home } from '../lib/mailstore.ts';
 
 const backing = (): MemoryProvider => fileMemory({ dir: path.join(home(), 'memory') });
 
diff --git a/registry/inbox-triage/tools/inbox.ts b/registry/inbox-triage/tools/inbox.ts
index bd7d17dfa..f9914bea3 100644
--- a/registry/inbox-triage/tools/inbox.ts
+++ b/registry/inbox-triage/tools/inbox.ts
@@ -6,7 +6,7 @@
  */
 import { z } from 'zod';
 import { defineTool } from '@lousho/build-ai-agent';
-import { getMessage, listMessages, updateMessage, type MessageStatus } from '../lib/mailstore';
+import { getMessage, listMessages, updateMessage, type MessageStatus } from '../lib/mailstore.ts';
 
 const STATUS = z.enum(['new', 'triaged', 'replied', 'processed', 'trashed']);
 
diff --git a/registry/inbox-triage/tools/replies.ts b/registry/inbox-triage/tools/replies.ts
index 96e1ef470..ce2dc3a7e 100644
--- a/registry/inbox-triage/tools/replies.ts
+++ b/registry/inbox-triage/tools/replies.ts
@@ -6,7 +6,7 @@
  */
 import { z } from 'zod';
 import { defineTool } from '@lousho/build-ai-agent';
-import { appendOutbox, findDraft, getMessage, listDrafts, addDraft, updateDraft, updateMessage } from '../lib/mailstore';
+import { appendOutbox, findDraft, getMessage, listDrafts, addDraft, updateDraft, updateMessage } from '../lib/mailstore.ts';
 
 const list = defineTool({
   name: 'list_drafts',
diff --git a/src/agentDir/importModule.test.ts b/src/agentDir/importModule.test.ts
new file mode 100644
index 000000000..b2262d47f
--- /dev/null
+++ b/src/agentDir/importModule.test.ts
@@ -0,0 +1,55 @@
+/**
+ * `withFreshImports` re-evaluates the local files a reloaded file imports
+ * (`lousho dev` hot reload). The resolve hook it installs is a Node loader
+ * hook, which vitest's own module runner bypasses, so this bundles
+ * importModule.ts and runs it in a plain `node` process, as the CLI does.
+ */
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+let dir: string;
+
+beforeAll(async () => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'lousho-fresh-imports-'));
+  const { build } = await import('esbuild');
+  await build({
+    entryPoints: [path.join(__dirname, 'importModule.ts')],
+    outfile: path.join(dir, 'importModule.mjs'),
+    bundle: true,
+    format: 'esm',
+    platform: 'node',
+    logLevel: 'silent',
+  });
+}, 60_000);
+
+afterAll(() => fs.rmSync(dir, { recursive: true, force: true }));
+
+describe('withFreshImports', () => {
+  it('re-evaluates the local helpers of a reloaded file, not only the file itself', () => {
+    const agent = path.join(dir, 'agent');
+    fs.mkdirSync(path.join(agent, 'lib'), { recursive: true });
+    fs.writeFileSync(path.join(agent, 'package.json'), '{"type":"module"}');
+    fs.writeFileSync(path.join(agent, 'tool.ts'), "import { version } from './lib/helper.ts';\nexport const seen: string = version;\n");
+    const helper = path.join(agent, 'lib', 'helper.ts');
+    const script = `
+      import * as fs from 'node:fs';
+      import { importModule, withFreshImports } from ${JSON.stringify(path.join(dir, 'importModule.mjs'))};
+      const seen = [];
+      for (const [i, v] of ['v1', 'v2', 'v3'].entries()) {
+        fs.writeFileSync(${JSON.stringify(helper)}, 'export const version: string = ' + JSON.stringify(v) + ';\\n');
+        const mod = await withFreshImports('1-' + i, () => importModule(${JSON.stringify(path.join(agent, 'tool.ts'))}));
+        seen.push(mod.seen);
+      }
+      console.log(seen.join(','));
+    `;
+    const run = spawnSync(process.execPath, ['--input-type=module', '-e', script], {
+      encoding: 'utf8',
+      env: { ...process.env, NODE_OPTIONS: '' },
+    });
+    expect(run.stderr).toBe('');
+    expect(run.stdout.trim()).toBe('v1,v2,v3');
+  });
+});
diff --git a/src/agentDir/importModule.ts b/src/agentDir/importModule.ts
index ba34be8fc..d5794d40c 100644
--- a/src/agentDir/importModule.ts
+++ b/src/agentDir/importModule.ts
@@ -1,8 +1,9 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { realpathSync } from 'node:fs';
+import { existsSync, realpathSync } from 'node:fs';
+import * as nodeModule from 'node:module';
 import { createRequire } from 'node:module';
 import * as path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { SDKError } from '../utils/sdkError';
 
 const cacheBust = new AsyncLocalStorage<string>();
@@ -10,15 +11,67 @@ const cacheBust = new AsyncLocalStorage<string>();
 /**
  * Runs `fn` so every file `importModule()` loads inside it is imported with a
  * `?t=<token>` query: a fresh module instance instead of the cached one
- * (`lousho dev` hot reload, LOU-D31). Only the file itself is re-evaluated;
- * modules it imports stay cached by the runtime. A CommonJS file (`.cjs`, or
- * `.js` in a package without `"type": "module"`) is cached by file name, which
- * ignores the query, so it is also dropped from `require.cache` first.
+ * (`lousho dev` hot reload, LOU-D31). A resolve hook (see
+ * {@link freshImportGraph}) passes the query on to the local files such a file
+ * imports by relative specifier, so an edited helper is re-evaluated too;
+ * packages under node_modules stay cached. A CommonJS file (`.cjs`, or `.js` in
+ * a package without `"type": "module"`) is cached by file name, which ignores
+ * the query, so it is also dropped from `require.cache` first.
  */
 export function withFreshImports<T>(token: string, fn: () => Promise<T>): Promise<T> {
+  freshImportGraph();
   return cacheBust.run(token, fn);
 }
 
+/** The `t` query a cache-busted import carries (the tokens `lousho dev` issues are `<digits>-<digits>`). */
+const FRESH_QUERY = /[?&]t=(\d+-\d+)(?:[&#]|$)/;
+
+interface ResolveResult {
+  url: string;
+  format?: string | null;
+  shortCircuit?: boolean;
+}
+type RegisterHooks = (hooks: {
+  resolve: (
+    specifier: string,
+    context: { parentURL?: string; conditions?: readonly string[] },
+    nextResolve: (specifier: string, context?: unknown) => ResolveResult
+  ) => ResolveResult;
+}) => unknown;
+
+let graphHook: boolean | undefined;
+
+/**
+ * Installs (once) a synchronous resolve hook: an ESM `import` of a relative
+ * specifier from a module loaded with `?t=<token>` resolves with the same
+ * query, so the whole local import graph of a reloaded file is evaluated
+ * afresh. Returns false when this Node has no `module.registerHooks` (before
+ * 22.15), where only the file itself is re-evaluated.
+ */
+function freshImportGraph(): boolean {
+  if (graphHook !== undefined) return graphHook;
+  const registerHooks = (nodeModule as unknown as { registerHooks?: RegisterHooks }).registerHooks;
+  if (typeof registerHooks !== 'function') return (graphHook = false);
+  registerHooks({
+    resolve(specifier, context, nextResolve) {
+      const result = nextResolve(specifier, context);
+      const token = FRESH_QUERY.exec(context.parentURL ?? '')?.[1];
+      if (
+        token === undefined ||
+        !/^\.{1,2}\//.test(specifier) ||
+        !(context.conditions ?? []).includes('import') ||
+        !result.url.startsWith('file:') ||
+        result.url.includes('?') ||
+        result.url.includes('/node_modules/')
+      ) {
+        return result;
+      }
+      return { ...result, url: `${result.url}?t=${token}` };
+    },
+  });
+  return (graphHook = true);
+}
+
 /** Node error codes that mean "this process cannot load a TypeScript file". */
 const NO_TS_LOADER_CODES = new Set(['ERR_UNKNOWN_FILE_EXTENSION']);
 
@@ -44,6 +97,7 @@ export function explainImportError(file: string, error: unknown): Error {
   if (TS_FILE.test(file) && cause.code !== undefined && NO_TS_LOADER_CODES.has(cause.code)) {
     return new Error(
       `loadAgentDir: cannot import ${file}: this process cannot load TypeScript files (${cause.code}). ` +
+        nodeTooOld() +
         "Run your script under a TypeScript loader, e.g. 'npx tsx your-script.ts' (also works with " +
         "ts-node, bun, deno, or Node's --experimental-strip-types), or compile the agent directory to " +
         'JavaScript first and load the compiled output. Alternatively write this file as .js/.mjs, or ' +
@@ -63,9 +117,48 @@ export function explainImportError(file: string, error: unknown): Error {
         `Install it in the project that contains the agent directory (npm install ${missing}), or move the agent directory inside a project that has it installed.`,
     });
   }
+  const extension = missingExtension(file, cause);
+  if (extension !== undefined) {
+    return new SDKError(message, 'LOUSHO_AGENT_DIR_INVALID', {
+      cause: error,
+      hint:
+        `Node resolves relative imports only with the file extension: write '${extension.fixed}' instead of '${extension.written}'. ` +
+        'Bundlers and tsx add it for you; the lousho CLI loads TypeScript with Node itself.',
+    });
+  }
   return new SDKError(message, 'LOUSHO_AGENT_DIR_INVALID', { cause: error });
 }
 
+/** The Node version note for a process with no built-in type stripping (before Node 22.18), or ''. */
+function nodeTooOld(): string {
+  const [major, minor] = process.versions.node.split('.').map(Number);
+  if (major > 22 || (major === 22 && minor >= 18)) return '';
+  return `The lousho CLI loads .ts files with Node's built-in type stripping, which needs Node 22.19 or newer (this is Node ${process.versions.node}): upgrade Node. `;
+}
+
+const SOURCE_EXT = ['.ts', '.mts', '.cts', '.js', '.mjs', '.cjs'];
+
+/**
+ * For a relative import written without its extension (`./lib/store` for
+ * `./lib/store.ts`), the specifier as written and as it should be; undefined
+ * when the error is about something else or no such file exists.
+ */
+function missingExtension(file: string, cause: NodeJS.ErrnoException): { written: string; fixed: string } | undefined {
+  if (cause.code !== 'ERR_MODULE_NOT_FOUND' && cause.code !== 'MODULE_NOT_FOUND') return undefined;
+  const match = /Cannot find module '([^']+)'(?: imported from (.+?)\s*$)?/m.exec(cause.message ?? '');
+  const specifier = match?.[1];
+  if (specifier === undefined || !/^(?:\.{1,2}[\\/]|\/|[A-Za-z]:[\\/]|file:)/.test(specifier)) return undefined;
+  const from = match?.[2]?.replace(/\?.*$/, '');
+  const importer = from === undefined ? file : from.startsWith('file:') ? fileURLToPath(from) : from;
+  const target = specifier.startsWith('file:') ? fileURLToPath(specifier) : path.resolve(path.dirname(importer), specifier);
+  const relative = path.relative(path.dirname(importer), target).split(path.sep).join('/');
+  const written = relative.startsWith('.') ? relative : `./${relative}`;
+  const ext = SOURCE_EXT.find((e) => existsSync(target + e));
+  if (ext !== undefined) return { written, fixed: written + ext };
+  const index = SOURCE_EXT.find((e) => existsSync(path.join(target, `index${e}`)));
+  return index === undefined ? undefined : { written, fixed: `${written}/index${index}` };
+}
+
 /** The bare package name a "module not found" import error is about, or undefined (also for a missing relative file). */
 function missingPackage(cause: NodeJS.ErrnoException): string | undefined {
   if (cause.code !== 'ERR_MODULE_NOT_FOUND' && cause.code !== 'MODULE_NOT_FOUND') return undefined;
diff --git a/src/agentDir/loadAgentDir.test.ts b/src/agentDir/loadAgentDir.test.ts
index 7952df418..ca6a2cea7 100644
--- a/src/agentDir/loadAgentDir.test.ts
+++ b/src/agentDir/loadAgentDir.test.ts
@@ -637,6 +637,37 @@ describe('helpers', () => {
     expect(plain.hint).not.toContain('npm install');
   });
 
+  it('hints at the missing file extension of a relative import that type stripping cannot resolve', () => {
+    const dir = mkdtempSync(path.join(tmpdir(), 'lousho-ext-hint-'));
+    mkdirSync(path.join(dir, 'lib'));
+    writeFileSync(path.join(dir, 'lib', 'store.ts'), 'export {};');
+    const hooks = path.join(dir, 'hooks.ts');
+    const esm = Object.assign(new Error(`Cannot find module '${path.join(dir, 'lib', 'store')}' imported from ${hooks}`), {
+      code: 'ERR_MODULE_NOT_FOUND',
+    });
+    const error = explainImportError(hooks, esm) as SDKError;
+    expect(error.code).toBe('LOUSHO_AGENT_DIR_INVALID');
+    expect(error.hint).toContain("write './lib/store.ts' instead of './lib/store'");
+    const cjs = Object.assign(new Error("Cannot find module './lib/store'\nRequire stack:\n- x"), { code: 'MODULE_NOT_FOUND' });
+    expect((explainImportError(hooks, cjs) as SDKError).hint).toContain("'./lib/store.ts'");
+    // No such file with any extension: no extension hint.
+    const gone = Object.assign(new Error("Cannot find module './lib/nope'"), { code: 'MODULE_NOT_FOUND' });
+    expect((explainImportError(hooks, gone) as SDKError).hint ?? '').not.toContain('instead of');
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('names the Node version when it has no built-in type stripping', () => {
+    const cause = Object.assign(new Error('Unknown file extension ".ts"'), { code: 'ERR_UNKNOWN_FILE_EXTENSION' });
+    const node = Object.getOwnPropertyDescriptor(process.versions, 'node');
+    Object.defineProperty(process.versions, 'node', { value: '20.20.0', configurable: true });
+    try {
+      expect(explainImportError('/x/tools/a.ts', cause).message).toContain('needs Node 22.19 or newer (this is Node 20.20.0)');
+    } finally {
+      Object.defineProperty(process.versions, 'node', node as PropertyDescriptor);
+    }
+    expect(explainImportError('/x/tools/a.ts', cause).message).not.toContain('this is Node');
+  });
+
   it('suggests close keys and nothing for distant ones', () => {
     expect(closest('maxStep', ['maxSteps', 'name'])).toBe('maxSteps');
     expect(closest('prompt', ['instructions', 'name'])).toBe('instructions');
diff --git a/src/cli/defaultRegistry.test.ts b/src/cli/defaultRegistry.test.ts
index 7a016a829..90a2d271c 100644
--- a/src/cli/defaultRegistry.test.ts
+++ b/src/cli/defaultRegistry.test.ts
@@ -21,6 +21,7 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { PassThrough, Writable } from 'node:stream';
 import { resolveAgentDir } from '@lousho/build-ai-agent';
 import { runAdd } from './add';
@@ -118,4 +119,31 @@ describe('default registry (registry/dist)', () => {
       else process.env.WEBHOOK_SECRET = secret;
     }
   });
+
+  // The CLI loads agent directories with Node's own type stripping, which needs the
+  // `.ts` extension on relative imports; vitest and tsup resolve `./lib/x` anyway, so
+  // only a plain `node` process catches a kit that `lousho dev`/`chat` cannot load.
+  it('installs every kit and each loads under plain node, as the CLI loads it', async () => {
+    const index = IndexSchema.parse(JSON.parse(fs.readFileSync(INDEX, 'utf8')));
+    const kits = index.items.filter((entry) => entry.type === 'kit');
+    expect(kits.length).toBeGreaterThan(0);
+    const loader =
+      "const { resolveAgentDir } = await import('@lousho/build-ai-agent');" +
+      'const { manifest } = await resolveAgentDir(process.argv[1]);' +
+      'console.log(JSON.stringify({ tools: manifest.tools.length }));';
+    // Dummy keys and secrets: the kits are only loaded, never run.
+    const env = { ...process.env, NODE_OPTIONS: '', OPENROUTER_API_KEY: 'x', OPENAI_API_KEY: 'x', ANTHROPIC_API_KEY: 'x', WEBHOOK_SECRET: 'x', INBOUND_TOKEN: 'x' };
+    for (const entry of kits) {
+      const result = await add([entry.name, '--registry', INDEX, '--dir', entry.name, '--yes', '--allow', 'exec,fs-write,network,env']);
+      expect(result.err, entry.name).toBe('');
+      expect(result.code, entry.name).toBe(0);
+      const run = spawnSync(process.execPath, ['--input-type=module', '-e', loader, path.join(root, entry.name)], {
+        cwd: root,
+        encoding: 'utf8',
+        env: { ...env, INBOX_TRIAGE_HOME: path.join(root, `${entry.name}-home`) },
+      });
+      expect(run.status, `${entry.name}: ${run.stderr}`).toBe(0);
+      expect(JSON.parse(run.stdout.trim().split('\n').pop() as string).tools, entry.name).toBeGreaterThan(0);
+    }
+  }, 120_000);
 });

From 6303ee20deb17bf09575cb76ac4cab470f553941 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 12 Oct 2026 11:17:56 +0000
Subject: [PATCH 02/11] fix(providers): pass OPENAI_BASE_URL /
 ANTHROPIC_BASE_URL on ai 4 provider packages

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BG6n8mwoFq1jmay9zCPS6n
---
 docs/providers.md                       |  5 +++--
 src/cli/doctorChecks.ts                 |  4 ++--
 src/providers/AnthropicProvider.test.ts | 15 +++++++++++++++
 src/providers/AnthropicProvider.ts      |  4 +++-
 src/providers/OpenAIProvider.test.ts    | 16 ++++++++++++++++
 src/providers/OpenAIProvider.ts         | 14 ++++++++++----
 6 files changed, 49 insertions(+), 9 deletions(-)

diff --git a/docs/providers.md b/docs/providers.md
index acb484ae8..7fd5bbdd9 100644
--- a/docs/providers.md
+++ b/docs/providers.md
@@ -428,8 +428,9 @@ const agent = createAgent({
   `registerModel({ id, provider: 'openai', contextWindow })` once (see
   [Local and unknown models](./compaction.md#local-and-unknown-models)).
 
-**The `openai/<model>` string with `OPENAI_BASE_URL`.** `@ai-sdk/openai` reads
-`OPENAI_BASE_URL`, so `createAgent({ model: 'openai/qwen3-8b' })` with
+**The `openai/<model>` string with `OPENAI_BASE_URL`.** `OpenAIProvider` passes
+`OPENAI_BASE_URL` to `@ai-sdk/openai` when no `baseURL` is configured (on every
+major, including the 1.x line that pairs with `ai` 4), so `createAgent({ model: 'openai/qwen3-8b' })` with
 `OPENAI_BASE_URL=http://localhost:1234/v1` and a dummy `OPENAI_API_KEY=any`
 calls the local server without code changes. That route uses the Responses
 API unless `LOUSHO_OPENAI_API=chat` is set too, which selects Chat Completions
diff --git a/src/cli/doctorChecks.ts b/src/cli/doctorChecks.ts
index 025c8d02d..ce530bf74 100644
--- a/src/cli/doctorChecks.ts
+++ b/src/cli/doctorChecks.ts
@@ -169,7 +169,7 @@ export function checkOptionalPeers(env: DoctorEnvironment, needs: SpecNeeds): Do
   return [...providers, ...features].map(([name, peer]) => checkOptionalPeer(env, name, peer));
 }
 
-/** The env variable the provider package reads for a custom endpoint (a local or OpenAI-compatible server). */
+/** The env variable the provider reads for a custom endpoint (a local or OpenAI-compatible server), on every provider-package major. */
 const BASE_URL_ENV: Record<string, string> = { openai: 'OPENAI_BASE_URL', anthropic: 'ANTHROPIC_BASE_URL' };
 
 /** `; base URL <url> (from <VAR>)` when the provider's base-URL variable is set; credentials and query are left out. */
@@ -239,7 +239,7 @@ function displayUrl(raw: string): string | null {
   }
 }
 
-/** OPENAI_BASE_URL (read by `@ai-sdk/openai`, so `openai/<model>` calls it); only shown when set. */
+/** OPENAI_BASE_URL (passed to `@ai-sdk/openai` by OpenAIProvider, so `openai/<model>` calls it); only shown when set. */
 export function checkOpenAIBaseUrl(env: DoctorEnvironment): DoctorCheck | null {
   const raw = env.env.OPENAI_BASE_URL;
   if (!raw) return null;
diff --git a/src/providers/AnthropicProvider.test.ts b/src/providers/AnthropicProvider.test.ts
index 2b52ba0ee..c85687779 100644
--- a/src/providers/AnthropicProvider.test.ts
+++ b/src/providers/AnthropicProvider.test.ts
@@ -192,6 +192,21 @@ describe('AnthropicProvider', () => {
     });
   });
 
+  // `@ai-sdk/anthropic` 0.x/1.x (the ai 4 line) does not read ANTHROPIC_BASE_URL itself; the provider passes it.
+  it('builds its model against ANTHROPIC_BASE_URL when no baseURL is configured', async () => {
+    vi.stubEnv('ANTHROPIC_BASE_URL', 'http://127.0.0.1:4998/v1');
+    try {
+      const local = new AnthropicProvider({ name: 'anthropic', apiKey: 'any' });
+      type Built = { config: { baseURL?: string; url?: (o: { path: string }) => string } };
+      const model = await (local as unknown as { createModel(id: string): Promise<Built> }).createModel('claude-sonnet-4-5');
+      // 0.x keeps `baseURL` on the model config; newer majors keep a `url()` builder.
+      const url = model.config.baseURL ?? model.config.url?.({ path: '/messages' });
+      expect(url).toContain('http://127.0.0.1:4998/v1');
+    } finally {
+      vi.unstubAllEnvs();
+    }
+  });
+
   describe('registry', () => {
     it('is retrievable via LLMProviderRegistry.create under the name "anthropic"', () => {
       expect(LLMProviderRegistry.has('anthropic')).toBe(true);
diff --git a/src/providers/AnthropicProvider.ts b/src/providers/AnthropicProvider.ts
index cfc682917..f99fae36b 100644
--- a/src/providers/AnthropicProvider.ts
+++ b/src/providers/AnthropicProvider.ts
@@ -71,7 +71,9 @@ export class AnthropicProvider extends AiSdkProvider<AnthropicProviderConfig> {
       () => import('@ai-sdk/anthropic'),
       aiMajorOf(this.ai)
     );
-    return createAnthropic(this.clientOptions());
+    // `@ai-sdk/anthropic` 2+ reads ANTHROPIC_BASE_URL itself; 0.x/1.x (the ai 4 line) does not, so it is passed explicitly.
+    const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env;
+    return createAnthropic({ ...this.clientOptions(), baseURL: this.config.baseURL ?? (env?.ANTHROPIC_BASE_URL || undefined) });
   });
 
   /** PDF file parts go to the model on ai 6 and 7; older peers have no file parts. */
diff --git a/src/providers/OpenAIProvider.test.ts b/src/providers/OpenAIProvider.test.ts
index 28fd82557..a3e56d0d0 100644
--- a/src/providers/OpenAIProvider.test.ts
+++ b/src/providers/OpenAIProvider.test.ts
@@ -83,6 +83,22 @@ describe('OpenAIProvider', () => {
       await expect(local.generate({ messages: [{ role: 'user', content: 'hi' }], model: 'qwen3' })).rejects.toThrow();
       expect(String(fetchMock.mock.calls[0][0])).toBe('http://localhost:1234/v1/chat/completions');
     });
+
+    // `@ai-sdk/openai` 1.x (the ai 4 line) does not read OPENAI_BASE_URL itself; the provider passes it.
+    it('calls OPENAI_BASE_URL when no baseURL is configured, on every @ai-sdk/openai major', async () => {
+      const fetchMock = vi.fn().mockImplementation(
+        async () => new Response(JSON.stringify({ error: { message: 'stub' } }), { status: 400 })
+      );
+      vi.stubGlobal('fetch', fetchMock);
+      vi.stubEnv('OPENAI_BASE_URL', 'http://127.0.0.1:4999/v1');
+      try {
+        const local = new OpenAIProvider({ name: 'openai', apiKey: 'any', api: 'chat', maxRetries: 0 });
+        await expect(local.generate({ messages: [{ role: 'user', content: 'hi' }], model: 'qwen3' })).rejects.toThrow();
+        expect(String(fetchMock.mock.calls[0][0])).toBe('http://127.0.0.1:4999/v1/chat/completions');
+      } finally {
+        vi.unstubAllEnvs();
+      }
+    });
   });
 
   // Note: Actual API calls are not tested to avoid external dependencies
diff --git a/src/providers/OpenAIProvider.ts b/src/providers/OpenAIProvider.ts
index 942d86a56..8a701680e 100644
--- a/src/providers/OpenAIProvider.ts
+++ b/src/providers/OpenAIProvider.ts
@@ -62,10 +62,14 @@ export interface OpenAIProviderConfig extends AiSdkProviderConfig {
   store?: boolean;
 }
 
-/** `LOUSHO_OPENAI_API`, where there is a `process.env` (not in a browser or Worker). */
+/** `process.env`, where there is one (not in a browser or Worker). */
+function processEnv(): Record<string, string | undefined> | undefined {
+  return (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env;
+}
+
+/** `LOUSHO_OPENAI_API`, where there is a `process.env`. */
 function envApi(): string | undefined {
-  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env;
-  return env?.LOUSHO_OPENAI_API?.trim().toLowerCase();
+  return processEnv()?.LOUSHO_OPENAI_API?.trim().toLowerCase();
 }
 
 /**
@@ -79,7 +83,9 @@ export class OpenAIProvider extends AiSdkProvider<OpenAIProviderConfig> {
   /** Loads `@ai-sdk/openai` on first use (it is an optional peer). */
   private readonly loadProvider = lazyValue(async () => {
     const { createOpenAI } = await loadOptionalPeer('@ai-sdk/openai', () => import('@ai-sdk/openai'), aiMajorOf(this.ai));
-    return createOpenAI({ ...this.clientOptions(), organization: this.config.organization });
+    // `@ai-sdk/openai` 2+ reads OPENAI_BASE_URL itself; 0.x/1.x (the ai 4 line) does not, so it is passed explicitly.
+    const baseURL = this.config.baseURL ?? (processEnv()?.OPENAI_BASE_URL || undefined);
+    return createOpenAI({ ...this.clientOptions(), baseURL, organization: this.config.organization });
   });
 
   /** PDF file parts go to the model on ai 6 and 7; older peers have no file parts. */

From 2a3105495ef2dab9c7e2a3f09834f4dbf7476bb3 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 12 Oct 2026 11:17:56 +0000
Subject: [PATCH 03/11] fix(execution): PropagatingToolError, McpToolError,
 WorkspaceError instanceof across SDK copies

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BG6n8mwoFq1jmay9zCPS6n
---
 api/index.api.md                      |  3 +++
 api/mcp.api.md                        |  1 +
 api/tools.api.md                      |  2 ++
 src/execution/propagatingToolError.ts | 13 +++++++++++--
 src/providers/sharedChunks.test.ts    | 24 +++++++++++++++++++++++-
 src/tools/mcp/result.ts               |  7 +++++++
 src/tools/workspace/paths.ts          |  7 +++++++
 7 files changed, 54 insertions(+), 3 deletions(-)

diff --git a/api/index.api.md b/api/index.api.md
index 04f1c7e76..a634b7094 100644
--- a/api/index.api.md
+++ b/api/index.api.md
@@ -3711,6 +3711,7 @@ export interface McpToolAnnotations {
 
 // @public
 export class McpToolError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
     constructor(message: string);
     readonly toolErrorKind: "mcp";
 }
@@ -4769,6 +4770,7 @@ export interface PromptScheduleInput extends ScheduleBase {
 
 // @public
 export class PropagatingToolError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
 }
 
 // @public
@@ -7137,6 +7139,7 @@ export type WorkspaceEntryType = 'file' | 'directory' | 'symlink' | 'other';
 
 // @public
 export class WorkspaceError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
     constructor(message: string);
 }
 
diff --git a/api/mcp.api.md b/api/mcp.api.md
index 8e7076148..8966ef479 100644
--- a/api/mcp.api.md
+++ b/api/mcp.api.md
@@ -1128,6 +1128,7 @@ interface McpToolAnnotations {
 
 // @public
 export class McpToolError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
     constructor(message: string);
     readonly toolErrorKind: "mcp";
 }
diff --git a/api/tools.api.md b/api/tools.api.md
index 905421e24..dc2ff541b 100644
--- a/api/tools.api.md
+++ b/api/tools.api.md
@@ -1376,6 +1376,7 @@ interface McpToolAnnotations {
 
 // @public
 export class McpToolError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
     constructor(message: string);
     readonly toolErrorKind: "mcp";
 }
@@ -2864,6 +2865,7 @@ export type WorkspaceEntryType = 'file' | 'directory' | 'symlink' | 'other';
 
 // @public
 export class WorkspaceError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
     constructor(message: string);
 }
 
diff --git a/src/execution/propagatingToolError.ts b/src/execution/propagatingToolError.ts
index 4dfdea59e..a3634ec71 100644
--- a/src/execution/propagatingToolError.ts
+++ b/src/execution/propagatingToolError.ts
@@ -1,3 +1,5 @@
+import { brandClass, instanceOfOwnBrand, sharedWeakSet } from '../utils/brand';
+
 /**
  * Base class for tool errors that must NOT be swallowed by
  * executeToolCall()'s catch-all and converted into a conversational
@@ -15,9 +17,16 @@
  * its public home) so the executor's tool-call path and the delegation
  * core can both use it without a circular import.
  */
-export class PropagatingToolError extends Error {}
+export class PropagatingToolError extends Error {
+  /** `instanceof` also holds for one thrown by another loaded copy of the SDK (a `.cjs` tool next to the ESM CLI). */
+  static [Symbol.hasInstance](value: unknown): boolean {
+    return instanceOfOwnBrand(this, value);
+  }
+}
+brandClass(PropagatingToolError, 'PropagatingToolError');
 
-const propagatingErrors = new WeakSet<object>();
+/** Shared by every loaded copy of the SDK, like the class brand. */
+const propagatingErrors = sharedWeakSet('lousho.propagatingErrors');
 
 /**
  * Makes an error that is not a {@link PropagatingToolError} propagate like
diff --git a/src/providers/sharedChunks.test.ts b/src/providers/sharedChunks.test.ts
index 3cacef001..e3f17b4fb 100644
--- a/src/providers/sharedChunks.test.ts
+++ b/src/providers/sharedChunks.test.ts
@@ -11,6 +11,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { SDKError, ValidationError } from '../execution/errors';
 import { HookRegistry } from '../execution/hooks';
+import { isPropagatingToolError, PropagatingToolError } from '../execution/propagatingToolError';
+import { SubagentApprovalPause } from '../execution/subagentRuntime';
+import { McpToolError } from '../tools/mcp/result';
+import { WorkspaceError } from '../tools/workspace/paths';
 
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 const dist = (file: string) => JSON.stringify(path.join(REPO_ROOT, 'dist', file));
@@ -60,8 +64,20 @@ describe('shared chunks across package entries (LOU-D42)', () => {
           .filter((name) => !(Reflect.construct(esmRoot[name], ['x', 'y']) instanceof cjsRoot[name])),
         inherited: new esmRoot.CompactedLLMProviderError({ error: 'x', category: 'unknown', retryable: false }) instanceof cjsRoot.LLMProviderError,
         siblingNotConfused: new esmRoot.TimeoutError('x') instanceof cjsRoot.RateLimitError === false,
+        // Tool errors outside the SDKError family: a CJS tool's "do not retry" must stop the ESM executor's run.
+        toolErrors: ['PropagatingToolError', 'McpToolError', 'WorkspaceError']
+          .filter((name) => !(new cjsRoot[name]('x') instanceof esmRoot[name]) || new Error('x') instanceof esmRoot[name]),
       };`);
-    expect(result).toEqual({ distinctCopies: true, sdkError: true, hookRegistry: true, subclassNotConfused: true, subclasses: [], inherited: true, siblingNotConfused: true });
+    expect(result).toEqual({
+      distinctCopies: true,
+      sdkError: true,
+      hookRegistry: true,
+      subclassNotConfused: true,
+      subclasses: [],
+      inherited: true,
+      siblingNotConfused: true,
+      toolErrors: [],
+    });
   });
 
   it('brands answer instanceof for foreign-copy objects but not for unrelated ones', () => {
@@ -76,6 +92,12 @@ describe('shared chunks across package entries (LOU-D42)', () => {
     class MyValidationError extends ValidationError {}
     expect(new ValidationError('x')).not.toBeInstanceOf(MyValidationError);
     expect(new MyValidationError('x')).toBeInstanceOf(ValidationError);
+    expect(Object.create({ [Symbol.for('lousho.PropagatingToolError')]: true })).toBeInstanceOf(PropagatingToolError);
+    expect(isPropagatingToolError(Object.create({ [Symbol.for('lousho.PropagatingToolError')]: true }))).toBe(true);
+    expect(Object.create({ [Symbol.for('lousho.McpToolError')]: true })).toBeInstanceOf(McpToolError);
+    expect(Object.create({ [Symbol.for('lousho.WorkspaceError')]: true })).toBeInstanceOf(WorkspaceError);
+    expect(new Error('x')).not.toBeInstanceOf(PropagatingToolError);
+    expect(new PropagatingToolError('x')).not.toBeInstanceOf(SubagentApprovalPause);
   });
 
   it('every package.json exports target exists in dist/', () => {
diff --git a/src/tools/mcp/result.ts b/src/tools/mcp/result.ts
index 18918196c..73c78ec77 100644
--- a/src/tools/mcp/result.ts
+++ b/src/tools/mcp/result.ts
@@ -6,6 +6,7 @@
  * path reports it), otherwise a JSON-serializable result that keeps every
  * content part.
  */
+import { brandClass, instanceOfOwnBrand } from '../../utils/brand';
 
 /** A content part of an MCP tool result, in a typed, JSON-serializable form. */
 export type McpContentPart =
@@ -54,6 +55,11 @@ export interface McpStructuredToolResult {
  * where `message` is the server's text content.
  */
 export class McpToolError extends Error {
+  /** `instanceof` also holds for one thrown by another loaded copy of the SDK. */
+  static [Symbol.hasInstance](value: unknown): boolean {
+    return instanceOfOwnBrand(this, value);
+  }
+
   /** Read by the executor's shared tool-error shape (LOU-U14). */
   readonly toolErrorKind = 'mcp' as const;
 
@@ -62,6 +68,7 @@ export class McpToolError extends Error {
     this.name = 'McpToolError';
   }
 }
+brandClass(McpToolError, 'McpToolError');
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
diff --git a/src/tools/workspace/paths.ts b/src/tools/workspace/paths.ts
index d89929bbf..27d0fc75b 100644
--- a/src/tools/workspace/paths.ts
+++ b/src/tools/workspace/paths.ts
@@ -1,6 +1,7 @@
 /**
  * Workspace path validation shared by every provider and tool (LOU-X6).
  */
+import { brandClass, instanceOfOwnBrand } from '../../utils/brand';
 
 /**
  * A workspace operation was refused or failed (path outside the workspace,
@@ -9,11 +10,17 @@
  * (`{ error: 'WorkspaceError', toolName, message }`) instead of aborting the run.
  */
 export class WorkspaceError extends Error {
+  /** `instanceof` also holds for one thrown by another loaded copy of the SDK. */
+  static [Symbol.hasInstance](value: unknown): boolean {
+    return instanceOfOwnBrand(this, value);
+  }
+
   constructor(message: string) {
     super(message);
     this.name = 'WorkspaceError';
   }
 }
+brandClass(WorkspaceError, 'WorkspaceError');
 
 /** Windows reserved device names (`CON`, `NUL`, `COM1`, ...), with or without an extension. */
 const WINDOWS_DEVICE_NAME = /^(con|prn|aux|nul|com[0-9¹²³]|lpt[0-9¹²³])(\..*)?$/i;

From 21902f373c1b8ea7a38e597cd44417eb40f48aaa Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 12 Oct 2026 11:17:56 +0000
Subject: [PATCH 04/11] feat(cli): build agent modules, usable minimal/tools
 scaffolds, leaner docker image

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BG6n8mwoFq1jmay9zCPS6n
---
 docs/deployment.md                            |  26 +++-
 src/cli/build.test.ts                         |   4 +-
 src/cli/build.ts                              |   7 +-
 .../init/__snapshots__/templates.test.ts.snap | 147 +++++++++++++-----
 src/cli/init/sdkDependency.ts                 |  18 ++-
 src/cli/init/templates.test.ts                |  25 ++-
 src/cli/init/templates.ts                     |  27 +++-
 src/deploy/adapters/docker.test.ts            |  17 +-
 src/deploy/adapters/docker.ts                 |   6 +
 .../adapters/node-server-module.test.ts       |  88 +++++++++++
 src/deploy/adapters/node-server.test.ts       |   5 +-
 src/deploy/adapters/node-server.ts            | 129 +++++++++++----
 12 files changed, 399 insertions(+), 100 deletions(-)
 create mode 100644 src/deploy/adapters/node-server-module.test.ts

diff --git a/docs/deployment.md b/docs/deployment.md
index 66c00c5d7..34522bb2e 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -60,6 +60,26 @@ only a Worker-safe part of `@lousho/build-ai-agent`
 npx lousho build ./my-agent --target=cloudflare-worker
 ```
 
+## Agent modules
+
+The `node-server` and `docker` targets also build a `.ts`/`.js` module whose
+default (or `agent`) export is `createAgent()` options or a built agent: the
+same file `lousho dev src/agent.ts` serves, and what the minimal and tools
+scaffolds have (their `npm run build` runs this):
+
+```bash
+npx lousho build src/agent.ts --target=node-server
+node .lousho/build/node-server/dist/server.js
+```
+
+The generated `server.ts` imports the module, so tsup bundles it with its local
+imports and the SDK into an ESM `dist/server.js`. With an options export the
+server builds the agent with `LOUSHO_STORE` (unless the options name a
+`store`); an exported agent keeps its own. The build's `package.json` names
+the provider package when the module has a literal `model: '<provider>/...'`;
+add any other optional peer it needs yourself. The `cloudflare-worker` target
+does not build a module: use a spec or an agent directory.
+
 ## HTTP API
 
 Every target serves the same `/chat` protocol as `lousho dev`
@@ -203,10 +223,10 @@ browser-platform ES module; the build fails if any `node:` import ends up in the
 `dist/server.js` bundles the SDK but leaves its optional peers (the `peerDependenciesMeta`
 entries of its package.json: provider packages, `dockerode`, the MCP SDK, `prompts`, ...) external, so a build
 never needs one you do not use. The generated `package.json` already lists the
-ones the agent needs where the server runs - `@lousho/build-ai-agent` (at
-`^` the version that built it, a caret range, not an exact pin), the provider package the spec names (at the
+ones the agent needs where the server runs - the provider package the spec names (at the
 range pairing with the build's `ai` major, e.g. `@ai-sdk/openai` for an OpenAI
-agent) and `@modelcontextprotocol/sdk` when the spec has `mcpServers` - so the
+agent) and `@modelcontextprotocol/sdk` when the spec has `mcpServers` - and
+nothing else: `@lousho/build-ai-agent`, `ai` and `zod` are inside the bundle, so the
 docker image's `npm install --omit=dev` or a `npm install` next to the
 node-server output installs them. Anything else (an agent directory's own
 imports, `dockerode` for sandboxed tools) you add yourself; a code path that
diff --git a/src/cli/build.test.ts b/src/cli/build.test.ts
index 5f70e826c..2ee5341c5 100644
--- a/src/cli/build.test.ts
+++ b/src/cli/build.test.ts
@@ -80,7 +80,7 @@ describe('runBuild', () => {
     expect(await runBuild(['--target=stub', '--bogus'], captureIO())).toBe(2);
     const noAgent = captureIO();
     expect(await runBuild(['--target=stub'], noAgent)).toBe(2);
-    expect(noAgent.err.join('\n')).toContain('an agent path is required. Usage: lousho build <agent-dir|spec> --target=');
+    expect(noAgent.err.join('\n')).toContain('an agent path is required. Usage: lousho build <agent-dir|spec|agent.ts> --target=');
     expect(stubAdapterCalls).toEqual([]);
   });
 
@@ -169,7 +169,7 @@ describe('bin/lousho.js build (subprocess smoke test)', () => {
     expect(stdout).toContain('--traces[=dir]');
     expect(stdout).toContain('--drift');
     expect(stdout).toContain('--sdk-path');
-    expect(stdout).toContain('lousho build <agent-dir|spec> --target=<node-server|cloudflare-worker|docker>');
+    expect(stdout).toContain('lousho build <agent-dir|spec|agent.ts> --target=<node-server|cloudflare-worker|docker>');
   });
 
   it('dispatches `lousho build --target=stub` and runs scaffold, build, describe in order', () => {
diff --git a/src/cli/build.ts b/src/cli/build.ts
index 507185549..7f5771fba 100644
--- a/src/cli/build.ts
+++ b/src/cli/build.ts
@@ -29,11 +29,12 @@ export interface BuildArgs {
   help?: boolean;
 }
 
-const USAGE = 'Usage: lousho build <agent-dir|spec> --target=<node-server|cloudflare-worker|docker> [--out=<dir>]   (or --agent=<path>)';
+const USAGE = 'Usage: lousho build <agent-dir|spec|agent.ts> --target=<node-server|cloudflare-worker|docker> [--out=<dir>]   (or --agent=<path>)';
 
 const HELP = `${USAGE}
 
-Bundles an agent spec (agent.yaml / agent.json) or an agent directory for deployment.
+Bundles an agent spec (agent.yaml / agent.json), an agent directory or (node-server, docker) a .ts/.js
+module exporting createAgent() options or an agent, for deployment.
 
 Targets:
   node-server        a self-contained Node HTTP server (dist/server.js)
@@ -43,7 +44,7 @@ Targets:
 Options:
   --target=<name>    the deployment target (required)
   --out=<dir>        where to write the build (default: .lousho/build/<target>)
-  --agent=<path>     the spec file or agent directory (or pass it as the first argument)
+  --agent=<path>     the spec file, agent directory or module (or pass it as the first argument)
   -h, --help         show this help`;
 
 const SPEC: CommandSpec = {
diff --git a/src/cli/init/__snapshots__/templates.test.ts.snap b/src/cli/init/__snapshots__/templates.test.ts.snap
index 2c4d371db..859457f9a 100644
--- a/src/cli/init/__snapshots__/templates.test.ts.snap
+++ b/src/cli/init/__snapshots__/templates.test.ts.snap
@@ -1,7 +1,7 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
 exports[`renderProject > snapshot: anthropic / minimal agent.ts 1`] = `
-"import { createAgent, defineTool, type LLMProvider } from '@lousho/build-ai-agent';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@lousho/build-ai-agent';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -17,20 +17,25 @@ export const currentTime = defineTool({
 const instructions = 'You are a helpful assistant. Use your tools when they help.';
 const tools = [currentTime];
 
+/**
+ * The agent's options. The default export is what \`lousho dev src/agent.ts\`
+ * (and \`lousho chat\`, \`mcp\`, \`acp\`, \`build\`) serve.
+ */
+const config: CreateAgentConfig = { model: 'anthropic/claude-sonnet-4-5', instructions, tools };
+export default config;
+
 /**
  * The agent. \`createAgent({ model, instructions })\` is the whole idea; the
  * optional \`provider\` lets tests swap in a scripted model (see agent.test.ts).
  */
 export function buildAgent(provider?: LLMProvider) {
-  return provider
-    ? createAgent({ provider, instructions, tools })
-    : createAgent({ model: 'anthropic/claude-sonnet-4-5', instructions, tools });
+  return provider ? createAgent({ provider, instructions, tools }) : createAgent(config);
 }
 "
 `;
 
 exports[`renderProject > snapshot: anthropic / tools agent.ts 1`] = `
-"import { createAgent, defineTool, type LLMProvider } from '@lousho/build-ai-agent';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@lousho/build-ai-agent';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -62,14 +67,19 @@ export const wordCount = defineTool({
 const instructions = 'You are a helpful assistant. Use your tools when they help.';
 const tools = [currentTime, rollDie, wordCount];
 
+/**
+ * The agent's options. The default export is what \`lousho dev src/agent.ts\`
+ * (and \`lousho chat\`, \`mcp\`, \`acp\`, \`build\`) serve.
+ */
+const config: CreateAgentConfig = { model: 'anthropic/claude-sonnet-4-5', instructions, tools };
+export default config;
+
 /**
  * The agent. \`createAgent({ model, instructions })\` is the whole idea; the
  * optional \`provider\` lets tests swap in a scripted model (see agent.test.ts).
  */
 export function buildAgent(provider?: LLMProvider) {
-  return provider
-    ? createAgent({ provider, instructions, tools })
-    : createAgent({ model: 'anthropic/claude-sonnet-4-5', instructions, tools });
+  return provider ? createAgent({ provider, instructions, tools }) : createAgent(config);
 }
 "
 `;
@@ -82,9 +92,11 @@ exports[`renderProject > snapshot: minimal package.json 1`] = `
   "type": "module",
   "scripts": {
     "dev": "tsx src/index.ts",
+    "dev:ui": "lousho dev src/agent.ts",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
-    "doctor": "lousho doctor"
+    "doctor": "lousho doctor",
+    "build": "lousho build src/agent.ts --target=node-server"
   },
   "dependencies": {
     "@ai-sdk/openai": "^4.0.0",
@@ -94,8 +106,10 @@ exports[`renderProject > snapshot: minimal package.json 1`] = `
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0",
+    "vite": "^8.0.0",
     "vitest": "^5.0.3"
   },
   "engines": {
@@ -106,7 +120,7 @@ exports[`renderProject > snapshot: minimal package.json 1`] = `
 `;
 
 exports[`renderProject > snapshot: ollama / minimal agent.ts 1`] = `
-"import { createAgent, defineTool, type LLMProvider } from '@lousho/build-ai-agent';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@lousho/build-ai-agent';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -122,20 +136,25 @@ export const currentTime = defineTool({
 const instructions = 'You are a helpful assistant. Use your tools when they help.';
 const tools = [currentTime];
 
+/**
+ * The agent's options. The default export is what \`lousho dev src/agent.ts\`
+ * (and \`lousho chat\`, \`mcp\`, \`acp\`, \`build\`) serve.
+ */
+const config: CreateAgentConfig = { model: 'ollama/llama3', instructions, tools };
+export default config;
+
 /**
  * The agent. \`createAgent({ model, instructions })\` is the whole idea; the
  * optional \`provider\` lets tests swap in a scripted model (see agent.test.ts).
  */
 export function buildAgent(provider?: LLMProvider) {
-  return provider
-    ? createAgent({ provider, instructions, tools })
-    : createAgent({ model: 'ollama/llama3', instructions, tools });
+  return provider ? createAgent({ provider, instructions, tools }) : createAgent(config);
 }
 "
 `;
 
 exports[`renderProject > snapshot: ollama / tools agent.ts 1`] = `
-"import { createAgent, defineTool, type LLMProvider } from '@lousho/build-ai-agent';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@lousho/build-ai-agent';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -167,20 +186,25 @@ export const wordCount = defineTool({
 const instructions = 'You are a helpful assistant. Use your tools when they help.';
 const tools = [currentTime, rollDie, wordCount];
 
+/**
+ * The agent's options. The default export is what \`lousho dev src/agent.ts\`
+ * (and \`lousho chat\`, \`mcp\`, \`acp\`, \`build\`) serve.
+ */
+const config: CreateAgentConfig = { model: 'ollama/llama3', instructions, tools };
+export default config;
+
 /**
  * The agent. \`createAgent({ model, instructions })\` is the whole idea; the
  * optional \`provider\` lets tests swap in a scripted model (see agent.test.ts).
  */
 export function buildAgent(provider?: LLMProvider) {
-  return provider
-    ? createAgent({ provider, instructions, tools })
-    : createAgent({ model: 'ollama/llama3', instructions, tools });
+  return provider ? createAgent({ provider, instructions, tools }) : createAgent(config);
 }
 "
 `;
 
 exports[`renderProject > snapshot: openai / minimal agent.ts 1`] = `
-"import { createAgent, defineTool, type LLMProvider } from '@lousho/build-ai-agent';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@lousho/build-ai-agent';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -196,20 +220,25 @@ export const currentTime = defineTool({
 const instructions = 'You are a helpful assistant. Use your tools when they help.';
 const tools = [currentTime];
 
+/**
+ * The agent's options. The default export is what \`lousho dev src/agent.ts\`
+ * (and \`lousho chat\`, \`mcp\`, \`acp\`, \`build\`) serve.
+ */
+const config: CreateAgentConfig = { model: 'openai/gpt-4o-mini', instructions, tools };
+export default config;
+
 /**
  * The agent. \`createAgent({ model, instructions })\` is the whole idea; the
  * optional \`provider\` lets tests swap in a scripted model (see agent.test.ts).
  */
 export function buildAgent(provider?: LLMProvider) {
-  return provider
-    ? createAgent({ provider, instructions, tools })
-    : createAgent({ model: 'openai/gpt-4o-mini', instructions, tools });
+  return provider ? createAgent({ provider, instructions, tools }) : createAgent(config);
 }
 "
 `;
 
 exports[`renderProject > snapshot: openai / tools agent.ts 1`] = `
-"import { createAgent, defineTool, type LLMProvider } from '@lousho/build-ai-agent';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@lousho/build-ai-agent';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -241,20 +270,25 @@ export const wordCount = defineTool({
 const instructions = 'You are a helpful assistant. Use your tools when they help.';
 const tools = [currentTime, rollDie, wordCount];
 
+/**
+ * The agent's options. The default export is what \`lousho dev src/agent.ts\`
+ * (and \`lousho chat\`, \`mcp\`, \`acp\`, \`build\`) serve.
+ */
+const config: CreateAgentConfig = { model: 'openai/gpt-4o-mini', instructions, tools };
+export default config;
+
 /**
  * The agent. \`createAgent({ model, instructions })\` is the whole idea; the
  * optional \`provider\` lets tests swap in a scripted model (see agent.test.ts).
  */
 export function buildAgent(provider?: LLMProvider) {
-  return provider
-    ? createAgent({ provider, instructions, tools })
-    : createAgent({ model: 'openai/gpt-4o-mini', instructions, tools });
+  return provider ? createAgent({ provider, instructions, tools }) : createAgent(config);
 }
 "
 `;
 
 exports[`renderProject > snapshot: openrouter / minimal agent.ts 1`] = `
-"import { createAgent, defineTool, type LLMProvider } from '@lousho/build-ai-agent';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@lousho/build-ai-agent';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -270,20 +304,25 @@ export const currentTime = defineTool({
 const instructions = 'You are a helpful assistant. Use your tools when they help.';
 const tools = [currentTime];
 
+/**
+ * The agent's options. The default export is what \`lousho dev src/agent.ts\`
+ * (and \`lousho chat\`, \`mcp\`, \`acp\`, \`build\`) serve.
+ */
+const config: CreateAgentConfig = { model: 'openrouter/openai/gpt-4o-mini', instructions, tools };
+export default config;
+
 /**
  * The agent. \`createAgent({ model, instructions })\` is the whole idea; the
  * optional \`provider\` lets tests swap in a scripted model (see agent.test.ts).
  */
 export function buildAgent(provider?: LLMProvider) {
-  return provider
-    ? createAgent({ provider, instructions, tools })
-    : createAgent({ model: 'openrouter/openai/gpt-4o-mini', instructions, tools });
+  return provider ? createAgent({ provider, instructions, tools }) : createAgent(config);
 }
 "
 `;
 
 exports[`renderProject > snapshot: openrouter / tools agent.ts 1`] = `
-"import { createAgent, defineTool, type LLMProvider } from '@lousho/build-ai-agent';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@lousho/build-ai-agent';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -315,20 +354,25 @@ export const wordCount = defineTool({
 const instructions = 'You are a helpful assistant. Use your tools when they help.';
 const tools = [currentTime, rollDie, wordCount];
 
+/**
+ * The agent's options. The default export is what \`lousho dev src/agent.ts\`
+ * (and \`lousho chat\`, \`mcp\`, \`acp\`, \`build\`) serve.
+ */
+const config: CreateAgentConfig = { model: 'openrouter/openai/gpt-4o-mini', instructions, tools };
+export default config;
+
 /**
  * The agent. \`createAgent({ model, instructions })\` is the whole idea; the
  * optional \`provider\` lets tests swap in a scripted model (see agent.test.ts).
  */
 export function buildAgent(provider?: LLMProvider) {
-  return provider
-    ? createAgent({ provider, instructions, tools })
-    : createAgent({ model: 'openrouter/openai/gpt-4o-mini', instructions, tools });
+  return provider ? createAgent({ provider, instructions, tools }) : createAgent(config);
 }
 "
 `;
 
 exports[`renderProject > snapshot: pi / minimal agent.ts 1`] = `
-"import { createAgent, defineTool, type LLMProvider } from '@lousho/build-ai-agent';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@lousho/build-ai-agent';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -344,20 +388,25 @@ export const currentTime = defineTool({
 const instructions = 'You are a helpful assistant. Use your tools when they help.';
 const tools = [currentTime];
 
+/**
+ * The agent's options. The default export is what \`lousho dev src/agent.ts\`
+ * (and \`lousho chat\`, \`mcp\`, \`acp\`, \`build\`) serve.
+ */
+const config: CreateAgentConfig = { model: 'pi/openrouter/openai/gpt-4o-mini', instructions, tools };
+export default config;
+
 /**
  * The agent. \`createAgent({ model, instructions })\` is the whole idea; the
  * optional \`provider\` lets tests swap in a scripted model (see agent.test.ts).
  */
 export function buildAgent(provider?: LLMProvider) {
-  return provider
-    ? createAgent({ provider, instructions, tools })
-    : createAgent({ model: 'pi/openrouter/openai/gpt-4o-mini', instructions, tools });
+  return provider ? createAgent({ provider, instructions, tools }) : createAgent(config);
 }
 "
 `;
 
 exports[`renderProject > snapshot: pi / tools agent.ts 1`] = `
-"import { createAgent, defineTool, type LLMProvider } from '@lousho/build-ai-agent';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@lousho/build-ai-agent';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -389,14 +438,19 @@ export const wordCount = defineTool({
 const instructions = 'You are a helpful assistant. Use your tools when they help.';
 const tools = [currentTime, rollDie, wordCount];
 
+/**
+ * The agent's options. The default export is what \`lousho dev src/agent.ts\`
+ * (and \`lousho chat\`, \`mcp\`, \`acp\`, \`build\`) serve.
+ */
+const config: CreateAgentConfig = { model: 'pi/openrouter/openai/gpt-4o-mini', instructions, tools };
+export default config;
+
 /**
  * The agent. \`createAgent({ model, instructions })\` is the whole idea; the
  * optional \`provider\` lets tests swap in a scripted model (see agent.test.ts).
  */
 export function buildAgent(provider?: LLMProvider) {
-  return provider
-    ? createAgent({ provider, instructions, tools })
-    : createAgent({ model: 'pi/openrouter/openai/gpt-4o-mini', instructions, tools });
+  return provider ? createAgent({ provider, instructions, tools }) : createAgent(config);
 }
 "
 `;
@@ -409,9 +463,11 @@ exports[`renderProject > snapshot: tools package.json 1`] = `
   "type": "module",
   "scripts": {
     "dev": "tsx src/index.ts",
+    "dev:ui": "lousho dev src/agent.ts",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
-    "doctor": "lousho doctor"
+    "doctor": "lousho doctor",
+    "build": "lousho build src/agent.ts --target=node-server"
   },
   "dependencies": {
     "@ai-sdk/openai": "^4.0.0",
@@ -421,8 +477,10 @@ exports[`renderProject > snapshot: tools package.json 1`] = `
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0",
+    "vite": "^8.0.0",
     "vitest": "^5.0.3"
   },
   "engines": {
@@ -442,7 +500,8 @@ exports[`renderProject > snapshot: yaml package.json 1`] = `
     "dev": "lousho dev agent.yaml",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
-    "doctor": "lousho doctor agent.yaml"
+    "doctor": "lousho doctor agent.yaml",
+    "build": "lousho build agent.yaml --target=node-server"
   },
   "dependencies": {
     "@ai-sdk/openai": "^4.0.0",
@@ -452,8 +511,10 @@ exports[`renderProject > snapshot: yaml package.json 1`] = `
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0",
+    "vite": "^8.0.0",
     "vitest": "^5.0.3"
   },
   "engines": {
diff --git a/src/cli/init/sdkDependency.ts b/src/cli/init/sdkDependency.ts
index 8574514dd..42d9b5e8b 100644
--- a/src/cli/init/sdkDependency.ts
+++ b/src/cli/init/sdkDependency.ts
@@ -29,17 +29,23 @@ function packSdk(sdkRoot: string, dest: string): string {
   return output.trim().split(/\r?\n/).pop()!.trim();
 }
 
+/** Why `sdkPath` cannot be an `--sdk-path` (missing, or a file that is not a .tgz), or undefined when it can. */
+export function sdkPathProblem(sdkPath: string): string | undefined {
+  const resolved = path.resolve(sdkPath);
+  if (!fs.existsSync(resolved)) return `lousho init: --sdk-path '${sdkPath}' does not exist. Pass an SDK checkout directory or a packed .tgz file.`;
+  if (!fs.statSync(resolved).isDirectory() && !isTarball(resolved)) {
+    return `lousho init: --sdk-path '${sdkPath}' is a file but not a .tgz tarball. Pass a checkout directory or a packed .tgz file.`;
+  }
+  return undefined;
+}
+
 /** Puts a tarball of the SDK at `sdkPath` (a checkout or a .tgz) into `projectDir`; returns its file name. */
 function vendorSdk(sdkPath: string, projectDir: string): string {
   const resolved = path.resolve(sdkPath);
-  if (!fs.existsSync(resolved)) {
-    throw new ConfigurationError(`lousho init: --sdk-path '${sdkPath}' does not exist. Pass an SDK checkout directory or a packed .tgz file.`, 'sdk-path');
-  }
+  const problem = sdkPathProblem(sdkPath);
+  if (problem !== undefined) throw new ConfigurationError(problem, 'sdk-path');
   fs.mkdirSync(projectDir, { recursive: true });
   if (fs.statSync(resolved).isDirectory()) return packSdk(resolved, projectDir);
-  if (!isTarball(resolved)) {
-    throw new ConfigurationError(`lousho init: --sdk-path '${sdkPath}' is a file but not a .tgz tarball. Pass a checkout directory or a packed .tgz file.`, 'sdk-path');
-  }
   fs.copyFileSync(resolved, path.join(projectDir, path.basename(resolved)));
   return path.basename(resolved);
 }
diff --git a/src/cli/init/templates.test.ts b/src/cli/init/templates.test.ts
index c23993e4c..7b9d0f29d 100644
--- a/src/cli/init/templates.test.ts
+++ b/src/cli/init/templates.test.ts
@@ -76,7 +76,14 @@ describe('renderProject', () => {
     '%s / %s: agent.ts uses createAgent + defineTool and the test uses mockModel',
     (provider, template) => {
       const files = renderProject(config(provider, template));
-      expect(files['src/agent.ts']).toContain("import { createAgent, defineTool, type LLMProvider } from '@lousho/build-ai-agent';");
+      expect(files['src/agent.ts']).toContain(
+        "import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@lousho/build-ai-agent';"
+      );
+      // The default export is what `lousho dev|chat|mcp|acp|build src/agent.ts` load.
+      expect(files['src/agent.ts']).toContain('export default config;');
+      const pkg = JSON.parse(files['package.json']!);
+      expect(pkg.scripts['dev:ui']).toBe('lousho dev src/agent.ts');
+      expect(pkg.scripts.build).toBe('lousho build src/agent.ts --target=node-server');
       expect(files['src/agent.ts']).toMatch(new RegExp(`model: '${provider}/[^']+'`));
       expect(files['src/agent.ts']).toContain('instructions');
       expect(files['src/agent.test.ts']).toContain("import { mockModel } from '@lousho/build-ai-agent/testing';");
@@ -115,6 +122,22 @@ describe('renderProject', () => {
     expect(files['src/agent.ts']).toBeUndefined();
   });
 
+  it.each(TEMPLATES)('the %s template can build (tsup) and test under yarn 1, which skips peers (vite)', (template) => {
+    const pkg = JSON.parse(renderProject(config('openai', template))['package.json']!);
+    expect(pkg.devDependencies).toMatchObject({ tsup: expect.any(String), vite: expect.any(String) });
+    expect(pkg.scripts.build).toMatch(/^lousho build \S+ --target=node-server$/);
+  });
+
+  it('the README lists three next commands and counts the tools', () => {
+    for (const template of TEMPLATES) {
+      const readme = renderProject(config('openai', template))['README.md']!;
+      const block = /## Next 3 commands\n\n```bash\n([\s\S]*?)```/.exec(readme)![1]!;
+      expect(block.split('\n').filter((line) => /^npm run /.test(line))).toHaveLength(3);
+    }
+    expect(renderProject(config('openai', 'tools'))['README.md']).toContain('the agent and three example tools');
+    expect(renderProject(config('openai', 'minimal'))['README.md']).toContain('the agent and an example tool');
+  });
+
   it('the yaml template test imports only public SDK entry points', () => {
     const test = renderProject(config('openai', 'yaml'))['src/agent.test.ts']!;
     const specifiers = [...test.matchAll(/from '([^']+)'/g)].map((m) => m[1]);
diff --git a/src/cli/init/templates.ts b/src/cli/init/templates.ts
index bea26f6ef..f1d6a0e42 100644
--- a/src/cli/init/templates.ts
+++ b/src/cli/init/templates.ts
@@ -66,9 +66,13 @@ function packageJson(config: ProjectConfig): string {
     scripts: {
       // `lousho dev` loads .env itself, and so does src/index.ts (tsx --env-file-if-exists prints "not found" twice).
       dev: yaml ? 'lousho dev agent.yaml' : 'tsx src/index.ts',
+      // The chat UI with hot reload; it serves src/agent.ts's default export.
+      ...(yaml ? {} : { 'dev:ui': 'lousho dev src/agent.ts' }),
       test: 'vitest run',
       typecheck: 'tsc --noEmit',
       doctor: yaml ? 'lousho doctor agent.yaml' : 'lousho doctor',
+      // A self-contained HTTP server in .lousho/build/node-server (--target=docker adds a Dockerfile).
+      build: `lousho build ${yaml ? 'agent.yaml' : 'src/agent.ts'} --target=node-server`,
     },
     dependencies: sortKeys({
       '@lousho/build-ai-agent': config.sdkDependency,
@@ -77,8 +81,12 @@ function packageJson(config: ProjectConfig): string {
     }),
     devDependencies: {
       '@types/node': '^22.0.0',
+      // `lousho build` bundles with tsup.
+      tsup: '^8.0.0',
       tsx: '^4.19.0',
       typescript: '^5.6.0',
+      // vitest's peer: yarn 1 does not install peers, so it is listed.
+      vite: '^8.0.0',
       vitest: '^5.0.3',
     },
     engines: { node: '>=22.19.0' },
@@ -140,7 +148,7 @@ function toolNames(template: Template): string[] {
 function agentSource(config: ProjectConfig): string {
   const info = providerInfo(config.provider);
   const extra = config.template === 'tools' ? EXTRA_TOOLS : '';
-  return `import { createAgent, defineTool, type LLMProvider } from '@lousho/build-ai-agent';
+  return `import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@lousho/build-ai-agent';
 import { z } from 'zod';
 
 ${TIME_TOOL}${extra}
@@ -148,14 +156,19 @@ ${TIME_TOOL}${extra}
 const instructions = 'You are a helpful assistant. Use your tools when they help.';
 const tools = [${toolNames(config.template).join(', ')}];
 
+/**
+ * The agent's options. The default export is what \`lousho dev src/agent.ts\`
+ * (and \`lousho chat\`, \`mcp\`, \`acp\`, \`build\`) serve.
+ */
+const config: CreateAgentConfig = { model: '${config.provider}/${info.defaultModel}', instructions, tools };
+export default config;
+
 /**
  * The agent. \`createAgent({ model, instructions })\` is the whole idea; the
  * optional \`provider\` lets tests swap in a scripted model (see agent.test.ts).
  */
 export function buildAgent(provider?: LLMProvider) {
-  return provider
-    ? createAgent({ provider, instructions, tools })
-    : createAgent({ model: '${config.provider}/${info.defaultModel}', instructions, tools });
+  return provider ? createAgent({ provider, instructions, tools }) : createAgent(config);
 }
 `;
 }
@@ -292,9 +305,10 @@ function readme(config: ProjectConfig): string {
   const pm = config.packageManager;
   const info = providerInfo(config.provider);
   const yaml = config.template === 'yaml';
+  const tools = config.template === 'tools' ? 'three example tools' : 'an example tool';
   const files = yaml
     ? '- `agent.yaml` - the agent: prompt, provider and tools\n- `src/agent.test.ts` - checks the spec loads, offline'
-    : '- `src/agent.ts` - the agent and an example tool\n- `src/agent.test.ts` - tests with a scripted model, offline\n- `src/index.ts` - a tiny terminal chat';
+    : `- \`src/agent.ts\` - the agent and ${tools}\n- \`src/agent.test.ts\` - tests with a scripted model, offline\n- \`src/index.ts\` - a tiny terminal chat`;
   return `# ${config.name}
 
 An agent built with [@lousho/build-ai-agent](https://github.com/LinuxDevil/agent-sdk).
@@ -305,8 +319,11 @@ An agent built with [@lousho/build-ai-agent](https://github.com/LinuxDevil/agent
 # copy .env.example to .env (cp on macOS/Linux, copy on Windows), then put your ${info.envKey} in it${yaml ? ' (or export it)' : ''}
 ${run(pm, 'dev')}${yaml ? '          # chat UI with hot reload' : '          # chat with the agent in your terminal'}
 ${run(pm, 'test')}         # offline tests, no API key needed
+${yaml ? `${run(pm, 'build')}        # a deployable server in .lousho/build/node-server` : `${run(pm, 'dev:ui')}       # chat UI with hot reload (lousho dev)`}
 \`\`\`
 
+\`${run(pm, 'build')}\` bundles the agent into a self-contained HTTP server (\`node .lousho/build/node-server/dist/server.js\`); \`lousho build ${yaml ? 'agent.yaml' : 'src/agent.ts'} --target=docker\` adds a Dockerfile.
+
 Run \`${run(pm, 'doctor')}\` if something does not work: it checks Node, packages and API keys.
 
 ## What is here
diff --git a/src/deploy/adapters/docker.test.ts b/src/deploy/adapters/docker.test.ts
index 0d0709a3b..58f531d86 100644
--- a/src/deploy/adapters/docker.test.ts
+++ b/src/deploy/adapters/docker.test.ts
@@ -56,6 +56,8 @@ describe('DockerAdapter', () => {
     // ...plus the Dockerfile.
     const dockerfile = fs.readFileSync(path.join(outDir, 'Dockerfile'), 'utf8');
     expect(dockerfile).toBe(DOCKERFILE);
+    // A local .env or a packed SDK tarball in the build folder (--out=.) never reaches the image.
+    expect(fs.readFileSync(path.join(outDir, '.dockerignore'), 'utf8').split('\n')).toEqual(expect.arrayContaining(['.env', '.env.*', '*.tgz']));
     const lines = dockerfile.split('\n');
     expect(lines).toContain('FROM node:22-slim');
     expect(lines).toContain('WORKDIR /app');
@@ -67,6 +69,8 @@ describe('DockerAdapter', () => {
     expect(lines).toContain('USER node');
     expect(lines).toContain('EXPOSE 3000');
     expect(lines).toContain('CMD ["node", "dist/server.js"]');
+    // The slim image has no curl: the health check probes /health with Node.
+    expect(DOCKERFILE).toMatch(/^HEALTHCHECK .*\\\n\s+CMD \["node", "-e", "fetch\('http:\/\/127\.0\.0\.1:' \+ \(process\.env\.PORT \|\| 3000\) \+ '\/health'\)/m);
     // Container needs an explicit all-interfaces opt-in to be reachable via -p.
     expect(lines).toContain('ENV HOST=0.0.0.0');
   });
@@ -83,21 +87,20 @@ describe('DockerAdapter', () => {
 
     const manifest = JSON.parse(fs.readFileSync(path.join(outDir, 'package.json'), 'utf8'));
     const sdk = JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', '..', 'package.json'), 'utf8'));
-    // The image's `npm install --omit=dev` must install what the bundle left
-    // external; `^` lets a scaffold from an unpublished dev version resolve.
-    expect(manifest.dependencies['@lousho/build-ai-agent']).toBe(`^${sdk.version}`);
+    // The image's `npm install --omit=dev` installs only what the bundle left
+    // external: not the SDK, which dist/server.js bundles.
+    expect(manifest.dependencies['@lousho/build-ai-agent']).toBeUndefined();
     expect(manifest.dependencies['@ai-sdk/openai']).toBeDefined();
     expect(manifest.dependencies['@modelcontextprotocol/sdk']).toBe(sdk.peerDependencies['@modelcontextprotocol/sdk']);
     expect(manifest.scripts.start).toBe('node dist/server.js');
   });
 
-  it('a mock-provider spec ships only the SDK dependency', async () => {
+  it('a mock-provider spec ships no dependency', async () => {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'lousho-docker-'));
     const outDir = path.join(dir, 'out');
     await DockerAdapter.scaffold(writeSpec(dir), outDir);
     const manifest = JSON.parse(fs.readFileSync(path.join(outDir, 'package.json'), 'utf8'));
-    const sdk = JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', '..', 'package.json'), 'utf8'));
-    expect(manifest.dependencies).toEqual({ '@lousho/build-ai-agent': `^${sdk.version}` });
+    expect(manifest.dependencies).toEqual({});
   });
 
   it('an agent directory ships the provider peer its data config names', async () => {
@@ -118,7 +121,7 @@ describe('DockerAdapter', () => {
     expect(deps['@modelcontextprotocol/sdk']).toBeUndefined();
     expect(deployDependencies('nope')).toEqual(deployDependencies());
     const ollamaMcp = deployDependencies('ollama', true);
-    expect(Object.keys(ollamaMcp)).toHaveLength(3);
+    expect(Object.keys(ollamaMcp)).toHaveLength(2);
     expect(Object.keys(ollamaMcp).some((k) => k.startsWith('ollama-ai-provider'))).toBe(true);
     expect(ollamaMcp['@modelcontextprotocol/sdk']).toBeDefined();
   });
diff --git a/src/deploy/adapters/docker.ts b/src/deploy/adapters/docker.ts
index 44c83dcfd..af8fc7ca8 100644
--- a/src/deploy/adapters/docker.ts
+++ b/src/deploy/adapters/docker.ts
@@ -32,12 +32,18 @@ USER node
 ENV HOST=0.0.0.0
 ENV PORT=3000
 EXPOSE 3000
+# The slim image has no curl: Node's fetch probes GET /health.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \\
+  CMD ["node", "-e", "fetch('http://127.0.0.1:' + (process.env.PORT || 3000) + '/health').then((r) => process.exit(r.ok ? 0 : 1), () => process.exit(1))"]
 CMD ["node", "dist/server.js"]
 `;
 
 const DOCKERIGNORE = `node_modules
 server.ts
 agent.config.js
+.env
+.env.*
+*.tgz
 `;
 
 export const DockerAdapter: DeploymentAdapter = {
diff --git a/src/deploy/adapters/node-server-module.test.ts b/src/deploy/adapters/node-server-module.test.ts
new file mode 100644
index 000000000..2e87fea1a
--- /dev/null
+++ b/src/deploy/adapters/node-server-module.test.ts
@@ -0,0 +1,88 @@
+/**
+ * The node-server (and docker) targets build a .ts agent module - the file
+ * `lousho dev src/agent.ts` serves, as create-lousho-agent scaffolds it: a
+ * default export holding createAgent() options. scaffold + tsup build + the
+ * built dist/server.js as a real subprocess; only the LLM is the mock provider.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { NodeServerAdapter, loadAgentSpecForDeploy } from './node-server';
+import { withBuildLock } from '../buildLock.testkit';
+
+const AGENT_TS = `import { createMockProvider, type CreateAgentConfig } from '@lousho/build-ai-agent';
+
+const instructions: string = 'You are a deployed agent module.';
+const config: CreateAgentConfig = { instructions, provider: createMockProvider({ name: 'mock', responses: ['module pong'] }) };
+export default config;
+`;
+
+/** Starts dist/server.js on a free port; resolves once it listens. */
+function startServer(outDir: string): Promise<{ stop: () => void; port: number }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, ['dist/server.js', '--port=0'], { cwd: outDir, stdio: ['ignore', 'pipe', 'pipe'] });
+    let output = '';
+    const timer = setTimeout(() => reject(new Error(`server did not start: ${output}`)), 15_000);
+    child.stdout.on('data', (chunk) => {
+      output += chunk;
+      const match = /listening on http:\/\/[^:]+:(\d+)/.exec(output);
+      if (!match) return;
+      clearTimeout(timer);
+      resolve({ stop: () => child.kill(), port: Number(match[1]) });
+    });
+    child.stderr.on('data', (chunk) => (output += chunk));
+    child.on('exit', (code) => reject(new Error(`server exited early (code ${code}): ${output}`)));
+  });
+}
+
+describe('NodeServerAdapter with an agent module', () => {
+  let root: string;
+  let outDir: string;
+
+  beforeAll(async () => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'lousho-agent-module-'));
+    fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name: 'module-project', type: 'module' }));
+    fs.mkdirSync(path.join(root, 'src'));
+    fs.writeFileSync(path.join(root, 'src', 'agent.ts'), AGENT_TS);
+    outDir = path.join(root, 'out');
+    await NodeServerAdapter.scaffold(path.join(root, 'src', 'agent.ts'), outDir);
+    await withBuildLock(() => NodeServerAdapter.build(outDir));
+  }, 120_000);
+  afterAll(() => {
+    if (root) fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it('generates a server.ts that imports the module, and a package.json named after the project', () => {
+    expect(fs.readFileSync(path.join(outDir, 'server.ts'), 'utf8')).toContain('import * as agentModule from');
+    expect(JSON.parse(fs.readFileSync(path.join(outDir, 'package.json'), 'utf8'))).toMatchObject({ name: 'module-project', dependencies: {} });
+  });
+
+  it('the built server answers /chat with the module agent', async () => {
+    const { stop, port } = await startServer(outDir);
+    try {
+      expect((await fetch(`http://127.0.0.1:${port}/health`)).status).toBe(200);
+      const res = await fetch(`http://127.0.0.1:${port}/chat`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ message: 'hi' }),
+      });
+      expect(res.status).toBe(200);
+      expect(((await res.json()) as { text: string }).text).toBe('module pong');
+    } finally {
+      stop();
+    }
+  }, 30_000);
+
+  it('a later spec build in the same out dir is not mistaken for the module', async () => {
+    const spec = path.join(root, 'spec.json');
+    fs.writeFileSync(spec, JSON.stringify({ name: 's', prompt: 'p', provider: { type: 'mock', model: 'm' } }));
+    await NodeServerAdapter.scaffold(spec, outDir);
+    expect(fs.existsSync(path.join(outDir, 'agent-module.json'))).toBe(false);
+  });
+
+  it('targets that only build specs say which ones build a module', () => {
+    expect(() => loadAgentSpecForDeploy(path.join(root, 'src', 'agent.ts'))).toThrow(/--target=node-server and --target=docker build an agent module/);
+  });
+});
diff --git a/src/deploy/adapters/node-server.test.ts b/src/deploy/adapters/node-server.test.ts
index c7724228a..d9aff50f8 100644
--- a/src/deploy/adapters/node-server.test.ts
+++ b/src/deploy/adapters/node-server.test.ts
@@ -63,7 +63,10 @@ describe('NodeServerAdapter', () => {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'lousho-node-server-bad-'));
     const tsPath = path.join(dir, 'agent.ts');
     fs.writeFileSync(tsPath, 'export {}');
-    expect(() => loadAgentSpecForDeploy(tsPath)).toThrow(/expected an AgentSpec .yaml\/.yml\/.json/);
+    expect(() => loadAgentSpecForDeploy(tsPath)).toThrow(/builds an AgentSpec .yaml\/.yml\/.json file or an agent directory/);
+    const txtPath = path.join(dir, 'agent.txt');
+    fs.writeFileSync(txtPath, '');
+    expect(() => loadAgentSpecForDeploy(txtPath)).toThrow(/expected an AgentSpec .yaml\/.yml\/.json file/);
     expect(() => loadAgentSpecForDeploy('')).toThrow(/an agent path is required/);
     const bad = writeSpec(dir, { name: 'x', provider: { type: 'mock', model: 'm' } });
     expect(() => loadAgentSpecForDeploy(bad)).toThrow(/'prompt'/);
diff --git a/src/deploy/adapters/node-server.ts b/src/deploy/adapters/node-server.ts
index 827e7300b..55c7379b7 100644
--- a/src/deploy/adapters/node-server.ts
+++ b/src/deploy/adapters/node-server.ts
@@ -9,12 +9,14 @@
  *                        GET /health plus the `lousho dev` /chat API (sessions,
  *                        SSE, approvals; LOU-D14), bearer auth via LOUSHO_API_TOKEN
  *     - package.json     manifest with a `start` script and the runtime
- *                        dependencies the built server needs (the SDK, the
- *                        spec's provider peer, the MCP SDK when mcpServers
- *                        are configured) - the docker image's `npm install`
+ *                        dependencies the built server needs (the spec's
+ *                        provider peer, the MCP SDK when mcpServers are
+ *                        configured) - the docker image's `npm install`
  *   An agent directory (LOU-P8.2, see node-server-dir.ts) is accepted in place
  *   of a spec: server.ts then resolves it with resolveAgentDir() and starts
- *   its schedules and mounts its channels.
+ *   its schedules and mounts its channels. So is a .ts/.js module whose
+ *   default (or `agent`) export is a createAgent() config or a built agent,
+ *   the same module `lousho dev` serves: server.ts imports it.
  * build():    bundles server.ts (+ agent.config.js + the SDK runtime) with
  *             tsup into a single self-contained dist/server.js.
  * describe(): 'node dist/server.js'.
@@ -39,25 +41,40 @@ import { RUNTIME_SPECIFIER, buildBundle, bundleExternals, findSdkRoot, loadTsup,
 import { agentDirEntries, copyAgentDirAssets, isAgentDir, scaffoldedAgentDir, writeAgentDirPointer } from './node-server-dir';
 
 const SPEC_EXTENSIONS = new Set(['.yaml', '.yml', '.json']);
+const MODULE_EXTENSIONS = new Set(['.ts', '.mts', '.cts', '.js', '.mjs', '.cjs']);
+
+/** Records the agent module a scaffold imports, so `build(outDir)` bundles it as ESM (`build` only receives `outDir`). */
+const AGENT_MODULE_POINTER = 'agent-module.json';
+
+/** Whether `agentPath` is a .ts/.js file (an agent module, not a spec). */
+function isAgentModule(agentPath: string): boolean {
+  return MODULE_EXTENSIONS.has(path.extname(agentPath).toLowerCase()) && fs.existsSync(agentPath) && fs.statSync(agentPath).isFile();
+}
 
 /**
- * Loads the agent config for a deployment target. Only declarative AgentSpec
- * files are supported: the repo's other agent "configs" (examples/*\/index.ts,
- * create-lousho-agent's src/agent.ts) are runnable scripts that call
- * createAgent() and immediately send a message, not importable configs.
+ * Loads the AgentSpec file a deployment target builds. Agent directories and
+ * (node-server, docker) agent modules are handled before this is called; a
+ * target that gets a .ts/.js file here does not build modules, and says which do.
  */
 export function loadAgentSpecForDeploy(agentPath: string): AgentSpec {
   if (!agentPath) {
-    throw new SDKError('an agent path is required (an AgentSpec .yaml/.yml/.json file): lousho build <agent-dir|spec> --target=<name>', 'LOUSHO_DEPLOY_FAILED');
+    throw new SDKError('an agent path is required (an AgentSpec .yaml/.yml/.json file, an agent directory or an agent module): lousho build <agent-dir|spec|agent.ts> --target=<name>', 'LOUSHO_DEPLOY_FAILED');
   }
   if (!fs.existsSync(agentPath)) {
     throw new SDKError(`agent config not found: ${agentPath}`, 'LOUSHO_DEPLOY_FAILED');
   }
   const ext = path.extname(agentPath).toLowerCase();
+  if (MODULE_EXTENSIONS.has(ext)) {
+    throw new SDKError(
+      `unsupported agent config '${agentPath}': this target builds an AgentSpec .yaml/.yml/.json file or an agent directory, ` +
+        'not a .ts/.js module. --target=node-server and --target=docker build an agent module.',
+      'LOUSHO_DEPLOY_FAILED'
+    );
+  }
   if (!SPEC_EXTENSIONS.has(ext)) {
     throw new SDKError(
-      `unsupported agent config '${agentPath}': expected an AgentSpec .yaml/.yml/.json file ` +
-        `(the same format \`lousho dev\` loads)`,
+      `unsupported agent config '${agentPath}': expected an AgentSpec .yaml/.yml/.json file, an agent directory ` +
+        `or (node-server, docker) a .ts/.js agent module, as \`lousho dev\` loads`,
       'LOUSHO_DEPLOY_FAILED'
     );
   }
@@ -111,6 +128,31 @@ import { createAgent, createDeployedServer, resolveAgentDir, storeFromEnv } from
   };
 }
 
+/** A .ts/.js module (what `lousho dev <file>` serves): its default or `agent` export, a createAgent() config or a built agent. */
+function agentModuleVariant(agentPath: string, options: DeployOptions): ServerVariant {
+  const file = JSON.stringify(agentPath.split(path.sep).join('/'));
+  return {
+    imports: `import { createAgent, createDeployedServer, storeFromEnv } from '${RUNTIME_SPECIFIER}';
+import * as agentModule from ${file};`,
+    boot: `const exported: any = (agentModule as any).default ?? (agentModule as any).agent;
+  if (typeof exported !== 'object' || exported === null) {
+    console.error('[lousho server] ' + ${file} + ' must export a createAgent() config or an agent as its default export (or as agent).');
+    process.exit(1);
+  }
+  // A config's own 'store' wins over the LOUSHO_STORE default; an explicit LOUSHO_STORE still wins. A built agent keeps its own.
+  const store = process.env.LOUSHO_STORE === undefined ? (exported.store ?? storeFromEnv()) : storeFromEnv();
+  const agent = typeof exported.send === 'function' ? exported : createAgent({ ...exported, store });
+  await agent.ready();`,
+    options: JSON.stringify(options),
+    report: '',
+  };
+}
+
+/** The first literal `model: '<provider>/<id>'` in a module's source (a guess at its provider, for the build's package.json). */
+function agentModuleModel(agentPath: string): string | undefined {
+  return /\bmodel\s*:\s*['"`]([a-z][\w-]*\/[^'"`]+)['"`]/.exec(fs.readFileSync(agentPath, 'utf8'))?.[1];
+}
+
 /** The generated server.ts: flags and listening here, the routes in the SDK runtime (src/deploy/nodeServer.ts). */
 function serverSource(variant: ServerVariant): string {
   return `/**
@@ -220,27 +262,21 @@ async function agentDirModel(dir: string): Promise<string | undefined> {
 
 /**
  * The runtime dependencies a built server needs (LOU-R20): `dist/server.js`
- * bundles the SDK and its required dependencies, but the SDK's optional peers
- * stay external (see bundleExternals()), so `npm install` where the server
- * runs - the docker image's `npm install --omit=dev` - must install the ones
- * the agent actually uses. That is the SDK itself (pinned to the version that
- * built it, which also pulls its required peers such as `ai`), the provider
- * package `providerType` resolves to (at the range pairing with the build's
- * `ai` major), and `@modelcontextprotocol/sdk` when the agent uses MCP
- * servers. An unknown provider type (e.g. a registered test provider) adds no
- * dependency.
+ * bundles the SDK and its required dependencies (`ai`, `zod`, ...), but the
+ * SDK's optional peers stay external (see bundleExternals()), so `npm install`
+ * where the server runs - the docker image's `npm install --omit=dev` - must
+ * install the ones the agent actually uses: the provider package
+ * `providerType` resolves to (at the range pairing with the build's `ai`
+ * major) and `@modelcontextprotocol/sdk` when the agent uses MCP servers. The
+ * SDK itself is not listed: the bundle never loads an installed copy. An
+ * unknown provider type (e.g. a registered test provider) adds no dependency.
  */
 export function deployDependencies(providerType?: string, hasMcpServers = false): Record<string, string> {
   const sdkRoot = findSdkRoot();
   const pkg = JSON.parse(fs.readFileSync(path.join(sdkRoot, 'package.json'), 'utf8')) as {
-    version: string;
     peerDependencies?: Record<string, string>;
   };
-  // `^` so a scaffold made from an unpublished development version resolves to
-  // the nearest published release (`npm install` inside the image cannot
-  // install a version that was never pushed to the registry), the same
-  // convention sync-version.mjs uses for the create-lousho-agent pin.
-  const dependencies: Record<string, string> = { '@lousho/build-ai-agent': `^${pkg.version}` };
+  const dependencies: Record<string, string> = {};
   const info = listProviders().find((p) => p.name === providerType);
   if (info) {
     const peer = info.peers[bundledAiMajor(sdkRoot)];
@@ -271,7 +307,36 @@ function packageJsonSource(agentName: string, dependencies: Record<string, strin
   );
 }
 
+/** The `name` of the nearest package.json above `file`, if any. */
+function projectName(file: string): string | undefined {
+  for (let dir = path.dirname(file); ; dir = path.dirname(dir)) {
+    try {
+      const name = (JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')) as { name?: unknown }).name;
+      if (typeof name === 'string') return name;
+    } catch {
+      // no (readable) package.json here
+    }
+    if (path.dirname(dir) === dir) return undefined;
+  }
+}
+
+/** Records `agentPath` as the agent module the scaffold imports, or (undefined) removes an earlier record. */
+function writeAgentModulePointer(outDir: string, agentPath: string | undefined): void {
+  const pointer = path.join(outDir, AGENT_MODULE_POINTER);
+  if (agentPath === undefined) return fs.rmSync(pointer, { force: true });
+  writeFile(pointer, JSON.stringify({ source: agentPath }) + '\n');
+}
+
+function scaffoldAgentModule(agentPath: string, outDir: string, options: DeployOptions): void {
+  writeAgentDirPointer(outDir, undefined);
+  writeAgentModulePointer(outDir, agentPath);
+  writeFile(path.join(outDir, 'server.ts'), serverSource(agentModuleVariant(agentPath, options)));
+  const name = projectName(agentPath) ?? path.basename(agentPath, path.extname(agentPath));
+  writeFile(path.join(outDir, 'package.json'), packageJsonSource(name, deployDependencies(providerTypeOf(agentModuleModel(agentPath)))));
+}
+
 async function scaffoldAgentDir(agentPath: string, outDir: string, options: DeployOptions): Promise<void> {
+  writeAgentModulePointer(outDir, undefined);
   writeAgentDirPointer(outDir, agentPath);
   writeFile(path.join(outDir, 'server.ts'), serverSource(agentDirVariant(options)));
   // A code config can name any provider; a data config's `model` ('openai/...') tells us the peer to ship.
@@ -282,6 +347,7 @@ async function scaffoldAgentDir(agentPath: string, outDir: string, options: Depl
 export const NodeServerAdapter: DeploymentAdapter = {
   async scaffold(agentPath: string, outDir: string, options: DeployOptions = {}): Promise<void> {
     if (isAgentDir(agentPath)) return scaffoldAgentDir(agentPath, outDir, options);
+    if (isAgentModule(agentPath)) return scaffoldAgentModule(agentPath, outDir, options);
     const spec = loadAgentSpecForDeploy(agentPath);
     // Fail at build time, not at first request, on an unresolvable tool name.
     for (const tool of spec.tools || []) resolveSpecTool(tool);
@@ -289,6 +355,7 @@ export const NodeServerAdapter: DeploymentAdapter = {
     specSchedules(spec.triggers);
 
     writeAgentDirPointer(outDir, undefined);
+    writeAgentModulePointer(outDir, undefined);
     writeFile(path.join(outDir, 'agent.config.js'), agentConfigModuleSource(spec));
     writeFile(path.join(outDir, 'server.ts'), serverSource(specVariant(options)));
     writeFile(
@@ -301,15 +368,17 @@ export const NodeServerAdapter: DeploymentAdapter = {
     const { build } = await loadTsup();
     const source = scaffoldedAgentDir(outDir);
     const entry = { server: path.join(outDir, 'server.ts'), ...(source ? await agentDirEntries(source) : {}) };
+    // An agent module may use ESM-only syntax (top-level await, import.meta), so it is bundled as ESM like a directory.
+    const esm = source !== undefined || fs.existsSync(path.join(outDir, AGENT_MODULE_POINTER));
     await buildBundle(build, {
       config: false,
       entry,
       outDir: path.join(outDir, 'dist'),
       // An agent directory is one ESM build with shared chunks (node-server-dir.ts); a spec is a single CJS file.
-      format: [source ? 'esm' : 'cjs'],
-      shims: source !== undefined,
+      format: [esm ? 'esm' : 'cjs'],
+      shims: esm,
       // Bundled CommonJS dependencies (yaml, ...) call require() on node built-ins.
-      banner: source ? { js: "import { createRequire as __cr } from 'node:module'; const require = __cr(import.meta.url);" } : {},
+      banner: esm ? { js: "import { createRequire as __cr } from 'node:module'; const require = __cr(import.meta.url);" } : {},
       splitting: source !== undefined,
       platform: 'node',
       target: 'node18',
@@ -326,6 +395,8 @@ export const NodeServerAdapter: DeploymentAdapter = {
       silent: !process.env.LOUSHO_BUILD_VERBOSE,
     }, outDir);
     if (source) copyAgentDirAssets(source, outDir);
+    // An ESM dist/server.js needs "type": "module" next to it (a directory build's copy step writes it too).
+    else if (esm) writeFile(path.join(outDir, 'dist', 'package.json'), '{ "type": "module" }\n');
   },
 
   describe(): string {

From 47a90a557a554cc9d57868965fc7e21dcbbdb86a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 12 Oct 2026 11:17:56 +0000
Subject: [PATCH 05/11] fix(cli): eval timeouts and empty runs, command help,
 small message and exit-code fixes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BG6n8mwoFq1jmay9zCPS6n
---
 bin/lousho.js                         | 23 +++++++++-----
 docs/evals.md                         |  6 ++--
 src/cli/add.test.ts                   |  6 ++++
 src/cli/add.ts                        | 20 +++++++++++-
 src/cli/args.test.ts                  |  8 +++--
 src/cli/bin.test.ts                   | 20 ++++++++++++
 src/cli/chat.test.ts                  |  6 ++++
 src/cli/chat.ts                       |  2 +-
 src/cli/devReload.ts                  | 13 +++++---
 src/cli/eval.test.ts                  | 44 +++++++++++++++++++++++++--
 src/cli/eval.ts                       | 34 +++++++++++++++++++--
 src/cli/evalReport.ts                 | 31 ++++++++++++++++++-
 src/cli/init.test.ts                  |  1 +
 src/cli/init.ts                       |  5 ++-
 src/cli/mcp.test.ts                   |  6 ++--
 src/cli/mcp.ts                        |  5 +--
 src/cli/studio.test.ts                | 17 +++++++++--
 src/cli/studio.ts                     | 16 +++++++++-
 src/cli/traces.test.ts                |  2 ++
 src/cli/traces.ts                     | 14 ++++++++-
 src/createAgent.test.ts               |  2 +-
 src/providers/providerSpec.ts         |  7 +++--
 src/providers/resolveProvider.test.ts |  4 +--
 23 files changed, 253 insertions(+), 39 deletions(-)

diff --git a/bin/lousho.js b/bin/lousho.js
index 4209c08dc..6f66944b5 100755
--- a/bin/lousho.js
+++ b/bin/lousho.js
@@ -18,7 +18,7 @@ const USAGE = [
   '      Serve an agent over the Agent Client Protocol on stdio (for editors).',
   '  lousho add <name> [--registry <url-or-path>] [--dir <agent-dir>] [--yes] [--allow <list>] [--overwrite] [--dry-run] | --list',
   '      Install a tool, skill, channel, schedule or kit from a registry into an agent directory.',
-  '  lousho build <agent-dir|spec> --target=<node-server|cloudflare-worker|docker> [--out=<dir>]   (or --agent=<path>)',
+  '  lousho build <agent-dir|spec|agent.ts> --target=<node-server|cloudflare-worker|docker> [--out=<dir>]   (or --agent=<path>)',
   '      Bundle an agent for deployment (default output: .lousho/build/<target>).',
   '  lousho studio [--port N] [--host H] [--prod|--dev]',
   '      Open Agent Forge, the visual agent builder.',
@@ -83,12 +83,17 @@ function loadDotEnv() {
 }
 
 // `lousho --version` / `-v` / `version` print the package version (kept in sync with VERSION by scripts/sync-version.mjs).
-function runVersion() {
+function runVersion(rest) {
+  if (rest.length > 0) return usageError(`'version' takes no arguments; got '${rest[0]}'.`);
   console.log(require(path.join(__dirname, '..', 'package.json')).version);
 }
 
-function runHelp() {
-  console.log(USAGE);
+// `lousho help <command>` is `lousho <command> --help`.
+function runHelp(rest) {
+  if (rest.length === 0) return console.log(USAGE);
+  const entry = COMMANDS.get(rest[0]);
+  if (!entry) return unknownCommand(rest[0]);
+  return runCommand(entry, ['--help']);
 }
 
 // `lousho --help` / `-h` / `help` print the usage and succeed (a bare `lousho` is still an error).
@@ -104,11 +109,15 @@ const BUILTINS = new Map([
 /** The exit code for a usage error, as every command returns it (src/cli/args.ts USAGE_EXIT_CODE). */
 const USAGE_EXIT_CODE = 2;
 
-function unknownCommand(command) {
-  console.error(`lousho: unknown command '${command ?? ''}'.\n${USAGE}`);
+function usageError(message) {
+  console.error(`lousho: ${message}\n${USAGE}`);
   process.exitCode = USAGE_EXIT_CODE;
 }
 
+function unknownCommand(command) {
+  usageError(`unknown command '${command ?? ''}'.`);
+}
+
 /**
  * Drops Node's MODULE_TYPELESS_PACKAGE_JSON warning: the CLI imports a
  * `tools/*.ts` file as an ES module even in a project whose package.json has
@@ -135,7 +144,7 @@ async function runCommand(entry, rest) {
 async function main() {
   const [command, ...rest] = process.argv.slice(2);
   const builtin = BUILTINS.get(command);
-  if (builtin) return builtin();
+  if (builtin) return builtin(rest);
   const entry = COMMANDS.get(command);
   return entry ? runCommand(entry, rest) : unknownCommand(command);
 }
diff --git a/docs/evals.md b/docs/evals.md
index cd7fc445e..acb253f38 100644
--- a/docs/evals.md
+++ b/docs/evals.md
@@ -263,8 +263,10 @@ failures and soft failures listed separately.
 
 **Exit code:** `1` on any gate failure (or soft failure with `--strict`, or when
 vitest itself fails, for example a file that does not load, or is not installed,
-or a `--junit`/`--json` report cannot be written), `2` for a usage error (bad
-arguments), otherwise `0`.
+or a `--junit`/`--json` report cannot be written, or when no case ran at all:
+no eval file matched, or a `--tag` matched no case), `2` for a usage error (bad
+arguments), otherwise `0`. A case that vitest fails after the case itself
+finished (it ran past its time limit) is reported as that case failing.
 
 How results are collected: each case appends one JSON line to a file named by
 the `LOUSHO_EVAL_RESULTS` environment variable, which `lousho eval` sets and
diff --git a/src/cli/add.test.ts b/src/cli/add.test.ts
index 6e24a1c09..4360f90ea 100644
--- a/src/cli/add.test.ts
+++ b/src/cli/add.test.ts
@@ -89,6 +89,12 @@ async function add(args: string[], options: { stdin?: string; tty?: boolean; fet
 const withRegistry = (...rest: string[]) => [...rest, '--registry', registry, '--dir', 'agent'];
 
 describe('lousho add', () => {
+  it('--help describes every flag', async () => {
+    const { code, out } = await add(['--help']);
+    expect(code).toBe(0);
+    for (const flag of ['--registry', '--dir', '--yes', '--allow', '--overwrite', '--dry-run', '--list']) expect(out).toMatch(new RegExp(`\\n  ${flag}\\b.* {2,}\\S`));
+  });
+
   it('parses its flags and needs a name or --list', () => {
     expect(parseAddArgs(['x', '--yes', '--dry-run', '--overwrite']).dryRun).toBe(true);
     expect(parseAddArgs(['--list']).list).toBe(true);
diff --git a/src/cli/add.ts b/src/cli/add.ts
index 6cea7a3c3..fd49400f2 100644
--- a/src/cli/add.ts
+++ b/src/cli/add.ts
@@ -23,6 +23,24 @@ import { loadItem, openRegistry, type RegistryIndex, type RegistryItem, type Reg
 
 const USAGE = 'Usage: lousho add <name> [--registry <url-or-path>] [--dir <agent-dir>] [--yes] [--allow exec,fs-write,network,env] [--overwrite] [--dry-run]\n       lousho add --list [--registry <url-or-path>]';
 
+const HELP = `${USAGE}
+
+Installs a tool, skill, channel, schedule, memory slot or kit from a registry into an agent directory,
+as source you own. It prints the item's permissions and files and asks first; nothing from the
+registry is executed, and its npm dependencies are only printed as an install command.
+
+Options:
+  --registry <url-or-path>  the registry index (default: LOUSHO_REGISTRY, else the public registry)
+  --dir <agent-dir>         the agent directory to install into (default: .)
+  --yes                     do not ask; elevated permissions still need --allow
+  --allow <list>            with --yes, grant these elevated permissions: exec, fs-write, network, env
+  --overwrite               replace files that already exist
+  --dry-run                 print what would be written, write nothing
+  --list                    print the registry's items
+  -h, --help                show this help
+
+See docs/registry.md.`;
+
 const SPEC: CommandSpec = {
   command: 'add',
   usage: USAGE,
@@ -255,7 +273,7 @@ export async function runAdd(args: string[], io: AddIo = { stdin: process.stdin,
   try {
     const parsed = parseAddArgs(args);
     if (parsed.help) {
-      io.stdout.write(`${USAGE}\n`);
+      io.stdout.write(`${HELP}\n`);
       return 0;
     }
     return await runParsed(parsed, io);
diff --git a/src/cli/args.test.ts b/src/cli/args.test.ts
index 8dea72631..a13bc8e5b 100644
--- a/src/cli/args.test.ts
+++ b/src/cli/args.test.ts
@@ -89,7 +89,8 @@ const CASES: Case[] = [
   { command: 'chat', parse: parseChatArgs, base: ['a.yaml'], flag: ['--session', 'session', 's1'], positionals: 1, run: (a) => runChat(a, { stdin: new PassThrough(), stdout: new PassThrough(), stderr: new PassThrough() }) },
   { command: 'dev', parse: parseDevArgs, base: ['a.yaml'], flag: ['--host', 'host', '0.0.0.0'], positionals: 1, run: runDev },
   { command: 'build', parse: parseBuildArgs, base: [], flag: ['--target', 'target', 'stub'], positionals: 0, run: (a) => runBuild(a, { stdout: () => {}, stderr: () => {} }) },
-  { command: 'mcp', parse: parseMcpArgs, base: ['a.yaml'], flag: ['--host', 'host', '0.0.0.0'], positionals: 1, run: runMcp },
+  // --host and --port need --http (stdio has neither).
+  { command: 'mcp', parse: parseMcpArgs, base: ['a.yaml', '--http'], flag: ['--host', 'host', '0.0.0.0'], positionals: 1, run: runMcp },
   { command: 'studio', parse: parseStudioArgs, base: [], flag: ['--host', 'apiHost', '0.0.0.0'], positionals: 0, run: runStudio },
   { command: 'doctor', parse: parseDoctorArgs, base: [], positionals: 1, run: (a) => runDoctorCommand(a, undefined, () => {}) },
 ];
@@ -176,8 +177,9 @@ describe('usage errors exit 2 in every command', () => {
 describe('lousho mcp, dev and studio ports', () => {
   it('reject a port that is not an integer from 0 to 65535 and accept --port=N', () => {
     for (const parse of [parseMcpArgs, parseDevArgs, parseStudioArgs]) {
-      expect(() => parse([...(parse === parseStudioArgs ? [] : ['a.yaml']), '--port', 'abc'])).toThrowError(/--port must be an integer between 0 and 65535/);
-      expect(parse([...(parse === parseStudioArgs ? [] : ['a.yaml']), '--port=4000'])).toMatchObject({ [parse === parseStudioArgs ? 'apiPort' : 'port']: 4000 });
+      const base = parse === parseStudioArgs ? [] : parse === parseMcpArgs ? ['a.yaml', '--http'] : ['a.yaml'];
+      expect(() => parse([...base, '--port', 'abc'])).toThrowError(/--port must be an integer between 0 and 65535/);
+      expect(parse([...base, '--port=4000'])).toMatchObject({ [parse === parseStudioArgs ? 'apiPort' : 'port']: 4000 });
     }
   });
 
diff --git a/src/cli/bin.test.ts b/src/cli/bin.test.ts
index e6b8d7eaf..afd4aa0cc 100644
--- a/src/cli/bin.test.ts
+++ b/src/cli/bin.test.ts
@@ -32,6 +32,26 @@ describe('bin/lousho.js', () => {
     expect(banner).toContain('2 usage error');
   });
 
+  it('exits 2 for `version` with an argument instead of ignoring it', () => {
+    const res = lousho('version', 'extra');
+    expect(res.status).toBe(2);
+    expect(res.stderr).toContain("'version' takes no arguments; got 'extra'");
+  });
+
+  it('`help <unknown>` is an unknown command', () => {
+    expect(lousho('help', 'bogus').status).toBe(2);
+  });
+
+  it.skipIf(!fs.existsSync(path.resolve(__dirname, '..', '..', 'dist', 'cli', 'traces.mjs')))(
+    '`help <command>` prints that command\'s help, as `<command> --help` does (needs npm run build)',
+    () => {
+      const res = lousho('help', 'traces');
+      expect(res.status).toBe(0);
+      expect(res.stdout).toBe(lousho('traces', '--help').stdout);
+      expect(res.stdout).toContain('lousho traces');
+    }
+  );
+
   it('exits 2 for an unknown command, like every command does for a usage error', () => {
     const res = lousho('bogus');
     expect(res.status).toBe(2);
diff --git a/src/cli/chat.test.ts b/src/cli/chat.test.ts
index 934132f9f..0e782d8c2 100644
--- a/src/cli/chat.test.ts
+++ b/src/cli/chat.test.ts
@@ -300,6 +300,12 @@ describe('lousho chat command', () => {
     expect(out).toBe('');
   });
 
+  it('names lousho chat, not lousho dev, for a module that exports no agent', async () => {
+    const { code, err } = await run([path.join(fixtures, 'dev-module', 'bad.ts')], ['hi'], undefined);
+    expect(code).toBe(1);
+    expect(err).toMatch(/^lousho chat: .*bad\.ts must export a SimpleAgent/);
+  });
+
   it('fails with LOUSHO_SPEC_NOT_FOUND for a missing spec file (no raw ENOENT)', async () => {
     const { code, err } = await run([path.join(fixtures, 'nope.yaml')], ['hi'], undefined);
     expect(code).toBe(1);
diff --git a/src/cli/chat.ts b/src/cli/chat.ts
index 1d0cbda67..16c4cd3f7 100644
--- a/src/cli/chat.ts
+++ b/src/cli/chat.ts
@@ -84,7 +84,7 @@ export async function buildAgent(path: string, io: Pick<ChatIo, 'overrides'>, mo
     ...io.overrides,
     ...(model && { model, provider: undefined }),
   } as CreateAgentConfig;
-  return loadTarget(target, { overrides });
+  return loadTarget(target, { overrides, command });
 }
 
 /** Runs `lousho chat` with the arguments after `chat`. */
diff --git a/src/cli/devReload.ts b/src/cli/devReload.ts
index 34a97e6e1..82bc30e77 100644
--- a/src/cli/devReload.ts
+++ b/src/cli/devReload.ts
@@ -54,6 +54,8 @@ export interface DevOptions {
   schedules?: boolean;
   /** Overrides for the scheduler (clock, timers, error sink); mainly for tests. */
   scheduler?: StartSchedulesOptions;
+  /** The `lousho` command loading the target, named in its errors. Default 'dev'. */
+  command?: string;
   /** `--allowed-hosts`: host names the `Host` header may carry besides loopback ones (and, off loopback, IP addresses); `'*'` for any. */
   allowedHosts?: string[];
 }
@@ -109,7 +111,7 @@ function isAgentConfig(value: unknown): value is CreateAgentConfig {
   return typeof value === 'object' && value !== null && ('instructions' in value || 'prompt' in value);
 }
 
-async function loadModuleAgent(file: string, token: string, overrides: CreateAgentConfig): Promise<SimpleAgent> {
+async function loadModuleAgent(file: string, token: string, overrides: CreateAgentConfig, command = 'dev'): Promise<SimpleAgent> {
   let mod: Record<string, unknown>;
   try {
     mod = (await import(`${pathToFileURL(file).href}?t=${token}`)) as Record<string, unknown>;
@@ -141,7 +143,7 @@ async function loadModuleAgent(file: string, token: string, overrides: CreateAge
     return agent;
   }
   throw new SDKError(
-    `lousho dev: ${file} must export a SimpleAgent or a createAgent() config as its default export (or as 'agent').`,
+    `lousho ${command}: ${file} must export a SimpleAgent or a createAgent() config as its default export (or as 'agent').`,
     'LOUSHO_CONFIG_INVALID',
     { hint: "Add 'export default createAgent({ ... })', or export the createAgent() options object." }
   );
@@ -170,7 +172,7 @@ async function loadDevTarget(target: DevTarget, options: DevOptions): Promise<Lo
   const loaded = await withFreshImports(token, async () =>
     target.kind === 'dir'
       ? loadDirTarget(target.path, overrides)
-      : { agent: await loadModuleAgent(target.path, token, overrides), schedules: [], channels: [] }
+      : { agent: await loadModuleAgent(target.path, token, overrides, options.command), schedules: [], channels: [] }
   );
   const { agent } = loaded;
   if (overrides.store) storeOwners.add(agent);
@@ -343,9 +345,10 @@ export async function startReloader(target: DevTarget, options: DevOptions = {})
   let closed = false;
 
   async function reload(): Promise<void> {
-    const what = [...changed].filter(Boolean).join(', ') || name;
-    // A changed CommonJS helper that a tool file requires is cached by Node apart from the tool file itself.
     const root = target.kind === 'dir' ? target.path : path.dirname(target.path);
+    // An editor's or sed's temp file (written, then renamed over the real one) is gone by now: not worth naming.
+    const what = [...changed].filter((file) => file && (path.extname(file) !== '' || fs.existsSync(path.resolve(root, file)))).join(', ') || name;
+    // A changed CommonJS helper that a tool file requires is cached by Node apart from the tool file itself.
     forgetCommonJsModules([...changed].filter(Boolean).map((file) => path.resolve(root, file)));
     changed.clear();
     try {
diff --git a/src/cli/eval.test.ts b/src/cli/eval.test.ts
index b2e643fe1..5f51f13ec 100644
--- a/src/cli/eval.test.ts
+++ b/src/cli/eval.test.ts
@@ -120,6 +120,15 @@ const gateResult = result({
 });
 
 describe('runEval with a fake vitest', () => {
+  it('--help describes every flag', async () => {
+    const log = vi.fn();
+    expect(await runEval(['--help'], { log })).toBe(0);
+    const help = String(log.mock.calls[0][0]);
+    for (const flag of ['--tag', '--junit', '--json', '--strict', '--judge', '--record', '--replay', '--drift', '--drift-usage', '--url', '--token', '--config', '--timeout']) {
+      expect(help).toMatch(new RegExp(`\\n  ${flag}\\b[^\\n]* {2,}\\S`));
+    }
+  });
+
   it('exits 1 (not a usage error) and prints the install command when vitest is not installed', async () => {
     const error = vi.spyOn(console, 'error').mockImplementation(() => {});
     expect(await runEval([], { resolveVitest: () => undefined })).toBe(1);
@@ -174,10 +183,12 @@ describe('runEval with a fake vitest', () => {
     expect(log.mock.calls[0][0]).not.toContain('1 failed');
   });
 
-  it('says so when no results were recorded', async () => {
+  it('says so and exits 1 when no results were recorded, naming the --tag that matched nothing', async () => {
     const log = vi.fn();
-    await runEval([], { resolveVitest: () => 'v', spawnVitest: fakeVitest([]).spawnVitest, log });
+    expect(await runEval([], { resolveVitest: () => 'v', spawnVitest: fakeVitest([]).spawnVitest, log })).toBe(1);
     expect(log.mock.calls[0][0]).toContain('no eval results were recorded');
+    expect(await runEval(['--tag', 'smok'], { resolveVitest: () => 'v', spawnVitest: fakeVitest([]).spawnVitest, log })).toBe(1);
+    expect(log.mock.calls[1][0]).toContain('no eval results were recorded (no eval case has the tag smok)');
   });
 
   it('passes --judge through as the judge env var and uses the user config with --config', async () => {
@@ -381,6 +392,35 @@ describe('unreportedFailures (docs-qa F2)', () => {
     expect(renderJunit(extra, false)).toContain('<error message="fixture failed to load" type="EvalError">');
   });
 
+  it('fails a case vitest failed after it recorded a pass (a late timeout) instead of adding a vitest row', () => {
+    const timedOut = { status: 'failed', failureMessages: ['Error: Test timed out in 1ms.'] };
+    const report = {
+      testResults: [
+        {
+          name: file('refund.eval.ts'),
+          status: 'failed',
+          message: '',
+          assertionResults: [
+            { ...timedOut, title: 'refund flow', fullName: 'refund flow' },
+            { ...timedOut, title: 'cases [b]', fullName: 'suite cases [b]' },
+            { status: 'passed', title: 'cases [a]' },
+            { ...timedOut, title: 'repeated' },
+          ],
+        },
+      ],
+    };
+    const results = [
+      result({ name: 'refund flow', file: file('refund.eval.ts') }),
+      result({ name: 'cases', case: 'a', file: file('refund.eval.ts') }),
+      result({ name: 'cases', case: 'b', file: file('refund.eval.ts') }),
+      result({ name: 'repeated', case: 'repeated #1', file: file('refund.eval.ts') }),
+      result({ name: 'refund flow', file: file('other.eval.ts') }),
+    ];
+    expect(unreportedFailures(results, report, 1, options)).toEqual([]);
+    expect(results.map((r) => r.passed)).toEqual([false, true, false, false, true]);
+    expect(results[0]?.error).toMatch(/^Error: Test timed out in 1ms\. Raise the limit with defineEval/);
+  });
+
   it('falls back to one error for the run when vitest failed with nothing failing and no report', () => {
     expect(unreportedFailures([result({})], undefined, 1, options)).toEqual([
       expect.objectContaining({ name: 'vitest', case: 'run', passed: false, error: expect.stringContaining('vitest exited with code 1') }),
diff --git a/src/cli/eval.ts b/src/cli/eval.ts
index a3eaad041..0dbd32671 100644
--- a/src/cli/eval.ts
+++ b/src/cli/eval.ts
@@ -63,6 +63,31 @@ export interface EvalCliArgs {
   help?: boolean;
 }
 
+const HELP = `${USAGE}
+
+Runs *.eval.ts files (defineEval()) under the vitest installed in your project and prints one row
+per case, with totals and the gate and soft failures. Exit code 1 on a gate failure, a vitest
+failure or when no case ran; 2 for a usage error.
+
+Options:
+  globs...              eval files to run (default **/*.eval.ts, or **/*.judge.eval.ts with --judge)
+  --tag t               only cases with this tag (repeat, or comma-separate, for several)
+  --junit path          write a JUnit XML report
+  --json path           write the summary and every result as JSON
+  --strict              soft failures fail the run too
+  --judge               run the *.judge.eval.ts files (llmJudge(); they call a real model)
+  --record              run against the real provider and write one cassette per case
+  --replay              run every case from its cassette, offline; a missing cassette fails the case
+  --drift               re-record into a temp directory and report how each trajectory changed
+  --drift-usage         with --drift: compare token usage too
+  --url <base>          run the cases against the agent deployed at <base> instead of in-process
+  --token <bearer>      with --url: the bearer token (default LOUSHO_EVAL_TOKEN)
+  --config <file>       use your own vitest config instead of the generated one
+  --timeout <ms>        time limit per case (0 = none; live runs default to 10 minutes)
+  -h, --help            show this help
+
+See docs/evals.md.`;
+
 const SPEC: CommandSpec = {
   command: 'eval',
   usage: USAGE,
@@ -338,13 +363,16 @@ async function runAndReport(args: EvalCliArgs, deps: Required<EvalDeps>, vitestB
       results.push(...unreportedFailures(results, vitestReport, vitestCode, { cwd: deps.cwd, strict: args.strict }));
     }
     const drift = args.drift ? applyDrift(results, args, invocation.env[DRIFT_DIR_ENV] as string) : undefined;
-    if (!noFiles) deps.log(results.length > 0 ? `\n${renderTable(results, args.strict)}` : '\nlousho eval: no eval results were recorded.');
+    // Nothing recorded verifies nothing: like a glob that matches no file, it fails (a mistyped --tag skips every case).
+    const nothingRan = !noFiles && results.length === 0;
+    const skipped = args.tags.length > 0 ? ` (no eval case has the tag ${args.tags.join(' or ')})` : '';
+    if (!noFiles) deps.log(results.length > 0 ? `\n${renderTable(results, args.strict)}` : `\nlousho eval: no eval results were recorded${skipped}.`);
     if (drift) deps.log(`\n${renderDriftTable(drift)}`);
     if (args.junit) writeReport(args.junit, renderJunit(results, args.strict));
     if (args.json) writeReport(args.json, renderJson(results, args.strict));
     // A non-zero vitest code with no recorded failure (a file that failed to
     // load, an ordinary test failing) must not read as success.
-    return results.some((r) => failsRun(r, args.strict)) || vitestCode !== 0 ? 1 : 0;
+    return results.some((r) => failsRun(r, args.strict)) || vitestCode !== 0 || nothingRan ? 1 : 0;
   } finally {
     fs.rmSync(workDir, { recursive: true, force: true });
   }
@@ -370,7 +398,7 @@ export async function runEval(rest: string[], deps: EvalDeps = {}): Promise<numb
     return USAGE_EXIT_CODE;
   }
   if (args.help) {
-    resolved.log(USAGE);
+    resolved.log(HELP);
     return 0;
   }
   try {
diff --git a/src/cli/evalReport.ts b/src/cli/evalReport.ts
index 52990a547..049e8dea7 100644
--- a/src/cli/evalReport.ts
+++ b/src/cli/evalReport.ts
@@ -227,6 +227,34 @@ function sameFile(a: string, b: string): boolean {
   return norm(a) === norm(b);
 }
 
+/** The vitest test titles `result` can come from: `name`, `name [case]`, and for a repeat run (`<case> #n`) the case's own title. */
+function testTitles(result: EvalResult): string[] {
+  const titleFor = (label: string | undefined) => (label === undefined || label === result.name ? result.name : `${result.name} [${label}]`);
+  const repeated = result.case === undefined ? undefined : /^(.*) #\d+$/.exec(result.case)?.[1];
+  return [titleFor(result.case), ...(repeated === undefined ? [] : [titleFor(repeated)])];
+}
+
+/**
+ * A case that recorded a pass but whose vitest test failed - it finished after
+ * vitest's timeout fired (or after vitest found it ran past it), or a hook of
+ * that test failed - is failed with vitest's message, in place: the reports
+ * then show that case failing instead of a green case plus a vitest row.
+ */
+function failLateCases(results: EvalResult[], vitestReport: unknown): void {
+  for (const file of (vitestReport as VitestJsonReport | undefined)?.testResults ?? []) {
+    for (const test of file.assertionResults ?? []) {
+      if (test.status !== 'failed') continue;
+      const title = test.title ?? test.fullName;
+      for (const result of results) {
+        if (!result.passed || !result.file || !sameFile(result.file, file.name) || !testTitles(result).includes(title ?? '')) continue;
+        result.passed = false;
+        const message = test.failureMessages?.[0]?.split('\n')[0] ?? 'vitest failed this test after the case recorded a pass';
+        result.error = /timed out/i.test(message) ? `${message} Raise the limit with defineEval({ timeoutMs }) or lousho eval --timeout <ms>.` : message;
+      }
+    }
+  }
+}
+
 export function vitestError(label: string, message: string): EvalResult {
   return { name: 'vitest', case: label, tags: [], passed: false, assertions: [], durationMs: 0, steps: 0, toolCalls: [], error: message };
 }
@@ -239,11 +267,12 @@ export function vitestError(label: string, message: string): EvalResult {
  * empty (green-looking) JUnit and JSON reports.
  */
 export function unreportedFailures(
-  results: readonly EvalResult[],
+  results: EvalResult[],
   vitestReport: unknown,
   vitestCode: number,
   options: { cwd: string; strict: boolean }
 ): EvalResult[] {
+  failLateCases(results, vitestReport);
   const failingFiles = results.filter((r) => failsRun(r, options.strict) && r.file).map((r) => r.file as string);
   const extra: EvalResult[] = [];
   for (const file of (vitestReport as VitestJsonReport | undefined)?.testResults ?? []) {
diff --git a/src/cli/init.test.ts b/src/cli/init.test.ts
index b439656a8..840a459a4 100644
--- a/src/cli/init.test.ts
+++ b/src/cli/init.test.ts
@@ -164,6 +164,7 @@ describe('runInit guards', () => {
     [['--template', 'huge'], /invalid --template 'huge'.*minimal, tools, yaml/],
     [['--package-manager', 'deno'], /invalid --package-manager 'deno'.*npm, pnpm, yarn, bun/],
     [['--wat'], /--wat/],
+    [['--sdk-path', '/nonexistent/lousho-sdk'], /--sdk-path '\/nonexistent\/lousho-sdk' does not exist/],
   ])('rejects bad flags %j with a clear message', async (flags, message) => {
     const h = harness();
     expect(await runInit(['x', '--yes', ...flags], h.environment)).toBe(2);
diff --git a/src/cli/init.ts b/src/cli/init.ts
index a40bff160..87c03fc68 100644
--- a/src/cli/init.ts
+++ b/src/cli/init.ts
@@ -28,7 +28,7 @@ import { askMissing, type AskInput, type InitAnswers } from './init/prompts';
 import { USAGE_EXIT_CODE } from './args';
 import { MissingPeerDependencyError } from '../providers/optionalPeer';
 import { assertWritable, packageNameFor, writeFiles } from './init/scaffold';
-import { resolveSdkDependency, type SdkManifest } from './init/sdkDependency';
+import { resolveSdkDependency, sdkPathProblem, type SdkManifest } from './init/sdkDependency';
 import { renderProject } from './init/templates';
 
 /** Everything `runInit` touches outside the project directory, so tests can fake it. */
@@ -82,6 +82,9 @@ function validateFlags(options: InitOptions): void {
   if (options.provider !== undefined) expectOneOf('--provider', options.provider, PROVIDER_NAMES);
   if (options.template !== undefined) expectOneOf('--template', options.template, TEMPLATES);
   if (options.packageManager !== undefined) expectOneOf('--package-manager', options.packageManager, PACKAGE_MANAGERS);
+  // A bad --sdk-path is a usage error (exit 2), like a bad --provider.
+  const sdkPath = options.sdkPath === undefined ? undefined : sdkPathProblem(options.sdkPath);
+  if (sdkPath !== undefined) throw new InitUsageError(sdkPath);
 }
 
 /**
diff --git a/src/cli/mcp.test.ts b/src/cli/mcp.test.ts
index 412e95f22..b818a1b3f 100644
--- a/src/cli/mcp.test.ts
+++ b/src/cli/mcp.test.ts
@@ -35,8 +35,10 @@ describe('parseMcpArgs', () => {
   });
 
   it('explains how to fix a missing path or bad port', () => {
-    expect(() => parseMcpArgs([])).toThrow(/spec file path is required/);
-    expect(() => parseMcpArgs(['a.json', '--port', 'abc'])).toThrow(/--port must be an integer/);
+    expect(() => parseMcpArgs([])).toThrow(/an agent path is required \(a spec file, an agent directory or a \.ts\/\.js module\)/);
+    expect(() => parseMcpArgs(['a.json', '--http', '--port', 'abc'])).toThrow(/--port must be an integer/);
+    // stdio has no port: a --port without --http is a usage error, not silently ignored.
+    expect(() => parseMcpArgs(['a.json', '--port', '5'])).toThrow(/--port and --host need --http/);
   });
 });
 
diff --git a/src/cli/mcp.ts b/src/cli/mcp.ts
index 0e2fc8f72..dc95187ea 100644
--- a/src/cli/mcp.ts
+++ b/src/cli/mcp.ts
@@ -46,7 +46,8 @@ const SPEC: CommandSpec = {
 export function parseMcpArgs(rest: string[]): McpCliArgs {
   const { values, positionals, help } = parseCommand(SPEC, rest);
   if (help) return { configPath: '', http: false, port: 3920, host: '127.0.0.1', help };
-  if (positionals.length === 0) throw usageError(SPEC, 'an agent spec file path is required.');
+  if (positionals.length === 0) throw usageError(SPEC, 'an agent path is required (a spec file, an agent directory or a .ts/.js module).');
+  if (values.http !== true && (values.port !== undefined || values.host !== undefined)) throw usageError(SPEC, '--port and --host need --http (stdio is the default).');
   return { configPath: positionals[0], http: values.http === true, port: portValue(SPEC, values.port, 3920), host: stringValue(values.host) ?? '127.0.0.1' };
 }
 
@@ -60,7 +61,7 @@ export async function startMcpServer(args: McpCliArgs): Promise<ServeMcpHandle>
     agent = specToAgent(spec);
     name = spec.name;
   } else {
-    agent = await loadTarget(target);
+    agent = await loadTarget(target, { command: 'mcp' });
     name = path.basename(target.path, path.extname(target.path));
   }
   return serveMcp({
diff --git a/src/cli/studio.test.ts b/src/cli/studio.test.ts
index f0177b9c4..33c550b64 100644
--- a/src/cli/studio.test.ts
+++ b/src/cli/studio.test.ts
@@ -1,8 +1,8 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, vi } from 'vitest';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { startStudio, resolveAgentForgeDir, studioUrl } from './studio';
+import { runStudio, startStudio, resolveAgentForgeDir, studioUrl } from './studio';
 
 const tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'lousho-studio-test-'));
 
@@ -148,3 +148,16 @@ describe('startStudio', () => {
   // covers startStudio()'s own pure logic (the apps/agent-forge lookup and
   // dev/prod/auto mode resolution).
 });
+
+describe('lousho studio --help', () => {
+  it('describes every flag', async () => {
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+    try {
+      expect(await runStudio(['--help'])).toBe(0);
+      const help = String(log.mock.calls[0]?.[0]);
+      for (const flag of ['--port', '--host', '--prod', '--dev']) expect(help).toMatch(new RegExp(`\\n  ${flag}\\b[^\\n]* {2,}\\S`));
+    } finally {
+      log.mockRestore();
+    }
+  });
+});
diff --git a/src/cli/studio.ts b/src/cli/studio.ts
index 4c4259db0..05da47b03 100644
--- a/src/cli/studio.ts
+++ b/src/cli/studio.ts
@@ -287,6 +287,20 @@ function startDevStudio(appDir: string, repoRoot: string, apiPort: number, apiHo
 
 const USAGE = 'Usage: lousho studio [--port N] [--host H] [--prod|--dev]';
 
+const HELP = `${USAGE}
+
+Opens Agent Forge, the visual agent builder. It prints a URL with a per-launch token; every
+API and WebSocket request needs that token.
+
+Options:
+  --port N    the studio's port (default 4750)
+  --host H    the interface to listen on (default 127.0.0.1)
+  --prod      serve the built UI from one process (needs the studio build)
+  --dev       run the API and the Vite dev server (a checkout of the SDK repository)
+  -h, --help  show this help
+
+Without --prod or --dev it serves the built UI when there is one, else the dev servers.`;
+
 const SPEC: CommandSpec = {
   command: 'studio',
   usage: USAGE,
@@ -306,7 +320,7 @@ export async function runStudio(rest: string[]): Promise<number> {
   try {
     const { help, ...options } = parseStudioArgs(rest);
     if (help) {
-      console.log(USAGE);
+      console.log(HELP);
       return 0;
     }
     startStudio({ ...options, repoRoot: process.cwd() });
diff --git a/src/cli/traces.test.ts b/src/cli/traces.test.ts
index 54c4b33c7..76db59c38 100644
--- a/src/cli/traces.test.ts
+++ b/src/cli/traces.test.ts
@@ -106,6 +106,8 @@ describe('lousho traces (M5a)', () => {
 
   it('--help prints the usage; a bad flag or --limit exits 2', async () => {
     expect((await run(['--help'])).out).toContain('Usage: lousho traces');
+    // Every flag is described, not just listed in the usage line.
+    expect((await run(['--help'])).out).toMatch(/--content +with a trace id/);
     expect((await run(['--nope'])).code).toBe(2);
     expect((await run(['--limit', '0'])).code).toBe(2);
     expect(() => parseTracesArgs(['a', 'b'])).toThrow(/unexpected argument 'b'/);
diff --git a/src/cli/traces.ts b/src/cli/traces.ts
index 9035a9e89..c6c65d7a6 100644
--- a/src/cli/traces.ts
+++ b/src/cli/traces.ts
@@ -14,6 +14,18 @@ import { parseCommand, stringValue, usageError, type CommandSpec } from './args'
 const USAGE =
   'Usage: lousho traces [--dir D] [--limit N] [--json]\n       lousho traces <traceId|prefix> [--dir D] [--json] [--content]';
 
+const HELP = `${USAGE}
+
+Lists the runs fileTraceExporter() (or --traces on dev, chat) saved, newest first; with a trace id
+or a unique prefix of one, prints that run as a tree of spans.
+
+Options:
+  --dir D      the trace directory (default ${DEFAULT_TRACE_DIR})
+  --limit N    how many runs to list (default 20)
+  --json       print JSON instead of a table or tree
+  --content    with a trace id: also print prompts, replies and tool arguments
+  -h, --help   show this help`;
+
 const SPEC: CommandSpec = {
   command: 'traces',
   usage: USAGE,
@@ -305,7 +317,7 @@ export async function runTraces(rest: string[], deps: TracesDeps = {}): Promise<
   try {
     const args = parseTracesArgs(rest);
     if (args.help) {
-      resolved.log(USAGE);
+      resolved.log(HELP);
       return 0;
     }
     const dir = path.resolve(resolved.cwd, args.dir);
diff --git a/src/createAgent.test.ts b/src/createAgent.test.ts
index 411613fb2..11ae31371 100644
--- a/src/createAgent.test.ts
+++ b/src/createAgent.test.ts
@@ -144,7 +144,7 @@ describe('createAgent', () => {
 
     it('lists supported prefixes and suggests the closest for an unknown provider', () => {
       expect(() => createAgent({ model: 'opnai/gpt-4o' })).toThrow(
-        /createAgent: unrecognized provider 'opnai'.*Supported prefixes: openai, anthropic, openrouter, ollama, pi\. Did you mean 'openai\/gpt-4o'\?/
+        /createAgent: unrecognized provider 'opnai'.*Supported prefixes: openai, anthropic, openrouter, ollama, pi, mock\. Did you mean 'openai\/gpt-4o'\?/
       );
     });
 
diff --git a/src/providers/providerSpec.ts b/src/providers/providerSpec.ts
index d1fbd7067..017af595a 100644
--- a/src/providers/providerSpec.ts
+++ b/src/providers/providerSpec.ts
@@ -189,6 +189,9 @@ const PROVIDER_NAMES = Object.keys(PROVIDERS);
 /** The built-in test provider: registered like the others, but needs no key and no peer, so it has no entry above. */
 const MOCK_PROVIDER = 'mock';
 
+/** Every prefix a `<provider>/<model>` spec takes, as error messages list them (the scripted `mock` one included). */
+const SPEC_PREFIXES = [...PROVIDER_NAMES, MOCK_PROVIDER].join(', ');
+
 /** Env var that overrides the automatic provider choice, e.g. `LOUSHO_MODEL=anthropic/claude-sonnet-4-5`. */
 const MODEL_ENV_VAR = 'LOUSHO_MODEL';
 
@@ -196,7 +199,7 @@ function unknownProviderError(caller: string, providerName: string, spec: string
   const suggestion = closestMatch(providerName, PROVIDER_NAMES);
   return new ConfigurationError(
     `${caller}: unrecognized provider '${providerName}' in spec '${spec}'. ` +
-      `Supported prefixes: ${PROVIDER_NAMES.join(', ')}.` +
+      `Supported prefixes: ${SPEC_PREFIXES}.` +
       (suggestion ? ` Did you mean '${suggestion}/${spec.slice(providerName.length + 1)}'?` : ''),
     'model',
     'LOUSHO_PROVIDER_UNKNOWN'
@@ -300,7 +303,7 @@ export function resolveProviderSpec(spec: string, caller: string, registry: Prov
   if (separatorIndex <= 0 || separatorIndex === spec.length - 1) {
     throw new ConfigurationError(
       `${caller}: expected a "<provider>/<model>" spec, got '${spec}'. ` +
-        `Example: 'openai/gpt-4o-mini'. Supported prefixes: ${PROVIDER_NAMES.join(', ')}.`,
+        `Example: 'openai/gpt-4o-mini'. Supported prefixes: ${SPEC_PREFIXES}.`,
       'model',
       'LOUSHO_PROVIDER_SPEC_INVALID'
     );
diff --git a/src/providers/resolveProvider.test.ts b/src/providers/resolveProvider.test.ts
index 4990a4513..c6e045276 100644
--- a/src/providers/resolveProvider.test.ts
+++ b/src/providers/resolveProvider.test.ts
@@ -144,12 +144,12 @@ describe('resolveProvider errors (LOU-D1)', () => {
 
   it('lists supported prefixes and suggests the closest match for a typo', () => {
     expect(() => resolveProvider('anthopic/claude-3')).toThrow(
-      "unrecognized provider 'anthopic' in spec 'anthopic/claude-3'. Supported prefixes: openai, anthropic, openrouter, ollama, pi. Did you mean 'anthropic/claude-3'?"
+      "unrecognized provider 'anthopic' in spec 'anthopic/claude-3'. Supported prefixes: openai, anthropic, openrouter, ollama, pi, mock. Did you mean 'anthropic/claude-3'?"
     );
   });
 
   it('lists supported prefixes without a suggestion when nothing is close', () => {
-    expect(() => resolveProvider('zzzzzzzzzz/m')).toThrow(/Supported prefixes: openai, anthropic, openrouter, ollama, pi\.$/m);
+    expect(() => resolveProvider('zzzzzzzzzz/m')).toThrow(/Supported prefixes: openai, anthropic, openrouter, ollama, pi, mock\.$/m);
   });
 
   it('shows an example for a spec without a provider prefix', () => {

From fc68e5f54e63155c0e52ab1869461c3ab44897e5 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 12 Oct 2026 11:17:56 +0000
Subject: [PATCH 06/11] chore(package): stop shipping the CJS CLI build;
 changelog and upgrading notes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BG6n8mwoFq1jmay9zCPS6n
---
 CHANGELOG.md          | 12 ++++++++++
 docs/upgrading.md     |  4 ++++
 llms-full.txt         | 54 +++++++++++++++++++++++++++++++++----------
 package.json          |  2 ++
 scripts/pack-smoke.ts |  3 +++
 tsup.config.ts        |  4 +++-
 6 files changed, 66 insertions(+), 13 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5b9708aea..156219489 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -62,6 +62,8 @@ opt-out.
 - Agent Forge: a run on a real provider without an API key fails with `LOUSHO_PROVIDER_MISSING_API_KEY` (HTTP 422) instead of silently using the mock provider, and the provider pill shows what actually ran.
 - The examples import `@lousho/build-ai-agent` and its public subpaths instead of the repository's `src/`, so they can be copied into an app as they are.
 
+- The `package.json` that `lousho build --target=node-server|docker` writes lists only the optional peers the bundled server loads (the provider package, `@modelcontextprotocol/sdk` with `mcpServers`), no longer `@lousho/build-ai-agent`: `dist/server.js` bundles the SDK, `ai` and `zod`, so the image's install is smaller.
+- The npm package no longer ships the CommonJS build of the CLI (`dist/cli/*.js` and maps) or the CLI's type declarations: `bin/lousho.js` loads only `dist/cli/*.mjs`.
 ### Added
 - Providers: a `timeout` option (default 10 minutes until the response starts and between chunks; `0` or `Infinity` turns it off) and a `fetch` option on every built-in provider. `OpenAIProvider({ api: 'chat' })` and `LOUSHO_OPENAI_API=chat` use Chat Completions for OpenAI-compatible servers (LM Studio, Ollama, vLLM, llama.cpp; the built-in hosted tools are then refused with `LOUSHO_HOSTED_TOOL_UNSUPPORTED`); see [Local and OpenAI-compatible servers](docs/providers.md#local-and-openai-compatible-servers). `withRateLimit()` / `createRateLimiter()` and `createAgent({ rateLimit })` queue model calls client-side. `promptCaching: 'auto'` (the default) marks Anthropic cache breakpoints for Claude on `anthropic` and `openrouter`. `withRetry({ idleTimeoutMs })` fails a stream that stalls between chunks (`timeoutMs` now bounds only the wait for the first chunk). `withFallback()` results carry `servedBy`.
 - Model settings: `createAgent({ modelSettings })` and per-call `modelSettings` (`maxTokens`, `temperature`, `topP`, penalties, `stop`, `seed`, `toolChoice`), range-checked up front, also in `agent.json`. Per-call `maxSteps` and `instructions` on `send()` / `stream()`. See [Configuration](docs/configuration.md#model-settings).
@@ -79,6 +81,9 @@ opt-out.
 - Channels and schedules: `githubChannel({ pullRequestOpened: true })`, `webhookChannel({ principal })`, exported `fireSchedule()`, `startSchedules({ keepAlive: true })` and an awaitable `stop()`, and `mountFetchChannels({ waitUntil })`.
 - CLI: `lousho doctor --ping` and base URLs in its output, and `lousho --version`.
 
+- `lousho build --target=node-server|docker` builds a `.ts`/`.js` agent module (the file `lousho dev src/agent.ts` serves: a default or `agent` export holding `createAgent()` options or a built agent). The `cloudflare-worker` target says it builds only a spec or an agent directory. The minimal and tools scaffolds export their options as `src/agent.ts`'s default export, so `lousho dev|chat|mcp|acp|build src/agent.ts` work on a new project, and every scaffold has a `build` script (and `tsup`); the minimal and tools ones also have `dev:ui` (`lousho dev src/agent.ts`).
+- The Docker image `lousho build --target=docker` writes has a `HEALTHCHECK` on `GET /health`, and its `.dockerignore` keeps `.env`, `.env.*` and `*.tgz` out of the image.
+- `lousho add`, `studio`, `eval` and `traces --help` describe every flag; `lousho help <command>` prints that command's help.
 ### Fixed
 - Durability: concurrent commits on one session no longer lose a turn (new optional `SessionStore.saveIf()` compare-and-swap; `KVStore` stays best effort), and session objects re-read the store instead of caching the transcript. Concurrent `send({ sessionId })` calls in one process run in order. Parallel tool calls are checkpointed as each settles, so a crash no longer re-runs finished calls. A restarted process that resolves a session's approval commits the turn instead of dropping it. `session.clear()` deletes every turn's checkpoints and history, finished turns stay forkable, `session.fork()` works for 122-128 character ids, and sub-agent task ids are never reused.
 - Stores: `fileStore` file names are case-safe on Windows and macOS (`Alice` and `alice` no longer share a file), long ids and device names are hashed, older long names are still read, writes are `fsync`ed and Windows `EPERM` / `EBUSY` is retried. A corrupt checkpoint fails with `LOUSHO_CHECKPOINT_CORRUPT` and can be discarded. `SqliteStore` waits 50 ms instead of freezing the event loop, retries locked writes without blocking (`LOUSHO_STORAGE_BUSY`) and `prune()` keeps paused turns. `KVStore` approval claims run a tool once in the common case (`ctx.approval.id` serves as an idempotency key). Image and file bytes survive every store. Taking over a stale file lock is serialized, and `KVCheckpointStore.list()` throws without a `list` binding instead of returning `[]`. `agent.approvals.get()` returns `undefined` for an id that cannot name an approval. `fileMemory` and `sqliteMemory` keep every item with several writers.
@@ -112,6 +117,13 @@ opt-out.
 - Approve-with-edits on a sub-agent's *grouped* approval validates the edited args against the tool's schema like a top-level or single sub-agent decision does: before, `snapshot.subagent` stored `decision.args` raw, so an invalid edit (e.g. a string where `z.number()` wants a number) ran the tool with garbage args; it now throws `LOUSHO_TOOL_ARGS_INVALID` and leaves the approval pending. (Eve2-F4)
 - Aborting a run during a tool call no longer hangs `send()` / `stream()` / `approvals.resolve()` forever on a tool that ignores its `abortSignal`: the tool batch and the approved-tool wait of `resumeAfterApproval()` are raced against the run's signal the way the model call already was (Eve CORE-F15), the run ends `finishReason: 'aborted'` with a 'cancelled' result for calls still running past a short grace window (a result that lands within it is still kept), and the tool keeps running in the background. (Eve2-F5)
 - A run that re-pauses on several approvals after a resume persists every pending approval id in its checkpoint: `markAwaitingApproval()` wrote only `approvalId`, so durable discovery (`pausedApprovalIds`, `agent.approvals.list()`) named 1 of N approvals; it now carries the group's `approvalIds` like `markGroupPending()` does. (Eve2-F6)
+- The `inbox-triage` registry kit loads under `lousho dev`, `chat`, `acp`, `mcp` and `doctor`: its relative imports carry the `.ts` extension Node's type stripping needs (only bundlers resolved them). A test now installs every registry kit and loads it in a plain `node` process, as the CLI does. An extensionless relative import in an agent directory gets a hint naming the specifier to write (`'./lib/store.ts'`), and on a Node without built-in type stripping (before 22.18) the `.ts` load error says Node 22.19+ is required.
+- `OPENAI_BASE_URL` (and `ANTHROPIC_BASE_URL`) is used with `@ai-sdk/openai` 1.x (`@ai-sdk/anthropic` 1.x), the line that pairs with `ai` 4: the provider passes it when no `baseURL` is configured. Before, `model: 'openai/...'` called api.openai.com while `lousho doctor --ping` reported the custom endpoint.
+- `PropagatingToolError`, `McpToolError` and `WorkspaceError` pass `instanceof` across the ESM and CJS copies of the SDK, so a `.cjs` tool's "do not retry" error stops the run under the ESM `lousho` CLI instead of being handed to the model (and retried).
+- `lousho dev` re-evaluates the local helper files an edited tool or agent module imports (the `?t=` cache-bust is passed on to relative imports), instead of logging "reloaded" while serving the stale helper; editor temp files no longer show in the "changed:" list.
+- `lousho eval`: a case that vitest fails after the case finished (it ran past its time limit) is reported as that case failing, not as a pass plus an extra `vitest` row; a run that records no case at all (a mistyped `--tag`) exits 1 like a glob that matches nothing.
+- The yarn scaffold's `yarn test` works: the templates list `vite`, vitest's peer, which yarn 1 does not install. The README's "Next 3 commands" lists three, and the tools template's README counts its three tools.
+- CLI messages: a module that exports no agent names the command that loaded it (`lousho chat:`, not `lousho dev:`); `lousho mcp` without a path says a spec, directory or module is accepted, and `--port`/`--host` without `--http` are a usage error instead of ignored; `lousho version <arg>` and `init --sdk-path <missing>` exit 2; the unknown-provider error lists `mock`.
 
 ## [1.0.0-alpha.19] - 2026-10-08
 
diff --git a/docs/upgrading.md b/docs/upgrading.md
index 342cafb82..37853a9b1 100644
--- a/docs/upgrading.md
+++ b/docs/upgrading.md
@@ -278,6 +278,10 @@ there is one. A change marked "no opt-out" closed a security or data-loss bug.
 | `lousho eval` gives each live, `--record` and `--drift` case 10 minutes instead of vitest's 5 s. See [Time limits](./evals.md#time-limits). | `--timeout <ms>` or `defineEval({ timeoutMs })` |
 | Agent Forge fails a run on a real provider with no API key (`LOUSHO_PROVIDER_MISSING_API_KEY`) instead of silently using the mock provider. | switch the agent's provider to `mock` |
 | The npm package no longer ships `llms-full.txt` (it stays in the repository; `llms.txt` ships). | fetch `llms-full.txt` from the repository |
+| `lousho eval` exits 1 when no case ran (every case skipped by `--tag`, or no `defineEval()` in the files). | pass the tags or globs that select cases |
+| `lousho mcp --port N` or `--host H` without `--http` is a usage error (exit 2); stdio has no port. | drop the flags, or add `--http` |
+| The `package.json` of a node-server or docker build no longer lists `@lousho/build-ai-agent` (the bundle contains it). | add it yourself if other code next to the build imports the SDK |
+| The npm package no longer ships `dist/cli/*.js` (the CommonJS CLI build) or `dist/cli/*.d.ts`; `bin/lousho.js` never loaded them. | run the CLI through `bin/lousho.js` (`npx lousho`) |
 
 ## What 1.0 promises
 
diff --git a/llms-full.txt b/llms-full.txt
index 362492c27..93e3b0f06 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -4706,7 +4706,7 @@ lousho dev <spec.yaml|spec.json|agent-dir|agent.ts> [--port N] [--host H] [--all
 lousho chat <spec.yaml|spec.json|agent-dir|agent.ts> [--model provider/model] [--session id] [--store sqlite:<file>] [--traces[=dir]]
 lousho acp <spec.yaml|spec.json|agent-dir|agent.ts> [--model provider/model]
 lousho add <name> [--registry <url-or-path>] [--dir <agent-dir>] [--yes] [--allow <list>] [--overwrite] [--dry-run]    (or --list)
-lousho build <agent-dir|spec> --target=<node-server|cloudflare-worker|docker> [--out=<dir>]    (or --agent=<path>)
+lousho build <agent-dir|spec|agent.ts> --target=<node-server|cloudflare-worker|docker> [--out=<dir>]    (or --agent=<path>)
 lousho studio [--port N] [--host H] [--prod|--dev]
 lousho mcp <agent.yaml|json|agent-dir|agent.ts> [--http --port N --host H]
 lousho doctor [agent.yaml|json|agent-dir] [--json] [--ping]
@@ -4717,8 +4717,8 @@ lousho --version
 
 Every command parses its flags the same way (Node's `parseArgs`, strict):
 `--flag value` and `--flag=value` both work, the last of a repeated flag wins
-(`--tag` accumulates), `--` ends the flags, and `-h` / `--help` prints the
-command's usage and exits 0. An unknown flag, a flag without its value (it
+(`--tag` accumulates), `--` ends the flags, and `-h` / `--help` (or `lousho help
+<command>`) prints the command's usage and flags and exits 0. An unknown flag, a flag without its value (it
 never takes the next flag as its value) or an extra argument fails with
 `LOUSHO_CONFIG_INVALID` and the usage line. A value that starts with `-` needs
 the `=` form: `--model=-x`. `--traces` is the one flag whose value is optional:
@@ -4823,8 +4823,10 @@ without restarting the server or dropping the port:
   `require` specifiers, found once at startup; no bundler).
 
 Directory and module files are imported with a `?t=<time>` cache-busting query,
-so an edited tool or agent file is re-evaluated. A file *imported by* that file
-(a shared helper) stays cached by Node: restart `lousho dev` after editing one.
+so an edited tool or agent file is re-evaluated, and so are the local files it
+imports by relative specifier (a shared `./lib/helper.ts`): the query is passed
+on to them. Packages under `node_modules` stay cached; restart `lousho dev`
+after changing one.
 The console logs what reloaded. The new agent is built (and `ready()`, so MCP
 servers connect) before it replaces the old one, and the old one is then
 `close()`d. If the rebuild fails, the last good agent keeps answering, the error
@@ -4918,6 +4920,7 @@ scripted lines and a `mockModel` agent and no terminal.
 ```bash
 npx lousho build --target=node-server --agent=agent.yaml        # or docker / cloudflare-worker
 npx lousho build ./my-agent --target=node-server                # an agent directory (node-server, docker)
+npx lousho build src/agent.ts --target=node-server              # an agent module (node-server, docker)
 ```
 
 Writes the artifact to `--out` (default `.lousho/build/<target>`) and prints
@@ -6821,6 +6824,26 @@ only a Worker-safe part of `@lousho/build-ai-agent`
 npx lousho build ./my-agent --target=cloudflare-worker
 ```
 
+## Agent modules
+
+The `node-server` and `docker` targets also build a `.ts`/`.js` module whose
+default (or `agent`) export is `createAgent()` options or a built agent: the
+same file `lousho dev src/agent.ts` serves, and what the minimal and tools
+scaffolds have (their `npm run build` runs this):
+
+```bash
+npx lousho build src/agent.ts --target=node-server
+node .lousho/build/node-server/dist/server.js
+```
+
+The generated `server.ts` imports the module, so tsup bundles it with its local
+imports and the SDK into an ESM `dist/server.js`. With an options export the
+server builds the agent with `LOUSHO_STORE` (unless the options name a
+`store`); an exported agent keeps its own. The build's `package.json` names
+the provider package when the module has a literal `model: '<provider>/...'`;
+add any other optional peer it needs yourself. The `cloudflare-worker` target
+does not build a module: use a spec or an agent directory.
+
 ## HTTP API
 
 Every target serves the same `/chat` protocol as `lousho dev`
@@ -6964,10 +6987,10 @@ browser-platform ES module; the build fails if any `node:` import ends up in the
 `dist/server.js` bundles the SDK but leaves its optional peers (the `peerDependenciesMeta`
 entries of its package.json: provider packages, `dockerode`, the MCP SDK, `prompts`, ...) external, so a build
 never needs one you do not use. The generated `package.json` already lists the
-ones the agent needs where the server runs - `@lousho/build-ai-agent` (at
-`^` the version that built it, a caret range, not an exact pin), the provider package the spec names (at the
+ones the agent needs where the server runs - the provider package the spec names (at the
 range pairing with the build's `ai` major, e.g. `@ai-sdk/openai` for an OpenAI
-agent) and `@modelcontextprotocol/sdk` when the spec has `mcpServers` - so the
+agent) and `@modelcontextprotocol/sdk` when the spec has `mcpServers` - and
+nothing else: `@lousho/build-ai-agent`, `ai` and `zod` are inside the bundle, so the
 docker image's `npm install --omit=dev` or a `npm install` next to the
 node-server output installs them. Anything else (an agent directory's own
 imports, `dockerode` for sandboxed tools) you add yourself; a code path that
@@ -9153,8 +9176,10 @@ failures and soft failures listed separately.
 
 **Exit code:** `1` on any gate failure (or soft failure with `--strict`, or when
 vitest itself fails, for example a file that does not load, or is not installed,
-or a `--junit`/`--json` report cannot be written), `2` for a usage error (bad
-arguments), otherwise `0`.
+or a `--junit`/`--json` report cannot be written, or when no case ran at all:
+no eval file matched, or a `--tag` matched no case), `2` for a usage error (bad
+arguments), otherwise `0`. A case that vitest fails after the case itself
+finished (it ran past its time limit) is reported as that case failing.
 
 How results are collected: each case appends one JSON line to a file named by
 the `LOUSHO_EVAL_RESULTS` environment variable, which `lousho eval` sets and
@@ -13923,8 +13948,9 @@ const agent = createAgent({
   `registerModel({ id, provider: 'openai', contextWindow })` once (see
   [Local and unknown models](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/compaction.md#local-and-unknown-models)).
 
-**The `openai/<model>` string with `OPENAI_BASE_URL`.** `@ai-sdk/openai` reads
-`OPENAI_BASE_URL`, so `createAgent({ model: 'openai/qwen3-8b' })` with
+**The `openai/<model>` string with `OPENAI_BASE_URL`.** `OpenAIProvider` passes
+`OPENAI_BASE_URL` to `@ai-sdk/openai` when no `baseURL` is configured (on every
+major, including the 1.x line that pairs with `ai` 4), so `createAgent({ model: 'openai/qwen3-8b' })` with
 `OPENAI_BASE_URL=http://localhost:1234/v1` and a dummy `OPENAI_API_KEY=any`
 calls the local server without code changes. That route uses the Responses
 API unless `LOUSHO_OPENAI_API=chat` is set too, which selects Chat Completions
@@ -18923,6 +18949,10 @@ there is one. A change marked "no opt-out" closed a security or data-loss bug.
 | `lousho eval` gives each live, `--record` and `--drift` case 10 minutes instead of vitest's 5 s. See [Time limits](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/evals.md#time-limits). | `--timeout <ms>` or `defineEval({ timeoutMs })` |
 | Agent Forge fails a run on a real provider with no API key (`LOUSHO_PROVIDER_MISSING_API_KEY`) instead of silently using the mock provider. | switch the agent's provider to `mock` |
 | The npm package no longer ships `llms-full.txt` (it stays in the repository; `llms.txt` ships). | fetch `llms-full.txt` from the repository |
+| `lousho eval` exits 1 when no case ran (every case skipped by `--tag`, or no `defineEval()` in the files). | pass the tags or globs that select cases |
+| `lousho mcp --port N` or `--host H` without `--http` is a usage error (exit 2); stdio has no port. | drop the flags, or add `--http` |
+| The `package.json` of a node-server or docker build no longer lists `@lousho/build-ai-agent` (the bundle contains it). | add it yourself if other code next to the build imports the SDK |
+| The npm package no longer ships `dist/cli/*.js` (the CommonJS CLI build) or `dist/cli/*.d.ts`; `bin/lousho.js` never loaded them. | run the CLI through `bin/lousho.js` (`npx lousho`) |
 
 ## What 1.0 promises
 
diff --git a/package.json b/package.json
index 711b315a5..33b99b41e 100644
--- a/package.json
+++ b/package.json
@@ -277,6 +277,8 @@
   },
   "files": [
     "dist",
+    "!dist/cli/*.js",
+    "!dist/cli/*.js.map",
     "src",
     "!src/**/*.test.ts",
     "!src/**/*.test-d.ts",
diff --git a/scripts/pack-smoke.ts b/scripts/pack-smoke.ts
index bf519a42a..e3f434fcb 100644
--- a/scripts/pack-smoke.ts
+++ b/scripts/pack-smoke.ts
@@ -77,6 +77,8 @@ const FORBIDDEN_PATHS = [
   /(^|\/)node_modules\//,
   /^apps\/agent-forge\/dist-server\/.*\.map$/,
   /^dist\/deploy\/worker\.m?js\.map$/,
+  // bin/lousho.js loads only the ESM CLI build (dist/cli/*.mjs); the CJS one is not shipped.
+  /^dist\/cli\/[^/]+\.js(\.map)?$/,
   /\.pem$/,
   /\.key$/,
 ];
@@ -89,6 +91,7 @@ const FORBIDDEN_PATHS = [
  */
 const REQUIRED_PATHS = [
   'src/index.ts',
+  'dist/cli/dev.mjs',
   'src/deploy/runtime.worker.ts',
   'src/deploy/shims/node.worker.ts',
   'apps/agent-forge/dist-server/index.cjs',
diff --git a/tsup.config.ts b/tsup.config.ts
index 71791c029..cd6385e65 100644
--- a/tsup.config.ts
+++ b/tsup.config.ts
@@ -70,7 +70,9 @@ export default defineConfig([
     // deletes all of dist's *.d.* at the start of its own (parallel) dts
     // run - the two dts builds would race. The dts pass needs no shims:
     // type-only imports emit no code.
-    dts: { entry: { ...entry, 'deploy/worker': 'src/deploy/worker.ts' } },
+    // The CLI entries get none: bin/lousho.js runs their ESM build and nothing imports them as a library
+    // (their CJS build, which shares this build's chunks, is left out of the package: see "files").
+    dts: { entry: { ...Object.fromEntries(Object.entries(entry).filter(([name]) => !name.startsWith('cli/'))), 'deploy/worker': 'src/deploy/worker.ts' } },
     splitting: true,
     sourcemap: true,
     clean: true,

From f244c0cae3a15cbc6e8fa03e871d479f781335a3 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 12 Oct 2026 16:26:16 +0000
Subject: [PATCH 07/11] refactor(cli): split failLateCases so it stays under
 the cognitive-complexity limit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BG6n8mwoFq1jmay9zCPS6n
---
 src/cli/evalReport.ts | 28 ++++++++++++++++++----------
 1 file changed, 18 insertions(+), 10 deletions(-)

diff --git a/src/cli/evalReport.ts b/src/cli/evalReport.ts
index 049e8dea7..7171862f4 100644
--- a/src/cli/evalReport.ts
+++ b/src/cli/evalReport.ts
@@ -241,20 +241,28 @@ function testTitles(result: EvalResult): string[] {
  * then show that case failing instead of a green case plus a vitest row.
  */
 function failLateCases(results: EvalResult[], vitestReport: unknown): void {
-  for (const file of (vitestReport as VitestJsonReport | undefined)?.testResults ?? []) {
-    for (const test of file.assertionResults ?? []) {
-      if (test.status !== 'failed') continue;
-      const title = test.title ?? test.fullName;
-      for (const result of results) {
-        if (!result.passed || !result.file || !sameFile(result.file, file.name) || !testTitles(result).includes(title ?? '')) continue;
-        result.passed = false;
-        const message = test.failureMessages?.[0]?.split('\n')[0] ?? 'vitest failed this test after the case recorded a pass';
-        result.error = /timed out/i.test(message) ? `${message} Raise the limit with defineEval({ timeoutMs }) or lousho eval --timeout <ms>.` : message;
-      }
+  for (const { file, test } of failedTests(vitestReport)) {
+    const title = test.title ?? test.fullName ?? '';
+    const late = results.filter((result) => result.passed && result.file && sameFile(result.file, file) && testTitles(result).includes(title));
+    for (const result of late) {
+      result.passed = false;
+      result.error = lateFailureMessage(test.failureMessages?.[0]);
     }
   }
 }
 
+/** Every test vitest marked failed, with the file it is in. */
+function failedTests(vitestReport: unknown) {
+  return ((vitestReport as VitestJsonReport | undefined)?.testResults ?? []).flatMap((file) =>
+    (file.assertionResults ?? []).filter((test) => test.status === 'failed').map((test) => ({ file: file.name, test }))
+  );
+}
+
+function lateFailureMessage(failure: string | undefined): string {
+  const message = failure?.split('\n')[0] ?? 'vitest failed this test after the case recorded a pass';
+  return /timed out/i.test(message) ? `${message} Raise the limit with defineEval({ timeoutMs }) or lousho eval --timeout <ms>.` : message;
+}
+
 export function vitestError(label: string, message: string): EvalResult {
   return { name: 'vitest', case: label, tags: [], passed: false, assertions: [], durationMs: 0, steps: 0, toolCalls: [], error: message };
 }

From caad41b326097f4dd4d5a45c86bbbb33ee47156f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 12 Oct 2026 16:26:16 +0000
Subject: [PATCH 08/11] refactor(execution): one abortable() helper for
 provider calls and resumed tool calls

The resumed-tool race added in #618 duplicated generateStep's abortable();
both now share it, with an optional grace period for the tool path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BG6n8mwoFq1jmay9zCPS6n
---
 src/execution/abortable.ts    | 23 +++++++++++++++++++++++
 src/execution/generateStep.ts | 16 +---------------
 src/execution/resume.ts       | 29 ++++-------------------------
 3 files changed, 28 insertions(+), 40 deletions(-)
 create mode 100644 src/execution/abortable.ts

diff --git a/src/execution/abortable.ts b/src/execution/abortable.ts
new file mode 100644
index 000000000..ad9dcdc36
--- /dev/null
+++ b/src/execution/abortable.ts
@@ -0,0 +1,23 @@
+/**
+ * `call`, or its rejection with `signal`'s reason once `signal` aborts - work
+ * that ignores the signal is not waited for, though `call` keeps running.
+ * With `graceMs`, the abort side waits that long first, so a settlement that
+ * lands while the run unwinds still wins (a tool released just as the run
+ * aborted keeps its real result, like ToolBatch.settled()'s drained wait).
+ */
+export function abortable<T>(call: Promise<T>, signal: AbortSignal | undefined, graceMs = 0): Promise<T> {
+  if (!signal) return call;
+  return new Promise<T>((resolve, reject) => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const onAbort = () => {
+      if (graceMs > 0) timer = setTimeout(() => reject(signal.reason), graceMs);
+      else reject(signal.reason);
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    if (signal.aborted) onAbort();
+    call.then(resolve, reject).finally(() => {
+      signal.removeEventListener('abort', onAbort);
+      clearTimeout(timer);
+    });
+  });
+}
diff --git a/src/execution/generateStep.ts b/src/execution/generateStep.ts
index e18e8df86..68876a39f 100644
--- a/src/execution/generateStep.ts
+++ b/src/execution/generateStep.ts
@@ -35,6 +35,7 @@ import { settleHostedFinish } from './hostedToolCalls';
 import { hostedToolsInMode, permissionModeOf } from './permissions';
 import type { ParallelInputCheck } from './ioGuardrails';
 import { deferralOf, visibleTools, type ToolDeferral } from './toolDeferral';
+import { abortable } from './abortable';
 
 /** A legacy `.tool`'s description when it is a string (always, on `ai` v4). */
 function legacyDescription(description: unknown): string | undefined {
@@ -228,21 +229,6 @@ export interface GeneratedStep {
   measured: CallUsage;
 }
 
-/**
- * LOU-V10: `call`, or its rejection with `signal`'s reason as soon as
- * `signal` aborts - a provider that ignores the signal is not waited for.
- * `call` keeps running either way.
- */
-function abortable<T>(call: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
-  if (!signal) return call;
-  return new Promise<T>((resolve, reject) => {
-    const onAbort = () => reject(signal.reason);
-    signal.addEventListener('abort', onAbort, { once: true });
-    if (signal.aborted) onAbort();
-    call.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
-  });
-}
-
 /** The signal that aborts when either does (`undefined` when neither is set). */
 function anySignal(a: AbortSignal | undefined, b: AbortSignal | undefined): AbortSignal | undefined {
   if (!a || !b || a === b) return a ?? b;
diff --git a/src/execution/resume.ts b/src/execution/resume.ts
index d6b4851fd..41113a6b8 100644
--- a/src/execution/resume.ts
+++ b/src/execution/resume.ts
@@ -24,6 +24,7 @@ import {
 } from './ApprovalGate';
 import { validateToolArguments } from './toolArgsValidation';
 import { TOOL_ABORT_GRACE_MS } from './toolBatch';
+import { abortable } from './abortable';
 import { AgentExecutor, ExecuteOptions, ExecutionResult, extendRunOptions } from './AgentExecutor';
 import { observeRun, partialSink, runEventsOf, streamResumed, type AgentRun, type ToolSettled } from './agentRun';
 import { Checkpoint, CheckpointStore, RUN_CONFIG_KEY, pausedApprovalIds } from './checkpoint';
@@ -1472,29 +1473,6 @@ interface SettledCall {
   replacedByHook?: string;
 }
 
-/**
- * Eve2-F5: like `abortable()` (a tool that ignores the signal does not hold
- * the run open forever), except a settlement landing while the run unwinds
- * still wins - the abort side drains for TOOL_ABORT_GRACE_MS first, so a
- * tool released just as the run aborted keeps its real result (B4), exactly
- * like ToolBatch.settled()'s drained wait.
- */
-function abortableToolCall<T>(call: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
-  if (!signal) return call;
-  return new Promise<T>((resolve, reject) => {
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    const onAbort = () => {
-      timer = setTimeout(() => reject(signal.reason), TOOL_ABORT_GRACE_MS);
-    };
-    signal.addEventListener('abort', onAbort, { once: true });
-    if (signal.aborted) onAbort();
-    call.then(resolve, reject).finally(() => {
-      signal.removeEventListener('abort', onAbort);
-      clearTimeout(timer);
-    });
-  });
-}
-
 /**
  * Executes the approved tool itself. The try/catch here handles ONLY the
  * tool's own execution failure - NOT the postToolCall hook call that
@@ -1530,7 +1508,7 @@ async function executeApprovedTool(
       // would otherwise hold the resume open forever. The rejection lands
       // in the catch below like the tool's own abort error (the tool keeps
       // running, documented for ExecuteOptions.signal).
-      result: await abortableToolCall(
+      result: await abortable(
         executeToolWithSandboxGuard(
           pending.toolName,
           toolDesc,
@@ -1540,7 +1518,8 @@ async function executeApprovedTool(
           { toolCallId: pending.toolCallId, messages, approval, sessionId, principal: executeOptions.principal, tokens: executeOptions.tokens, onPartial: partialsOf(pending, executeOptions) },
           scope
         ),
-        executeOptions.signal
+        executeOptions.signal,
+        TOOL_ABORT_GRACE_MS
       ),
     };
   } catch (error) {

From a35ed59c27cefe048d13cfd9f63e34ce103e24a3 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 12 Oct 2026 16:26:16 +0000
Subject: [PATCH 09/11] test(mcp): let the run start before the client timeout
 fires

A 200 ms timeout could fire before a cold runner started the run, so the
cancel matched nothing and the run was never aborted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BG6n8mwoFq1jmay9zCPS6n
---
 src/tools/mcp/server/serveMcp.test.ts | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/tools/mcp/server/serveMcp.test.ts b/src/tools/mcp/server/serveMcp.test.ts
index 7c09a548e..faeb6275b 100644
--- a/src/tools/mcp/server/serveMcp.test.ts
+++ b/src/tools/mcp/server/serveMcp.test.ts
@@ -313,8 +313,10 @@ describe('serveMcp over HTTP', () => {
     const client = new Client({ name: 'c', version: '1' });
     await client.connect(new StreamableHTTPClientTransport(new URL(server.url!)));
     closers.push(() => client.close());
-    await expect(client.callTool({ name: 'slow', arguments: { message: 'x' } }, undefined, { timeout: 200 })).rejects.toThrow(/timed out/i);
-    await vi.waitFor(() => expect(seen?.aborted).toBe(true));
+    // The timeout must fire after the run has started (a cancel for a request not yet in flight matches
+    // nothing), which a cold CI runner can take well over 200 ms to reach; the run itself lasts 5 s.
+    await expect(client.callTool({ name: 'slow', arguments: { message: 'x' } }, undefined, { timeout: 1500 })).rejects.toThrow(/timed out/i);
+    await vi.waitFor(() => expect(seen?.aborted).toBe(true), { timeout: 3000 });
   });
 
   it('a cancel naming a request id two clients have in flight is ignored', async () => {

From 0aad27f245375f26899317484159cddcc1cc515d Mon Sep 17 00:00:00 2001
From: Ali Mohammad <freelancealimohammad@gmail.com>
Date: Mon, 12 Oct 2026 19:42:06 +0300
Subject: [PATCH 10/11] ci: retrigger checks


From 1b97db91c1d445ad8015e9fd240507a9d64fba1f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 12 Oct 2026 16:59:45 +0000
Subject: [PATCH 11/11] test(mcp): give serveMcp's run-start and cancel waits
 room on busy runners

vi.waitFor's 1 s default failed on a CI runner whose suite took 300 s,
before the server had started the run. The late-cancel test's runs now
last long enough for the cancel to land first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BG6n8mwoFq1jmay9zCPS6n
---
 src/tools/mcp/server/serveMcp.test.ts | 21 ++++++++++++---------
 1 file changed, 12 insertions(+), 9 deletions(-)

diff --git a/src/tools/mcp/server/serveMcp.test.ts b/src/tools/mcp/server/serveMcp.test.ts
index faeb6275b..b8fc12cfd 100644
--- a/src/tools/mcp/server/serveMcp.test.ts
+++ b/src/tools/mcp/server/serveMcp.test.ts
@@ -10,6 +10,9 @@ import { mockModel } from '../../../testing';
 import { buildServer, sanitizeToolName, type ServerSpec } from './buildServer';
 import { serveMcp, type ServeMcpHandle } from './serveMcp';
 
+/** Busy CI runners can take seconds to start a run or deliver a cancel; vi.waitFor's 1 s default is too tight. */
+const SLOW_RUNNER = { timeout: 5000 };
+
 const searchDocs = defineTool({
   name: 'search_docs',
   description: 'Search the docs',
@@ -183,7 +186,7 @@ describe('serveMcp agent tool', () => {
     await startedPromise;
     controller.abort();
     await expect(call).rejects.toBeDefined();
-    await vi.waitFor(() => expect(seen?.aborted).toBe(true));
+    await vi.waitFor(() => expect(seen?.aborted).toBe(true), SLOW_RUNNER);
   });
 });
 
@@ -316,7 +319,7 @@ describe('serveMcp over HTTP', () => {
     // The timeout must fire after the run has started (a cancel for a request not yet in flight matches
     // nothing), which a cold CI runner can take well over 200 ms to reach; the run itself lasts 5 s.
     await expect(client.callTool({ name: 'slow', arguments: { message: 'x' } }, undefined, { timeout: 1500 })).rejects.toThrow(/timed out/i);
-    await vi.waitFor(() => expect(seen?.aborted).toBe(true), { timeout: 3000 });
+    await vi.waitFor(() => expect(seen?.aborted).toBe(true), SLOW_RUNNER);
   });
 
   it('a cancel naming a request id two clients have in flight is ignored', async () => {
@@ -337,7 +340,7 @@ describe('serveMcp over HTTP', () => {
     const call = () =>
       fetch(server.url!, { method: 'POST', headers, body: JSON.stringify({ jsonrpc: '2.0', id: 7, method: 'tools/call', params: { name: 'slow', arguments: { message: 'x' } } }) });
     const calls = [call(), call()];
-    await vi.waitFor(() => expect(started).toBe(2));
+    await vi.waitFor(() => expect(started).toBe(2), SLOW_RUNNER);
     await fetch(server.url!, { method: 'POST', headers, body: JSON.stringify({ jsonrpc: '2.0', method: 'notifications/cancelled', params: { requestId: 7 } }) });
     const results = await Promise.all(calls.map(async (response) => (await response).json()));
     expect(signals.map((signal) => signal.aborted)).toEqual([false, false]);
@@ -376,21 +379,21 @@ describe('serveMcp over HTTP', () => {
     expect(transports[0].sessionId).not.toBe(transports[1].sessionId);
     // Both clients send the same JSON-RPC ids, from the same address and User-Agent.
     const full = clients[0].callTool({ name: 'slow', arguments: { message: 'a' } });
-    await vi.waitFor(() => expect(signals).toHaveLength(1));
+    await vi.waitFor(() => expect(signals).toHaveLength(1), SLOW_RUNNER);
     // Cancel only once the second run has started: a fixed client timeout can fire before the
     // server registers the request on a busy runner, and then there is nothing to abort yet.
     const cancel = new AbortController();
     const second = clients[1].callTool({ name: 'slow', arguments: { message: 'b' } }, undefined, { signal: cancel.signal });
-    await vi.waitFor(() => expect(signals).toHaveLength(2));
+    await vi.waitFor(() => expect(signals).toHaveLength(2), SLOW_RUNNER);
     cancel.abort();
     await expect(second).rejects.toThrow();
-    await vi.waitFor(() => expect(signals[1]?.aborted).toBe(true));
+    await vi.waitFor(() => expect(signals[1]?.aborted).toBe(true), SLOW_RUNNER);
     expect(textOf(await full)).toBe('done');
     expect(signals[0].aborted).toBe(false);
   });
 
   it("a late cancel from another session does not stop a request with the same id, and a cancelled request is answered", async () => {
-    const { agent: slow, signals } = slowAgent(400);
+    const { agent: slow, signals } = slowAgent(2000);
     const server = await serveMcp({ agent: slow, name: 'slow', transport: { type: 'http', port: 0 }, warn: () => {} });
     closers.push(server.close);
     const headers = (session: string) => ({ 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream', 'Mcp-Session-Id': session });
@@ -400,14 +403,14 @@ describe('serveMcp over HTTP', () => {
       fetch(server.url!, { method: 'POST', headers: headers(session), body: JSON.stringify({ jsonrpc: '2.0', method: 'notifications/cancelled', params: { requestId: 7 } }) });
 
     const a = call('session-a');
-    await vi.waitFor(() => expect(signals).toHaveLength(1));
+    await vi.waitFor(() => expect(signals).toHaveLength(1), SLOW_RUNNER);
     // session-b has nothing in flight under id 7: its (late) cancel must not reach session-a.
     await cancel('session-b');
     expect(signals[0].aborted).toBe(false);
     expect((await (await a).json()).result.content[0].text).toBe('done');
 
     const b = call('session-b');
-    await vi.waitFor(() => expect(signals).toHaveLength(2));
+    await vi.waitFor(() => expect(signals).toHaveLength(2), SLOW_RUNNER);
     await cancel('session-b');
     const answer = await b;
     expect(signals[1].aborted).toBe(true);