From fba3aa6647030de7cf64f6cead06e48109d3bce1 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 1 Oct 2026 16:50:08 +0000
Subject: [PATCH] [EPIC-D][LOU-D31] loushy dev serves agent directories, TS
 agents and specs with hot reload

loushy dev <path> now takes a spec file, an agent directory (loadAgentDir) or a
.ts/.js module exporting a SimpleAgent or createAgent() config. It watches the
directory tree or the module and its relative imports, debounces, rebuilds with
a ?t= cache-busted import, readies the new agent, swaps it in and closes the
previous one. A failed reload keeps the last good agent and is reported in the
console, the chat page banner and GET /dev/status.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016bY29ibQgv3MDdjAbUT4YR
---
 CHANGELOG.md                                  |   1 +
 bin/loushy.js                                 |   4 +-
 docs/agent-directories.md                     |  17 +-
 docs/cli.md                                   |  47 +++-
 llms-full.txt                                 |  64 ++++-
 src/agentDir/importModule.ts                  |  17 +-
 src/cli/__fixtures__/dev-agent/agent.json     |   1 +
 .../__fixtures__/dev-agent/instructions.md    |   1 +
 src/cli/__fixtures__/dev-agent/tools/ping.ts  |   9 +
 src/cli/__fixtures__/dev-module/agent.ts      |   9 +
 src/cli/__fixtures__/dev-module/bad.ts        |   1 +
 src/cli/__fixtures__/dev-module/config.ts     |   1 +
 src/cli/__fixtures__/dev-module/greeting.ts   |   1 +
 src/cli/dev-ui/index.html                     |  17 ++
 src/cli/dev.test.ts                           | 138 ++++++++++-
 src/cli/dev.ts                                |  77 +++---
 src/cli/devReload.ts                          | 233 ++++++++++++++++++
 17 files changed, 575 insertions(+), 63 deletions(-)
 create mode 100644 src/cli/__fixtures__/dev-agent/agent.json
 create mode 100644 src/cli/__fixtures__/dev-agent/instructions.md
 create mode 100644 src/cli/__fixtures__/dev-agent/tools/ping.ts
 create mode 100644 src/cli/__fixtures__/dev-module/agent.ts
 create mode 100644 src/cli/__fixtures__/dev-module/bad.ts
 create mode 100644 src/cli/__fixtures__/dev-module/config.ts
 create mode 100644 src/cli/__fixtures__/dev-module/greeting.ts
 create mode 100644 src/cli/devReload.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6e7a77118..69d1029f0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased] - 2026-09-28
 
 ### Added
+- `loushy dev` for agent directories and TS agents, with hot reload (LOU-D31): `loushy dev <path>` takes a spec file (as before), an agent directory (`loadAgentDir()`) or a `.ts`/`.js` module whose default (or `agent`) export is a `SimpleAgent` or a `createAgent()` options object, detected by path type and extension (a bad path, extension or export fails with `LOUSHY_CONFIG_INVALID` / `LOUSHY_SPEC_UNSUPPORTED_FORMAT`). It watches the directory tree, or the module and its relative imports, and rebuilds the agent about 100 ms after a change with a `?t=<time>` cache-busted import, so edited tools reload; the new agent is built and `ready()` before it replaces the old one, which is then `close()`d. A failed rebuild keeps the last good agent and reports the error in the console, in a banner on the chat page and in the new `GET /dev/status` (`{ kind, path, reloads, error }`). `startDevServer(path, port?, host?, { overrides?, debounceMs? })` gains the options argument. Spec-file behaviour is unchanged; the chat is not streamed or per-tab (LOU-D32). See docs/cli.md#loushy-dev and docs/agent-directories.md#run-it-with-loushy-dev.
 - Fork and replay (LOU-D44): `AgentExecutor.fork({ sessionId, fromStep, newSessionId?, checkpointStore, patch? })` takes the newest entry of `fromStep` in the session's checkpoint history, applies `patch` (`messages(messages)`, `businessState`, `toolResult: { toolCallId, result }` replaced in place so the transcript stays provider-valid, `appendInput` queued as a user message) and saves it as the `'in-progress'` checkpoint of `newSessionId` (default `<sessionId>.fork-<n>`), leaving the original session untouched; it returns `{ sessionId, step, checkpoint }`, and `execute({ sessionId, checkpointStore, input: [] })` continues the fork. A missing step throws the new `LOUSHY_CHECKPOINT_NOT_FOUND` code. `createAgent()` agents gain `agent.fork(sessionId, { fromStep, newSessionId?, patch? })` over `store.checkpoints` (resume with `agent.resume()`). `compareTrajectories(a, b)` compares two checkpoints or transcripts step by step: each run's steps (text, tool calls and results), the first diverging step and the `loushy eval --drift` diff. New types `ForkOptions`, `ForkPatch`, `ForkResult`, `TrajectoryComparison`, `TrajectoryStep` and `DriftEntry`. See docs/durable-execution.md#fork-and-replay.
 - Multimodal message parts (LOU-V11): `Message.content` is now `string | ContentPart[]`, where a `ContentPart` is `{ type: 'text', text }`, `{ type: 'image', image, mimeType? }` (an `http(s)` URL, a `data:` URL or a `Uint8Array`) or `{ type: 'file', data, mimeType, filename? }` (new types `ContentPart`, `TextContentPart`, `ImageContentPart`, `FileContentPart`). The built-in providers map the parts of `user` messages to the `ai` v4 user-content parts: images go to the model with all four (the `ai` SDK downloads an image URL first for Anthropic and Ollama); file parts become a `[file <name> (<mimeType>) not sent]` text note with a one-time `console.warn`, since the pinned peers (`@ai-sdk/*` 0.0.x, `ollama-ai-provider`) cannot send files (a subclass sets `acceptsFileParts = true` to send them). `system`, `assistant` and `tool` messages are sent as their text. The new `textOf(message)` returns a message's text (the string, or its text parts joined), and is what `estimateTokens()` (each image or file part counts 1,000 tokens), compaction, `recordReplay()` fingerprints (cassette messages gain an optional `attachments` list: each image or file as its URL or a digest of its bytes), `mockModel()`, `MockLLMProvider`, OpenTelemetry content attributes and the React reducer (`ui.send` takes parts too) now read. `FileSessionStore` saves `Uint8Array`s as `{ "$bytes": "<base64>" }` and loads them back. Pass multimodal messages as `AgentExecutor.execute({ input: Message[] })`; `agent.send()` / `session.send()` taking parts is LOU-V12. See docs/providers.md#multimodal-input.
 - Declarative permission policies (LOU-X2): `permissions?: PermissionRule[]` on `createAgent()`, `ExecuteOptions` and `resumeAfterApproval()` options. A rule is `{ tool: string | string[] | RegExp | '*', when?: (args, { toolName, toolCallId, sessionId }) => boolean | Promise<boolean>, action: 'allow' | 'deny' | 'ask', reason? }`; rules are checked in order for each tool call (after argument validation and `preToolCall` hooks, before `needsApproval`) and the first match decides: `allow` runs the call without approval even when `needsApproval` would ask, `deny` gives the model a tool error with the new `kind: 'denied'` (`ToolDeniedError`, plus `reason`) and streams `tool.error`, `ask` pauses for approval (or asks `approve`). No match keeps today's behaviour. New helpers `allow(tools)`, `deny(tools, reason?)`, `ask(tools)` and types `PermissionRule`, `PermissionAction`, `PermissionToolMatcher`, `PermissionContext`, `PermissionDecision`, `PermissionDecisionEntry`, `PermissionOptions`. Audit log: `onPermissionDecision(entry)` gets `{ toolName, toolCallId, decision: 'allow' | 'deny' | 'ask' | 'default', rule?: { index, reason? }, args?, at }` per call (`args` left out under `redactContent`), and streams get the same entry as the new typed `permission.decision` event (`PermissionDecisionEvent`; additive, the event schema version stays 1). Neither is produced unless `permissions` or `onPermissionDecision` is set. Sub-agents inherit the lead's rules (checked before their own) and its `onPermissionDecision`. See docs/approvals.md#permission-policies.
diff --git a/bin/loushy.js b/bin/loushy.js
index 616d6882a..8efdbbfa2 100644
--- a/bin/loushy.js
+++ b/bin/loushy.js
@@ -6,7 +6,7 @@ const path = require('node:path');
 const USAGE = [
   'Usage:',
   '  loushy init [dir] [--provider P] [--template T] [--yes] [--no-install] [--no-git] [--package-manager PM] [--force]',
-  '  loushy dev <config.yaml|config.json> [--port N] [--host H]',
+  '  loushy dev <spec.yaml|spec.json|agent-dir|agent.ts> [--port N] [--host H]',
   '  loushy build --target=<name> --agent=<path> [--out=<dir>]',
   '  loushy studio [--port N] [--host H] [--prod|--dev]',
   '  loushy mcp <agent.yaml|json> [--http --port N --host H]',
@@ -36,7 +36,7 @@ async function runDev(rest) {
   const host = readFlag(rest, 'host', '127.0.0.1');
 
   if (!configPath) {
-    console.error('loushy dev: a config file path is required. Usage: loushy dev <config.yaml|config.json> [--port N] [--host H]');
+    console.error('loushy dev: a path is required (a spec file, an agent directory or a .ts/.js agent module). Usage: loushy dev <spec.yaml|spec.json|agent-dir|agent.ts> [--port N] [--host H]');
     process.exitCode = 1;
     return;
   }
diff --git a/docs/agent-directories.md b/docs/agent-directories.md
index d9d26d718..83c0f04db 100644
--- a/docs/agent-directories.md
+++ b/docs/agent-directories.md
@@ -146,7 +146,20 @@ says so. Compile the directory first, or use `.js`/`.mjs` tools with an
 `import` syntax needs `"type": "module"` in the nearest `package.json` (or the
 `.mjs` extension).
 
+## Run it with `loushy dev`
+
+```bash
+npx loushy dev ./my-agent
+```
+
+Serves the chat UI and `POST /chat` for the directory and reloads it when
+`instructions.md`, the config file, `tools/`, `skills/` or `subagents/` change
+(see [`loushy dev`](cli.md#loushy-dev) for the details). A tool file is
+imported afresh on each reload, so an edit to `tools/*.ts` takes effect on the
+next message. A failed reload (a syntax error, an empty `instructions.md`) is
+logged and shown in the chat page, and the previous agent keeps answering.
+
 ## What is not covered
 
-`loushy dev` and `loushy mcp` still take an agent spec file
-([Configuration](configuration.md)), not a directory.
+`loushy mcp` still takes an agent spec file ([Configuration](configuration.md)),
+not a directory.
diff --git a/docs/cli.md b/docs/cli.md
index 3f0f0fb1f..1e696bee1 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -9,7 +9,7 @@ Run it with `npx loushy <command>` inside a project that has the SDK installed.
 | ------- | ------------ | ------- |
 | `loushy init [dir]` | Scaffold a project: an agent with an example tool, an offline test, `.env.example`; installs dependencies and runs `git init`. | [Installation](./installation.md#scaffolding-a-new-project) |
 | `loushy doctor [spec] [--json]` | Check Node, peer packages, provider keys, and optionally a spec file; prints a fix for every problem. | [Installation](./installation.md#troubleshooting-loushy-doctor) |
-| `loushy dev <spec>` | Local dev server for a spec file: chat UI, `POST /chat`, hot reload on save. | [Below](#loushy-dev) |
+| `loushy dev <path>` | Local dev server for a spec file, an agent directory or a TS agent: chat UI, `POST /chat`, hot reload on save. | [Below](#loushy-dev) |
 | `loushy mcp <spec>` | Serve the agent as an MCP server (stdio, or HTTP with `--http`). | [Configuration](./configuration.md#serve-an-agent-over-mcp) |
 | `loushy eval [globs...]` | Run `*.eval.ts` files under vitest; print a summary and write JUnit/JSON reports. | [Evals](./evals.md#loushy-eval) |
 | `loushy build --target=<t> --agent=<spec>` | Build a deployable Node server, Docker image or Cloudflare Worker. | [Deployment](./deployment.md) |
@@ -22,7 +22,7 @@ Every command that takes a `<spec>` reads an agent spec file (`.yaml`,
 
 ```text
 loushy init [dir] [--provider P] [--template T] [--yes] [--no-install] [--no-git] [--package-manager PM] [--force]
-loushy dev <config.yaml|config.json> [--port N] [--host H]
+loushy dev <spec.yaml|spec.json|agent-dir|agent.ts> [--port N] [--host H]
 loushy build --target=<name> --agent=<path> [--out=<dir>]
 loushy studio [--port N] [--host H] [--prod|--dev]
 loushy mcp <agent.yaml|json> [--http --port N --host H]
@@ -38,13 +38,48 @@ with `node bin/loushy.js init my-agent --sdk-path .` (see
 ## `loushy dev`
 
 ```bash
-npx loushy dev agent.yaml
+npx loushy dev agent.yaml                  # a spec file
+npx loushy dev ./my-agent                  # an agent directory
+npx loushy dev src/agent.ts                # a TypeScript (or JavaScript) module
 npx loushy dev agent.yaml --port 4000 --host 0.0.0.0
 ```
 
-Serves `GET /` (a chat UI), `GET /health` and `POST /chat`
-(`{ "message": "..." }`, 1MB body limit). The agent is reloaded whenever the
-spec file changes, and the last good config is kept if an edit is invalid.
+Serves `GET /` (a chat UI), `GET /health`, `GET /dev/status` and `POST /chat`
+(`{ "message": "..." }`, 1MB body limit). What `<path>` is follows from the path:
+
+| Path | Loaded with |
+| ---- | ----------- |
+| `.yaml`, `.yml`, `.json` | `loadSpec()` + `specToAgent()` ([Configuration](./configuration.md)) |
+| a directory | `loadAgentDir()` ([Agent directories](./agent-directories.md)) |
+| `.ts`, `.mts`, `.js`, `.mjs`, `.cjs` | the module's default export, or its `agent` export: a `SimpleAgent` (what `createAgent()` returns) or a `createAgent()` options object |
+
+Any other extension, a missing path, or a module with no agent export fails
+with a coded error (`LOUSHY_SPEC_UNSUPPORTED_FORMAT`, `LOUSHY_CONFIG_INVALID`)
+and its fix. A `.ts` module is imported by the running Node (22.19 or later
+strips types, so relative imports need their file extension); use `.js` for
+code that needs a transpiler.
+
+**Hot reload.** The agent is rebuilt a moment (100 ms) after a file changes,
+without restarting the server or dropping the port:
+
+- a spec: the spec file;
+- a directory: everything under it (`instructions.md`, the config file,
+  `tools/`, `skills/`, `subagents/`), except `node_modules` and `.git`;
+- a module: the file and the local files it imports (relative `import` /
+  `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 `loushy dev` after editing 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
+is logged and shown in a banner on the chat page (and as `error` in
+`GET /dev/status`); the next good edit clears it.
+
+Directories and modules are your code and run with your permissions; only run
+`loushy dev` on ones you trust. `POST /chat` talks to one shared agent, not one
+conversation per browser tab.
 
 - `--port` - default `3737`.
 - `--host` - default `127.0.0.1` (localhost only). Pass e.g. `--host=0.0.0.0`
diff --git a/llms-full.txt b/llms-full.txt
index 709d3db4b..4e891ec56 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -1581,10 +1581,23 @@ says so. Compile the directory first, or use `.js`/`.mjs` tools with an
 `import` syntax needs `"type": "module"` in the nearest `package.json` (or the
 `.mjs` extension).
 
+## Run it with `loushy dev`
+
+```bash
+npx loushy dev ./my-agent
+```
+
+Serves the chat UI and `POST /chat` for the directory and reloads it when
+`instructions.md`, the config file, `tools/`, `skills/` or `subagents/` change
+(see [`loushy dev`](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/cli.md#loushy-dev) for the details). A tool file is
+imported afresh on each reload, so an edit to `tools/*.ts` takes effect on the
+next message. A failed reload (a syntax error, an empty `instructions.md`) is
+logged and shown in the chat page, and the previous agent keeps answering.
+
 ## What is not covered
 
-`loushy dev` and `loushy mcp` still take an agent spec file
-([Configuration](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/configuration.md)), not a directory.
+`loushy mcp` still takes an agent spec file ([Configuration](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/configuration.md)),
+not a directory.
 
 # Agent Forge
 
@@ -2048,7 +2061,7 @@ Run it with `npx loushy <command>` inside a project that has the SDK installed.
 | ------- | ------------ | ------- |
 | `loushy init [dir]` | Scaffold a project: an agent with an example tool, an offline test, `.env.example`; installs dependencies and runs `git init`. | [Installation](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/installation.md#scaffolding-a-new-project) |
 | `loushy doctor [spec] [--json]` | Check Node, peer packages, provider keys, and optionally a spec file; prints a fix for every problem. | [Installation](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/installation.md#troubleshooting-loushy-doctor) |
-| `loushy dev <spec>` | Local dev server for a spec file: chat UI, `POST /chat`, hot reload on save. | [Below](#loushy-dev) |
+| `loushy dev <path>` | Local dev server for a spec file, an agent directory or a TS agent: chat UI, `POST /chat`, hot reload on save. | [Below](#loushy-dev) |
 | `loushy mcp <spec>` | Serve the agent as an MCP server (stdio, or HTTP with `--http`). | [Configuration](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/configuration.md#serve-an-agent-over-mcp) |
 | `loushy eval [globs...]` | Run `*.eval.ts` files under vitest; print a summary and write JUnit/JSON reports. | [Evals](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/evals.md#loushy-eval) |
 | `loushy build --target=<t> --agent=<spec>` | Build a deployable Node server, Docker image or Cloudflare Worker. | [Deployment](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/deployment.md) |
@@ -2061,7 +2074,7 @@ Every command that takes a `<spec>` reads an agent spec file (`.yaml`,
 
 ```text
 loushy init [dir] [--provider P] [--template T] [--yes] [--no-install] [--no-git] [--package-manager PM] [--force]
-loushy dev <config.yaml|config.json> [--port N] [--host H]
+loushy dev <spec.yaml|spec.json|agent-dir|agent.ts> [--port N] [--host H]
 loushy build --target=<name> --agent=<path> [--out=<dir>]
 loushy studio [--port N] [--host H] [--prod|--dev]
 loushy mcp <agent.yaml|json> [--http --port N --host H]
@@ -2077,13 +2090,48 @@ with `node bin/loushy.js init my-agent --sdk-path .` (see
 ## `loushy dev`
 
 ```bash
-npx loushy dev agent.yaml
+npx loushy dev agent.yaml                  # a spec file
+npx loushy dev ./my-agent                  # an agent directory
+npx loushy dev src/agent.ts                # a TypeScript (or JavaScript) module
 npx loushy dev agent.yaml --port 4000 --host 0.0.0.0
 ```
 
-Serves `GET /` (a chat UI), `GET /health` and `POST /chat`
-(`{ "message": "..." }`, 1MB body limit). The agent is reloaded whenever the
-spec file changes, and the last good config is kept if an edit is invalid.
+Serves `GET /` (a chat UI), `GET /health`, `GET /dev/status` and `POST /chat`
+(`{ "message": "..." }`, 1MB body limit). What `<path>` is follows from the path:
+
+| Path | Loaded with |
+| ---- | ----------- |
+| `.yaml`, `.yml`, `.json` | `loadSpec()` + `specToAgent()` ([Configuration](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/configuration.md)) |
+| a directory | `loadAgentDir()` ([Agent directories](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/agent-directories.md)) |
+| `.ts`, `.mts`, `.js`, `.mjs`, `.cjs` | the module's default export, or its `agent` export: a `SimpleAgent` (what `createAgent()` returns) or a `createAgent()` options object |
+
+Any other extension, a missing path, or a module with no agent export fails
+with a coded error (`LOUSHY_SPEC_UNSUPPORTED_FORMAT`, `LOUSHY_CONFIG_INVALID`)
+and its fix. A `.ts` module is imported by the running Node (22.19 or later
+strips types, so relative imports need their file extension); use `.js` for
+code that needs a transpiler.
+
+**Hot reload.** The agent is rebuilt a moment (100 ms) after a file changes,
+without restarting the server or dropping the port:
+
+- a spec: the spec file;
+- a directory: everything under it (`instructions.md`, the config file,
+  `tools/`, `skills/`, `subagents/`), except `node_modules` and `.git`;
+- a module: the file and the local files it imports (relative `import` /
+  `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 `loushy dev` after editing 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
+is logged and shown in a banner on the chat page (and as `error` in
+`GET /dev/status`); the next good edit clears it.
+
+Directories and modules are your code and run with your permissions; only run
+`loushy dev` on ones you trust. `POST /chat` talks to one shared agent, not one
+conversation per browser tab.
 
 - `--port` - default `3737`.
 - `--host` - default `127.0.0.1` (localhost only). Pass e.g. `--host=0.0.0.0`
diff --git a/src/agentDir/importModule.ts b/src/agentDir/importModule.ts
index 890fb10bd..1895535b9 100644
--- a/src/agentDir/importModule.ts
+++ b/src/agentDir/importModule.ts
@@ -1,5 +1,18 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { pathToFileURL } from 'node:url';
 
+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
+ * (`loushy dev` hot reload, LOU-D31). Only the file itself is re-evaluated;
+ * modules it imports stay cached by the runtime.
+ */
+export function withFreshImports<T>(token: string, fn: () => Promise<T>): Promise<T> {
+  return cacheBust.run(token, fn);
+}
+
 /** Node error codes that mean "this process cannot load a TypeScript file". */
 const NO_TS_LOADER_CODES = new Set(['ERR_UNKNOWN_FILE_EXTENSION', 'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX']);
 
@@ -29,7 +42,9 @@ export function explainImportError(file: string, error: unknown): Error {
 /** Dynamically imports a user file, with path-bearing errors (see {@link explainImportError}). */
 export async function importModule(file: string): Promise<Record<string, unknown>> {
   try {
-    return (await import(pathToFileURL(file).href)) as Record<string, unknown>;
+    const token = cacheBust.getStore();
+    const href = pathToFileURL(file).href;
+    return (await import(token === undefined ? href : `${href}?t=${token}`)) as Record<string, unknown>;
   } catch (error) {
     throw explainImportError(file, error);
   }
diff --git a/src/cli/__fixtures__/dev-agent/agent.json b/src/cli/__fixtures__/dev-agent/agent.json
new file mode 100644
index 000000000..25a3d8535
--- /dev/null
+++ b/src/cli/__fixtures__/dev-agent/agent.json
@@ -0,0 +1 @@
+{ "name": "dev-fixture", "description": "loushy dev fixture" }
diff --git a/src/cli/__fixtures__/dev-agent/instructions.md b/src/cli/__fixtures__/dev-agent/instructions.md
new file mode 100644
index 000000000..7648a63c5
--- /dev/null
+++ b/src/cli/__fixtures__/dev-agent/instructions.md
@@ -0,0 +1 @@
+You are the dev fixture agent.
diff --git a/src/cli/__fixtures__/dev-agent/tools/ping.ts b/src/cli/__fixtures__/dev-agent/tools/ping.ts
new file mode 100644
index 000000000..449746006
--- /dev/null
+++ b/src/cli/__fixtures__/dev-agent/tools/ping.ts
@@ -0,0 +1,9 @@
+import { z } from 'zod';
+import { defineTool } from '../../../../tools/defineTool';
+
+export default defineTool({
+  name: 'ping',
+  description: 'Reply with pong',
+  input: z.object({}),
+  execute: () => 'pong',
+});
diff --git a/src/cli/__fixtures__/dev-module/agent.ts b/src/cli/__fixtures__/dev-module/agent.ts
new file mode 100644
index 000000000..3cc5affbb
--- /dev/null
+++ b/src/cli/__fixtures__/dev-module/agent.ts
@@ -0,0 +1,9 @@
+import { createAgent } from '../../../createAgent';
+import { mockModel } from '../../../testing';
+import { GREETING } from './greeting';
+
+export default createAgent({
+  name: 'dev-module',
+  instructions: GREETING,
+  provider: mockModel(['module says hi', 'module says hi']),
+});
diff --git a/src/cli/__fixtures__/dev-module/bad.ts b/src/cli/__fixtures__/dev-module/bad.ts
new file mode 100644
index 000000000..d0741895f
--- /dev/null
+++ b/src/cli/__fixtures__/dev-module/bad.ts
@@ -0,0 +1 @@
+export default { not: 'an agent' };
diff --git a/src/cli/__fixtures__/dev-module/config.ts b/src/cli/__fixtures__/dev-module/config.ts
new file mode 100644
index 000000000..c5267ec2e
--- /dev/null
+++ b/src/cli/__fixtures__/dev-module/config.ts
@@ -0,0 +1 @@
+export const agent = { name: 'dev-config', instructions: 'You are the config-export agent.' };
diff --git a/src/cli/__fixtures__/dev-module/greeting.ts b/src/cli/__fixtures__/dev-module/greeting.ts
new file mode 100644
index 000000000..81235b27b
--- /dev/null
+++ b/src/cli/__fixtures__/dev-module/greeting.ts
@@ -0,0 +1 @@
+export const GREETING = 'You are the dev module agent.';
diff --git a/src/cli/dev-ui/index.html b/src/cli/dev-ui/index.html
index 0ba82f1a9..a324654db 100644
--- a/src/cli/dev-ui/index.html
+++ b/src/cli/dev-ui/index.html
@@ -12,10 +12,13 @@
   button { padding: 0.5rem 1rem; }
   .entry { margin-bottom: 0.5rem; }
   .entry.user { font-weight: 600; }
+  #status { border-radius: 8px; padding: 0.5rem 0.75rem; margin-bottom: 1rem; background: #fde8e8; color: #7a1b1b; white-space: pre-wrap; }
+  #status[hidden] { display: none; }
 </style>
 </head>
 <body>
   <h1>loushy dev</h1>
+  <div id="status" hidden></div>
   <div id="log"></div>
   <div class="row">
     <input id="msg" type="text" placeholder="Say something..." autocomplete="off" />
@@ -57,6 +60,20 @@ <h1>loushy dev</h1>
       }
     }
 
+    // Hot reload (LOU-D31): show the last failed reload; the previous agent keeps answering.
+    const status = document.getElementById('status');
+    async function refreshStatus() {
+      try {
+        const info = await (await fetch('/dev/status')).json();
+        status.hidden = !info.error;
+        status.textContent = info.error ? 'Last reload failed, still serving the previous agent:\n' + info.error : '';
+      } catch (err) {
+        status.hidden = true;
+      }
+    }
+    refreshStatus();
+    setInterval(refreshStatus, 2000);
+
     button.addEventListener('click', send);
     input.addEventListener('keydown', (e) => {
       if (e.key === 'Enter') send();
diff --git a/src/cli/dev.test.ts b/src/cli/dev.test.ts
index b8cee4260..360a79336 100644
--- a/src/cli/dev.test.ts
+++ b/src/cli/dev.test.ts
@@ -1,10 +1,12 @@
-import { describe, it, expect, beforeAll, afterEach } from 'vitest';
+import { describe, it, expect, beforeAll, afterEach, vi } from 'vitest';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { startDevServer, DevServerHandle } from './dev';
 import { LLMProviderRegistry } from '../providers/llm';
 import { createMockProvider } from '../providers/mock';
+import { mockModel } from '../testing';
+import { collectLocalImports, detectTarget } from './devReload';
 
 const MOCK_RESPONSE = 'This is the mock dev-server response.';
 
@@ -198,6 +200,140 @@ describe('hot reload (LOU-H8)', () => {
   });
 });
 
+describe('agent directories and TS modules (LOU-D31)', () => {
+  const fixtures = path.join(__dirname, '__fixtures__');
+  const copies: string[] = [];
+
+  /** A scratch copy of a fixture next to it, so the fixture's relative imports still resolve. */
+  function copyFixture(name: string): string {
+    const copy = fs.mkdtempSync(path.join(fixtures, `tmp-${name}-`));
+    copies.push(copy);
+    fs.cpSync(path.join(fixtures, name), copy, { recursive: true });
+    return copy;
+  }
+  afterEach(() => {
+    for (const copy of copies.splice(0)) fs.rmSync(copy, { recursive: true, force: true });
+  });
+
+  const url = (h: DevServerHandle, route: string) => `http://localhost:${addressPort(h)}${route}`;
+  const chat = async (h: DevServerHandle, message = 'hi') =>
+    (
+      await fetch(url(h, '/chat'), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ message }),
+      })
+    ).json();
+  const status = async (h: DevServerHandle) => (await fetch(url(h, '/dev/status'))).json();
+  async function waitFor(check: () => Promise<boolean>): Promise<void> {
+    for (let i = 0; i < 100; i++) {
+      if (await check()) return;
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    throw new Error('timed out waiting for the dev server');
+  }
+  const systemOf = (call: { messages: readonly { role: string; content: unknown }[] }) =>
+    String(call.messages.find((m) => m.role === 'system')?.content);
+
+  it('detects a spec, a directory and a module by path type and extension, with coded errors otherwise', () => {
+    expect(detectTarget(path.join(fixtures, 'dev-agent')).kind).toBe('dir');
+    expect(detectTarget(path.join(fixtures, 'dev-module', 'agent.ts')).kind).toBe('module');
+    expect(detectTarget('agent.yaml').kind).toBe('spec');
+    expect(() => detectTarget(path.join(fixtures, 'nope.ts'))).toThrow(/LOUSHY_CONFIG_INVALID/);
+    expect(() => detectTarget(path.join(fixtures, 'dev-agent', 'instructions.md'))).toThrow(
+      /LOUSHY_SPEC_UNSUPPORTED_FORMAT/
+    );
+  });
+
+  it('serves an agent directory with loadAgentDir', async () => {
+    const provider = mockModel(['dir says hi']);
+    handle = await startDevServer(path.join(fixtures, 'dev-agent'), 0, '127.0.0.1', { overrides: { provider } });
+
+    expect((await chat(handle)).text).toBe('dir says hi');
+    expect(systemOf(provider.calls[0])).toContain('You are the dev fixture agent.');
+    expect(provider.calls[0].tools?.map((t) => t.function.name)).toEqual(['ping']);
+    expect(await status(handle)).toMatchObject({ kind: 'dir', reloads: 0, error: null });
+  });
+
+  it('serves a TS module whose default export is a SimpleAgent, and accepts a config export', async () => {
+    handle = await startDevServer(path.join(fixtures, 'dev-module', 'agent.ts'), 0);
+    expect((await chat(handle)).text).toBe('module says hi');
+    expect(await status(handle)).toMatchObject({ kind: 'module' });
+    await handle.close();
+
+    const provider = mockModel(['config says hi']);
+    handle = await startDevServer(path.join(fixtures, 'dev-module', 'config.ts'), 0, '127.0.0.1', {
+      overrides: { provider },
+    });
+    expect((await chat(handle)).text).toBe('config says hi');
+    expect(systemOf(provider.calls[0])).toContain('config-export agent');
+  });
+
+  it('rejects a module that exports no agent with a coded error', async () => {
+    await expect(startDevServer(path.join(fixtures, 'dev-module', 'bad.ts'), 0)).rejects.toThrow(
+      /LOUSHY_CONFIG_INVALID/
+    );
+  });
+
+  it('reloads when instructions.md or a tool changes, without restarting the server', async () => {
+    const dir = copyFixture('dev-agent');
+    const provider = mockModel(['ok', 'ok', 'ok']);
+    handle = await startDevServer(dir, 0, '127.0.0.1', { overrides: { provider }, debounceMs: 20 });
+    const server = handle.server;
+    await chat(handle);
+
+    fs.writeFileSync(path.join(dir, 'instructions.md'), 'You are the EDITED agent.\n');
+    await waitFor(async () => (await status(handle!)).reloads >= 1);
+    await chat(handle);
+    expect(systemOf(provider.calls[1])).toContain('EDITED');
+
+    const toolFile = path.join(dir, 'tools', 'ping.ts');
+    fs.writeFileSync(toolFile, fs.readFileSync(toolFile, 'utf8').replace("'ping'", "'ping_v2'"));
+    await waitFor(async () => (await status(handle!)).reloads >= 2);
+    await chat(handle);
+    expect(provider.calls[2].tools?.map((t) => t.function.name)).toEqual(['ping_v2']);
+    expect(handle.server).toBe(server);
+  });
+
+  it('keeps the previous agent after a failed reload and reports the error', async () => {
+    const dir = copyFixture('dev-agent');
+    const provider = mockModel(['ok', 'ok', 'ok']);
+    handle = await startDevServer(dir, 0, '127.0.0.1', { overrides: { provider }, debounceMs: 20 });
+    const quiet = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+
+    fs.writeFileSync(path.join(dir, 'tools', 'ping.ts'), 'export default (');
+    await waitFor(async () => (await status(handle!)).error !== null);
+    expect((await status(handle)).reloads).toBe(0);
+    expect(await chat(handle)).toMatchObject({ text: 'ok' });
+    expect(systemOf(provider.calls[0])).toContain('You are the dev fixture agent.');
+    expect(quiet).toHaveBeenCalledWith(expect.stringContaining('keeping the previous agent'));
+
+    // Fixing the file recovers and clears the error.
+    fs.copyFileSync(path.join(fixtures, 'dev-agent', 'tools', 'ping.ts'), path.join(dir, 'tools', 'ping.ts'));
+    await waitFor(async () => (await status(handle!)).error === null);
+    expect((await status(handle)).reloads).toBe(1);
+    quiet.mockRestore();
+  });
+
+  it('reloads a module when it or a local import changes', async () => {
+    const dir = copyFixture('dev-module');
+    const file = path.join(dir, 'agent.ts');
+    const local = collectLocalImports(file).filter((f) => f.startsWith(dir));
+    expect(local.map((f) => path.basename(f)).sort()).toEqual(['agent.ts', 'greeting.ts']);
+
+    handle = await startDevServer(file, 0, '127.0.0.1', { debounceMs: 20 });
+    expect((await chat(handle)).text).toBe('module says hi');
+
+    fs.writeFileSync(file, fs.readFileSync(file, 'utf8').replaceAll('module says hi', 'edited reply'));
+    await waitFor(async () => (await status(handle!)).reloads >= 1);
+    expect((await chat(handle)).text).toBe('edited reply');
+
+    // An edit to an imported file triggers a reload too.
+    fs.appendFileSync(path.join(dir, 'greeting.ts'), '// touched\n');
+    await waitFor(async () => (await status(handle!)).reloads >= 2);
+  });
+});
+
 function addressPort(h: DevServerHandle): number {
   const addr = h.server.address();
   if (addr && typeof addr === 'object') return addr.port;
diff --git a/src/cli/dev.ts b/src/cli/dev.ts
index df73bcccb..a504c85a3 100644
--- a/src/cli/dev.ts
+++ b/src/cli/dev.ts
@@ -14,17 +14,17 @@
  * designed-for successor) exists - the two shapes are compatible (a plain
  * .json config in the old shape is a valid AgentSpec), so no existing
  * configs need to change.
+ *
+ * Targets (LOU-D31): the path may also be an agent directory (loadAgentDir)
+ * or a .ts/.js module exporting a SimpleAgent / createAgent() config; see
+ * devReload.ts for detection, watching and the reload swap.
  */
 import * as http from 'node:http';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { SimpleAgent } from '../createAgent';
-import { loadSpec } from '../spec/loadSpec';
-import { specToAgent } from '../spec/specToAgent';
+import { detectTarget, startReloader, type DevOptions, type DevState } from './devReload';
 
-function loadAgentFromConfig(configPath: string): SimpleAgent {
-  return specToAgent(loadSpec(configPath));
-}
+export type { DevOptions } from './devReload';
 
 export interface DevServerHandle {
   server: http.Server;
@@ -77,9 +77,7 @@ function serveChatUi(res: http.ServerResponse): void {
  * reads the latest reloaded version without restarting the HTTP server or
  * dropping connections.
  */
-interface AgentHolder {
-  agent: SimpleAgent;
-}
+type AgentHolder = DevState;
 
 type RouteHandler = (
   req: http.IncomingMessage,
@@ -138,8 +136,14 @@ async function handleChat(
   }
 }
 
+function handleStatus(_req: http.IncomingMessage, res: http.ServerResponse, holder: AgentHolder): void {
+  const { target, reloads, error } = holder;
+  sendJson(res, 200, { kind: target.kind, path: target.path, reloads, error: error ?? null });
+}
+
 const ROUTES = new Map<string, RouteHandler>([
   ['GET /health', (_req, res) => sendText(res, 200, 'ok')],
+  ['GET /dev/status', handleStatus],
   ['GET /', handleChatUi],
   ['POST /chat', handleChat],
 ]);
@@ -157,24 +161,6 @@ async function handleRequest(
   await handler(req, res, holder);
 }
 
-/** Reloads the agent into `holder` whenever configPath changes; keeps the old agent on a bad edit. */
-function watchConfig(configPath: string, holder: AgentHolder): fs.FSWatcher {
-  return fs.watch(configPath, { persistent: false }, () => {
-    try {
-      holder.agent = loadAgentFromConfig(configPath);
-      // eslint-disable-next-line no-console
-      console.log(`[loushy dev] reloaded config from ${configPath}`);
-    } catch (error) {
-      // eslint-disable-next-line no-console
-      console.error(
-        `[loushy dev] failed to reload ${configPath}, keeping previous config: ${
-          (error as Error).message
-        }`
-      );
-    }
-  });
-}
-
 function createDevHttpServer(holder: AgentHolder): http.Server {
   return http.createServer((req, res) => {
     handleRequest(req, res, holder).catch((error) => {
@@ -218,30 +204,35 @@ function listenOnPort(server: http.Server, port: number, host: string): Promise<
  * explicit host (e.g. '0.0.0.0') to opt in to LAN access, such as testing
  * from a phone on the same network.
  *
- * Watches configPath (LOU-H8) via fs.watch: on a valid edit, the live
- * agent is swapped in-place through the mutable AgentHolder above; on an
- * invalid edit (e.g. a JSON syntax error, or a missing required field),
- * the error is logged and the previous working agent is kept - the server
- * never crashes and never drops the port on a bad config edit.
+ * `configPath` is a spec file, an agent directory or a .ts/.js agent module
+ * (detected by path type and extension, see `detectTarget`). Its sources are
+ * watched (LOU-H8, LOU-D31): on a valid edit the live agent is swapped
+ * in-place through the mutable AgentHolder above and the previous agent is
+ * closed; on an invalid edit the error is logged and shown in the chat UI,
+ * and the previous working agent is kept - the server never crashes and never
+ * drops the port on a bad edit.
  */
 export async function startDevServer(
   configPath: string,
   port = 3737,
-  host = '127.0.0.1'
+  host = '127.0.0.1',
+  options: DevOptions = {}
 ): Promise<DevServerHandle> {
-  const holder: AgentHolder = { agent: loadAgentFromConfig(configPath) };
-
-  const watcher = watchConfig(configPath, holder);
-  const server = createDevHttpServer(holder);
-  await listenOnPort(server, port, host);
+  const reloader = await startReloader(detectTarget(configPath), options);
+  const server = createDevHttpServer(reloader.state);
+  try {
+    await listenOnPort(server, port, host);
+  } catch (error) {
+    await reloader.close();
+    throw error;
+  }
 
   return {
     server,
     port,
-    close: () =>
-      new Promise<void>((resolve, reject) => {
-        watcher.close();
-        server.close((err) => (err ? reject(err) : resolve()));
-      }),
+    close: async () => {
+      await reloader.close();
+      await new Promise<void>((resolve, reject) => server.close((err) => (err ? reject(err) : resolve())));
+    },
   };
 }
diff --git a/src/cli/devReload.ts b/src/cli/devReload.ts
new file mode 100644
index 000000000..9d8a34691
--- /dev/null
+++ b/src/cli/devReload.ts
@@ -0,0 +1,233 @@
+/**
+ * What `loushy dev` serves and how it hot-reloads it (LOU-D31).
+ *
+ * A target is a spec file (.yaml/.yml/.json), an agent directory, or a
+ * .ts/.js module whose default (or `agent`) export is a `SimpleAgent` or a
+ * `createAgent()` config. {@link startReloader} loads it, watches what it was
+ * built from and swaps a rebuilt agent into the shared {@link DevState}.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createAgent, type CreateAgentConfig, type SimpleAgent } from '../createAgent';
+import { SDKError } from '../execution/errors';
+import { loadAgentDir } from '../agentDir';
+import { explainImportError, withFreshImports } from '../agentDir/importModule';
+import { loadSpec } from '../spec/loadSpec';
+import { specToAgent } from '../spec/specToAgent';
+
+export type DevTargetKind = 'spec' | 'dir' | 'module';
+
+export interface DevTarget {
+  kind: DevTargetKind;
+  /** Absolute path of the spec file, directory or module. */
+  path: string;
+}
+
+/** What `GET /dev/status` reports and what the chat UI shows. */
+export interface DevState {
+  agent: SimpleAgent;
+  target: DevTarget;
+  /** Successful reloads since start. */
+  reloads: number;
+  /** The last failed reload's message; cleared by the next good one. */
+  error?: string;
+}
+
+export interface DevOptions {
+  /** `createAgent()` options that win over what the target says (e.g. a test provider). */
+  overrides?: CreateAgentConfig;
+  /** Wait this long after the last file change before reloading. Default 100. */
+  debounceMs?: number;
+}
+
+const SPEC_EXT = new Set(['.yaml', '.yml', '.json']);
+const MODULE_EXT = new Set(['.ts', '.mts', '.cts', '.js', '.mjs', '.cjs']);
+const RESOLVE_EXT = ['.ts', '.mts', '.cts', '.js', '.mjs', '.cjs', '.json'];
+const TARGET_HINT = 'Pass an agent spec (.yaml/.yml/.json), an agent directory, or a .ts/.js module that exports an agent.';
+
+function log(message: string): void {
+  console.log(`[loushy dev] ${message}`);
+}
+
+/** Picks the target kind from the path: a directory, a spec by extension, or a module by extension. */
+export function detectTarget(rawPath: string): DevTarget {
+  const file = path.resolve(rawPath);
+  const ext = path.extname(file).toLowerCase();
+  if (fs.existsSync(file) && fs.statSync(file).isDirectory()) return { kind: 'dir', path: file };
+  // A missing spec keeps failing inside loadSpec, as it always did.
+  if (SPEC_EXT.has(ext)) return { kind: 'spec', path: file };
+  if (!fs.existsSync(file)) {
+    throw new SDKError(`loushy dev: '${rawPath}' does not exist.`, 'LOUSHY_CONFIG_INVALID', { hint: TARGET_HINT });
+  }
+  if (MODULE_EXT.has(ext)) return { kind: 'module', path: file };
+  throw new SDKError(
+    `loushy dev: unsupported file type '${ext || '(none)'}' for '${rawPath}'.`,
+    'LOUSHY_SPEC_UNSUPPORTED_FORMAT',
+    { hint: TARGET_HINT }
+  );
+}
+
+function isSimpleAgent(value: unknown): value is SimpleAgent {
+  const v = value as Partial<SimpleAgent> | null;
+  return typeof v === 'object' && v !== null && typeof v.send === 'function' && typeof v.close === 'function';
+}
+
+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> {
+  let mod: Record<string, unknown>;
+  try {
+    mod = (await import(`${pathToFileURL(file).href}?t=${token}`)) as Record<string, unknown>;
+  } catch (error) {
+    throw explainImportError(file, error);
+  }
+  const exported = mod.default ?? mod.agent;
+  if (isSimpleAgent(exported)) return exported;
+  if (isAgentConfig(exported)) return createAgent({ ...exported, ...overrides } as CreateAgentConfig);
+  throw new SDKError(
+    `loushy dev: ${file} must export a SimpleAgent or a createAgent() config as its default export (or as 'agent').`,
+    'LOUSHY_CONFIG_INVALID',
+    { hint: "Add 'export default createAgent({ ... })', or export the createAgent() options object." }
+  );
+}
+
+let loads = 0;
+
+/**
+ * Builds the agent a target describes. Directory and module loads import the
+ * edited files afresh (`?t=` cache-bust); they also `ready()` the agent so MCP
+ * connection errors surface here.
+ */
+async function loadTarget(target: DevTarget, options: DevOptions = {}): Promise<SimpleAgent> {
+  const overrides = options.overrides ?? {};
+  if (target.kind === 'spec') return specToAgent(loadSpec(target.path));
+  const token = `${Date.now()}-${loads++}`;
+  const agent = await withFreshImports(token, () =>
+    target.kind === 'dir' ? loadAgentDir(target.path, overrides) : loadModuleAgent(target.path, token, overrides)
+  );
+  try {
+    await agent.ready();
+  } catch (error) {
+    await agent.close().catch(() => undefined);
+    throw error;
+  }
+  return agent;
+}
+
+const IMPORT_SPECIFIER = /(?:\bfrom\s*|\bimport\s*\(?\s*|\brequire\s*\(\s*)['"](\.{1,2}\/[^'"]*)['"]/g;
+
+function isFile(file: string): boolean {
+  return fs.existsSync(file) && fs.statSync(file).isFile();
+}
+
+function resolveImport(from: string, specifier: string): string | undefined {
+  const base = path.resolve(path.dirname(from), specifier);
+  // './x.js' written for an './x.ts' source (NodeNext style) is tried too.
+  const stems = [base, base.replace(/\.[cm]?js$/, '')];
+  const candidates = stems.flatMap((s) => [s, ...RESOLVE_EXT.map((e) => s + e), ...RESOLVE_EXT.map((e) => path.join(s, `index${e}`))]);
+  return candidates.find(isFile);
+}
+
+/** `entry` plus every file it imports through relative specifiers, walked once (no bundler, no node_modules). */
+export function collectLocalImports(entry: string): string[] {
+  const seen = new Set<string>();
+  const queue = [entry];
+  for (let file = queue.pop(); file !== undefined; file = queue.pop()) {
+    if (seen.has(file)) continue;
+    seen.add(file);
+    if (!/\.[cm]?[jt]s$/.test(file)) continue;
+    for (const match of fs.readFileSync(file, 'utf8').matchAll(IMPORT_SPECIFIER)) {
+      const resolved = resolveImport(file, match[1]);
+      if (resolved) queue.push(resolved);
+    }
+  }
+  return [...seen];
+}
+
+const IGNORED_SEGMENT = /(^|[\\/])(node_modules|\.git)([\\/]|$)/;
+
+/** Watches the target's sources; calls `onChange` with the name that changed (relative to the target's folder). */
+function watchTarget(target: DevTarget, onChange: (name: string) => void): () => void {
+  const watchers: fs.FSWatcher[] = [];
+  if (target.kind === 'dir') {
+    watchers.push(
+      fs.watch(target.path, { recursive: true, persistent: false }, (_event, name) => {
+        if (name === null || !IGNORED_SEGMENT.test(name)) onChange(name ?? '');
+      })
+    );
+  } else {
+    // Watch parent directories: editors replace files on save, which kills a per-file watcher.
+    const files = target.kind === 'module' ? collectLocalImports(target.path) : [target.path];
+    const wanted = new Set(files);
+    const root = path.dirname(target.path);
+    for (const dir of new Set(files.map((f) => path.dirname(f)))) {
+      watchers.push(
+        fs.watch(dir, { persistent: false }, (_event, name) => {
+          if (name === null || wanted.has(path.join(dir, name))) onChange(path.relative(root, path.join(dir, name ?? '')));
+        })
+      );
+    }
+  }
+  return () => watchers.forEach((w) => w.close());
+}
+
+export interface DevReloader {
+  state: DevState;
+  /** Waits for a reload in progress, stops watching and closes the live agent. */
+  close: () => Promise<void>;
+}
+
+/**
+ * Loads `target` and keeps `state.agent` current as its files change
+ * (debounced). A reload builds and readies the new agent first, then swaps it
+ * in and closes the previous one. If building fails, the last good agent
+ * stays, `state.error` is set and the error is logged.
+ */
+export async function startReloader(target: DevTarget, options: DevOptions = {}): Promise<DevReloader> {
+  const state: DevState = { agent: await loadTarget(target, options), target, reloads: 0 };
+  const changed = new Set<string>();
+  const name = path.basename(target.path);
+  let timer: NodeJS.Timeout | undefined;
+  let running: Promise<void> = Promise.resolve();
+  let closed = false;
+
+  async function reload(): Promise<void> {
+    const what = [...changed].filter(Boolean).join(', ') || name;
+    changed.clear();
+    try {
+      const next = await loadTarget(target, options);
+      if (closed) return void (await next.close());
+      const previous = state.agent;
+      state.agent = next;
+      state.reloads += 1;
+      delete state.error;
+      await previous.close().catch(() => undefined);
+      log(`reloaded ${name} (changed: ${what})`);
+    } catch (error) {
+      state.error = error instanceof Error ? error.message : String(error);
+      console.error(`[loushy dev] failed to reload ${name}, keeping the previous agent: ${state.error}`);
+    }
+  }
+
+  const stop = watchTarget(target, (changedName) => {
+    changed.add(changedName);
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      running = running.then(reload);
+    }, options.debounceMs ?? 100);
+  });
+
+  return {
+    state,
+    close: async () => {
+      closed = true;
+      clearTimeout(timer);
+      stop();
+      await running;
+      await state.agent.close().catch(() => undefined);
+    },
+  };
+}