diff --git a/.fallowrc.json b/.fallowrc.json
index 4ceaf9526..529aa3531 100644
--- a/.fallowrc.json
+++ b/.fallowrc.json
@@ -16,6 +16,9 @@
     // `new Worker(new URL('./layout.worker.ts', import.meta.url))` in
     // apps/agent-forge/src/canvas/layout.ts (C17).
     "apps/agent-forge/src/canvas/layout.worker.ts",
+    // The packaged Studio's `lousho-studio` bin and its pack-time SDK-range pin.
+    "apps/agent-forge/server/cli.ts",
+    "apps/agent-forge/scripts/pin-sdk-range.mjs",
     // The <forge-chat> widget bundle (X04b): vite.widget.config.ts's
     // lib.entry is not visible to the import graph.
     "apps/agent-forge/src/widget/entry.ts",
@@ -100,7 +103,7 @@
     "@ai-sdk/anthropic",
     "@ai-sdk/google",
     "@ai-sdk/openai",
-    "lousho",
+    "@linuxdevil/lousho",
     "ollama-ai-provider",
     "ollama-ai-provider-v2",
     "prompts"
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index f50328cd3..8b0099ab1 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -31,7 +31,7 @@ What did you run, and what did it show? Name anything you couldn't verify, such
 
 ## Release
 
-Merging doesn't publish. The Release workflow publishes `lousho` and `create-lousho` to npm as `latest` every Monday at 06:00 UTC, or when run by hand, so everyone on a default install gets this change in the next release. The `Unreleased` entry above becomes that release's notes.
+Merging publishes `@linuxdevil/lousho` and `create-lousho` to npm as `latest`, so everyone on a default install gets this change.
 
 - [ ] This PR doesn't need a release on its own, so I added the `norelease` label. The weekly run skips when every PR since the last release has it
 
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 4a15e953d..19c3dec76 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -51,9 +51,7 @@ jobs:
       - run: npm run registry:check
       # schemas/ is generated from the workspace contracts; fail if stale.
       - run: npm run workspaces:schema:check
-      # Agent Forge imports the SDK as `lousho` via `file:../..`, i.e. the root dist/ built above.
-      - run: npm run typecheck --workspace apps/agent-forge
-      - run: npm run typecheck:server --workspace apps/agent-forge
+      # Agent Forge typechecks moved to the dedicated `studio` job (W15a).
   zod4:
     runs-on: ubuntu-latest
     steps:
@@ -66,8 +64,11 @@ jobs:
       - run: npm install --no-save zod@4
       - run: npx tsc --noEmit
       - run: npm run typecheck:tests
-  forge:
+  # @linuxdevil/studio (apps/agent-forge): its own package since W13. Builds the SDK first (Studio depends on it through
+  # file:../.. in the monorepo), then Studio's checks, then packs both and smoke-tests the install.
+  studio:
     runs-on: ubuntu-latest
+    timeout-minutes: 25
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
@@ -75,11 +76,67 @@ jobs:
           node-version: '22.19.0'
           cache: 'npm'
       - run: npm ci
-      - run: npm run build -- --no-dts
-      - run: npm run test --workspace apps/agent-forge -- --run
-      - run: npm run test:server --workspace apps/agent-forge
+      - run: npm run build
+        env:
+          NODE_OPTIONS: --max-old-space-size=12288
+      - run: npm run typecheck --workspace apps/agent-forge
+      - run: npm run typecheck:server --workspace apps/agent-forge
       # Studio imports only public SDK exports (PLAN §19.7).
       - run: npm run lint:imports --workspace apps/agent-forge
+      - run: npm run test --workspace apps/agent-forge -- --run
+      - run: npm run test:server --workspace apps/agent-forge
+      # W15b: the same bridge-compat matrix against the SDK in this commit.
+      - run: npm run test:bridge-compat --workspace apps/agent-forge
+      - run: npm run build:studio
+      # Packs the SDK and @linuxdevil/studio, dry-run publishes Studio, installs both in a fresh project, and checks
+      # that `lousho-studio` and `lousho studio` serve the UI. Never publishes.
+      - run: npm run pack-smoke:studio -- --skip-build
+  # W15b: the same bridge-compat matrix against the OLDEST SDK release Studio
+  # still supports (MIN_BRIDGE_SDK_VERSION in server/host/sdkCompat.ts). When
+  # that version is not on npm yet the job skips with a notice; once it is
+  # published this runs the suite against the real installed package.
+  bridge-compat-min:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22.19.0'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build
+        env:
+          NODE_OPTIONS: --max-old-space-size=12288
+      - name: Resolve MIN_BRIDGE_SDK_VERSION
+        id: min
+        run: |
+          v=$(npx tsx -e "import { MIN_BRIDGE_SDK_VERSION } from './apps/agent-forge/server/host/sdkCompat.ts'; console.log(MIN_BRIDGE_SDK_VERSION)")
+          echo "version=$v" >> "$GITHUB_OUTPUT"
+      - name: Check the minimum SDK is published
+        id: pub
+        env:
+          MIN: ${{ steps.min.outputs.version }}
+        run: |
+          if npm view "@linuxdevil/lousho@$MIN" version > /dev/null 2>&1; then
+            echo "published=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "published=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::@linuxdevil/lousho@$MIN is not published yet - bridge-compat-min skips until it is."
+          fi
+      - name: Install the minimum SDK
+        if: steps.pub.outputs.published == 'true'
+        env:
+          MIN: ${{ steps.min.outputs.version }}
+        run: |
+          mkdir -p "$RUNNER_TEMP/min-sdk" && cd "$RUNNER_TEMP/min-sdk"
+          npm init -y > /dev/null
+          npm install "@linuxdevil/lousho@$MIN" ai@7 zod@4 --no-audit --no-fund
+      - name: Run the compat suite against it
+        if: steps.pub.outputs.published == 'true'
+        env:
+          MIN: ${{ steps.min.outputs.version }}
+          LOUSHO_BRIDGE_SDK_DIR: ${{ runner.temp }}/min-sdk/node_modules/@linuxdevil/lousho
+        run: npm run test:bridge-compat --workspace apps/agent-forge
   test:
     runs-on: ubuntu-latest
     steps:
diff --git a/.gitignore b/.gitignore
index 12480d960..dd7bc06eb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -81,3 +81,6 @@ snip.txt
 # Author eval run outputs (npm run eval:author --workspace apps/agent-forge).
 # baseline.json is committed and lives one level up at evals/author/.
 apps/agent-forge/evals/author/results/*.json
+
+# Studio pack-time SDK-range pin backup
+.package.json.prepack
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9cf81d763..00417628e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,898 +1,904 @@
-# Changelog
-
-All notable changes to @lousho/build-ai-agent will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-- New `lousho/observe` subpath: `startObserveDaemon`, `probeHealth`, `isObserveDaemon`, `defaultDbPath`, `OBSERVE_DEFAULT_PORT` and the daemon option/retention defaults, so a host process (Studio) can run and probe the collector through public exports.
-- `lousho bridge`: a new command that speaks Studio's bridge protocol (NDJSON on stdin/stdout, protocol 1) so Lousho Studio can build and run a project's agents with that project's own SDK and dependencies. It answers `hello`, `catalog`, `compile` and `shutdown`, and runs agents: `run`/`chat` start a run or chat turn, `steer`/`abort` control it, `resolveApproval`/`answerQuestion` resume a paused run, and every `AgentEvent`, trace span, steer join and run settle arrives as a pushed event (flows are refused with `LOUSHO_HOST_UNSUPPORTED`).
-- Model strings resolve any official AI SDK provider: `mistral/...`, `groq/...`, `xai/...`, `bedrock/...`, `vertex/...`, `azure/...` and 13 more load `@ai-sdk/<vendor>` on the first call, and `ai-sdk/<vendor>/<model>` loads any other `@ai-sdk/*` package. The package reads its own credentials. See [Providers](docs/providers.md#any-ai-sdk-vendor-by-name).
-
-## [1.0.0-alpha.117] - 2026-11-09
-
-## [1.0.0-alpha.116] - 2026-11-09
-
-## [1.0.0-alpha.115] - 2026-11-09
-
-## [1.0.0-alpha.114] - 2026-11-09
-
-## [1.0.0-alpha.113] - 2026-11-09
-
-## [1.0.0-alpha.112] - 2026-11-09
-
-## [1.0.0-alpha.111] - 2026-11-09
-
-## [1.0.0-alpha.110] - 2026-11-09
-
-## [1.0.0-alpha.109] - 2026-11-09
-
-## [1.0.0-alpha.108] - 2026-11-09
-
-## [1.0.0-alpha.107] - 2026-11-09
-
-## [1.0.0-alpha.106] - 2026-11-09
-
-## [1.0.0-alpha.105] - 2026-11-09
-
-## [1.0.0-alpha.104] - 2026-11-09
-
-## [1.0.0-alpha.103] - 2026-11-08
-
-## [1.0.0-alpha.102] - 2026-11-08
-
-## [1.0.0-alpha.101] - 2026-11-08
-
-## [1.0.0-alpha.100] - 2026-11-08
-
-## [1.0.0-alpha.99] - 2026-11-08
-
-## [1.0.0-alpha.98] - 2026-11-08
-
-## [1.0.0-alpha.97] - 2026-11-08
-
-## [1.0.0-alpha.96] - 2026-11-08
-
-## [1.0.0-alpha.95] - 2026-11-08
-
-## [1.0.0-alpha.94] - 2026-11-08
-
-## [1.0.0-alpha.93] - 2026-11-08
-
-## [1.0.0-alpha.92] - 2026-11-08
-
-## [1.0.0-alpha.91] - 2026-11-08
-
-## [1.0.0-alpha.90] - 2026-11-08
-
-## [1.0.0-alpha.89] - 2026-11-08
-
-## [1.0.0-alpha.88] - 2026-11-08
-
-## [1.0.0-alpha.87] - 2026-11-08
-
-## [1.0.0-alpha.86] - 2026-11-08
-
-## [1.0.0-alpha.85] - 2026-11-08
-
-## [1.0.0-alpha.84] - 2026-11-08
-
-## [1.0.0-alpha.83] - 2026-11-08
-
-## [1.0.0-alpha.82] - 2026-11-08
-
-## [1.0.0-alpha.81] - 2026-11-08
-
-## [1.0.0-alpha.80] - 2026-11-08
-
-## [1.0.0-alpha.79] - 2026-11-08
-
-## [1.0.0-alpha.78] - 2026-11-08
-
-## [1.0.0-alpha.77] - 2026-11-08
-
-## [1.0.0-alpha.76] - 2026-11-08
-
-## [1.0.0-alpha.75] - 2026-11-08
-
-## [1.0.0-alpha.74] - 2026-11-08
-
-## [1.0.0-alpha.73] - 2026-11-08
-
-## [1.0.0-alpha.72] - 2026-11-08
-
-## [1.0.0-alpha.71] - 2026-11-08
-
-## [1.0.0-alpha.70] - 2026-11-08
-
-## [1.0.0-alpha.69] - 2026-11-08
-
-## [1.0.0-alpha.68] - 2026-11-08
-
-## [1.0.0-alpha.67] - 2026-11-08
-
-## [1.0.0-alpha.66] - 2026-11-08
-
-## [1.0.0-alpha.65] - 2026-11-08
-
-## [1.0.0-alpha.64] - 2026-11-08
-
-## [1.0.0-alpha.63] - 2026-11-08
-
-## [1.0.0-alpha.62] - 2026-11-08
-
-## [1.0.0-alpha.61] - 2026-11-08
-
-## [1.0.0-alpha.60] - 2026-11-08
-
-## [1.0.0-alpha.59] - 2026-11-08
-
-## [1.0.0-alpha.58] - 2026-11-08
-
-## [1.0.0-alpha.57] - 2026-11-08
-
-## [1.0.0-alpha.56] - 2026-11-08
-
-## [1.0.0-alpha.55] - 2026-11-08
-
-## [1.0.0-alpha.54] - 2026-11-08
-
-## [1.0.0-alpha.53] - 2026-11-07
-
-## [1.0.0-alpha.52] - 2026-11-07
-
-## [1.0.0-alpha.51] - 2026-11-07
-
-## [1.0.0-alpha.50] - 2026-11-07
-
-## [1.0.0-alpha.49] - 2026-11-07
-
-## [1.0.0-alpha.48] - 2026-11-07
-
-## [1.0.0-alpha.47] - 2026-11-07
-
-## [1.0.0-alpha.46] - 2026-11-07
-
-## [1.0.0-alpha.45] - 2026-11-07
-
-## [1.0.0-alpha.44] - 2026-11-07
-
-## [1.0.0-alpha.43] - 2026-11-07
-
-## [1.0.0-alpha.42] - 2026-11-07
-
-## [1.0.0-alpha.41] - 2026-11-07
-
-## [1.0.0-alpha.40] - 2026-11-07
-
-## [1.0.0-alpha.39] - 2026-11-07
-
-## [1.0.0-alpha.38] - 2026-11-07
-
-## [1.0.0-alpha.37] - 2026-11-07
-
-## [1.0.0-alpha.36] - 2026-11-07
-
-## [1.0.0-alpha.35] - 2026-11-07
-
-## [1.0.0-alpha.34] - 2026-11-07
-
-## [1.0.0-alpha.33] - 2026-11-07
-
-## [1.0.0-alpha.32] - 2026-11-07
-
-- Install docs use the public npm packages again (`npm install lousho`, `npm create lousho`).
-- `lousho/improve` (experimental): `improveAgent()` proposes tested edits to an agent's instructions and skills, offline, gated against the current harness and held-out cases. It applies nothing. See [Improving an agent](docs/improve.md).
-- `agent.recover({ retryWithDiagnosis: true })` gives a run that reached `maxAttempts` one fork told why it failed, before quarantining it. `createOutputCheck()` is a new hook that runs your check after a tool succeeds and tells the model what it found. A fork no longer inherits `lastError` and `attempts` from its source.
-- **Behavior change:** `agent.recover()` no longer resumes a failing run forever. It backs off exponentially from the last failure (up to 15 minutes) and stops after `maxAttempts` failures in a row (default 10), calling the new `onQuarantined(run)` once. `agent.resume()` still runs a quarantined run. Pass a larger `maxAttempts` to keep retrying longer.
-- `lousho observe failures` also lists runs whose process died and scores below `--min-score` (default 0.5).
-- `agent.recover()` pauses during a provider outage instead of using up each run's attempts: after 3 provider failures in a row it stops resuming, probes with one run at growing intervals, and reports through the new `onOutage(paused)`.
-- `createProgressGuard()` gains `maxSameResults` (default 5), which denies a tool that keeps returning the same result even when its arguments differ. Run spans record `lousho.run.finish_reason`, and `lousho observe failures` lists runs that ended without an answer and names rate limits.
-- `lousho observe failures` lists recurring tool and model failures by agent, from the observe database or from trace files (`--traces`), each with a class and trace ids. See [Observability](docs/observability.md).
-- `createProgressGuard()`: an opt-in hook that adds advice to repeated tool failures, denies calls that keep returning the same result and tools that keep failing the same way, and stops the run with `LOUSHO_RUN_NO_PROGRESS` if denials continue. Actions stream as the new `heal.action` event; tool hooks get `ctx.emit`, and tool spans record `lousho.tool.replaced_by_hook`. See [Hooks](docs/hooks.md#stop-a-run-that-makes-no-progress).
-
-## [1.0.0-alpha.31] - 2026-11-01
-
-- **Behavior change:** the package is renamed from `@lousho/build-ai-agent` to `lousho`, and the scaffolder from `create-lousho-agent` to `create-lousho` (`npm create lousho`). Update imports from `@lousho/build-ai-agent` to `lousho` (subpaths such as `lousho/testing` keep their names). Install with `npm install lousho` or `npm create lousho` (no token needed). The packages are also mirrored to GitHub Packages as `@linuxdevil/lousho` and `@linuxdevil/create-lousho` for the repository's Packages tab.
-
-## [1.0.0-alpha.30] - 2026-10-31
-
-What is on `main` and not yet on npm. Entries marked **Behavior change** can
-break working code; [Upgrading](docs/upgrading.md) lists each one with its
-opt-out.
-
-### Added
-
-- The `lousho observe` daemon: a local collector (loopback, `http://127.0.0.1:7777`, SQLite at `~/.lousho/observe.db`) that gathers every agent's traces, heartbeats and eval scores when `LOUSHO_OBSERVE` is set — no per-agent code changes. `lousho observe start|status|stop|rebuild-rollups|token create`; a second `start` on a busy port attaches when it is already the observe daemon. See [Observability](docs/observability.md#the-observe-daemon).
-- Agent Forge is rebuilt around a left navigation grouped Build (Agents, Playground), Observe (Traces, Threads, Monitoring), Evaluate (Evaluations: Scores, Datasets, Evaluators, Annotation queues) and Assets (Prompts, Context Hub), plus Settings. It replaces the Build/Observe toggle and the old Observe tabs, and the Build toolbar shows only on Agents. See [Agent Forge](docs/agent-forge.md#navigation).
-- Every Studio screen has a hash route with its filters in the query string (`#/traces?agent=…&status=error`, `#/traces/<id>?obs=<step>`), so a reload, a bookmark, a pasted link or back/forward lands on the same view. See [Routes and deep links](docs/agent-forge.md#routes-and-deep-links).
-- Studio keyboard: `Ctrl+K` / `Cmd+K` opens a command palette (go to a screen, open an agent, open a pasted trace id, toggle the light/dark theme), `?` lists the shortcuts, and `j`/`k`/`Enter` move through and open table rows. See [Keyboard](docs/agent-forge.md#keyboard).
-- The last Studio nav item shows whether the collector answers. While the daemon is down, each daemon screen shows the command to start it and fills in once it is back. Daemon screens read it through the token-gated `/observe/**` proxy on the studio server, which forwards reads plus only the writes the screens make. See [The collector](docs/agent-forge.md#the-collector-observe-daemon).
-- Studio Traces and Trace screens: the list filters by search (name, input, output), agent, status, model, project, prompt and time range (15m to 30d or custom, default 24 h), sorts by duration, tokens or cost, and shows input/output previews, the error message and the model. A trace opens in one viewer (tree or waterfall, the failed step selected by default) whose inspector shows the error, input and output as chat bubbles with tool-call chips (Rendered, Raw or JSON), thumbs up/down feedback, usage and attributes; the header links the agent and thread and has **Copy link**, **Add to dataset** and **Add to queue**. Model-call steps carry **Open in Playground**. See [Traces](docs/agent-forge.md#traces).
-- Studio Threads (`#/threads`, one row per session, a session's turns oldest first), Monitoring (`#/monitoring`: the fleet table with status, last heartbeat, runs today, error rate, p95 latency and dropped events, plus Runs, Latency p95, Error rate, Cost and Tokens charts over 1h to 30d whose buckets open the matching traces) and Scores (`#/evals/scores`: one row per eval with pass rate, trend, per-check pass rates and latest failures, filtered by eval, agent, source and range). See [Monitoring](docs/agent-forge.md#monitoring).
-- Studio Playground (`#/playground`): system, user and assistant messages with `{name}` variables, a provider and model (`mock` with no key), tools borrowed from a saved agent, a streamed run with **Stop**, **Open trace** when it finishes, and **Save as new prompt version**. See [Playground](docs/agent-forge.md#playground).
-- Playground deep links: `#/playground?trace=<id>&fromObs=<obs>` loads a model call from a trace, and `#/playground?prompt=<name>[@<ref>]` loads a registry prompt.
-- `POST /playground/run` on the studio server runs a playground request and streams SSE `delta`, `tool_call`, `done` and `error` events; runs report to the daemon as agent `playground`. See [Playground run endpoint](docs/agent-forge.md#playground-run-endpoint).
-- Studio Prompts (`#/prompts`: versions, labels, runs that used each version, a side-by-side diff, **Move `<label>` here**, **Open in Playground**) and Context Hub (`#/hub`: namespaces viewed as one agent, `private` or `fleet` scope, and editing a fleet entry). See [Prompts](docs/agent-forge.md#prompts).
-- The Agents builder: node cards show the model, tool count and status; an empty canvas offers templates; Inspector sections collapse and the bottom drawer resizes (both remembered); and a run's status pill links **Open trace**. Builder runs report to the observe daemon under their agent id, with captured content kept out of the project's trace files. See [Agents](docs/agent-forge.md#agents).
-- Datasets: the daemon stores named datasets of `{ input, expected? }` examples (`GET`/`POST /api/v1/datasets`, `GET /api/v1/datasets/:name`, `POST /api/v1/datasets/:name/examples` with an example or `{ from_trace_id }`, which copies a trace's root input and output, and `DELETE …/examples/:id`). `defineEval({ dataset: 'name' })` in place of `cases` runs one test per example (`c` is `{ input, expected, label, example_id, source_trace_id }`) and fails with `LOUSHO_DATASET_UNAVAILABLE` when the daemon cannot serve it. Studio's `#/evals/datasets` lists, creates and browses datasets and deletes examples, and a trace's **Add to dataset** copies it into one. See [Datasets](docs/observability.md#datasets) and [Evals](docs/evals.md#from-the-daemon).
-- Online evaluator rules: `/api/v1/evaluators` holds rules with a `filter` on agent, status and name, a `sample_rate` and an `enabled` switch. Each enabled rule scores new traces as their root ends, as `source: online` scores named after the rule. See [Online evaluator rules](docs/observability.md#online-evaluator-rules).
-- Code evaluators: a `code` rule is a function `(trace) => number | { value, comment }` the daemon runs in the isolate sandbox. It needs `isolated-vm`, plus `NODE_OPTIONS=--no-node-snapshot` on Node 20+; without them code rules are skipped with one warning. `POST /api/v1/evaluators/:id/test` dry-runs a rule on one trace without writing a score. See [Online evaluators](docs/observability.md#online-evaluators).
-- Judge evaluators: a `judge` rule is a model and a rubric. The daemon queues a job per matching trace, and Agent Forge runs the judge with its provider keys (a key saved in Settings, or the provider's env var; the saved key wins), so judges run only while Studio is running. `LOUSHO_STUDIO_JUDGE=0` turns Studio's judge loop off. Studio's `/observe/api/v1/evaluators/:id/test` dry-runs judge rules too. See [Judge rules](docs/observability.md#judge-rules-through-agent-forge).
-- Studio Evaluators screen (`#/evals/evaluators`): lists the rules with their last run and runs in the last 24 hours, and creates, edits, enables, disables and deletes them. **Test on trace** dry-runs a rule on one trace id. The judge kind stays disabled until Studio has a provider key, saved in Settings or set in the provider's env var. See [Evaluators](docs/agent-forge.md#evaluators).
-- Annotation queues: `/api/v1/queues` holds named lists of traces with an optional rubric (`name`, `description`, `min`, `max` per score); `GET /api/v1/queues/:id/next` returns the oldest pending item and `POST …/items/:item/complete` writes its scores as human scores (or skips it). Studio's `#/evals/queues` creates queues and reviews them one trace at a time beside the rubric (Enter submits, `S` skips), and a trace's **Add to queue** adds it. See [Annotation queues](docs/observability.md#annotation-queues).
-- Human feedback scores: `POST /api/v1/scores` `{ trace_id, obs_id?, name, value, comment? }` adds a `source: human` score (`201 { score_id }`; unknown trace or step `404`). Each eval case also records one `<evalName>` score: 1 when no gate check failed and the case did not throw, else 0 with the failed gates in the comment. See [The observe daemon](docs/observability.md#the-observe-daemon).
-- Prompt labels: a label (`prod`, `staging`) points at one version; `lousho prompt label <name> <label> <version>` (or `PUT /api/v1/prompts/:name/labels/:label`) moves it, `push --labels` sets it on the pushed version, and `createAgent({ prompt: 'name@prod' })`, `lousho prompt get name@prod` and `GET /api/v1/prompts/:name/:ref` resolve it. A push whose text and variables equal the latest version's mints nothing (`unchanged: true`). See [`lousho prompt`](docs/cli.md#lousho-prompt).
-- Trace list API: `GET /api/v1/traces` takes `from`/`to` (half-open ms), `q` (substring of name, input or output), `min_duration_ms`, `model`, `prompt` (`<name>[@<version>]`), `sort` (`start`, `duration`, `tokens`, `cost`) and `order`, and rows add `agent_name`, `model`, `error_message` and input/output previews. See [Trace list API](docs/observability.md#trace-list-api).
-- Sessions API: `GET /api/v1/sessions` (filter by agent, status and start window, paged) and `GET /api/v1/sessions/:id` (the session and its traces, oldest first) with per-session trace counts, tokens, cost and last input. See [Sessions API](docs/observability.md#sessions-threads-api).
-- Retention: once a day the daemon deletes finished traces whose last observation ended more than `lousho observe start --retention-days N` ago (default 30, `0` keeps everything), with their scores and prompt-use links, plus older scores whose trace is gone and sessions that are not `active` and no run references. A trace with a run still open and an `active` session are kept. Rollups, prompts, hub entries, the agent registry, tokens, datasets, evaluator rules and annotation queues are never pruned. `lousho observe prune --older-than <N>d` prunes now and runs `VACUUM`. See [Retention](docs/observability.md#retention).
-- `lousho observe export [--since 7d] [--agent X] [--out file]` writes traces as JSONL (`{ trace, observations, scores }` per line) straight from the db, without a running daemon. See [Export](docs/observability.md#export).
-- Insights series carry `p95_latency_ms` and `error_rate` per agent and bucket. A db written by an older daemon lacks them for past buckets: run `lousho observe rebuild-rollups` once to backfill. See [The observe daemon](docs/observability.md#the-observe-daemon).
-- Heartbeats carry the reporter's dropped-event count, and each `/api/v1/agents` row shows it as `dropped` (`null` for older SDKs); Studio's Monitoring fleet table shows it. See [The observe daemon](docs/observability.md#the-observe-daemon) and [Monitoring](docs/agent-forge.md#monitoring).
-- Prompt registry: `createAgent({ prompt: 'name@version' })` or `LOUSHO_PROMPT` resolves versioned instructions from the daemon at build; every run records the version used. `lousho prompt push|list|get` manages it. When the daemon is unreachable, embedded `instructions` are used; with no `instructions` the agent fails closed: every run rejects with `LOUSHO_PROMPT_UNRESOLVED` instead of running without a system prompt. A failed fetch is not cached for good: runs in the next 30 seconds resolve at once, then the next run fetches again (waiting up to 2.5 seconds).
-- Context hub: `hub()` / `hubTools()` publish and query namespaced shared memory scoped `private` (the writing agent) or `fleet` (every agent on the daemon).
-- Fleet monitoring: heartbeat-derived agent status, `agent.deregister` on graceful exit, a crashed agent's open sessions and unfinished observations flip to `interrupted`, and webhook alerts (`--webhook`, `alerts.json`) on down transitions and error-rate thresholds.
-- Eval scores report to the daemon: every `AssertionResult` lands as a score row on the exercised run's trace (`source: eval` or `judge`); `lousho eval --observe` forces emission. Each case's `eval` span and score rows are flushed when the case finishes, each wait capped at 1 second; the scores share the reporter's queue, so they go out after the span and are retried while the daemon is down. A wait that runs out skips the waits of the next 30 seconds of cases.
-- Reporting to the daemon: spans that finished without an error report status `ok`. A down daemon's batches are requeued and retried with exponential backoff (1 s up to 30 s); batches are capped at 1000 events and 4 MB, and a batch the daemon refuses (`400`/`413`) is dropped and counted in `dropped`. The queue holds at most 5000 events or 32 MB, oldest evicted first. A process dying of an uncaught exception or unhandled rejection sends the newest 16 MB it holds, blocking for at most 1 second; a graceful exit makes one final attempt capped at about 2 seconds. A run's root span is reported when the run starts, so a run whose process is killed is still listed and turns `interrupted`.
-- `LOUSHO_OBSERVE` accepts `1`/`true`/`on`/`yes`, an `http(s)://` URL, or `0`/`false`/`off`/`no`/`none`/`disabled`/empty (any case). Any other value warns once naming `LOUSHO_OBSERVE` and disables reporting, instead of being posted to as a URL.
-- With `LOUSHO_OBSERVE` pointing at a loopback daemon, `createAgent` captures message and tool content for the daemon by default (`captureContent: false` turns it off). Only the daemon gets it: the agent's own `exporter` (trace files, OTLP or vendor exporters, the built server's OTel export) still records no content unless the agent sets `captureContent: true`. Captured content goes through `redactContent` first (see the scrubber entry under Changed). See [Observability](docs/observability.md#message-and-argument-content-is-opt-in).
-- Each observe daemon writes its own pidfile beside its db (`foo.db` gives `foo.pid`), so two dbs in one folder never share one. `lousho observe start` exits 1 when the port already serves another db, and `stop` refuses to signal when the daemon on the pidfile's port reports another db or answers as a different service. `/health` names the db it serves only to callers on the same machine. A daemon started with `--db foo.db` by an earlier build of this feature wrote the shared pidfile and is not found by the new `stop`: stop it before updating.
-- `lousho observe start` and Studio print the `LOUSHO_OBSERVE` value for the port and host the daemon really uses (`LOUSHO_OBSERVE=http://127.0.0.1:7788` on a non-default port), and the Studio proxy answers `/observe/__target` with the daemon URL reporters should use.
-- `sandbox({ driver: 'isolate' })` runs tool code in an `isolated-vm` V8 isolate (optional peer `isolated-vm`); `defineTool({ sandbox })` opts a tool in, timeouts and OOM map to `sandbox.error` on the tool span. `'docker'` and `'e2b'` driver names are reserved for later drivers.
-
-### Changed
-
-- **Behavior change:** content captured for traces is scrubbed for secrets by default. `redactContent` is `boolean | ((text) => string)`: unset or `true` runs a built-in scrubber over message text, system instructions, tool-call arguments and tool results that replaces API-key shapes (`sk-…`, `lsv2_…`, GitHub tokens, AWS access key ids, the token after `Bearer`) with `[redacted]`; a function replaces the scrubber (text it throws on is recorded as `[redacted]`); `false` records content as is. It catches common key formats, not every secret, so set `captureContent: false` if content must never reach the db. See [Secrets in captured content](docs/observability.md#secrets-in-captured-content).
-- **Behavior change:** sessions end. The daemon marks a session `ended` once none of its runs is open and nothing in it has started or finished for `lousho observe start --session-idle-minutes N` (default 30, `0` turns it off); `ended_at` is the last activity, and a new run makes it `active` again. Sessions in an existing db close on the first sweep that finds them idle, and ended sessions then age out with retention. See [Idle sessions](docs/observability.md#idle-sessions).
-- **Behavior change:** the daemon keeps 30 days of runs by default. On its first sweep after start, and daily after that, it deletes traces whose observations all finished more than `--retention-days` ago, with their scores; a trace with a run still open, and a session still `active`, is kept. Start it with `--retention-days 0` to keep an existing db's history. See [Retention](docs/observability.md#retention).
-- Studio redesign: a new look in light and dark (Settings > Appearance picks Light, Dark or System, plus Compact or Comfortable table density), a left nav that collapses to an icon rail, and a Settings screen in sections (among them Appearance, Provider keys with Set / From environment / Not set, Collector, Keyboard shortcuts). Traces gains **Refresh** and a **Live** toggle that refreshes every 5 seconds, the trace viewer switches between **Tree** and **Waterfall**, Evaluations moves between Scores, Datasets, Evaluators and Annotation queues with tabs, Ctrl/Cmd+Enter runs the Playground, and the Agents canvas opens with the whole graph fitted and the Inspector folded until you select a node. See [Agent Forge](docs/agent-forge.md).
-
-### Fixed
-
-- Studio filter bar: the search box keeps what you type — a trailing space (`tool `) no longer gets reset when the URL echoes the trimmed query; clearing filters or navigating still updates it.
-- Insights runs/day averages over the days an agent was active in the window, so an agent first seen today with 12 runs reports 12/day instead of 12/7.
-- Studio threads: each turn now shows its full input and output (chat messages render as bubbles) instead of the 200-char previews; a turn fetches its trace as it scrolls near the viewport, shows the preview labelled "Preview (truncated)" while loading or if the trace can't be read, and says so when the recorder truncated the turn's I/O.
-- An open run's root start is kept when the reporter's buffer trims or a crash flush cuts to its newest 16 MB, so a run whose child spans overflow the buffer is still listed.
-- Studio Scores and `GET /api/v1/scores?aggregate=eval`: `human` and `online` scores now pass only on a value of exactly 1, so a thumbs-down or an online rule returning 0 (or 0.9) without a comment counts as a failure instead of a pass; `eval` and `judge` scores keep their rule (no failure comment, or a perfect 1), and the table and the eval detail agree.
-- Studio: the command palette and `?` shortcuts sheet now keep every keydown to themselves, so `S` no longer skips the annotation-queue item behind them; Traces, Threads, a Thread, Prompts and the Context Hub recover in place after the daemon restarts instead of staying on "daemon down"; and the queue review's trace tree no longer wraps a row name one letter per line at 1280px.
-- The run inspector shows `error`, not `running`, for a failed step that has no end time.
-- Studio trace viewer: an observation the crash sweep marked `interrupted` (or an open `error` one) now shows as terminal instead of "running" forever; its duration and the waterfall stop at the latest known end and the header clock stops ticking.
-- The observe daemon refuses cross-site browser writes and DNS rebinding on `/api/*`: a loopback-bound daemon answers only loopback `Host` names (403), writes carrying a non-loopback `Origin` (including `null`) or `Sec-Fetch-Site: cross-site` get 403, and a write with a body must be `Content-Type: application/json` (415) — `curl -d` needs `-H "Content-Type: application/json"`. The SDK reporter, CLI and Studio already comply. See [Observability](docs/observability.md).
-- Observe retention (`lousho observe start --retention-days`, `lousho observe prune`) also deletes old traces the sweep marked `interrupted` (a crashed run whose end never arrived); their age counts from when they were interrupted.
-- The observe daemon's online evaluator worker no longer blocks the daemon: it yields between traces, checks each rule's filter against the root row before loading anything else, hands code rules at most 200 observations (attrs over 8192 characters become `{ truncated: true }`) and no scores, and judge jobs claimed by Agent Forge carry the root fields only (`observations: []`).
-- Error text recorded on spans (`error` attributes and the span status message, on runs, LLM calls, tools, resumed runs and flows) goes through the same `redactContent` choice as captured content, so tokens in an error no longer reach traces, exports, evaluators or judge prompts; the built-in scrubber also catches case-insensitive `Bearer`, Stripe `sk_`/`rk_` live and test keys, Slack `xox[abprs]-` tokens, Google `AIza` keys and JWTs. `recordSpanError` and `withSpan` take an optional redactor (default: the built-in scrubber).
-
-### Documentation
-
-- [Agent Forge](docs/agent-forge.md) documents the left navigation, every screen, the deep-link routes and the keyboard shortcuts, with screenshots in `docs/images`; [Observability](docs/observability.md), [CLI](docs/cli.md) and [Evals](docs/evals.md) link to the screens. The screenshots come from an opt-in Playwright spec: `LOUSHO_DOC_SHOTS=1 npx playwright test -c apps/agent-forge/playwright.config.ts docShots`. See [Keyboard](docs/agent-forge.md#keyboard) and [Routes and deep links](docs/agent-forge.md#routes-and-deep-links).
-
-### Security
-
-- Agent Forge's studio server requires its per-launch token on every API route regardless of path case or encoding: `/PLAYGROUND/run`, `/Observe/api/v1/scores`, `//settings/...` or `/%70layground/run` no longer skip the check. Routing is case-sensitive, and every request except a `GET`/`HEAD` of `/health` or the built client needs the token.
-- Agent Forge's `/observe/**` proxy only ever forwards to the `LOUSHO_OBSERVE_URL` daemon: the upstream URL is built from the request's path and query alone, so an absolute-form request line (`GET http://a@evil.example/observe/...`) can no longer point it at another host, and a path that URL parsing would rewrite (`..`, `%2e`, a literal `\`) is refused with 400 instead of reaching a write route the allowlist does not name. The proxy sends `LOUSHO_OBSERVE_TOKEN` as the bearer to a daemon that requires one, and the Playground's "Save as new prompt version" (`POST /api/v1/prompts`) is forwarded instead of answering 405.
-
-## [1.0.0-alpha.29] - 2026-10-21
-
-### Changed
-
-- **Behavior change:** the built node-server and Docker image refuse to start on a non-loopback host when no auth is configured (no `LOUSHO_API_TOKEN`, build token or `auth.ts`), with `LOUSHO_SERVER_UNPROTECTED`. Set a token, add `auth.ts`, bind to `127.0.0.1`, or set `LOUSHO_ALLOW_PUBLIC=1` to serve an open agent on purpose. `lousho build --target=docker` prints the run command with `-e LOUSHO_API_TOKEN=<token>`.
-- The `limits.maxCostUsd` warning for a model with no known price names the model, says the limit is not enforced for it, and shows the `registerModel()` call that fixes it. It is printed once per model instead of on every step.
-- Scaffolded READMEs link to the docs site (`https://lousho.com/quickstart`) instead of the GitHub file on `main`.
-- [Sessions](docs/sessions.md#sharing-a-sqlite-file) has one statement on sharing a SQLite store, used across the docs: several processes on one host and a local disk are fine; network filesystems and multiple hosts are not.
-
-- **Behavior change:** the built node-server and Docker image resume runs a crash left in progress when they start (`agent.recover()`), and check again every 30 seconds until shutdown. Runs paused on an approval or a question are left alone, and a run another replica holds is skipped. `LOUSHO_RECOVER_ON_START=0` turns it off. See [Crash recovery](docs/deployment.md#crash-recovery).
-- **Behavior change:** `createAgent()` and `defineTool()` reject an option key they don't know with `LOUSHO_CONFIG_INVALID` and a suggestion (`requireApproval` → `needsApproval`, `maxOutputTokens` → `modelSettings.maxTokens`) instead of ignoring it. A mistyped `needsApproval` used to run the tool unapproved. Keys set to `undefined` are ignored.
-- **Behavior change:** the workspace file tools deny `.env` and `.env.*` by default as well as `.git`. `.env.example`, `.env.sample` and `.env.template` stay readable. A `deny` list you pass still replaces the defaults.
-- `POST /chat` answers `409` with `Retry-After: 2` and `code: LOUSHO_SESSION_BUSY` when another process or replica is running the session, instead of a `200` stream holding only the error. An `Idempotency-Key` resend that hits a running turn gets the same `409`.
-- Scaffolded agents (`lousho init`, `create-lousho-agent`) set `modelSettings: { maxTokens: 4096 }`, so a first run on a low-credit OpenRouter key no longer fails with "requires more credits, or fewer max_tokens". The generated README explains the error.
-- Error `docs` links point to `https://lousho.com/errors#<code>` instead of the GitHub file on `main`.
-- The Docker image creates `/app/data` owned by `node` and declares it a `VOLUME`, so a fresh named volume works with `LOUSHO_STORE=sqlite:/app/data/lousho.db`.
-- The [Authentication](docs/auth.md) examples read secrets from the environment and fail at startup when they are missing, instead of falling back to a literal secret.
-
-- **Behavior change:** the built node-server (and the Docker image) now guards `POST /channels/<name>` and its approvals route for a channel without `verify` with `LOUSHO_API_TOKEN` / `auth.ts`, the same as `/chat`. Before, such a channel answered anyone even with a token set. Channels that verify their own requests (Slack, Discord, Telegram, GitHub, Teams, `webhookChannel` with a secret, any channel with `verify`) are unchanged, and the start-up log lists each channel route's guard (`self-verified`, `server-auth` or `open`).
-- **Behavior change:** `webhookChannel` replies with `{ sessionId, text, finishReason, approval? }` (plus `approvalPrompt` on a pause), as `httpChannel` does, instead of the full `ExecutionResult`. The full result echoed the system prompt and the whole transcript to the caller. `fullResult: true` restores the old body.
-- Channels answer a turn on a session that another process or replica is running (`LOUSHO_SESSION_BUSY`) with `409` and `Retry-After: 2` instead of a `500`, and report a turn that fails before the request is acknowledged to `onError` with stage `'turn'` (it said `'parse'`).
-- README and [Comparison](https://github.com/LinuxDevil/agent-sdk/blob/995e21b7a835a4c869c1ae0b427fc92b0ee9c000/docs/comparison.md) no longer list ACP and MCP as differentiators, and describe Agent Forge as a local visual console.
-
-- CI is one workflow with two jobs: `ci` (type checks, lint, build, tests with coverage, docs, API and fallow gates, pack-smoke, size check, and a zod 4 type check) and `compat` (the newest peers, `ai` 7 with zod 4, plus the real-Docker sandbox tests). The separate Docker Engine, Agent Forge E2E and weekly registry-smoke workflows and the `ai` 6 / zod 3 matrix entries are gone; `npm run registry-smoke` and `npm run test:e2e:studio` still run locally. When the fallow gate fails, CI now prints its full health and duplication reports.
-
-### Added
-- `GET /ready` on the built node-server and Docker image: `200 {"status":"ready"}` while serving, `503 {"status":"draining"}` once shutdown starts. `/health` is unchanged. See [Deployment](docs/deployment.md).
-- The built server exports OpenTelemetry traces over OTLP/HTTP when `OTEL_EXPORTER_OTLP_ENDPOINT` (or `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`) is set, next to any exporter the agent already has. It loads `@opentelemetry/sdk-trace-node`, `@opentelemetry/resources` and `@opentelemetry/exporter-trace-otlp-http` only then, says how to install them when missing, and honours `OTEL_SERVICE_NAME`. See [Observability](docs/observability.md).
-- `createAgent({ toolErrorMessage })` replaces the text of a thrown tool error (`kind: 'execution'`) before it reaches the model, `tool.error` events and hooks; a sanitizer that throws gives "The tool failed.". See [Tools](docs/tools.md).
-- `lousho init` and `create-lousho-agent` generate an `AGENTS.md` for coding agents (the project's real scripts, conventions and docs links) and a `CLAUDE.md` that imports it.
-- `lousho add` falls back to the registry bundled in the npm package (`registry/dist`) when `registry.lousho.com` and its GitHub fallbacks are unreachable, with a notice that the bundled copy may be older.
-- [Pause, restart and resume](docs/pause-and-resume.md): one tutorial for an approval that waits across a restart, crash recovery, and resending over HTTP.
-- `SECURITY.md`: supported versions, private reporting through GitHub, and the disclosure policy.
-- `httpChannel()` created without `verify` logs one warning that the channel is unauthenticated and its `sessionKey` values are guessable. [Channels](docs/channels.md) shows `verify` in the quick start, and [Deployment](docs/deployment.md) says which routes `LOUSHO_API_TOKEN` guards.
-- `POST /chat` accepts an `Idempotency-Key` header: a resend with the same key replays the finished turn's reply (`Idempotent-Replayed: true`, nothing runs), resumes a turn a crash interrupted instead of appending the message again, and is a `409` (`LOUSHO_SESSION_BUSY`) while that turn still runs. The key is stored on the turn's user message (`metadata.idempotencyKey`), so it survives restarts; `session.pending()` reports it as `idempotencyKey`. See [Resending a turn](docs/deployment.md#resending-a-turn).
-- `fromAiSdkTools(record)` converts Vercel AI SDK tools (`tool({ ... })` or plain `{ description, inputSchema | parameters, execute, needsApproval? }` objects) into Lousho tools, keyed by name: zod and Standard Schemas are kept, `jsonSchema()` wrappers and plain JSON Schemas are converted (their own `validate` still runs), `needsApproval` (boolean or function) pauses the run for approval, and `execute` gets the call id and the run's abort signal. It imports nothing from `ai`, so tools built on `ai` 4 to 7 work with any installed version. New guide: [Migrating from the AI SDK](docs/migrating-from-ai-sdk.md).
-- `lousho eval` without vitest installed now says it runs `*.eval.ts` files through vitest, the directory it searched from, and the install command; [Evals](docs/evals.md) states the requirement up front.
-- `result.usage.delegated.toolErrors`: the tool calls that failed inside a run's sub-agents (and theirs), which the lead's own `result.toolErrors` does not count. `ToolCallContext.onDelegatedUsage` takes the child's `toolErrors` as an optional second argument.
-- The session HTTP API (`createRouteHandler()`, the deployed node server, the Worker, `lousho dev`) writes an SSE comment (`: ping`) after 15 seconds without an event, so proxies and client idle timeouts no longer drop a turn whose model or tool is slow; `heartbeatMs` changes the interval (`0` turns it off). See [HTTP API](docs/deployment.md#http-api).
-- `google/<model>` model strings (e.g. `createAgent({ model: 'google/gemini-2.5-flash' })`) and a `GoogleProvider`, backed by the optional peer `@ai-sdk/google` (`^1.2.0` with `ai` 4, `^3.0.0` with `ai` 6, `^4.0.0` with `ai` 7) and reading `GOOGLE_GENERATIVE_AI_API_KEY`. `lousho init --provider google`, `lousho doctor` (package pairing, key, `--ping`) and the missing-peer install hint cover it. See [Providers](docs/providers.md).
-- An unknown model prefix (`mistral/...`, `xai/...`) now says how to reach the vendor anyway: `openrouter/<vendor>/<model>`, `pi/<vendor>/<model>` when pi serves it, or `fromAiSdk()` with the vendor's AI SDK package. See [Vendors without a prefix](docs/providers.md#vendors-without-a-prefix).
-- `lousho doctor` fails an installed `ai` 5 (AI SDK v5 is not supported) with an upgrade hint to `ai` 6 or 7 and the matching `@ai-sdk/*` majors.
-
-### Fixed
-- `lousho build` works again in a project without the optional `@opentelemetry/*` packages (every fresh scaffold): the OTel exporter added for the built server is loaded only when `OTEL_EXPORTER_OTLP_ENDPOINT` is set, and the build leaves those packages unresolved instead of failing with `Could not resolve "@opentelemetry/api"`. The scaffold end-to-end test now builds the server and checks `/health`.
-- The `httpChannel()` "no verify" warning no longer says the channel is unauthenticated when the built server guards it with `LOUSHO_API_TOKEN` or `auth.ts`, and [Channels](docs/channels.md) shows `webhookChannel`'s trimmed reply.
-- `lousho add` works again when `registry.lousho.com` is unreachable: the fallback now tries the release tag as the repository names it (`1.0.0-alpha.24`), then the `v`-prefixed tag, then `main`. It asked only for `v<version>`, which 404'd.
-- The file tools' `deny` list (`.git` by default) is now also checked where a path really leads: a symlink or Windows junction inside the workspace pointing at `.git` or into it (`gitj -> .git`) let `edit_file gitj/config` rewrite `.git/config` (for example `core.hooksPath`, which runs code on the next git command) and `write_file gitj/PWNED` create files in `.git`. Reads, writes, edits, `list_dir`, and `glob`/`grep` given such a link as `path` are now refused. Providers with links can implement the new optional `FsProvider.realPath(path)`; `NodeWorkspace` does. See [Workspace tools](docs/workspace-tools.md#security-model).
-- `NodeWorkspace.writeFile` (and so `write_file` / `edit_file`) writes a temp file in the same directory and renames it into place, so a process killed mid-write no longer leaves a truncated file. A replaced file keeps its permission bits; a read-only file is still refused.
-- `WorkspaceCheckpoints` stores a file's backup before `write_file` / `edit_file` writes it, not after. A process killed between the write and the backup lost the original: on resume the re-run call backed up the agent's own content, so `rewind()` reported `restored` but put back the agent's version (or, for `edit_file`, recorded nothing). A re-run now keeps the turn's first backup, and rewind treats a file still holding its backed-up content as nothing to undo. `track()` also accepts a `PreparedWorkspaceWrite` (`{ prepare, write }`), which the built-in tools use.
-- `edit_file` re-run after a crash (the edit already in the file: `old_string` gone, a non-empty `new_string` present, also with `replace_all`) now succeeds with "the edit was already applied" and writes nothing, instead of failing with `old_string was not found` and sending the model into a loop. A `write_file` / `edit_file` that leaves the file unchanged no longer records a checkpoint backup.
-- [Sessions](docs/sessions.md) no longer says to call `resume()` before resolving an approval after a restart: `agent.approvals.resolve()` / `streamResolve()` from a fresh process finds the session itself. It and [Build a coding agent](docs/build-a-coding-agent.md) now say how to show a resumed turn's progress (`session.on()`, `onEvent`), and the guide points long coding turns at compaction.
-- MCP tool schemas with OpenAPI's `nullable: true` (any type) now accept `null`; the model's valid `null` was rejected with `ToolArgumentsValidationError`.
-- A failed MCP tool call (server exited, timeout, protocol error) now rejects with `LOUSHO_MCP_CALL_FAILED`, naming `<server>__<tool>` with the MCP error as `cause`, instead of a bare `MCP error -32000: Connection closed`. [MCP](docs/mcp.md) now says stdio `env` is merged onto the MCP SDK's default allow-list, not `process.env`.
-- Flows (consumer harness): a `{{variable}}` holding an object (a `toolCall` result, an MCP result) no longer reaches a prompt as `[object Object]`: an object whose only field is `text` (an MCP tool result) is that text, a raw MCP `{ content }` result its text parts, and any other object or array its JSON. Placeholders take dotted paths (`{{res.user.name}}`, `{{list.0}}`, own properties only), also as whole tool-argument values. An `evaluator` step stores its result in `outputVariable`. See [Template values](docs/flows.md#template-values).
-- Flows: a durable run is saved before its first step, so a run whose first step failed can be `resume()`d instead of failing with `LOUSHO_CHECKPOINT_NOT_FOUND`, whose hint for a flow run now points at `FlowExecutor.execute()` rather than forking session history. A step's checkpoint is saved before its `step-complete` event, so a crash in between no longer re-runs a step reported complete.
-- Flows: an `llmCall` whose model request fails rejects with the same compacted `CompactedLLMProviderError` as an agent run (`LOUSHO_PROVIDER_*` code, `compacted.category`), not the provider SDK's raw `APICallError`, and its `retry` no longer retries a failure marked `retryable: false` (a 401, an exhausted quota, a too-long prompt).
-- A provider answering a streaming request with HTTP 200 and a body that is neither an event stream nor valid JSON (for example a truncated `{"choices": [ {"oops`) no longer ends as a silent empty reply. It now fails as a retryable 502, so `withRetry` retries it and an exhausted retry surfaces as a provider error.
-- A sub-agent with an `output` schema that ran out of steps and gave a valid object in its forced final call is now a `task` result (the object, with a line saying the steps ran out), not a failure telling the lead it gave no final answer - which made leads re-run the task.
-- Sub-agents are held to their lead's token, cost and duration `limits` while they run, counted with what the lead and its other running sub-agents have spent, so parallel sub-agents no longer each spend the lead's whole budget (a lead with `maxCostUsd` could end at several times it). A sub-agent stopped this way reports the limit to the lead. A spend limit stays a hard stop with no forced `output` answer; the finished tool results stay in `result.messages` ([Budgets](docs/configuration.md#budgets)).
-- **Behavior change:** `POST /chat` to a session paused on an approval is a `409` JSON body (`LOUSHO_SESSION_AWAITING_APPROVAL`, with `approvalId` and `approvalIds`) instead of a `200` stream ending in a generic error.
-- A decision on an approval whose winning decision is still streaming is a `409` (`LOUSHO_APPROVAL_CONFLICT`), as docs/auth.md says, instead of a `404`.
-- The session routes' `400` bodies carry a `code`: `LOUSHO_REQUEST_INVALID` (invalid JSON, missing or empty fields), `LOUSHO_APPROVAL_DECISION_INVALID` (an approval body with neither `approved` nor `answer`), `LOUSHO_SESSION_ID_INVALID`.
-- `lousho chat` prints a failed turn with its error code, the provider's failure category and HTTP status, and the fix (`error: User not found. (auth-failure, HTTP 401)` then `[LOUSHO_PROVIDER_REQUEST_FAILED] ...`), as docs/cli.md says, instead of the bare provider message. The terminal chat of a project scaffolded by `lousho init` / `create-lousho-agent` does the same.
-- A `.env` saved with a UTF-8 byte order mark (PowerShell 5.1's `Set-Content -Encoding utf8`) no longer loses its first variable: the `lousho` commands and the scaffolded `src/index.ts` drop the mark before parsing. Variables already set in the environment still win.
-- `lousho doctor src/agent.ts` loads a `.ts`/`.js` agent module the way `lousho dev` does instead of failing with `LOUSHO_SPEC_UNSUPPORTED_FORMAT`, and a missing key for the module's provider is a failure. A scaffolded project's `npm run doctor` now runs `lousho doctor src/agent.ts`, so it fails when the agent's key is missing.
-- `lousho doctor --ping` checks OpenRouter at `/api/v1/key`, which needs the key (its `/models` answers without one, so a wrong key passed); a key the provider rejects is now a failure, and a ping of a custom `OPENAI_BASE_URL` says it shows reachability only.
-- `lousho doctor` fix lines use PowerShell syntax (`$env:NAME="<your key>"`) on Windows.
-- The `lousho eval` table shows the scores of passing scored gates (such as `t.check('words', n, atLeast(3))`), not only in `--json`.
-- **Behavior change.** An agent with `output` and tools no longer sends the strict `responseFormat` schema on calls that offer tools: `openai/gpt-4o-mini` via OpenRouter then called tools on every step until `maxSteps` and never answered. `responseFormat` now goes only on calls without tools (an agent without tools, the "answer now" call at `maxSteps`, the repair step); tool-offering calls answer from the schema in the prompt, with the existing parse and repair. `output: { schema, responseFormat: 'always' }` restores the old behavior, and is the default with `promptSchema: false`. `object.delta` events still stream on every step of an `output` run. See [Structured output](docs/structured-output.md#how-it-works).
-- An agent directory built with `lousho build --target=node-server` (or `docker`) can now change who may decide an approval and who may use a session: `auth.ts` may export functions named `authorizeApproval` and `authorizeSession` next to its default auth list, `resolveAgentDir()` returns them, and the built server applies them. Before, the built server always used the defaults, so a manager could not approve another user's paused call while that user could approve their own. See [Who may decide an approval](docs/auth.md#who-may-decide-an-approval).
-
-### Documentation
-
-- Tool idempotency: `toolCallId` and `ctx.approval.id` identify one call; after a crash the model may retry with a new call, so side effects that must happen once need a key from your own data. New guidance for ending a run after a rejected approval, and for extract-then-approve-then-act with structured output.
-- [Durable execution](docs/durable-execution.md#recovering-after-a-crash): `agent.resume()` resolves with a result, not a stream (stream a resumed run with `agent.stream([], { sessionId })`), and `agent.pending()` also lists runs still active in another process. [Installation](docs/installation.md#typescript-settings): TypeScript 6+ projects need `"types": ["node"]` for the SDK's declarations.
-
-## [1.0.0-alpha.24] - 2026-10-17
-
-Two fixes on top of 1.0.0-alpha.23, published from the release branch.
-
-### Added
-- `model-unloaded` provider error category: "model is not loaded/unloaded" replies from a local server (LM Studio, Ollama) classify as retryable, so `withRetry()` rides out the server evicting or still loading a model.
-- A run ended by `maxSteps` or a budget without a final answer now returns explanatory text instead of an empty string.
-
-### Changed
-- MCP: a warning is logged when a server's tool schemas exceed about 16K tokens (deferred tools excluded). A server marked `optional: true` connects in the background, so a slow or failing optional server no longer blocks the first `send()`.
-
-### Fixed
-- Compaction: when the provider rejects a request for context size and the configured `contextWindow` is larger than the model's real one, the error is marked on the transcript and folded into it for a retry when a compaction hook exists; the hook compacts under the server's observed window (or the rejected request size when unnamed) for the rest of the run.
-- `toolCalls` of a run continued from a transcript (approval resolve, resume) are collected from its messages, so they no longer disappear from the result.
-- `recall_<slot>` with a query that matches nothing now says the slot is not empty, instead of returning a bare `[]` that contradicted the injected `<memory>` block.
-- The guardrail starter set's `ignore-instructions` signal also catches "ignore these/those/her/his/their/our instructions" and "ignore your instructions", without a qualifier such as "previous".
-
-## [1.0.0-alpha.23] - 2026-10-16
-
-The same tree as 1.0.0-alpha.21; no code changes. create-lousho-agent
-0.1.2-alpha.7.
-
-## [1.0.0-alpha.22]
-
-Never published to npm (the registry goes from 1.0.0-alpha.21 to
-1.0.0-alpha.23); no changes.
-
-## [1.0.0-alpha.21] - 2026-10-16
-
-Everything merged to `main` after 1.0.0-alpha.20. create-lousho-agent
-0.1.2-alpha.6.
-
-### Breaking
-- Removed the deprecated trigger adapters and their types from `@lousho/build-ai-agent/triggers`. `TriggerAdapter`, `TriggerRegistry`, the `WebhookAuth` helpers, `verifySlackSignature()` and `parseCronExpression()` stay. Migration (see [Migrating from triggers](docs/upgrading.md#migrating-from-triggers)):
-  - `WebhookTriggerAdapter`, `WebhookTriggerAdapterOptions`, `WebhookTriggerHandle` -> `webhookChannel()` with `mountChannels()` (same `auth` option)
-  - `SlackTriggerAdapter`, `SlackTriggerAdapterOptions` -> `slackChannel()` with `mountChannels()`
-  - `CronTriggerAdapter`, `CronTriggerAdapterOptions`, `CronIntervalOptions`, `CronExpressionOptions` -> `defineSchedule()` with `startSchedules()` (no `intervalMs`: use a cron expression such as `*/5 * * * *`)
-
-### Added
-- `agent.recover({ intervalMs?, signal?, onError?, onRecovered? })` finishes interrupted durable runs in the background: it polls `agent.pending()` and resumes each `'in-progress'` run once its crashed holder's run lease is free, leaving approval and question pauses (and non-retryable failures) alone; returns `{ done, stop() }` ([Durable execution](docs/durable-execution.md#recovering-automatically)).
-- An agent directory's config accepts `retry` (`agent.json`: `maxRetries`, `timeoutMs`, `backoff`, ...) and, in an `agent.ts` code config, `output` (a Standard Schema), so `lousho dev`/`chat`/`build ./agent` keep structured output and per-attempt timeouts. `loadAgentDir(dir, { output })` now returns `SimpleAgent<Infer<output>>`, so `result.object` is typed.
-- `result.toolErrors` counts a run's tool calls that ended in an error result, so an answer the model gave after its tools failed (`finishReason: 'stop'`) is no longer indistinguishable from a good one; `limits.maxToolErrors` stops the run (`'budget-exceeded'`, `budget.limit: 'maxToolErrors'`) once that many failed. See [Failed calls in the result](docs/tools.md#failed-calls-in-the-result).
-- An error a run rejects with carries what the run spent as `error.usage` (also on `PropagatingToolError` and your own errors). A sub-agent's spend is saved on its lead's checkpoint as it runs, so a lead resumed after a crash mid-sub-agent counts the interrupted sub-agent's model calls.
-- A `send(msg, { sessionId })` or `agent.resume()` run that rejects records `lastError` and `attempts` on its checkpoint, and `agent.pending()` lists them (`attempts` is new for session turns too), so a restart loop can tell a failing run from a crashed one.
-- Docs: a webhook-redelivery recipe (run a job once by checking the checkpoint before `send()`), a note on structured-output schemas that mirror a side-effect tool, and the `fetch` option for proxies and fault injection on every provider class.
-
-### Changed
-- **Behavior change:** the fallback default model for the OpenAI, OpenRouter and Pi providers (what `lousho init` scaffolds and what runs when no model is configured) is now `gpt-4.1-mini` instead of `gpt-4o-mini`; set `model` or `LOUSHO_MODEL` to keep the old one. README and Quick Start use it. Added `docs/comparison.md`; CI also runs on pushes to `main`; README no longer claims unverifiable live validation.
-- `createAgent({ prompt })` is deprecated: `instructions` is the one documented name (`prompt` still works as an alias, marked `@deprecated`). Docs, README and examples now use `instructions`, and `npm run docs:verify-snippets` fails a docs snippet that passes `prompt` to `createAgent`.
-- The published package no longer ships source maps (`dist/**/*.map`, ~3.7 MB; tsup no longer emits them). The tarball goes from 965 files / 18.9 MB unpacked / 5.0 MB packed to 774 files / 15.1 MB / 4.3 MB. `src/` still ships because `lousho build` bundles the SDK from it. `npm run size-check` now guards the tarball size and a hello-world bundle against `scripts/size-budget.json`.
-- `docs/comparison.md` is now a dated (October 2026) per-competitor table covering the AI SDK 7, Mastra, LangGraph.js, OpenAI Agents SDK, Claude Agent SDK, eve, VoltAgent and open-harness, and the README's differentiator list keeps only claims still true against them.
-
-### Fixed
-- **Behavior change:** a session without a `checkpointStore` that pauses on an approval now keeps an in-process pause marker, so a second `send()` / `stream()` / `compact()` on it throws `SessionAwaitingApprovalError` (`LOUSHO_SESSION_AWAITING_APPROVAL`) — before, the new turn ran over the truncated transcript and the later `approvals.resolve()` silently overwrote the committed turn. The marker covers `send`, `stream`, `compact`, `clear`, `pending` and `discardPending`, and is dropped when the turn resolves, aborts, fails or is discarded. Across processes there is still no durable marker: a session that may pause needs a `checkpointStore`.
-- Session turn checkpoints no longer reuse a `<id>.turn-<n>` id after `compact()` shortened the transcript: the `n` now comes from a persisted high-water mark (`<id>.turn-counter`), so `fork()` can no longer resolve a stale checkpoint of a different turn, and `prune()` keeps the counter while its session's paused run needs it.
-- Memory: two parallel `remember_<slot>` calls with an `itemKey` no longer store duplicate items — the check-and-replace is serialized per memory key. A remembered item is capped at 20,000 characters and the injected `<memory>` block at 20,000 (each line 4,000), so one item can no longer outgrow the context window of every later run.
-- `lousho add <kit> --dir <new-dir>` no longer creates the target directory before the install is decided: a non-interactive refusal, a manifest refusal or a 'no' at the prompt now truly leaves "nothing was written" — before, an empty directory stayed behind.
-- A malformed or truncated provider response before any output (the AI SDK `JSONParseError`/`TypeValidationError` on a garbage first SSE chunk, or a stream cut by `UND_ERR_SOCKET` / "terminated" / "other side closed", also inside a `cause`) is now retried by `withRetry()` like other network errors, with a `provider.retry` event, instead of ending the turn with `LOUSHO_PROVIDER_REQUEST_FAILED`. Nothing is retried once text or a tool call was emitted.
-- `lousho build --target=node-server` now lists the provider package in the build's `package.json` when the agent module (or a code `agent.ts`) uses an SDK provider class such as `new OpenRouterProvider(...)`, not only a literal `model: '<provider>/...'`, and warns when it detects no provider. `docs/deployment.md` no longer tells readers to call the internal `createDeployedServer()`; it shows a graceful shutdown for a self-served agent.
-- Errors and cost (consumer harness): a session turn that fails outside its run (e.g. `LOUSHO_SESSION_BUSY`) now sends the error's stable `code` on the `error` event, with the message still sanitized; `provider.fallback` events carry `fromModel` / `toModel`, so two providers of the same name (both OpenRouter) can be told apart; and one step with no known price no longer discards the run's cost: `usage.costUsd` keeps the priced steps' sum and `usage.costPartial: true` flags it (also on `byModel` entries, `delegated` and `step.done` / `run.done` usage), and `limits.maxCostUsd` is enforced on that partial total.
-- `grep` no longer times out on a cheap pattern over a slow disk: the 10 s budget now counts only the time spent matching, not reading files. The timeout error says whether the pattern is slow or the many files used the budget, and how many files were scanned. New `createFsTools({ grepTimeoutMs })`.
-- Permissions: a `permissions` rule naming a tool the agent does not have (a typo such as `write_flie`, so a `deny` silently guarded nothing) now logs a `[lousho]` warning at `createAgent()` with a "did you mean", and `lousho doctor <agent-dir>` reports it as a warning. Wildcards, globs, patterns and agents whose tools may arrive later (MCP, tool search, sub-agents) are only checked for near-miss typos.
-- `lousho init` / `create-lousho-agent` template: `npm run dev` with piped input (`printf 'hi\n' | npm run dev`) no longer exits before the reply; it streams the reply and exits when the turn is done.
-- `lousho eval`: the "with soft failures" total (`softFailed` in the JSON summary) also counts cases that failed a gate or threw; the JUnit report keeps their soft failures as `<system-out>` notes.
-- Sessions: a checkpointed turn whose first model call fails (a 5xx after retries, an exhausted 429, a malformed response) no longer loses the user's message. The turn is kept as an `in-progress` pending turn (new `Checkpoint.unstarted`), so `pending()` and the route's `GET` show it, and the next `send()` / `resume()` runs it again with the message in the transcript once. Over the session routes, that stored turn claims the session for its caller.
-- `lousho eval --replay` / `--record` skip a `mockModel()` provider: a scripted mock needs no network, so a mock eval no longer fails with `no cassette ... [LOUSHO_CASSETTE_INVALID]`.
-- `limits.maxCostUsd` no longer logs "cost limit is not enforced" on runs that use `mockModel()`, which has no price.
-- `lousho doctor` lists optional packages the agent does not use as one info line instead of a warning each.
-- Docs: `fileMemory({ dir })` in an agent directory's `memory/*.ts` resolves against the working directory (anchor it to the module); `lousho mcp` takes an agent directory; running `create-lousho-agent` from a local tarball; `lousho dev`/`chat` cannot pass run metadata.
-- Flows: a durable run (`checkpointStore` and `runId`) holds a run lease, like an agent run: a concurrent `FlowExecutor.execute()` or `resume()` of the same `runId` (in this process, another process or through another store object) is refused with `LOUSHO_SESSION_BUSY` and runs nothing, instead of running the remaining steps twice. A lease left by a crashed process expires, so the run can still be resumed. See [Durable runs](docs/flows.md#durable-runs).
-- Flows: a `toolCall` argument that is exactly `'{{name}}'` or `'$name'` passes the variable's value (a number, an object) instead of its text, so `{ n: '{{n}}' }` works with a `z.number()` tool. Mixed strings are still interpolated as text. See [Argument values](docs/flows.md#argument-values).
-- Flows: a `step` node (`StepNode`) fails with a message naming the supported way to run a `createAgent()` agent in a flow (a tool that calls `agent.send()`). See [Running an agent in a flow](docs/flows.md#running-an-agent-in-a-flow).
-- Sub-agents: a sub-agent's own `memory` works when the lead's `task` tool runs it (recall in its system prompt, its `remember_<name>` / `recall_<name>` tools), scoped by the lead run's `sessionId`, `metadata` and `principal`; before, its slots were silently ignored there. New `subagentOptions: { continuation: false }` leaves `taskId` and `mode` out of the `task` tool, and the error for another sub-agent's `taskId` tells the model to omit it for a new task. See [Sub-agents](docs/sub-agents.md#continuing-a-task).
-
-### Security
-- **Behavior change:** the file tools from `createFsTools()` (`read_file`, `list_dir`, `glob`, `grep`, `write_file`, `edit_file`) refuse any path with a `.git` segment (`.git/config`, `./.git`, `a/../.git`, `.GIT`, a worktree's `.git` file; on Windows also 8.3 names such as `GIT~1`) with a `WorkspaceError`, and `glob`, `grep` and `list_dir` leave `.git` out of their results. `.git/config` can hold a CI checkout token (`http.<url>.extraheader`) and a worktree's `.git` names a host path. The new `deny` option sets the names (default `['.git']`; `[]` turns it off). The `shell` tool is not path-filtered. See [Security model](docs/workspace-tools.md#security-model).
-- `lousho build <dir> --target=node-server|docker` no longer copies an agent directory's `.env` files or its `.lousho/` session store (real user transcripts) into `dist/` and the Docker image. Only the files the server reads are copied: `instructions.md`, `instructions/`, `skills/` and a JSON/YAML config, in the directory and each sub-agent; `.env*`, `.lousho`, a JSON/YAML config's `store.dir`, `.git` and `node_modules` are skipped at any depth. `dist/` is emptied before each build so sessions a previous build's server wrote there are not resurrected, and the generated `.dockerignore` also lists `**/.env`, `**/.env.*` and `**/.lousho`. Rebuild and redeploy images built from an agent directory with an earlier version. See [Deployment](docs/deployment.md#agent-directories).
-- `createRouteHandler()`'s UI stream (`POST <base>/ui`) and framework hook route (`POST <base>`) now enforce the documented 1 MB body cap (`413`) like `POST /chat` does; they previously buffered the full body via `request.json()`.
-- A channel approval decision now binds to the session recorded in the approval's own durable snapshot, not the `sessionKey` the caller sends, so a request carrying a foreign session key can no longer resolve another conversation's pending approval.
-- `POST /chat/:sessionId/approvals/:id` checks the approval's kind after authorization: `answer` only decides question approvals and `approved`/`note` only tool approvals; a mismatched body is `400 LOUSHO_APPROVAL_KIND_MISMATCH` instead of silently approving a tool.
-- `POST /chat` message arrays may carry `role: 'user'` only; client-supplied `system`, `assistant` and `tool` messages are dropped before the turn (content-part arrays without roles are unaffected).
-- **Behavior change:** `crossSiteRequest` no longer trusts `X-Forwarded-Host` or `Forwarded: host=` as same-site evidence — those headers are client-controllable. A request is same-site when its `Origin` matches the server's actual `Host` (or an `allowedOrigins` entry); behind a trusted proxy, set `allowedOrigins` to the public origin.
-- Session-owner bookkeeping adds a per-principal cap (1024 claimed sessions per caller) under the global 100,000 LRU, so one caller flooding new session ids can no longer evict everyone else's ownership claims.
-- `webhookChannel()` only defines `verify` when an `auth` option is configured; an unauthenticated webhook is treated as an open channel and its cross-site requests are refused like `httpChannel()`'s. The deprecated `WebhookTriggerAdapter` treats a missing `verify` as success.
-- Malformed percent-encoding in route parameters (`%zz`, truncated UTF-8) answers `400` instead of a `URIError` 500 on `/chat/:sessionId/...` and channel approval routes.
-
-## [1.0.0-alpha.20] - 2026-10-16
-
-create-lousho-agent 0.1.2-alpha.5.
-
-### Security
-- **Behavior change:** with route auth and no `authorizeSession`, a session belongs to the first principal that sends it a turn (reading claims nothing); any other principal gets `403 LOUSHO_SESSION_FORBIDDEN`. Owners are kept in memory per agent for the 100,000 most recently used sessions, so a stored session whose owner is not on record (after a restart, on another replica, past the cap) is refused to everyone: pass `authorizeSession` for multi-instance deployments and durable stores, or `authorizeSession: () => true` for the old behavior. A route behind one bearer token has a single caller and checks no owner. `POST /chat` with an empty `input` (and `POST <base>/ui` without a user message) is a `400` that claims nothing, and a turn that stores nothing drops its claim, so an owner can no longer be evicted by flooding. See [Who may use a session](docs/auth.md#who-may-use-a-session).
-- **Behavior change:** `POST /chat/:sessionId/approvals/:id` answers `404` unless the approval belongs to that session, and by default only the caller the paused run acts for may decide it; allow others (a supervisor) with `authorizeApproval`.
-- **Behavior change:** the session routes (`createRouteHandler()`, `createDeployedServer()`, the Worker, `lousho dev`) refuse cross-site requests: a POST whose `Origin` is neither the server's own (`Host`, `X-Forwarded-Host` or `Forwarded: host=`) nor in the new `allowedOrigins`, or that the browser marked `Sec-Fetch-Site: cross-site`, is `403 LOUSHO_REQUEST_FORBIDDEN`, and a POST body must be `Content-Type: application/json` (`415 LOUSHO_UNSUPPORTED_MEDIA_TYPE`). Requests without `Origin` are unaffected. Opt out with `allowedOrigins: ['*']` and `requireJsonBody: false`; `allowedHosts` refuses unlisted `Host` headers. Built servers read `LOUSHO_ALLOWED_ORIGINS`, `LOUSHO_ALLOWED_HOSTS` and `LOUSHO_REQUIRE_JSON_BODY=false`. The React/Vue/Svelte bindings no longer send `Content-Type` twice and accept a `Headers` instance. See [Cross-site requests](docs/auth.md#cross-site-requests).
-- **Behavior change:** `lousho dev` answers `403` to a non-loopback `Host` (off loopback: an IP address or the `--host` name; new `--allowed-hosts a,b`), so a web page cannot reach it through DNS rebinding, and warns when bound off loopback. A channel without `verify` refuses a cross-site browser request (`403`), and `httpChannel()` without `verify` requires a JSON body (`415`).
-- **Behavior change:** the Cloudflare Worker refuses every `/chat` route (`403 LOUSHO_REQUEST_FORBIDDEN`) when no `LOUSHO_API_TOKEN` secret is set; set the var `LOUSHO_ALLOW_OPEN_SESSIONS` (or the earlier `LOUSHO_ALLOW_OPEN_TRANSCRIPTS`) to `"true"` to allow it. `/health`, the OAuth callback and channels stay open, and `lousho build --target=cloudflare-worker` warns about the secret.
-- **Behavior change:** `WebhookTriggerAdapter` binds `127.0.0.1` by default (was `0.0.0.0`), refuses a non-loopback `host` without `auth` unless `allowUnauthenticated: true` (`LOUSHO_TRIGGER_INVALID`), refuses a foreign `Host` or an `Origin` on loopback without `auth`, caps bodies at 1 MB (`413`) before auth, and no longer echoes handler errors. See [Webhook](docs/triggers.md#webhook-authentication).
-- **Behavior change:** MCP tools ask for approval by default (`approval: 'always'`); a server's `readOnlyHint` / `destructiveHint` count only with `approval: 'annotations'`. An MCP tool named like a local tool is refused with `LOUSHO_CONFIG_INVALID` instead of replacing it. See [MCP](docs/mcp.md#approval-for-mcp-tools).
-- Flows: a `toolCall` step passes the same gate as an agent's tool call (`permissions`, `permissionMode`, `onPermissionDecision` and a new `approve` option on `FlowExecutionContext`); a call that needs approval and is not approved fails with `LOUSHO_FLOW_TOOL_DENIED` without running. Step arguments are validated against the tool's schema (`LOUSHO_TOOL_ARGS_INVALID`) and a flow's declared `inputs` are enforced (`LOUSHO_VALIDATION_FAILED`). See [Flows](docs/flows.md#tool-calls).
-- Registry: the approval an install receipt requires for an `exec`, `needsApproval` or unattested item can no longer be waived from inside the agent directory (an `allow` rule, `acceptEdits` or the directory's own `approve` file); only a person or an `approve` passed in code decides it. Receipts now also cover a kit's `subagents/<name>/` tools. `coding-kit` / `coding-pi` refuse writes to their own config, tools and `.git/`, drop `git diff` from the shell allowlist and accept `node --test` only with test file paths (reinstall with `lousho add coding-kit --overwrite`). See [Registry](docs/registry.md).
-- Shell tool: an `allow` string pattern refuses arguments that escape the workspace (`..` segments, also in `--flag=../x`, `~`, absolute paths, quoted or escaped forms such as `cat "../x"`, globs that can expand to `..`, and `$`, `{`, `}`), and under cmd.exe `%` and `^` count as shell operators. Use a `CommandRule` or an anchored RegExp to allow such arguments.
-- Agent Forge (`lousho studio`) no longer answers any origin: it sends no CORS headers, refuses a foreign `Origin` or a non-loopback `Host`, and every API and WebSocket call needs the per-launch token printed in its URL. See [Agent Forge](docs/agent-forge.md#access-token).
-- Tracing: `redactContent` defaults to `true`, so prompts, instructions and tool output are no longer written to span attributes or `.lousho/traces` unless you pass `redactContent: false` (or `captureContent: true` for `gen_ai.*` content).
-- The session routes no longer send raw error text to clients: `error` events, `500`s and `provider.retry` / `provider.fallback` events carry the error's `name` and `code` with a generic message, and the full error is logged. Pass `exposeErrors: true` for the old behavior (`lousho dev` does). Channel `500`s no longer echo internal errors either.
-- `fromUIMessages()` (and `POST <base>/ui`) keeps only `user` and `assistant` messages from the client; a client-sent `system` message is dropped.
-- OAuth: a principal without an issuer gets tokens namespaced by its authenticator, so the same id from Slack and GitHub no longer shares a token (docs/oauth.md has the one-time move); `telegramChannel` and `teamsChannel` send a sign-in link only in a 1:1 chat; the `[REDACTED]` net for `ctx.getToken()` tokens also covers thrown errors, object keys, URLs, class instances and base64 forms of the token.
-- `serveMcp` over HTTP validates `Host` and `Origin` against DNS rebinding (new `allowedHosts` / `allowedOrigins`), and loopback checks there and in `WebhookTriggerAdapter` accept exactly `localhost`, `127.x.x.x` and `::1` (`127.attacker.example` passed).
-- The `openrouter` provider without `apiKey` reads `OPENROUTER_API_KEY` and no longer sends `OPENAI_API_KEY` to openrouter.ai.
-- Slack and Discord signatures accept a timestamp at most a minute ahead (was five minutes either way), read in seconds; `discordChannel` refuses timestamps more than five minutes old. `githubChannel({ deliveries })` takes a shared `DeliveryStore` for `X-GitHub-Delivery` replay protection.
-- The `@modelcontextprotocol/sdk` peer range is `^1.31.0` (was `^1.30.1`): 1.30.x is affected by GHSA-6qxp-vccf-f47h, which MCP OAuth relies on.
-- `SubprocessSandbox`: `writeFile()` stays under the new `root` option (`LOUSHO_SANDBOX_PATH_DENIED`, also through symlinks), and containers run as `1000:1000` with all capabilities dropped, `no-new-privileges` and default limits (512 MiB, 256 pids, 1 CPU); pass `user: 'root'` for the old user. See [Guardrails](docs/guardrails.md#sandboxed-tools).
-
-### Changed
-- **Behavior change:** session turns keep the checkpoint history of the latest 10 committed turns (`agent.session({ id, turnHistoryLimit })`; `0` keeps none); storage used to grow with the square of the conversation. Excess history already in a store is deleted over the next commits, also when each turn uses a new process or store object. New `fileStore(dir).prune({ olderThanMs })` returns `checkpointHistory` too; `fileStore()` returns the new `FileStore` type.
-- **Behavior change:** a checkpointed run holds a run lease while it executes (new optional `CheckpointStore.acquireLease()`, `releaseLease()`, `renewLease()`, `saveIfLeased()`; file, SQLite, memory and best-effort KV stores). A second process, replica or store object that sends to the same session, resumes it or resolves its approval gets `LOUSHO_SESSION_BUSY` instead of running its tool calls again, and a stalled holder can no longer overwrite the run that took over. A dead holder on the same host is taken over at once; on another machine 30-60 s after its last heartbeat. Schedule fires are claimed the same way, so replicas fire a tick once. See [Run leases](docs/durable-execution.md#run-leases).
-- **Behavior change:** approvals run at most once: deciding one re-saves the turn as `'in-progress'` with the call in `Checkpoint.startedToolCallIds`, and resuming after a crash mid-call gives it a `kind: 'interrupted'` tool error instead of running it again. Resolving an approval whose run was deleted or replaced fails with `LOUSHO_APPROVAL_ORPHANED` and withdraws it.
-- **Behavior change:** a session turn paused for approval locks the session id: a new turn on it throws `SessionAwaitingApprovalError` (`LOUSHO_SESSION_AWAITING_APPROVAL`) until the approval is decided or `discardPending()` drops the turn.
-- **Behavior change:** a deterministic provider error records `lastError` on the turn's checkpoint, and later calls on that session fail fast with `LOUSHO_SESSION_TURN_FAILED` instead of replaying the failing turn; `resume()` retries it.
-- **Behavior change:** run ids (`send({ sessionId })`, a fork's `newSessionId`) are 1-200 characters of `A-Za-z0-9_.-` on every store and may not end in `.turn-<n>`, `.paused` or `.fire`; `''` is refused. Session ids (`agent.session({ id })`, the routes) stay 1-128 characters of `A-Za-z0-9_-`. The error messages now say which of the two rules applies.
-- **Behavior change:** with a store, tools, `needsApproval`, permission rules and hooks get the session id as `ctx.sessionId`, not the checkpoint key `<id>.turn-<n>` (new `ExecuteOptions.contextSessionId`).
-- **Behavior change:** a model step with several calls that need approval pauses once, on all of them (`result.approvalIds`, `agent.approvals.resolveAll()`); calls that need no approval run before the pause. See [Several calls in one step](docs/approvals.md#several-calls-in-one-step).
-- **Behavior change:** `once()` no longer remembers a yes from a `createAgent({ approve })` callback, and `'defer'` is reserved: an approval note that is exactly `'defer'` defers.
-- **Behavior change:** `approvalTtlMs` and an `ask` rule's `ttlMs` above 100 years throw `LOUSHO_CONFIG_INVALID` (they meant "never expires").
-- **Behavior change:** memory items are keyed `<slot name>#<scope key>`, so two slots on one scope no longer share items. Run `migrateMemoryKeys(slot)` once to copy items stored under the old bare key. See [Memory](docs/memory.md#items-from-before-slot-name-keys).
-- **Behavior change:** a prompt schedule runs every fire in its own session `schedule-<name>-<fire time>` (`defineSchedule({ sharedSession: true })` keeps one shared session), and a fire that does not finish `'stop'` reports the new `LOUSHO_SCHEDULE_RUN_INCOMPLETE`.
-- **Behavior change:** channels without a `store` keep transcripts in the agent's `createAgent({ store })` when it has `sessions`.
-- **Behavior change:** the routes let a session turn run to its end and save it when the client disconnects (`onDisconnect: 'abort'` for the old behavior; `waitUntil` keeps a serverless function alive). An aborted turn keeps the user's input, the tool calls that ran and the partial reply (`metadata: { interrupted: true }`), and its usage counts.
-- **Behavior change:** tool results are capped at `maxToolResultChars` (default `50_000`, `Infinity` for none) for every tool; MCP image/audio/blob data reaches the model as a placeholder and MCP tool descriptions are cut at 2,000 characters.
-- **Behavior change:** a user file part the provider cannot send rejects the call with `LOUSHO_UNSUPPORTED_CONTENT` (under fallback the next provider gets it) instead of a text note; `unsupportedFiles: 'text-note'` keeps the note. See [Multimodal input](docs/providers.md#multimodal-input).
-- **Behavior change:** `createAgent({ provider })` with a built-in or `fromAiSdk()` provider and no `retry` wraps it in `withRetry()` (provider's `maxRetries`, default 2), and `withRetry()` is the only retry layer: the built-in providers turn the `ai` SDK's own retries off (`retry: false` used to send 3 requests, `maxRetries: 3` sent 12).
-- **Behavior change:** a rate-limited call has the code `LOUSHO_PROVIDER_RATE_LIMITED`, and an out-of-credit account (`insufficient_quota`, 402) is the new non-retryable category `quota-exceeded`.
-- **Behavior change:** `OpenAIProvider` sends `store: false` on the Responses API unless `store: true` is set.
-- **Behavior change (types):** `LLMProviderConfig` has no index signature, so a misspelled option is a type error; `LLMProviderRegistry.register()` / `create()` take the provider's own config type (new `BuiltinProviderConfigs`). `ExecutionFinishReason` is a closed union, and an unknown provider finish reason is reported as `'other'`.
-- **Behavior change:** `agent.stream()` rethrows the run's error after the `error` and `run.done` events (`{ throwOnError: false }` for the old behavior).
-- **Behavior change (CLI):** every usage error exits 2 and 1 means a command ran and failed. `lousho eval`, `build`, `dev`, `chat`, `acp`, `mcp` and `doctor` load `./.env`. The fallback registry URL points at the installed version's release tag.
-- **Behavior change:** `connectMcp()` rethrows a server's start failure as `McpStartError` (`LOUSHO_MCP_START_FAILED`, with exit code and the last stderr lines) instead of wrapping it.
-- Evals: `t.maxCostUsd(n)` fails when a run reports no cost (`{ unknownCost: 'skip' }` for the old, now warning, behavior); `judge.model` and `llmJudge()` / `llmCritique()`'s `model` are optional.
-- Pruned tool results leave a stub naming the call and its arguments (`[pruned: search({"query":"deploy"}) result, 18234 chars; already read]`).
-- 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).
-- Cost: built-in prices for more default models (Ollama `llama3` window, OpenRouter variants), cache read/write prices (`cachedInputCostPerMTok`, `cacheWriteCostPerMTok`, `cacheWriteTokens`) and OpenRouter's reported `usage.cost` for `costUsd` and `limits.maxCostUsd`.
-- Approvals: `remember: 'session'` and edited `args` on a decision, `'defer'` from an `approve` callback, `approvalTtlMs` / `ttlMs` deadlines (`expiresAt` on events and UI state), `agent.approvals.list()` across processes (new optional `ApprovalStore.list()`), `agent.pending()` for unfinished runs (new optional `CheckpointStore.list()`), and `resumedAfterApproval` on tool-call hook contexts. See [Approvals](docs/approvals.md) and [Recovering after a crash](docs/durable-execution.md#recovering-after-a-crash).
-- Routes: `authorizeSession` and `authorizeApproval` on `createRouteHandler()` / `createDeployedServer()`; approvals report their `sessionId` and error events their `code`. Built node and Docker servers drain on SIGTERM (`shutdown({ timeoutMs })`, `LOUSHO_SHUTDOWN_TIMEOUT_MS`). Channel routes decide each call of a multi-call pause and accept a `sessionKey` after a restart.
-- Flows: durable runs (`checkpointStore` + `runId`, `FlowExecutor.resume()`), pausing for approval (`status: 'awaiting-approval'`), per-node `retry` and `timeoutMs`, cancellation through `signal`, and `usage` on the result. See [Flows](docs/flows.md).
-- Structured output: partial-object streaming (`object.delta`, `partialObject` in the UI bindings), `result.outputRepaired`, `{ schema, promptSchema: false }`, a forced no-tools answer when `maxSteps` or `limits.maxSteps` runs out, and `outputError.kind: 'truncated'`. Unions, records, tuples and optional fields now work on strict endpoints. See [Structured output](docs/structured-output.md).
-- Memory: `expose: { forget: true }`, `itemSchema` / `itemKey` upserts (new optional `MemoryProvider.upsert()`), `memoryKey()`, de-duplicated `add()`, and `migrateMemoryKeys()`. See [Memory](docs/memory.md#correcting-memory).
-- MCP: `optional: true`, `cwd`, `stderr`, `connectTimeoutMs`, `timeoutMs`, `tools: { include, exclude }`, per-call `approval({ args })`, `onToolsChanged` and `McpConnections.reconnect()`. See [MCP](docs/mcp.md).
-- Observability: `invoke_agent` spans carry the request model and token totals (`agentUsageTotals: false` leaves them off), `legacyAttributes: false`, `parentSpanId` on `send()` / `stream()`, retry attributes on `chat` spans, sub-agent names on their spans, and compaction calls as counted `chat` spans. See [Observability](docs/observability.md).
-- Tools and sub-agents: `defineTool({ timeoutMs })`, `subagentOptions: { background: false }`, `read_skill_file` for skill folders, `ToolDescriptor.transient`, `CommandRule` objects for the shell tool's `allow` / `deny`, and an optional `ShellProvider.shell` that tells the model which shell runs its commands.
-- Compaction: `reserveOutputTokens` and `onCompaction` on the object form; `GenerateHookContext.generate()` for counted side calls.
-- Evals: sub-agent tool calls in trajectory evals, `SendOptions.onEvent`, `repeat` / `passAt`, `{ agent }` for `setProviderInterceptor` callbacks, `lousho eval --timeout` and `defineEval({ timeoutMs })`, and `recordReplay({ rerecordHint })`. See [Evals](docs/evals.md).
-- 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.
-- OAuth: concurrent `ctx.getToken()` calls share one refresh, and a refused refresh no longer deletes a newer token.
-- Approvals and memory: a run resumed after an approval or a crash keeps its memory tools and the scope it paused with; memory stays on after a handoff; recall errors skip the slot with a warning; invalid scopes fail with `LOUSHO_MEMORY_INVALID`; keyword recall matches whole words; `<memory` tags in item text are escaped; `recall_<name>` returns scores and metadata.
-- Providers on `ai` 4, 6 and 7: tool errors are no longer wrapped twice on `ai` 7, malformed or truncated tool-call JSON reaches the model as a repairable `LOUSHO_TOOL_ARGS_INVALID` error (light repairs are tried first; `tool.start` has `rawArgs`), prefixed tool names (`functions.read_file`) resolve, unknown tools suggest the closest name, duplicate tool-call ids both run, a completion sent to a streaming request is replayed, mid-stream and `finish_reason: "error"` failures become retryable 502s, a stream that fails before any output is retried, and unset `temperature` / `maxTokens` are left out. `withFallback()` keeps its state per call, so concurrent calls no longer misreport fallbacks or book cost under the wrong model, and `withRateLimit()` over `withRetry()` streams reports the final attempt and holds its slot until the retried stream ends.
-- Provider errors: local runtimes' context overflows are `context-length-exceeded`, refused connections name the URL, status and message are read together, nested OpenRouter reasons are shown, a long `Retry-After` fails at once instead of sleeping, negative hints are ignored, and compacted errors keep their category through `createAgent()`. A missing provider package fails with `LOUSHO_PEER_MISSING`, and the routes send its `npm install` command to the client.
-- Provider features: `reasoning` reaches more models and warns once when it is dropped; image MIME types are sniffed; `OpenRouterProvider` honours `baseURL` and `OllamaProvider` sends `headers` and `apiKey`; `supportsTools()` knows current models; registered providers work in model strings; retired fallback models are replaced; price lookup handles OpenRouter spellings; the forced answer at `maxSteps` works on Claude.
-- Runs: abort no longer waits on a provider or tool that ignores the signal (`finishReason: 'aborted'`, `result.abortReason`; `mockModel` honours `signal`), aborted streams keep their text, a throwing event listener or trace exporter no longer fails the run, tool results with cycles, BigInts, Maps or Sets serialize, `send(result.messages)` does not repeat the system prompt, `send([])` throws `LOUSHO_CONFIG_INVALID`, a `finish_reason: tool_calls` reply without calls ends `'stop'`, a `load_skill` tool that clashes with `skills` throws, `maxSteps` must be a whole number >= 1, and handoffs work on local models and Anthropic (no mid-conversation system message).
-- Structured output: the repair and forced-answer prompts stay out of transcripts, near-miss replies (prose, `<think>` blocks, fenced JSON) are accepted without a repair call, a reply that repeats the schema gets a clearer repair message, and unsupported root unions or zod 4 `z.date()` fields throw a `ConfigurationError` naming the fix. `defineTool()` rejects inputs no model can satisfy and accepts `z.preprocess` dates on zod 4.1+.
-- Compaction: summarizing splits oversized histories, counts tool definitions and the output schema, warns when it falls back to a 128,000-token window for an unknown model, caps `protectedTokens` at half the threshold, retries the summarizer after a rejection, counts its call in usage and budgets, and reports `appliedStrategy`.
-- Sub-agents and handoffs: dynamic sub-agent config functions get the lead's `sessionId`, `metadata` and `principal`; a failed sub-agent's spend counts; truncated answers say so; agent-directory and Worker `subagents/` run as native sub-agents; a handoff target's `toolSearch` applies.
-- Schedules: a fixed-hour cron job in a spring-forward gap runs once after the gap instead of being skipped.
-- Flows: a failed `parallel` branch aborts its siblings, `forEach` variables are per iteration, unnamed steps get unique ids, and `resume()` refuses a changed flow (`LOUSHO_FLOW_CHANGED`).
-- MCP: `Not connected` counts as a dropped connection and reconnects, `tools/list` follows every page, dropped servers report `'failed'` with their stderr, calls honour abort, text-only results are sent once, tool names are made valid for every provider, object schemas with a sibling `oneOf` keep their shape, `agent.ready()` reconnects after `close()`, and `serveMcp()` over HTTP cancels the run a client cancels or abandons (matched by its new `Mcp-Session-Id`) and rejects its pending approvals. `serveAcp` keeps serving after a malformed JSON line.
-- Channels: redelivered webhooks run once (Telegram, GitHub, Slack), concurrent decisions on one approval decide it once (`409 LOUSHO_APPROVAL_CONFLICT`, also on the routes), `webhookChannel` authenticates on Fetch hosts and its pause replies carry the prompt, `githubChannel` ignores `/approve` for unknown approvals, and channel `metadata` reaches the run. `POST <base>/ui` answers 400 for an invalid id, and `auth: ''` is `LOUSHO_AUTH_CONFIG_INVALID` on `createRouteHandler()` and `serveFetch()`.
-- UI bindings (React, Vue, Svelte): remote mode keeps one session across turns, a stream that ends early becomes an error, each step starts a new paragraph, abnormal endings set `status: 'error'`, React gains `reset()`, server error messages are kept, Svelte no longer aborts on a transient subscribe, `formatUsage()` shows small costs, and `parseEventStream()` joins multi-line `data:` fields.
-- Tracing and OpenTelemetry: open spans are bounded without losing parents, queued background sub-agents stay in the lead's trace, background sub-agent cost rolls up, and `execute_tool` spans carry the error message.
-- Evals: replay matches calls by request, sub-agent cassettes are named after the agent, cassette names include a hash of the case label, re-recording unchanged exchanges leaves no diff, tool order no longer breaks replay, reasoning and full usage are recorded, judge scores parse more formats (the last `SCORE:` wins) and judges see the user's input at temperature 0, `lousho eval` gives live cases 10 minutes and its reports are never empty when vitest fails.
-- CLI: `lousho dev` reloads CommonJS tool files and recreated folders, tool files no longer print `MODULE_TYPELESS_PACKAGE_JSON`, TypeScript syntax that type stripping cannot erase gets an error suggesting `--experimental-transform-types`, every agent command loads `tools/*.ts` of an installed project (one ESM build, shared brands, `instanceof` across ESM and CJS copies), `lousho build` reports bundling failures as `LOUSHO_DEPLOY_FAILED`, warns about missing provider packages, merges an existing `wrangler.toml` (new default `compatibility_date` `2026-09-01`), no longer needs unused provider packages for a Worker and prints where it wrote, Docker images run as `node`, `lousho doctor` and `lousho mcp` accept agent directories, `lousho add` checks flags and target directories up front and falls back to GitHub when the default registry is down, `lousho init` templates and Windows instructions are fixed, `init` says when the provider's API key is missing and git-ignores an `--sdk-path` tarball, and help texts and messages are clearer.
-- Agent directories: every `createAgent()` override passed to `loadAgentDir()` is forwarded, `mock/<name>` models work from every entry point, and import failures throw `LOUSHO_AGENT_DIR_INVALID` with an install hint. `loadSkills()` skips a loose `README.md`.
-- Workspace tools: `grep` refuses catastrophic regexes and runs with a time budget, `edit_file` refuses non-UTF-8 files instead of corrupting them, and `tool_search` ranks synonyms and word families.
-- Agent Forge: agents are read from and written to `.lousho/agents/`, narrow screens and keyboard and screen-reader use work, invalid names and imports show errors instead of a blank page, finished runs report `done`, and several drawing and status glitches are fixed.
-- Packaging and types: ESM consumers get `.d.mts` declarations (plus `typesVersions` for `node10`), declarations type-check with `skipLibCheck: false` on zod 3 and 4, the pi peers are caret ranges, `llms-full.txt` no longer ships and the Worker entry has no source maps.
-- Docs: corrections throughout (sessions vs runs under one id, schedules, nextjs approvals, memory, `engines.node`), the snippet check now also runs every snippet that builds its own mock provider and checks fences indented in lists, and the ops-pipeline example works as described.
-- A checkpointed session turn that stalled past its run lease and then failed for good no longer stamps its `lastError` (`retryable: false`) on the checkpoint of the process that took the turn over, which bricked that turn forever with `LOUSHO_SESSION_TURN_FAILED`: the session now holds the turn's run lease itself (handed to the run as `HELD_RUN_LEASE`) and `recordFailure()` writes through `RunLease.save`, whose fenced save writes nothing once the lease is lost.
-- `agent.send(msg, { sessionId })` and a fresh `agent.session({ id })` no longer run beside a session turn that waits on an approval when its `<id>.paused` marker was never written (a crash or a send between the executor's awaiting-approval checkpoint and `markPaused()`): `pausedSessionTurn` now also scans the store's `<id>.turn-*` checkpoints for `status: 'awaiting-approval'` when the marker is absent, on stores that implement `list()`.
-- A streamed tool call whose deltas repeat its `id` while omitting `index` (the OpenAI-compatible / Gemini-proxy servers the tool-call id rewrite exists for) stays one call: each repeat no longer mints a `call_1_2`, `call_1_3`, … id that split the arguments JSON across phantom calls none of which parses; the call's slot in the delta's `tool_calls` stands in for the missing `index`.
-- A non-streamed request whose body carries a nested `"stream": true` (a `providerOptions` passthrough, tool arguments, gateway metadata) no longer has its JSON reply rewritten into an SSE stream the consumer cannot parse: whether a request asked for streaming is read from the parsed top-level `stream` field instead of a regex over the raw body.
-- Session routes: two concurrent first-touch turns on one unowned session no longer both pass the owner check - the claim is atomic now, so the loser is refused (`403 LOUSHO_SESSION_FORBIDDEN`) instead of streaming a turn inside the winner's session; a claim lost while a turn ran clears what it stored and ends the stream on the same coded error.
-- 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.
-- 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, 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.
-- 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.
-- 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
-
-Everything published from 1.0.0-alpha.15 (2026-10-06) through 1.0.0-alpha.19
-(alpha.17 on 2026-10-07, alpha.18 and alpha.19 on 2026-10-08). Most of it was
-prepared on `main` under the version number 1.0.0-rc.0, which was never
-published. Upgrading from an earlier `1.0.0-alpha.*` release? Read the
-[upgrade guide](docs/upgrading.md): imports moved to subpaths, dead and
-superseded APIs were removed, and the patch guardrails are now patch checks.
-What 1.0 considers public is defined there (every `exports` entry and the
-checked-in `api/` reports).
-
-### Breaking
-- Flows, the Jira / GitHub / Slack / email tools, encryption, `StorageService` and the validators moved out of the package root. Import them from their subpath: `FlowBuilder`, `FlowExecutor`, `validateFlow` and every flow type (`AgentFlow`, `EditorStep`, `FlowExecutionEvent`,...) from `@lousho/build-ai-agent/flows`; `createJiraTools`, `createGitHubTools`, `createSlackTool`, `slackTool`, `postSlackAlert`, `createEmailTool` and their types from `@lousho/build-ai-agent/integrations`; `EncryptionUtils`, `DTOEncryptionFilter`, `DecryptionError`, `sha256`, `generatePassword`, `StorageService`, `StorageServiceApprovalStore`, `LocalStorageCheckpointStore` and the validators (`validateWithSchema`, `safeValidate`, `isValidEmail`,...) from `@lousho/build-ai-agent/utils`. The integrations are no longer in `@lousho/build-ai-agent/tools` and the flow types are no longer in `@lousho/build-ai-agent/types`. Nothing else changed: the classes and functions are the same. For file-backed stores with `createAgent()`, prefer `fileStore(dir)`.
-- Removed `AgentType`, `AgentTypeDescriptor`, `AgentConfig.agentType`, `AgentBuilder.setType()` and the agent-type registry (`agentTypesRegistry`, `getAgentTypeDescriptor`, `getAllAgentTypeDescriptors`, `isValidAgentType`, `validateAgentConfig`, `validateAgentTools`). They had no runtime effect since 1.0.0-alpha: delete the `setType(...)` call and the `agentType` field. Also removed, because nothing implemented or used them: the repository interfaces (`IRepository`, `IAgentRepository`, `ISessionRepository`, `IResultRepository`, `SessionData`, `ResultData`, `SDKRepositories`), `DataLoadingStatus`, `PaginationParams`, `PaginatedResponse`, `DeepPartial`, `Timestamped`, `IdEntity`, `AgentExecutionOptions`, `AgentExecutionResult`, `AgentDefinition` and `ToolSetting`. If your code used one of these types, copy its declaration into your project. A checkpoint saved with `agentType` still loads; the field is ignored.
-- Removed `ExecuteOptions.onEvent` and the `ExecutionEvent` / `ExecutionEventType` types, deprecated in an earlier alpha. Pass `onAgentEvent` to `AgentExecutor.execute()` / `stream()` / `resumeAfterApproval()` instead (with `createAgent()`, `onEvent` already receives `AgentEvent`s and is unchanged). The mapping from the old event names to `AgentEvent` types is in docs/streaming.md#listening-without-iterating ("Migrating from `onEvent` / `ExecutionEvent`"). The one-time "onEvent is deprecated" warning is gone with it.
-- Removed `createDelegateTool()`, `DelegateAgentOptions`, `DelegateAgentResult` and `DelegationDepthExceededError`. Use the `subagents` option instead, on `createAgent()` or `AgentExecutor.execute()`: create the child with `createAgent({ provider, instructions, description })` and pass `subagents: { billing }`. The model gets one `task` tool for every sub-agent, with the same inheritance (hooks, permissions, abort, usage roll-up) and a depth limit (`maxSubagentDepth`, default `1`). A run at the depth limit is not offered the `task` tool, so a delegation cycle can no longer start; `DelegationDepthExceededError` is gone. See docs/sub-agents.md.
-- The executor API moved out of the package root to `@lousho/build-ai-agent/executor`: `AgentExecutor`, `AgentBuilder`, `ExecuteOptions`, `resumeAfterApproval`, `streamResumeAfterApproval`, `resumeRequest`, `ResumeExecuteOptions`, `ResumeRequest`, `ToolRegistry` and `globalToolRegistry`. Change `import { AgentExecutor, AgentBuilder } from '@lousho/build-ai-agent'` to `import { AgentExecutor, AgentBuilder } from '@lousho/build-ai-agent/executor'`. `ToolRegistry` is also still in `@lousho/build-ai-agent/tools`. The `@lousho/build-ai-agent/core` subpath is removed: import `AgentBuilder` from `@lousho/build-ai-agent/executor`. `createAgent()`, `ExecutionResult` and every type `createAgent()` uses stay in the root. To move off the executor API entirely, see docs/migrating-to-create-agent.md.
-- The patch guardrails are now called patch checks, so "guardrail" only means the input/output/tool guardrails of `createAgent({ guardrails })`. Rename: `runGuardrails` to `runPatchChecks`, `Guardrail` to `PatchCheck`, `GuardrailResult` to `PatchCheckResult`, `ProposedAction` to `ProposedPatch`, `RunGuardrailsResult` to `RunPatchChecksResult`, `runGuardrailSafely` to `runPatchCheckSafely`, `secretScanGuardrail` to `secretScanCheck`, `createDiffSizeGuardrail` to `createDiffSizeCheck`, `createCommandGuardrail` to `createCommandCheck` (options type `CommandCheckOptions`), `createTestRunGuardrail` to `createTestRunCheck`, `createLintGuardrail` to `createLintCheck`. Arguments, results and behavior are unchanged. `SECRET_PATTERNS` keeps its name.
-
-### Security
-- **Behavior change:** MCP tools now ask for approval by default (`approval: 'always'`). A server's own `readOnlyHint` / `destructiveHint` no longer switch approval off or let a tool run in plan mode unless its entry opts in with `approval: 'annotations'` (loaded descriptors then carry `metadata.mcp.annotationsTrusted: false`). An MCP tool whose `<server>__<tool>` name equals a local tool's is refused with `LOUSHO_CONFIG_INVALID` instead of silently replacing it and its approval gate. Set `approval: 'annotations'` on servers you trust to keep the old behavior. See [MCP](docs/mcp.md#approval-for-mcp-tools).
-- `openApiTools()` can refuse private destinations: with the new option `privateAddresses: 'refuse'` (default `'allow'`, unchanged), every operation request and the document fetch, each redirect hop included, fails when its host is or resolves to a loopback, link-local, private or reserved address. Host names go through the pinned DNS lookup `http_request` and `web_fetch` use (one resolution per connection, every address checked, the socket connects to the checked address), so DNS rebinding cannot reach a private address; IP literals in every form `URL` normalizes (decimal, octal, hex, IPv4-mapped IPv6) and `localhost` / `*.localhost` are refused when the tools are made. `allowPrivate` lists hosts that may be private. `'refuse'` cannot be combined with a custom `fetch` (it throws a `ConfigurationError`: a custom fetch's connections cannot be pinned) and needs Node.js (`undici`, `node:dns`); where undici cannot load, making the tools throws a `ConfigurationError`. See docs/openapi-tools.md#security-rules.
-- The registry permission manifest is now enforced when an agent directory loads and runs. `loadAgentDir` re-hashes every file the `lousho-registry.json` receipt lists; an item with edited or missing files is reported `unattested` (a warning naming the item and files, and `manifest.registry` on `resolveAgentDir()`, which also gains the new `Attestation`, `RegistryItemStatus` and `RegistryStatus` types) without refusing the load. Every tool a receipt item owns then runs inside the manifest accepted at install: an `exec: true` or `needsApproval: true` item's tools - and any unattested item's tools - always wait for approval (a tool's own `deny` still denies); `fetch` while the tool runs is limited to the declared `network` hosts; `process.env` shows only the declared `env` names; and a `requiresSandbox` tool gets a narrowed adapter (`run()` refused without `exec`, `writeFile()` without `filesystem: "write"`, a command env of the non-secret base plus the declared variables only). The envelope stays as narrow as the last accepted manifest until `lousho add <name> --overwrite` attests the current files. Limits, unchanged: the guards intercept `fetch` and `process.env`, not `http`/`net`/`axios`, the filesystem, module-scope captures or a container's own network policy; the manifest is still not a sandbox. See docs/registry.md#permission-manifest.
-
-### Changed
-- The published package is smaller: ~873 files / ~13.5 MiB unpacked / ~3.65 MiB packed, down from ~902 / ~20.8 MiB / ~5.6 MiB. Test-only files that still shipped (`*.test-d.ts` type tests, `*.testkit.ts` helpers, `__snapshots__/` and the test-replay `__cassettes__/` directories) and the Agent Forge server source map no longer ship, and the SDK's own source maps no longer embed `sourcesContent` — their `sources` still resolve to the shipped `src/`, so `--enable-source-maps` stack traces keep working. `pack-smoke` now also runs `build:studio`, so it measures the tarball that is actually published, and it fails when a file `lousho build` or `lousho studio` needs is missing.
-- Test files are type-checked (`npm run typecheck:tests`, in CI); `pack-smoke` also checks the published declarations with `skipLibCheck: false`.
-
-### Added
-- Agent directories: new `agent.*` config keys `permissionMode`, `permissions` (a serializable rule form: `tool` is a name, a list or - in a code config - a `RegExp`; `when` narrows the rule with a record of argument names to matchers - a regular expression string or an operator object (`eq`/`ne`, `lt`/`lte`/`gt`/`gte` on `Number(arg)`, `matches`), or a predicate in a code config; `action` is `allow` / `ask` / `deny`), `compaction`, `limits`, plus `hooks` and `approve`, each a path (relative to the directory) to a file default-exporting the hook(s) / the approver function, or the value inline in a code config. `instructions/<family>.md` appends to `instructions.md` when the resolved model id contains `<family>` (e.g. `openai`, `anthropic`). `lousho build --target=node-server` (and `--target=docker`) bundles a root `hooks.*` / `approve.*` file next to the config and resolves the compiled `.js` sibling; the Cloudflare Worker target carries `permissionMode`, `permissions`, `compaction` and `limits` over and accepts `hooks` / `approve` from a code config (a file path is refused, a Worker cannot import it). See [Agent directories](docs/agent-directories.md).
-- Registry: a new item `type` `kit` is a whole agent directory - its `files` may sit at any (still safe) relative path - so `lousho add <kit> --dir <target>` installs `agent.*`, `instructions.md`, tools, skills and sub-agents in one item, under one permission manifest, and records it in `lousho-registry.json` like any other item. The default registry's first kit is `coding-kit`, a port of the `examples/coding-harness` baseline: workspace tools with checkpoint rewind, an allow-listed shell, permission rules, a loop guard and output cap as hooks, a compaction setting, a `fix-failing-test` skill and a read-only `explorer` sub-agent (manifest: `exec`, `fs-write`; install with `lousho add coding-kit --dir <dir> --yes --allow exec,fs-write`). See [Registry](docs/registry.md).
-- The `pi` provider: `createAgent({ model: 'pi/<pi-provider>/<model>' })` routes calls through `@earendil-works/pi-ai` (`1.0.3`, a new optional peer - `npm install @earendil-works/pi-ai@1.0.3`), the engine `pi-coding-agent` runs on, so pi's whole catalog (OpenRouter, Anthropic, OpenAI, Google,...) is usable natively; e.g. `pi/openrouter/openai/gpt-4o-mini` is OpenRouter's `openai/gpt-4o-mini` (nested slashes are kept: the segment after `pi/` is the pi provider, the rest the model id). Messages (including reasoning blocks, tool calls/results and image parts), tool `parameters` (raw JSON Schema, zod 3/4 or Standard Schema), streamed chunks and usage/cost map to the same surface the `ai`-SDK providers expose, and pi's own retries are pinned off so `retry`/`fallbackModels` stay the only retry layer. Credentials are per nested provider: pi reads each one's own env var (`pi/openrouter/...` reads `OPENROUTER_API_KEY`), and a missing one fails the call with `LOUSHO_PROVIDER_MISSING_API_KEY` naming it; a missing package fails with `MissingPeerDependencyError` naming `npm install @earendil-works/pi-ai@1.0.3`. New export `PiProvider` (+ `PiProviderConfig`, whose `models` injects custom/faux catalog entries). `pi` is Node-only: the `cloudflare-worker` target refuses `pi/...` specs. See docs/providers.md#the-pi-provider.
-- `piAgent()` ("pi-coder"): a Pi coding-agent session (`@earendil-works/pi-coding-agent`, a new optional peer) usable in-process as a `createAgent({ subagents })` entry - `subagents: { coder: piAgent({ cwd, model, description, permissions }) }`. Each `task` call is one Pi session under the task's `sessionId`, so `taskId` resumes and approval resumes reopen the same JSONL transcript even across a restart. `permissions` (the same `PermissionRule`s as `createAgent()`) gate every Pi tool call through a `tool_call` extension handler: `deny` refuses it, `ask` pauses the lead run durably for approval when the caller can pause and refuses it otherwise; approving re-issues that exact call once (Pi has no run-blocked-call API, so a decision prompt asks the model to repeat it and the gate lets that one call through), rejecting sends the note as the next turn. Pi usage rolls into the lead's `result.usage`, and aborts propagate to the Pi session. Node-only: the package is loaded lazily, so a consumer without it still typechecks and `run()` fails with `LOUSHO_PEER_MISSING`. Also new: `defineRemoteSubagent(impl)` wraps any `RemoteSubagent` implementation (same contract as `remoteAgent()`), and `SubagentApprovalPause` is exported for such adapters.
-- Agent directories: three more `agent.*` config keys wire the approval surface. `approvalTtlMs` is `createAgent`'s run-level default for how long a pause for approval stays decidable (milliseconds); a `permissions` `ask` rule may set `ttlMs`, bounding that rule's pauses and winning over `approvalTtlMs` (both positive finite numbers, rejected otherwise). `store` declares a durable store so paused approvals survive restarts ("draft today, approve tomorrow"): `{ "dir": "./.lousho" }` (resolved against the agent directory, staying inside it) becomes a `fileStore()` - sessions, checkpoints and approvals as JSON files, with `historyLimit` / `tokenKey` also declarable; a code config may set an `AgentStore` instance instead. `store` is Node-only: the Cloudflare Worker target rejects it. `loadAgentDir(dir, { approve: null })` / `{ hooks: null }` strip the directory's wiring (the file the config names is not even imported), where `undefined` keeps it. The generated node-server / docker server keeps a config-declared `store` unless `LOUSHO_STORE` is set. See [Agent directories](docs/agent-directories.md).
-- Agent directories: `"engine": "pi"` in a `subagents/<name>/` config makes that directory a `piAgent()` coding sub-agent instead of a nested `createAgent()` one - it lands in the parent's `subagents` map (the `task` tool) and its sessions run in the parent's directory, the workspace both share. Its `model` is the usual `pi/<provider>/<model>` id and its `permissions` gate the Pi session's own tool calls; the remaining config keys are ignored (Pi carries its own prompt and tools). `loadAgentDir()`'s new `piAgent` override injects `PiAgentOptions` into every such sub-agent (a faux `modelRuntime` in tests, a `sessionDir` for durable approvals); the directory always wins `cwd`, `name` and `description`. Cloudflare Worker targets reject `engine` - Pi needs the Node runtime. The default registry's second kit, `coding-pi`, is `coding-kit` on the full Pi stack: pi-provider lead, dir-declared pi coder, same safety rails (install `--allow exec,fs-write,network,env`). See [Agent directories](docs/agent-directories.md#sub-agents).
-- The `approve` callback may return `'defer'` to abstain: the call stays pending (listed by `agent.approvals.list()`, resolvable by `agent.approvals.resolve()` / `streamResolve()` / `answer()`) and the run surfaces the pause - `send()` resolves with `finishReason: 'awaiting-approval'`, as if the callback had never been asked - so an approver can decide the calls it trusts and hand the rest to a human. Note: `'defer'` is now reserved; an approval note that is exactly `'defer'` defers instead of approving. See [Deciding in code](docs/approvals.md#deciding-in-code).
-- Tool-call hook contexts carry `resumedAfterApproval`: `true` only when `preToolCall` / `postToolCall` fire for the post-approval re-run of a call the run paused on (`agent.approvals.resolve()`, `resumeAfterApproval()`). Stateful hooks (loop guards, audit counters) can skip the re-fire with `if (ctx.resumedAfterApproval) return;`. See [Hooks](docs/hooks.md).
-- New `ToolDescriptor.transient` marks a tool bound per run (a memory slot's `remember_*` / `recall_*` tools, bound to the run's scope keys): it is left out of the agent fingerprint, so an approval-resumed run - whose registry intentionally does not rebind them - no longer reports `tools removed` agent drift on every resolve.
-- Approvals can expire. `createAgent({ approvalTtlMs })` (validated: positive finite) sets a default deadline for every pause, `send()`/`stream()` take a per-call override, a `permissions` `ask` rule may set `ttlMs` (wins over the run default), and `ExecuteOptions.approvalTtlMs` covers `AgentExecutor.execute()`; sub-agents inherit the lead's TTL unless they set their own. A pending approval past `expiresAt` resolves as denied with `'approval expired'` - enforced at decision time, so a durable-store resume (a restart, another process) can never approve a stale pause - and `list()` keeps expired entries (marked by `expiresAt`) so `resolve()` still continues the run. `approval.requested` events and `UIPendingApproval` carry `expiresAt` for UI countdowns; expiry writes an audited `deny` decision to `onPermissionDecision`. See [Approvals](docs/approvals.md).
-- `llmCritique(config)`: like `llmJudge` but returns `{ score, feedback }` - one judge call, a `SCORE:`/`FEEDBACK:` prompt, graceful degradation on malformed output - so evaluator-optimizer loops get actionable revision guidance, not just a number. See [Evals](docs/evals.md).
-- Testing helpers: `testToolContext(overrides?)` (`@lousho/build-ai-agent/testing`) builds a valid `ToolExecutionContext` for direct `tool.execute()` calls - `getToken`/`requireAuth` fail loudly unless stubbed - and `toolResultText(message)` (root export) unwraps a `tool` message's JSON-encoded content to its result text.
-- Channels: `ChannelInbound.metadata` now reaches the run as `SendOptions.metadata` (memory scopes and `when` contexts can key on channel-supplied data; it is unauthenticated, unlike `principal`), and `webhookChannel({ principal: (body, req) =>... })` can derive the caller principal from a verified body/header - so a webhook intake (PagerDuty, Grafana) attributes the run to the alerting system. See [Channels](docs/channels.md).
-- New registry kits and examples replicating the most-built agent archetypes: `inbox-triage` (channel intake → classify → draft → approval-gated send, per-sender memory, `@hourly` sweep; install `lousho add inbox-triage --allow env,fs-write`) and `incident-response` (webhook alert → diagnose → risk-tiered approvals → remediate → verify → audit timeline; install `--allow env,fs-write`); examples `deep-research` (orchestrator-workers fan-out with cited synthesis), `support-desk` (triage → `handoff()` to specialist agents), `evaluator-loop` (writer ↔ `llmCritique` revision loop) and `data-analyst` (text-to-SQL with read-only enforcement). Each runs offline on mock models and accepts `OPENROUTER_API_KEY` for a live pass.
-- `claudeProject(dir)`: loads a repository's Claude-Code-conventional context into options that spread into `createAgent()` — `CLAUDE.md`/`AGENTS.md` + `.claude/rules/*.md` become `instructions`, `.claude/skills/*/SKILL.md` load through `loadSkills()` unchanged, `.claude/agents/*.md` frontmatter becomes `subagents` (frontmatter `model` selects the sub-agent's model; `provider`/`model` options are the fallback), and `.claude/scratchpad/` gets a `scratchpad` note tool (name-validated `*.md` writes). Nothing in the directory executes: markdown is read as data, and `.claude/commands`, `settings*.json` and `mcp.json` are listed on `manifest.ignored` rather than loaded. See [Claude Code projects](docs/claude-projects.md).
-- `decide()`: typed answers from the OpenAI Decisions API (`POST /v1/decisions`, public beta — `gpt-6-luna` only) — `predicate` questions return a probability, `choice` returns a value plus per-option `probabilities` and `confidence`, `score` returns a rubric's probability-weighted level index, and any question may come back a `refusal`. Input is a string or messages with `input_text`/`input_image` (inline base64) parts; `apiKey` (default `OPENAI_API_KEY`), `baseURL`, `timeoutMs`, `signal` and `fetch` are overridable. It is the fast path for typed decisions (route/gate/score) — no agent turn and no generated prose — and does not go through providers or OpenRouter. See [Decisions](docs/decisions.md).
-- Four new examples covering the agentic-patterns catalog: `waves` (Workers · Aggregate · Verify · Extend — bounded parallel workers, deterministic merge, a typed `{ verdict, gaps }` verifier, extension waves seeded by its gaps), `phase-pipeline` (discuss → spec → plan → implement → proof gate → report on `FlowBuilder`/`FlowExecutor`, with the implement↔check retry ladder as a `oneOf` chain), `coding-agent-workflows` (a coding agent routed by a typed decision — `output` schema `{ route, confidence, reason }`, a confidence floor escalating low-confidence calls to the careful path), and `connectors` (MCP connectors à la Claude — runs fully offline against a mock `serveMcp` stdio server exposing `docs_*`/`slack_*` tools; README maps Google Docs, Slack, GitHub and Notion). Plus `hostinger-deploy`: build an agent with `lousho build --target=docker`, ship it to a Hostinger VPS over SSH and smoke-test `/health` + bearer auth + approval pause/resume. See [Prompting and context techniques](docs/prompting-techniques.md), [Connectors](docs/connectors.md) and [Hostinger VPS](docs/hostinger-vps.md).
-- `lousho add` has a default registry: without `--registry` or `LOUSHO_REGISTRY` it reads `https://registry.lousho.com/index.json` - the `registry/dist/` folder of this repository served as static JSON - instead of failing with "no registry configured; there is no hosted registry yet", so `lousho add --list` works out of the box. It carries five starter items: the tools `open-meteo-weather` (current weather by city through Open-Meteo, no API key) and `github-issues` (list and create issues through `api.github.com`; creating asks for approval), the skills `changelog` and `code-review`, and the `generic-webhook` channel (HMAC-SHA256 signature verification from `WEBHOOK_SECRET`). `--registry` and `LOUSHO_REGISTRY` still override it, and the new value `none` (in either place) disables the registry entirely with the old `LOUSHO_CONFIG_INVALID` "no registry configured" error, for offline or locked-down use. The items live in `registry/` as an `item.json` plus their files per folder; `npm run registry:build` validates each against the registry schemas, the path rules and the M7a code/manifest check, and writes the committed `registry/dist/` (`npm run registry:check` fails when it is stale and runs in CI). See docs/registry.md.
-
-### Fixed
-- A channel button click (Slack, Discord), inline-keyboard tap (Telegram), Adaptive Card press (Teams) or `/approve` command (GitHub) after a restart is now bound to the conversation's session before the approval is resolved, so its continuation is appended to the session transcript again. The decision names the conversation it came from (`inbound`); with checkpointed sessions (`mountChannels` `store` with `checkpoints`, e.g. a `SqliteStore`) it is accepted only when that session's pending turn waits on exactly that approval id and kind - a decision for another conversation, a replay of a decided one and a decision of the wrong kind are refused (`LOUSHO_APPROVAL_NOT_FOUND`) before the approval is touched, and `onDecision` audits only decisions that pass, so a replayed click cannot run the tool twice and the thread's next message continues the same session. Without a checkpoint store nothing can be checked, so the approval store alone decides, as before.
-- A channel's function `approvers` works after a restart: `ctx.approval(id)` asked only this process's `agent.approvals.list()`, so a pause the restarted process did not make looked the same as a denial and the function failed closed. `ApprovalStore` gains an optional `load(id)` - `resolve()` without removing the record; every shipped store implements it, and a custom store without it keeps compiling and behaves as before - and the new `agent.approvals.get(id)` reads through it. `ctx.approval` falls back to that, so the function sees the same request (`toolName`, `input`, `sessionId`, `principal`) it saw before the restart and fails closed only when no store knows the id (a process-local approval store still forgets its pauses at a restart).
-- A hand-written Cloudflare Worker can now bundle `createAgent`. The package root also exports file stores, the agent-directory loader, MCP over stdio and sandboxes, so bundling it for `platform: 'browser'` failed with `Could not resolve "async_hooks"` (and `crypto`, `fs/promises`, `http`, `net`, `stream`) - only the generated Worker ever bundled, because `lousho build --target=cloudflare-worker` redirects those imports to shims itself. `@lousho/build-ai-agent/worker` is a new subpath exporting `createAgent` (and its config types), `memoryStore`, the KV stores (`KVStore`, `KVCheckpointStore`, `CHECKPOINT_KV_BINDING`), the schedule helpers (`defineSchedule`, `handleScheduled`), `serveFetch` (the `/chat` API as a fetch handler), the providers a Worker can run and the whole Worker-safe subset agent-directory code may import. The SDK's own build produces it through the same Node-builtin/sandbox/QuickJS shims the adapter applies (plus new `ollama-ai-provider` and `@modelcontextprotocol/sdk` ones, which an external specifier would leave unresolvable and `mcpServers` therefore fails on first connect - use `lousho build` for MCP on Workers), so the published entry carries no `node:` import for a user's own bundler to fail on; `ai`, `zod`, `@opentelemetry/api` and the `@ai-sdk/*` provider packages stay external specifiers resolved from the user's install. Guarded by `src/deploy/worker.test.ts`; see docs/cloudflare-workers.md#writing-your-own-worker.
-- The published `.d.ts` files no longer import the types of optional peers: `SubprocessSandboxOptions.dockerOptions` is now the structural `DockerConnectionOptions` (same fields as dockerode's `DockerOptions`, passed through unchanged) and `McpClientLike` is the structural subset of the MCP SDK's `Client` it already was (`listTools` / `callTool`). Before, `dist/index.d.ts` imported `dockerode` and the shared schema chunk imported `@modelcontextprotocol/sdk`, so a consumer compiling with `skipLibCheck: false` without those optional peers installed got TS2307 inside the SDK's own declarations. A dockerode `DockerOptions` or MCP `Client` value still satisfies both types.
-
-## [1.0.0-alpha.18] - 2026-10-08
-
-See the 1.0.0-alpha.19 section, which covers everything from 1.0.0-alpha.15 through 1.0.0-alpha.19.
-
-## [1.0.0-alpha.17] - 2026-10-07
-
-See the 1.0.0-alpha.19 section, which covers everything from 1.0.0-alpha.15 through 1.0.0-alpha.19.
-
-## [1.0.0-alpha.15] - 2026-10-06
-
-See the 1.0.0-alpha.19 section, which covers everything from 1.0.0-alpha.15 through 1.0.0-alpha.19.
-
-## [1.0.0-alpha.9] - 2026-10-04
-
-### Security
-- `http_request` is no longer open to DNS rebinding. It resolved a host name once to check it against the private-address list and then let `fetch` resolve it again to connect, so a name that answered a public address to the check and `127.0.0.1` (or a cloud metadata or intranet address) to the connection reached the private address; the docs and a comment in the Worker runtime described the check as rebinding-safe. Now the one resolution is the check: the in-process path connects through an undici `Agent` whose `connect.lookup` checks every address and hands the socket the address it checked (each redirect hop included), and the sandboxed path (`sandboxExecute`, which agents use) resolves and checks the host in the agent's process and has the sandboxed process connect to that address (node:http/https with a fixed lookup; the host name still goes in `Host` and TLS SNI). The private-address list is now the shared one (below), which adds `0.0.0.0/8`, `100.64.0.0/10`, `192.0.0.0/24`, `198.18.0.0/15`, multicast and reserved `224.0.0.0/3`, `::`, `ff00::/8`, NAT64 `64:ff9b::/96` and 6to4 `2002::/16` to what `http_request` refused. Behavior changes: a host name that cannot be resolved now fails with the resolver's error instead of being passed to `fetch`; `undici` is loaded on the first `http_request` request (not only with `validateSSL: false`). New option `createHttpTool({ allowPrivate })` for hosts that may resolve to private addresses. Cloudflare Workers have no DNS hook, so neither tool exists in the Worker build; docs/deployment.md now says what a Worker can and cannot check.
-- A run's principal is fixed for the whole run: an approval resolved by another caller, a restart, `agent.resume()` or a session's pending turn continue as the caller that started the run, and the decider is recorded as the approver (`ctx.approval.by`), never swapped in as the run's principal, so a later caller cannot use an earlier caller's grant by approving their pending call. The principal comes only from route auth or a channel's verified sender; the approvals route and channels never read it from a body field. It is frozen before a tool, a policy or a hook sees it. Remote sub-agents are not told who the caller is.
-
-### Changed
-- Behaviour and types: a tool whose `execute` returns an async iterator that is also async iterable (what an `async function*` returns) is now iterated: its last yielded value is the result, instead of the iterator object itself (which used to reach the model as `{}`). `AgentEvent` gains `tool.partial` (`ToolPartialEvent`), `isToolEvent()` narrows to it too, `UIToolCall` gains `partial?`, the `tool-output-available` UI chunk type gains `preliminary?: true`, and `DefinedTool` gains a third, defaulted type parameter (what `execute` resolves to). Migration: a `switch` over `event.type` meant to be exhaustive needs a `'tool.partial'` case; code using the result of `isToolEvent()` as start/done/error only should check `event.type`; a tool that means to return an async generator as a value should wrap it (`{ items: generator }`) - a value that is only async iterable, such as a `ReadableStream`, is still returned as it is.
-- Types only: `AgentEvent` gains the `handoff` event (`HandoffEvent`) and `ExecutionResult` the optional `agentName` (set on every result the executor returns: the agent of the final reply). Migration: a `switch` over `event.type` meant to be exhaustive needs a `handoff` case; a test comparing a whole `ExecutionResult` with `toEqual()` now sees `agentName`. Nothing changes at runtime for an agent without `handoffs`.
-- BREAKING (types only): `McpServerStatus` gains `'needs-auth'`, and `AgentOAuth` (the type of `agent.oauth`) gains `mcpSignInUrl(server)`. Migration: an exhaustive `switch` over `connectMcp(...).status()` values needs a `'needs-auth'` case (only servers with `oauth` ever report it); an object written by hand to satisfy `AgentOAuth` (a test double, say) needs an `mcpSignInUrl` method. Runtime behaviour without `oauth` is unchanged.
-- BREAKING (types only): `ToolExecutionContext` gains the methods `getToken(provider)` and `requireAuth(provider)`, and `ApprovalKind` gains `'sign-in'`. Migration: code that builds a tool's execute context by hand (for example to call `tool.execute(args, { toolCallId, messages })` in a unit test) must add the two methods or cast (`as ToolExecutionContext`); a `switch` over `PendingApproval.kind` / `approval.requested`'s `kind` that is meant to be exhaustive needs a `'sign-in'` case. Contexts the SDK builds have them already; nothing changes at runtime.
-- BREAKING: `send()` and `AgentExecutor.execute()` with a listener (`createAgent({ onEvent })`, `onAgentEvent`, or the deprecated `onEvent` option) now stream model calls: a step's text arrives as several `text.delta` events, as in `stream()`, instead of one `text.delta` per step after the step finished. What a listener receives otherwise does not change: the same event types in the same order, exactly one `text.done` per step with the step's whole text, the same `step.done` usage and `run.done`, the same `ExecutionResult` (text, tool calls, usage, steps). A provider without `stream()`, or whose `supportsStreaming(model)` is `false`, still gives one `text.delta` per step. Output guardrails on `send()` still check only the final reply (a `stream()` you iterate checks every step's text, as before). `send()` without a listener still calls `provider.generate()`. Hooks' `ctx.emit` is set whenever the run has listeners (it was already; the docs said "only when streamed"). Migration: concatenate `text.delta`, or listen to `text.done` for whole steps; `execute({ streamModelCalls: false })` (new option, default `true`) restores whole steps.
-- `MockLLMProvider` / `createMockProvider()`: `stream()` now streams the same step `generate()` returns: the same tool calls (it streamed none, so a streamed mock run never called a tool), finish reason and usage, and text chunks that add up to exactly the generated text (the old chunks ended with an extra space: `'This is a mock response. '`). Runs on the mock provider with a listener (Agent Forge's, for one) therefore give the same results as before, and `stream()` runs on it now call tools as `send()` does.
-- Agent Forge: runs now stream their model calls, so the run WebSocket (`WS /agents/:id/stream`) carries several `text.delta` events per step; the chat, logs and trace views are unchanged (they use `text.done` and the reconciled messages). Stop is checked between streamed chunks and after the last one, as it was after each `generate()` call.
-- CI peer matrix: the `typecheck-ai7` and `typecheck-zod4` jobs are replaced by one `peers` job with five entries, each installed for real on top of the default install and run through `tsc`, `test:types`, both builds and `npx vitest run`: `ai4-zod4`, `ai6-zod3`, `ai6-zod4`, `ai7-zod3`, `ai7-zod4`. The two zod 4 entries on `ai` 6/7 also install `ollama-ai-provider-v2` (3.x / 4.x), and the new `src/providers/ollamaV2.contract.test.ts` runs `OllamaProvider` against the real package and a local fake Ollama server (`generate()`, `stream()`, a tool-call turn through `createAgent().send()` and `.stream()`). The `ai-v6` dev alias replaces the hand-made `ai` 6 stand-in in `aiMajorPeers.test.ts`.
-- `lousho init --provider ollama` now scaffolds `ai@^7.0.0` with `ollama-ai-provider-v2@^4.0.0` and `zod@^4.0.0` (it was `ai@^4.3.19` with `ollama-ai-provider@^1.2.0` and zod 3). Existing projects are not touched; to stay on the old pairing keep `ai@^4.3.19` and `ollama-ai-provider@^1.2.0`.
-- A run paused inside a sub-agent compares the sub-agent with its current definition on resume, under the lead's `onAgentDrift`. Behaviour change: with `onAgentDrift: 'error'`, `agent.approvals.resolve()` (and `resumeAfterApproval()`) now also rejects with `LOUSHO_AGENT_DRIFT` when a paused sub-agent's instructions, model or tools changed; before, only tool and provider default-model changes of a sub-agent were seen, and always as a warning. This holds at any depth (a sub-agent of a sub-agent uses the lead's mode). With `'warn'` (still the default) the `agent.drift` event carries `subagent`. A rejected resume puts the lead's approval record and its `'awaiting-approval'` checkpoint back, so fixing the sub-agent and resolving again finishes the run; before, a sub-agent's missing-tool error became an error result of the `task` call and the run continued. Migration: none for `'warn'` / `'ignore'`; with `'error'`, resolve approvals paused before a sub-agent changed with the old definition, or use `'warn'`. See docs/durable-execution.md#resuming-with-a-changed-agent.
-- `lousho add` enforces the permission manifest at install. Behaviour change: an item whose code does not match its manifest is now refused with the new code `LOUSHO_REGISTRY_MANIFEST_MISMATCH`, and nothing is written. Before writing, every JavaScript / TypeScript file of the item is scanned (comments stripped) for `child_process` / `execa` / `shelljs` / `createShellTool` / `SubprocessSandbox` (needs `exec: true`), `fs` imports and `createFsTools` (needs `filesystem: "read"`), file-writing calls (needs `"write"`), `fetch(` and network modules (needs a non-empty `network`), `http(s)://` hosts in strings (each must match a `network` entry) and `process.env.NAME` reads (each must be in `env`); `eval(`, `new Function(`, a computed `process.env[...]` and a non-literal `import()` / `require()` are always refused. Each finding is listed as `<file>:<line>: <what> (<fix>)`. `network` entries must now be host patterns and `env` entries variable names (`LOUSHO_REGISTRY_INVALID` otherwise). With `--yes`, an item asking for `exec: true`, `filesystem: "write"`, a `network` or an `env` is refused unless each is named in the new `--allow exec,fs-write,network,env` flag; the interactive prompt lists them, and the printed manifest marks them `[elevated:...]`. After writing, `lousho add` records the item (type, registry, time, permissions, each file's sha256) in `<agent-dir>/lousho-registry.json`. Migration: registry authors declare what their code uses; scripts that run `lousho add --yes` add `--allow` with the permissions they accept. It is a static check, not a sandbox; see docs/registry.md#permission-manifest. The example item in docs/registry.md now uses `input` (not `inputSchema`).
-- Behaviour change: continuing an unfinished checkpointed run (`send(message, { sessionId, principal })`, `AgentExecutor.execute({ sessionId, checkpointStore, principal })`) with a principal other than the one it was saved with now throws `LOUSHO_CONFIG_INVALID` instead of running the new input; without a principal (`agent.resume()`, a session's pending turn) the run continues as the saved caller. Migration: resume such a run without `principal`, or start a new session. `onPermissionDecision` is called with a second argument, `{ principal }` (callbacks that take one argument are unaffected). Checkpoints, approval snapshots and pending approvals now store the run's principal (claims included): treat those stores as personal data. Checkpoints and snapshots written before this release resume with no principal; no migration.
-
-### Added
-- `lousho dev` and `lousho chat` take `--traces` (or `--traces=<dir>`) to write local traces with `fileTraceExporter()`: `.lousho/traces` by default, the directory `lousho traces` reads, for spec files, agent directories and modules (`specToAgent()` now also accepts an `exporter` option). It is opt-in because trace files hold prompt and tool content even with `captureContent: false` (only `redactContent: true` removes it); the command prints where it writes. `lousho init` projects already ignore `.lousho/`.
-- Code mode: `createAgent({ codeMode: true | CodeModeOptions })` adds a `run_code` tool. The model writes the body of an async JavaScript function that calls the agent's tools as `await tools.<name>(args)`, loops and combines their results, and returns one JSON value; `run_code` returns `{ result, logs, toolCalls }` and only that enters the transcript. Scripts run in a QuickJS WebAssembly isolate from the new optional peer `quickjs-emscripten` (`^0.32.0`, listed by `lousho doctor`; without it the first run of a `codeMode` agent fails with `MissingPeerDependencyError`): a fresh runtime per script, no `require`, `import`, `process`, `fetch`, timers or host objects, values passed as JSON copies, and the limits `timeoutMs` (30,000, whole script including awaited tool calls), `memoryLimitBytes` (64 MiB), `maxToolCalls` (50) and `maxOutputChars` (20,000, return value plus logs). `tools` picks the callable tools (default: all but `run_code`, `ask_question`, sub-agent tools, `tool_search`, `load_skill` and deferred tools); `exclusive: true` takes them off the model's tool list. Every inner call (id `<run_code id>:<n>`) goes through the same gate as a direct call: validation, hooks, permission rules and modes (plan mode refuses non-read-only inner calls; `run_code` itself is read-only), tool guardrails (a block stops the run), `needsApproval`, sandbox routing and the principal. A call that would pause the run (approval, sign-in, a sub-agent's approval) throws inside the script instead and the run does not pause; `run_code` itself can be paused for approval by a rule and runs after the decision. A failed script's error lists its first five tool calls with their (clipped) results. New export: type `CodeModeOptions`. Types: `parentToolCallId?` on the `tool.start`, `tool.partial`, `tool.done` and `tool.error` events (set on inner calls; their `tool.done` / `tool.error` comes before `run_code`'s); inner calls get `execute_tool` spans under the `run_code` span with the attribute `lousho.tool.parent_call_id`. No migration needed: nothing changes without `codeMode`. See docs/code-mode.md.
-- Streaming partial tool results: a tool's `execute` may be an `async function*`. Every `yield` is a complete snapshot of its output, streamed as the new `tool.partial` event (`{ toolCallId, toolName, output, index }`, `index` from 0) between the call's `tool.start` and `tool.done`; the last yield is the result the model gets (and `tool.done`'s `result`), a `return` value is ignored and a generator that yields nothing has the result `undefined`. Snapshots are not sent to the model, not added to the transcript, not checkpointed and not recorded in trace spans; hooks see only the result; tokens from `ctx.getToken()` are redacted in snapshots like in the result. The main loop, a streamed resume after an approval (`agent.approvals.streamResolve()`) and a flow's tool-call node iterate the generator; aborting the run stops reading it and calls its `return()`; `toolConcurrency` counts the whole generator run. A call that pauses for a sign-in mid-stream runs again from the start (index from 0); partial output is lost on a crash. `defineTool` types it: `ToolOutput<typeof tool>` is the yielded type (new helper type `ToolResultOf<R>`). The UI reducer (`useLoushoAgent()` and the Vue / Svelte bindings) keeps the latest snapshot as `toolCalls[i].partial`, and `toUIMessageStream()` sends snapshots as the AI SDK's preliminary tool output (`tool-output-available` with `preliminary: true`). See docs/tools.md#streaming-partial-results.
-- Tool search: tools marked `deferLoading` (`defineTool({ deferLoading: true })`, or every tool of an MCP server with `mcpServers.<name>.deferLoading: true`, also in spec files and agent directories) are withheld from the model, which finds them with a built-in `tool_search` tool (`{ query }` -> `{ loaded: [{ name, description }], more }`); the tools it finds are sent from the next step on, and `tool_search` stops being offered once everything is loaded. New option `toolSearch` on `createAgent()` and `AgentExecutor.execute()`: `{ thresholdPercent? (default 0.1 of the context window; 0 always defers), maxResults? (5), contextWindow?, search? }`, or `false` to send every tool upfront. Below the threshold nothing is deferred and no `tool_search` exists. Which tools are loaded is read from the transcript at each model call, so loading survives crash resume, approvals, forks and session turns; compaction that prunes a `tool_search` result unloads its tools; a handoff target or a sub-agent never inherits the lead's loaded tools. Skills, memory, `task`, `ask_question` and handoff tools are never deferred. New exports: `ToolSearchOptions`, `ToolSearchResult`, `rankToolsByKeywords()`. Types: `ToolDescriptor.deferLoading`, `DefineToolOptions.deferLoading`, `McpStdioServerSpec` / `McpHttpServerSpec.deferLoading`, `LoadMcpToolsOptions.deferLoading`, `SubagentSpec.toolSearch`, `ToolMetadata.mcp.server`. Behaviour change: tools loaded by `loadMcpTools()` / `connectMcp()` now carry their server name in `metadata.mcp.server`; a test comparing an MCP tool's whole `metadata` with `toEqual()` needs that key. A user tool named `tool_search` is refused (`LOUSHO_CONFIG_INVALID`) only when deferral is active. See docs/tool-search.md.
-- Handoffs: `createAgent({ handoffs: [billing, handoff(refunds, options)] })` lets an agent hand the whole conversation to another `createAgent()` agent (with a `name` and a `description`), offered to the model as one `transfer_to_<name>` tool each. The handoff call is not run as a tool: once the other calls of its step are done, the run goes on in the same `send()` / `stream()` as the target, with its instructions (replacing the system prompt), model, tools, skills, sub-agents, reasoning and own handoffs, the lead's guardrails and permission rules before its own, on the transcript the handoff's `inputFilter` returns (`handoffFilters.removeToolCalls`, `handoffFilters.lastUserMessage`, or your own). Hooks, `limits` and spend, `maxSteps` (counted across agents), the signal, the approval, checkpoint and token stores, listeners, `output`, the permission mode and the principal stay the run's. `handoff()` options: `toolName`, `description`, `input` (validated; bad arguments get a tool error and no handoff), `inputFilter`, `onHandoff`, `isEnabled` (a `PerRun<boolean>`). Only the first handoff call of a turn is honored; `maxHandoffs` (default 5) caps one run. The transcript marks each handoff with `metadata.handoff = { from, to }`; a session's next turn, `agent.resume()`, `session.resume()` and `agent.approvals.resolve()` continue as the agent it last handed off to (`agent.send()` without a session starts at the lead), and the resume drift check compares with that agent. Approvals remembered with `once()` are dropped at a handoff. A `transfer_to_*` call passes the run's gate like a tool call: `permissions` rules apply to it (`deny` gives the model a `kind: 'denied'` tool error and no handoff happens; `ask` pauses the run for approval and the decided call then hands off or reports the rejection), pre/post tool hooks may deny it or rewrite its arguments, and its decision is audited to `onPermissionDecision` / `permission.decision`. Each handoff appends a routing system note (`metadata.handoff`) carrying the validated call arguments to the transcript the target reads; `handoffFilters.removeToolCalls` keeps it and a custom `inputFilter` may drop or replace it. `createAgent()` warns once when a reachable handoff target was created with run-level options (`approve`, `approvalStore`, `permissionMode`, `approvalTtlMs`, `store`) - a run keeps the entry agent's. New `handoff` event (`from`, `to`, `toolCallId`) and `ExecutionResult.agentName`; `ExecuteOptions.handoffs` / `maxHandoffs` for the executor API. Remote agents cannot be handoff targets. See docs/handoffs.md.
-- OAuth for HTTP MCP servers, per the MCP authorization spec: an `mcpServers` HTTP entry takes `oauth: { redirectUri, clientId?, clientSecret?, scopes?, clientName? }` (new type `McpOAuthOptions`; refused on stdio entries by the spec schema). The MCP SDK's client does discovery (RFC 9728 protected resource metadata, RFC 8414 authorization server metadata), dynamic client registration (RFC 7591) when no `clientId` is given, PKCE and resource indicators (RFC 8707), and refreshes an expired token; tokens are kept in the agent's encrypted token store as provider `mcp-<server>`, owned by the app. An operator signs the agent in once with the new `agent.oauth.mcpSignInUrl(server)`; N9b's `agent.oauth.complete()` and `GET /oauth/callback` finish it. Without a usable token the server's status is the new `'needs-auth'` and connecting fails with the new error code `LOUSHO_MCP_AUTH_REQUIRED` (a tool call refused mid-run is a tool error with that code; nothing pauses). `connectMcp(servers, { tokens })` takes the token store. Security: `oauth` needs an https `url` (http only for localhost, 127.0.0.1 and [::1]); an `Authorization` header together with `oauth` is refused; with `oauth`, `headers` go only to the MCP server's origin, never to the authorization server; a stored grant is only used for the `url` it was obtained for (a changed `url` needs a new sign-in); no token, code, verifier or client secret appears in errors, logs, `status()`, events or results. Out of scope for now: per-user MCP grants, a `lousho mcp login` command, OAuth over stdio. See docs/oauth.md, "MCP servers with OAuth".
-- Parallel input guardrails: `IoGuardrail.runInParallel` (default `false`) makes an `input` guardrail run while the first model call is already in flight, so a slow, model-backed check no longer delays the answer by its whole latency; `promptInjectionGuardrail({ runInParallel })` and `moderationGuardrail({ runInParallel })` take it as an option. The blocking input guardrails run first as before (rewrites included), then the parallel ones start together on that input. Until all have passed, the call's `text.delta`, `reasoning.*` and provider-run tool events are held in order (on the iterator and `onAgentEvent` alike), its tool calls do not run, and `onLLMResponse`, post-generate hooks, output guardrails, `text.done` and the checkpoint after the response wait. A trip aborts the call (its signal only, not the run's), drops the held events and ends the run with `finishReason: 'guardrail'`, `result.guardrail` and `guardrail.tripped` (or `GuardrailError` under `onTripped: 'throw'`), with nothing of the call in the transcript or a checkpoint; the call's usage counts in `result.usage` only when the provider reported it. A parallel check cannot rewrite (`action: 'rewrite'` blocks, the reason prefixed `runInParallel guardrails cannot rewrite: `), and a check that throws fails the run. Ignored on `output` and `tools` guardrails. No change for guardrails without the flag. See docs/guardrails.md#input-and-output-guardrails.
-- OAuth sign-in for tools: `defineOAuthProvider({ name, displayName?, credentialOwner?, authorizationUrl, tokenUrl, clientId, clientSecret?, clientAuth?, scopes?, redirectUri, authorizationParams?, fetch? })`, and in a tool `ctx.getToken(provider)` and `ctx.requireAuth(provider)`. Without a usable token the run pauses durably like an approval (`finishReason: 'awaiting-approval'`, `kind: 'sign-in'`, `signIn: { provider, displayName?, url }` on the pending approval and the `approval.requested` event); the authorization URL uses PKCE S256 and a single-use 256-bit `state` that expires after 10 minutes, and the verifier is kept only in the encrypted pending record. The new route `GET /oauth/callback` (`lousho dev`, the node server, the Worker) and `GET <basePath>/oauth/callback` (`createRouteHandler`) is not behind route auth (a browser redirect carries no API token): it calls the new `agent.oauth.complete({ state, code?, error? })`, which stores the token for the paused run's principal and answers a small HTML page (400 for an unknown, used or expired state). Approving the pause (`agent.approvals.resolve({ id, approved: true })`, or the approvals route) runs the tool call again; before the callback it throws `LOUSHO_SIGNIN_PENDING` (HTTP 409) and the run stays paused. Tokens within 60 s of expiry are refreshed; `requireAuth()` deletes a refused token and pauses. A user credential needs a principal (`LOUSHO_OAUTH_PRINCIPAL_REQUIRED`); an app credential (`credentialOwner: 'app'`) is never asked of a chat user (`LOUSHO_OAUTH_APP_SIGNIN_REQUIRED`) and is connected by the operator with `agent.oauth.signInUrl(provider)`. The `approve` callback is never asked about a sign-in. Slack sends the link with `chat.postEphemeral` and Discord as an ephemeral follow-up, both without buttons; GitHub never posts it in a public thread; behind `createDeployedServer()` and `lousho dev` the callback continues the paused channel turn. The UI state (`pendingApproval.signIn`), the `data-lousho-approval` part, `lousho dev`'s page, `lousho chat` and `lousho acp` show the link. A tool result that contains a token handed out during that call is redacted to `[REDACTED]` with a warning. New error codes `LOUSHO_OAUTH_PRINCIPAL_REQUIRED`, `LOUSHO_OAUTH_APP_SIGNIN_REQUIRED`, `LOUSHO_OAUTH_STORE_MISSING`, `LOUSHO_OAUTH_STATE_INVALID`, `LOUSHO_SIGNIN_PENDING`, `LOUSHO_OAUTH_TOKEN_EXCHANGE_FAILED`. See [OAuth](docs/oauth.md#tools-that-need-sign-in).
-- Hosted tools on Anthropic and OpenRouter: `webSearch()` and `codeInterpreter()` now also run on the Anthropic provider (`ai` 6 with `@ai-sdk/anthropic` 3, `ai` 7 with `@ai-sdk/anthropic` 4): `webSearch()` is the newest `tools.webSearch_*()` the installed package exports (options `maxUses`, `allowedDomains`, `blockedDomains`, `userLocation`), `codeInterpreter()` the newest `tools.codeExecution_*()`; events and `usage.hostedToolCalls` keep the neutral name `code_interpreter`. `fileSearch()` on Anthropic, and `codeInterpreter()` / `fileSearch()` on OpenRouter, are `LOUSHO_HOSTED_TOOL_UNSUPPORTED`. `webSearch()` works with every `openrouter/...` model on any `ai` major: the provider adds OpenRouter's `openrouter:web_search` server tool to the request body (after the function tools, composing with the `reasoning` field; `maxUses`, `allowedDomains`, `blockedDomains` and `searchContextSize` map to its parameters) and reports one hosted call per step that searched, read from the response: the cited urls from `url_citation` annotations as `sources`, and `result: { requests }` when OpenRouter reports `usage.server_tool_use.web_search_requests`. OpenRouter bills each search on top of tokens (not in `costUsd`). `supportsHostedTool()` on both providers reflects this. The per-provider table in docs/hosted-tools.md is complete, and a replayable cassette from a live OpenRouter search is in the test suite (`npm run test:live` re-records it with `OPENROUTER_API_KEY`).
-- Hosted provider tools: `webSearch()`, `codeInterpreter()`, `fileSearch()` and `hostedTool(name, aiSdkTool)` go in `createAgent({ tools })` next to local tools (array or record form; in the record form the key must be the tool's name), and the provider runs them inside the model request. OpenAI maps them to `openai.tools.webSearch()` / `.codeInterpreter()` / `.fileSearch()` on `ai` 6 with `@ai-sdk/openai` 3 and `ai` 7 with `@ai-sdk/openai` 4 (options it does not take, such as `maxUses`, are dropped with one warning); `hostedTool()` passes any AI SDK provider tool through on `ai` 6 or 7, including on `fromAiSdk()` models. Provider-executed calls are never handed to the executor as local tool calls (on `ai` 6/7 they used to come back as calls of an unknown tool): they are reported as `tool.start` / `tool.done` / `tool.error` with the new optional field `executedBy: 'provider'` (as they stream in, or after a non-streamed call in call order; results capped at 20,000 characters of JSON), kept on the step's assistant message as `metadata.hostedToolCalls` (with url sources; not sent back to the model), counted in `usage.hostedToolCalls` and `run.done` usage per tool name (fees not in `costUsd`), and named on the `chat` span as `lousho.hosted_tool_calls`. A step whose only calls the provider ran ends the run even when the provider reports `tool-calls`. No permission rule, guardrail, approval or hook runs for them; instead, in permission mode `'plan'` only the read-only `webSearch()` and `fileSearch()` are sent to the provider (`codeInterpreter()` and `hostedTool()` are left out of the request, read before every model call), and every other mode sends them all. New: `ExecuteOptions.hostedTools`, `GenerateOptions.hostedTools`, `GenerateResult.hostedToolCalls`, `HostedToolCall`, stream chunks `hosted-tool-call` / `hosted-tool-result`, optional `LLMProvider.supportsHostedTool(type)`, `mockModel` turns with `hostedToolCalls`, cassettes that keep hosted calls, error code `LOUSHO_HOSTED_TOOL_UNSUPPORTED` (ai 4, Ollama, a provider without `supportsHostedTool()`, or an `@ai-sdk/openai` without the tool). Sub-agents do not inherit the lead's hosted tools; the agent fingerprint includes them. Anthropic and OpenRouter mappings follow in N1b (below). See docs/hosted-tools.md.
-- `session.history()` and `session.fork({ fromStep, id?, patch? })` on `agent.session()` sessions. `history()` lists the steps of the committed transcript (one per model response: `step` numbered from 1 across the session, `turn`, `messageIndex`, `text`, and `toolCalls` with `args` and `result`). `fork()` saves the transcript up to and including a step (`0` keeps nothing), optionally with one tool result replaced (`patch.toolResult`), under a new id in the same store (default `<id>-fork-<n>`) and returns a session of the same agent and options (with the permission mode the session has at that moment); the original is not changed. The spend recorded for `limits` up to that point carries over. A turn waiting on an approval or a question, or an interrupted checkpointed turn, stays with the source session, so it is resolved once; workspace files are not rewound. Works on every shipped store (memory, `fileStore()`, `SqliteStore`, `KVStore`), with one contract suite run against each. New types `SessionHistoryStep`, `SessionForkOptions` and `SessionSpawner`; new error codes `LOUSHO_SESSION_STEP_NOT_FOUND`, `LOUSHO_SESSION_EXISTS` and `LOUSHO_SESSION_FORK_UNSUPPORTED`; `AgentSession`'s constructor takes an optional fourth argument, the function that creates its forks. See [Forking a session](docs/sessions.md#forking-a-session).
-- Permission modes: `createAgent({ permissionMode })`, `send()` / `stream()` `{ permissionMode }`, `agent.session({ permissionMode })` and `session.setPermissionMode()` put an agent in `'plan'` (only read-only tools run; everything else is refused with `kind: 'denied'`, also when an `allow` rule matched, and a run that starts in plan mode gets one system-prompt paragraph saying so), `'acceptEdits'` (file edits that would ask run without asking) or `'dontAsk'` (a call that would ask is refused; nothing pauses). The modes are presets applied after hooks, permission rules, tool guardrails and `needsApproval`, so no mode turns a deny into a run. A function mode, and a session's mode, are read at every tool call, so a switch applies from the next call, also mid-turn and in a paused turn continued by `agent.approvals.resolve()`. Sub-agents run under the lead's mode unless it is `'default'`; a remote sub-agent is refused in plan mode. Audit: under a mode other than `'default'` every call is audited, `PermissionDecisionEntry.mode` says when the mode changed the outcome, and the new `onPermissionModeChange` records each switch. New: `PermissionMode` and `PermissionModeChange` types, `defineTool({ editsFiles })` (`metadata.editsFiles`, set on `write_file` and `edit_file`), `readOnlyHint: true` on `load_skill`, `recall_<name>`, `agent_status` and `agent_await`. The mode is not saved in checkpoints. Example: `examples/plan-mode`. See [Permission modes](docs/permission-modes.md).
-- Semantic recall: a memory slot can recall by meaning. New `EmbeddingProvider` (`{ id, embed(texts) }`) and `aiSdkEmbedder(model, { id?, maxBatch? })`, which wraps any AI SDK embedding model through `embedMany` from the installed `ai` (4, 6 or 7; `ai` is loaded on first use, no new dependency), and two providers that rank by cosine similarity: `inMemoryVectorMemory({ embedder, maxItems?, minScore? })` from the root and `sqliteVectorMemory(store, options)` from `@lousho/build-ai-agent/sqlite` (a new `memory_vectors` table, added to an existing database file on open; `memory_items` and `sqliteMemory()` are unchanged). With a query, `list()` returns the scope key's items by score (floor `minScore`, default 0.2; score in `metadata.score`); without one it lists the newest first. Items embedded by another embedder id are skipped when ranking until `provider.reindex(scopeKey?)` re-embeds them. A `MemoryProvider` may set `ranking: 'relevance'`, which makes the `recall_<name>` tool say "by meaning, most relevant first". `hashEmbedder({ dimensions? })` from `@lousho/build-ai-agent/testing` is a deterministic offline embedder for tests. `describeMemoryProviderContract` takes `{ query: 'filter' | 'rank' }`. docs/memory.md has a new `## Semantic recall` section at the end.
-- `teamsChannel({ appId, appPassword, tenantId?, name?, fetch?, approvers?, onError? })`: an agent behind an Azure Bot in Microsoft Teams, mounted like the other channels (`POST <basePath>/teams`). The inbound Bot Framework token is verified with the auth module (`oidc()`: RS256, the key set of the fixed Bot Framework OpenID metadata, issuer `https://api.botframework.com`, audience `appId`, 5-minute tolerance) before the body is parsed, and its `serviceurl` claim must equal the activity's `serviceUrl`; replies go only to that service URL (https). Personal chats always reach the agent, group chats and channels only on an `@mention` (stripped from the text); one session per conversation; Markdown replies split at 25,000 characters; tool approvals are Adaptive Cards with Approve and Deny buttons (`approvers` as on the other channels; the card updates to "Approved by..." and names its conversation, so a copied or replayed reference decides nothing); `ask_question` is answered by the next message, also after a restart with durable stores. No `node:*` import. Telegram and GitHub now set the sender as the run's `principal` too (`authenticator: 'telegram'` with the user id, `'github'` with the login), as Slack and Discord do. See docs/channels.md#microsoft-teams.
-- Cloudflare Worker target builds agent directories (config, instructions, TypeScript tools, skills): `npx lousho build./my-agent --target=cloudflare-worker`. The build reads the directory on Node and generates `agent.module.ts` (static imports of `tools/*` and of an `agent.ts` config; `instructions.md`, a JSON/YAML config and the skills embedded as JSON), and the Worker builds the agent with the rules of `resolveAgentDir()` (the config check and the tool-export rules now live in Node-free modules both use). The config's `model` must name a Worker provider, or `agent.ts` sets a `provider` instance. `subagents/`, `schedules/`, `channels/`, `memory/`, `projectInstructions` and an unsupported provider are rejected with `LOUSHO_DEPLOY_FAILED`, naming what to remove. In a Worker build, an agent file's `@lousho/build-ai-agent` import resolves to a Worker-safe subset (`defineTool`, `defineSkill`, the Worker providers, `fromAiSdk`, errors,...); another name fails the build with the list. The leak check now names the file that imported a Node builtin (`"node:fs" imported by my-agent/tools/files.ts`) instead of failing with esbuild's "Could not resolve". Tools run in the Worker's isolate with its rights: see docs/cloudflare-workers.md#build-and-deploy.
-- Workspace rewind: `createFsTools(fs, { checkpoints })` with a new `WorkspaceCheckpoints` backs up every file `write_file` and `edit_file` change (content and, where the provider has the new optional `FsProvider.getMode` / `chmod`, permission bits), grouped by session and turn. `checkpoints.list({ sessionId })` shows the changed paths per turn; `checkpoints.rewind(toTurn, { sessionId, dryRun, force })` restores every file changed in that turn or later, deletes files the agent created, and skips files changed since by something else (`'changed-since'`), files over `maxFileBytes` (`'too-large'`) and paths that are no longer files. Every path is checked before anything is written, and restores go through the provider, so `NodeWorkspace` keeps them inside its root. Retention: the newest `maxTurns` turns per session (default 20), the old content only for a turn's first write of a path, rewound turns dropped, `clear({ sessionId })`. Stores: `MemoryWorkspaceCheckpointStore` (default) and `FileWorkspaceCheckpointStore(dir)` (one JSON file per session, atomic writes). `NodeWorkspace` gains `getMode()` and `chmod()`. Without `checkpoints` the tools behave as before. See [Workspace tools](docs/workspace-tools.md#the-tools).
-- Route auth and principals: a new subpath, `@lousho/build-ai-agent/auth`, with `jwt()`, `oidc()`, `basic()`, `apiToken()`, `anonymous()` and `routeAuth()`. A route takes an ordered list of entries: the first one that returns a `Principal` accepts the request, `null` skips to the next, `AuthError(401 | 403)` stops; when every entry skips the answer is a generic `401` with one `WWW-Authenticate` header per challenge (`Bearer`, `Basic realm="..."`), and the body never says which check failed. JWTs are verified with Web Crypto only (no new dependency, no `node:` import, so the helpers run on Workers and edge routes): `alg: none`, algorithms outside the configured list, a `crit` header and algorithm confusion (an HS token checked against a public key) are refused; `exp` is required, `nbf` / `iat` honored, `iss` / `aud` checked, with a clock tolerance of 60 s (at most 300); JWKS key sets are cached for 10 minutes and refetched at most once per 30 s, and a key-set URL is never taken from a token. `oidc()` uses the configured issuer's discovery document and requires it to name the same issuer. `basic()` and `apiToken()` compare in constant time. `createRouteHandler({ auth })` and `createDeployedServer(agent, { auth })` take the list (a token string and a boolean function work as before); the node server appends `apiToken(LOUSHO_API_TOKEN)` when that variable is set; an agent directory's `auth.ts` is bundled by `lousho build --target=node-server` / `docker` and guards the built server (`resolveAgentDir()` returns it as `auth`, the manifest has `auth: true`). The accepted principal reaches the run: `send()` / `stream()` / session turns take `principal`, and `RunConfigContext` (the `model` / `instructions` / `tools` functions) and `MemoryScopeContext` (memory scopes) carry it; Slack and Discord channels set the sender as the principal. `Principal` is also exported from the root. Bad helper options throw the new error code `LOUSHO_AUTH_CONFIG_INVALID` when the helper is created. `createRouteHandler()` without `auth` logs one warning when `NODE_ENV` is `production`. Route auth does not check session ownership, the principal does not reach tools or approval policies yet, and the Cloudflare Worker target keeps the `LOUSHO_API_TOKEN` token only. See [Route auth and principals](docs/auth.md).
-- OAuth token storage: `AgentStore` gains a fourth optional part, `tokens` (`OAuthTokenStore`: `get` / `set` / `delete` / `list` per provider and credential owner, single-use pending sign-ins with `putPending` / `takePending`, and `getClient` / `setClient` for dynamically registered clients). Owners are `{ owner: 'app' }` or `{ owner: 'user', principalId, issuer? }`; `tokenStoreKey(provider, owner)` is the stable, percent-encoded record key (`<provider>|app`, `<provider>|user|<issuer>|<principalId>`). `memoryStore()` keeps tokens in process memory; `fileStore(dir)`, `SqliteStore` and `KVStore` encrypt every record with AES-256-GCM (Web Crypto, a fresh 12-byte IV per write, the record key as additional authenticated data) under a 32-byte key the application supplies as `tokenKey` or `LOUSHO_TOKEN_KEY`; there is no default key. Several keys (newest first, or comma-separated in the variable) rotate: writes use the first, reads try each. New error codes `LOUSHO_TOKEN_KEY_MISSING` (first write, or a read of an existing record, without a key) and `LOUSHO_TOKEN_DECRYPT_FAILED` (wrong key or a changed record; names the provider, never the token). `list()` returns metadata only. `generateTokenKey()` makes a key. SQLite: schema migration 4 adds the `oauth_tokens` and `oauth_pending` tables, and `prune()` also deletes expired pending sign-ins (its result gains `oauthPending`). KV: keys under `<prefix>oauth/`, pending sign-ins written with an `expirationTtl`; `KVBinding` gains an optional `list()` (used only by `tokens.list()`), and `KVListOptions` / `KVListResult` are exported from `/kv`. The generated Cloudflare Worker passes its `LOUSHO_TOKEN_KEY` secret to `KVStore`. Nothing signs in yet; the sign-in flow follows. New page [OAuth](docs/oauth.md); new `## OAuth` section at the end of docs/errors.md.
-- `githubChannel({ webhookSecret, botName, token?, app?, botLogin?, name?, apiUrl?, fetch?, triggers?, approvers?, onError? })`: an agent that answers GitHub issue, pull-request and review comments. `@<botName>` in a comment starts a turn and the reply is a new comment in the same thread (a review thread gets a reply under it; text over 60,000 characters is split); one session per issue or pull request and one per review thread, and later comments in a thread with a session are follow-ups. `X-Hub-Signature-256` is verified over the raw body in constant time before the body is parsed (401 otherwise); the webhook is acknowledged at once. Comments by bots, by the channel's own account and every comment the channel posts (a hidden marker) are ignored, and so are edits, deletions and other events. Replies are posted with `token` (a personal access token, or a function) or as a GitHub App (`app: { appId, privateKey }`: a PKCS#1 or PKCS#8 key signs an RS256 JWT with Web Crypto, exchanged for an installation token that is cached per installation until 5 minutes before it expires; `src/channels/githubAppAuth.ts`, not exported). Approvals are comments: the prompt asks for `/approve <id>` or `/deny <id>` (first line only, notes below it), and by default only a commenter whose `author_association` is `OWNER`, `MEMBER` or `COLLABORATOR` may decide, read from the command comment itself; `approvers` (logins, or a function that sees the association in `user.roles`) overrides it, and `triggers` (logins, or a function) restricts who may start a turn or answer a question (default: everyone who can comment, so restrict it on a public repository). A comment is untrusted input to the agent; see the security note in docs/channels.md. An `ask_question` is answered by the next comment in the thread and survives a restart given durable stores. Errors name the call and the HTTP status, never the token. The `LOUSHO_CHANNEL_INVALID` hint, docs/agent-directories.md and docs/errors.md now list `githubChannel()`. New section `## GitHub` at the end of docs/channels.md.
-- Agent Forge keeps the traces of its runs: every run is written with `fileTraceExporter()` to `.lousho/agents/<agent id>/traces` (the files `lousho traces` reads), and the Trace tab gets a list of the agent's past runs (time, duration, model calls, tokens, cost, status) with a "Live" entry while a run is active; choosing one opens its spans in the waterfall, with span kind and error status. New server routes `GET /agents/:id/traces?limit=N` and `GET /agents/:id/traces/:traceId`; the server reads only inside the agent's trace folder. The live `span` WebSocket messages now carry `kind` and `status` (optional fields of `SpanEvent`). See [Agent Forge](docs/agent-forge.md).
-- A background sub-agent that needs approval pauses the lead when the lead awaits it (`agent_await`), and resumes with `approvals.resolve()` / `resume()`. The lead's result is `awaiting-approval` with the child's call (`subagentPath: ['<agent>']`) in `agent.approvals.list()`; the decision runs or rejects the child's call, the child finishes, and the continued lead gets its answer as the `agent_await` result. A child that pauses again, or several awaited tasks that are all paused, pause the lead one approval at a time. The child's usage is added to the lead's, and its conversation is saved under its `taskId`. The paused tasks are kept on the lead's approval record (`SubagentSuspension.background`, plain JSON), never in the tool arguments the model sees. Without `agent_await` nothing changes: the task reports `awaiting-approval` and is not resumable. The `task` and `agent_status` tool descriptions tell the model that a task awaiting approval continues only when it calls `agent_await` on it. Docs: docs/sub-agents.md ("When the lead run ends" and "Continuing a task").
-- Guardrail starter set: `piiGuardrail()` (email, phone, credit card with a Luhn check, IBAN with its mod-97 check, US SSN, IPv4; blocks, or rewrites each match to `[<type>]`), `secretsGuardrail()` (private keys; Anthropic, OpenRouter, OpenAI, AWS, GitHub, Slack, Google and Stripe live keys; JWTs; `Authorization: Bearer` tokens; `extraPatterns`; rewrites to `[secret]` by default), `promptInjectionGuardrail()` (phrase, role-marker and Unicode-tag heuristics, plus an optional model check that must answer `SAFE` or `INJECTION: <reason>`) and `moderationGuardrail({ model })` (one model call that answers `NONE` or the categories that apply: `hate`, `harassment`, `self-harm`, `sexual`, `sexual-minors`, `violence`, `illicit`). The PII, secret and injection checks are heuristic pattern checks: they catch common cases and miss others, and are not a security boundary. Model-backed checks fail closed on a reply they cannot read. A guardrail result can now carry `info?: GuardrailTripInfo` (`pii`, `secret`, `prompt-injection`, `moderation` or `custom`), copied to `result.guardrail`, `guardrail.tripped` and `guardrail.rewrote`; it holds types, labels and offsets, never the matched text. Agent spec files can name them in `policy.guardrails` as `pii`, `secrets`, `prompt-injection` and `moderation`. New exported types `GuardrailTripInfo`, `PiiType`, `ModerationCategory`. Docs: [Guardrails](docs/guardrails.md#input-and-output-guardrails), [Configuration](docs/configuration.md#policy-policy), [Stream events](docs/stream-events.md).
-- `telegramChannel({ botToken, secretToken, botUsername?, name?, fetch?, approvers?, onError? })`: an agent behind a Telegram bot, mounted like the Slack and Discord channels (`POST &channels&telegram`). The webhook secret token header (`X-Telegram-Bot-Api-Secret-Token`) is compared in constant time (401 otherwise); updates are acknowledged with `200` and the turn runs after. A private chat is one session per chat; in a group only `&ask`, `&ask@<botUsername>`, an `@<botUsername>` mention or a reply to the bot wakes it, and a forum topic is its own session. Replies are plain text, split at 4096 characters. Tool approvals are an inline keyboard (Approve & Deny) that only `approvers` (default: the user who started the turn) can tap; the tap names its chat, so it works after a restart. An `ask_question` is sent with `force_reply`; a pending one survives a restart given durable stores, like Slack and Discord. The bot token is never put in an error message or log line. `src&channels&channelSupport.ts` gains the internal `secretsEqual()` (constant-time compare with Web Crypto). The `LOUSHO_CHANNEL_INVALID` hint, docs&agent-directories.md and docs&errors.md now list `discordChannel()` and `telegramChannel()`. New section `## Telegram` at the end of docs&channels.md (attachments are not read yet).&r
-- `todo.updated` stream event and `useTodos()` (React, Vue) / `loushoTodos()` (Svelte): every successful `todo_write` emits `todo.updated { todos, counts, toolCallId }` right after its `tool.done` (sub-agents too, with `subagent`). The shared UI reducer keeps the list in a new `AgentUIState.todos` (carried across turns, cleared by `reset()`), `useLoushoAgent()` / `loushoAgent()` expose it, `useTodos(agent)` / `loushoTodos(agent)` add counts, the current item and progress (`todoView()` computes the same view framework-free), and `toUIMessageStream()` sends a `data-lousho-todos` part for the AI SDK UI. See [Todos](docs/react.md#todos).
-- Cloudflare Worker target: the `openrouter` provider and the `http` tool (with a required `LOUSHO_HTTP_ALLOW` host allowlist). `openrouter` reads its key from the `OPENROUTER_API_KEY` binding and is `@ai-sdk/openai` pointed at OpenRouter, so its bundle passes the `node:` leak check like `openai`. The Worker's `http` is `http_request` with the Node tool's input, over the platform `fetch()`: since a Worker cannot see or pin where a host name resolves, it reaches only the host names (`api.github.com`) and `*.` wildcards (subdomains only) listed in the comma-separated `LOUSHO_HTTP_ALLOW` binding, refuses IP-address hosts even when listed and any scheme but `http:`/`https:`, checks every redirect hop the same way, and refuses every request when the binding is unset or empty. An invalid entry fails every request with an error naming it. `wrangler.toml` gets a commented `[vars]` `LOUSHO_HTTP_ALLOW` line when the spec lists `http`. `ollama` and `web-fetch` stay unsupported on Workers. Internally, the request, redirect and response logic of `http_request` moved to the Node-free `src/tools/built-in/httpCore.ts`, shared by both tools; the Node tool's behaviour is unchanged. See docs/cloudflare-workers.md#providers-and-tools.
-- `fromAiSdk(model)`: any AI SDK `LanguageModel` (Google, Bedrock, Azure, Mistral, Gateway,...) as `createAgent({ provider })`. Options `name` (default: the model's `provider` field), `fileMediaTypes`, `replaysReasoning` and `maxRetries` (default 0); exported with `FromAiSdkOptions` from the package root. Throws `LOUSHO_CONFIG_INVALID` for a model id string, for a model built for another `ai` major than the installed one, and for a call with another model id than the wrapped one. See docs/providers.md#any-ai-sdk-model-fromaisdk.
-- Two ready-made durable stores. `@lousho/build-ai-agent/kv` is a new subpath exporting `KVStore`, `KVCheckpointStore`, `CHECKPOINT_KV_BINDING` and the types `KVStoreOptions`, `KVBinding`, `KVPutOptions`, so a hand-written Cloudflare Worker can use `createAgent({ provider, store: new KVStore(env.AGENT_KV) })`; nothing in its import graph touches `node:*`, so it bundles without shims (`assertSessionId` moved to the Node-free `src/session/sessionId.ts` and is still exported where it was). `fileStore(dir, { historyLimit? })` (root export) is an `AgentStore` of plain JSON files: `sessions/<id>.json`, `checkpoints/<id>.json`, `checkpoint-history/<id>.json` and `approvals/<id>.json`, each written to a temp file and renamed into place, with no lock files and no `StorageService`; resolving an approval claims it with an exclusive create, so of two processes resolving one approval only one gets it. It replaces combining `FileSessionStore`, `LocalStorageCheckpointStore` and `StorageServiceApprovalStore` by hand. See docs/sessions.md#choosing-a-store and docs/deployment.md.
-- `web_fetch` built-in tool: `webFetchTool` / `createWebFetchTool(options)`, and `web-fetch` in spec files. It `GET`s one public web page and returns `{ url, finalUrl, status, contentType, content, truncated }`: HTML converted to text by a small built-in converter (scripts and styles dropped, link URLs kept, entities decoded), JSON and `text/*` as sent, a note for other types; a 4xx/5xx is returned with its body. Loopback, private and link-local destinations are refused on every hop with the connection pinned to the checked address; redirects (10), bytes read (2 MiB), characters returned (50 000) and time (30 s) are capped; `allowedHosts` / `blockedHosts` are checked before DNS and `allowPrivate` exempts named hosts. Node only. See docs/tools.md#built-in-tools.
-- `src/security/privateAddress.ts` (internal): `isPrivateAddress()` and `pinnedLookup()`, shared by the credential broker, `http_request` and `web_fetch`. The credential broker uses it instead of its own list, so it also refuses `192.0.0.0/24`, `198.18.0.0/15`, NAT64 and 6to4 addresses.
-- Slack and Discord: a pending `ask_question` survives a restart. Given durable stores for sessions, checkpoints and approvals, the next message in the Slack thread (or the next `/ask` in the Discord channel) after a restart is still the answer: the turn continues, the reply is posted, and the question, the answer and the reply are appended to the session transcript (before, the answer became a new turn and the question was orphaned). A message in a conversation that waits on a tool approval still does not decide it. New `ChannelContext.pendingQuestion(sessionKey)` for custom channels: the id of the `ask_question` that key's session waits on, also one asked before a restart (it binds the approval to the session, so the continuation is recorded); handed out once until that answer has run. A channel's answer and click continuations now run one at a time with the session's turns. Supporting additions: `Checkpoint.approvalKind`, `PendingTurn.approvalKind` (`session.pending()`) and `SessionAwaitingApprovalError.approvalKind` are `'question'` for a turn paused on an `ask_question`. Slack thread replies that answer a pending question no longer need a saved transcript first (a first turn paused on a question with checkpoints has none yet). See docs/channels.md.
-- Local traces and `lousho traces`: `createAgent({ exporter, captureContent })` traces every run of the agent (`send()`, `stream()`, session turns, `agent.resume()` and runs continued by `agent.approvals.resolve()`; sub-agents join the lead's trace). The new subpath `@lousho/build-ai-agent/traces` exports `fileTraceExporter({ dir })`, which writes each run as JSON Lines to `<dir>/<YYYY-MM-DD>/<traceId>.jsonl` (default `.lousho/traces`; one finished span per line; a write error warns once and never fails the run), and `listTraces()` / `readTrace()` to read them. `npx lousho traces [--dir D] [--limit N] [--json]` lists recent runs with duration, model and tool calls, tokens and cost; `npx lousho traces <id|prefix> [--json] [--content]` prints one run as a span tree with duration bars. Projects made by `lousho init` now ignore `.lousho/`. See docs/observability.md#local-traces.
-- `openApiTools(document, options)`: an OpenAPI 3.0 / 3.1 document (object, JSON or YAML string, or https URL) becomes one typed tool per operation, exported from the root and `./tools`. Names come from `operationId` (or `<method>_<path>`); the input has path, query, header and cookie parameters plus an `application/json` `body`, with `$ref`s resolved; every HTTP response is returned as `{ status, statusText, body }`. GET, HEAD and OPTIONS run and other methods ask for approval by default (`approval`), with read-only / destructive annotations. Options: `baseUrl`, `include`, `exclude`, `prefix`, `headers`, `bearerToken`, `providedArguments` (removed from the model's schema), `timeoutMs`, `maxResponseChars`, `fetch`. The base URL must be https (http only for loopback), credentials never reach events or the transcript, and redirects are followed only on the base origin. Swagger 2.0, multipart bodies and remote `$ref`s are refused. `jsonSchemaToZod(schema, root?)` takes an optional root for `$ref` resolution. New page docs/openapi-tools.md.
-- Built-in OpenAI, Anthropic and OpenRouter providers send PDF file parts on `ai` 6 and 7 (Anthropic also `text/plain`); `ai` 4 and Ollama keep the text note. A provider subclass opts more media types in with `fileMediaTypes()` (`acceptsFileParts = true` still sends every type). The text-note warning is now once per provider and media type and names the type and the `ai` major. Added `npm run test:live` (`vitest.live.config.ts`) for `*.live.test.ts` files, which the default suite excludes. See docs/providers.md#multimodal-input.
-- Principals in tools, approval policies and permissions: the run's principal reaches a tool's `execute(args, ctx)` as `ctx.principal`, `needsApproval` functions (`ApprovalCheckContext.principal`), permission rules' `when(args, ctx)` (`PermissionContext.principal`), `preToolCall` / `postToolCall` hooks (`ToolCallHookContext.principal`), `onPermissionDecision`'s new second argument (`PermissionAuditContext`), pending approvals (`PendingApproval.principal`, seen by `approve` and by a channel's `approvers` function as `request.principal`) and in-process sub-agents (`task`, background tasks, `createDelegateTool()`; `remoteAgent()` does not forward it). New `ExecuteOptions.principal`, set by `createAgent()` for `send()`, `stream()`, session turns and channel turns. It is saved in checkpoints (`Checkpoint.principal`) and approval snapshots (`ExecutionSnapshot.principal`), so a static or dynamic run resumed after an approval or a crash acts for the same caller. `agent.approvals.resolve()` / `answer()` / `streamResolve()` / `streamAnswer()` take `{ principal }` (new `ResolveApprovalOptions`) for who decides, and the approved tool sees it as `ctx.approval.by`; `resumeAfterApproval()` takes it as `executeOptions.approver`. The approvals route (`POST /chat/:sessionId/approvals/:id`) passes the caller route auth accepted, and `mountChannels()` the clicking user (`{ id, type: 'user', authenticator: <channel name> }`) or, for a question answered by a message, its sender. `agent.fork()` keeps the source run's principal; `session.fork()` copies only the conversation. The principal is not added to events, spans or trace files. See [Principals in tools and approvals](docs/auth.md#principals-in-tools-and-approvals).
-
-### Deprecated
-- `SlackTriggerAdapter`, `CronTriggerAdapter` and `WebhookTriggerAdapter` (`@lousho/build-ai-agent/triggers`) are deprecated and will be removed in a future major version. Use `slackChannel()` for Slack (sessions per thread, approval buttons), `defineSchedule()` with `startSchedules()` for cron (or `schedules/` in an agent directory, or cron triggers in a spec file), and `webhookChannel()` for webhooks, each mounted with `mountChannels()`. `verifySlackSignature()`, the `WebhookAuth` helpers, `parseCronExpression()`, `TriggerAdapter` and `TriggerRegistry` are not deprecated. Their options types (`SlackTriggerAdapterOptions`, `CronTriggerAdapterOptions` with `CronIntervalOptions` and `CronExpressionOptions`, `WebhookTriggerAdapterOptions`) and `WebhookTriggerHandle` carry `@deprecated` too. Nothing changes at run time. See docs/triggers.md.
-
-### Fixed
-- `lousho` CLI surface: `lousho dev`/`lousho chat --traces` now writes traces for a `.ts`/`.js` module that exports an already-built `createAgent()` agent - the module's export could not take the flag's exporter after the fact, so nothing was written. `createAgent()` remembers the config it was built with (readable via the internal `createAgentConfigOf()`), and the loader rebuilds the agent with the flag's exporter (the module's own `exporter` is replaced while the flag is set; a module exporting an agent not made by `createAgent()` prints a warning and keeps its own). A spec path that does not exist (e.g. `lousho chat missing.yaml`) now fails with the coded `LOUSHO_SPEC_NOT_FOUND` instead of a raw ENOENT. `lousho add --dry-run` no longer fails when a target file already exists; it prints the file list with an "(exists - a real install needs --overwrite)" marker and exits 0 (the symlink checks still run). Top-level `lousho --help` lists the implemented flags again: `--no-schedules`/`--traces` on `dev` and `chat`, `eval`'s record/replay/drift/`--config` flags, `init`'s `--sdk-path`, and `build`'s positional form.
-- A cassette failure keeps its type through `agent.send()`: a replay mismatch (or a missing cassette raised by the provider-interception seam that `lousho eval` installs) was compacted into a generic `CompactedLLMProviderError`, losing the cassette path, the call number and the re-record hint. `CassetteMismatchError` is now an `SDKError` with code `LOUSHO_CASSETTE_INVALID` (docs/errors.md already claimed cassette errors carry it), and the run loop rethrows cassette errors untouched instead of compacting them, so `send()` rejects with the `CassetteMismatchError` itself (`.cassette`, `.callNumber`). `setProviderInterceptor()` and the `ProviderInterceptor` type are now exported from `@lousho/build-ai-agent/testing`, the public entry for the model-boundary seam docs/evals.md describes.
-- A tool call approved with `agent.approvals.resolve()` (or `resumeAfterApproval()`) now has its `execute_tool` span. It ran before the continued run started, outside any span, so OpenTelemetry and `fileTraceExporter()` showed the continued run's `invoke_agent` and `chat` spans but not the approved tool. The continued run's `invoke_agent` span now opens first and the approved call runs inside it: its `execute_tool` span is a child of it (a `run_code` call's inner calls and a sub-agent the tool starts are children of the tool span), with the same `captureContent` / `redactContent` rules as any tool span, and no span is made for a rejected call. A pause that happens again (sign-in) leaves the `invoke_agent` span with the tool span and no `chat`.
-- A tool that returns `undefined` (or an async generator that yields nothing) no longer writes a `tool` message with `content: undefined` into the transcript. Its result is now `null` everywhere: the transcript and the next model request carry `"null"`, and `tool.done`, approval resumes, `run_code` and flows see `null`. Providers, session stores and checkpoints get a valid string.
-- `recordReplay` matches a tool's parameter schema the same way under zod 3 and zod 4. A zod 4 schema was fingerprinted from its JSON Schema (with `$schema`, `required`, `additionalProperties`) while a zod 3 one, and so every recorded cassette, used a fingerprint of the schema itself, so cassettes recorded with zod 3 failed to replay with zod 4 installed (the CI `peers` jobs `ai4-zod4`, `ai6-zod4` and `ai7-zod4` failed on every replay test). Both now give the same fingerprint for the same schema; existing cassettes stay valid and need no re-recording, and a real change to a tool's parameters still fails the match.
-- Parallel `task` calls now get their `taskId`s, and background tasks start, in call order: allocating an id awaited a SHA-256 digest whose completion order is not fixed, so with `maxConcurrent: 1` the second task could take the slot first (#296, the flaky "queues tasks beyond maxConcurrent" test).
-- `SubprocessSandbox.run()` no longer fails with HTTP 404 "no such container" for a command that exits at once: the container is `AutoRemove`d, and `wait()` was only called after `start()`, so a fast command could be gone by then (10 of 40 parallel `true` runs failed on Docker Desktop). It now begins `wait({ condition: 'next-exit' })` before `start()`, and removes the container if `start()` itself fails.
-- The `cloudflare-worker` build's Node-builtin leak check now accepts the runtime-guarded `loadNodeModule("node:module" | "node:dns")` probes that `@ai-sdk/provider-utils` 4 (installed with `ai` 6) uses, as it already did for `ai` 7's `loadBuiltinModule`; without it a Worker bundle built on `ai` 6 failed with "Node builtins leaked" (found by the new `ai6` matrix entries).
-- `isAgentEvent()` is now exhaustive (the runtime type list is a `Record<AgentEventType, true>`, so the compiler rejects a missing type). It had no `agent.drift`, so remote UI clients (`parseEventStream()`, the React, Vue and Svelte bindings) silently dropped that event.
-- A remote sub-agent's token usage is added to the lead's `result.usage`. It was dropped, so budgets and cost reports undercounted delegation to a `remoteAgent()`. The lead adds what the remote agent reports on its `run.done` event to its totals, to `usage.delegated` and to `byModel['remote:<name>']`, which keeps the remote's own `costUsd` (the lead's `costUsd` is `undefined` when the remote sends none). A remote run that pauses for an approval adds what it spent up to the pause, and the continuation adds only what it spent after it; background remote tasks roll up the same way. A deployment that sends no usage adds nothing. `RemoteRunOptions` has a new optional `onUsage(usage)` callback; `RemoteSubagent.run()` still returns `Promise<string>`, so hand-written ones compile unchanged. See docs/sub-agents.md#remote-sub-agents.
-- `lousho studio` finds the Agent Forge build that ships inside the installed package when it is run from a project that does not have `apps/agent-forge` (it used to fail with "could not find apps/agent-forge" everywhere except the SDK repo). A project's own `apps/agent-forge` still wins, and `.lousho/` is still created in the directory you ran it from. `--dev` from an installed package still needs the TypeScript source and says so.
-- Documentation corrections: install commands, CLI command lists, optional peers, durable execution and compaction descriptions, the Status section, reasoning and file-part notes in the providers guide, and the `KVStore` note in the deployment guide now match the code. Ticket ids are gone from user-facing prose.
-
-### Tests
-- Two more load-sensitive tests fixed. `SandboxShell.test.ts` "passes only set values and allowed host names, never planted secrets" starts two real `node -e` processes and timed out at the 5 s default in 1 of 20 parallel runs; it has a 30 s timeout now (pure slowness, no race: it passes in under a second alone). `backgroundSubagents.test.ts` "reports a sub-agent paused for approval as awaiting-approval" waited a fixed 10 ms for the child's pause and failed in 9 of 20 parallel runs with the task still `running`; the lead now asks `agent_status` again until the task has left `running`.
-- `http.test.ts` "rejects near the configured timeout" no longer compares real elapsed time to a real timeout (flaky under load, #324): it drives the request timer with a fake clock and checks the request is still pending at 499 ms, rejects with "timed out after 500ms" at 500 ms, and that the connection is closed.
-- `src/tools/workspace/checkpoints.node.test.ts` "rewinds three turns" has a 30 s timeout: it takes well under a second alone, but timed out at the 5 s default when eight copies of the suite ran at once. The rewind itself is correct; every failure was the timeout.
-- Live-model cassettes recorded: real gpt-4o-mini runs through OpenRouter are now replayed in CI with no key, for the coding agent in the docs, the Telegram, GitHub and Teams channels, plan mode, `web_fetch`, streaming `send()`, the guardrail starter set, `fromAiSdk()` and PDF/PNG file parts, plus a recorded `lousho traces` fixture. The live files that never ran (`sendStreams`, `guardrailStarterSet`, `fileTraceExporter`, `remoteUsage`) were missing the `import '../providers'` that registers OpenRouter; fixed. New live tests (skipped without a key): ai 6 through OpenRouter and `aiSdkEmbedder()` over OpenRouter embeddings.
-- `pack-smoke` allows a 16 MiB unpacked tarball (was 14 MiB): `main` was 45 KB under the old cap and permission modes went over it; see #316 for shrinking the package instead.
-- Sandbox egress and the credential broker are tested against a real Docker Engine: a new CI workflow, "Docker Engine" (`.github/workflows/docker.yml`, on pull requests touching the sandbox, broker or docker deploy adapter, on demand and weekly), runs `npm run test:docker` on GitHub's `ubuntu-latest` runner (rootful Engine 28.0.4). `src/security/sandboxEgress.docker.test.ts` checks nine cases of `SubprocessSandbox({ network: { allow }, broker })` with `curlimages/curl`: an allowed HTTPS host answers through the broker, another host gets a 403, bypassing the proxy and raw IPs have no route, outside names do not resolve, the broker injects a credential the container never sees, a container outside the internal network cannot use the gateway listener, an aborted run and `close()` leave no container or network, and a reused non-internal network is refused. The docker deploy image test (`/health` and `/chat`) moved to `src/deploy/adapters/docker.docker.test.ts` and runs in the same job; it was skipped in CI before and passes there. No product defect was found. `*.docker.test.ts` files are excluded from `npm test` and `npm run test:coverage`; they skip without a daemon unless `LOUSHO_DOCKER_TESTS=1` is set (the workflow sets it), which makes a missing daemon fail. docs/workspace-tools.md says what the job checks; CONTRIBUTING.md mentions `npm run test:docker`.
-- `src/execution/principal.test.ts` and `principal.test-d.ts`: the principal in tools (send, stream, session and channel turns), policies, rules, hooks and sub-agents (local, background, remote), pause and resume with another approver, a restart, a crash resume on an on-disk `SqliteStore`, old checkpoints and snapshots, forks, the approvals route and channel clicks; frozen in strict mode; absent from events and spans.
-- Test files can be type-checked: `npm run typecheck:tests` runs `tsc` over `src/` including every `*.test.ts` through the new `tsconfig.tests.json`, and the test files under `src/execution`, `src/context`, `src/session`, `src/subagents`, `src/acp` and `src/testing` now pass it. The check is not in CI yet. One type change: `textOf()` also accepts a message or content whose parts are `readonly`, such as a `mockModel` request snapshot.
-
-### Docs
-- The `vendor/` model prefix note: every docs page whose snippets hardcode a `provider/model` string now says the prefix chooses the provider and that with OpenRouter the id is `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`), so `createAgent()` does not throw `LOUSHO_PROVIDER_MISSING_API_KEY` when only `OPENROUTER_API_KEY` is set. Stale model ids refreshed: `anthropic/claude-3-5-haiku-latest` examples are now `anthropic/claude-haiku-4-5`, `'anthropic/claude-3-5-sonnet-latest'` in errors.md is `'anthropic/claude-sonnet-4-5'`, `google('gemini-2.0-flash')` is `google('gemini-2.5-flash')` and the OpenRouter fallback example uses `openrouter/meta-llama/llama-3.3-70b-instruct`. (`anthropic/claude-3-5-sonnet-latest` stays where it documents the `ANTHROPIC_API_KEY` env default, which is still that id in `src/providers/providerSpec.ts`.)
-- Corrections in [Errors](docs/errors.md), [Troubleshooting](docs/troubleshooting.md) and [Testing](docs/testing.md): not every intentional error is an `SDKError` (the named `Error` subclasses — `PropagatingToolError`, `CassetteMismatchError`, `CronExpressionError`, `DecryptionError` — carry no `code`); the `Find a code by area` table now lists the `Auth` section and every code that has one; `LOUSHO_CASSETTE_INVALID` no longer claims to cover request mismatches (that is `CassetteMismatchError`), and its example uses `webhookChannel()` rather than a `webhookTrigger()` that does not exist; `createAgent()`'s default retry is documented as applying only to model strings and env-resolved models, not a `provider` instance; the file-parts entry now matches providers.md (PDFs and `text/plain` do reach providers on `ai` 6/7); `connectMcp().status()` lists `'needs-auth'`; the `mockModel` `usage` default is "none reported" (the run estimates it) rather than zero; and the request-assertion snippet notes where `temperature` comes from, since `createAgent()` has no `temperature` option.
-- [Stream events](docs/stream-events.md) gains the missing `agent.drift` row (emitted on a resume under `onAgentDrift: 'warn'`, before the continuation's first step) and the fields the table understated: `executedBy: 'provider'` on `tool.start` / `tool.done` / `tool.error` (hosted tools), `replacedByHook` on `tool.done`, `hook` on `permission.decision`, `trigger: 'manual'` on `compaction.start` / `compaction.done`, and the full `usage` shape (`inputTokens` / `outputTokens`, `estimated`, `costUsd`, and `modelCalls` / `hostedToolCalls` on `run.done`). The ordering guarantees now say that a streamed approval continuation reports `agent.drift` and the decided call's `tool.start` / `tool.done` before its first `step.start`, so those events fall outside a step. [Runs](docs/runs.md) uses the canonical event names `tool.start` / `tool.done` / `run.done` instead of the deprecated `tool-call` / `tool-result` / `finish`, and [Testing](docs/testing.md) no longer claims a `mockModel` turn without `usage` reports zeros (it reports none).
-- Long-tail corrections across the guides: `lousho eval --config`, `lousho init`'s `InitUsageError` and `-y`, `.cts` among the dev-server module extensions and streamed approval continuations in docs/cli.md; `lousho build --target=...` (not `lousho deploy`) and the public `createRouteHandler().handler` (not the internal `serveFetch()`) in docs/sub-agents.md; `description` as a `createAgent()` option and `createDeployedServer()` as build-internal in docs/agent-directories.md, docs/channels.md and docs/schedules.md; approval continuations on Workers emit `tool.start` / `tool.done`, `deploy-runtime-worker` is bundler-internal and `handleScheduled` needs a store in docs/cloudflare-workers.md; `schedule-<name>` sessions, `checkpoint-history/` and the late-appearing `approvals/` directory in docs/schedules.md and docs/sessions.md; `saveAttachment`/`readAttachment` signatures in docs/utilities.md; 256-bit OAuth state in docs/oauth.md; the `recall_<name>` description's `<name>` in docs/memory.md; `ctx.sessionId` in docs/tools.md; the `throw` flow node in docs/flows.md; the `triggers` spec field in docs/configuration.md; `principal` in a permission rule's `when` in docs/approvals.md; the `'not-a-file'` rewind skip and `NodeWorkspace`'s required `root` in docs/workspace-tools.md; a built-in channel's `name` setting its route in docs/channels.md; the `completed()` 'max-steps' message in docs/evals.md; `formatUsage`'s `$0.0000` in docs/models-and-cost.md; the completed registry static-check list and the leading letter/digit name rule in docs/registry.md; `exporter`, `captureContent` and `redactContent` as `createAgent()` options in docs/migrating-to-create-agent.md; `connectMcp().tools` as a `Record` that combines with array tools in docs/mcp.md; `HookRegistry.size()` as a method in docs/hooks.md; `*.example.com` matching subdomains only in docs/tools.md, docs/workspace-tools.md and docs/registry.md; `resumeAfterApproval()` named as an export, not an executor method, and the fork `divergedAt` comment corrected in docs/durable-execution.md.
-- New page, [Permission modes](docs/permission-modes.md): the modes and their table, which tools are read-only, the `editsFiles` marker, the order of evaluation, switching, the audit log, sub-agents and resume. [Approvals](docs/approvals.md) "Permission policies" links to it; [Tools](docs/tools.md), [Stream events](docs/stream-events.md) and [Sub-agents](docs/sub-agents.md) ("What a sub-agent inherits") gained a row each.
-- New page, [Route auth and principals](docs/auth.md): the ordered list and its three outcomes, each helper, 401 / 403 / `WWW-Authenticate`, which helpers run where (Node, Workers, edge), `createRouteHandler`, the node server and `auth.ts`, reading the principal in the run, and security notes (no session ownership check; `basic()` only over HTTPS). docs/errors.md gains a `## Auth` section at the end (`LOUSHO_AUTH_CONFIG_INVALID`). One-paragraph links from deployment.md (`### Auth`), nextjs.md (`## Routes`), memory.md (`## Scopes`), agent-directories.md (layout and deploy), api-overview.md and a "Route auth" row in the cloudflare-workers.md limits table; no heading of an existing page changed.
-- New page, [Cloudflare Workers](docs/cloudflare-workers.md): a table of what the Worker target supports and what it does not comes first, then build and deploy, bindings, sessions, checkpoints and approvals in KV, scheduled runs, consistency, and bundle size and Node builtins. The Worker sections moved out of docs/deployment.md unchanged (`Bindings, sessions and the API on Workers`, `Cron triggers and handleScheduled` and `Durable execution (pause/resume) on Workers` are gone from it); deployment.md keeps a short `cloudflare-worker` summary that links to the page. Links to `deployment.md#cron-triggers-and-handlescheduled` moved to `cloudflare-workers.md#scheduled-runs`.
-- Two dead heading links fixed: docs/executor-api.md now links to `tools.md#advanced-toolregistry`, and docs/troubleshooting.md links to `mcp.md#use-mcp-servers-in-an-agent` (the configuration anchor moved with the MCP section). No other link in `docs/` or the README points to a missing heading. docs/approvals.md lists `fileStore(dir)` among the approval stores.
-- Long pages split; text moved unchanged. New pages: [Runs](docs/runs.md), [Models and cost](docs/models-and-cost.md), [Stream events](docs/stream-events.md), [Queued input and steering](docs/queue-and-steer.md). Moved anchors (old to new): `api-overview.md#finish-reasons`, `#cancellation` and `#parallel-tool-calls` to `runs.md` (same anchors); `api-overview.md#models-tokens-and-cost` to `models-and-cost.md#models-and-the-price-table`; `api-overview.md#usage-and-cost-of-a-run` to `models-and-cost.md#usage-and-cost-of-a-run`; `api-overview.md#flow-expressions` to `flows.md#flow-expressions`; `api-overview.md#todo-tools` to `tools.md#todo-tools`; `api-overview.md#tool-errors` to `tools.md#errors`; `api-overview.md#context-compaction` to `compaction.md`; `streaming.md#event-schema-version-1`, `#ordering-guarantees`, `#typescript` and `#versioning` to `stream-events.md` (same anchors); `streaming.md#queued-input` and `#steering` to `queue-and-steer.md` (same anchors); the `AgentExecutor.execute()` options table of `configuration.md` to `executor-api.md#options-of-agentexecutorexecute`. The error codes page gained a "Find a code by area" table; its headings are unchanged.
-- The API overview, providers, structured output, tools, tracing, guardrails and testing guides teach `createAgent()` first: usage and multimodal examples use it, the testing tool example uses `defineTool()`, and every executor, `AgentBuilder` or `ToolRegistry` snippet sits under an "Advanced" heading that links to [the executor API](docs/executor-api.md). They say that `createAgent()` does not take `exporter`, `captureContent` or `sandbox` yet.
-- New page, [Triggers](docs/triggers.md): the `@lousho/build-ai-agent/triggers` adapters, a table that says when to use triggers, channels or schedules, the `TriggerAdapter` interface (with a custom adapter and `TriggerRegistry`), and the webhook, Slack and cron sections that moved from the API overview, unchanged. The API overview now points to it; links to `api-overview.md#triggers`, `#webhook-authentication` and `#slack-request-signatures` moved to `triggers.md`. The missing-`auth` warning of `WebhookTriggerAdapter` and the missing-`signingSecret` warning of `SlackTriggerAdapter` now link to `docs/triggers.md`.
-- New page docs/migrating-to-create-agent.md: from `AgentBuilder`, `AgentExecutor`, `ToolRegistry` and `resumeAfterApproval()` to `createAgent()`, with a before-and-after example, a mapping table, the `ExecuteOptions` that `createAgent()` does not take yet (with alternatives), the behavior differences and a step-by-step checklist. Linked from docs/executor-api.md and the README docs table.
-- New page, [Hooks](docs/hooks.md): the four hook points, the outcomes of a `preToolCall` / `postToolCall` hook, four type-checked recipes (deny a tool, add a default argument, redact a result, inject context), ordering, and `HookRegistry`. The `HookRegistry` bullet and the `### Hook outcomes` section moved there from the API overview, which now points to it; links to `api-overview.md#hook-outcomes` moved to `hooks.md#hook-outcomes`.
-- Approvals, sessions, streaming, sub-agents, compaction and skills guides show `createAgent()` first. Executor snippets (`AgentExecutor`, `resumeAfterApproval`, `streamResumeAfterApproval`, `InputQueue`, `HookRegistry`) moved under headings named "Advanced: the executor API" (links to docs/executor-api.md); `approvals` and `streaming` renamed a section to that name. `createAgent({ hooks: [createCompactionHook(...)] })` is the compaction example. Removed a statement from the sub-agents guide that `createAgent()` takes no `approvalStore` (it does, and `agent.approvals` resolves sub-agent pauses).
-- Stale statements removed: ticket ids in the Agent Forge page, the "removed next minor" promise on `AgentType` in the API overview, and the installation note that read as if every user needs Node 22.19 for the `http` tool (it comes from the `undici@8` dependency, which is loaded only for `validateSSL: false` requests). The `ProposedAction` doc comment no longer refers to an unlanded ticket.
-- New page docs/mcp.md, "MCP (Model Context Protocol)": using MCP servers in an agent, `connectMcp()`, approval for MCP tools, `loadMcpTools()`, serving an agent with `serveMcp()` and `lousho mcp`, and a Limits list. These sections moved out of docs/configuration.md, which keeps the `mcpServers` spec field and links to the new page; links from approvals, CLI, tools, API overview and the README now point to `mcp.md`.
-- `docs/durable-execution.md` and `docs/workspace-tools.md` lead with `createAgent()` (`send()` with a `sessionId`, `agent.resume()`, `agent.approvals.resolve()`, `agent.fork()`) instead of `AgentExecutor`. The executor snippets (`execute()` with a `checkpointStore`, `resumeAfterApproval()`, `AgentExecutor.fork()`, the `ToolRegistry` setup) moved under "Advanced: the executor API". In durable-execution the heading "What happens when you call `execute()` again with the same `sessionId`" is now "What happens when you send again with the same `sessionId`".
-- New page docs/troubleshooting.md: start from the symptom (setup, runs that end without an answer, tools, providers, sandbox and MCP), with cause, fix and a link for each. README docs table, `docs/installation.md` and `docs/errors.md` link to it.
-- New guide, [Build a coding agent](docs/build-a-coding-agent.md): a terminal coding agent in six steps (workspace tools confined to the project, approval before writes and risky commands, a streamed UI that handles the approval pause, a session for follow-up questions, offline tests with `MemoryWorkspace` and `mockModel`), with an offline test of the same agent (`docs/buildACodingAgent.test.ts`; its replay of a recorded real-model run is skipped until the cassette `docs/__cassettes__/build-a-coding-agent.json` is recorded).
-- The Quick Start is rewritten around `createAgent()`: hello world, a tool, streaming, a session, an approval, an offline test with `mockModel`, a custom provider and spec files, each runnable with no API key (the first excepted). The `AgentBuilder` + `AgentExecutor` section moved to a new page, docs/executor-api.md (with the `ToolRegistry` note); the Quick Start no longer shows either API.
-- `create-lousho-agent` has a README (its npm page was empty) and `license`, `homepage` and `repository` fields; they appear on npm with its next release. `lousho init --help` no longer says `--sdk-path` is needed until the package is on npm.
-- docs/auth.md gains a section at its end, `## Principals in tools and approvals` (with `### In a tool`, `### Approval policies and permission rules`, `### Who approved`, `### Pauses, crashes and forks`, `### Sub-agents`, `### What is stored and logged`); its "Reading the principal in the run" and "Security notes" text is updated. One-sentence links, no new headings: docs/approvals.md (`needsApproval` context, `approve`), docs/tools.md (`ctx.principal` and `ctx.approval` rows), docs/permission-modes.md (the audit log) and docs/channels.md (`approvers`).
-- UI and server examples corrected: docs/ai-sdk-ui.md's client snippet used `useChat({ api: '/api/chat' })`, the `ai` 4 signature, which is invalid for the documented `ai` 6/7 combos — it now uses `useChat({ transport: new DefaultChatTransport({ api }) })` and a note says which `ai` majors are supported (`ai` 4 keeps `useChat({ api })` and returns `input` / `handleInputChange` / `handleSubmit`; `ai` 5 is not in the peer range). docs/nextjs.md's `useChat` snippet has the same version note. The route handlers of ai-sdk-ui.md and nextjs.md opened `agent.session({ id })` per request with no `store`, so a second turn forgot the first: both now pass `store: memoryStore()` and say to use a durable store on serverless; docs/react.md's server section says the same for a per-request session. The `data-lousho-approval` part no longer reads as if `kind` / `question` only mark an `ask_question`: a tool waiting on an OAuth sign-in carries `kind: 'sign-in'` and `signIn: { provider, displayName?, url }`; docs/react.md's `pendingApproval` row says the same.
-
-## [1.0.0-alpha.8] - 2026-10-02
-
-### Changed
-- No `any` left in the SDK's types (LOU-D16): `npm run lint` now fails on any ESLint warning, and `no-explicit-any`, `no-unused-vars` and `ban-ts-comment` are errors. Runtime behavior is unchanged; some exported types are stricter, which can be a compile error where code read an `any` value without checking it. What changed, and how to migrate:
-  - Values the SDK cannot know are `unknown` (narrow them, or cast to the shape you expect): `FlowExecutionResult.output` and `.variables`, `FlowExecutionContext.variables` / `session` / `memory`, `GenerateResult.rawResponse`, `StreamChunk.toolResult.result`, extra keys of `LLMProviderConfig`, `AgentConfig.expectedResult` / `events` / `metadata`, `AgentExecutionResult.result`, `ResultData.result`, `SessionData.data`, `JiraTicket.customFields`, the extra keys of `formatZodError()`'s result, `ToolConfiguration.options`, `ToolSetting.options`, `FlowToolSetting.options`, `ToolNode.toolOptions`, `UIComponentNode.componentProps`, `FlowChunkEvent.issues` / `input` / `toolResults[].args` / `componentProps`, and `ToolDefinition.function.parameters`.
-  - `FlowExecutionEvent` is a union discriminated on `type`, with `data` typed per event type (new `FlowExecutionEventOf<T>` and `FlowExecutionEventDataMap`): check `event.type` before reading `event.data` (`if (event.type === 'tool-call') event.data?.tool`).
-  - `AgentConfig.settings` (and `AgentBuilder.setSettings()`) is the new `AgentSettings` (`{ model?: string; [key: string]: unknown }`).
-  - `StorageService.readPlainJSONAttachment<T>()` (and `IStorageService`'s) defaults `T` to `unknown`: pass the type you stored, `readPlainJSONAttachment<MyRecord>(key)`.
-  - `OpenRouterProvider.getModelInfo()` returns the new `OpenRouterModel` (`{ id: string; [key: string]: unknown }`), `null` or `undefined`.
-  - `FlowBuilder.addAgent()` / `setAgents()` take `FlowAgentDefinition`; `injectVariables()` and `applyInputTransformation()` take a `FlowDefinitionNode` (`injectVariables()` returns the type it was given); `validateFlowInput()` takes `Record<string, unknown>`; `validateAgentTools()` takes `Record<string, { tool?: unknown }>`; `createDynamicZodSchemaForInputs()` returns `z.ZodObject<Record<string, z.ZodTypeAny>>`.
-  - Still accepted as before: `needsApproval` predicates typed for a tool's own arguments, any argument to `formatAxiosError()` and `hasRequiredKeys()`, and anything as `writePlainJSONAttachment()` data. The deprecated `ExecutionEvent` keeps `toolResult.result: any`.
-- Eval cassettes hook in at the model boundary (LOU-D46.2): `lousho eval --record / --replay / --drift` no longer reassigns `AgentExecutor.execute` at runtime. The run loop routes every model call through a small provider-interception seam (`setProviderInterceptor()` / `interceptProvider()` in `src/providers/interception.ts`; a no-op unless an interceptor is installed), and the eval runner installs one that answers with the per-case `recordReplay()` wrapper. Cassette files, keying, `--drift` output and JUnit reports are unchanged, so existing cassettes keep replaying. Streamed runs and sub-agents inside an eval case are covered by tests.
-- More errors carry SDK error codes (LOU-D2.2): the plain `Error`s thrown by `src/execution` (`historyLimit`, `toolConcurrency`, a second iteration of an `AgentRun`), the tool registry, the built-in tools, `serveMcp()`, `NodeWorkspace` and the `lousho init` / `studio` / chat helpers are now `SDKError`s with an existing code (`LOUSHO_CONFIG_INVALID` via `ConfigurationError`, `LOUSHO_RUN_ALREADY_ITERATED`, `LOUSHO_APPROVAL_NOT_FOUND`, `LOUSHO_PROVIDER_UNKNOWN`, `LOUSHO_TOOL_EXECUTION_FAILED`). Messages are unchanged; `error.code`, `error.hint` and a `[code] hint (docs)` line (not on the built-in tools' run-time failures, whose message is the model-visible tool result) are added. Code that matched `error.constructor === Error` or `error.name === 'Error'` needs `error instanceof SDKError`.
-- The remaining user-reachable plain `Error`s carry SDK error codes (LOU-D2.3): agent directories, flows, memory, skills, storage (SQLite), triggers, deploy, evals, record/replay cassettes, `defineTool()`, sub-agent options, channels, sandbox/credential-broker options and the `llm` registry now throw an `SDKError` (message text unchanged, plus the `[code] hint (docs)` line, except for tool results and messages tests assert, which stay as written). New codes: `LOUSHO_TOOL_ARGS_INVALID` (what `ToolArgumentsValidationError` carries now), `LOUSHO_AGENT_DIR_INVALID`, `LOUSHO_SKILL_INVALID`, `LOUSHO_FLOW_INVALID`, `LOUSHO_STORAGE_FAILED`, `LOUSHO_TRIGGER_INVALID`, `LOUSHO_DEPLOY_FAILED`, `LOUSHO_EVALS_INVALID`, `LOUSHO_TEST_FAILED`, `LOUSHO_CASSETTE_INVALID` and `LOUSHO_CHANNEL_REQUEST_FAILED`, all in `docs/errors.md`. Code that matched these errors by `error.constructor === Error` or `error.name === 'Error'` must check `instanceof SDKError` / `error.code` instead. `ToolExecutionError` takes an optional fourth `code` argument. A new test (`src/utils/plainErrors.test.ts`) fails when new SDK code throws a plain `Error`; the 5 that remain are listed there with the reason.
-- The last two allowlisted plain `Error`s are `SDKError`s (LOU-D16): OpenRouter's model-catalog fetch (`LOUSHO_PROVIDER_REQUEST_FAILED`; `getModels()` / `getModelInfo()` still catch it and fall back) and the UI runner's failed `POST` to a remote agent (`LOUSHO_REMOTE_REQUEST_FAILED`, as used by `useLoushoAgent()` and the Vue/Svelte bindings). Both keep their message text exactly (no help line appended), so the UI's error event shows the same message, now with `name: 'SDKError'` instead of `'Error'`. `SDKError` itself moved to `src/utils/sdkError.ts` (re-exported from the same places as before) so the browser entries can throw it without importing `ai`. The allowlist in `src/utils/plainErrors.test.ts` is down to the 3 intended sites.
-- zod 3 or zod 4 (LOU-D29): the `zod` peer is now `^3.25.76 || ^4.0.0`. Schemas of either major (including `zod/v4` on zod 3.25 and `zod/v3` on zod 4) work in `defineTool({ input })`, structured `output` and argument validation: zod 4 schemas are sent to the model as `z.toJSONSchema` output (also to `ai` v4, whose own converter only reads zod 3), zod 3 schemas through the `ai` SDK's converter as before, and both are parsed with their own `safeParse`. `defineTool` also takes any Standard Schema that exposes `~standard.jsonSchema`; tool arguments validate with any Standard Schema's `~standard.validate`. The SDK's own schemas (AgentSpec, registry documents, built-in tools, MCP tool conversion) run on whichever major is installed, and issue messages read the same on both (zod 4's `Invalid input: expected string, received undefined` is reported as `Required`). `lousho init` keeps zod 3 for the `ai` 4 scaffold (Ollama), whose packages peer on zod 3. Ollama on `ai` 6/7 (`ollama-ai-provider-v2`, which peers on zod 4) is no longer blocked by the SDK's zod peer. CI runs the type check, build and suite on zod 4 too. Migration: `DefineToolOptions`, `DefinedTool` and `ToolDescriptor.inputSchema` are typed with the new exported `StandardSchemaV1` (parsed type: `InferSchemaOutput`) instead of zod 3's `ZodTypeAny`; code that called zod methods on `descriptor.inputSchema` needs a cast. The `task` tool's error for an unknown sub-agent now reads `Unknown sub-agent "x". Expected one of: 'a', 'b'`. `createAgent({ output })` is still typed with the installed major's `ZodType`.
-- Slack and Discord approvals are starter-only by default (LOU-P5.2, behaviour change): without `approvers`, only the user who started the turn (the Slack message author, the Discord command's user) can approve or deny a tool call; before, anyone who could see the message could. Migration: pass `approvers: () => true` for the old behaviour, or a list of user ids / a function for a team. Approval button values (Slack) and custom ids (Discord) now carry the starter (`<starter>:<approval id>`), so buttons posted before the upgrade carry no starter and only an `approvers` list or function can approve them.
-- Package entries share one copy of each module (LOU-D42): tsup code splitting is on, so `@lousho/build-ai-agent`, `/hooks`, `/tools`, `/mcp` and the rest import shared chunks instead of each bundling their own copy. `HookRegistry`, `SDKError` and module-level registries are now the same object across entries (they were duplicated, so `instanceof` and singletons could disagree), and `dist/` shrinks from about 25 MB to 8.8 MB. `instanceof SDKError` and `instanceof HookRegistry` also hold between the ESM and CJS copies a mixed-format process loads (a `Symbol.for` brand). See [Installation](docs/installation.md#entry-points-share-code-esm-and-cjs).
-- A crash resume of a dynamic agent restores the run's config (LOU-V15.2): checkpoints now carry `runConfig` (the `ctx` and model the run was resolved with, as approval snapshots already did), and `agent.resume(id)` / `session.resume()` / `send(…, { sessionId })` on an unfinished run use the saved model and re-resolve `tools` and `instructions` with the saved `ctx`, instead of `input: []` and no `metadata`; a model chosen from `metadata` no longer changes mid-run. Static agents are unchanged.
-- Resumed approved calls must run with the approved arguments (LOU-X3.2, behaviour change): after the pre-tool hooks ran on the resumed call, the arguments are compared (deep, key order ignored) with the approved ones whether a hook returned `{ input }` or changed `ctx.args` in place, and a difference is refused with the existing `kind: 'validation'` error ("approved with different input"); a hook that rebuilds the same arguments in another key order is no longer refused. **Migration:** a hook that rewrites arguments (a redactor, a normalizer) must also run on the original run, so the approval record already holds the rewritten input; a hook added only after the pause, that changes the arguments, now refuses the call. A call whose tool no longer exists after an approval (snapshots with an agent fingerprint) now rejects with `LOUSHO_RESUME_TOOL_MISSING` instead of giving the model a `not-found` tool result; older snapshots keep the old behaviour.
-- Cancelled and settled tool calls use the shared tool-error shape (LOU-U14.2): a tool call cancelled before it ran (the run was aborted or steered) and a sub-agent call dropped because the lead run was already pausing for another approval now reach the model as `{ error: 'ToolNotRunError', toolName, message, kind: 'not-run' }` with the transcript message flagged `isError`. Before, the result was `{ error: '<text>' }` (and the cancelled one was not flagged `isError`); the text is now under `message`.
-- A `permissions` `allow` (or `ask`) rule no longer overrides a tool's own `needsApproval` deny (LOU-X8 follow-up, behaviour change): the tool's `needsApproval` is now called for those calls too, and its `'deny'` / `{ deny }` denies the call; an `allow` still skips the tool's ask. A `deny` rule still wins without calling `needsApproval`. Migration: a tool that should run under an `allow` rule must not deny it from `needsApproval`. See docs/approvals.md.
-- `agent.session()` passes the agent's `createAgent({ compaction })` to the session (LOU-W8 follow-up), so `session.compact()` uses the agent's strategy and sizes unless `agent.session({ compaction })` sets its own.
-- The `cloudflare-worker` target builds with `ai` v7 installed (LOU-D28c). With `ai` v7 (`@ai-sdk/openai`/`@ai-sdk/anthropic` v4), `lousho build --target=cloudflare-worker` failed with "Node builtins leaked" (`node:module`, `node:dns`, `node:diagnostics_channel`, `node:async_hooks`). Those are not imports: `ai` v7 and `@ai-sdk/provider-utils` v5 probe them at run time through `process.getBuiltinModule()`, only when running on Node, so the bundle never loads them on Workers. The build's leak check now exempts exactly those four ids, and only as the argument of a `getBuiltinModule`/`loadBuiltinModule` call; any other `node:` reference still fails the build. No `nodejs_compat` flag is needed. The 16 Worker bundle tests that LOU-D28b skipped on `ai` v7 now run on both majors. The bundle is about 3.4 MB raw on v7 (1.7 MB on v4), well under the 64 MiB limit.
-- BREAKING: sandboxed and workspace commands get an allowlisted environment (LOU-X11). Commands run by `NodeWorkspace.exec()` and `SandboxShell` no longer see the host's `process.env`, so `env`/`printenv` cannot reveal API keys or cloud credentials. They get a small base a shell needs (`PATH`, `HOME`/`USERPROFILE`, `TMP`/`TEMP`/`TMPDIR`, `LANG`, `LC_*`, `TERM`, plus `SystemRoot`, `SystemDrive`, `ComSpec`, `PATHEXT`, `WINDIR` on Windows) and what you add. A container (`SubprocessSandbox`) gets only what you add, never the host env. `SandboxShell` gains `env` and `inheritEnv` options; `NodeWorkspaceOptions.inheritEnv` and `SandboxShellOptions.inheritEnv` accept `true`; `SandboxRunOptions` gains `inheritEnv` (`NoopSandbox` keeps passing the host env unless it is `false`, which `SandboxShell` sets). `SubprocessSandbox` gains `network: 'none' | 'default' | { allow: string[] }` (default `'none'`, as before); `{ allow }` is validated and kept on `sandbox.network` but runs with no network until the egress proxy of LOU-X12 enforces it (fail closed). **Migration:** pass what commands need, either values (`env: { NODE_ENV: 'test' }`) or host names to copy (`inheritEnv: ['CI', 'NODE_OPTIONS']`); to restore the old behavior, pass `inheritEnv: true`. See docs/workspace-tools.md.
-- Internal (LOU-D28b): the test suite runs with `ai` v7 installed as `ai`. A test helper (`src/providers/aiMajor.testkit.ts`: `installedAiMajor`, `describeOnAiV4`, `itOnAiV4`) reads the installed major; tests whose behavior is the same on both majors are made major-agnostic, the 66 that only make sense on v4 (v4 message and call shapes, `MockLanguageModelV1`) or on a Worker bundle that still leaks `node:` built-ins on v7 (LOU-D28c) are skipped there. The `typecheck-ai7` CI job now also builds and runs `npx vitest run`. Test and CI change only; no product change.
-- Internal (LOU-D28a): the SDK source now type-checks against `ai` v7 (with `@ai-sdk/openai`/`@ai-sdk/anthropic` v4) as well as `ai` v4. `AiSdkProvider` builds its `ai` v4 request with SDK-owned structural types instead of the v4-only `CoreMessage`/`CoreAssistantMessage`/`CoreToolMessage`/`Output` types and no longer calls `ai`'s `tool()` (an identity function on v4); the legacy `.tool` that `defineTool()`/`toolDescriptorFromSchema()` hand-build is cast once at that boundary. No runtime change on v4. A new CI job runs `tsc --noEmit` with `ai@7` installed. The `ai`/`@ai-sdk/*` peer ranges are unchanged for now (LOU-D28d).
-- MCP tools without `readOnlyHint` now ask for approval by default (LOU-Z5, BREAKING for MCP users): `loadMcpTools()`, `connectMcp()` and `createAgent({ mcpServers })` set `needsApproval` from each tool's MCP annotations: `readOnlyHint: true` runs, `destructiveHint` true or absent (the MCP spec default) asks, `destructiveHint: false` runs. Choose per server with the new `approval: 'annotations' | 'always' | 'never' | ({ name, annotations }) => boolean` (`loadMcpTools(client, name, { approval })`, `connectMcp()` server entries, `createAgent({ mcpServers })` and `AgentSpec.mcpServers`, which validates it; a spec file takes the three strings). The descriptor keeps the raw annotations on the new `ToolDescriptor.metadata?.mcp.annotations` (types `McpToolAnnotations`, `ToolMetadata`, `McpApproval`) and uses the annotation `title` as `displayName`. Migration: pass `approval: 'never'` to restore the old behaviour (every MCP tool runs without asking). `createAgent()` agents pause with `finishReason: 'awaiting-approval'`, while a bare `AgentExecutor` without an `approvalStore` now throws for such tools. See docs/configuration.md#mcp-tool-approval-approval.
-- Small built-in tools are defined with `defineTool` (LOU-D24, not breaking): `currentDateTool`, `dayNameTool`, `createEmailTool()`, `createHttpTool()`, `createSlackTool()`, `createDelegateTool()` and the descriptors `loadMcpTools()` builds no longer call `ai`'s `tool()`. They now carry canonical `inputSchema` / `execute` (the legacy `.tool` stays), and the built-ins have the tool names `current_date`, `day_name`, `send_email`, `http_request`, `slack_alert` and `delegate_to_<agent>`. Descriptions, schemas, approval and sandbox behaviour and the factory signatures are unchanged. MCP descriptors are built with the new internal `toolDescriptorFromSchema()`, which (unlike `defineTool`) accepts any server-provided name or empty description. `routeFetchThroughSandbox()` reads the canonical `execute` first.
-- GitHub and Jira tools are defined with `defineTool` (LOU-D25, not breaking): the 28 `createGitHubTools()` tools and the 20 `createJiraTools()` tools no longer call `ai`'s `tool()`, so nothing under `src/tools` imports `ai` any more. They now carry canonical `inputSchema` / `execute` (the legacy `.tool` stays). Tool names, descriptions, schemas, the sandbox flags and the factory signatures are unchanged. The GitHub out-of-scope tools (branch/file writes, code search, issue CRUD, merge) are disabled through the canonical `execute` as well as `tool.execute`, so calling one still throws "out of scope" before any HTTP request. `JiraTools.register()` now also routes tools registered with `defineTool` through the sandbox seam.
-- BREAKING (types only): `Message.content` is widened from `string` to `string | ContentPart[]` (LOU-V11). Messages you build keep working unchanged, but code that reads `message.content` as a string (`.length`, `.startsWith()`, a template literal) no longer type-checks. **Migration:** read `textOf(message)` instead, or narrow with `typeof message.content === 'string'`. A custom `LLMProvider` that forwards `content` should handle the parts or send `textOf(message)`.
-- The execute context is our own type (LOU-D23, not breaking): the new exported `ToolExecutionContext` (`{ toolCallId, messages: readonly Message[], abortSignal?, sessionId?, onDelegatedUsage? }`, `Message` from `@lousho/build-ai-agent`) replaces the `ai` SDK's `ToolExecutionOptions` as the type of the second argument of `defineTool()`'s `execute`, `ToolDescriptor.execute`, `DefinedTool.execute` and the third argument of `sandboxExecute`, and is what `buildToolRunContext()` returns; the public types no longer import `ToolExecutionOptions` from `ai`. A function typed for `ai`'s options that only reads `toolCallId` or `abortSignal` stays assignable. `ToolRunContext` is now a deprecated alias of the optional fields of `ToolExecutionContext` (it already existed with `onDelegatedUsage` and `toolCallId`). `AgentExecutionOptions.messages` is typed `Message[]` instead of the `ai` SDK's `CoreMessage[]` (the field is unused by the SDK). The legacy `ToolDescriptor.tool` (`ai` v4 `Tool`) is unchanged. See docs/tools.md#execute-context.
-- BREAKING (small): `SDKError.code` values are now the `LOUSHO_*` codes (LOU-D2): `AGENT_EXECUTION_ERROR` -> `LOUSHO_AGENT_EXECUTION_FAILED`, `TOOL_EXECUTION_ERROR` -> `LOUSHO_TOOL_EXECUTION_FAILED`, `LLM_PROVIDER_ERROR` -> `LOUSHO_PROVIDER_REQUEST_FAILED`, `SESSION_AWAITING_APPROVAL` -> `LOUSHO_SESSION_AWAITING_APPROVAL`, `FLOW_EXECUTION_ERROR` -> `LOUSHO_FLOW_EXECUTION_FAILED`, `CONFIGURATION_ERROR` -> `LOUSHO_CONFIG_INVALID`, `VALIDATION_ERROR` -> `LOUSHO_VALIDATION_FAILED`, `TIMEOUT_ERROR` -> `LOUSHO_OPERATION_TIMEOUT`, `RATE_LIMIT_ERROR` -> `LOUSHO_PROVIDER_RATE_LIMITED`; `code` is no longer optional (`new SDKError(message)` gets `LOUSHO_GENERIC_ERROR`). No class was renamed. The messages of `SDKError`s other than `ToolExecutionError`, `LLMProviderError`, `TimeoutError` and `RateLimitError` gain a second line with the code, hint and docs link, and `loadSpec()` now rejects a spec whose top-level field is a likely typo of a spec field (`LOUSHO_SPEC_UNKNOWN_FIELD`; other unknown fields are still ignored). **Migration:** compare `code` against the new values (or use `instanceof`); match messages with `toContain` / a regex, or compare `error.detail`, instead of exact equality.
-- BREAKING (small): tool failures that did not go through the thrown-error path now use the shared shape (LOU-U14), so `error` is an error name instead of a message. Before: an unknown tool or a missing registry gave `{ error: "Tool 'x' not found" }` / `{ error: 'No tool registry available' }`; a rejected approval gave `{ error: 'Tool execution was rejected by the reviewer', note }`; a tool that threw after an approval gave `{ error: '<message>' }`; a call left without a result on resume gave `{ error: 'Tool call was not run: ...' }`. Now each is `{ error: '<ToolNotFoundError | ToolRejectedError | <thrown error name> | ToolNotRunError>', toolName, message: '<the old text>', kind, ... }`. A tool approved but missing from the registry on resume used to reject `resumeAfterApproval()` with `Tool 'x' not found in registry`; it now resolves with a `not-found` error result. The sandbox guard throws `SandboxRequiredError` (same message, still an `Error`). **Migration:** read `message` instead of `error` when you want the text, and branch on `kind`. `ToolArgumentsValidationError.toToolResult()` now also returns `kind: 'validation'`.
-- Background sub-agents still running when the lead run ends are now cancelled (LOU-Y4.2) instead of running to completion on their own; a lead run that pauses for approval cancels them too (the resumed run starts with none). **Migration:** to keep them, have the lead collect them with `agent_await` before its final answer, or set `subagentOptions: { awaitBackgroundOnFinish: true }`.
-- Heavy dependencies are optional peers (LOU-D40): `dockerode` (Docker sandboxing, `SubprocessSandbox`), `@modelcontextprotocol/sdk` (`serveMcp`, `lousho mcp`, MCP clients) and `prompts` (the interactive questions of `lousho init`) moved from `dependencies` to `peerDependencies`, marked optional in `peerDependenciesMeta`. They were already loaded lazily; now a project that uses none of them does not install them. Using one without its package fails that call with `MissingPeerDependencyError`, which now also carries `feature` and names the exact command (for example `npm install dockerode@^5.0.1`). `lousho doctor` lists the three with what they enable (a missing `dockerode` fails the check when the agent spec uses a sandboxed tool), and its version lookup no longer returns `undefined` for packages whose `exports` map hides `package.json`. **Migration:** install the peer if you use Docker sandboxing (`npm install dockerode`), MCP (`npm install @modelcontextprotocol/sdk`), or interactive `lousho init` (`npm install prompts`; `npm create lousho-agent` already does, and `lousho init --yes` needs nothing). See docs/installation.md.
-- The `http` tool no longer loads `undici` for default requests (LOU-D40): with TLS verification on (the default) it uses the runtime's global `fetch`; `undici` (still a regular dependency) is loaded only for `validateSSL: false`, whose per-request TLS dispatcher the global `fetch` cannot express. `yaml` stays a dependency (agent specs and skills need a YAML parser).
-- Retries no longer stack (LOU-V7.2): the built-in providers (`OpenAIProvider`, `AnthropicProvider`, `OllamaProvider`, `OpenRouterProvider`) now pass `maxRetries` to the `ai` SDK calls: `config.maxRetries`, or 2 (the `ai` SDK's default, so behaviour is unchanged) when unset. `createAgent()` builds the providers it resolves from strings with `maxRetries: 0` and retries in its `withRetry()` wrapper instead, so retries happen in one place (at most 3 calls by default, as before) and each one is observable. If you wrap a built-in provider in `withRetry()` / `resilientProvider()` yourself, build it with `maxRetries: 0`; note that a `maxRetries` you already set in a provider config is now honoured by the `ai` SDK.
-- `AgentType` is optional and deprecated (LOU-D34, not breaking): `AgentBuilder.build()` no longer requires `setType()` and `AgentConfig.agentType` is now optional (`createAgent()` and `specToAgent()` agents carry no type). `AgentType`, `setType()` and the `agent-types` registry/validators are marked `@deprecated`: they have no runtime effect and will be removed in the next minor; they stay exported for now. Drop your `setType(...)` calls.
-- BREAKING: `encrypt()` now generates a random salt per call instead of a hardcoded one. Ciphertext produced before this change cannot be decrypted with the new code and must be re-encrypted.
-- BREAKING: The mock repositories (`MockAgentRepository`, `MockSessionRepository`, `MockResultRepository`, `MockMemoryRepository`, `MockAttachmentRepository` — previously re-exported from `src/data/mocks.ts` via the package root/`./data` subpath; this package has no `createMockRepositories` factory) are no longer exported from the package root. Import them from `@lousho/build-ai-agent/testing` instead.
-- One session-API client behind `remoteAgent()` and `remoteTarget()` (LOU-D53): both now share an internal client (`src/server/sessionClient.ts`) for `POST <url>/chat`, the SSE read, bearer-token scrubbing and the error mapping, and use one pair of codes, `LOUSHO_REMOTE_REQUEST_FAILED` and `LOUSHO_REMOTE_UNAUTHORIZED`. The unreleased `LOUSHO_REMOTE_AGENT_FAILED` (LOU-Y7) is removed: a `remoteAgent()` failure now carries `LOUSHO_REMOTE_REQUEST_FAILED` (network, non-2xx, truncated stream, or a remote run that ends in an error, with "the remote run ended in an error" in the message) or `LOUSHO_REMOTE_UNAUTHORIZED` (401). No option or behavior of either function changed.
-
-### Added
-- Remote sub-agent approvals go through the lead run (LOU-Y7.3): a `remoteAgent()` task whose remote run pauses for a tool approval now pauses the lead run the way a local sub-agent does (it used to fail with `LOUSHO_SESSION_AWAITING_APPROVAL`): the lead's pending approval (`agent.approvals.list()`, channel buttons, the dev chat, ACP permission requests) has the remote tool's name and input and `subagentPath: [<remote agent>]`, and a remote `ask_question` arrives as a question. Deciding it on the lead (`resolve`, `streamResolve`, `answer`) posts the decision to the remote `POST <url>/chat/:sessionId/approvals/:id` and the continuation's final answer is the `task` result; a further pause pauses the lead again. The lead's approval snapshot stores the remote session id, the remote approval id, the `taskId` and the agent name (never the token), so a fresh lead process on the same store can decide it. Failures while deciding (401, other non-2xx including the remote's 404 for an approval no longer pending, network) are the `task` call's structured tool error with `LOUSHO_REMOTE_UNAUTHORIZED` / `LOUSHO_REMOTE_REQUEST_FAILED`. A remote agent with an `output` schema now returns its object as JSON with the footer (the V4.2 shape), read from `run.done`'s `object`. `RemoteSubagent.run()` takes `pausable` and `decision` (type `RemoteRunOptions`); the internal session client gains `resolveRemoteApproval()` and `SessionTurnSummary.object`. Only a lead run without an approval store keeps the old `LOUSHO_SESSION_AWAITING_APPROVAL` error. See docs/sub-agents.md#remote-approvals.
-- Structured output for sessions and sub-agents, typed for either zod major (LOU-V4.2): `createAgent({ output })` and `ExecuteOptions.output` accept a zod 3 schema, a zod 4 schema (`zod/v4` on zod 3.25, or zod 4) or a Standard Schema that can produce JSON Schema, and `result.object` is inferred from each without a cast (`InferSchemaOutput`, as `defineTool`). `AgentSession` is generic (`AgentSession<TObject = unknown>`): `agent.session().send()` and `.stream()` results carry the typed `object`. A sub-agent with its own `output` returns its validated object as JSON (then the `taskId` footer) as the `task` and `agent_await` result; its `output-invalid` finish is a structured tool error. Sub-agents do not inherit the lead's `output`; `remoteAgent()` returns text only. The exported spec schemas (`agentSpecSchema`, ...) are typed as `SpecSchema<T>` / `SpecObjectSchema<T>`, so the published `schema-*.d.ts` no longer depends on zod 3 generics (`skipLibCheck: false` projects on zod 4). The Ollama missing-peer note now says `ollama-ai-provider-v2` needs zod 4 (`npm install zod@^4.0.0`). See docs/structured-output.md.
-- Publish readiness (LOU-D49): `npm run pack-smoke` (scripts/pack-smoke.ts, a CI job) packs the SDK and `create-lousho-agent`, checks the tarball (no `.env`, tests or secret-looking strings; entry count and size caps), runs `npm publish --dry-run` for both (nothing is published), installs the tarballs plus peers from the registry into a fresh project and verifies ESM and CJS loads of every `exports` entry, a mock-model agent turn, the `lousho` bin (`--help`, `doctor`) and `tsc` with `moduleResolution` bundler and node16.
-- One event system (LOU-D41): `AgentEvent` listeners for callers who do not iterate a run. `createAgent({ onEvent: (event: AgentEvent) => void })` and the new `ExecuteOptions.onAgentEvent` (also taken by `AgentExecutor.stream()` and `resumeAfterApproval()`) are called synchronously with every `AgentEvent` of the run, on `send()` / `execute()` as on `stream()`, sub-agents' events included: the same events in the same order as the stream yields (a non-streamed run generates each model step whole, so its text is one `text.delta` per step). A run with a listener also reports hook events, permission decisions, budgets and guardrails to it when it is not streamed. A non-streamed `resumeAfterApproval()` with a listener now reports the decided call (`run.start`, `tool.start`, `tool.done`) like a streamed one. See docs/streaming.md#listening-without-iterating.
-- Reasoning (LOU-V13): new `reasoning` option on `createAgent()`, `send()` / `stream()` (per call, overriding the agent's), `ExecuteOptions` and `GenerateOptions`: `'none' | 'minimal' | 'low' | 'medium' | 'high'` or `{ effort?, budgetTokens?, summary?: 'auto' | 'none', force? }` (types `ReasoningOption`, `ReasoningEffort`, `ReasoningSettings`). The built-in providers send it through `providerOptions` on `ai` 4.3 and 6/7: OpenAI `reasoningEffort` (+ `reasoningSummary`), Anthropic `thinking: { type: 'enabled', budgetTokens }` (effort table 1024 / 2048 / 8192 / 24576 tokens), Ollama `think` (`ollama-ai-provider-v2` only; ignored with one warning on `ai` 4), and OpenRouter's unified `reasoning` body field (`effort` or `max_tokens`). It is only sent to model families known to accept it (`force: true` overrides); `'none'` sends nothing. New events `reasoning.start`, `reasoning.delta` (`text`) and `reasoning.done` (`text`, `tokens?`) in the `AgentEvent` union, emitted inside the step before its first text or tool call, from `ai` v4 `reasoning` parts and v6/v7 `reasoning-start/delta/end`; `ExecutionResult.reasoning` holds the run's reasoning text and `GenerateResult.reasoning` a call's blocks (new type `ReasoningBlock`); new stream chunk types `reasoning-delta` / `reasoning-end` (`StreamChunk.reasoning`). Reasoning is not written to the transcript as text; an assistant tool-call turn keeps Anthropic's signed or redacted thinking blocks in the new `Message.reasoning`, which the Anthropic provider sends back unmodified (it survives checkpoints and resumes). The UI reducer keeps `UIMessage.reasoning`, `toUIMessageStream()` emits `reasoning-start` / `reasoning-delta` / `reasoning-end`, `lousho acp` sends `agent_thought_chunk`, `lousho chat` prints reasoning dimmed, and `chat` spans carry `lousho.usage.reasoning_tokens`. Cassettes record the reasoning chunks. See docs/reasoning.md.
-- Tools know their session (LOU-D23.2): `ToolExecutionContext.sessionId` is now set whenever the run has one: `AgentExecutor.execute({ sessionId })`, `send({ sessionId })`, every `agent.session()` turn (the session id; a checkpointed turn's own `<id>.turn-<n>`, as hooks see it), approval resumes (the paused run's), and sub-agents (`<parent session>/<task tool call id>`). A session turn's run now carries the session id even without a checkpoint store (no checkpoint is written), so hooks and the `invoke_agent` span's conversation id see it too.
-- Hardened Slack and Discord channels (LOU-P5.2): `approvers` (a list of platform user ids, or `(user: { id, name?, roles? }, { toolName, input, sessionId }) => boolean | Promise<boolean>`) says who may click Approve / Deny (a refused click gets an ephemeral "not allowed" and the approval stays pending); `onError(error, { channel, stage, sessionId? })` on both channels, on `mountChannels()` and on `defineChannel()` receives failures after the acknowledgment (reply delivery, a failed turn, an approval continuation; default `console.error` with channel, stage, session and SDK error code, never a token) and a failed turn tells the user so; `mountChannels({ onDecision })` reports who decided; `parse` gets a third `ctx` argument (`ChannelContext`: pending approval, session id, `hasSession`) and a `{ decision }` may carry `inbound` and `approver`. Pending approvals now resolve from the click itself and the Slack 'active thread' check asks the session store, so both survive a restart. Slack: the clicked message is replaced with the outcome (buttons removed) and direct messages (`message.im`, scope `im:history`) are sessions keyed on the DM channel. See docs/channels.md.
-- Resumable sub-agent tasks (LOU-Y6): every `task` result ends with a `taskId` (the footer is now `[sub-agent '<name>': N step(s), finish reason '<reason>', taskId 'task_1']`; a remote one gains `, taskId '...'` too), and `task` takes optional `taskId` and `mode: 'new' | 'resume' | 'fork'` (default `new` without a `taskId`, `resume` with one). `resume` continues that sub-agent with its transcript and the new prompt as the next user turn; `fork` starts a new task (new `taskId`) from a copy of it and leaves the original alone. Conversations are kept per lead session in the agent's `store.sessions` (new `SubagentOptions.sessions`, set by `createAgent({ store })`) for lead runs with a `sessionId` (checkpointed `send()` and session turns), under a key hashed from the lead session and the taskId, so they survive a restart and cannot be reached from another session; other runs keep them in memory for the run. Background tasks share the ids (a background task's id is now `task_<n>` counted with the synchronous ones): a finished one can be resumed, a running one is refused with the new `LOUSHO_SUBAGENT_TASK_BUSY`; an unknown, foreign or other sub-agent's id gets the new `LOUSHO_SUBAGENT_TASK_NOT_FOUND`, both as the structured tool error. An approval inside a resumed child pauses and resumes the lead as before (streamed or not), and a resumed child's usage counts toward the lead like a fresh call. `remoteAgent()` tasks resumed by `taskId` continue in the same remote session (LOU-Y7.2; `RemoteSubagent.run()` takes `sessionId` and `taskId`); remote approvals are still not proxied, but a task whose remote run paused can be continued once the approval was decided on the remote agent. The model-facing `task` description and the sub-agents prompt block say how to continue a task. See docs/sub-agents.md#continuing-a-task.
-- Agent-directory and spec builds keep optional peers external, and the node server runs spec cron triggers (LOU-P8.3): `lousho build --target=node-server|docker` leaves every optional peer of the SDK (read from its `peerDependenciesMeta`) out of the bundle, replacing the hand-kept `dockerode` / `ollama-ai-provider-v2` list, so a build no longer needs peers the agent does not use; a spec's `{ type: 'cron' }` triggers now start on the built server (and are validated at build time), as on the Cloudflare Worker target. See [Deployment](docs/deployment.md#optional-peers-in-node-and-docker-builds).
-- Agent fingerprint on resume (LOU-W9.2): every checkpoint and approval snapshot now carries `agentFingerprint` (new type `AgentFingerprint`: the model id, each tool's name with a hash of its JSON input schema, a hash of the instructions, and a SHA-256 prefix over them, via Web Crypto; functions are ignored), and a resume compares it with the resuming agent's before any model call or tool runs. New option `onAgentDrift: 'warn' | 'error' | 'ignore'` (type `AgentDriftMode`) on `createAgent()`, `AgentExecutor.execute()` and `resumeAfterApproval()`: `'warn'` (default) emits the new `agent.drift` event (`AgentDriftEvent`: `model?`, `toolsAdded`, `toolsRemoved`, `toolsChanged`, `instructions`) and a `console.warn`, `'error'` rejects with the new `LOUSHO_AGENT_DRIFT` and leaves the checkpoint (or the pending approval) untouched. A pending tool call whose tool no longer exists always rejects with the new `LOUSHO_RESUME_TOOL_MISSING`. Works for crash resume, `session.resume()` and approval resume, streamed or not; old checkpoints and snapshots have no fingerprint and resume unchecked. A sub-agent's nested approval snapshot carries its own fingerprint, but only the top-level agent is compared. `resumeAfterApproval()`'s options take `currentAgent` (set by `createAgent()`) so instructions can be compared. See docs/durable-execution.md#resuming-with-a-changed-agent.
-- Docker sandbox network allowlists are enforced through the credential broker (LOU-X12.2): `new SubprocessSandbox({ network: { allow }, broker })` creates (or reuses, by `networkName`) an internal Docker network (`Internal: true`, label `com.lousho.sandbox=egress`), has the broker listen on its gateway address for that subnet only, and starts each container on it with `HTTP_PROXY`/`HTTPS_PROXY` pointing there, so the broker (allowlist: its rule hosts plus `allow`) is the container's only route out. New `sandbox.close()` stops the listener and removes the network it created. New `broker.listen({ host, clients, allow? })` adds a listener on another address that drops peers outside the `clients` subnet; the broker still listens on loopback only by default. Enforced on Docker Engine 25.0.5+ for Linux with the agent on the same host; Docker Desktop, rootless Docker, a remote daemon, a non-internal reused network and older Engines are refused with the new code `LOUSHO_SANDBOX_EGRESS_UNSUPPORTED` (no container is started). Without a `broker`, `{ allow }` still means no network. See docs/workspace-tools.md.
-- The Docker sandbox honors cancellation (LOU-U23): `SubprocessSandbox.run()` takes `signal` (`SandboxRunOptions`). When it aborts, the container is killed and force-removed (errors from an already stopped or removed container are ignored) and `run()` rejects with an `AbortError`, like `NoopSandbox`; an already-aborted signal starts no container; a timeout uses the same cleanup. `SandboxShell` passes the tool's abort signal down, so a cancelled `shell` call stops its container (it used to run until the timeout) and reports `aborted: true`. See docs/workspace-tools.md.
-- Schedules on Cloudflare Workers (LOU-P9): the `cloudflare-worker` target writes the spec's `{ type: 'cron', cron, input, name?, timezone? }` triggers (deduplicated) to `wrangler.toml` as `[triggers] crons = [...]`, and the generated Worker exports `scheduled(controller, env, ctx)`, which runs every trigger whose expression equals `controller.cron` as an agent turn inside `ctx.waitUntil()`, in session `schedule:<name>` (visible in the KV store when bound). A failing trigger is logged with `console.error` (name and error code) and never stops the others. The build fails with `LOUSHO_SCHEDULE_INVALID` naming the trigger for what Cloudflare would not fire: a `timezone` (crons are UTC), a seconds field or `@daily` shortcut, a numeric day-of-week (Cloudflare counts 1 as Sunday). New `handleScheduled(agent, schedules, controller, ctx)` (root and `deploy-runtime-worker`) wires `defineSchedule` schedules to a hand-written Worker's `scheduled()`. `startSchedules` shares its fire step with it. See docs/schedules.md#on-cloudflare-workers.
-- `ai` v6 and v7 as peers (LOU-D28d): `peerDependencies` now accept `ai` `^4.3.19 || ^6.0.0 || ^7.0.0` and `@ai-sdk/openai` / `@ai-sdk/anthropic` `^0.0.42 || ^1.0.0 || ^3.0.0 || ^4.0.0` (still optional), plus the new optional peer `ollama-ai-provider-v2` `^2.0.0 || ^3.0.0 || ^4.0.0`, so a project on the current `ai` major installs without peer conflicts. Pairings: `ai` 4 with `@ai-sdk/*` 0.0.x/1.x and `ollama-ai-provider` 1.x; `ai` 6 with `@ai-sdk/*` 3.x and `ollama-ai-provider-v2` 2.x/3.x; `ai` 7 with `@ai-sdk/*` 4.x and `ollama-ai-provider-v2` 4.x. A missing provider package's `MissingPeerDependencyError.installCommand` names the version for the installed `ai` major (`npm install @ai-sdk/openai@^4.0.0` on `ai` 7; unchanged on `ai` 4). `OllamaProvider` loads `ollama-ai-provider-v2` on `ai` 6/7; that package needs zod 4, which the SDK does not support yet, so its install hint says so and Ollama stays on `ai` 4 for now. `lousho doctor` checks provider packages against the installed `ai` major and flags a mismatched pair (e.g. `ai` 7 with `@ai-sdk/openai` 1.x) with the version to install; a missing or unsupported `ai` gets `npm install ai@^7.0.0`. `lousho init` / `npm create lousho-agent` scaffold `ai@^7.0.0` with `@ai-sdk/openai@^4.0.0` / `@ai-sdk/anthropic@^4.0.0` for OpenAI and Anthropic, and keep `ai@^4.3.19` for Ollama (zod 4) and OpenRouter (`@ai-sdk/openai` 2+ defaults to the Responses API, not yet verified there). The hint of `resolveProvider()`'s rare synchronous missing-peer error lists the command for each `ai` major. See [Installation](docs/installation.md#provider-packages).
-- `lousho add` (LOU-D50): `lousho add <name> [--registry <url-or-path>] [--dir <agent-dir>] [--yes] [--overwrite] [--dry-run]` installs a tool, skill, channel, schedule or memory slot from a static JSON registry (an index plus one document per item that carries the file contents) into an agent directory as source you own; `lousho add --list` prints the index. The registry comes from `--registry` or `LOUSHO_REGISTRY` (there is no hosted registry yet). It prints the item's permission manifest (hosts, env vars, filesystem, exec, whether its tools ask for approval) and the files first and asks for confirmation (`--yes` skips it; a non-interactive stdin without `--yes` refuses; `--dry-run` writes nothing). Paths must be relative, inside the folder of the item's type and inside the agent directory (no `..`, absolute paths, drive letters, backslashes or symlink escapes), files and items have size caps, existing files need `--overwrite`, fetches time out and only `http(s)` and local paths are read; nothing from a registry is executed and `dependencies` are only printed as an `npm install` line. New error codes `LOUSHO_REGISTRY_UNREACHABLE`, `LOUSHO_REGISTRY_ITEM_NOT_FOUND`, `LOUSHO_REGISTRY_INVALID`, `LOUSHO_REGISTRY_UNSAFE_PATH`, `LOUSHO_REGISTRY_FILE_EXISTS`. See docs/registry.md.
-- Checkpoint history for `KVCheckpointStore` and Agent Forge's file store (LOU-D43.2): `KVCheckpointStore` (and `KVStore`, with the new `historyLimit` option) keeps the bounded per-session history `memoryStore()` keeps, as one index key (`<prefix><sessionId>#history`) and one key per entry (`<prefix><sessionId>#history/<id>`) next to the unchanged latest-checkpoint key, so `agent.fork()`, `compareTrajectories()` and time travel work for Worker-deployed agents; a store written before this change still loads. A save now makes one `get` and two `put`s more (`historyLimit: 0` turns the history off), and two concurrent saves of one session can lose an index update (KV has no transactions). Agent Forge's `FileCheckpointStore` reads a partially written history file as empty and writes its files atomically. The history contract suite now runs against `KVCheckpointStore` too. See docs/durable-execution.md#checkpoint-history.
-- Hook outcomes (LOU-X3): a `preToolCall` hook may return `{ deny: reason }` (the call does not run; the model gets the same `kind: 'denied'` tool error as a `needsApproval` deny, streams see `tool.error`, and `onPermissionDecision` / `permission.decision` record `decision: 'deny'` with the new `hook` field and `reason`), `{ result: value }` (the call does not run; `value` is its result) or `{ input: args }` (the call runs with `args`, validated against the tool's schema again; a mismatch is a `kind: 'validation'` tool error naming the hook). A `postToolCall` hook may return `{ result: value }` to replace the result the model sees. Pre-hooks run in registration order: the first deny or result skips the later ones, inputs chain. A replaced result is marked `replacedByHook` on the `tool.done` event, the `ToolCallOutcome` / `tool-result` event and the transcript's `tool` message `metadata`. Hooks still run first (after argument validation, before permission rules, tool guardrails and `needsApproval`), so the approval sees the hook's input; on a resumed approved call the pre-hooks run again and an `{ input }` that differs from the approved input is refused. Sub-agents inherit the outcomes. Hooks that return nothing type-check and behave as before; `HookRegistry.runPreToolCall()` now resolves to a `PreToolCallDecision` and `runPostToolCall()` to the name of the replacing hook (new types `PreToolCallOutcome`, `PostToolCallOutcome`, `PreToolCallDecision`). A hook that throws still rejects the run. See docs/api-overview.md#hook-outcomes.
-- `lousho acp` (LOU-Z6): `lousho acp <spec.yaml|spec.json|agent-dir|agent.ts> [--model provider/model]` serves an agent over the Agent Client Protocol (v1) on stdio, so Zed and other ACP editors can run it as an external agent; stdout carries only JSON-RPC lines (the agent's `console.log` goes to stderr). It implements `initialize`, `session/new`, `session/prompt` (text and `resource_link` blocks) and `session/cancel`, streams `session/update`s (`agent_message_chunk`, `tool_call`, `tool_call_update`), asks `session/request_permission` (Allow / Reject) when a tool needs approval and streams the continuation, and maps finish reasons to stop reasons (`max-steps` to `max_turn_requests`, `budget-exceeded` / `length` to `max_tokens`, `guardrail` to `refusal`, a cancel to `cancelled`). One ACP session is one SDK session. An `ask_question` pause ends the turn with the question as the agent's message; the next prompt answers it. A failed run answers a JSON-RPC error whose `data.code` is the SDK error code. The protocol core is exported as `serveAcp(agent, { input, write, store? })` (new type `ServeAcpOptions`), transport-independent. Not supported yet: `session/load`, the client's `fs/*` and `terminal/*` methods, images, audio and embedded resources, `plan` and thought chunks. See docs/acp.md.
-- Agent directories deploy and serve with their schedules and channels (LOU-P8.2): `lousho build <agent-dir> --target=node-server` (and `docker`; the path may also be `--agent`) builds a directory into a server whose entry calls `resolveAgentDir()` and `createDeployedServer(agent, { schedules, channels })`, so the deployed process starts the `schedules/` and mounts the `channels/` under `/channels` and logs which it found. The code files are pre-bundled by the existing tsup step into `dist/agent/**.js` (one ESM build sharing one SDK copy; `dist/` is marked ESM) and the rest of the directory is copied, so nothing needs a TypeScript loader at run time; spec builds are unchanged. `lousho dev <agent-dir>` mounts the directory's channels and starts its schedules, swapping both on hot reload (old schedules stopped first); `--no-schedules` starts none. The deploy runtime also exports `createAgent`, `resolveAgentDir` and `storeFromEnv`. The Cloudflare Worker target is unchanged (P9). See docs/agent-directories.md#deploy-it-with-lousho-build.
-- Route handler (LOU-P4): `createRouteHandler(agent, { basePath?, auth?, uiMessageStream? })` returns `{ GET, POST, handler }`, Fetch handlers (`(request: Request) => Promise<Response>`) that serve the deployed session API under `basePath` (default `/api/agent`; trailing slash accepted, other paths 404) from a Next.js App Router `app/api/agent/[[...path]]/route.ts`, SvelteKit `+server.ts`, Hono or Bun.serve, with no framework or `node:*` import. `auth` is a bearer token or a `(request) => boolean | Promise<boolean>` (default none: a public route needs one; `GET /health` stays open). `useLoushoAgent({ url, approvalsUrl })` works against it (`POST <basePath>` with `{ input, sessionId? }`, `POST <basePath>/approvals/:id`), and `uiMessageStream: true` adds `POST <basePath>/ui` for `useChat`. `hasBearerToken` in `src/server/fetchRoutes.ts` is now exported for it. See docs/nextjs.md.
-- AI SDK UI stream (LOU-P1): `toUIMessageStream(run)` maps a run's events to the Vercel AI SDK's UI message stream chunks (`start`, `start-step`, `text-start` / `text-delta` / `text-end`, `tool-input-start` / `tool-input-available` / `tool-output-available` / `tool-output-error`, `finish-step`, `error`, `finish` with the AI SDK finish reason), and `toUIMessageStreamResponse(run, init?)` returns the SSE `Response` (`data: [DONE]`, header `x-vercel-ai-ui-message-stream: v1`) for a route handler, so `useChat` can render a Lousho run. An approval pause or `ask_question` is a `data-lousho-approval` part (`approvalId`, `toolCallId`, `toolName`, `input`, `kind?`, `question?`); usage and the run's own finish reason are in the `finish` chunk's `messageMetadata`. `fromUIMessages(messages, { lastUserOnly? })` converts the `UIMessage[]` `useChat` posts (text, image and file parts; others ignored) to an `AgentInput`. Own structural chunk types (`LoushoUIMessageChunk`, `UIMessageLike`, ...), no `ai` import and no `node:*`, so it also runs on Workers; exported from the package root (a dedicated subpath can follow). See docs/ai-sdk-ui.md.
-- Approval policies (LOU-X8): a `needsApproval` function may return (or resolve to) `'approve'`, `'deny'`, `'ask'` or `{ deny: reason }` besides a boolean (`true` is `'ask'`, `false` is `'approve'`; new type `ApprovalOutcome`), and gets a second argument `{ toolName, toolCallId, sessionId?, messages }` (new type `ApprovalCheckContext`). A deny does not pause: the call is not run, the model gets a `kind: 'denied'` tool error with the reason, streams see `tool.error`, and `onPermissionDecision` / `permission.decision` record `decision: 'deny'` with the new `reason` field (no `rule`); the audit entry is now reported once the call is decided (after tool guardrails) instead of before them. New helpers `always()`, `never()` and `once({ per?: 'tool' | 'args' })` (with type `ApprovalPolicy`): `once()` asks the first time a tool is called in a session and runs later calls once a human approved one (a rejection is not remembered; `per: 'args'` keys on the arguments' hash). The memory is the approved call's `tool` message (`metadata.approval`, set by `resumeAfterApproval()` and its streamed form), so it persists with sessions, checkpoints and approval snapshots and survives a resume in another process. A `permissions` `deny` rule wins; an `allow` or `ask` rule replaces the tool's ask but not its deny (see Changed); the tool's outcome applies when no rule matches. Existing boolean functions type-check and behave as before; a test asserting `needsApproval` was called with exactly one argument now sees the context too. See docs/approvals.md#approve-deny-or-ask.
-- Approval continuations stream live (LOU-D32.2): `POST /chat/:sessionId/approvals/:id` (node server, Cloudflare Worker, `lousho dev`) now streams the continuation from `agent.approvals.streamResolve()` / `streamAnswer()` instead of replaying it after the turn ends; `createAgentRunner`'s `approve()` / `reject()` / `answer()` (React, Vue, Svelte) read that SSE stream event by event (an `ApprovalOutcome` JSON from an older server still works), and `lousho chat` prints the continuation as it streams. The UI reducer maps a streamed `tool.error` named `ToolRejectedError` to a `rejected` tool call. A second pause arrives as `approval.requested`. The approvals route has always answered with SSE, so no client opt-in was added.
-- `session.compact()` and `session.clear()` (LOU-W8): `await session.compact({ strategy?, protectedTokens?, contextWindow?, signal? })` compacts the session's transcript now, whatever its size, with the given strategy, else `agent.session({ compaction })` (new option, the value of `createAgent({ compaction })`), else by pruning old tool results; it saves the result through the session's store and resolves to `{ messagesBefore, messagesAfter, tokensBefore, tokensAfter, strategy, error? }`. `clear()` (which already existed and forgot the conversation) now emits `context.cleared` (new `ContextClearedEvent` in the `AgentEvent` union) and rejects with `LOUSHO_SESSION_AWAITING_APPROVAL` when a durable turn waits on an approval; it keeps the session id. New `session.on(listener)` receives `compaction.start` / `compaction.done` (which gain an optional `trigger: 'manual'`) and `context.cleared`. Both reject with the new `LOUSHO_SESSION_BUSY` while a turn is in flight; `compact()` also with `LOUSHO_SESSION_TURN_PENDING` for an interrupted durable turn. `lousho chat` gains `/compact` and `/clear`. See docs/compaction.md#compacting-a-session.
-- Discord channel (LOU-P6): `discordChannel({ publicKey, applicationId, botToken?, name?, fetch? })` serves Discord's HTTP Interactions endpoint through `mountChannels()` (Web Crypto and `fetch` only, Worker-safe, no gateway, no new dependency). It verifies `X-Signature-Ed25519` / `X-Signature-Timestamp` (Ed25519 over `timestamp + body`, 401 otherwise) and answers `PING` with `PONG`. A slash command (`/ask prompt:<text>`) is acknowledged at once with a deferred response; its session is keyed on guild + channel (+ thread), and the reply edits the original response, with text over 2000 characters continued in follow-up messages. A tool approval is posted with Approve / Deny buttons and resolved by the click; an `ask_question` is answered by the next `/ask` in the channel. See docs/channels.md#discord.
-- Streaming resume after an approval (LOU-V14): `streamResumeAfterApproval(decision, approvalStore, toolRegistry, provider, options?, checkpointStore?)` takes `resumeAfterApproval()`'s arguments and returns an `AgentRun` whose `result` is what `resumeAfterApproval()` returns. Its events are `run.start`, the decided call's `tool.start` / `tool.done` (`tool.error` for a rejection), then the continuation's events as in a fresh `stream()` run; a further pause ends it with `approval.requested`. Abort, `enqueue()` and `steer()` work as on any run, and the approval can be resolved in another process. `createAgent()` agents get `agent.approvals.streamResolve(decision, { signal })` and `streamAnswer({ id, answer }, { signal })` (a pause made in a session continues in it, `run.done` after the transcript is saved; a dynamic agent keeps the model the paused run used). Also new: the `ResumeRequest` type and `resumeRequest(request)` (`resumeAfterApproval()` with one object argument). Additive: `resolve()`, `answer()` and `resumeAfterApproval()` are unchanged. See docs/streaming.md#streaming-after-an-approval.
-- Credential broker (LOU-X12): `createCredentialBroker({ rules, allow?, allowPrivate?, port?, host?, pathFormScheme? })` starts a host-side HTTP forward proxy (Node-only, on an ephemeral `127.0.0.1` port by default) and resolves to `{ url, env, baseUrl(host), close() }`. `rules` map a host (exact or `*.suffix`) to headers to inject, as strings or per-request functions, so a command the model runs can call an authenticated API without the token entering its environment: pass `broker.env` (`HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY`, both cases) to `NodeWorkspace` or `SandboxShell`'s `env`. Hosts outside the rules and `allow` get a 403 without a connection; hosts resolving to loopback, link-local or private addresses are refused unless in `allowPrivate`; a client `Authorization` header for a brokered host is replaced; hop-by-hop headers are dropped. Injection covers plain-HTTP requests and the `/__broker/<host>/<path>` form (forwarded to `https://<host>/<path>`, returned by `baseUrl(host)`); HTTPS `CONNECT` tunnels are allowlist-checked and passed through untouched (no TLS interception). `SubprocessSandbox`'s `network: { allow }` still fails closed: routing containers through the broker is LOU-X12.2. New types `CredentialBroker`, `CredentialBrokerOptions`, `BrokerHeaderValue`. See docs/workspace-tools.md#credential-broker.
-- Memory in agent directories (LOU-W6.3): `memory/*.ts|js|mjs` files default-export a memory slot (`defineMemory()`, or the same options without a `name`; name = file name unless set). Unlike schedules and channels they are part of the agent: `loadAgentDir()` passes them to `createAgent({ memory })`, `resolveAgentDir()` lists them in `manifest.memory`, and a `memory` override is merged by name (the override wins a clash). A bad file fails with the new `LOUSHO_MEMORY_INVALID` naming the file. A directory without `memory/` is unchanged. See docs/agent-directories.md#memory.
-- Channels in agent directories (LOU-P7.2): `channels/*.ts|js|mjs` files default-export a channel (`defineChannel()` or a built-in factory; name = file name unless set); `resolveAgentDir()` returns them as `channels` and `manifest.channels`, and a file that exports no channel fails with the new `LOUSHO_CHANNEL_INVALID` naming the file. `createDeployedServer(agent, { channels })` mounts them under `/channels` next to the chat routes. `loadSchedules()` and `loadChannels()` share one loader (schedule files that do not export a schedule now throw an `SDKError` with `LOUSHO_SCHEDULE_INVALID`, same message). `lousho dev` and the Cloudflare Worker target do not mount them yet. See docs/agent-directories.md#channels.
-- `serveMcp` annotations (LOU-Z5.2): `defineTool({ annotations })` (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`, `title`; stored as `metadata.mcp.annotations`) is sent in `tools/list` verbatim, and a tool with `needsApproval` is advertised `readOnlyHint: false, destructiveHint: true` (never read-only). An unannotated tool sends none. A Lousho agent consuming the server therefore runs read-only tools without an approval pause, pauses for `needsApproval` ones and keeps asking for unannotated ones. The built-in `read_file`, `list_dir`, `glob`, `grep`, `todo_read`, `current_date` and `day_name` tools are marked read-only. See docs/configuration.md#annotations.
-- Svelte store (LOU-P3): new `@lousho/build-ai-agent/svelte` subpath with `loushoAgent(source, options?)`. It returns a Svelte store (`subscribe(run) => unsubscribe`, so `$agent` works in Svelte 4 and 5) whose value is the same state as the React hook and the Vue composable (`messages`, `status`, `pendingApproval`, `error`, `usage`, `lastEvent`), plus `send()`, `stop()`, `approve()`, `reject()`, `answer()` and `reset()`. The run in flight is aborted by `stop()` and when the last subscriber unsubscribes. The store contract is implemented by hand: the entry imports nothing from `svelte`, so there is no new peer dependency. See docs/svelte.md.
-- Per-run dynamic config (LOU-V15): `createAgent()`'s `model`, `instructions` / `prompt` and `tools` each also take a function of the run, `(ctx) => value | Promise<value>` (new types `PerRun<T>` and `RunConfigContext` = `{ sessionId?, input, metadata? }`), resolved once at the start of each run and of each session turn, before the first model call. `fallbackModels`, `retry`, `projectInstructions`, memory, MCP tools, sub-agents, permissions, approvals and guardrails apply to the resolved values; a dynamic agent used as a sub-agent resolves with the task prompt as `input`. `session.send()` / `session.stream()` gain the `metadata` option (`send()` / `stream()` already had it, and now pass it to these functions too). A function that throws fails the run with the new `LOUSHO_CONFIG_RESOLVER_FAILED` (`field` names the option, `cause` is the error); a session keeps its transcript. A run paused for approval stores its `ctx` and resolved model in the approval snapshot (`agent.metadata.loushoRunConfig`): resuming it uses that model and re-resolves the tools with the same `ctx`; a crash resume from a checkpoint resolves with `input: []`. Static options behave and type as before. `SessionRunner` / `SessionStreamRunner` take an optional fourth `call` argument (new type `SessionTurnCall`). See docs/api-overview.md#dynamic-config.
-- Vue composable (LOU-P2): new `@lousho/build-ai-agent/vue` subpath with `useLoushoAgent(source, options?)` for Vue 3. It takes the same sources and options as the React hook (either may be a `ref`, read when a turn starts) and returns `messages`, `status`, `pendingApproval`, `error`, `usage` and `lastEvent` as read-only refs, plus `send()`, `stop()`, `approve()`, `reject()`, `answer()` and a new `reset()` (aborts, forgets the in-process session, clears the chat). The run in flight is aborted by `stop()` and when the owning scope is disposed (`onScopeDispose`: component unmount, `effectScope().stop()`). `vue` (`^3`) is an optional peer dependency, loaded by no other entry. To share the logic, the reducer and the stream parser moved from `src/react/` to a framework-neutral `src/ui/`, together with the run logic extracted from the React hook (`createAgentRunner()`); the `./react` exports are unchanged, and the reducer gains an additive `ui.reset` action. See docs/vue.md.
-- One flag parser for the `lousho` CLI (LOU-U21): every command (`dev`, `chat`, `eval`, `build`, `mcp`, `doctor`, `studio`; `init` already did) parses its flags with `node:util` `parseArgs` in strict mode through `src/cli/args.ts`. `--flag value` and `--flag=value` work everywhere, `--` ends the flags, `-h` / `--help` prints the usage and exits 0, and an unknown flag, a flag without its value or an extra argument fails with `LOUSHO_CONFIG_INVALID` and the command's usage as the hint. **Behaviour change (migration):** `dev`, `studio`, `mcp`, `build` and `doctor` used to ignore unknown flags, and a flag missing its value could take the next flag or a prefix match (`--portx 1` read as `--port`); they now fail with exit 1 and the usage line, so remove typos from scripts. A value that starts with `-` must be written `--flag=-x` (a bare `--flag -x` is a missing value); `--port` must be an integer from 0 to 65535 for `dev`, `studio` and `mcp`; `dev`, `mcp` and `doctor` reject a second path; `studio --prod --dev` is rejected instead of preferring `--prod`. `lousho dev` and `lousho studio` parsing moved from `bin/lousho.js` into `src/cli/dev.ts` / `src/cli/studio.ts` (`parseDevArgs`, `runDev`, `parseStudioArgs`, `runStudio`). See docs/cli.md.
-- `sqliteMemory(store, { maxItems? })` (LOU-W6.2, exported from `@lousho/build-ai-agent/sqlite`) keeps `defineMemory` slots in the agent's `SqliteStore` file: a new `memory_items` table (migration 3, one JSON array per scope key, with the same serialization, `maxItems` and query rules as `fileMemory`). An existing database gains the table on open and keeps its sessions and checkpoints. The memory provider contract tests now run against the in-memory, file and SQLite providers. See docs/memory.md#sqlite.
-- Slack channel (LOU-P5): `slackChannel({ signingSecret, botToken, name?, fetch? })` (new export, with types `SlackChannelOptions`, `SlackChannelEvent`, `SlackThread`) serves a Slack app's Events API and interactivity requests through `mountChannels()`. It verifies the `v0` request signature with Web Crypto (no `node:*` import; the timestamp and header checks are shared with `verifySlackSignature()`), answers the `url_verification` challenge, and acknowledges every request before the turn runs. Each Slack thread is one session (team + channel + thread root `ts`): a mention starts or continues it, and later messages in a thread the bot was mentioned in continue it. Retries (`X-Slack-Retry-Num`) and bot messages are skipped. Replies go to the thread with `chat.postMessage` over `fetch`; a tool approval is posted as Approve / Deny buttons whose click resumes the session, and an `ask_question` as text answered by the next thread message. The channel contract gains two additive hooks for this: `parse(req, respond)` may call `respond` to answer the request before the turn runs, and may return `{ decision }` (new type `ChannelDecision`; `ChannelApprovalDecision` now lives in `defineChannel.ts`, same public export) to resolve a pause instead of starting a turn. See docs/channels.md#slack.
-- Remote sub-agents (LOU-Y7): `remoteAgent({ url, auth?, name?, description?, headers?, fetch? })` (new export, with types `RemoteAgentOptions` and `RemoteSubagent`) makes a deployed agent usable wherever a local sub-agent is: in `createAgent({ subagents })` records and `SubagentCatalog.resolve()`, delegated to by the `task` tool and by `background: true` tasks. Each task opens a fresh session on the remote agent over `POST <url>/chat` (bearer `auth`: a string or a function, called per task), reads the SSE stream to the end and returns the remote agent's final text; the lead run's abort signal aborts the request. Failures (network, 401 or other non-2xx, malformed stream, remote run error) are structured tool errors with the new code `LOUSHO_REMOTE_AGENT_FAILED`, and the token never appears in errors or events; a remote run that pauses for approval fails with `LOUSHO_SESSION_AWAITING_APPROVAL` naming the remote session (proxying approvals is a follow-up). Worker-safe (`fetch` only). See docs/sub-agents.md#remote-sub-agents.
-- Eval against a deployed agent (LOU-D47): `lousho eval --url <baseUrl> [--token <bearer>]` (token also from `LOUSHO_EVAL_TOKEN`) runs every case of the trajectory eval files against a deployment (node server or Cloudflare Worker) instead of the in-process agent: one remote session per case over `POST /chat { sessionId, input }`, the SSE stream read to `run.done` and turned into the usual result (tool calls, reply, finish reason, steps, usage), so checks, scorers, `t.judge()`, the summary and `--junit` work unchanged. A check that needs data the stream lacks (`maxTokens` without usage) fails and names what is missing. Programmatic equivalent: `defineEval({ target: remoteTarget({ url, auth?, fetch? }) })` (new `remoteTarget()`, `EvalTarget`; `agent` is now optional when a `target` is given, and `AgentSource` also accepts any `{ send() }`). `--url` with `--record` / `--replay` / `--drift` is rejected with `LOUSHO_CONFIG_CONFLICTING_OPTIONS`; an unreachable deployment, a non-2xx answer or a truncated stream fails the case with the new `LOUSHO_REMOTE_REQUEST_FAILED`, and 401 with `LOUSHO_REMOTE_UNAUTHORIZED`. The token never reaches output or reports. See docs/evals.md#run-evals-against-a-deployment.
-- Schedules (LOU-P8): `defineSchedule({ cron, timezone?, name?, prompt | run })` declares a cron schedule (a `prompt` sent to the agent as a new turn, or `run({ agent, firedAt, name })`); an invalid cron expression, or not exactly one of `prompt`/`run`, throws the new `LOUSHO_SCHEDULE_INVALID` at definition time. An agent directory's `schedules/*.ts|js|mjs` files default-export one each (name = file name unless set); `resolveAgentDir()` returns them as `schedules` and `manifest.schedules`. `startSchedules(agent, schedules, { now?, setTimer?, onError? })` runs them with injectable clock and timers, isolates errors, skips a fire while the previous one runs and returns `stop()`; `createDeployedServer(agent, { schedules })` starts them on listen and stops them on close. The Cloudflare Worker target is not covered yet. See docs/schedules.md.
-- Channels (LOU-P7): `defineChannel({ name, verify?, parse, reply, onApproval?, sessionId?, stream? })` describes one surface: `verify` authenticates a request (`false` or `{ ok: false }` answers 401), `parse` maps it to `{ sessionKey, input, metadata?, replyTo }` (or `null` to acknowledge it without a turn), `reply` delivers the agent's reply (with `stream: true`, also partial text as the model writes) and `onApproval` renders a pause (default: a text prompt through `reply`). `mountChannels(agent, channels, { store, basePath })` returns a framework-free `(req, res)` handler, in the style of the `/chat` routes, that serves `POST <basePath>/<name>` (verify -> parse -> a turn in session `` `${name}:${sessionKey}` `` -> reply; turns of one session run one at a time) and `POST <basePath>/<name>/approvals/<id>` (`{ approved, note? }` or `{ answer }`); `handler.resolveApproval()` decides a pause from code (e.g. a button callback) and replies through the same channel. Built in: `httpChannel()` (JSON `{ sessionKey, input }` in, `{ sessionId, text, finishReason, approval? }` out) and `webhookChannel({ secret })` (`WebhookTriggerAdapter`'s behaviour; the adapter now delegates its auth and parsing to it, unchanged for callers). Slack and Discord channels are LOU-P5 / LOU-P6. See docs/channels.md.
-- Cloudflare Worker parity (LOU-D51): the `cloudflare-worker` target now serves the same API as the node server: `POST /chat { sessionId, input }` streamed as SSE, history per session, `GET /chat/:sessionId`, `POST /chat/:sessionId/approvals/:id` and `GET /health`; the deprecated `POST /chat { message, sessionId? }` still works and still checkpoints under `sessionId`. `LOUSHO_API_TOKEN` (a Worker secret: `wrangler secret put LOUSHO_API_TOKEN`) makes every route except `/health` require `Authorization: Bearer <token>` (constant-time compare). New `KVStore(kvBinding, { prefix?, ttl? })` (`src/deploy/kvStore.ts`) is an `AgentStore` on a Workers KV namespace: `sessions/<id>` (transcript JSON, bytes as `{ "$bytes" }`), `checkpoints/<id>` (`KVCheckpointStore`, which gains an optional TTL) and `approvals/<id>`, with optional per-kind TTLs; the Worker builds it from the existing `AGENT_CHECKPOINTS` binding, and keeps sessions in the isolate's memory without one. An approval paused on one request can be decided by another request on a new isolate. The routes are now Fetch-native (`src/server/fetchRoutes.ts`: `Request` in, `Response` and a `ReadableStream` SSE body out, bearer auth with Web Crypto); `src/server/chatRoutes.ts` adapts them to `node:http` for `lousho dev` and the node server, and `src/server/bearerAuth.ts` is gone. The built Worker runs a `createAgent()` agent, so the build swaps its Node-only imports for `src/deploy/shims/node.worker.ts`, and the `node:` leak check now also catches bare builtin specifiers; the bundle grows to about 1.7 MB. The generated `wrangler.toml` documents the KV binding and both secrets. The `wrangler dev` test now streams a session turn through workerd with a KV binding and a token. See docs/deployment.md#bindings-sessions-and-the-api-on-workers.
-- Steering (LOU-V10): `run.steer(input)` on `AgentRun` (from `agent.stream()`, `session.stream()` and `AgentExecutor.stream()`), and `InputQueue.steer(input)` for non-streaming callers, redirect a running run to new user input. If a model call is in flight and has not emitted text or tool calls yet, it is aborted with a per-call signal (not the run's), its partial output is discarded, the input is appended as a user message and the model is called again (`applied: 'immediate'`; that step ends with `step.done` `'steered'` and counts toward `maxSteps`; a provider that ignores the signal is not waited for). Once the model has emitted output, the input waits for the next safe point like `enqueue()` (`'queued'`); after the run has finished, `applied` is `false`. Tool calls already running finish and keep their results; calls of that turn not started yet get the usual "cancelled before it ran" result. It returns `{ id, applied, joined }` (new type `SteerResult`; `joined` is a promise of whether the input reached the transcript). New event `input.steered` `{ id, text, mode: 'immediate' | 'queued' }` (`InputSteeredEvent`, additive, schema v1), followed by the existing `input.applied`. With checkpointing, the input is checkpointed when it is taken, before the model is called again, and the discarded partial turn is never checkpointed. `agent.session({ turnPolicy: 'steer' })` makes a `send()` / `stream()` made while a turn runs steer that turn (`'queue'` and `'wait'` are unchanged). `AgentRun` gains the required `steer()` member, so a hand-written `AgentRun` object must add it. See docs/streaming.md#steering and docs/sessions.md.
-- `ai` v6/v7 `stream()` (LOU-D27): the built-in providers' `stream()` (and so `agent.stream()`) now works on `ai` v6 and v7 as well as v4, through the LOU-D26 compatibility layer (`streamCompat()`): the request is mapped as for `generate()`, and either major's `fullStream` is read into the same `StreamChunk`s: text deltas, tool calls (the whole call, or one assembled from `tool-input-start`/`-delta`/`-end` when the model sends none), and a `finish` chunk with the finish reason and usage, including cached and reasoning tokens. An `error` part now rejects the stream with its error on both majors (on v4 the step used to end with finish reason `error` and the partial text), an `abort` part with the signal's reason; reasoning deltas are dropped until a reasoning chunk type exists (LOU-V13). `StreamChunk`/`StreamResult` are unchanged. The protected `AiSdkProvider.convertMessages()` now returns our structural `AiSdkMessage[]` instead of `ai` v4's `CoreMessage[]` (which v6/v7 do not export) and is marked deprecated for LOU-D28; an override returning `CoreMessage[]` still compiles. The `ai`/`@ai-sdk/*` peer ranges still name v4 (LOU-D28). Tested on the real `ai` v7 (`MockLanguageModelV4`), with `agent.stream()` events asserted by one helper on v4 and v7. See docs/providers.md#vercel-ai-sdk-versions.
-- `spec.policy` is enforced (LOU-X5): `specToAgent()` compiles the policy block into `createAgent()` options through the new `compilePolicy()`. `requiresApproval` (`true` or a list of tool names) becomes `permissions: [ask(...)]`; `guardrails` (`max-length`, `secret-scan`, `regex`, `deny-topics`, `llm-judge`, by name or `{ name, ...options, on }`) become input and output guardrails; `limits`, `askQuestion` and `compaction` pass through. `loadSpec()` validates the known fields (an unknown guardrail name fails with the names available and a did-you-mean; unknown policy keys are still kept for the generators), and `lousho doctor <spec>` prints one line per policy block and flags unknown guardrail names. **Behaviour change:** `requiresApproval: true` now actually pauses tool calls (`finishReason: 'awaiting-approval'`); before, a spec that set it ran its tools without asking, and a spec with a guardrail name outside the built-ins (for example `diff-size-cap`) now fails validation. See docs/configuration.md#policy-policy.
-- `ai` v6/v7 `generate()` (LOU-D26): the built-in providers' `generate()` now works on `ai` v6 and v7 as well as v4, through a compatibility layer that detects the installed major (v5+ exports `stepCountIs`). On v6/v7 it sends messages as `ModelMessage`s (tool calls with `input`, tool results as `output`, `mediaType`), `maxTokens` as `maxOutputTokens`, one step as `stopWhen: stepCountIs(1)`, tools as `inputSchema` without `execute` and `responseFormat` as a JSON-mode `output`, and reads usage from `inputTokens`/`outputTokens`/`totalTokens` (cached and reasoning tokens from their details) into the same `GenerateResult`. `LLMProvider`, `GenerateOptions` and `GenerateResult` are unchanged, and v4 behaves as before. `stream()` on v6/v7 throws an error naming LOU-D27 until that ticket lands; the `ai` and `@ai-sdk/*` peer ranges still name v4 (LOU-D28). Tested against the real `ai` v7 (`MockLanguageModelV4`) next to the v4 contract tests. See docs/providers.md#vercel-ai-sdk-versions.
-- Queued follow-up input (LOU-V9): `run.enqueue(input)` on `AgentRun` (from `agent.stream()`, `session.stream()` and `AgentExecutor.stream()`) adds user input to a run that is still going; it joins the transcript at the next safe point (after the current step's tool results, before the next model call) and the run continues as if the user had typed it, with one more step when it arrives during the final reply. It returns `{ id, applied }`: `applied` is `false` when the run had already finished (send the input as a new turn, e.g. `session.send()`), otherwise a promise of whether it was applied. New events `input.queued` `{ id, text }` and `input.applied` `{ id, step }` (additive, schema v1). Non-streaming callers pass an `InputQueue` (new export) as `ExecuteOptions.inputQueue` and call its `push(input)`. With checkpointing, a waiting input is saved right away at the end of the checkpoint (the LOU-U8 queued-input slot), so a crash does not lose it. `agent.session({ turnPolicy: 'queue' })` makes a `send()` / `stream()` made while a turn runs (or waits to start) join that turn instead of waiting for its own (`'wait'`, the default, keeps today's behaviour). `AgentRun` gains the required `enqueue()` member, so a hand-written `AgentRun` object must add it. Steering (aborting the in-flight model call to redirect) is the follow-up, LOU-V10. See docs/streaming.md#queued-input and docs/sessions.md.
-- Input and output guardrails (LOU-X4): `guardrails?: { input?, output?, tools?, onTripped? }` on `createAgent()` and `ExecuteOptions` (new type `AgentGuardrails`). A guardrail is `{ name, check(ctx) }` (new type `IoGuardrail`; `ctx` is `{ kind: 'input' | 'output' | 'tool', text, messages, toolName?, args?, signal? }`) returning `{ ok: true }` or `{ ok: false, reason, action?: 'block' | 'rewrite', replacement? }`. Input guardrails run on each new user message before the first model call; output guardrails on the final reply (in a streamed run, on every step's text, before its `text.done`); tool guardrails on a call's arguments after the permission rules (skipped on `deny`) and before `needsApproval`. A block ends the run with the new `finishReason: 'guardrail'` and `result.guardrail` (`{ name, kind, reason, toolName? }`, new type `GuardrailTrip`), with no model call for an input block; `onTripped: 'throw'` rejects with the new `GuardrailError` (`LOUSHO_GUARDRAIL_TRIPPED`) instead. A rewrite replaces the text. `stream()` emits the new `guardrail.tripped` (before `run.done`) and `guardrail.rewrote` events. Sub-agents run their parent's guardrails, then their own. Built-ins: `maxLengthGuardrail({ maxChars })`, `regexGuardrail({ name, pattern?, action?, replacement? })` (defaults to the secret-scan patterns, now exported as `SECRET_PATTERNS`), `denyTopicsGuardrail({ topics })` and `llmJudgeGuardrail({ model, instruction })`. The patch guardrails (`runGuardrails()`, `secretScanGuardrail`, ...) are unchanged; the new types are named `IoGuardrail*` because `Guardrail` and `GuardrailResult` are theirs. `spec.policy.guardrails` in agent spec files is not wired yet (LOU-X5). See docs/guardrails.md#input-and-output-guardrails.
-- Deployed `/chat` upgrade (LOU-D14): the `node-server` and `docker` targets (`dist/server.js`) now serve the `lousho dev` protocol: `POST /chat { sessionId, input }` streams the turn as SSE (`data: <AgentEvent JSON>`, then `event: done`) with history kept per session, `GET /chat/:sessionId`, `POST /chat/:sessionId/approvals/:id` (`{ approved, note? }` or `{ answer }`) and `GET /health`; the single-turn `POST /chat { message }` still works (now with a `Deprecation: true` header). The routes are one shared module, `src/server/chatRoutes.ts`, used by `lousho dev` and the deployed runtime. `LOUSHO_STORE` (`memory`, the default, or `sqlite:<path>`, Node >= 22) picks where sessions live. Bearer auth: set `LOUSHO_API_TOKEN` (or pass `{ auth: { token } }` as the new optional third argument of `adapter.scaffold()`; the variable wins) and every route except `/health` requires `Authorization: Bearer <token>` (constant-time compare, `401` JSON otherwise); treat it as required for anything not on localhost. The `docker` image is now based on `node:22-slim` (was `node:20-slim`) for `node:sqlite`. `specToAgent(spec, { store })` takes an optional `store`. The Cloudflare Worker target is unchanged (sessions over KV and SSE there are LOU-D51). See docs/deployment.md#http-api.
-- `lousho chat` (LOU-D33): a terminal REPL for an agent. `lousho chat <spec|dir|module> [--model provider/model] [--session id] [--store sqlite:<file>]` loads the target like `lousho dev` and reads one turn per line through `agent.session({ id, store }).stream()`: text deltas as they arrive, each tool call as a dim `[tool_name] {args}` line followed by `  -> result`, `Approve <tool>(args)? [y/N]` for a tool that needs approval, a numbered prompt with free text for an `ask_question` call, and `[usage]` tokens and cost after each turn. Slash commands: `/new`, `/model <provider/model>` (rebuilds the agent, the session continues), `/history`, `/quit`. SDK errors print with their `[LOUSHO_...]` code and fix. The loop is `runChatRepl({ input, output, createAgent })` in `src/cli/chatRepl.ts` (testable with scripted lines and a `mockModel` agent); `loadTarget()` is now exported from `src/cli/devReload.ts`. See docs/cli.md#lousho-chat.
-- Memory slots (LOU-W6): `defineMemory({ name, description?, scope, provider, recall?, expose? })` (new export) defines a named long-term memory, and `createAgent({ memory: [slot] })` wires it in. On the first model call of every run (`send()`, `stream()`, each session turn), a `preGenerate` hook recalls the slot's newest `recall.maxItems` (default 10) items into the system prompt as a `<memory name="...">` block (`recall.query: 'last-input'` passes the last user message as the provider query; `recall.onSessionStart: false` turns recall off). The model gets `remember_<name>({ text })` and `recall_<name>({ query?, limit? })` tools (`expose: { remember?, recall? }`, both on by default). `scope` is `'global'`, `'session'` (keyed by `agent.session({ id })`'s id or `send()`'s `sessionId`) or a function of `{ sessionId, metadata }`; the new `SendOptions.metadata` feeds it. Providers implement `MemoryProvider` (`list` / `add` / `remove`); built in are `inMemoryMemory()` and `fileMemory({ dir })` (one JSON file per scope key), both bounded by `maxItems` (default 1000, oldest dropped). See docs/memory.md.
-- Budgets (LOU-V6): `limits?: { maxTokens?, maxInputTokens?, maxOutputTokens?, maxCostUsd?, maxDurationMs?, maxSteps?, onExceeded? }` on `createAgent()` and `ExecuteOptions` (new type `RunLimits`). Limits are checked before every model call (so after every tool batch) and after a model call that asks for tools, and `maxDurationMs` aborts an in-flight model or tool call through the run's signal. A tripped limit ends the run with the new `finishReason: 'budget-exceeded'` and `result.budget: { limit, value, max, scope }` (`BudgetExceeded`); tool calls of that step get a cancelled result and the run is checkpointed as finished, like `'max-steps'`. `stream()` emits the new typed `budget.exceeded` event (`BudgetExceededEvent`) before `run.done` (additive, the event schema version stays 1). `onExceeded: 'throw'` rejects with the new `BudgetExceededError` (`LOUSHO_BUDGET_EXCEEDED`, no longer reserved) instead. `limits.maxSteps` is an alias of `maxSteps` (the stricter wins; alone it replaces the default of 10). Sub-agents' usage counts toward their lead's budget. `agent.session({ id, limits })` applies limits across a session's turns: what the turns spent is saved as `metadata.sessionUsage` on the transcript's last message (new types `BudgetSpent`, `SessionBudget`, `SessionTurnOptions`; `ExecuteOptions.sessionBudget` carries it to the run), so `maxCostUsd` per session holds across processes. See docs/configuration.md#budgets.
-- Stateful streaming dev chat (LOU-D32): `lousho dev` serves one session per browser tab. `POST /chat` with `{ sessionId, input }` streams the turn as SSE (`data: <AgentEvent JSON>` per event, then `event: done`) through `agent.session({ id, store }).stream(input)` over an in-process `memoryStore()` (or the agent's own `store`, when a module's `createAgent()` options or `overrides` set one); `GET /chat/:sessionId` returns the transcript and the pending approval; `POST /chat/:sessionId/approvals/:id` with `{ approved, note? }` or `{ answer }` decides an approval or answers a question and streams the continuation (rebuilt from the continued run's result, since `agent.approvals.resolve()` is not streamed). The chat page renders text deltas, tool calls with arguments and results, Approve / Reject and question buttons, errors and `run.done` usage and cost, with a "New session" button and the id kept in `sessionStorage`. Sessions survive a hot reload and continue on the new agent. The `{ message }` body of `POST /chat` still works and is deprecated (no session, JSON `ExecutionResult`, `Deprecation: true` header). See docs/cli.md#lousho-dev and docs/streaming.md.
-- Agent Forge History tab (LOU-D45.2): the bottom drawer's new **History** tab lists the loaded agent's run steps (step, status, finish reason, tool calls, tokens, cost). "Edit and replay from here" appends a user message or edits one of the step's tool results, forks the run at that step through `POST /runs/:id/fork`, and shows the fork next to the original as a side-by-side trajectory with the diverging turn and the drift entries highlighted, refreshed when the fork finishes. See docs/agent-forge.md#the-history-tab.
-- `lousho dev` for agent directories and TS agents, with hot reload (LOU-D31): `lousho 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 `LOUSHO_CONFIG_INVALID` / `LOUSHO_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#lousho-dev and docs/agent-directories.md#run-it-with-lousho-dev.
-- Multimodal input through the public API (LOU-V12): `agent.send()` / `agent.stream()`, `session.send()` / `stream()`, `t.send()` in evals and `useLoushoAgent().send()` take the new exported `AgentInput` (`string | ContentPart[] | Message[]`): a string or parts become one user message, a `Message[]` is passed through (in a session it is appended to the transcript). Checkpoints, `agent.resume()` and queued input hold the parts like any message. The React user bubble shows the text with an `[image]` / `[file]` marker per non-text part. `SqliteStore` sessions and checkpoints save `Uint8Array` parts as `{ "$bytes": "<base64>" }`, as `FileSessionStore` does. Finishes LOU-V11 (its note that `agent.send()` / `session.send()` take no parts is out of date). See docs/providers.md#multimodal-input.
-- Built-in `ask_question` tool (LOU-X9): `createAgent({ askQuestion: true })` (off by default) or `askQuestionTool()` gives the agent `ask_question({ question, options?, allowFreeText? })`. A call pauses the run through the approval mechanism, so it waits durably like any approval (sessions, `memoryStore()` / `SqliteStore`, a restart between question and answer). The pending record gains optional `kind: 'question'` and `question: { text, options?, allowFreeText? }` (new types `ApprovalKind`, `ApprovalQuestion`; `describeApproval()` and `ASK_QUESTION_TOOL_NAME` are exported), and so do the `approval.requested` event and the React hook's `pendingApproval`. The new `agent.approvals.answer({ id, answer })` (the same as `resolve({ id, approved: true, note: answer })`) continues the run with `{ answer, option? }` as the tool result (`option`: index of the matching option); `approved: false` gives the model a `kind: 'rejected'` error saying the user declined to answer. `useLoushoAgent()` gets `answer(text)`. The `approve` callback may now return a string (`ApproveToolCall` returns `boolean | string`), which approves with that note, so code can answer questions. A tool run after an approval sees the decision's note as `ctx.approval.note` (new optional `ToolExecutionContext.approval`). See docs/approvals.md "Asking the user a question".
-- Agent Forge time travel API (LOU-D45): Agent Forge's `FileCheckpointStore` keeps the bounded per-session checkpoint history (`history()`, `historyLimit` option, `delete({ keepHistory })`) with the same semantics as `LocalStorageCheckpointStore`, checked by the SDK's history contract suite. The runtime control server gains `GET /runs/:id/history` (each step's status, save time, finish reason, tool calls, tokens and cost), `POST /runs/:id/fork` (`{ fromStep, patch?: { toolResult?, appendInput?, businessState? } }`, forks with `AgentExecutor.fork()` and starts the fork as a run of its own) and `GET /runs/compare?a=&b=` (`compareTrajectories()`). Fixed on the way: Agent Forge's chat transcript compiles against multimodal `Message.content` (LOU-V11) again, keeping each message's text. See docs/agent-forge.md#time-travel.
-- 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 `LOUSHO_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 `lousho 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.
-- Compaction events and the `compaction` option (LOU-W3.2): `agent.stream()`, `session.stream()` and `AgentExecutor.stream()` emit two new typed events whenever the compaction hook compacts a request: `compaction.start` (`strategy`, `tokensBefore`, `contextWindow`, `thresholdTokens`) before the work and `compaction.done` (`strategy`, `tokensBefore`, `tokensAfter`, `prunedToolCallIds`, `summary?`, `error?: { message }`) after it, inside the step and before the model call; `error` is set when the strategy failed and the hook fell back. Additive: the event schema version stays 1. `GenerateHookContext` gains the optional `emit(event)` (set in streamed runs only) that the hook uses. `createAgent({ compaction })` takes `true` (the prune hook with its defaults) or `{ strategy?, thresholdPercent?, contextWindow?, protectedTokens?, summarizer? }`, where `summarizer` (a `'provider/model'` string or an `LLMProvider`) selects `twoPhaseStrategy()` with that model; `summarizer` together with `strategy` is a `ConfigurationError`. `createAgent({ hooks })` (new) takes any `AgentHook[]`, run before the compaction hook. See docs/compaction.md.
-- Connect MCP servers from config (LOU-Z4): `connectMcp(servers, { lazy?, onError?, logger? })` (`@lousho/build-ai-agent/mcp` and the root) connects stdio (`command`/`args`/`env`) and streamable HTTP (`url`/`headers`) servers, lists their tools as `<server>__<tool>` descriptors and returns `{ tools, close(), status() }`. Every server connects up front (listing tools needs a connection); `lazy` (default `true`) reconnects on the next tool call after `close()` or a dropped connection. `onError: 'skip'` leaves a failing server out with a warning instead of rejecting. `createAgent({ mcpServers })` connects them on the new `agent.ready()` or the first `send()` / `stream()` and adds their tools; the new `agent.close()` disconnects them (both are no-ops without `mcpServers`). `specToAgent()` now connects `spec.mcpServers` the same way (closes TODO(LOU-D20.2)); `agent.mcpServers` still lists them. `loadMcpTools()` accepts any `{ listTools, callTool }` (`McpClientLike`). See docs/configuration.md#connect-mcp-servers-mcpservers-connectmcp.
-- Error codes with fixes (LOU-D2): every `SDKError` now has a stable `code` (`LOUSHO_<AREA>_<NAME>`, e.g. `LOUSHO_CONFIG_MISSING_PROVIDER`, `LOUSHO_PEER_MISSING`, `LOUSHO_SPEC_INVALID`, `LOUSHO_SESSION_AWAITING_APPROVAL`), a one-sentence `hint` and a `docs` link to its section of the new docs/errors.md; its message ends with a `[code] hint (docs)` line (`detail` is the message without it), and `toString()` always shows it. `ERROR_CODES` / `ErrorCode` (new exports) are the registry, and a test keeps it, the codes used in `src/` and docs/errors.md in sync. The plain `Error`s thrown by `createAgent()` (no model, `instructions` + `prompt`, `sessionId` without checkpoints), `resolveProvider()` (bad spec, unknown prefix, missing API key, missing peer), `AgentExecutor.execute()` / `stream()` (missing `provider` / `agent` / `input`, approval with no `approvalStore`), `resumeAfterApproval()` (unknown approval), sessions (invalid id, corrupt file, second iteration, no stream runner), `loadSpec()` and `specToAgent()` are now `ConfigurationError` / `ValidationError` / `SDKError` with codes; `MissingPeerDependencyError` extends `SDKError`. Existing message text is unchanged (the help line is appended). `loadSpec()` suggests the field a top-level typo meant (`unknown field 'promt' (did you mean 'prompt'?)`). See docs/errors.md.
-- Checkpoint history (LOU-D43): `memoryStore()`, `SqliteStore` and `LocalStorageCheckpointStore` keep a bounded history per session: every `save()` also appends the record to a ring (`historyLimit` option, default 50, `0` keeps none; the oldest are dropped), and the new optional `CheckpointStore.history(sessionId, { limit? })` returns `{ step, savedAt, status, checkpoint }` entries newest first. `CheckpointStore.delete(sessionId, { keepHistory: true })` keeps the history (by default `delete()` clears it too), `getCheckpointHistory(store, sessionId)` reads it and returns `undefined` for a store without `history()`, and `SqliteStore` gains the `checkpoint_history` table (added when an existing database file is opened; `prune()` removes old entries). New types `CheckpointHistoryEntry`, `CheckpointHistoryOptions`, `CheckpointDeleteOptions` and `MemoryStoreOptions`. `KVCheckpointStore` and Agent Forge's file store keep no history yet (LOU-D43.2). This is the first step of time-travel from a past step. See docs/durable-execution.md#checkpoint-history.
-- `lousho eval --record / --replay / --drift` (LOU-D46): `--record` runs every eval case against its agent's real provider through `recordReplay()` and writes one cassette per case next to the eval file (`__cassettes__/<eval-name>/<case>.json`, the normal cassette format); `--replay` runs every case from its cassette with no network, and a missing cassette fails the case with the `--record` command to run. Plain `lousho eval` with `CI` set replays the cases that have a cassette; without `CI` it is unchanged. `--drift` re-records into a temp directory and compares each case with its committed cassette (ordered tool names, JSON-normalized tool arguments, step count, finish reason; tokens with `--drift-usage`): the summary gets a `Drift:` table and each drifted case a soft `drift` assertion (a JUnit `<system-out>` note), or a gate failure with `--strict`. Existing eval files need no change: while a case runs, `AgentExecutor.execute()` wraps its provider for that case. `EvalResult` gains `cassettes`. Fixed on the way: trajectory and classic eval results now carry their `file` (it was read before the test ran and was always empty). See docs/evals.md#record-replay-and-drift.
-- OpenTelemetry GenAI metrics and cost (LOU-D48): `createOtelTraceExporter()` (`@lousho/build-ai-agent/otel`) now also records the GenAI client metrics `gen_ai.client.token.usage` (histogram, `{token}`, one record per `gen_ai.token.type` `input`/`output`) and `gen_ai.client.operation.duration` (histogram, `s`, for every model call and tool call) through `@opentelemetry/api`'s metrics API: the global `MeterProvider`, or the new `meter` option; `metrics: false` turns them off. Without a registered `MeterProvider` they are discarded by OpenTelemetry's no-op meter. Spans gain `lousho.cost_usd` (estimated USD: per step on `chat` spans, cumulative on `invoke_agent` spans, absent when the price table does not know a model) and `lousho.usage.estimated` on `invoke_agent` spans (it was already on `chat` spans). Any `TraceExporter` sees the cumulative attributes: `withSpan()` sums the cost of finished child spans onto their parent. See docs/observability.md.
-- One `store` option (LOU-D30): `createAgent({ store })` takes an `AgentStore` (`{ sessions?, checkpoints?, approvals? }`, new export) and wires all three from it. `SqliteStore` is one; the new `memoryStore()` returns in-memory sessions, checkpoints and approvals, and docs/sessions.md shows the file-based combination (`FileSessionStore`, `LocalStorageCheckpointStore`, `StorageServiceApprovalStore`). `agent.session({ id })` then keeps its transcript in `store.sessions` and checkpoints every turn in `store.checkpoints`; `store.approvals` is the default `approvalStore`. `SendOptions.sessionId` makes `send()` / `stream()` a durable run checkpointed in `store.checkpoints` (an error without one), so a one-shot durable job needs no `AgentExecutor`, and `agent.approvals.resolve()` keeps checkpointing it. The new `agent.resume(sessionId)` finishes an interrupted `send(..., { sessionId })` run, or else the session's pending turn (as `session.resume()`), and returns `null` when nothing is pending. A session's own `store` / `checkpointStore` and an explicit `approvalStore` still win, part by part. Without `store`, nothing changes.
-- One tool-error shape (LOU-U14): every failed tool call reaches the model as `{ error, toolName, message, kind }` (message capped at 2,000 characters, transcript message flagged `isError`), whichever path failed: `kind` is `'execution'`, `'validation'` (plus `issues`), `'not-found'`, `'rejected'` (plus `note`), `'not-run'`, `'mcp'` or `'sandbox'`. New exports `toolErrorResult()`, `ToolErrorResult`, `ToolErrorKind` and `ToolErrorInput`; `McpToolError` and the sandbox guard's error (named `SandboxRequiredError`, not exported) carry a `toolErrorKind`. `kind` is additive on thrown-error and validation results. The paths that built their own shapes changed, see Changed. See docs/tools.md.
-- Background sub-agents end with the lead run (LOU-Y4.2): when a run ends (any `finishReason`, or an error), its background sub-agents still queued or running are cancelled, and the run resolves once their runs have stopped, so none of their events reaches `onEvent` afterwards. `withSubagentOptions(subagents, { awaitBackgroundOnFinish: true })` waits for them instead (an aborted or failed lead still cancels them). The new `result.backgroundTasks` lists the run's background tasks as `{ taskId, agent, status, elapsedMs, ... }` (absent when it started none). `createAgent({ subagentOptions: { maxConcurrent, awaitBackgroundOnFinish } })` sets the same options (over any attached with `withSubagentOptions()`, without changing the `subagents` value). The executor hook behind it is public: `ExecuteOptions.onRunEnd({ result } | { error })` is called exactly once per `execute()` / `stream()` run, however it ends; an error it throws rejects the run. See docs/sub-agents.md.
-- Durable sessions (LOU-W9): `agent.session({ id, store, checkpointStore })` (or a `store` that carries both, `{ sessions, checkpoints }`, such as a `SqliteStore`) runs each turn with `sessionId: '<id>.turn-<n>'` and that `CheckpointStore`, so it is checkpointed after every model response and tool result. `session.resume()` finishes a turn interrupted by a crash, a failed checkpoint write or a `PropagatingToolError` (also in a new process) without re-running recorded tool calls or model responses, adds it to the transcript as `send()` would and returns its result (`null` when nothing is pending); `session.pending()` reports an unfinished turn and `session.discardPending()` drops it. `send()` / `stream()` resume a pending turn before sending the new message. A turn paused for approval stays in its checkpoint until it finishes: `resume()` / `send()` throw `SessionAwaitingApprovalError`, and `agent.approvals.resolve()` continues it in the session. Sessions without a checkpoint store are unchanged. See docs/sessions.md.
-- Structured output (LOU-V4): `createAgent({ output: zodSchema })` (and `ExecuteOptions.output`) makes the final reply a JSON object validated by the schema. `send()`, `run.result` and `agent.approvals.resolve()` resolve with it as `result.object`, typed `z.output<typeof schema>` from `send()` and `stream()` of `createAgent()` agents (`SimpleAgent`, `AgentRun` and `ExecutionResult` gain a type parameter that defaults to `unknown`); `result.text` keeps the raw JSON. The system prompt gets an `## Output format` section with the schema as JSON Schema, and each model call carries the new `GenerateOptions.responseFormat: { type: 'json', schema? }` hint, which the `ai`-SDK providers map to `experimental_output` JSON mode. The reply is parsed (a code fence is tolerated) and validated; when invalid, one repair step sends the model the issues (it counts against `maxSteps`), and a reply still invalid ends the run with the new `finishReason: 'output-invalid'`, no `object` and `outputError: { message, issues }`. `run.done` gains an optional `object` field (additive: the event schema version stays 1). See docs/structured-output.md.
-- Background sub-agents (LOU-Y4): the `task` tool takes `background: true`, which starts the sub-agent and returns `{ taskId, status: 'running', agent }` at once. Agents with `subagents` also get `agent_status({ taskId? })` (`queued`/`running`/`done`/`failed`/`cancelled`/`awaiting-approval`, plus `elapsedMs`), `agent_await({ taskId | taskIds, timeoutMs? })` (the synchronous `task` result, or `status: 'timeout'`) and `agent_cancel({ taskId })`. `withSubagentOptions(subagents, { maxConcurrent })` bounds how many run at once per lead run (default 3; the rest queue). Background sub-agents inherit the lead run's runtime and `maxSubagentDepth`, and aborting the lead cancels them. Not yet: resuming one that paused for approval (it reports `awaiting-approval` with its `approvalId`). A user tool named `agent_status`, `agent_await` or `agent_cancel` now conflicts with `subagents`, like `task`. See docs/sub-agents.md.
-- React hook (LOU-D15): new `@lousho/build-ai-agent/react` subpath with `useLoushoAgent(source, options?)`. `source` is `{ agent, sessionId? }` (in process, via `agent.stream()` or `agent.session({ id }).stream()`) or `{ url, headers?, fetch? }` (POSTs `{ input }` and reads the SSE or NDJSON event stream). It returns `messages` (text and tool calls with status, args and result), `status` (`idle`/`streaming`/`awaiting-approval`/`error`), `pendingApproval`, `error`, `usage`, `lastEvent`, `send()`, `stop()` (aborts; unmount aborts too), `approve(note?)` and `reject(note?)` (via `agent.approvals.resolve()` in process, or `POST ${approvalsUrl}/${id}` remotely). The framework-neutral `reduceAgentEvents()` reducer and `parseEventStream()` parser are exported from the same subpath. `react` (`^18 || ^19`) is an optional peer dependency. See docs/react.md.
-- Summarizing compaction (LOU-W3): `summarizeStrategy({ model, protectedTokens?, prompt?, maxSummaryTokens? })` replaces the turns before the protected tail with one `[Conversation summary]` user message written by `model` (an `LLMProvider` or a `"provider/model"` spec), keeping system and pinned messages and each assistant turn together with its tool results; if the summary call fails it falls back to pruning and reports `error`. `twoPhaseStrategy()` (the recommended strategy) prunes first and summarizes only when still above the threshold. `pinMessage()` / `isPinned()` and the new optional `Message.metadata` (never sent to providers) mark messages no built-in strategy compacts. `CompactionStrategy.compact()` may now be async, so `compactMessages()` returns a Promise; `CompactionResult` / `CompactionInfo` gain `summary` and `error`, and `CompactionInput` gains `thresholdTokens` and `signal`. A strategy that throws no longer fails the run: the hook reports the `error` to `onCompaction`. See docs/compaction.md.
-- `createAgent({ retry, fallbackModels })` (LOU-V7.2): `retry` (`withRetry()` options, or `false`) retries failed model calls and defaults to `{ maxRetries: 2 }` for models given as `provider/model` strings (or picked from the environment); a `provider` instance is wrapped only when `retry` is set. `fallbackModels` are `provider/model` strings tried in order once the primary model's retries are used up (`withFallback([withRetry(primary), withRetry(fallback), ...])`). `agent.stream()`, `session.stream()` and `AgentExecutor.stream()` report them as two new typed events, `provider.retry` (`attempt`, `maxRetries`, `delayMs`, `error: { message, category? }`, `provider`) and `provider.fallback` (`from`, `to`, `error: { message }`), for any `withRetry()` / `withFallback()` provider. Additive: the event schema version stays 1.
-- Context compaction (LOU-W2): `createCompactionHook()` returns an `AgentHook` that, before a model call estimated above `thresholdPercent` (default 0.9) of the model's context window, replaces tool results older than the newest `protectedTokens` (default 40,000) with a `[pruned: <tool> result, N chars]` marker, in the run's transcript itself. `compactMessages()` compacts a conversation by hand; `CompactionStrategy` / `pruneToolResultsStrategy()` make the strategy pluggable. See docs/compaction.md.
-- `AgentSpec.mcpServers` (LOU-D20): a validated map of MCP servers (stdio `command`/`args`/`env` or HTTP `url`/`headers`) in agent spec files. `loadSpec()` reports a bad entry with its name, `lousho doctor` reads the validated field instead of the raw file, and `specToAgent()` exposes the parsed servers as `agent.mcpServers` (connecting them is TODO(LOU-D20.2)). Existing specs are unaffected.
-- `createAgent()` agents can pause for approval (LOU-D21): a `needsApproval` tool no longer fails the run with "requires approval but no approvalStore". The run pauses (`finishReason: 'awaiting-approval'`) in a per-agent `InMemoryApprovalStore` (or the new `approvalStore` option), and `agent.approvals.list()` / `agent.approvals.resolve({ id, approved, note? })` continue it, in its session if it paused in one. The `approve` option decides calls in code without pausing.
-- Tools own their contract (LOU-D22): `ToolDescriptor` gains optional `inputSchema` (zod) and `execute(args, ctx)`, which are now the canonical fields. `defineTool()` sets both and no longer calls `ai`'s `tool()`. Argument validation, the schema sent to the model, and tool execution read them first and fall back to `tool.parameters` / `tool.execute`. `ToolDescriptor.tool` (the `ai` v4 `Tool`) is now legacy: it is still built by `defineTool()` and still accepted on hand-written descriptors this release, but new code should set `inputSchema` and `execute`.
-- ✅ Complete Phase 5 migration: Security, Storage, Templates, and Utils modules
-- ✅ Security module with encryption, hashing, and quota validation
-- ✅ Storage service with file locking mechanism
-- ✅ Template rendering engine with Jinja2-like syntax
-- ✅ Comprehensive utility functions (errors, formatters, validators)
-- ✅ File extraction and processing utilities
-- ✅ JSON path navigation utilities
-- ✅ Framework-agnostic architecture (zero framework dependencies)
-
-### Fixed
-- `lousho --help`, `-h` and `help` print the usage and exit 0 (they were "unknown command" with exit 1) (LOU-D49).
-- Install truth (LOU-U20): the README, installation, CLI, quick start and Agent Forge docs, `lousho init --help` and the message after a failed `lousho init` install now say the package is not on npm yet and point to one section, "Installing before the first release" (docs/installation.md); `npm install github:LinuxDevil/agent-sdk` is documented as not working. Stale "planned / not yet" statements about agent-directory channels, `toolCallId` in sandboxed tools and the Agent Forge Settings tab are corrected.
-- On `ai` 5+ the providers send images as `file` parts with an image `mediaType` (`image/*` when unknown) instead of the deprecated `image` part, which made `ai` 7 log a deprecation warning for every image. `ai` 4 still gets `image` parts.
-- OpenRouter on `@ai-sdk/openai` 2+, and the Ollama base URL (LOU-D28f, behaviour fix): `OpenRouterProvider` now builds its model with `provider.chat(modelId)` (Chat Completions, the only API OpenRouter implements) instead of the bare call, which targets the Responses API from `@ai-sdk/openai` 2 on; no change on `ai` 4. `OllamaProvider` appends `/api` to a base URL that has no path (`http://host:11434` or `http://host:11434/`), the form `ollama-ai-provider` and `ollama-ai-provider-v2` expect, so a configured bare host no longer hits `/chat` outside `/api` (before, `getModels()` hit `<baseURL>/api/tags` but chat requests went to `<baseURL>/chat`); a URL ending in `/api` or with any other path is used as it is, and `getModels()` no longer doubles `/api` for a base URL that has it. `lousho init` (and `create-lousho-agent`) now scaffolds OpenRouter projects on `ai@^7.0.0` with `@ai-sdk/openai@^4.0.0`.
-
-### Deprecated
-- `ExecuteOptions.onEvent`, `ExecutionEvent` and `ExecutionEventType` (LOU-D41). `onEvent` keeps working: the executor now emits only `AgentEvent`s, and an adapter derives the old events from them in the old order (`start`, `text-complete`, `tool-call`, `tool-result`, `error`, `abort`, `finish`, sub-agents' tagged with `subagent`), with a one-time `console.warn`. Differences: `finish` now comes after the run's checkpoint is written (it was just before), and a run that fails outside a step (an input guardrail that throws, `onRunEnd` throwing) now gets an `error` event too. Migration: replace `onEvent` with `onAgentEvent` (or `createAgent({ onEvent })`); `start` -> `run.start`, `text-complete` -> `text.done` (step usage on `step.done`), `tool-call` -> `tool.start`, `tool-result` -> `tool.done` / `tool.error`, `abort` / `finish` -> `run.done` (`finishReason`), `error` -> `error` (`{ name, message }`). The full table is in docs/streaming.md#migrating-from-onevent--executionevent.
-
-### Removed
-- `ExecuteOptions.streaming` (LOU-D41): it was never read. Use `AgentExecutor.stream()` / `agent.stream()` to stream a run. Passing it in an object literal is now a type error; remove the property.
-- `ToolDescriptor.injectStreamingController` and `defineTool({ injectStreamingController })` (LOU-D41.2, deprecated earlier in this release): no SDK path ever called it, so removing the property changes nothing at runtime. Passing it is now a type error; remove the property.
-- `AgentExecutionOptions.streaming` (LOU-D41.2): it was never read (`AgentExecutionOptions` is a legacy type no SDK API takes). Remove the property; stream a run with `agent.stream()` / `AgentExecutor.stream()`.
-- BREAKING: `validateTokenQuotas()` (`src/security/quotas.ts`) and the SaaS-era types `SaaSContext`, `QuotaConfig`, `UsageStats` and `QuotaValidationResult` (LOU-D36) no longer ship from the package root. Nothing in the SDK called them. No replacement; copy the file into your project if you relied on it.
-- BREAKING: `ConfigManager` and `SDKConfig` (`src/core/ConfigManager.ts`) (LOU-D36) no longer ship from the package root or `./core` (which still exports `AgentBuilder`). Nothing in the SDK used them. No replacement; copy the file into your project if you relied on it.
-- BREAKING: The formatters (LOU-D36) `getCurrentTS()`, `getTS()`, `formatDate()`, `safeJsonParse()`, `removeCodeBlocks()`, `findCodeBlocks()`, `checkApiKey()` and the types `CodeBlock`, `CodeBlockError`, `CodeBlockResult` (`src/utils/formatters.ts`) no longer ship from the package root. No replacement; copy the file into your project if you relied on it.
-- BREAKING: The JSON path helpers `getObjectByPath()` and `setRecursiveNames()` (`src/utils/json-path.ts`) (LOU-D36) no longer ship from the package root. No replacement; copy the file into your project if you relied on it.
-- BREAKING: The file extraction helpers `getMimeType()`, `getFileExtensionFromMimeType()`, `replaceBase64Content()`, `isBinaryData()`, `extractBase64Data()`, `createDataUri()` and `ProcessFilesParams` (`src/utils/file-extractor.ts`) (LOU-D36) no longer ship from the package root. No replacement; copy the file into your project if you relied on it.
-- BREAKING: The flows-ai converters (LOU-D35) are gone: `convertToFlowDefinition()` and `convertFromFlowDefinition()` (`src/flows/converters.ts`) no longer ship from the package root or `./flows`. There is no replacement: the flows-ai engine they targeted was never a dependency of this package and `FlowExecutor` never used them. Run flows with `FlowExecutor` directly.
-- BREAKING: `MemoryManager` and its types `MemoryManagerConfig`, `StoreMemoryOptions`, `RecallMemoryOptions` and `MemorySearchResult` (`src/execution/MemoryManager.ts`) (LOU-D38) no longer ship from the package root. Nothing in the SDK used them (`AgentExecutor`, `createAgent`, `resume` and the flows never called them; only their own test and the `execution/index.ts` re-export). Migrate to `defineMemory()` and `createAgent({ memory })` (memory slots, see docs/memory.md).
-- BREAKING: `ContextBuilder`, `ContextBuilderOptions` and `ExecutionContext` (`src/execution/ContextBuilder.ts`) (LOU-D38) no longer ship from the package root. Nothing in the SDK used them; they truncated by message count only. Migrate to `createAgent({ compaction })` (token-aware compaction, see docs/compaction.md).
-- BREAKING: The `retry()` family (`retry`, `retryOnError`, `retryWithTimeout`, `retryBatch`, `RetryableOperation`, `RetryOptions`, `RetryResult`; `src/execution/retry.ts`) (LOU-D38) no longer ships from the package root. Provider calls retry through the provider wrappers; nothing else in the SDK used it. Migrate to `createAgent({ retry, fallbackModels })`, or copy the file into your project for general-purpose retries.
-- BREAKING: The `data/` module (LOU-D39) is gone: the classes `Agent`, `Session`, `Result`, `Memory`, `Attachment` and the repository interfaces `BaseRepository`, `AgentRepository`, `SessionRepository`, `ResultRepository`, `MemoryRepository`, `AttachmentRepository`, `RepositoryCollection`, `RepositoryFactory`, `PaginationOptions`, `PaginatedResult` no longer ship from the package root. They were donor-product data tables that nothing in the SDK used once `MemoryManager` was removed. No replacement: unused. Use `AgentConfig`, sessions (`agent.session()`) and `defineMemory()` for the SDK's own concepts.
-- BREAKING: `@lousho/build-ai-agent/testing` exports test utilities only (LOU-D39). The in-memory repository mocks `MockAgentRepository`, `MockSessionRepository`, `MockResultRepository`, `MockMemoryRepository` and `MockAttachmentRepository` are removed with the `data/` module. No replacement: unused. `mockModel` and `recordReplay` are unchanged.
-- BREAKING: The template engine (`TemplateManager`, `renderTemplate()` and the types `TemplateFilter`, `TemplateContext`, `TemplateOptions`, `ITemplateManager`; `src/templates`) (LOU-D37) no longer ships from the package root. Nothing in the SDK, `lousho init` or Agent Forge used it (the executor never rendered prompts through it; the scaffold templates are separate files under `src/cli/init`). No replacement: unused; use a template literal or your own renderer.
-- `nanoid` is no longer a dependency (LOU-D35). Generated ids (agent, run, trace, memory ids) now come from `globalThis.crypto.randomUUID()` via an internal `newId()`, so they are UUIDs instead of 21-character nanoids. Nothing public depended on the old format.
-- `finishReason: 'max-steps'` (LOU-U19): a run that exhausts `maxSteps` while the model still wanted to continue (last turn ended in tool calls) now resolves with `finishReason: 'max-steps'` instead of the stale last-turn reason (usually `'tool_calls'`), on `ExecutionResult`, the `finish` event and `run.done`. Resumed runs count `initialSteps` toward the budget. A run that finishes naturally within the budget is unchanged. Code that treated `'tool_calls'` as "hit maxSteps" should check `'max-steps'` instead (the eval `completed()` message and the MCP server's agent tool do).
-
-### Docs
-- README revamped into a short front page (LOU-D52); the details it dropped moved to `docs/` (new pages: tools, approvals, providers, cli, flows, guardrails, utilities).
-
-### Renamed
-- The project is now **lousho** (it was `loushy`), before the first npm release, so nothing was ever published under the old name. Everything that carried the name changed with it, and this changelog uses the new names throughout, including in older entries: the package `@lousho/build-ai-agent` (was `@loushy/build-ai-agent`), the `lousho` CLI (was `loushy`), `create-lousho-agent` (was `create-loushy-agent`), the exports `useLoushoAgent`, `loushoAgent`, `LoushoAgentSource`, `LoushoUIMessageChunk` and the other `Lousho*` types, every `LOUSHO_*` error code and environment variable (`LOUSHO_MODEL`, `LOUSHO_API_TOKEN`, `LOUSHO_STORE`, ...), the `.lousho/` directory, the `lousho.*` span attributes and the `data-lousho-approval` stream part. Migration for a checkout that used the old name: replace `loushy` with `lousho` (keeping the case) in imports, scripts, environment variables and config, and rename an existing `.loushy/` directory to `.lousho/`.
-
-### Published
-- `@lousho/build-ai-agent` and `create-lousho-agent` are on npm. The README and the installation, quick start, CLI and Agent Forge docs no longer say the package is unpublished; "Installing before the first release" is now "Installing from a local build" (docs/installation.md#installing-from-a-local-build) and covers trying an unreleased commit. The hint printed after a failed `lousho init` install no longer mentions a 404; it points to `--sdk-path`. The docs site moved to https://lousho.com.
+# Changelog
+
+All notable changes to @linuxdevil/lousho will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+- **Breaking:** the package is renamed from `lousho` to `@linuxdevil/lousho`. Update imports from `'lousho'` / `'lousho/…'` to `'@linuxdevil/lousho'` / `'@linuxdevil/lousho/…'` and dependencies from `"lousho"` to `"@linuxdevil/lousho"`. The `lousho` binary name is unchanged, so `npx @linuxdevil/lousho …` and `lousho …` commands keep working.
+- Docs: `docs/agent-forge.md` is retitled **Lousho Studio** and now documents installing the separate `@linuxdevil/studio` package, workspaces, which SDK runs a workspace's agents (with each banner), the collector, and reporting deployed agents via `LOUSHO_OBSERVE_PROJECT`.
+- **Breaking:** Studio is now the separate package `@linuxdevil/studio`; the SDK tarball no longer contains `apps/agent-forge`. `lousho studio` finds an installed `@linuxdevil/studio` (local, next to the SDK, or global) and opens the current folder as a workspace, or prints `Studio is a separate install: npx @linuxdevil/studio` when it is missing. Inside the SDK checkout it keeps its dev/prod modes (`--prod`/`--dev`). Install Studio with `npm i -g @linuxdevil/studio` (or `npx @linuxdevil/studio`).
+- Studio: the Code tab gains "Eject to project" (`POST /agents/:id/eject`), which writes the agent-directory form (`specToAgentDir`) to `agents/<id>/` in the workspace after a confirm dialog, with an explicit overwrite step when the folder already exists.
+- New `@linuxdevil/lousho/observe` subpath: `startObserveDaemon`, `probeHealth`, `isObserveDaemon`, `defaultDbPath`, `OBSERVE_DEFAULT_PORT` and the daemon option/retention defaults, so a host process (Studio) can run and probe the collector through public exports.
+- Install docs use the public npm packages again (`npm install @linuxdevil/lousho`, `npm create lousho`).
+- `@linuxdevil/lousho/improve` (experimental): `improveAgent()` proposes tested edits to an agent's instructions and skills, offline, gated against the current harness and held-out cases. It applies nothing. See [Improving an agent](docs/improve.md).
+- `lousho bridge`: a new command that speaks Studio's bridge protocol (NDJSON on stdin/stdout, protocol 1) so Lousho Studio can build and run a project's agents with that project's own SDK and dependencies. It answers `hello`, `catalog`, `compile` and `shutdown`, and runs agents: `run`/`chat` start a run or chat turn, `steer`/`abort` control it, `resolveApproval`/`answerQuestion` resume a paused run, and every `AgentEvent`, trace span, steer join and run settle arrives as a pushed event (flows are refused with `LOUSHO_HOST_UNSUPPORTED`).
+- Model strings resolve any official AI SDK provider: `mistral/...`, `groq/...`, `xai/...`, `bedrock/...`, `vertex/...`, `azure/...` and 13 more load `@ai-sdk/<vendor>` on the first call, and `ai-sdk/<vendor>/<model>` loads any other `@ai-sdk/*` package. The package reads its own credentials. See [Providers](docs/providers.md#any-ai-sdk-vendor-by-name).
+
+## [1.0.0-alpha.117] - 2026-11-09
+
+## [1.0.0-alpha.116] - 2026-11-09
+
+## [1.0.0-alpha.115] - 2026-11-09
+
+## [1.0.0-alpha.114] - 2026-11-09
+
+## [1.0.0-alpha.113] - 2026-11-09
+
+## [1.0.0-alpha.112] - 2026-11-09
+
+## [1.0.0-alpha.111] - 2026-11-09
+
+## [1.0.0-alpha.110] - 2026-11-09
+
+## [1.0.0-alpha.109] - 2026-11-09
+
+## [1.0.0-alpha.108] - 2026-11-09
+
+## [1.0.0-alpha.107] - 2026-11-09
+
+## [1.0.0-alpha.106] - 2026-11-09
+
+## [1.0.0-alpha.105] - 2026-11-09
+
+## [1.0.0-alpha.104] - 2026-11-09
+
+## [1.0.0-alpha.103] - 2026-11-08
+
+## [1.0.0-alpha.102] - 2026-11-08
+
+## [1.0.0-alpha.101] - 2026-11-08
+
+## [1.0.0-alpha.100] - 2026-11-08
+
+## [1.0.0-alpha.99] - 2026-11-08
+
+## [1.0.0-alpha.98] - 2026-11-08
+
+## [1.0.0-alpha.97] - 2026-11-08
+
+## [1.0.0-alpha.96] - 2026-11-08
+
+## [1.0.0-alpha.95] - 2026-11-08
+
+## [1.0.0-alpha.94] - 2026-11-08
+
+## [1.0.0-alpha.93] - 2026-11-08
+
+## [1.0.0-alpha.92] - 2026-11-08
+
+## [1.0.0-alpha.91] - 2026-11-08
+
+## [1.0.0-alpha.90] - 2026-11-08
+
+## [1.0.0-alpha.89] - 2026-11-08
+
+## [1.0.0-alpha.88] - 2026-11-08
+
+## [1.0.0-alpha.87] - 2026-11-08
+
+## [1.0.0-alpha.86] - 2026-11-08
+
+## [1.0.0-alpha.85] - 2026-11-08
+
+## [1.0.0-alpha.84] - 2026-11-08
+
+## [1.0.0-alpha.83] - 2026-11-08
+
+## [1.0.0-alpha.82] - 2026-11-08
+
+## [1.0.0-alpha.81] - 2026-11-08
+
+## [1.0.0-alpha.80] - 2026-11-08
+
+## [1.0.0-alpha.79] - 2026-11-08
+
+## [1.0.0-alpha.78] - 2026-11-08
+
+## [1.0.0-alpha.77] - 2026-11-08
+
+## [1.0.0-alpha.76] - 2026-11-08
+
+## [1.0.0-alpha.75] - 2026-11-08
+
+## [1.0.0-alpha.74] - 2026-11-08
+
+## [1.0.0-alpha.73] - 2026-11-08
+
+## [1.0.0-alpha.72] - 2026-11-08
+
+## [1.0.0-alpha.71] - 2026-11-08
+
+## [1.0.0-alpha.70] - 2026-11-08
+
+## [1.0.0-alpha.69] - 2026-11-08
+
+## [1.0.0-alpha.68] - 2026-11-08
+
+## [1.0.0-alpha.67] - 2026-11-08
+
+## [1.0.0-alpha.66] - 2026-11-08
+
+## [1.0.0-alpha.65] - 2026-11-08
+
+## [1.0.0-alpha.64] - 2026-11-08
+
+## [1.0.0-alpha.63] - 2026-11-08
+
+## [1.0.0-alpha.62] - 2026-11-08
+
+## [1.0.0-alpha.61] - 2026-11-08
+
+## [1.0.0-alpha.60] - 2026-11-08
+
+## [1.0.0-alpha.59] - 2026-11-08
+
+## [1.0.0-alpha.58] - 2026-11-08
+
+## [1.0.0-alpha.57] - 2026-11-08
+
+## [1.0.0-alpha.56] - 2026-11-08
+
+## [1.0.0-alpha.55] - 2026-11-08
+
+## [1.0.0-alpha.54] - 2026-11-08
+
+## [1.0.0-alpha.53] - 2026-11-07
+
+## [1.0.0-alpha.52] - 2026-11-07
+
+## [1.0.0-alpha.51] - 2026-11-07
+
+## [1.0.0-alpha.50] - 2026-11-07
+
+## [1.0.0-alpha.49] - 2026-11-07
+
+## [1.0.0-alpha.48] - 2026-11-07
+
+## [1.0.0-alpha.47] - 2026-11-07
+
+## [1.0.0-alpha.46] - 2026-11-07
+
+## [1.0.0-alpha.45] - 2026-11-07
+
+## [1.0.0-alpha.44] - 2026-11-07
+
+## [1.0.0-alpha.43] - 2026-11-07
+
+## [1.0.0-alpha.42] - 2026-11-07
+
+## [1.0.0-alpha.41] - 2026-11-07
+
+## [1.0.0-alpha.40] - 2026-11-07
+
+## [1.0.0-alpha.39] - 2026-11-07
+
+## [1.0.0-alpha.38] - 2026-11-07
+
+## [1.0.0-alpha.37] - 2026-11-07
+
+## [1.0.0-alpha.36] - 2026-11-07
+
+## [1.0.0-alpha.35] - 2026-11-07
+
+## [1.0.0-alpha.34] - 2026-11-07
+
+## [1.0.0-alpha.33] - 2026-11-07
+
+## [1.0.0-alpha.32] - 2026-11-07
+
+- Install docs use the public npm packages again (`npm install @linuxdevil/lousho`, `npm create lousho`).
+- `@linuxdevil/lousho/improve` (experimental): `improveAgent()` proposes tested edits to an agent's instructions and skills, offline, gated against the current harness and held-out cases. It applies nothing. See [Improving an agent](docs/improve.md).
+- `agent.recover({ retryWithDiagnosis: true })` gives a run that reached `maxAttempts` one fork told why it failed, before quarantining it. `createOutputCheck()` is a new hook that runs your check after a tool succeeds and tells the model what it found. A fork no longer inherits `lastError` and `attempts` from its source.
+- **Behavior change:** `agent.recover()` no longer resumes a failing run forever. It backs off exponentially from the last failure (up to 15 minutes) and stops after `maxAttempts` failures in a row (default 10), calling the new `onQuarantined(run)` once. `agent.resume()` still runs a quarantined run. Pass a larger `maxAttempts` to keep retrying longer.
+- `lousho observe failures` also lists runs whose process died and scores below `--min-score` (default 0.5).
+- `agent.recover()` pauses during a provider outage instead of using up each run's attempts: after 3 provider failures in a row it stops resuming, probes with one run at growing intervals, and reports through the new `onOutage(paused)`.
+- `createProgressGuard()` gains `maxSameResults` (default 5), which denies a tool that keeps returning the same result even when its arguments differ. Run spans record `lousho.run.finish_reason`, and `lousho observe failures` lists runs that ended without an answer and names rate limits.
+- `lousho observe failures` lists recurring tool and model failures by agent, from the observe database or from trace files (`--traces`), each with a class and trace ids. See [Observability](docs/observability.md).
+- `createProgressGuard()`: an opt-in hook that adds advice to repeated tool failures, denies calls that keep returning the same result and tools that keep failing the same way, and stops the run with `LOUSHO_RUN_NO_PROGRESS` if denials continue. Actions stream as the new `heal.action` event; tool hooks get `ctx.emit`, and tool spans record `lousho.tool.replaced_by_hook`. See [Hooks](docs/hooks.md#stop-a-run-that-makes-no-progress).
+
+## [1.0.0-alpha.31] - 2026-11-01
+
+- **Behavior change:** the package is renamed from `@lousho/build-ai-agent` to `@linuxdevil/lousho`, and the scaffolder from `create-lousho-agent` to `create-lousho` (`npm create lousho`). Update imports from `@lousho/build-ai-agent` to `@linuxdevil/lousho` (subpaths such as `@linuxdevil/lousho/testing` keep their names). Install with `npm install @linuxdevil/lousho` or `npm create lousho` (no token needed). The packages are also mirrored to GitHub Packages as `@linuxdevil/lousho` and `@linuxdevil/create-lousho` for the repository's Packages tab.
+
+## [1.0.0-alpha.30] - 2026-10-31
+
+What is on `main` and not yet on npm. Entries marked **Behavior change** can
+break working code; [Upgrading](docs/upgrading.md) lists each one with its
+opt-out.
+
+### Added
+
+- The `lousho observe` daemon: a local collector (loopback, `http://127.0.0.1:7777`, SQLite at `~/.lousho/observe.db`) that gathers every agent's traces, heartbeats and eval scores when `LOUSHO_OBSERVE` is set — no per-agent code changes. `lousho observe start|status|stop|rebuild-rollups|token create`; a second `start` on a busy port attaches when it is already the observe daemon. See [Observability](docs/observability.md#the-observe-daemon).
+- Agent Forge is rebuilt around a left navigation grouped Build (Agents, Playground), Observe (Traces, Threads, Monitoring), Evaluate (Evaluations: Scores, Datasets, Evaluators, Annotation queues) and Assets (Prompts, Context Hub), plus Settings. It replaces the Build/Observe toggle and the old Observe tabs, and the Build toolbar shows only on Agents. See [Agent Forge](docs/agent-forge.md#navigation).
+- Every Studio screen has a hash route with its filters in the query string (`#/traces?agent=…&status=error`, `#/traces/<id>?obs=<step>`), so a reload, a bookmark, a pasted link or back/forward lands on the same view. See [Routes and deep links](docs/agent-forge.md#routes-and-deep-links).
+- Studio keyboard: `Ctrl+K` / `Cmd+K` opens a command palette (go to a screen, open an agent, open a pasted trace id, toggle the light/dark theme), `?` lists the shortcuts, and `j`/`k`/`Enter` move through and open table rows. See [Keyboard](docs/agent-forge.md#keyboard).
+- The last Studio nav item shows whether the collector answers. While the daemon is down, each daemon screen shows the command to start it and fills in once it is back. Daemon screens read it through the token-gated `/observe/**` proxy on the studio server, which forwards reads plus only the writes the screens make. See [The collector](docs/agent-forge.md#the-collector-observe-daemon).
+- Studio Traces and Trace screens: the list filters by search (name, input, output), agent, status, model, project, prompt and time range (15m to 30d or custom, default 24 h), sorts by duration, tokens or cost, and shows input/output previews, the error message and the model. A trace opens in one viewer (tree or waterfall, the failed step selected by default) whose inspector shows the error, input and output as chat bubbles with tool-call chips (Rendered, Raw or JSON), thumbs up/down feedback, usage and attributes; the header links the agent and thread and has **Copy link**, **Add to dataset** and **Add to queue**. Model-call steps carry **Open in Playground**. See [Traces](docs/agent-forge.md#traces).
+- Studio Threads (`#/threads`, one row per session, a session's turns oldest first), Monitoring (`#/monitoring`: the fleet table with status, last heartbeat, runs today, error rate, p95 latency and dropped events, plus Runs, Latency p95, Error rate, Cost and Tokens charts over 1h to 30d whose buckets open the matching traces) and Scores (`#/evals/scores`: one row per eval with pass rate, trend, per-check pass rates and latest failures, filtered by eval, agent, source and range). See [Monitoring](docs/agent-forge.md#monitoring).
+- Studio Playground (`#/playground`): system, user and assistant messages with `{name}` variables, a provider and model (`mock` with no key), tools borrowed from a saved agent, a streamed run with **Stop**, **Open trace** when it finishes, and **Save as new prompt version**. See [Playground](docs/agent-forge.md#playground).
+- Playground deep links: `#/playground?trace=<id>&fromObs=<obs>` loads a model call from a trace, and `#/playground?prompt=<name>[@<ref>]` loads a registry prompt.
+- `POST /playground/run` on the studio server runs a playground request and streams SSE `delta`, `tool_call`, `done` and `error` events; runs report to the daemon as agent `playground`. See [Playground run endpoint](docs/agent-forge.md#playground-run-endpoint).
+- Studio Prompts (`#/prompts`: versions, labels, runs that used each version, a side-by-side diff, **Move `<label>` here**, **Open in Playground**) and Context Hub (`#/hub`: namespaces viewed as one agent, `private` or `fleet` scope, and editing a fleet entry). See [Prompts](docs/agent-forge.md#prompts).
+- The Agents builder: node cards show the model, tool count and status; an empty canvas offers templates; Inspector sections collapse and the bottom drawer resizes (both remembered); and a run's status pill links **Open trace**. Builder runs report to the observe daemon under their agent id, with captured content kept out of the project's trace files. See [Agents](docs/agent-forge.md#agents).
+- Datasets: the daemon stores named datasets of `{ input, expected? }` examples (`GET`/`POST /api/v1/datasets`, `GET /api/v1/datasets/:name`, `POST /api/v1/datasets/:name/examples` with an example or `{ from_trace_id }`, which copies a trace's root input and output, and `DELETE …/examples/:id`). `defineEval({ dataset: 'name' })` in place of `cases` runs one test per example (`c` is `{ input, expected, label, example_id, source_trace_id }`) and fails with `LOUSHO_DATASET_UNAVAILABLE` when the daemon cannot serve it. Studio's `#/evals/datasets` lists, creates and browses datasets and deletes examples, and a trace's **Add to dataset** copies it into one. See [Datasets](docs/observability.md#datasets) and [Evals](docs/evals.md#from-the-daemon).
+- Online evaluator rules: `/api/v1/evaluators` holds rules with a `filter` on agent, status and name, a `sample_rate` and an `enabled` switch. Each enabled rule scores new traces as their root ends, as `source: online` scores named after the rule. See [Online evaluator rules](docs/observability.md#online-evaluator-rules).
+- Code evaluators: a `code` rule is a function `(trace) => number | { value, comment }` the daemon runs in the isolate sandbox. It needs `isolated-vm`, plus `NODE_OPTIONS=--no-node-snapshot` on Node 20+; without them code rules are skipped with one warning. `POST /api/v1/evaluators/:id/test` dry-runs a rule on one trace without writing a score. See [Online evaluators](docs/observability.md#online-evaluators).
+- Judge evaluators: a `judge` rule is a model and a rubric. The daemon queues a job per matching trace, and Agent Forge runs the judge with its provider keys (a key saved in Settings, or the provider's env var; the saved key wins), so judges run only while Studio is running. `LOUSHO_STUDIO_JUDGE=0` turns Studio's judge loop off. Studio's `/observe/api/v1/evaluators/:id/test` dry-runs judge rules too. See [Judge rules](docs/observability.md#judge-rules-through-agent-forge).
+- Studio Evaluators screen (`#/evals/evaluators`): lists the rules with their last run and runs in the last 24 hours, and creates, edits, enables, disables and deletes them. **Test on trace** dry-runs a rule on one trace id. The judge kind stays disabled until Studio has a provider key, saved in Settings or set in the provider's env var. See [Evaluators](docs/agent-forge.md#evaluators).
+- Annotation queues: `/api/v1/queues` holds named lists of traces with an optional rubric (`name`, `description`, `min`, `max` per score); `GET /api/v1/queues/:id/next` returns the oldest pending item and `POST …/items/:item/complete` writes its scores as human scores (or skips it). Studio's `#/evals/queues` creates queues and reviews them one trace at a time beside the rubric (Enter submits, `S` skips), and a trace's **Add to queue** adds it. See [Annotation queues](docs/observability.md#annotation-queues).
+- Human feedback scores: `POST /api/v1/scores` `{ trace_id, obs_id?, name, value, comment? }` adds a `source: human` score (`201 { score_id }`; unknown trace or step `404`). Each eval case also records one `<evalName>` score: 1 when no gate check failed and the case did not throw, else 0 with the failed gates in the comment. See [The observe daemon](docs/observability.md#the-observe-daemon).
+- Prompt labels: a label (`prod`, `staging`) points at one version; `lousho prompt label <name> <label> <version>` (or `PUT /api/v1/prompts/:name/labels/:label`) moves it, `push --labels` sets it on the pushed version, and `createAgent({ prompt: 'name@prod' })`, `lousho prompt get name@prod` and `GET /api/v1/prompts/:name/:ref` resolve it. A push whose text and variables equal the latest version's mints nothing (`unchanged: true`). See [`lousho prompt`](docs/cli.md#lousho-prompt).
+- Trace list API: `GET /api/v1/traces` takes `from`/`to` (half-open ms), `q` (substring of name, input or output), `min_duration_ms`, `model`, `prompt` (`<name>[@<version>]`), `sort` (`start`, `duration`, `tokens`, `cost`) and `order`, and rows add `agent_name`, `model`, `error_message` and input/output previews. See [Trace list API](docs/observability.md#trace-list-api).
+- Sessions API: `GET /api/v1/sessions` (filter by agent, status and start window, paged) and `GET /api/v1/sessions/:id` (the session and its traces, oldest first) with per-session trace counts, tokens, cost and last input. See [Sessions API](docs/observability.md#sessions-threads-api).
+- Retention: once a day the daemon deletes finished traces whose last observation ended more than `lousho observe start --retention-days N` ago (default 30, `0` keeps everything), with their scores and prompt-use links, plus older scores whose trace is gone and sessions that are not `active` and no run references. A trace with a run still open and an `active` session are kept. Rollups, prompts, hub entries, the agent registry, tokens, datasets, evaluator rules and annotation queues are never pruned. `lousho observe prune --older-than <N>d` prunes now and runs `VACUUM`. See [Retention](docs/observability.md#retention).
+- `lousho observe export [--since 7d] [--agent X] [--out file]` writes traces as JSONL (`{ trace, observations, scores }` per line) straight from the db, without a running daemon. See [Export](docs/observability.md#export).
+- Insights series carry `p95_latency_ms` and `error_rate` per agent and bucket. A db written by an older daemon lacks them for past buckets: run `lousho observe rebuild-rollups` once to backfill. See [The observe daemon](docs/observability.md#the-observe-daemon).
+- Heartbeats carry the reporter's dropped-event count, and each `/api/v1/agents` row shows it as `dropped` (`null` for older SDKs); Studio's Monitoring fleet table shows it. See [The observe daemon](docs/observability.md#the-observe-daemon) and [Monitoring](docs/agent-forge.md#monitoring).
+- Prompt registry: `createAgent({ prompt: 'name@version' })` or `LOUSHO_PROMPT` resolves versioned instructions from the daemon at build; every run records the version used. `lousho prompt push|list|get` manages it. When the daemon is unreachable, embedded `instructions` are used; with no `instructions` the agent fails closed: every run rejects with `LOUSHO_PROMPT_UNRESOLVED` instead of running without a system prompt. A failed fetch is not cached for good: runs in the next 30 seconds resolve at once, then the next run fetches again (waiting up to 2.5 seconds).
+- Context hub: `hub()` / `hubTools()` publish and query namespaced shared memory scoped `private` (the writing agent) or `fleet` (every agent on the daemon).
+- Fleet monitoring: heartbeat-derived agent status, `agent.deregister` on graceful exit, a crashed agent's open sessions and unfinished observations flip to `interrupted`, and webhook alerts (`--webhook`, `alerts.json`) on down transitions and error-rate thresholds.
+- Eval scores report to the daemon: every `AssertionResult` lands as a score row on the exercised run's trace (`source: eval` or `judge`); `lousho eval --observe` forces emission. Each case's `eval` span and score rows are flushed when the case finishes, each wait capped at 1 second; the scores share the reporter's queue, so they go out after the span and are retried while the daemon is down. A wait that runs out skips the waits of the next 30 seconds of cases.
+- Reporting to the daemon: spans that finished without an error report status `ok`. A down daemon's batches are requeued and retried with exponential backoff (1 s up to 30 s); batches are capped at 1000 events and 4 MB, and a batch the daemon refuses (`400`/`413`) is dropped and counted in `dropped`. The queue holds at most 5000 events or 32 MB, oldest evicted first. A process dying of an uncaught exception or unhandled rejection sends the newest 16 MB it holds, blocking for at most 1 second; a graceful exit makes one final attempt capped at about 2 seconds. A run's root span is reported when the run starts, so a run whose process is killed is still listed and turns `interrupted`.
+- `LOUSHO_OBSERVE` accepts `1`/`true`/`on`/`yes`, an `http(s)://` URL, or `0`/`false`/`off`/`no`/`none`/`disabled`/empty (any case). Any other value warns once naming `LOUSHO_OBSERVE` and disables reporting, instead of being posted to as a URL.
+- With `LOUSHO_OBSERVE` pointing at a loopback daemon, `createAgent` captures message and tool content for the daemon by default (`captureContent: false` turns it off). Only the daemon gets it: the agent's own `exporter` (trace files, OTLP or vendor exporters, the built server's OTel export) still records no content unless the agent sets `captureContent: true`. Captured content goes through `redactContent` first (see the scrubber entry under Changed). See [Observability](docs/observability.md#message-and-argument-content-is-opt-in).
+- Each observe daemon writes its own pidfile beside its db (`foo.db` gives `foo.pid`), so two dbs in one folder never share one. `lousho observe start` exits 1 when the port already serves another db, and `stop` refuses to signal when the daemon on the pidfile's port reports another db or answers as a different service. `/health` names the db it serves only to callers on the same machine. A daemon started with `--db foo.db` by an earlier build of this feature wrote the shared pidfile and is not found by the new `stop`: stop it before updating.
+- `lousho observe start` and Studio print the `LOUSHO_OBSERVE` value for the port and host the daemon really uses (`LOUSHO_OBSERVE=http://127.0.0.1:7788` on a non-default port), and the Studio proxy answers `/observe/__target` with the daemon URL reporters should use.
+- `sandbox({ driver: 'isolate' })` runs tool code in an `isolated-vm` V8 isolate (optional peer `isolated-vm`); `defineTool({ sandbox })` opts a tool in, timeouts and OOM map to `sandbox.error` on the tool span. `'docker'` and `'e2b'` driver names are reserved for later drivers.
+
+### Changed
+
+- **Behavior change:** content captured for traces is scrubbed for secrets by default. `redactContent` is `boolean | ((text) => string)`: unset or `true` runs a built-in scrubber over message text, system instructions, tool-call arguments and tool results that replaces API-key shapes (`sk-…`, `lsv2_…`, GitHub tokens, AWS access key ids, the token after `Bearer`) with `[redacted]`; a function replaces the scrubber (text it throws on is recorded as `[redacted]`); `false` records content as is. It catches common key formats, not every secret, so set `captureContent: false` if content must never reach the db. See [Secrets in captured content](docs/observability.md#secrets-in-captured-content).
+- **Behavior change:** sessions end. The daemon marks a session `ended` once none of its runs is open and nothing in it has started or finished for `lousho observe start --session-idle-minutes N` (default 30, `0` turns it off); `ended_at` is the last activity, and a new run makes it `active` again. Sessions in an existing db close on the first sweep that finds them idle, and ended sessions then age out with retention. See [Idle sessions](docs/observability.md#idle-sessions).
+- **Behavior change:** the daemon keeps 30 days of runs by default. On its first sweep after start, and daily after that, it deletes traces whose observations all finished more than `--retention-days` ago, with their scores; a trace with a run still open, and a session still `active`, is kept. Start it with `--retention-days 0` to keep an existing db's history. See [Retention](docs/observability.md#retention).
+- Studio redesign: a new look in light and dark (Settings > Appearance picks Light, Dark or System, plus Compact or Comfortable table density), a left nav that collapses to an icon rail, and a Settings screen in sections (among them Appearance, Provider keys with Set / From environment / Not set, Collector, Keyboard shortcuts). Traces gains **Refresh** and a **Live** toggle that refreshes every 5 seconds, the trace viewer switches between **Tree** and **Waterfall**, Evaluations moves between Scores, Datasets, Evaluators and Annotation queues with tabs, Ctrl/Cmd+Enter runs the Playground, and the Agents canvas opens with the whole graph fitted and the Inspector folded until you select a node. See [Agent Forge](docs/agent-forge.md).
+
+### Fixed
+
+- Studio filter bar: the search box keeps what you type — a trailing space (`tool `) no longer gets reset when the URL echoes the trimmed query; clearing filters or navigating still updates it.
+- Insights runs/day averages over the days an agent was active in the window, so an agent first seen today with 12 runs reports 12/day instead of 12/7.
+- Studio threads: each turn now shows its full input and output (chat messages render as bubbles) instead of the 200-char previews; a turn fetches its trace as it scrolls near the viewport, shows the preview labelled "Preview (truncated)" while loading or if the trace can't be read, and says so when the recorder truncated the turn's I/O.
+- An open run's root start is kept when the reporter's buffer trims or a crash flush cuts to its newest 16 MB, so a run whose child spans overflow the buffer is still listed.
+- Studio Scores and `GET /api/v1/scores?aggregate=eval`: `human` and `online` scores now pass only on a value of exactly 1, so a thumbs-down or an online rule returning 0 (or 0.9) without a comment counts as a failure instead of a pass; `eval` and `judge` scores keep their rule (no failure comment, or a perfect 1), and the table and the eval detail agree.
+- Studio: the command palette and `?` shortcuts sheet now keep every keydown to themselves, so `S` no longer skips the annotation-queue item behind them; Traces, Threads, a Thread, Prompts and the Context Hub recover in place after the daemon restarts instead of staying on "daemon down"; and the queue review's trace tree no longer wraps a row name one letter per line at 1280px.
+- The run inspector shows `error`, not `running`, for a failed step that has no end time.
+- Studio trace viewer: an observation the crash sweep marked `interrupted` (or an open `error` one) now shows as terminal instead of "running" forever; its duration and the waterfall stop at the latest known end and the header clock stops ticking.
+- The observe daemon refuses cross-site browser writes and DNS rebinding on `/api/*`: a loopback-bound daemon answers only loopback `Host` names (403), writes carrying a non-loopback `Origin` (including `null`) or `Sec-Fetch-Site: cross-site` get 403, and a write with a body must be `Content-Type: application/json` (415) — `curl -d` needs `-H "Content-Type: application/json"`. The SDK reporter, CLI and Studio already comply. See [Observability](docs/observability.md).
+- Observe retention (`lousho observe start --retention-days`, `lousho observe prune`) also deletes old traces the sweep marked `interrupted` (a crashed run whose end never arrived); their age counts from when they were interrupted.
+- The observe daemon's online evaluator worker no longer blocks the daemon: it yields between traces, checks each rule's filter against the root row before loading anything else, hands code rules at most 200 observations (attrs over 8192 characters become `{ truncated: true }`) and no scores, and judge jobs claimed by Agent Forge carry the root fields only (`observations: []`).
+- Error text recorded on spans (`error` attributes and the span status message, on runs, LLM calls, tools, resumed runs and flows) goes through the same `redactContent` choice as captured content, so tokens in an error no longer reach traces, exports, evaluators or judge prompts; the built-in scrubber also catches case-insensitive `Bearer`, Stripe `sk_`/`rk_` live and test keys, Slack `xox[abprs]-` tokens, Google `AIza` keys and JWTs. `recordSpanError` and `withSpan` take an optional redactor (default: the built-in scrubber).
+
+### Documentation
+
+- [Agent Forge](docs/agent-forge.md) documents the left navigation, every screen, the deep-link routes and the keyboard shortcuts, with screenshots in `docs/images`; [Observability](docs/observability.md), [CLI](docs/cli.md) and [Evals](docs/evals.md) link to the screens. The screenshots come from an opt-in Playwright spec: `LOUSHO_DOC_SHOTS=1 npx playwright test -c apps/agent-forge/playwright.config.ts docShots`. See [Keyboard](docs/agent-forge.md#keyboard) and [Routes and deep links](docs/agent-forge.md#routes-and-deep-links).
+
+### Security
+
+- Agent Forge's studio server requires its per-launch token on every API route regardless of path case or encoding: `/PLAYGROUND/run`, `/Observe/api/v1/scores`, `//settings/...` or `/%70layground/run` no longer skip the check. Routing is case-sensitive, and every request except a `GET`/`HEAD` of `/health` or the built client needs the token.
+- Agent Forge's `/observe/**` proxy only ever forwards to the `LOUSHO_OBSERVE_URL` daemon: the upstream URL is built from the request's path and query alone, so an absolute-form request line (`GET http://a@evil.example/observe/...`) can no longer point it at another host, and a path that URL parsing would rewrite (`..`, `%2e`, a literal `\`) is refused with 400 instead of reaching a write route the allowlist does not name. The proxy sends `LOUSHO_OBSERVE_TOKEN` as the bearer to a daemon that requires one, and the Playground's "Save as new prompt version" (`POST /api/v1/prompts`) is forwarded instead of answering 405.
+
+## [1.0.0-alpha.29] - 2026-10-21
+
+### Changed
+
+- **Behavior change:** the built node-server and Docker image refuse to start on a non-loopback host when no auth is configured (no `LOUSHO_API_TOKEN`, build token or `auth.ts`), with `LOUSHO_SERVER_UNPROTECTED`. Set a token, add `auth.ts`, bind to `127.0.0.1`, or set `LOUSHO_ALLOW_PUBLIC=1` to serve an open agent on purpose. `lousho build --target=docker` prints the run command with `-e LOUSHO_API_TOKEN=<token>`.
+- The `limits.maxCostUsd` warning for a model with no known price names the model, says the limit is not enforced for it, and shows the `registerModel()` call that fixes it. It is printed once per model instead of on every step.
+- Scaffolded READMEs link to the docs site (`https://lousho.com/quickstart`) instead of the GitHub file on `main`.
+- [Sessions](docs/sessions.md#sharing-a-sqlite-file) has one statement on sharing a SQLite store, used across the docs: several processes on one host and a local disk are fine; network filesystems and multiple hosts are not.
+
+- **Behavior change:** the built node-server and Docker image resume runs a crash left in progress when they start (`agent.recover()`), and check again every 30 seconds until shutdown. Runs paused on an approval or a question are left alone, and a run another replica holds is skipped. `LOUSHO_RECOVER_ON_START=0` turns it off. See [Crash recovery](docs/deployment.md#crash-recovery).
+- **Behavior change:** `createAgent()` and `defineTool()` reject an option key they don't know with `LOUSHO_CONFIG_INVALID` and a suggestion (`requireApproval` → `needsApproval`, `maxOutputTokens` → `modelSettings.maxTokens`) instead of ignoring it. A mistyped `needsApproval` used to run the tool unapproved. Keys set to `undefined` are ignored.
+- **Behavior change:** the workspace file tools deny `.env` and `.env.*` by default as well as `.git`. `.env.example`, `.env.sample` and `.env.template` stay readable. A `deny` list you pass still replaces the defaults.
+- `POST /chat` answers `409` with `Retry-After: 2` and `code: LOUSHO_SESSION_BUSY` when another process or replica is running the session, instead of a `200` stream holding only the error. An `Idempotency-Key` resend that hits a running turn gets the same `409`.
+- Scaffolded agents (`lousho init`, `create-lousho-agent`) set `modelSettings: { maxTokens: 4096 }`, so a first run on a low-credit OpenRouter key no longer fails with "requires more credits, or fewer max_tokens". The generated README explains the error.
+- Error `docs` links point to `https://lousho.com/errors#<code>` instead of the GitHub file on `main`.
+- The Docker image creates `/app/data` owned by `node` and declares it a `VOLUME`, so a fresh named volume works with `LOUSHO_STORE=sqlite:/app/data/lousho.db`.
+- The [Authentication](docs/auth.md) examples read secrets from the environment and fail at startup when they are missing, instead of falling back to a literal secret.
+
+- **Behavior change:** the built node-server (and the Docker image) now guards `POST /channels/<name>` and its approvals route for a channel without `verify` with `LOUSHO_API_TOKEN` / `auth.ts`, the same as `/chat`. Before, such a channel answered anyone even with a token set. Channels that verify their own requests (Slack, Discord, Telegram, GitHub, Teams, `webhookChannel` with a secret, any channel with `verify`) are unchanged, and the start-up log lists each channel route's guard (`self-verified`, `server-auth` or `open`).
+- **Behavior change:** `webhookChannel` replies with `{ sessionId, text, finishReason, approval? }` (plus `approvalPrompt` on a pause), as `httpChannel` does, instead of the full `ExecutionResult`. The full result echoed the system prompt and the whole transcript to the caller. `fullResult: true` restores the old body.
+- Channels answer a turn on a session that another process or replica is running (`LOUSHO_SESSION_BUSY`) with `409` and `Retry-After: 2` instead of a `500`, and report a turn that fails before the request is acknowledged to `onError` with stage `'turn'` (it said `'parse'`).
+- README and [Comparison](https://github.com/LinuxDevil/agent-sdk/blob/995e21b7a835a4c869c1ae0b427fc92b0ee9c000/docs/comparison.md) no longer list ACP and MCP as differentiators, and describe Agent Forge as a local visual console.
+
+- CI is one workflow with two jobs: `ci` (type checks, lint, build, tests with coverage, docs, API and fallow gates, pack-smoke, size check, and a zod 4 type check) and `compat` (the newest peers, `ai` 7 with zod 4, plus the real-Docker sandbox tests). The separate Docker Engine, Agent Forge E2E and weekly registry-smoke workflows and the `ai` 6 / zod 3 matrix entries are gone; `npm run registry-smoke` and `npm run test:e2e:studio` still run locally. When the fallow gate fails, CI now prints its full health and duplication reports.
+
+### Added
+- `GET /ready` on the built node-server and Docker image: `200 {"status":"ready"}` while serving, `503 {"status":"draining"}` once shutdown starts. `/health` is unchanged. See [Deployment](docs/deployment.md).
+- The built server exports OpenTelemetry traces over OTLP/HTTP when `OTEL_EXPORTER_OTLP_ENDPOINT` (or `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`) is set, next to any exporter the agent already has. It loads `@opentelemetry/sdk-trace-node`, `@opentelemetry/resources` and `@opentelemetry/exporter-trace-otlp-http` only then, says how to install them when missing, and honours `OTEL_SERVICE_NAME`. See [Observability](docs/observability.md).
+- `createAgent({ toolErrorMessage })` replaces the text of a thrown tool error (`kind: 'execution'`) before it reaches the model, `tool.error` events and hooks; a sanitizer that throws gives "The tool failed.". See [Tools](docs/tools.md).
+- `lousho init` and `create-lousho-agent` generate an `AGENTS.md` for coding agents (the project's real scripts, conventions and docs links) and a `CLAUDE.md` that imports it.
+- `lousho add` falls back to the registry bundled in the npm package (`registry/dist`) when `registry.lousho.com` and its GitHub fallbacks are unreachable, with a notice that the bundled copy may be older.
+- [Pause, restart and resume](docs/pause-and-resume.md): one tutorial for an approval that waits across a restart, crash recovery, and resending over HTTP.
+- `SECURITY.md`: supported versions, private reporting through GitHub, and the disclosure policy.
+- `httpChannel()` created without `verify` logs one warning that the channel is unauthenticated and its `sessionKey` values are guessable. [Channels](docs/channels.md) shows `verify` in the quick start, and [Deployment](docs/deployment.md) says which routes `LOUSHO_API_TOKEN` guards.
+- `POST /chat` accepts an `Idempotency-Key` header: a resend with the same key replays the finished turn's reply (`Idempotent-Replayed: true`, nothing runs), resumes a turn a crash interrupted instead of appending the message again, and is a `409` (`LOUSHO_SESSION_BUSY`) while that turn still runs. The key is stored on the turn's user message (`metadata.idempotencyKey`), so it survives restarts; `session.pending()` reports it as `idempotencyKey`. See [Resending a turn](docs/deployment.md#resending-a-turn).
+- `fromAiSdkTools(record)` converts Vercel AI SDK tools (`tool({ ... })` or plain `{ description, inputSchema | parameters, execute, needsApproval? }` objects) into Lousho tools, keyed by name: zod and Standard Schemas are kept, `jsonSchema()` wrappers and plain JSON Schemas are converted (their own `validate` still runs), `needsApproval` (boolean or function) pauses the run for approval, and `execute` gets the call id and the run's abort signal. It imports nothing from `ai`, so tools built on `ai` 4 to 7 work with any installed version. New guide: [Migrating from the AI SDK](docs/migrating-from-ai-sdk.md).
+- `lousho eval` without vitest installed now says it runs `*.eval.ts` files through vitest, the directory it searched from, and the install command; [Evals](docs/evals.md) states the requirement up front.
+- `result.usage.delegated.toolErrors`: the tool calls that failed inside a run's sub-agents (and theirs), which the lead's own `result.toolErrors` does not count. `ToolCallContext.onDelegatedUsage` takes the child's `toolErrors` as an optional second argument.
+- The session HTTP API (`createRouteHandler()`, the deployed node server, the Worker, `lousho dev`) writes an SSE comment (`: ping`) after 15 seconds without an event, so proxies and client idle timeouts no longer drop a turn whose model or tool is slow; `heartbeatMs` changes the interval (`0` turns it off). See [HTTP API](docs/deployment.md#http-api).
+- `google/<model>` model strings (e.g. `createAgent({ model: 'google/gemini-2.5-flash' })`) and a `GoogleProvider`, backed by the optional peer `@ai-sdk/google` (`^1.2.0` with `ai` 4, `^3.0.0` with `ai` 6, `^4.0.0` with `ai` 7) and reading `GOOGLE_GENERATIVE_AI_API_KEY`. `lousho init --provider google`, `lousho doctor` (package pairing, key, `--ping`) and the missing-peer install hint cover it. See [Providers](docs/providers.md).
+- An unknown model prefix (`mistral/...`, `xai/...`) now says how to reach the vendor anyway: `openrouter/<vendor>/<model>`, `pi/<vendor>/<model>` when pi serves it, or `fromAiSdk()` with the vendor's AI SDK package. See [Vendors without a prefix](docs/providers.md#vendors-without-a-prefix).
+- `lousho doctor` fails an installed `ai` 5 (AI SDK v5 is not supported) with an upgrade hint to `ai` 6 or 7 and the matching `@ai-sdk/*` majors.
+
+### Fixed
+- `lousho build` works again in a project without the optional `@opentelemetry/*` packages (every fresh scaffold): the OTel exporter added for the built server is loaded only when `OTEL_EXPORTER_OTLP_ENDPOINT` is set, and the build leaves those packages unresolved instead of failing with `Could not resolve "@opentelemetry/api"`. The scaffold end-to-end test now builds the server and checks `/health`.
+- The `httpChannel()` "no verify" warning no longer says the channel is unauthenticated when the built server guards it with `LOUSHO_API_TOKEN` or `auth.ts`, and [Channels](docs/channels.md) shows `webhookChannel`'s trimmed reply.
+- `lousho add` works again when `registry.lousho.com` is unreachable: the fallback now tries the release tag as the repository names it (`1.0.0-alpha.24`), then the `v`-prefixed tag, then `main`. It asked only for `v<version>`, which 404'd.
+- The file tools' `deny` list (`.git` by default) is now also checked where a path really leads: a symlink or Windows junction inside the workspace pointing at `.git` or into it (`gitj -> .git`) let `edit_file gitj/config` rewrite `.git/config` (for example `core.hooksPath`, which runs code on the next git command) and `write_file gitj/PWNED` create files in `.git`. Reads, writes, edits, `list_dir`, and `glob`/`grep` given such a link as `path` are now refused. Providers with links can implement the new optional `FsProvider.realPath(path)`; `NodeWorkspace` does. See [Workspace tools](docs/workspace-tools.md#security-model).
+- `NodeWorkspace.writeFile` (and so `write_file` / `edit_file`) writes a temp file in the same directory and renames it into place, so a process killed mid-write no longer leaves a truncated file. A replaced file keeps its permission bits; a read-only file is still refused.
+- `WorkspaceCheckpoints` stores a file's backup before `write_file` / `edit_file` writes it, not after. A process killed between the write and the backup lost the original: on resume the re-run call backed up the agent's own content, so `rewind()` reported `restored` but put back the agent's version (or, for `edit_file`, recorded nothing). A re-run now keeps the turn's first backup, and rewind treats a file still holding its backed-up content as nothing to undo. `track()` also accepts a `PreparedWorkspaceWrite` (`{ prepare, write }`), which the built-in tools use.
+- `edit_file` re-run after a crash (the edit already in the file: `old_string` gone, a non-empty `new_string` present, also with `replace_all`) now succeeds with "the edit was already applied" and writes nothing, instead of failing with `old_string was not found` and sending the model into a loop. A `write_file` / `edit_file` that leaves the file unchanged no longer records a checkpoint backup.
+- [Sessions](docs/sessions.md) no longer says to call `resume()` before resolving an approval after a restart: `agent.approvals.resolve()` / `streamResolve()` from a fresh process finds the session itself. It and [Build a coding agent](docs/build-a-coding-agent.md) now say how to show a resumed turn's progress (`session.on()`, `onEvent`), and the guide points long coding turns at compaction.
+- MCP tool schemas with OpenAPI's `nullable: true` (any type) now accept `null`; the model's valid `null` was rejected with `ToolArgumentsValidationError`.
+- A failed MCP tool call (server exited, timeout, protocol error) now rejects with `LOUSHO_MCP_CALL_FAILED`, naming `<server>__<tool>` with the MCP error as `cause`, instead of a bare `MCP error -32000: Connection closed`. [MCP](docs/mcp.md) now says stdio `env` is merged onto the MCP SDK's default allow-list, not `process.env`.
+- Flows (consumer harness): a `{{variable}}` holding an object (a `toolCall` result, an MCP result) no longer reaches a prompt as `[object Object]`: an object whose only field is `text` (an MCP tool result) is that text, a raw MCP `{ content }` result its text parts, and any other object or array its JSON. Placeholders take dotted paths (`{{res.user.name}}`, `{{list.0}}`, own properties only), also as whole tool-argument values. An `evaluator` step stores its result in `outputVariable`. See [Template values](docs/flows.md#template-values).
+- Flows: a durable run is saved before its first step, so a run whose first step failed can be `resume()`d instead of failing with `LOUSHO_CHECKPOINT_NOT_FOUND`, whose hint for a flow run now points at `FlowExecutor.execute()` rather than forking session history. A step's checkpoint is saved before its `step-complete` event, so a crash in between no longer re-runs a step reported complete.
+- Flows: an `llmCall` whose model request fails rejects with the same compacted `CompactedLLMProviderError` as an agent run (`LOUSHO_PROVIDER_*` code, `compacted.category`), not the provider SDK's raw `APICallError`, and its `retry` no longer retries a failure marked `retryable: false` (a 401, an exhausted quota, a too-long prompt).
+- A provider answering a streaming request with HTTP 200 and a body that is neither an event stream nor valid JSON (for example a truncated `{"choices": [ {"oops`) no longer ends as a silent empty reply. It now fails as a retryable 502, so `withRetry` retries it and an exhausted retry surfaces as a provider error.
+- A sub-agent with an `output` schema that ran out of steps and gave a valid object in its forced final call is now a `task` result (the object, with a line saying the steps ran out), not a failure telling the lead it gave no final answer - which made leads re-run the task.
+- Sub-agents are held to their lead's token, cost and duration `limits` while they run, counted with what the lead and its other running sub-agents have spent, so parallel sub-agents no longer each spend the lead's whole budget (a lead with `maxCostUsd` could end at several times it). A sub-agent stopped this way reports the limit to the lead. A spend limit stays a hard stop with no forced `output` answer; the finished tool results stay in `result.messages` ([Budgets](docs/configuration.md#budgets)).
+- **Behavior change:** `POST /chat` to a session paused on an approval is a `409` JSON body (`LOUSHO_SESSION_AWAITING_APPROVAL`, with `approvalId` and `approvalIds`) instead of a `200` stream ending in a generic error.
+- A decision on an approval whose winning decision is still streaming is a `409` (`LOUSHO_APPROVAL_CONFLICT`), as docs/auth.md says, instead of a `404`.
+- The session routes' `400` bodies carry a `code`: `LOUSHO_REQUEST_INVALID` (invalid JSON, missing or empty fields), `LOUSHO_APPROVAL_DECISION_INVALID` (an approval body with neither `approved` nor `answer`), `LOUSHO_SESSION_ID_INVALID`.
+- `lousho chat` prints a failed turn with its error code, the provider's failure category and HTTP status, and the fix (`error: User not found. (auth-failure, HTTP 401)` then `[LOUSHO_PROVIDER_REQUEST_FAILED] ...`), as docs/cli.md says, instead of the bare provider message. The terminal chat of a project scaffolded by `lousho init` / `create-lousho-agent` does the same.
+- A `.env` saved with a UTF-8 byte order mark (PowerShell 5.1's `Set-Content -Encoding utf8`) no longer loses its first variable: the `@linuxdevil/lousho` commands and the scaffolded `src/index.ts` drop the mark before parsing. Variables already set in the environment still win.
+- `lousho doctor src/agent.ts` loads a `.ts`/`.js` agent module the way `lousho dev` does instead of failing with `LOUSHO_SPEC_UNSUPPORTED_FORMAT`, and a missing key for the module's provider is a failure. A scaffolded project's `npm run doctor` now runs `lousho doctor src/agent.ts`, so it fails when the agent's key is missing.
+- `lousho doctor --ping` checks OpenRouter at `/api/v1/key`, which needs the key (its `/models` answers without one, so a wrong key passed); a key the provider rejects is now a failure, and a ping of a custom `OPENAI_BASE_URL` says it shows reachability only.
+- `lousho doctor` fix lines use PowerShell syntax (`$env:NAME="<your key>"`) on Windows.
+- The `lousho eval` table shows the scores of passing scored gates (such as `t.check('words', n, atLeast(3))`), not only in `--json`.
+- **Behavior change.** An agent with `output` and tools no longer sends the strict `responseFormat` schema on calls that offer tools: `openai/gpt-4o-mini` via OpenRouter then called tools on every step until `maxSteps` and never answered. `responseFormat` now goes only on calls without tools (an agent without tools, the "answer now" call at `maxSteps`, the repair step); tool-offering calls answer from the schema in the prompt, with the existing parse and repair. `output: { schema, responseFormat: 'always' }` restores the old behavior, and is the default with `promptSchema: false`. `object.delta` events still stream on every step of an `output` run. See [Structured output](docs/structured-output.md#how-it-works).
+- An agent directory built with `lousho build --target=node-server` (or `docker`) can now change who may decide an approval and who may use a session: `auth.ts` may export functions named `authorizeApproval` and `authorizeSession` next to its default auth list, `resolveAgentDir()` returns them, and the built server applies them. Before, the built server always used the defaults, so a manager could not approve another user's paused call while that user could approve their own. See [Who may decide an approval](docs/auth.md#who-may-decide-an-approval).
+
+### Documentation
+
+- Tool idempotency: `toolCallId` and `ctx.approval.id` identify one call; after a crash the model may retry with a new call, so side effects that must happen once need a key from your own data. New guidance for ending a run after a rejected approval, and for extract-then-approve-then-act with structured output.
+- [Durable execution](docs/durable-execution.md#recovering-after-a-crash): `agent.resume()` resolves with a result, not a stream (stream a resumed run with `agent.stream([], { sessionId })`), and `agent.pending()` also lists runs still active in another process. [Installation](docs/installation.md#typescript-settings): TypeScript 6+ projects need `"types": ["node"]` for the SDK's declarations.
+
+## [1.0.0-alpha.24] - 2026-10-17
+
+Two fixes on top of 1.0.0-alpha.23, published from the release branch.
+
+### Added
+- `model-unloaded` provider error category: "model is not loaded/unloaded" replies from a local server (LM Studio, Ollama) classify as retryable, so `withRetry()` rides out the server evicting or still loading a model.
+- A run ended by `maxSteps` or a budget without a final answer now returns explanatory text instead of an empty string.
+
+### Changed
+- MCP: a warning is logged when a server's tool schemas exceed about 16K tokens (deferred tools excluded). A server marked `optional: true` connects in the background, so a slow or failing optional server no longer blocks the first `send()`.
+
+### Fixed
+- Compaction: when the provider rejects a request for context size and the configured `contextWindow` is larger than the model's real one, the error is marked on the transcript and folded into it for a retry when a compaction hook exists; the hook compacts under the server's observed window (or the rejected request size when unnamed) for the rest of the run.
+- `toolCalls` of a run continued from a transcript (approval resolve, resume) are collected from its messages, so they no longer disappear from the result.
+- `recall_<slot>` with a query that matches nothing now says the slot is not empty, instead of returning a bare `[]` that contradicted the injected `<memory>` block.
+- The guardrail starter set's `ignore-instructions` signal also catches "ignore these/those/her/his/their/our instructions" and "ignore your instructions", without a qualifier such as "previous".
+
+## [1.0.0-alpha.23] - 2026-10-16
+
+The same tree as 1.0.0-alpha.21; no code changes. create-lousho-agent
+0.1.2-alpha.7.
+
+## [1.0.0-alpha.22]
+
+Never published to npm (the registry goes from 1.0.0-alpha.21 to
+1.0.0-alpha.23); no changes.
+
+## [1.0.0-alpha.21] - 2026-10-16
+
+Everything merged to `main` after 1.0.0-alpha.20. create-lousho-agent
+0.1.2-alpha.6.
+
+### Breaking
+- Removed the deprecated trigger adapters and their types from `@lousho/build-ai-agent/triggers`. `TriggerAdapter`, `TriggerRegistry`, the `WebhookAuth` helpers, `verifySlackSignature()` and `parseCronExpression()` stay. Migration (see [Migrating from triggers](docs/upgrading.md#migrating-from-triggers)):
+  - `WebhookTriggerAdapter`, `WebhookTriggerAdapterOptions`, `WebhookTriggerHandle` -> `webhookChannel()` with `mountChannels()` (same `auth` option)
+  - `SlackTriggerAdapter`, `SlackTriggerAdapterOptions` -> `slackChannel()` with `mountChannels()`
+  - `CronTriggerAdapter`, `CronTriggerAdapterOptions`, `CronIntervalOptions`, `CronExpressionOptions` -> `defineSchedule()` with `startSchedules()` (no `intervalMs`: use a cron expression such as `*/5 * * * *`)
+
+### Added
+- `agent.recover({ intervalMs?, signal?, onError?, onRecovered? })` finishes interrupted durable runs in the background: it polls `agent.pending()` and resumes each `'in-progress'` run once its crashed holder's run lease is free, leaving approval and question pauses (and non-retryable failures) alone; returns `{ done, stop() }` ([Durable execution](docs/durable-execution.md#recovering-automatically)).
+- An agent directory's config accepts `retry` (`agent.json`: `maxRetries`, `timeoutMs`, `backoff`, ...) and, in an `agent.ts` code config, `output` (a Standard Schema), so `lousho dev`/`chat`/`build ./agent` keep structured output and per-attempt timeouts. `loadAgentDir(dir, { output })` now returns `SimpleAgent<Infer<output>>`, so `result.object` is typed.
+- `result.toolErrors` counts a run's tool calls that ended in an error result, so an answer the model gave after its tools failed (`finishReason: 'stop'`) is no longer indistinguishable from a good one; `limits.maxToolErrors` stops the run (`'budget-exceeded'`, `budget.limit: 'maxToolErrors'`) once that many failed. See [Failed calls in the result](docs/tools.md#failed-calls-in-the-result).
+- An error a run rejects with carries what the run spent as `error.usage` (also on `PropagatingToolError` and your own errors). A sub-agent's spend is saved on its lead's checkpoint as it runs, so a lead resumed after a crash mid-sub-agent counts the interrupted sub-agent's model calls.
+- A `send(msg, { sessionId })` or `agent.resume()` run that rejects records `lastError` and `attempts` on its checkpoint, and `agent.pending()` lists them (`attempts` is new for session turns too), so a restart loop can tell a failing run from a crashed one.
+- Docs: a webhook-redelivery recipe (run a job once by checking the checkpoint before `send()`), a note on structured-output schemas that mirror a side-effect tool, and the `fetch` option for proxies and fault injection on every provider class.
+
+### Changed
+- **Behavior change:** the fallback default model for the OpenAI, OpenRouter and Pi providers (what `lousho init` scaffolds and what runs when no model is configured) is now `gpt-4.1-mini` instead of `gpt-4o-mini`; set `model` or `LOUSHO_MODEL` to keep the old one. README and Quick Start use it. Added `docs/comparison.md`; CI also runs on pushes to `main`; README no longer claims unverifiable live validation.
+- `createAgent({ prompt })` is deprecated: `instructions` is the one documented name (`prompt` still works as an alias, marked `@deprecated`). Docs, README and examples now use `instructions`, and `npm run docs:verify-snippets` fails a docs snippet that passes `prompt` to `createAgent`.
+- The published package no longer ships source maps (`dist/**/*.map`, ~3.7 MB; tsup no longer emits them). The tarball goes from 965 files / 18.9 MB unpacked / 5.0 MB packed to 774 files / 15.1 MB / 4.3 MB. `src/` still ships because `lousho build` bundles the SDK from it. `npm run size-check` now guards the tarball size and a hello-world bundle against `scripts/size-budget.json`.
+- `docs/comparison.md` is now a dated (October 2026) per-competitor table covering the AI SDK 7, Mastra, LangGraph.js, OpenAI Agents SDK, Claude Agent SDK, eve, VoltAgent and open-harness, and the README's differentiator list keeps only claims still true against them.
+
+### Fixed
+- **Behavior change:** a session without a `checkpointStore` that pauses on an approval now keeps an in-process pause marker, so a second `send()` / `stream()` / `compact()` on it throws `SessionAwaitingApprovalError` (`LOUSHO_SESSION_AWAITING_APPROVAL`) — before, the new turn ran over the truncated transcript and the later `approvals.resolve()` silently overwrote the committed turn. The marker covers `send`, `stream`, `compact`, `clear`, `pending` and `discardPending`, and is dropped when the turn resolves, aborts, fails or is discarded. Across processes there is still no durable marker: a session that may pause needs a `checkpointStore`.
+- Session turn checkpoints no longer reuse a `<id>.turn-<n>` id after `compact()` shortened the transcript: the `n` now comes from a persisted high-water mark (`<id>.turn-counter`), so `fork()` can no longer resolve a stale checkpoint of a different turn, and `prune()` keeps the counter while its session's paused run needs it.
+- Memory: two parallel `remember_<slot>` calls with an `itemKey` no longer store duplicate items — the check-and-replace is serialized per memory key. A remembered item is capped at 20,000 characters and the injected `<memory>` block at 20,000 (each line 4,000), so one item can no longer outgrow the context window of every later run.
+- `lousho add <kit> --dir <new-dir>` no longer creates the target directory before the install is decided: a non-interactive refusal, a manifest refusal or a 'no' at the prompt now truly leaves "nothing was written" — before, an empty directory stayed behind.
+- A malformed or truncated provider response before any output (the AI SDK `JSONParseError`/`TypeValidationError` on a garbage first SSE chunk, or a stream cut by `UND_ERR_SOCKET` / "terminated" / "other side closed", also inside a `cause`) is now retried by `withRetry()` like other network errors, with a `provider.retry` event, instead of ending the turn with `LOUSHO_PROVIDER_REQUEST_FAILED`. Nothing is retried once text or a tool call was emitted.
+- `lousho build --target=node-server` now lists the provider package in the build's `package.json` when the agent module (or a code `agent.ts`) uses an SDK provider class such as `new OpenRouterProvider(...)`, not only a literal `model: '<provider>/...'`, and warns when it detects no provider. `docs/deployment.md` no longer tells readers to call the internal `createDeployedServer()`; it shows a graceful shutdown for a self-served agent.
+- Errors and cost (consumer harness): a session turn that fails outside its run (e.g. `LOUSHO_SESSION_BUSY`) now sends the error's stable `code` on the `error` event, with the message still sanitized; `provider.fallback` events carry `fromModel` / `toModel`, so two providers of the same name (both OpenRouter) can be told apart; and one step with no known price no longer discards the run's cost: `usage.costUsd` keeps the priced steps' sum and `usage.costPartial: true` flags it (also on `byModel` entries, `delegated` and `step.done` / `run.done` usage), and `limits.maxCostUsd` is enforced on that partial total.
+- `grep` no longer times out on a cheap pattern over a slow disk: the 10 s budget now counts only the time spent matching, not reading files. The timeout error says whether the pattern is slow or the many files used the budget, and how many files were scanned. New `createFsTools({ grepTimeoutMs })`.
+- Permissions: a `permissions` rule naming a tool the agent does not have (a typo such as `write_flie`, so a `deny` silently guarded nothing) now logs a `[lousho]` warning at `createAgent()` with a "did you mean", and `lousho doctor <agent-dir>` reports it as a warning. Wildcards, globs, patterns and agents whose tools may arrive later (MCP, tool search, sub-agents) are only checked for near-miss typos.
+- `lousho init` / `create-lousho-agent` template: `npm run dev` with piped input (`printf 'hi\n' | npm run dev`) no longer exits before the reply; it streams the reply and exits when the turn is done.
+- `lousho eval`: the "with soft failures" total (`softFailed` in the JSON summary) also counts cases that failed a gate or threw; the JUnit report keeps their soft failures as `<system-out>` notes.
+- Sessions: a checkpointed turn whose first model call fails (a 5xx after retries, an exhausted 429, a malformed response) no longer loses the user's message. The turn is kept as an `in-progress` pending turn (new `Checkpoint.unstarted`), so `pending()` and the route's `GET` show it, and the next `send()` / `resume()` runs it again with the message in the transcript once. Over the session routes, that stored turn claims the session for its caller.
+- `lousho eval --replay` / `--record` skip a `mockModel()` provider: a scripted mock needs no network, so a mock eval no longer fails with `no cassette ... [LOUSHO_CASSETTE_INVALID]`.
+- `limits.maxCostUsd` no longer logs "cost limit is not enforced" on runs that use `mockModel()`, which has no price.
+- `lousho doctor` lists optional packages the agent does not use as one info line instead of a warning each.
+- Docs: `fileMemory({ dir })` in an agent directory's `memory/*.ts` resolves against the working directory (anchor it to the module); `lousho mcp` takes an agent directory; running `create-lousho-agent` from a local tarball; `lousho dev`/`chat` cannot pass run metadata.
+- Flows: a durable run (`checkpointStore` and `runId`) holds a run lease, like an agent run: a concurrent `FlowExecutor.execute()` or `resume()` of the same `runId` (in this process, another process or through another store object) is refused with `LOUSHO_SESSION_BUSY` and runs nothing, instead of running the remaining steps twice. A lease left by a crashed process expires, so the run can still be resumed. See [Durable runs](docs/flows.md#durable-runs).
+- Flows: a `toolCall` argument that is exactly `'{{name}}'` or `'$name'` passes the variable's value (a number, an object) instead of its text, so `{ n: '{{n}}' }` works with a `z.number()` tool. Mixed strings are still interpolated as text. See [Argument values](docs/flows.md#argument-values).
+- Flows: a `step` node (`StepNode`) fails with a message naming the supported way to run a `createAgent()` agent in a flow (a tool that calls `agent.send()`). See [Running an agent in a flow](docs/flows.md#running-an-agent-in-a-flow).
+- Sub-agents: a sub-agent's own `memory` works when the lead's `task` tool runs it (recall in its system prompt, its `remember_<name>` / `recall_<name>` tools), scoped by the lead run's `sessionId`, `metadata` and `principal`; before, its slots were silently ignored there. New `subagentOptions: { continuation: false }` leaves `taskId` and `mode` out of the `task` tool, and the error for another sub-agent's `taskId` tells the model to omit it for a new task. See [Sub-agents](docs/sub-agents.md#continuing-a-task).
+
+### Security
+- **Behavior change:** the file tools from `createFsTools()` (`read_file`, `list_dir`, `glob`, `grep`, `write_file`, `edit_file`) refuse any path with a `.git` segment (`.git/config`, `./.git`, `a/../.git`, `.GIT`, a worktree's `.git` file; on Windows also 8.3 names such as `GIT~1`) with a `WorkspaceError`, and `glob`, `grep` and `list_dir` leave `.git` out of their results. `.git/config` can hold a CI checkout token (`http.<url>.extraheader`) and a worktree's `.git` names a host path. The new `deny` option sets the names (default `['.git']`; `[]` turns it off). The `shell` tool is not path-filtered. See [Security model](docs/workspace-tools.md#security-model).
+- `lousho build <dir> --target=node-server|docker` no longer copies an agent directory's `.env` files or its `.lousho/` session store (real user transcripts) into `dist/` and the Docker image. Only the files the server reads are copied: `instructions.md`, `instructions/`, `skills/` and a JSON/YAML config, in the directory and each sub-agent; `.env*`, `.lousho`, a JSON/YAML config's `store.dir`, `.git` and `node_modules` are skipped at any depth. `dist/` is emptied before each build so sessions a previous build's server wrote there are not resurrected, and the generated `.dockerignore` also lists `**/.env`, `**/.env.*` and `**/.lousho`. Rebuild and redeploy images built from an agent directory with an earlier version. See [Deployment](docs/deployment.md#agent-directories).
+- `createRouteHandler()`'s UI stream (`POST <base>/ui`) and framework hook route (`POST <base>`) now enforce the documented 1 MB body cap (`413`) like `POST /chat` does; they previously buffered the full body via `request.json()`.
+- A channel approval decision now binds to the session recorded in the approval's own durable snapshot, not the `sessionKey` the caller sends, so a request carrying a foreign session key can no longer resolve another conversation's pending approval.
+- `POST /chat/:sessionId/approvals/:id` checks the approval's kind after authorization: `answer` only decides question approvals and `approved`/`note` only tool approvals; a mismatched body is `400 LOUSHO_APPROVAL_KIND_MISMATCH` instead of silently approving a tool.
+- `POST /chat` message arrays may carry `role: 'user'` only; client-supplied `system`, `assistant` and `tool` messages are dropped before the turn (content-part arrays without roles are unaffected).
+- **Behavior change:** `crossSiteRequest` no longer trusts `X-Forwarded-Host` or `Forwarded: host=` as same-site evidence — those headers are client-controllable. A request is same-site when its `Origin` matches the server's actual `Host` (or an `allowedOrigins` entry); behind a trusted proxy, set `allowedOrigins` to the public origin.
+- Session-owner bookkeeping adds a per-principal cap (1024 claimed sessions per caller) under the global 100,000 LRU, so one caller flooding new session ids can no longer evict everyone else's ownership claims.
+- `webhookChannel()` only defines `verify` when an `auth` option is configured; an unauthenticated webhook is treated as an open channel and its cross-site requests are refused like `httpChannel()`'s. The deprecated `WebhookTriggerAdapter` treats a missing `verify` as success.
+- Malformed percent-encoding in route parameters (`%zz`, truncated UTF-8) answers `400` instead of a `URIError` 500 on `/chat/:sessionId/...` and channel approval routes.
+
+## [1.0.0-alpha.20] - 2026-10-16
+
+create-lousho-agent 0.1.2-alpha.5.
+
+### Security
+- **Behavior change:** with route auth and no `authorizeSession`, a session belongs to the first principal that sends it a turn (reading claims nothing); any other principal gets `403 LOUSHO_SESSION_FORBIDDEN`. Owners are kept in memory per agent for the 100,000 most recently used sessions, so a stored session whose owner is not on record (after a restart, on another replica, past the cap) is refused to everyone: pass `authorizeSession` for multi-instance deployments and durable stores, or `authorizeSession: () => true` for the old behavior. A route behind one bearer token has a single caller and checks no owner. `POST /chat` with an empty `input` (and `POST <base>/ui` without a user message) is a `400` that claims nothing, and a turn that stores nothing drops its claim, so an owner can no longer be evicted by flooding. See [Who may use a session](docs/auth.md#who-may-use-a-session).
+- **Behavior change:** `POST /chat/:sessionId/approvals/:id` answers `404` unless the approval belongs to that session, and by default only the caller the paused run acts for may decide it; allow others (a supervisor) with `authorizeApproval`.
+- **Behavior change:** the session routes (`createRouteHandler()`, `createDeployedServer()`, the Worker, `lousho dev`) refuse cross-site requests: a POST whose `Origin` is neither the server's own (`Host`, `X-Forwarded-Host` or `Forwarded: host=`) nor in the new `allowedOrigins`, or that the browser marked `Sec-Fetch-Site: cross-site`, is `403 LOUSHO_REQUEST_FORBIDDEN`, and a POST body must be `Content-Type: application/json` (`415 LOUSHO_UNSUPPORTED_MEDIA_TYPE`). Requests without `Origin` are unaffected. Opt out with `allowedOrigins: ['*']` and `requireJsonBody: false`; `allowedHosts` refuses unlisted `Host` headers. Built servers read `LOUSHO_ALLOWED_ORIGINS`, `LOUSHO_ALLOWED_HOSTS` and `LOUSHO_REQUIRE_JSON_BODY=false`. The React/Vue/Svelte bindings no longer send `Content-Type` twice and accept a `Headers` instance. See [Cross-site requests](docs/auth.md#cross-site-requests).
+- **Behavior change:** `lousho dev` answers `403` to a non-loopback `Host` (off loopback: an IP address or the `--host` name; new `--allowed-hosts a,b`), so a web page cannot reach it through DNS rebinding, and warns when bound off loopback. A channel without `verify` refuses a cross-site browser request (`403`), and `httpChannel()` without `verify` requires a JSON body (`415`).
+- **Behavior change:** the Cloudflare Worker refuses every `/chat` route (`403 LOUSHO_REQUEST_FORBIDDEN`) when no `LOUSHO_API_TOKEN` secret is set; set the var `LOUSHO_ALLOW_OPEN_SESSIONS` (or the earlier `LOUSHO_ALLOW_OPEN_TRANSCRIPTS`) to `"true"` to allow it. `/health`, the OAuth callback and channels stay open, and `lousho build --target=cloudflare-worker` warns about the secret.
+- **Behavior change:** `WebhookTriggerAdapter` binds `127.0.0.1` by default (was `0.0.0.0`), refuses a non-loopback `host` without `auth` unless `allowUnauthenticated: true` (`LOUSHO_TRIGGER_INVALID`), refuses a foreign `Host` or an `Origin` on loopback without `auth`, caps bodies at 1 MB (`413`) before auth, and no longer echoes handler errors. See [Webhook](docs/triggers.md#webhook-authentication).
+- **Behavior change:** MCP tools ask for approval by default (`approval: 'always'`); a server's `readOnlyHint` / `destructiveHint` count only with `approval: 'annotations'`. An MCP tool named like a local tool is refused with `LOUSHO_CONFIG_INVALID` instead of replacing it. See [MCP](docs/mcp.md#approval-for-mcp-tools).
+- Flows: a `toolCall` step passes the same gate as an agent's tool call (`permissions`, `permissionMode`, `onPermissionDecision` and a new `approve` option on `FlowExecutionContext`); a call that needs approval and is not approved fails with `LOUSHO_FLOW_TOOL_DENIED` without running. Step arguments are validated against the tool's schema (`LOUSHO_TOOL_ARGS_INVALID`) and a flow's declared `inputs` are enforced (`LOUSHO_VALIDATION_FAILED`). See [Flows](docs/flows.md#tool-calls).
+- Registry: the approval an install receipt requires for an `exec`, `needsApproval` or unattested item can no longer be waived from inside the agent directory (an `allow` rule, `acceptEdits` or the directory's own `approve` file); only a person or an `approve` passed in code decides it. Receipts now also cover a kit's `subagents/<name>/` tools. `coding-kit` / `coding-pi` refuse writes to their own config, tools and `.git/`, drop `git diff` from the shell allowlist and accept `node --test` only with test file paths (reinstall with `lousho add coding-kit --overwrite`). See [Registry](docs/registry.md).
+- Shell tool: an `allow` string pattern refuses arguments that escape the workspace (`..` segments, also in `--flag=../x`, `~`, absolute paths, quoted or escaped forms such as `cat "../x"`, globs that can expand to `..`, and `$`, `{`, `}`), and under cmd.exe `%` and `^` count as shell operators. Use a `CommandRule` or an anchored RegExp to allow such arguments.
+- Agent Forge (`lousho studio`) no longer answers any origin: it sends no CORS headers, refuses a foreign `Origin` or a non-loopback `Host`, and every API and WebSocket call needs the per-launch token printed in its URL. See [Agent Forge](docs/agent-forge.md#access-token).
+- Tracing: `redactContent` defaults to `true`, so prompts, instructions and tool output are no longer written to span attributes or `.lousho/traces` unless you pass `redactContent: false` (or `captureContent: true` for `gen_ai.*` content).
+- The session routes no longer send raw error text to clients: `error` events, `500`s and `provider.retry` / `provider.fallback` events carry the error's `name` and `code` with a generic message, and the full error is logged. Pass `exposeErrors: true` for the old behavior (`lousho dev` does). Channel `500`s no longer echo internal errors either.
+- `fromUIMessages()` (and `POST <base>/ui`) keeps only `user` and `assistant` messages from the client; a client-sent `system` message is dropped.
+- OAuth: a principal without an issuer gets tokens namespaced by its authenticator, so the same id from Slack and GitHub no longer shares a token (docs/oauth.md has the one-time move); `telegramChannel` and `teamsChannel` send a sign-in link only in a 1:1 chat; the `[REDACTED]` net for `ctx.getToken()` tokens also covers thrown errors, object keys, URLs, class instances and base64 forms of the token.
+- `serveMcp` over HTTP validates `Host` and `Origin` against DNS rebinding (new `allowedHosts` / `allowedOrigins`), and loopback checks there and in `WebhookTriggerAdapter` accept exactly `localhost`, `127.x.x.x` and `::1` (`127.attacker.example` passed).
+- The `openrouter` provider without `apiKey` reads `OPENROUTER_API_KEY` and no longer sends `OPENAI_API_KEY` to openrouter.ai.
+- Slack and Discord signatures accept a timestamp at most a minute ahead (was five minutes either way), read in seconds; `discordChannel` refuses timestamps more than five minutes old. `githubChannel({ deliveries })` takes a shared `DeliveryStore` for `X-GitHub-Delivery` replay protection.
+- The `@modelcontextprotocol/sdk` peer range is `^1.31.0` (was `^1.30.1`): 1.30.x is affected by GHSA-6qxp-vccf-f47h, which MCP OAuth relies on.
+- `SubprocessSandbox`: `writeFile()` stays under the new `root` option (`LOUSHO_SANDBOX_PATH_DENIED`, also through symlinks), and containers run as `1000:1000` with all capabilities dropped, `no-new-privileges` and default limits (512 MiB, 256 pids, 1 CPU); pass `user: 'root'` for the old user. See [Guardrails](docs/guardrails.md#sandboxed-tools).
+
+### Changed
+- **Behavior change:** session turns keep the checkpoint history of the latest 10 committed turns (`agent.session({ id, turnHistoryLimit })`; `0` keeps none); storage used to grow with the square of the conversation. Excess history already in a store is deleted over the next commits, also when each turn uses a new process or store object. New `fileStore(dir).prune({ olderThanMs })` returns `checkpointHistory` too; `fileStore()` returns the new `FileStore` type.
+- **Behavior change:** a checkpointed run holds a run lease while it executes (new optional `CheckpointStore.acquireLease()`, `releaseLease()`, `renewLease()`, `saveIfLeased()`; file, SQLite, memory and best-effort KV stores). A second process, replica or store object that sends to the same session, resumes it or resolves its approval gets `LOUSHO_SESSION_BUSY` instead of running its tool calls again, and a stalled holder can no longer overwrite the run that took over. A dead holder on the same host is taken over at once; on another machine 30-60 s after its last heartbeat. Schedule fires are claimed the same way, so replicas fire a tick once. See [Run leases](docs/durable-execution.md#run-leases).
+- **Behavior change:** approvals run at most once: deciding one re-saves the turn as `'in-progress'` with the call in `Checkpoint.startedToolCallIds`, and resuming after a crash mid-call gives it a `kind: 'interrupted'` tool error instead of running it again. Resolving an approval whose run was deleted or replaced fails with `LOUSHO_APPROVAL_ORPHANED` and withdraws it.
+- **Behavior change:** a session turn paused for approval locks the session id: a new turn on it throws `SessionAwaitingApprovalError` (`LOUSHO_SESSION_AWAITING_APPROVAL`) until the approval is decided or `discardPending()` drops the turn.
+- **Behavior change:** a deterministic provider error records `lastError` on the turn's checkpoint, and later calls on that session fail fast with `LOUSHO_SESSION_TURN_FAILED` instead of replaying the failing turn; `resume()` retries it.
+- **Behavior change:** run ids (`send({ sessionId })`, a fork's `newSessionId`) are 1-200 characters of `A-Za-z0-9_.-` on every store and may not end in `.turn-<n>`, `.paused` or `.fire`; `''` is refused. Session ids (`agent.session({ id })`, the routes) stay 1-128 characters of `A-Za-z0-9_-`. The error messages now say which of the two rules applies.
+- **Behavior change:** with a store, tools, `needsApproval`, permission rules and hooks get the session id as `ctx.sessionId`, not the checkpoint key `<id>.turn-<n>` (new `ExecuteOptions.contextSessionId`).
+- **Behavior change:** a model step with several calls that need approval pauses once, on all of them (`result.approvalIds`, `agent.approvals.resolveAll()`); calls that need no approval run before the pause. See [Several calls in one step](docs/approvals.md#several-calls-in-one-step).
+- **Behavior change:** `once()` no longer remembers a yes from a `createAgent({ approve })` callback, and `'defer'` is reserved: an approval note that is exactly `'defer'` defers.
+- **Behavior change:** `approvalTtlMs` and an `ask` rule's `ttlMs` above 100 years throw `LOUSHO_CONFIG_INVALID` (they meant "never expires").
+- **Behavior change:** memory items are keyed `<slot name>#<scope key>`, so two slots on one scope no longer share items. Run `migrateMemoryKeys(slot)` once to copy items stored under the old bare key. See [Memory](docs/memory.md#items-from-before-slot-name-keys).
+- **Behavior change:** a prompt schedule runs every fire in its own session `schedule-<name>-<fire time>` (`defineSchedule({ sharedSession: true })` keeps one shared session), and a fire that does not finish `'stop'` reports the new `LOUSHO_SCHEDULE_RUN_INCOMPLETE`.
+- **Behavior change:** channels without a `store` keep transcripts in the agent's `createAgent({ store })` when it has `sessions`.
+- **Behavior change:** the routes let a session turn run to its end and save it when the client disconnects (`onDisconnect: 'abort'` for the old behavior; `waitUntil` keeps a serverless function alive). An aborted turn keeps the user's input, the tool calls that ran and the partial reply (`metadata: { interrupted: true }`), and its usage counts.
+- **Behavior change:** tool results are capped at `maxToolResultChars` (default `50_000`, `Infinity` for none) for every tool; MCP image/audio/blob data reaches the model as a placeholder and MCP tool descriptions are cut at 2,000 characters.
+- **Behavior change:** a user file part the provider cannot send rejects the call with `LOUSHO_UNSUPPORTED_CONTENT` (under fallback the next provider gets it) instead of a text note; `unsupportedFiles: 'text-note'` keeps the note. See [Multimodal input](docs/providers.md#multimodal-input).
+- **Behavior change:** `createAgent({ provider })` with a built-in or `fromAiSdk()` provider and no `retry` wraps it in `withRetry()` (provider's `maxRetries`, default 2), and `withRetry()` is the only retry layer: the built-in providers turn the `ai` SDK's own retries off (`retry: false` used to send 3 requests, `maxRetries: 3` sent 12).
+- **Behavior change:** a rate-limited call has the code `LOUSHO_PROVIDER_RATE_LIMITED`, and an out-of-credit account (`insufficient_quota`, 402) is the new non-retryable category `quota-exceeded`.
+- **Behavior change:** `OpenAIProvider` sends `store: false` on the Responses API unless `store: true` is set.
+- **Behavior change (types):** `LLMProviderConfig` has no index signature, so a misspelled option is a type error; `LLMProviderRegistry.register()` / `create()` take the provider's own config type (new `BuiltinProviderConfigs`). `ExecutionFinishReason` is a closed union, and an unknown provider finish reason is reported as `'other'`.
+- **Behavior change:** `agent.stream()` rethrows the run's error after the `error` and `run.done` events (`{ throwOnError: false }` for the old behavior).
+- **Behavior change (CLI):** every usage error exits 2 and 1 means a command ran and failed. `lousho eval`, `build`, `dev`, `chat`, `acp`, `mcp` and `doctor` load `./.env`. The fallback registry URL points at the installed version's release tag.
+- **Behavior change:** `connectMcp()` rethrows a server's start failure as `McpStartError` (`LOUSHO_MCP_START_FAILED`, with exit code and the last stderr lines) instead of wrapping it.
+- Evals: `t.maxCostUsd(n)` fails when a run reports no cost (`{ unknownCost: 'skip' }` for the old, now warning, behavior); `judge.model` and `llmJudge()` / `llmCritique()`'s `model` are optional.
+- Pruned tool results leave a stub naming the call and its arguments (`[pruned: search({"query":"deploy"}) result, 18234 chars; already read]`).
+- 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).
+- Cost: built-in prices for more default models (Ollama `llama3` window, OpenRouter variants), cache read/write prices (`cachedInputCostPerMTok`, `cacheWriteCostPerMTok`, `cacheWriteTokens`) and OpenRouter's reported `usage.cost` for `costUsd` and `limits.maxCostUsd`.
+- Approvals: `remember: 'session'` and edited `args` on a decision, `'defer'` from an `approve` callback, `approvalTtlMs` / `ttlMs` deadlines (`expiresAt` on events and UI state), `agent.approvals.list()` across processes (new optional `ApprovalStore.list()`), `agent.pending()` for unfinished runs (new optional `CheckpointStore.list()`), and `resumedAfterApproval` on tool-call hook contexts. See [Approvals](docs/approvals.md) and [Recovering after a crash](docs/durable-execution.md#recovering-after-a-crash).
+- Routes: `authorizeSession` and `authorizeApproval` on `createRouteHandler()` / `createDeployedServer()`; approvals report their `sessionId` and error events their `code`. Built node and Docker servers drain on SIGTERM (`shutdown({ timeoutMs })`, `LOUSHO_SHUTDOWN_TIMEOUT_MS`). Channel routes decide each call of a multi-call pause and accept a `sessionKey` after a restart.
+- Flows: durable runs (`checkpointStore` + `runId`, `FlowExecutor.resume()`), pausing for approval (`status: 'awaiting-approval'`), per-node `retry` and `timeoutMs`, cancellation through `signal`, and `usage` on the result. See [Flows](docs/flows.md).
+- Structured output: partial-object streaming (`object.delta`, `partialObject` in the UI bindings), `result.outputRepaired`, `{ schema, promptSchema: false }`, a forced no-tools answer when `maxSteps` or `limits.maxSteps` runs out, and `outputError.kind: 'truncated'`. Unions, records, tuples and optional fields now work on strict endpoints. See [Structured output](docs/structured-output.md).
+- Memory: `expose: { forget: true }`, `itemSchema` / `itemKey` upserts (new optional `MemoryProvider.upsert()`), `memoryKey()`, de-duplicated `add()`, and `migrateMemoryKeys()`. See [Memory](docs/memory.md#correcting-memory).
+- MCP: `optional: true`, `cwd`, `stderr`, `connectTimeoutMs`, `timeoutMs`, `tools: { include, exclude }`, per-call `approval({ args })`, `onToolsChanged` and `McpConnections.reconnect()`. See [MCP](docs/mcp.md).
+- Observability: `invoke_agent` spans carry the request model and token totals (`agentUsageTotals: false` leaves them off), `legacyAttributes: false`, `parentSpanId` on `send()` / `stream()`, retry attributes on `chat` spans, sub-agent names on their spans, and compaction calls as counted `chat` spans. See [Observability](docs/observability.md).
+- Tools and sub-agents: `defineTool({ timeoutMs })`, `subagentOptions: { background: false }`, `read_skill_file` for skill folders, `ToolDescriptor.transient`, `CommandRule` objects for the shell tool's `allow` / `deny`, and an optional `ShellProvider.shell` that tells the model which shell runs its commands.
+- Compaction: `reserveOutputTokens` and `onCompaction` on the object form; `GenerateHookContext.generate()` for counted side calls.
+- Evals: sub-agent tool calls in trajectory evals, `SendOptions.onEvent`, `repeat` / `passAt`, `{ agent }` for `setProviderInterceptor` callbacks, `lousho eval --timeout` and `defineEval({ timeoutMs })`, and `recordReplay({ rerecordHint })`. See [Evals](docs/evals.md).
+- 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.
+- OAuth: concurrent `ctx.getToken()` calls share one refresh, and a refused refresh no longer deletes a newer token.
+- Approvals and memory: a run resumed after an approval or a crash keeps its memory tools and the scope it paused with; memory stays on after a handoff; recall errors skip the slot with a warning; invalid scopes fail with `LOUSHO_MEMORY_INVALID`; keyword recall matches whole words; `<memory` tags in item text are escaped; `recall_<name>` returns scores and metadata.
+- Providers on `ai` 4, 6 and 7: tool errors are no longer wrapped twice on `ai` 7, malformed or truncated tool-call JSON reaches the model as a repairable `LOUSHO_TOOL_ARGS_INVALID` error (light repairs are tried first; `tool.start` has `rawArgs`), prefixed tool names (`functions.read_file`) resolve, unknown tools suggest the closest name, duplicate tool-call ids both run, a completion sent to a streaming request is replayed, mid-stream and `finish_reason: "error"` failures become retryable 502s, a stream that fails before any output is retried, and unset `temperature` / `maxTokens` are left out. `withFallback()` keeps its state per call, so concurrent calls no longer misreport fallbacks or book cost under the wrong model, and `withRateLimit()` over `withRetry()` streams reports the final attempt and holds its slot until the retried stream ends.
+- Provider errors: local runtimes' context overflows are `context-length-exceeded`, refused connections name the URL, status and message are read together, nested OpenRouter reasons are shown, a long `Retry-After` fails at once instead of sleeping, negative hints are ignored, and compacted errors keep their category through `createAgent()`. A missing provider package fails with `LOUSHO_PEER_MISSING`, and the routes send its `npm install` command to the client.
+- Provider features: `reasoning` reaches more models and warns once when it is dropped; image MIME types are sniffed; `OpenRouterProvider` honours `baseURL` and `OllamaProvider` sends `headers` and `apiKey`; `supportsTools()` knows current models; registered providers work in model strings; retired fallback models are replaced; price lookup handles OpenRouter spellings; the forced answer at `maxSteps` works on Claude.
+- Runs: abort no longer waits on a provider or tool that ignores the signal (`finishReason: 'aborted'`, `result.abortReason`; `mockModel` honours `signal`), aborted streams keep their text, a throwing event listener or trace exporter no longer fails the run, tool results with cycles, BigInts, Maps or Sets serialize, `send(result.messages)` does not repeat the system prompt, `send([])` throws `LOUSHO_CONFIG_INVALID`, a `finish_reason: tool_calls` reply without calls ends `'stop'`, a `load_skill` tool that clashes with `skills` throws, `maxSteps` must be a whole number >= 1, and handoffs work on local models and Anthropic (no mid-conversation system message).
+- Structured output: the repair and forced-answer prompts stay out of transcripts, near-miss replies (prose, `<think>` blocks, fenced JSON) are accepted without a repair call, a reply that repeats the schema gets a clearer repair message, and unsupported root unions or zod 4 `z.date()` fields throw a `ConfigurationError` naming the fix. `defineTool()` rejects inputs no model can satisfy and accepts `z.preprocess` dates on zod 4.1+.
+- Compaction: summarizing splits oversized histories, counts tool definitions and the output schema, warns when it falls back to a 128,000-token window for an unknown model, caps `protectedTokens` at half the threshold, retries the summarizer after a rejection, counts its call in usage and budgets, and reports `appliedStrategy`.
+- Sub-agents and handoffs: dynamic sub-agent config functions get the lead's `sessionId`, `metadata` and `principal`; a failed sub-agent's spend counts; truncated answers say so; agent-directory and Worker `subagents/` run as native sub-agents; a handoff target's `toolSearch` applies.
+- Schedules: a fixed-hour cron job in a spring-forward gap runs once after the gap instead of being skipped.
+- Flows: a failed `parallel` branch aborts its siblings, `forEach` variables are per iteration, unnamed steps get unique ids, and `resume()` refuses a changed flow (`LOUSHO_FLOW_CHANGED`).
+- MCP: `Not connected` counts as a dropped connection and reconnects, `tools/list` follows every page, dropped servers report `'failed'` with their stderr, calls honour abort, text-only results are sent once, tool names are made valid for every provider, object schemas with a sibling `oneOf` keep their shape, `agent.ready()` reconnects after `close()`, and `serveMcp()` over HTTP cancels the run a client cancels or abandons (matched by its new `Mcp-Session-Id`) and rejects its pending approvals. `serveAcp` keeps serving after a malformed JSON line.
+- Channels: redelivered webhooks run once (Telegram, GitHub, Slack), concurrent decisions on one approval decide it once (`409 LOUSHO_APPROVAL_CONFLICT`, also on the routes), `webhookChannel` authenticates on Fetch hosts and its pause replies carry the prompt, `githubChannel` ignores `/approve` for unknown approvals, and channel `metadata` reaches the run. `POST <base>/ui` answers 400 for an invalid id, and `auth: ''` is `LOUSHO_AUTH_CONFIG_INVALID` on `createRouteHandler()` and `serveFetch()`.
+- UI bindings (React, Vue, Svelte): remote mode keeps one session across turns, a stream that ends early becomes an error, each step starts a new paragraph, abnormal endings set `status: 'error'`, React gains `reset()`, server error messages are kept, Svelte no longer aborts on a transient subscribe, `formatUsage()` shows small costs, and `parseEventStream()` joins multi-line `data:` fields.
+- Tracing and OpenTelemetry: open spans are bounded without losing parents, queued background sub-agents stay in the lead's trace, background sub-agent cost rolls up, and `execute_tool` spans carry the error message.
+- Evals: replay matches calls by request, sub-agent cassettes are named after the agent, cassette names include a hash of the case label, re-recording unchanged exchanges leaves no diff, tool order no longer breaks replay, reasoning and full usage are recorded, judge scores parse more formats (the last `SCORE:` wins) and judges see the user's input at temperature 0, `lousho eval` gives live cases 10 minutes and its reports are never empty when vitest fails.
+- CLI: `lousho dev` reloads CommonJS tool files and recreated folders, tool files no longer print `MODULE_TYPELESS_PACKAGE_JSON`, TypeScript syntax that type stripping cannot erase gets an error suggesting `--experimental-transform-types`, every agent command loads `tools/*.ts` of an installed project (one ESM build, shared brands, `instanceof` across ESM and CJS copies), `lousho build` reports bundling failures as `LOUSHO_DEPLOY_FAILED`, warns about missing provider packages, merges an existing `wrangler.toml` (new default `compatibility_date` `2026-09-01`), no longer needs unused provider packages for a Worker and prints where it wrote, Docker images run as `node`, `lousho doctor` and `lousho mcp` accept agent directories, `lousho add` checks flags and target directories up front and falls back to GitHub when the default registry is down, `lousho init` templates and Windows instructions are fixed, `init` says when the provider's API key is missing and git-ignores an `--sdk-path` tarball, and help texts and messages are clearer.
+- Agent directories: every `createAgent()` override passed to `loadAgentDir()` is forwarded, `mock/<name>` models work from every entry point, and import failures throw `LOUSHO_AGENT_DIR_INVALID` with an install hint. `loadSkills()` skips a loose `README.md`.
+- Workspace tools: `grep` refuses catastrophic regexes and runs with a time budget, `edit_file` refuses non-UTF-8 files instead of corrupting them, and `tool_search` ranks synonyms and word families.
+- Agent Forge: agents are read from and written to `.lousho/agents/`, narrow screens and keyboard and screen-reader use work, invalid names and imports show errors instead of a blank page, finished runs report `done`, and several drawing and status glitches are fixed.
+- Packaging and types: ESM consumers get `.d.mts` declarations (plus `typesVersions` for `node10`), declarations type-check with `skipLibCheck: false` on zod 3 and 4, the pi peers are caret ranges, `llms-full.txt` no longer ships and the Worker entry has no source maps.
+- Docs: corrections throughout (sessions vs runs under one id, schedules, nextjs approvals, memory, `engines.node`), the snippet check now also runs every snippet that builds its own mock provider and checks fences indented in lists, and the ops-pipeline example works as described.
+- A checkpointed session turn that stalled past its run lease and then failed for good no longer stamps its `lastError` (`retryable: false`) on the checkpoint of the process that took the turn over, which bricked that turn forever with `LOUSHO_SESSION_TURN_FAILED`: the session now holds the turn's run lease itself (handed to the run as `HELD_RUN_LEASE`) and `recordFailure()` writes through `RunLease.save`, whose fenced save writes nothing once the lease is lost.
+- `agent.send(msg, { sessionId })` and a fresh `agent.session({ id })` no longer run beside a session turn that waits on an approval when its `<id>.paused` marker was never written (a crash or a send between the executor's awaiting-approval checkpoint and `markPaused()`): `pausedSessionTurn` now also scans the store's `<id>.turn-*` checkpoints for `status: 'awaiting-approval'` when the marker is absent, on stores that implement `list()`.
+- A streamed tool call whose deltas repeat its `id` while omitting `index` (the OpenAI-compatible / Gemini-proxy servers the tool-call id rewrite exists for) stays one call: each repeat no longer mints a `call_1_2`, `call_1_3`, … id that split the arguments JSON across phantom calls none of which parses; the call's slot in the delta's `tool_calls` stands in for the missing `index`.
+- A non-streamed request whose body carries a nested `"stream": true` (a `providerOptions` passthrough, tool arguments, gateway metadata) no longer has its JSON reply rewritten into an SSE stream the consumer cannot parse: whether a request asked for streaming is read from the parsed top-level `stream` field instead of a regex over the raw body.
+- Session routes: two concurrent first-touch turns on one unowned session no longer both pass the owner check - the claim is atomic now, so the loser is refused (`403 LOUSHO_SESSION_FORBIDDEN`) instead of streaming a turn inside the winner's session; a claim lost while a turn ran clears what it stored and ends the stream on the same coded error.
+- 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.
+- 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, 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.
+- 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.
+- 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 `@linuxdevil/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
+
+Everything published from 1.0.0-alpha.15 (2026-10-06) through 1.0.0-alpha.19
+(alpha.17 on 2026-10-07, alpha.18 and alpha.19 on 2026-10-08). Most of it was
+prepared on `main` under the version number 1.0.0-rc.0, which was never
+published. Upgrading from an earlier `1.0.0-alpha.*` release? Read the
+[upgrade guide](docs/upgrading.md): imports moved to subpaths, dead and
+superseded APIs were removed, and the patch guardrails are now patch checks.
+What 1.0 considers public is defined there (every `exports` entry and the
+checked-in `api/` reports).
+
+### Breaking
+- Flows, the Jira / GitHub / Slack / email tools, encryption, `StorageService` and the validators moved out of the package root. Import them from their subpath: `FlowBuilder`, `FlowExecutor`, `validateFlow` and every flow type (`AgentFlow`, `EditorStep`, `FlowExecutionEvent`,...) from `@lousho/build-ai-agent/flows`; `createJiraTools`, `createGitHubTools`, `createSlackTool`, `slackTool`, `postSlackAlert`, `createEmailTool` and their types from `@lousho/build-ai-agent/integrations`; `EncryptionUtils`, `DTOEncryptionFilter`, `DecryptionError`, `sha256`, `generatePassword`, `StorageService`, `StorageServiceApprovalStore`, `LocalStorageCheckpointStore` and the validators (`validateWithSchema`, `safeValidate`, `isValidEmail`,...) from `@lousho/build-ai-agent/utils`. The integrations are no longer in `@lousho/build-ai-agent/tools` and the flow types are no longer in `@lousho/build-ai-agent/types`. Nothing else changed: the classes and functions are the same. For file-backed stores with `createAgent()`, prefer `fileStore(dir)`.
+- Removed `AgentType`, `AgentTypeDescriptor`, `AgentConfig.agentType`, `AgentBuilder.setType()` and the agent-type registry (`agentTypesRegistry`, `getAgentTypeDescriptor`, `getAllAgentTypeDescriptors`, `isValidAgentType`, `validateAgentConfig`, `validateAgentTools`). They had no runtime effect since 1.0.0-alpha: delete the `setType(...)` call and the `agentType` field. Also removed, because nothing implemented or used them: the repository interfaces (`IRepository`, `IAgentRepository`, `ISessionRepository`, `IResultRepository`, `SessionData`, `ResultData`, `SDKRepositories`), `DataLoadingStatus`, `PaginationParams`, `PaginatedResponse`, `DeepPartial`, `Timestamped`, `IdEntity`, `AgentExecutionOptions`, `AgentExecutionResult`, `AgentDefinition` and `ToolSetting`. If your code used one of these types, copy its declaration into your project. A checkpoint saved with `agentType` still loads; the field is ignored.
+- Removed `ExecuteOptions.onEvent` and the `ExecutionEvent` / `ExecutionEventType` types, deprecated in an earlier alpha. Pass `onAgentEvent` to `AgentExecutor.execute()` / `stream()` / `resumeAfterApproval()` instead (with `createAgent()`, `onEvent` already receives `AgentEvent`s and is unchanged). The mapping from the old event names to `AgentEvent` types is in docs/streaming.md#listening-without-iterating ("Migrating from `onEvent` / `ExecutionEvent`"). The one-time "onEvent is deprecated" warning is gone with it.
+- Removed `createDelegateTool()`, `DelegateAgentOptions`, `DelegateAgentResult` and `DelegationDepthExceededError`. Use the `subagents` option instead, on `createAgent()` or `AgentExecutor.execute()`: create the child with `createAgent({ provider, instructions, description })` and pass `subagents: { billing }`. The model gets one `task` tool for every sub-agent, with the same inheritance (hooks, permissions, abort, usage roll-up) and a depth limit (`maxSubagentDepth`, default `1`). A run at the depth limit is not offered the `task` tool, so a delegation cycle can no longer start; `DelegationDepthExceededError` is gone. See docs/sub-agents.md.
+- The executor API moved out of the package root to `@lousho/build-ai-agent/executor`: `AgentExecutor`, `AgentBuilder`, `ExecuteOptions`, `resumeAfterApproval`, `streamResumeAfterApproval`, `resumeRequest`, `ResumeExecuteOptions`, `ResumeRequest`, `ToolRegistry` and `globalToolRegistry`. Change `import { AgentExecutor, AgentBuilder } from '@lousho/build-ai-agent'` to `import { AgentExecutor, AgentBuilder } from '@lousho/build-ai-agent/executor'`. `ToolRegistry` is also still in `@lousho/build-ai-agent/tools`. The `@lousho/build-ai-agent/core` subpath is removed: import `AgentBuilder` from `@lousho/build-ai-agent/executor`. `createAgent()`, `ExecutionResult` and every type `createAgent()` uses stay in the root. To move off the executor API entirely, see docs/migrating-to-create-agent.md.
+- The patch guardrails are now called patch checks, so "guardrail" only means the input/output/tool guardrails of `createAgent({ guardrails })`. Rename: `runGuardrails` to `runPatchChecks`, `Guardrail` to `PatchCheck`, `GuardrailResult` to `PatchCheckResult`, `ProposedAction` to `ProposedPatch`, `RunGuardrailsResult` to `RunPatchChecksResult`, `runGuardrailSafely` to `runPatchCheckSafely`, `secretScanGuardrail` to `secretScanCheck`, `createDiffSizeGuardrail` to `createDiffSizeCheck`, `createCommandGuardrail` to `createCommandCheck` (options type `CommandCheckOptions`), `createTestRunGuardrail` to `createTestRunCheck`, `createLintGuardrail` to `createLintCheck`. Arguments, results and behavior are unchanged. `SECRET_PATTERNS` keeps its name.
+
+### Security
+- **Behavior change:** MCP tools now ask for approval by default (`approval: 'always'`). A server's own `readOnlyHint` / `destructiveHint` no longer switch approval off or let a tool run in plan mode unless its entry opts in with `approval: 'annotations'` (loaded descriptors then carry `metadata.mcp.annotationsTrusted: false`). An MCP tool whose `<server>__<tool>` name equals a local tool's is refused with `LOUSHO_CONFIG_INVALID` instead of silently replacing it and its approval gate. Set `approval: 'annotations'` on servers you trust to keep the old behavior. See [MCP](docs/mcp.md#approval-for-mcp-tools).
+- `openApiTools()` can refuse private destinations: with the new option `privateAddresses: 'refuse'` (default `'allow'`, unchanged), every operation request and the document fetch, each redirect hop included, fails when its host is or resolves to a loopback, link-local, private or reserved address. Host names go through the pinned DNS lookup `http_request` and `web_fetch` use (one resolution per connection, every address checked, the socket connects to the checked address), so DNS rebinding cannot reach a private address; IP literals in every form `URL` normalizes (decimal, octal, hex, IPv4-mapped IPv6) and `localhost` / `*.localhost` are refused when the tools are made. `allowPrivate` lists hosts that may be private. `'refuse'` cannot be combined with a custom `fetch` (it throws a `ConfigurationError`: a custom fetch's connections cannot be pinned) and needs Node.js (`undici`, `node:dns`); where undici cannot load, making the tools throws a `ConfigurationError`. See docs/openapi-tools.md#security-rules.
+- The registry permission manifest is now enforced when an agent directory loads and runs. `loadAgentDir` re-hashes every file the `lousho-registry.json` receipt lists; an item with edited or missing files is reported `unattested` (a warning naming the item and files, and `manifest.registry` on `resolveAgentDir()`, which also gains the new `Attestation`, `RegistryItemStatus` and `RegistryStatus` types) without refusing the load. Every tool a receipt item owns then runs inside the manifest accepted at install: an `exec: true` or `needsApproval: true` item's tools - and any unattested item's tools - always wait for approval (a tool's own `deny` still denies); `fetch` while the tool runs is limited to the declared `network` hosts; `process.env` shows only the declared `env` names; and a `requiresSandbox` tool gets a narrowed adapter (`run()` refused without `exec`, `writeFile()` without `filesystem: "write"`, a command env of the non-secret base plus the declared variables only). The envelope stays as narrow as the last accepted manifest until `lousho add <name> --overwrite` attests the current files. Limits, unchanged: the guards intercept `fetch` and `process.env`, not `http`/`net`/`axios`, the filesystem, module-scope captures or a container's own network policy; the manifest is still not a sandbox. See docs/registry.md#permission-manifest.
+
+### Changed
+- The published package is smaller: ~873 files / ~13.5 MiB unpacked / ~3.65 MiB packed, down from ~902 / ~20.8 MiB / ~5.6 MiB. Test-only files that still shipped (`*.test-d.ts` type tests, `*.testkit.ts` helpers, `__snapshots__/` and the test-replay `__cassettes__/` directories) and the Agent Forge server source map no longer ship, and the SDK's own source maps no longer embed `sourcesContent` — their `sources` still resolve to the shipped `src/`, so `--enable-source-maps` stack traces keep working. `pack-smoke` now also runs `build:studio`, so it measures the tarball that is actually published, and it fails when a file `lousho build` or `lousho studio` needs is missing.
+- Test files are type-checked (`npm run typecheck:tests`, in CI); `pack-smoke` also checks the published declarations with `skipLibCheck: false`.
+
+### Added
+- Agent directories: new `agent.*` config keys `permissionMode`, `permissions` (a serializable rule form: `tool` is a name, a list or - in a code config - a `RegExp`; `when` narrows the rule with a record of argument names to matchers - a regular expression string or an operator object (`eq`/`ne`, `lt`/`lte`/`gt`/`gte` on `Number(arg)`, `matches`), or a predicate in a code config; `action` is `allow` / `ask` / `deny`), `compaction`, `limits`, plus `hooks` and `approve`, each a path (relative to the directory) to a file default-exporting the hook(s) / the approver function, or the value inline in a code config. `instructions/<family>.md` appends to `instructions.md` when the resolved model id contains `<family>` (e.g. `openai`, `anthropic`). `lousho build --target=node-server` (and `--target=docker`) bundles a root `hooks.*` / `approve.*` file next to the config and resolves the compiled `.js` sibling; the Cloudflare Worker target carries `permissionMode`, `permissions`, `compaction` and `limits` over and accepts `hooks` / `approve` from a code config (a file path is refused, a Worker cannot import it). See [Agent directories](docs/agent-directories.md).
+- Registry: a new item `type` `kit` is a whole agent directory - its `files` may sit at any (still safe) relative path - so `lousho add <kit> --dir <target>` installs `agent.*`, `instructions.md`, tools, skills and sub-agents in one item, under one permission manifest, and records it in `lousho-registry.json` like any other item. The default registry's first kit is `coding-kit`, a port of the `examples/coding-harness` baseline: workspace tools with checkpoint rewind, an allow-listed shell, permission rules, a loop guard and output cap as hooks, a compaction setting, a `fix-failing-test` skill and a read-only `explorer` sub-agent (manifest: `exec`, `fs-write`; install with `lousho add coding-kit --dir <dir> --yes --allow exec,fs-write`). See [Registry](docs/registry.md).
+- The `pi` provider: `createAgent({ model: 'pi/<pi-provider>/<model>' })` routes calls through `@earendil-works/pi-ai` (`1.0.3`, a new optional peer - `npm install @earendil-works/pi-ai@1.0.3`), the engine `pi-coding-agent` runs on, so pi's whole catalog (OpenRouter, Anthropic, OpenAI, Google,...) is usable natively; e.g. `pi/openrouter/openai/gpt-4o-mini` is OpenRouter's `openai/gpt-4o-mini` (nested slashes are kept: the segment after `pi/` is the pi provider, the rest the model id). Messages (including reasoning blocks, tool calls/results and image parts), tool `parameters` (raw JSON Schema, zod 3/4 or Standard Schema), streamed chunks and usage/cost map to the same surface the `ai`-SDK providers expose, and pi's own retries are pinned off so `retry`/`fallbackModels` stay the only retry layer. Credentials are per nested provider: pi reads each one's own env var (`pi/openrouter/...` reads `OPENROUTER_API_KEY`), and a missing one fails the call with `LOUSHO_PROVIDER_MISSING_API_KEY` naming it; a missing package fails with `MissingPeerDependencyError` naming `npm install @earendil-works/pi-ai@1.0.3`. New export `PiProvider` (+ `PiProviderConfig`, whose `models` injects custom/faux catalog entries). `pi` is Node-only: the `cloudflare-worker` target refuses `pi/...` specs. See docs/providers.md#the-pi-provider.
+- `piAgent()` ("pi-coder"): a Pi coding-agent session (`@earendil-works/pi-coding-agent`, a new optional peer) usable in-process as a `createAgent({ subagents })` entry - `subagents: { coder: piAgent({ cwd, model, description, permissions }) }`. Each `task` call is one Pi session under the task's `sessionId`, so `taskId` resumes and approval resumes reopen the same JSONL transcript even across a restart. `permissions` (the same `PermissionRule`s as `createAgent()`) gate every Pi tool call through a `tool_call` extension handler: `deny` refuses it, `ask` pauses the lead run durably for approval when the caller can pause and refuses it otherwise; approving re-issues that exact call once (Pi has no run-blocked-call API, so a decision prompt asks the model to repeat it and the gate lets that one call through), rejecting sends the note as the next turn. Pi usage rolls into the lead's `result.usage`, and aborts propagate to the Pi session. Node-only: the package is loaded lazily, so a consumer without it still typechecks and `run()` fails with `LOUSHO_PEER_MISSING`. Also new: `defineRemoteSubagent(impl)` wraps any `RemoteSubagent` implementation (same contract as `remoteAgent()`), and `SubagentApprovalPause` is exported for such adapters.
+- Agent directories: three more `agent.*` config keys wire the approval surface. `approvalTtlMs` is `createAgent`'s run-level default for how long a pause for approval stays decidable (milliseconds); a `permissions` `ask` rule may set `ttlMs`, bounding that rule's pauses and winning over `approvalTtlMs` (both positive finite numbers, rejected otherwise). `store` declares a durable store so paused approvals survive restarts ("draft today, approve tomorrow"): `{ "dir": "./.lousho" }` (resolved against the agent directory, staying inside it) becomes a `fileStore()` - sessions, checkpoints and approvals as JSON files, with `historyLimit` / `tokenKey` also declarable; a code config may set an `AgentStore` instance instead. `store` is Node-only: the Cloudflare Worker target rejects it. `loadAgentDir(dir, { approve: null })` / `{ hooks: null }` strip the directory's wiring (the file the config names is not even imported), where `undefined` keeps it. The generated node-server / docker server keeps a config-declared `store` unless `LOUSHO_STORE` is set. See [Agent directories](docs/agent-directories.md).
+- Agent directories: `"engine": "pi"` in a `subagents/<name>/` config makes that directory a `piAgent()` coding sub-agent instead of a nested `createAgent()` one - it lands in the parent's `subagents` map (the `task` tool) and its sessions run in the parent's directory, the workspace both share. Its `model` is the usual `pi/<provider>/<model>` id and its `permissions` gate the Pi session's own tool calls; the remaining config keys are ignored (Pi carries its own prompt and tools). `loadAgentDir()`'s new `piAgent` override injects `PiAgentOptions` into every such sub-agent (a faux `modelRuntime` in tests, a `sessionDir` for durable approvals); the directory always wins `cwd`, `name` and `description`. Cloudflare Worker targets reject `engine` - Pi needs the Node runtime. The default registry's second kit, `coding-pi`, is `coding-kit` on the full Pi stack: pi-provider lead, dir-declared pi coder, same safety rails (install `--allow exec,fs-write,network,env`). See [Agent directories](docs/agent-directories.md#sub-agents).
+- The `approve` callback may return `'defer'` to abstain: the call stays pending (listed by `agent.approvals.list()`, resolvable by `agent.approvals.resolve()` / `streamResolve()` / `answer()`) and the run surfaces the pause - `send()` resolves with `finishReason: 'awaiting-approval'`, as if the callback had never been asked - so an approver can decide the calls it trusts and hand the rest to a human. Note: `'defer'` is now reserved; an approval note that is exactly `'defer'` defers instead of approving. See [Deciding in code](docs/approvals.md#deciding-in-code).
+- Tool-call hook contexts carry `resumedAfterApproval`: `true` only when `preToolCall` / `postToolCall` fire for the post-approval re-run of a call the run paused on (`agent.approvals.resolve()`, `resumeAfterApproval()`). Stateful hooks (loop guards, audit counters) can skip the re-fire with `if (ctx.resumedAfterApproval) return;`. See [Hooks](docs/hooks.md).
+- New `ToolDescriptor.transient` marks a tool bound per run (a memory slot's `remember_*` / `recall_*` tools, bound to the run's scope keys): it is left out of the agent fingerprint, so an approval-resumed run - whose registry intentionally does not rebind them - no longer reports `tools removed` agent drift on every resolve.
+- Approvals can expire. `createAgent({ approvalTtlMs })` (validated: positive finite) sets a default deadline for every pause, `send()`/`stream()` take a per-call override, a `permissions` `ask` rule may set `ttlMs` (wins over the run default), and `ExecuteOptions.approvalTtlMs` covers `AgentExecutor.execute()`; sub-agents inherit the lead's TTL unless they set their own. A pending approval past `expiresAt` resolves as denied with `'approval expired'` - enforced at decision time, so a durable-store resume (a restart, another process) can never approve a stale pause - and `list()` keeps expired entries (marked by `expiresAt`) so `resolve()` still continues the run. `approval.requested` events and `UIPendingApproval` carry `expiresAt` for UI countdowns; expiry writes an audited `deny` decision to `onPermissionDecision`. See [Approvals](docs/approvals.md).
+- `llmCritique(config)`: like `llmJudge` but returns `{ score, feedback }` - one judge call, a `SCORE:`/`FEEDBACK:` prompt, graceful degradation on malformed output - so evaluator-optimizer loops get actionable revision guidance, not just a number. See [Evals](docs/evals.md).
+- Testing helpers: `testToolContext(overrides?)` (`@lousho/build-ai-agent/testing`) builds a valid `ToolExecutionContext` for direct `tool.execute()` calls - `getToken`/`requireAuth` fail loudly unless stubbed - and `toolResultText(message)` (root export) unwraps a `tool` message's JSON-encoded content to its result text.
+- Channels: `ChannelInbound.metadata` now reaches the run as `SendOptions.metadata` (memory scopes and `when` contexts can key on channel-supplied data; it is unauthenticated, unlike `principal`), and `webhookChannel({ principal: (body, req) =>... })` can derive the caller principal from a verified body/header - so a webhook intake (PagerDuty, Grafana) attributes the run to the alerting system. See [Channels](docs/channels.md).
+- New registry kits and examples replicating the most-built agent archetypes: `inbox-triage` (channel intake → classify → draft → approval-gated send, per-sender memory, `@hourly` sweep; install `lousho add inbox-triage --allow env,fs-write`) and `incident-response` (webhook alert → diagnose → risk-tiered approvals → remediate → verify → audit timeline; install `--allow env,fs-write`); examples `deep-research` (orchestrator-workers fan-out with cited synthesis), `support-desk` (triage → `handoff()` to specialist agents), `evaluator-loop` (writer ↔ `llmCritique` revision loop) and `data-analyst` (text-to-SQL with read-only enforcement). Each runs offline on mock models and accepts `OPENROUTER_API_KEY` for a live pass.
+- `claudeProject(dir)`: loads a repository's Claude-Code-conventional context into options that spread into `createAgent()` — `CLAUDE.md`/`AGENTS.md` + `.claude/rules/*.md` become `instructions`, `.claude/skills/*/SKILL.md` load through `loadSkills()` unchanged, `.claude/agents/*.md` frontmatter becomes `subagents` (frontmatter `model` selects the sub-agent's model; `provider`/`model` options are the fallback), and `.claude/scratchpad/` gets a `scratchpad` note tool (name-validated `*.md` writes). Nothing in the directory executes: markdown is read as data, and `.claude/commands`, `settings*.json` and `mcp.json` are listed on `manifest.ignored` rather than loaded. See [Claude Code projects](docs/claude-projects.md).
+- `decide()`: typed answers from the OpenAI Decisions API (`POST /v1/decisions`, public beta — `gpt-6-luna` only) — `predicate` questions return a probability, `choice` returns a value plus per-option `probabilities` and `confidence`, `score` returns a rubric's probability-weighted level index, and any question may come back a `refusal`. Input is a string or messages with `input_text`/`input_image` (inline base64) parts; `apiKey` (default `OPENAI_API_KEY`), `baseURL`, `timeoutMs`, `signal` and `fetch` are overridable. It is the fast path for typed decisions (route/gate/score) — no agent turn and no generated prose — and does not go through providers or OpenRouter. See [Decisions](docs/decisions.md).
+- Four new examples covering the agentic-patterns catalog: `waves` (Workers · Aggregate · Verify · Extend — bounded parallel workers, deterministic merge, a typed `{ verdict, gaps }` verifier, extension waves seeded by its gaps), `phase-pipeline` (discuss → spec → plan → implement → proof gate → report on `FlowBuilder`/`FlowExecutor`, with the implement↔check retry ladder as a `oneOf` chain), `coding-agent-workflows` (a coding agent routed by a typed decision — `output` schema `{ route, confidence, reason }`, a confidence floor escalating low-confidence calls to the careful path), and `connectors` (MCP connectors à la Claude — runs fully offline against a mock `serveMcp` stdio server exposing `docs_*`/`slack_*` tools; README maps Google Docs, Slack, GitHub and Notion). Plus `hostinger-deploy`: build an agent with `lousho build --target=docker`, ship it to a Hostinger VPS over SSH and smoke-test `/health` + bearer auth + approval pause/resume. See [Prompting and context techniques](docs/prompting-techniques.md), [Connectors](docs/connectors.md) and [Hostinger VPS](docs/hostinger-vps.md).
+- `lousho add` has a default registry: without `--registry` or `LOUSHO_REGISTRY` it reads `https://registry.lousho.com/index.json` - the `registry/dist/` folder of this repository served as static JSON - instead of failing with "no registry configured; there is no hosted registry yet", so `lousho add --list` works out of the box. It carries five starter items: the tools `open-meteo-weather` (current weather by city through Open-Meteo, no API key) and `github-issues` (list and create issues through `api.github.com`; creating asks for approval), the skills `changelog` and `code-review`, and the `generic-webhook` channel (HMAC-SHA256 signature verification from `WEBHOOK_SECRET`). `--registry` and `LOUSHO_REGISTRY` still override it, and the new value `none` (in either place) disables the registry entirely with the old `LOUSHO_CONFIG_INVALID` "no registry configured" error, for offline or locked-down use. The items live in `registry/` as an `item.json` plus their files per folder; `npm run registry:build` validates each against the registry schemas, the path rules and the M7a code/manifest check, and writes the committed `registry/dist/` (`npm run registry:check` fails when it is stale and runs in CI). See docs/registry.md.
+
+### Fixed
+- A channel button click (Slack, Discord), inline-keyboard tap (Telegram), Adaptive Card press (Teams) or `/approve` command (GitHub) after a restart is now bound to the conversation's session before the approval is resolved, so its continuation is appended to the session transcript again. The decision names the conversation it came from (`inbound`); with checkpointed sessions (`mountChannels` `store` with `checkpoints`, e.g. a `SqliteStore`) it is accepted only when that session's pending turn waits on exactly that approval id and kind - a decision for another conversation, a replay of a decided one and a decision of the wrong kind are refused (`LOUSHO_APPROVAL_NOT_FOUND`) before the approval is touched, and `onDecision` audits only decisions that pass, so a replayed click cannot run the tool twice and the thread's next message continues the same session. Without a checkpoint store nothing can be checked, so the approval store alone decides, as before.
+- A channel's function `approvers` works after a restart: `ctx.approval(id)` asked only this process's `agent.approvals.list()`, so a pause the restarted process did not make looked the same as a denial and the function failed closed. `ApprovalStore` gains an optional `load(id)` - `resolve()` without removing the record; every shipped store implements it, and a custom store without it keeps compiling and behaves as before - and the new `agent.approvals.get(id)` reads through it. `ctx.approval` falls back to that, so the function sees the same request (`toolName`, `input`, `sessionId`, `principal`) it saw before the restart and fails closed only when no store knows the id (a process-local approval store still forgets its pauses at a restart).
+- A hand-written Cloudflare Worker can now bundle `createAgent`. The package root also exports file stores, the agent-directory loader, MCP over stdio and sandboxes, so bundling it for `platform: 'browser'` failed with `Could not resolve "async_hooks"` (and `crypto`, `fs/promises`, `http`, `net`, `stream`) - only the generated Worker ever bundled, because `lousho build --target=cloudflare-worker` redirects those imports to shims itself. `@lousho/build-ai-agent/worker` is a new subpath exporting `createAgent` (and its config types), `memoryStore`, the KV stores (`KVStore`, `KVCheckpointStore`, `CHECKPOINT_KV_BINDING`), the schedule helpers (`defineSchedule`, `handleScheduled`), `serveFetch` (the `/chat` API as a fetch handler), the providers a Worker can run and the whole Worker-safe subset agent-directory code may import. The SDK's own build produces it through the same Node-builtin/sandbox/QuickJS shims the adapter applies (plus new `ollama-ai-provider` and `@modelcontextprotocol/sdk` ones, which an external specifier would leave unresolvable and `mcpServers` therefore fails on first connect - use `lousho build` for MCP on Workers), so the published entry carries no `node:` import for a user's own bundler to fail on; `ai`, `zod`, `@opentelemetry/api` and the `@ai-sdk/*` provider packages stay external specifiers resolved from the user's install. Guarded by `src/deploy/worker.test.ts`; see docs/cloudflare-workers.md#writing-your-own-worker.
+- The published `.d.ts` files no longer import the types of optional peers: `SubprocessSandboxOptions.dockerOptions` is now the structural `DockerConnectionOptions` (same fields as dockerode's `DockerOptions`, passed through unchanged) and `McpClientLike` is the structural subset of the MCP SDK's `Client` it already was (`listTools` / `callTool`). Before, `dist/index.d.ts` imported `dockerode` and the shared schema chunk imported `@modelcontextprotocol/sdk`, so a consumer compiling with `skipLibCheck: false` without those optional peers installed got TS2307 inside the SDK's own declarations. A dockerode `DockerOptions` or MCP `Client` value still satisfies both types.
+
+## [1.0.0-alpha.18] - 2026-10-08
+
+See the 1.0.0-alpha.19 section, which covers everything from 1.0.0-alpha.15 through 1.0.0-alpha.19.
+
+## [1.0.0-alpha.17] - 2026-10-07
+
+See the 1.0.0-alpha.19 section, which covers everything from 1.0.0-alpha.15 through 1.0.0-alpha.19.
+
+## [1.0.0-alpha.15] - 2026-10-06
+
+See the 1.0.0-alpha.19 section, which covers everything from 1.0.0-alpha.15 through 1.0.0-alpha.19.
+
+## [1.0.0-alpha.9] - 2026-10-04
+
+### Security
+- `http_request` is no longer open to DNS rebinding. It resolved a host name once to check it against the private-address list and then let `fetch` resolve it again to connect, so a name that answered a public address to the check and `127.0.0.1` (or a cloud metadata or intranet address) to the connection reached the private address; the docs and a comment in the Worker runtime described the check as rebinding-safe. Now the one resolution is the check: the in-process path connects through an undici `Agent` whose `connect.lookup` checks every address and hands the socket the address it checked (each redirect hop included), and the sandboxed path (`sandboxExecute`, which agents use) resolves and checks the host in the agent's process and has the sandboxed process connect to that address (node:http/https with a fixed lookup; the host name still goes in `Host` and TLS SNI). The private-address list is now the shared one (below), which adds `0.0.0.0/8`, `100.64.0.0/10`, `192.0.0.0/24`, `198.18.0.0/15`, multicast and reserved `224.0.0.0/3`, `::`, `ff00::/8`, NAT64 `64:ff9b::/96` and 6to4 `2002::/16` to what `http_request` refused. Behavior changes: a host name that cannot be resolved now fails with the resolver's error instead of being passed to `fetch`; `undici` is loaded on the first `http_request` request (not only with `validateSSL: false`). New option `createHttpTool({ allowPrivate })` for hosts that may resolve to private addresses. Cloudflare Workers have no DNS hook, so neither tool exists in the Worker build; docs/deployment.md now says what a Worker can and cannot check.
+- A run's principal is fixed for the whole run: an approval resolved by another caller, a restart, `agent.resume()` or a session's pending turn continue as the caller that started the run, and the decider is recorded as the approver (`ctx.approval.by`), never swapped in as the run's principal, so a later caller cannot use an earlier caller's grant by approving their pending call. The principal comes only from route auth or a channel's verified sender; the approvals route and channels never read it from a body field. It is frozen before a tool, a policy or a hook sees it. Remote sub-agents are not told who the caller is.
+
+### Changed
+- Behaviour and types: a tool whose `execute` returns an async iterator that is also async iterable (what an `async function*` returns) is now iterated: its last yielded value is the result, instead of the iterator object itself (which used to reach the model as `{}`). `AgentEvent` gains `tool.partial` (`ToolPartialEvent`), `isToolEvent()` narrows to it too, `UIToolCall` gains `partial?`, the `tool-output-available` UI chunk type gains `preliminary?: true`, and `DefinedTool` gains a third, defaulted type parameter (what `execute` resolves to). Migration: a `switch` over `event.type` meant to be exhaustive needs a `'tool.partial'` case; code using the result of `isToolEvent()` as start/done/error only should check `event.type`; a tool that means to return an async generator as a value should wrap it (`{ items: generator }`) - a value that is only async iterable, such as a `ReadableStream`, is still returned as it is.
+- Types only: `AgentEvent` gains the `handoff` event (`HandoffEvent`) and `ExecutionResult` the optional `agentName` (set on every result the executor returns: the agent of the final reply). Migration: a `switch` over `event.type` meant to be exhaustive needs a `handoff` case; a test comparing a whole `ExecutionResult` with `toEqual()` now sees `agentName`. Nothing changes at runtime for an agent without `handoffs`.
+- BREAKING (types only): `McpServerStatus` gains `'needs-auth'`, and `AgentOAuth` (the type of `agent.oauth`) gains `mcpSignInUrl(server)`. Migration: an exhaustive `switch` over `connectMcp(...).status()` values needs a `'needs-auth'` case (only servers with `oauth` ever report it); an object written by hand to satisfy `AgentOAuth` (a test double, say) needs an `mcpSignInUrl` method. Runtime behaviour without `oauth` is unchanged.
+- BREAKING (types only): `ToolExecutionContext` gains the methods `getToken(provider)` and `requireAuth(provider)`, and `ApprovalKind` gains `'sign-in'`. Migration: code that builds a tool's execute context by hand (for example to call `tool.execute(args, { toolCallId, messages })` in a unit test) must add the two methods or cast (`as ToolExecutionContext`); a `switch` over `PendingApproval.kind` / `approval.requested`'s `kind` that is meant to be exhaustive needs a `'sign-in'` case. Contexts the SDK builds have them already; nothing changes at runtime.
+- BREAKING: `send()` and `AgentExecutor.execute()` with a listener (`createAgent({ onEvent })`, `onAgentEvent`, or the deprecated `onEvent` option) now stream model calls: a step's text arrives as several `text.delta` events, as in `stream()`, instead of one `text.delta` per step after the step finished. What a listener receives otherwise does not change: the same event types in the same order, exactly one `text.done` per step with the step's whole text, the same `step.done` usage and `run.done`, the same `ExecutionResult` (text, tool calls, usage, steps). A provider without `stream()`, or whose `supportsStreaming(model)` is `false`, still gives one `text.delta` per step. Output guardrails on `send()` still check only the final reply (a `stream()` you iterate checks every step's text, as before). `send()` without a listener still calls `provider.generate()`. Hooks' `ctx.emit` is set whenever the run has listeners (it was already; the docs said "only when streamed"). Migration: concatenate `text.delta`, or listen to `text.done` for whole steps; `execute({ streamModelCalls: false })` (new option, default `true`) restores whole steps.
+- `MockLLMProvider` / `createMockProvider()`: `stream()` now streams the same step `generate()` returns: the same tool calls (it streamed none, so a streamed mock run never called a tool), finish reason and usage, and text chunks that add up to exactly the generated text (the old chunks ended with an extra space: `'This is a mock response. '`). Runs on the mock provider with a listener (Agent Forge's, for one) therefore give the same results as before, and `stream()` runs on it now call tools as `send()` does.
+- Agent Forge: runs now stream their model calls, so the run WebSocket (`WS /agents/:id/stream`) carries several `text.delta` events per step; the chat, logs and trace views are unchanged (they use `text.done` and the reconciled messages). Stop is checked between streamed chunks and after the last one, as it was after each `generate()` call.
+- CI peer matrix: the `typecheck-ai7` and `typecheck-zod4` jobs are replaced by one `peers` job with five entries, each installed for real on top of the default install and run through `tsc`, `test:types`, both builds and `npx vitest run`: `ai4-zod4`, `ai6-zod3`, `ai6-zod4`, `ai7-zod3`, `ai7-zod4`. The two zod 4 entries on `ai` 6/7 also install `ollama-ai-provider-v2` (3.x / 4.x), and the new `src/providers/ollamaV2.contract.test.ts` runs `OllamaProvider` against the real package and a local fake Ollama server (`generate()`, `stream()`, a tool-call turn through `createAgent().send()` and `.stream()`). The `ai-v6` dev alias replaces the hand-made `ai` 6 stand-in in `aiMajorPeers.test.ts`.
+- `lousho init --provider ollama` now scaffolds `ai@^7.0.0` with `ollama-ai-provider-v2@^4.0.0` and `zod@^4.0.0` (it was `ai@^4.3.19` with `ollama-ai-provider@^1.2.0` and zod 3). Existing projects are not touched; to stay on the old pairing keep `ai@^4.3.19` and `ollama-ai-provider@^1.2.0`.
+- A run paused inside a sub-agent compares the sub-agent with its current definition on resume, under the lead's `onAgentDrift`. Behaviour change: with `onAgentDrift: 'error'`, `agent.approvals.resolve()` (and `resumeAfterApproval()`) now also rejects with `LOUSHO_AGENT_DRIFT` when a paused sub-agent's instructions, model or tools changed; before, only tool and provider default-model changes of a sub-agent were seen, and always as a warning. This holds at any depth (a sub-agent of a sub-agent uses the lead's mode). With `'warn'` (still the default) the `agent.drift` event carries `subagent`. A rejected resume puts the lead's approval record and its `'awaiting-approval'` checkpoint back, so fixing the sub-agent and resolving again finishes the run; before, a sub-agent's missing-tool error became an error result of the `task` call and the run continued. Migration: none for `'warn'` / `'ignore'`; with `'error'`, resolve approvals paused before a sub-agent changed with the old definition, or use `'warn'`. See docs/durable-execution.md#resuming-with-a-changed-agent.
+- `lousho add` enforces the permission manifest at install. Behaviour change: an item whose code does not match its manifest is now refused with the new code `LOUSHO_REGISTRY_MANIFEST_MISMATCH`, and nothing is written. Before writing, every JavaScript / TypeScript file of the item is scanned (comments stripped) for `child_process` / `execa` / `shelljs` / `createShellTool` / `SubprocessSandbox` (needs `exec: true`), `fs` imports and `createFsTools` (needs `filesystem: "read"`), file-writing calls (needs `"write"`), `fetch(` and network modules (needs a non-empty `network`), `http(s)://` hosts in strings (each must match a `network` entry) and `process.env.NAME` reads (each must be in `env`); `eval(`, `new Function(`, a computed `process.env[...]` and a non-literal `import()` / `require()` are always refused. Each finding is listed as `<file>:<line>: <what> (<fix>)`. `network` entries must now be host patterns and `env` entries variable names (`LOUSHO_REGISTRY_INVALID` otherwise). With `--yes`, an item asking for `exec: true`, `filesystem: "write"`, a `network` or an `env` is refused unless each is named in the new `--allow exec,fs-write,network,env` flag; the interactive prompt lists them, and the printed manifest marks them `[elevated:...]`. After writing, `lousho add` records the item (type, registry, time, permissions, each file's sha256) in `<agent-dir>/lousho-registry.json`. Migration: registry authors declare what their code uses; scripts that run `lousho add --yes` add `--allow` with the permissions they accept. It is a static check, not a sandbox; see docs/registry.md#permission-manifest. The example item in docs/registry.md now uses `input` (not `inputSchema`).
+- Behaviour change: continuing an unfinished checkpointed run (`send(message, { sessionId, principal })`, `AgentExecutor.execute({ sessionId, checkpointStore, principal })`) with a principal other than the one it was saved with now throws `LOUSHO_CONFIG_INVALID` instead of running the new input; without a principal (`agent.resume()`, a session's pending turn) the run continues as the saved caller. Migration: resume such a run without `principal`, or start a new session. `onPermissionDecision` is called with a second argument, `{ principal }` (callbacks that take one argument are unaffected). Checkpoints, approval snapshots and pending approvals now store the run's principal (claims included): treat those stores as personal data. Checkpoints and snapshots written before this release resume with no principal; no migration.
+
+### Added
+- `lousho dev` and `lousho chat` take `--traces` (or `--traces=<dir>`) to write local traces with `fileTraceExporter()`: `.lousho/traces` by default, the directory `lousho traces` reads, for spec files, agent directories and modules (`specToAgent()` now also accepts an `exporter` option). It is opt-in because trace files hold prompt and tool content even with `captureContent: false` (only `redactContent: true` removes it); the command prints where it writes. `lousho init` projects already ignore `.lousho/`.
+- Code mode: `createAgent({ codeMode: true | CodeModeOptions })` adds a `run_code` tool. The model writes the body of an async JavaScript function that calls the agent's tools as `await tools.<name>(args)`, loops and combines their results, and returns one JSON value; `run_code` returns `{ result, logs, toolCalls }` and only that enters the transcript. Scripts run in a QuickJS WebAssembly isolate from the new optional peer `quickjs-emscripten` (`^0.32.0`, listed by `lousho doctor`; without it the first run of a `codeMode` agent fails with `MissingPeerDependencyError`): a fresh runtime per script, no `require`, `import`, `process`, `fetch`, timers or host objects, values passed as JSON copies, and the limits `timeoutMs` (30,000, whole script including awaited tool calls), `memoryLimitBytes` (64 MiB), `maxToolCalls` (50) and `maxOutputChars` (20,000, return value plus logs). `tools` picks the callable tools (default: all but `run_code`, `ask_question`, sub-agent tools, `tool_search`, `load_skill` and deferred tools); `exclusive: true` takes them off the model's tool list. Every inner call (id `<run_code id>:<n>`) goes through the same gate as a direct call: validation, hooks, permission rules and modes (plan mode refuses non-read-only inner calls; `run_code` itself is read-only), tool guardrails (a block stops the run), `needsApproval`, sandbox routing and the principal. A call that would pause the run (approval, sign-in, a sub-agent's approval) throws inside the script instead and the run does not pause; `run_code` itself can be paused for approval by a rule and runs after the decision. A failed script's error lists its first five tool calls with their (clipped) results. New export: type `CodeModeOptions`. Types: `parentToolCallId?` on the `tool.start`, `tool.partial`, `tool.done` and `tool.error` events (set on inner calls; their `tool.done` / `tool.error` comes before `run_code`'s); inner calls get `execute_tool` spans under the `run_code` span with the attribute `lousho.tool.parent_call_id`. No migration needed: nothing changes without `codeMode`. See docs/code-mode.md.
+- Streaming partial tool results: a tool's `execute` may be an `async function*`. Every `yield` is a complete snapshot of its output, streamed as the new `tool.partial` event (`{ toolCallId, toolName, output, index }`, `index` from 0) between the call's `tool.start` and `tool.done`; the last yield is the result the model gets (and `tool.done`'s `result`), a `return` value is ignored and a generator that yields nothing has the result `undefined`. Snapshots are not sent to the model, not added to the transcript, not checkpointed and not recorded in trace spans; hooks see only the result; tokens from `ctx.getToken()` are redacted in snapshots like in the result. The main loop, a streamed resume after an approval (`agent.approvals.streamResolve()`) and a flow's tool-call node iterate the generator; aborting the run stops reading it and calls its `return()`; `toolConcurrency` counts the whole generator run. A call that pauses for a sign-in mid-stream runs again from the start (index from 0); partial output is lost on a crash. `defineTool` types it: `ToolOutput<typeof tool>` is the yielded type (new helper type `ToolResultOf<R>`). The UI reducer (`useLoushoAgent()` and the Vue / Svelte bindings) keeps the latest snapshot as `toolCalls[i].partial`, and `toUIMessageStream()` sends snapshots as the AI SDK's preliminary tool output (`tool-output-available` with `preliminary: true`). See docs/tools.md#streaming-partial-results.
+- Tool search: tools marked `deferLoading` (`defineTool({ deferLoading: true })`, or every tool of an MCP server with `mcpServers.<name>.deferLoading: true`, also in spec files and agent directories) are withheld from the model, which finds them with a built-in `tool_search` tool (`{ query }` -> `{ loaded: [{ name, description }], more }`); the tools it finds are sent from the next step on, and `tool_search` stops being offered once everything is loaded. New option `toolSearch` on `createAgent()` and `AgentExecutor.execute()`: `{ thresholdPercent? (default 0.1 of the context window; 0 always defers), maxResults? (5), contextWindow?, search? }`, or `false` to send every tool upfront. Below the threshold nothing is deferred and no `tool_search` exists. Which tools are loaded is read from the transcript at each model call, so loading survives crash resume, approvals, forks and session turns; compaction that prunes a `tool_search` result unloads its tools; a handoff target or a sub-agent never inherits the lead's loaded tools. Skills, memory, `task`, `ask_question` and handoff tools are never deferred. New exports: `ToolSearchOptions`, `ToolSearchResult`, `rankToolsByKeywords()`. Types: `ToolDescriptor.deferLoading`, `DefineToolOptions.deferLoading`, `McpStdioServerSpec` / `McpHttpServerSpec.deferLoading`, `LoadMcpToolsOptions.deferLoading`, `SubagentSpec.toolSearch`, `ToolMetadata.mcp.server`. Behaviour change: tools loaded by `loadMcpTools()` / `connectMcp()` now carry their server name in `metadata.mcp.server`; a test comparing an MCP tool's whole `metadata` with `toEqual()` needs that key. A user tool named `tool_search` is refused (`LOUSHO_CONFIG_INVALID`) only when deferral is active. See docs/tool-search.md.
+- Handoffs: `createAgent({ handoffs: [billing, handoff(refunds, options)] })` lets an agent hand the whole conversation to another `createAgent()` agent (with a `name` and a `description`), offered to the model as one `transfer_to_<name>` tool each. The handoff call is not run as a tool: once the other calls of its step are done, the run goes on in the same `send()` / `stream()` as the target, with its instructions (replacing the system prompt), model, tools, skills, sub-agents, reasoning and own handoffs, the lead's guardrails and permission rules before its own, on the transcript the handoff's `inputFilter` returns (`handoffFilters.removeToolCalls`, `handoffFilters.lastUserMessage`, or your own). Hooks, `limits` and spend, `maxSteps` (counted across agents), the signal, the approval, checkpoint and token stores, listeners, `output`, the permission mode and the principal stay the run's. `handoff()` options: `toolName`, `description`, `input` (validated; bad arguments get a tool error and no handoff), `inputFilter`, `onHandoff`, `isEnabled` (a `PerRun<boolean>`). Only the first handoff call of a turn is honored; `maxHandoffs` (default 5) caps one run. The transcript marks each handoff with `metadata.handoff = { from, to }`; a session's next turn, `agent.resume()`, `session.resume()` and `agent.approvals.resolve()` continue as the agent it last handed off to (`agent.send()` without a session starts at the lead), and the resume drift check compares with that agent. Approvals remembered with `once()` are dropped at a handoff. A `transfer_to_*` call passes the run's gate like a tool call: `permissions` rules apply to it (`deny` gives the model a `kind: 'denied'` tool error and no handoff happens; `ask` pauses the run for approval and the decided call then hands off or reports the rejection), pre/post tool hooks may deny it or rewrite its arguments, and its decision is audited to `onPermissionDecision` / `permission.decision`. Each handoff appends a routing system note (`metadata.handoff`) carrying the validated call arguments to the transcript the target reads; `handoffFilters.removeToolCalls` keeps it and a custom `inputFilter` may drop or replace it. `createAgent()` warns once when a reachable handoff target was created with run-level options (`approve`, `approvalStore`, `permissionMode`, `approvalTtlMs`, `store`) - a run keeps the entry agent's. New `handoff` event (`from`, `to`, `toolCallId`) and `ExecutionResult.agentName`; `ExecuteOptions.handoffs` / `maxHandoffs` for the executor API. Remote agents cannot be handoff targets. See docs/handoffs.md.
+- OAuth for HTTP MCP servers, per the MCP authorization spec: an `mcpServers` HTTP entry takes `oauth: { redirectUri, clientId?, clientSecret?, scopes?, clientName? }` (new type `McpOAuthOptions`; refused on stdio entries by the spec schema). The MCP SDK's client does discovery (RFC 9728 protected resource metadata, RFC 8414 authorization server metadata), dynamic client registration (RFC 7591) when no `clientId` is given, PKCE and resource indicators (RFC 8707), and refreshes an expired token; tokens are kept in the agent's encrypted token store as provider `mcp-<server>`, owned by the app. An operator signs the agent in once with the new `agent.oauth.mcpSignInUrl(server)`; N9b's `agent.oauth.complete()` and `GET /oauth/callback` finish it. Without a usable token the server's status is the new `'needs-auth'` and connecting fails with the new error code `LOUSHO_MCP_AUTH_REQUIRED` (a tool call refused mid-run is a tool error with that code; nothing pauses). `connectMcp(servers, { tokens })` takes the token store. Security: `oauth` needs an https `url` (http only for localhost, 127.0.0.1 and [::1]); an `Authorization` header together with `oauth` is refused; with `oauth`, `headers` go only to the MCP server's origin, never to the authorization server; a stored grant is only used for the `url` it was obtained for (a changed `url` needs a new sign-in); no token, code, verifier or client secret appears in errors, logs, `status()`, events or results. Out of scope for now: per-user MCP grants, a `lousho mcp login` command, OAuth over stdio. See docs/oauth.md, "MCP servers with OAuth".
+- Parallel input guardrails: `IoGuardrail.runInParallel` (default `false`) makes an `input` guardrail run while the first model call is already in flight, so a slow, model-backed check no longer delays the answer by its whole latency; `promptInjectionGuardrail({ runInParallel })` and `moderationGuardrail({ runInParallel })` take it as an option. The blocking input guardrails run first as before (rewrites included), then the parallel ones start together on that input. Until all have passed, the call's `text.delta`, `reasoning.*` and provider-run tool events are held in order (on the iterator and `onAgentEvent` alike), its tool calls do not run, and `onLLMResponse`, post-generate hooks, output guardrails, `text.done` and the checkpoint after the response wait. A trip aborts the call (its signal only, not the run's), drops the held events and ends the run with `finishReason: 'guardrail'`, `result.guardrail` and `guardrail.tripped` (or `GuardrailError` under `onTripped: 'throw'`), with nothing of the call in the transcript or a checkpoint; the call's usage counts in `result.usage` only when the provider reported it. A parallel check cannot rewrite (`action: 'rewrite'` blocks, the reason prefixed `runInParallel guardrails cannot rewrite: `), and a check that throws fails the run. Ignored on `output` and `tools` guardrails. No change for guardrails without the flag. See docs/guardrails.md#input-and-output-guardrails.
+- OAuth sign-in for tools: `defineOAuthProvider({ name, displayName?, credentialOwner?, authorizationUrl, tokenUrl, clientId, clientSecret?, clientAuth?, scopes?, redirectUri, authorizationParams?, fetch? })`, and in a tool `ctx.getToken(provider)` and `ctx.requireAuth(provider)`. Without a usable token the run pauses durably like an approval (`finishReason: 'awaiting-approval'`, `kind: 'sign-in'`, `signIn: { provider, displayName?, url }` on the pending approval and the `approval.requested` event); the authorization URL uses PKCE S256 and a single-use 256-bit `state` that expires after 10 minutes, and the verifier is kept only in the encrypted pending record. The new route `GET /oauth/callback` (`lousho dev`, the node server, the Worker) and `GET <basePath>/oauth/callback` (`createRouteHandler`) is not behind route auth (a browser redirect carries no API token): it calls the new `agent.oauth.complete({ state, code?, error? })`, which stores the token for the paused run's principal and answers a small HTML page (400 for an unknown, used or expired state). Approving the pause (`agent.approvals.resolve({ id, approved: true })`, or the approvals route) runs the tool call again; before the callback it throws `LOUSHO_SIGNIN_PENDING` (HTTP 409) and the run stays paused. Tokens within 60 s of expiry are refreshed; `requireAuth()` deletes a refused token and pauses. A user credential needs a principal (`LOUSHO_OAUTH_PRINCIPAL_REQUIRED`); an app credential (`credentialOwner: 'app'`) is never asked of a chat user (`LOUSHO_OAUTH_APP_SIGNIN_REQUIRED`) and is connected by the operator with `agent.oauth.signInUrl(provider)`. The `approve` callback is never asked about a sign-in. Slack sends the link with `chat.postEphemeral` and Discord as an ephemeral follow-up, both without buttons; GitHub never posts it in a public thread; behind `createDeployedServer()` and `lousho dev` the callback continues the paused channel turn. The UI state (`pendingApproval.signIn`), the `data-lousho-approval` part, `lousho dev`'s page, `lousho chat` and `lousho acp` show the link. A tool result that contains a token handed out during that call is redacted to `[REDACTED]` with a warning. New error codes `LOUSHO_OAUTH_PRINCIPAL_REQUIRED`, `LOUSHO_OAUTH_APP_SIGNIN_REQUIRED`, `LOUSHO_OAUTH_STORE_MISSING`, `LOUSHO_OAUTH_STATE_INVALID`, `LOUSHO_SIGNIN_PENDING`, `LOUSHO_OAUTH_TOKEN_EXCHANGE_FAILED`. See [OAuth](docs/oauth.md#tools-that-need-sign-in).
+- Hosted tools on Anthropic and OpenRouter: `webSearch()` and `codeInterpreter()` now also run on the Anthropic provider (`ai` 6 with `@ai-sdk/anthropic` 3, `ai` 7 with `@ai-sdk/anthropic` 4): `webSearch()` is the newest `tools.webSearch_*()` the installed package exports (options `maxUses`, `allowedDomains`, `blockedDomains`, `userLocation`), `codeInterpreter()` the newest `tools.codeExecution_*()`; events and `usage.hostedToolCalls` keep the neutral name `code_interpreter`. `fileSearch()` on Anthropic, and `codeInterpreter()` / `fileSearch()` on OpenRouter, are `LOUSHO_HOSTED_TOOL_UNSUPPORTED`. `webSearch()` works with every `openrouter/...` model on any `ai` major: the provider adds OpenRouter's `openrouter:web_search` server tool to the request body (after the function tools, composing with the `reasoning` field; `maxUses`, `allowedDomains`, `blockedDomains` and `searchContextSize` map to its parameters) and reports one hosted call per step that searched, read from the response: the cited urls from `url_citation` annotations as `sources`, and `result: { requests }` when OpenRouter reports `usage.server_tool_use.web_search_requests`. OpenRouter bills each search on top of tokens (not in `costUsd`). `supportsHostedTool()` on both providers reflects this. The per-provider table in docs/hosted-tools.md is complete, and a replayable cassette from a live OpenRouter search is in the test suite (`npm run test:live` re-records it with `OPENROUTER_API_KEY`).
+- Hosted provider tools: `webSearch()`, `codeInterpreter()`, `fileSearch()` and `hostedTool(name, aiSdkTool)` go in `createAgent({ tools })` next to local tools (array or record form; in the record form the key must be the tool's name), and the provider runs them inside the model request. OpenAI maps them to `openai.tools.webSearch()` / `.codeInterpreter()` / `.fileSearch()` on `ai` 6 with `@ai-sdk/openai` 3 and `ai` 7 with `@ai-sdk/openai` 4 (options it does not take, such as `maxUses`, are dropped with one warning); `hostedTool()` passes any AI SDK provider tool through on `ai` 6 or 7, including on `fromAiSdk()` models. Provider-executed calls are never handed to the executor as local tool calls (on `ai` 6/7 they used to come back as calls of an unknown tool): they are reported as `tool.start` / `tool.done` / `tool.error` with the new optional field `executedBy: 'provider'` (as they stream in, or after a non-streamed call in call order; results capped at 20,000 characters of JSON), kept on the step's assistant message as `metadata.hostedToolCalls` (with url sources; not sent back to the model), counted in `usage.hostedToolCalls` and `run.done` usage per tool name (fees not in `costUsd`), and named on the `chat` span as `lousho.hosted_tool_calls`. A step whose only calls the provider ran ends the run even when the provider reports `tool-calls`. No permission rule, guardrail, approval or hook runs for them; instead, in permission mode `'plan'` only the read-only `webSearch()` and `fileSearch()` are sent to the provider (`codeInterpreter()` and `hostedTool()` are left out of the request, read before every model call), and every other mode sends them all. New: `ExecuteOptions.hostedTools`, `GenerateOptions.hostedTools`, `GenerateResult.hostedToolCalls`, `HostedToolCall`, stream chunks `hosted-tool-call` / `hosted-tool-result`, optional `LLMProvider.supportsHostedTool(type)`, `mockModel` turns with `hostedToolCalls`, cassettes that keep hosted calls, error code `LOUSHO_HOSTED_TOOL_UNSUPPORTED` (ai 4, Ollama, a provider without `supportsHostedTool()`, or an `@ai-sdk/openai` without the tool). Sub-agents do not inherit the lead's hosted tools; the agent fingerprint includes them. Anthropic and OpenRouter mappings follow in N1b (below). See docs/hosted-tools.md.
+- `session.history()` and `session.fork({ fromStep, id?, patch? })` on `agent.session()` sessions. `history()` lists the steps of the committed transcript (one per model response: `step` numbered from 1 across the session, `turn`, `messageIndex`, `text`, and `toolCalls` with `args` and `result`). `fork()` saves the transcript up to and including a step (`0` keeps nothing), optionally with one tool result replaced (`patch.toolResult`), under a new id in the same store (default `<id>-fork-<n>`) and returns a session of the same agent and options (with the permission mode the session has at that moment); the original is not changed. The spend recorded for `limits` up to that point carries over. A turn waiting on an approval or a question, or an interrupted checkpointed turn, stays with the source session, so it is resolved once; workspace files are not rewound. Works on every shipped store (memory, `fileStore()`, `SqliteStore`, `KVStore`), with one contract suite run against each. New types `SessionHistoryStep`, `SessionForkOptions` and `SessionSpawner`; new error codes `LOUSHO_SESSION_STEP_NOT_FOUND`, `LOUSHO_SESSION_EXISTS` and `LOUSHO_SESSION_FORK_UNSUPPORTED`; `AgentSession`'s constructor takes an optional fourth argument, the function that creates its forks. See [Forking a session](docs/sessions.md#forking-a-session).
+- Permission modes: `createAgent({ permissionMode })`, `send()` / `stream()` `{ permissionMode }`, `agent.session({ permissionMode })` and `session.setPermissionMode()` put an agent in `'plan'` (only read-only tools run; everything else is refused with `kind: 'denied'`, also when an `allow` rule matched, and a run that starts in plan mode gets one system-prompt paragraph saying so), `'acceptEdits'` (file edits that would ask run without asking) or `'dontAsk'` (a call that would ask is refused; nothing pauses). The modes are presets applied after hooks, permission rules, tool guardrails and `needsApproval`, so no mode turns a deny into a run. A function mode, and a session's mode, are read at every tool call, so a switch applies from the next call, also mid-turn and in a paused turn continued by `agent.approvals.resolve()`. Sub-agents run under the lead's mode unless it is `'default'`; a remote sub-agent is refused in plan mode. Audit: under a mode other than `'default'` every call is audited, `PermissionDecisionEntry.mode` says when the mode changed the outcome, and the new `onPermissionModeChange` records each switch. New: `PermissionMode` and `PermissionModeChange` types, `defineTool({ editsFiles })` (`metadata.editsFiles`, set on `write_file` and `edit_file`), `readOnlyHint: true` on `load_skill`, `recall_<name>`, `agent_status` and `agent_await`. The mode is not saved in checkpoints. Example: `examples/plan-mode`. See [Permission modes](docs/permission-modes.md).
+- Semantic recall: a memory slot can recall by meaning. New `EmbeddingProvider` (`{ id, embed(texts) }`) and `aiSdkEmbedder(model, { id?, maxBatch? })`, which wraps any AI SDK embedding model through `embedMany` from the installed `ai` (4, 6 or 7; `ai` is loaded on first use, no new dependency), and two providers that rank by cosine similarity: `inMemoryVectorMemory({ embedder, maxItems?, minScore? })` from the root and `sqliteVectorMemory(store, options)` from `@lousho/build-ai-agent/sqlite` (a new `memory_vectors` table, added to an existing database file on open; `memory_items` and `sqliteMemory()` are unchanged). With a query, `list()` returns the scope key's items by score (floor `minScore`, default 0.2; score in `metadata.score`); without one it lists the newest first. Items embedded by another embedder id are skipped when ranking until `provider.reindex(scopeKey?)` re-embeds them. A `MemoryProvider` may set `ranking: 'relevance'`, which makes the `recall_<name>` tool say "by meaning, most relevant first". `hashEmbedder({ dimensions? })` from `@lousho/build-ai-agent/testing` is a deterministic offline embedder for tests. `describeMemoryProviderContract` takes `{ query: 'filter' | 'rank' }`. docs/memory.md has a new `## Semantic recall` section at the end.
+- `teamsChannel({ appId, appPassword, tenantId?, name?, fetch?, approvers?, onError? })`: an agent behind an Azure Bot in Microsoft Teams, mounted like the other channels (`POST <basePath>/teams`). The inbound Bot Framework token is verified with the auth module (`oidc()`: RS256, the key set of the fixed Bot Framework OpenID metadata, issuer `https://api.botframework.com`, audience `appId`, 5-minute tolerance) before the body is parsed, and its `serviceurl` claim must equal the activity's `serviceUrl`; replies go only to that service URL (https). Personal chats always reach the agent, group chats and channels only on an `@mention` (stripped from the text); one session per conversation; Markdown replies split at 25,000 characters; tool approvals are Adaptive Cards with Approve and Deny buttons (`approvers` as on the other channels; the card updates to "Approved by..." and names its conversation, so a copied or replayed reference decides nothing); `ask_question` is answered by the next message, also after a restart with durable stores. No `node:*` import. Telegram and GitHub now set the sender as the run's `principal` too (`authenticator: 'telegram'` with the user id, `'github'` with the login), as Slack and Discord do. See docs/channels.md#microsoft-teams.
+- Cloudflare Worker target builds agent directories (config, instructions, TypeScript tools, skills): `npx @linuxdevil/lousho build./my-agent --target=cloudflare-worker`. The build reads the directory on Node and generates `agent.module.ts` (static imports of `tools/*` and of an `agent.ts` config; `instructions.md`, a JSON/YAML config and the skills embedded as JSON), and the Worker builds the agent with the rules of `resolveAgentDir()` (the config check and the tool-export rules now live in Node-free modules both use). The config's `model` must name a Worker provider, or `agent.ts` sets a `provider` instance. `subagents/`, `schedules/`, `channels/`, `memory/`, `projectInstructions` and an unsupported provider are rejected with `LOUSHO_DEPLOY_FAILED`, naming what to remove. In a Worker build, an agent file's `@lousho/build-ai-agent` import resolves to a Worker-safe subset (`defineTool`, `defineSkill`, the Worker providers, `fromAiSdk`, errors,...); another name fails the build with the list. The leak check now names the file that imported a Node builtin (`"node:fs" imported by my-agent/tools/files.ts`) instead of failing with esbuild's "Could not resolve". Tools run in the Worker's isolate with its rights: see docs/cloudflare-workers.md#build-and-deploy.
+- Workspace rewind: `createFsTools(fs, { checkpoints })` with a new `WorkspaceCheckpoints` backs up every file `write_file` and `edit_file` change (content and, where the provider has the new optional `FsProvider.getMode` / `chmod`, permission bits), grouped by session and turn. `checkpoints.list({ sessionId })` shows the changed paths per turn; `checkpoints.rewind(toTurn, { sessionId, dryRun, force })` restores every file changed in that turn or later, deletes files the agent created, and skips files changed since by something else (`'changed-since'`), files over `maxFileBytes` (`'too-large'`) and paths that are no longer files. Every path is checked before anything is written, and restores go through the provider, so `NodeWorkspace` keeps them inside its root. Retention: the newest `maxTurns` turns per session (default 20), the old content only for a turn's first write of a path, rewound turns dropped, `clear({ sessionId })`. Stores: `MemoryWorkspaceCheckpointStore` (default) and `FileWorkspaceCheckpointStore(dir)` (one JSON file per session, atomic writes). `NodeWorkspace` gains `getMode()` and `chmod()`. Without `checkpoints` the tools behave as before. See [Workspace tools](docs/workspace-tools.md#the-tools).
+- Route auth and principals: a new subpath, `@lousho/build-ai-agent/auth`, with `jwt()`, `oidc()`, `basic()`, `apiToken()`, `anonymous()` and `routeAuth()`. A route takes an ordered list of entries: the first one that returns a `Principal` accepts the request, `null` skips to the next, `AuthError(401 | 403)` stops; when every entry skips the answer is a generic `401` with one `WWW-Authenticate` header per challenge (`Bearer`, `Basic realm="..."`), and the body never says which check failed. JWTs are verified with Web Crypto only (no new dependency, no `node:` import, so the helpers run on Workers and edge routes): `alg: none`, algorithms outside the configured list, a `crit` header and algorithm confusion (an HS token checked against a public key) are refused; `exp` is required, `nbf` / `iat` honored, `iss` / `aud` checked, with a clock tolerance of 60 s (at most 300); JWKS key sets are cached for 10 minutes and refetched at most once per 30 s, and a key-set URL is never taken from a token. `oidc()` uses the configured issuer's discovery document and requires it to name the same issuer. `basic()` and `apiToken()` compare in constant time. `createRouteHandler({ auth })` and `createDeployedServer(agent, { auth })` take the list (a token string and a boolean function work as before); the node server appends `apiToken(LOUSHO_API_TOKEN)` when that variable is set; an agent directory's `auth.ts` is bundled by `lousho build --target=node-server` / `docker` and guards the built server (`resolveAgentDir()` returns it as `auth`, the manifest has `auth: true`). The accepted principal reaches the run: `send()` / `stream()` / session turns take `principal`, and `RunConfigContext` (the `model` / `instructions` / `tools` functions) and `MemoryScopeContext` (memory scopes) carry it; Slack and Discord channels set the sender as the principal. `Principal` is also exported from the root. Bad helper options throw the new error code `LOUSHO_AUTH_CONFIG_INVALID` when the helper is created. `createRouteHandler()` without `auth` logs one warning when `NODE_ENV` is `production`. Route auth does not check session ownership, the principal does not reach tools or approval policies yet, and the Cloudflare Worker target keeps the `LOUSHO_API_TOKEN` token only. See [Route auth and principals](docs/auth.md).
+- OAuth token storage: `AgentStore` gains a fourth optional part, `tokens` (`OAuthTokenStore`: `get` / `set` / `delete` / `list` per provider and credential owner, single-use pending sign-ins with `putPending` / `takePending`, and `getClient` / `setClient` for dynamically registered clients). Owners are `{ owner: 'app' }` or `{ owner: 'user', principalId, issuer? }`; `tokenStoreKey(provider, owner)` is the stable, percent-encoded record key (`<provider>|app`, `<provider>|user|<issuer>|<principalId>`). `memoryStore()` keeps tokens in process memory; `fileStore(dir)`, `SqliteStore` and `KVStore` encrypt every record with AES-256-GCM (Web Crypto, a fresh 12-byte IV per write, the record key as additional authenticated data) under a 32-byte key the application supplies as `tokenKey` or `LOUSHO_TOKEN_KEY`; there is no default key. Several keys (newest first, or comma-separated in the variable) rotate: writes use the first, reads try each. New error codes `LOUSHO_TOKEN_KEY_MISSING` (first write, or a read of an existing record, without a key) and `LOUSHO_TOKEN_DECRYPT_FAILED` (wrong key or a changed record; names the provider, never the token). `list()` returns metadata only. `generateTokenKey()` makes a key. SQLite: schema migration 4 adds the `oauth_tokens` and `oauth_pending` tables, and `prune()` also deletes expired pending sign-ins (its result gains `oauthPending`). KV: keys under `<prefix>oauth/`, pending sign-ins written with an `expirationTtl`; `KVBinding` gains an optional `list()` (used only by `tokens.list()`), and `KVListOptions` / `KVListResult` are exported from `/kv`. The generated Cloudflare Worker passes its `LOUSHO_TOKEN_KEY` secret to `KVStore`. Nothing signs in yet; the sign-in flow follows. New page [OAuth](docs/oauth.md); new `## OAuth` section at the end of docs/errors.md.
+- `githubChannel({ webhookSecret, botName, token?, app?, botLogin?, name?, apiUrl?, fetch?, triggers?, approvers?, onError? })`: an agent that answers GitHub issue, pull-request and review comments. `@<botName>` in a comment starts a turn and the reply is a new comment in the same thread (a review thread gets a reply under it; text over 60,000 characters is split); one session per issue or pull request and one per review thread, and later comments in a thread with a session are follow-ups. `X-Hub-Signature-256` is verified over the raw body in constant time before the body is parsed (401 otherwise); the webhook is acknowledged at once. Comments by bots, by the channel's own account and every comment the channel posts (a hidden marker) are ignored, and so are edits, deletions and other events. Replies are posted with `token` (a personal access token, or a function) or as a GitHub App (`app: { appId, privateKey }`: a PKCS#1 or PKCS#8 key signs an RS256 JWT with Web Crypto, exchanged for an installation token that is cached per installation until 5 minutes before it expires; `src/channels/githubAppAuth.ts`, not exported). Approvals are comments: the prompt asks for `/approve <id>` or `/deny <id>` (first line only, notes below it), and by default only a commenter whose `author_association` is `OWNER`, `MEMBER` or `COLLABORATOR` may decide, read from the command comment itself; `approvers` (logins, or a function that sees the association in `user.roles`) overrides it, and `triggers` (logins, or a function) restricts who may start a turn or answer a question (default: everyone who can comment, so restrict it on a public repository). A comment is untrusted input to the agent; see the security note in docs/channels.md. An `ask_question` is answered by the next comment in the thread and survives a restart given durable stores. Errors name the call and the HTTP status, never the token. The `LOUSHO_CHANNEL_INVALID` hint, docs/agent-directories.md and docs/errors.md now list `githubChannel()`. New section `## GitHub` at the end of docs/channels.md.
+- Agent Forge keeps the traces of its runs: every run is written with `fileTraceExporter()` to `.lousho/agents/<agent id>/traces` (the files `lousho traces` reads), and the Trace tab gets a list of the agent's past runs (time, duration, model calls, tokens, cost, status) with a "Live" entry while a run is active; choosing one opens its spans in the waterfall, with span kind and error status. New server routes `GET /agents/:id/traces?limit=N` and `GET /agents/:id/traces/:traceId`; the server reads only inside the agent's trace folder. The live `span` WebSocket messages now carry `kind` and `status` (optional fields of `SpanEvent`). See [Agent Forge](docs/agent-forge.md).
+- A background sub-agent that needs approval pauses the lead when the lead awaits it (`agent_await`), and resumes with `approvals.resolve()` / `resume()`. The lead's result is `awaiting-approval` with the child's call (`subagentPath: ['<agent>']`) in `agent.approvals.list()`; the decision runs or rejects the child's call, the child finishes, and the continued lead gets its answer as the `agent_await` result. A child that pauses again, or several awaited tasks that are all paused, pause the lead one approval at a time. The child's usage is added to the lead's, and its conversation is saved under its `taskId`. The paused tasks are kept on the lead's approval record (`SubagentSuspension.background`, plain JSON), never in the tool arguments the model sees. Without `agent_await` nothing changes: the task reports `awaiting-approval` and is not resumable. The `task` and `agent_status` tool descriptions tell the model that a task awaiting approval continues only when it calls `agent_await` on it. Docs: docs/sub-agents.md ("When the lead run ends" and "Continuing a task").
+- Guardrail starter set: `piiGuardrail()` (email, phone, credit card with a Luhn check, IBAN with its mod-97 check, US SSN, IPv4; blocks, or rewrites each match to `[<type>]`), `secretsGuardrail()` (private keys; Anthropic, OpenRouter, OpenAI, AWS, GitHub, Slack, Google and Stripe live keys; JWTs; `Authorization: Bearer` tokens; `extraPatterns`; rewrites to `[secret]` by default), `promptInjectionGuardrail()` (phrase, role-marker and Unicode-tag heuristics, plus an optional model check that must answer `SAFE` or `INJECTION: <reason>`) and `moderationGuardrail({ model })` (one model call that answers `NONE` or the categories that apply: `hate`, `harassment`, `self-harm`, `sexual`, `sexual-minors`, `violence`, `illicit`). The PII, secret and injection checks are heuristic pattern checks: they catch common cases and miss others, and are not a security boundary. Model-backed checks fail closed on a reply they cannot read. A guardrail result can now carry `info?: GuardrailTripInfo` (`pii`, `secret`, `prompt-injection`, `moderation` or `custom`), copied to `result.guardrail`, `guardrail.tripped` and `guardrail.rewrote`; it holds types, labels and offsets, never the matched text. Agent spec files can name them in `policy.guardrails` as `pii`, `secrets`, `prompt-injection` and `moderation`. New exported types `GuardrailTripInfo`, `PiiType`, `ModerationCategory`. Docs: [Guardrails](docs/guardrails.md#input-and-output-guardrails), [Configuration](docs/configuration.md#policy-policy), [Stream events](docs/stream-events.md).
+- `telegramChannel({ botToken, secretToken, botUsername?, name?, fetch?, approvers?, onError? })`: an agent behind a Telegram bot, mounted like the Slack and Discord channels (`POST &channels&telegram`). The webhook secret token header (`X-Telegram-Bot-Api-Secret-Token`) is compared in constant time (401 otherwise); updates are acknowledged with `200` and the turn runs after. A private chat is one session per chat; in a group only `&ask`, `&ask@<botUsername>`, an `@<botUsername>` mention or a reply to the bot wakes it, and a forum topic is its own session. Replies are plain text, split at 4096 characters. Tool approvals are an inline keyboard (Approve & Deny) that only `approvers` (default: the user who started the turn) can tap; the tap names its chat, so it works after a restart. An `ask_question` is sent with `force_reply`; a pending one survives a restart given durable stores, like Slack and Discord. The bot token is never put in an error message or log line. `src&channels&channelSupport.ts` gains the internal `secretsEqual()` (constant-time compare with Web Crypto). The `LOUSHO_CHANNEL_INVALID` hint, docs&agent-directories.md and docs&errors.md now list `discordChannel()` and `telegramChannel()`. New section `## Telegram` at the end of docs&channels.md (attachments are not read yet).&r
+- `todo.updated` stream event and `useTodos()` (React, Vue) / `loushoTodos()` (Svelte): every successful `todo_write` emits `todo.updated { todos, counts, toolCallId }` right after its `tool.done` (sub-agents too, with `subagent`). The shared UI reducer keeps the list in a new `AgentUIState.todos` (carried across turns, cleared by `reset()`), `useLoushoAgent()` / `loushoAgent()` expose it, `useTodos(agent)` / `loushoTodos(agent)` add counts, the current item and progress (`todoView()` computes the same view framework-free), and `toUIMessageStream()` sends a `data-lousho-todos` part for the AI SDK UI. See [Todos](docs/react.md#todos).
+- Cloudflare Worker target: the `openrouter` provider and the `http` tool (with a required `LOUSHO_HTTP_ALLOW` host allowlist). `openrouter` reads its key from the `OPENROUTER_API_KEY` binding and is `@ai-sdk/openai` pointed at OpenRouter, so its bundle passes the `node:` leak check like `openai`. The Worker's `http` is `http_request` with the Node tool's input, over the platform `fetch()`: since a Worker cannot see or pin where a host name resolves, it reaches only the host names (`api.github.com`) and `*.` wildcards (subdomains only) listed in the comma-separated `LOUSHO_HTTP_ALLOW` binding, refuses IP-address hosts even when listed and any scheme but `http:`/`https:`, checks every redirect hop the same way, and refuses every request when the binding is unset or empty. An invalid entry fails every request with an error naming it. `wrangler.toml` gets a commented `[vars]` `LOUSHO_HTTP_ALLOW` line when the spec lists `http`. `ollama` and `web-fetch` stay unsupported on Workers. Internally, the request, redirect and response logic of `http_request` moved to the Node-free `src/tools/built-in/httpCore.ts`, shared by both tools; the Node tool's behaviour is unchanged. See docs/cloudflare-workers.md#providers-and-tools.
+- `fromAiSdk(model)`: any AI SDK `LanguageModel` (Google, Bedrock, Azure, Mistral, Gateway,...) as `createAgent({ provider })`. Options `name` (default: the model's `provider` field), `fileMediaTypes`, `replaysReasoning` and `maxRetries` (default 0); exported with `FromAiSdkOptions` from the package root. Throws `LOUSHO_CONFIG_INVALID` for a model id string, for a model built for another `ai` major than the installed one, and for a call with another model id than the wrapped one. See docs/providers.md#any-ai-sdk-model-fromaisdk.
+- Two ready-made durable stores. `@lousho/build-ai-agent/kv` is a new subpath exporting `KVStore`, `KVCheckpointStore`, `CHECKPOINT_KV_BINDING` and the types `KVStoreOptions`, `KVBinding`, `KVPutOptions`, so a hand-written Cloudflare Worker can use `createAgent({ provider, store: new KVStore(env.AGENT_KV) })`; nothing in its import graph touches `node:*`, so it bundles without shims (`assertSessionId` moved to the Node-free `src/session/sessionId.ts` and is still exported where it was). `fileStore(dir, { historyLimit? })` (root export) is an `AgentStore` of plain JSON files: `sessions/<id>.json`, `checkpoints/<id>.json`, `checkpoint-history/<id>.json` and `approvals/<id>.json`, each written to a temp file and renamed into place, with no lock files and no `StorageService`; resolving an approval claims it with an exclusive create, so of two processes resolving one approval only one gets it. It replaces combining `FileSessionStore`, `LocalStorageCheckpointStore` and `StorageServiceApprovalStore` by hand. See docs/sessions.md#choosing-a-store and docs/deployment.md.
+- `web_fetch` built-in tool: `webFetchTool` / `createWebFetchTool(options)`, and `web-fetch` in spec files. It `GET`s one public web page and returns `{ url, finalUrl, status, contentType, content, truncated }`: HTML converted to text by a small built-in converter (scripts and styles dropped, link URLs kept, entities decoded), JSON and `text/*` as sent, a note for other types; a 4xx/5xx is returned with its body. Loopback, private and link-local destinations are refused on every hop with the connection pinned to the checked address; redirects (10), bytes read (2 MiB), characters returned (50 000) and time (30 s) are capped; `allowedHosts` / `blockedHosts` are checked before DNS and `allowPrivate` exempts named hosts. Node only. See docs/tools.md#built-in-tools.
+- `src/security/privateAddress.ts` (internal): `isPrivateAddress()` and `pinnedLookup()`, shared by the credential broker, `http_request` and `web_fetch`. The credential broker uses it instead of its own list, so it also refuses `192.0.0.0/24`, `198.18.0.0/15`, NAT64 and 6to4 addresses.
+- Slack and Discord: a pending `ask_question` survives a restart. Given durable stores for sessions, checkpoints and approvals, the next message in the Slack thread (or the next `/ask` in the Discord channel) after a restart is still the answer: the turn continues, the reply is posted, and the question, the answer and the reply are appended to the session transcript (before, the answer became a new turn and the question was orphaned). A message in a conversation that waits on a tool approval still does not decide it. New `ChannelContext.pendingQuestion(sessionKey)` for custom channels: the id of the `ask_question` that key's session waits on, also one asked before a restart (it binds the approval to the session, so the continuation is recorded); handed out once until that answer has run. A channel's answer and click continuations now run one at a time with the session's turns. Supporting additions: `Checkpoint.approvalKind`, `PendingTurn.approvalKind` (`session.pending()`) and `SessionAwaitingApprovalError.approvalKind` are `'question'` for a turn paused on an `ask_question`. Slack thread replies that answer a pending question no longer need a saved transcript first (a first turn paused on a question with checkpoints has none yet). See docs/channels.md.
+- Local traces and `lousho traces`: `createAgent({ exporter, captureContent })` traces every run of the agent (`send()`, `stream()`, session turns, `agent.resume()` and runs continued by `agent.approvals.resolve()`; sub-agents join the lead's trace). The new subpath `@lousho/build-ai-agent/traces` exports `fileTraceExporter({ dir })`, which writes each run as JSON Lines to `<dir>/<YYYY-MM-DD>/<traceId>.jsonl` (default `.lousho/traces`; one finished span per line; a write error warns once and never fails the run), and `listTraces()` / `readTrace()` to read them. `npx @linuxdevil/lousho traces [--dir D] [--limit N] [--json]` lists recent runs with duration, model and tool calls, tokens and cost; `npx @linuxdevil/lousho traces <id|prefix> [--json] [--content]` prints one run as a span tree with duration bars. Projects made by `lousho init` now ignore `.lousho/`. See docs/observability.md#local-traces.
+- `openApiTools(document, options)`: an OpenAPI 3.0 / 3.1 document (object, JSON or YAML string, or https URL) becomes one typed tool per operation, exported from the root and `./tools`. Names come from `operationId` (or `<method>_<path>`); the input has path, query, header and cookie parameters plus an `application/json` `body`, with `$ref`s resolved; every HTTP response is returned as `{ status, statusText, body }`. GET, HEAD and OPTIONS run and other methods ask for approval by default (`approval`), with read-only / destructive annotations. Options: `baseUrl`, `include`, `exclude`, `prefix`, `headers`, `bearerToken`, `providedArguments` (removed from the model's schema), `timeoutMs`, `maxResponseChars`, `fetch`. The base URL must be https (http only for loopback), credentials never reach events or the transcript, and redirects are followed only on the base origin. Swagger 2.0, multipart bodies and remote `$ref`s are refused. `jsonSchemaToZod(schema, root?)` takes an optional root for `$ref` resolution. New page docs/openapi-tools.md.
+- Built-in OpenAI, Anthropic and OpenRouter providers send PDF file parts on `ai` 6 and 7 (Anthropic also `text/plain`); `ai` 4 and Ollama keep the text note. A provider subclass opts more media types in with `fileMediaTypes()` (`acceptsFileParts = true` still sends every type). The text-note warning is now once per provider and media type and names the type and the `ai` major. Added `npm run test:live` (`vitest.live.config.ts`) for `*.live.test.ts` files, which the default suite excludes. See docs/providers.md#multimodal-input.
+- Principals in tools, approval policies and permissions: the run's principal reaches a tool's `execute(args, ctx)` as `ctx.principal`, `needsApproval` functions (`ApprovalCheckContext.principal`), permission rules' `when(args, ctx)` (`PermissionContext.principal`), `preToolCall` / `postToolCall` hooks (`ToolCallHookContext.principal`), `onPermissionDecision`'s new second argument (`PermissionAuditContext`), pending approvals (`PendingApproval.principal`, seen by `approve` and by a channel's `approvers` function as `request.principal`) and in-process sub-agents (`task`, background tasks, `createDelegateTool()`; `remoteAgent()` does not forward it). New `ExecuteOptions.principal`, set by `createAgent()` for `send()`, `stream()`, session turns and channel turns. It is saved in checkpoints (`Checkpoint.principal`) and approval snapshots (`ExecutionSnapshot.principal`), so a static or dynamic run resumed after an approval or a crash acts for the same caller. `agent.approvals.resolve()` / `answer()` / `streamResolve()` / `streamAnswer()` take `{ principal }` (new `ResolveApprovalOptions`) for who decides, and the approved tool sees it as `ctx.approval.by`; `resumeAfterApproval()` takes it as `executeOptions.approver`. The approvals route (`POST /chat/:sessionId/approvals/:id`) passes the caller route auth accepted, and `mountChannels()` the clicking user (`{ id, type: 'user', authenticator: <channel name> }`) or, for a question answered by a message, its sender. `agent.fork()` keeps the source run's principal; `session.fork()` copies only the conversation. The principal is not added to events, spans or trace files. See [Principals in tools and approvals](docs/auth.md#principals-in-tools-and-approvals).
+
+### Deprecated
+- `SlackTriggerAdapter`, `CronTriggerAdapter` and `WebhookTriggerAdapter` (`@lousho/build-ai-agent/triggers`) are deprecated and will be removed in a future major version. Use `slackChannel()` for Slack (sessions per thread, approval buttons), `defineSchedule()` with `startSchedules()` for cron (or `schedules/` in an agent directory, or cron triggers in a spec file), and `webhookChannel()` for webhooks, each mounted with `mountChannels()`. `verifySlackSignature()`, the `WebhookAuth` helpers, `parseCronExpression()`, `TriggerAdapter` and `TriggerRegistry` are not deprecated. Their options types (`SlackTriggerAdapterOptions`, `CronTriggerAdapterOptions` with `CronIntervalOptions` and `CronExpressionOptions`, `WebhookTriggerAdapterOptions`) and `WebhookTriggerHandle` carry `@deprecated` too. Nothing changes at run time. See docs/triggers.md.
+
+### Fixed
+- `@linuxdevil/lousho` CLI surface: `lousho dev`/`lousho chat --traces` now writes traces for a `.ts`/`.js` module that exports an already-built `createAgent()` agent - the module's export could not take the flag's exporter after the fact, so nothing was written. `createAgent()` remembers the config it was built with (readable via the internal `createAgentConfigOf()`), and the loader rebuilds the agent with the flag's exporter (the module's own `exporter` is replaced while the flag is set; a module exporting an agent not made by `createAgent()` prints a warning and keeps its own). A spec path that does not exist (e.g. `lousho chat missing.yaml`) now fails with the coded `LOUSHO_SPEC_NOT_FOUND` instead of a raw ENOENT. `lousho add --dry-run` no longer fails when a target file already exists; it prints the file list with an "(exists - a real install needs --overwrite)" marker and exits 0 (the symlink checks still run). Top-level `lousho --help` lists the implemented flags again: `--no-schedules`/`--traces` on `dev` and `chat`, `eval`'s record/replay/drift/`--config` flags, `init`'s `--sdk-path`, and `build`'s positional form.
+- A cassette failure keeps its type through `agent.send()`: a replay mismatch (or a missing cassette raised by the provider-interception seam that `lousho eval` installs) was compacted into a generic `CompactedLLMProviderError`, losing the cassette path, the call number and the re-record hint. `CassetteMismatchError` is now an `SDKError` with code `LOUSHO_CASSETTE_INVALID` (docs/errors.md already claimed cassette errors carry it), and the run loop rethrows cassette errors untouched instead of compacting them, so `send()` rejects with the `CassetteMismatchError` itself (`.cassette`, `.callNumber`). `setProviderInterceptor()` and the `ProviderInterceptor` type are now exported from `@lousho/build-ai-agent/testing`, the public entry for the model-boundary seam docs/evals.md describes.
+- A tool call approved with `agent.approvals.resolve()` (or `resumeAfterApproval()`) now has its `execute_tool` span. It ran before the continued run started, outside any span, so OpenTelemetry and `fileTraceExporter()` showed the continued run's `invoke_agent` and `chat` spans but not the approved tool. The continued run's `invoke_agent` span now opens first and the approved call runs inside it: its `execute_tool` span is a child of it (a `run_code` call's inner calls and a sub-agent the tool starts are children of the tool span), with the same `captureContent` / `redactContent` rules as any tool span, and no span is made for a rejected call. A pause that happens again (sign-in) leaves the `invoke_agent` span with the tool span and no `chat`.
+- A tool that returns `undefined` (or an async generator that yields nothing) no longer writes a `tool` message with `content: undefined` into the transcript. Its result is now `null` everywhere: the transcript and the next model request carry `"null"`, and `tool.done`, approval resumes, `run_code` and flows see `null`. Providers, session stores and checkpoints get a valid string.
+- `recordReplay` matches a tool's parameter schema the same way under zod 3 and zod 4. A zod 4 schema was fingerprinted from its JSON Schema (with `$schema`, `required`, `additionalProperties`) while a zod 3 one, and so every recorded cassette, used a fingerprint of the schema itself, so cassettes recorded with zod 3 failed to replay with zod 4 installed (the CI `peers` jobs `ai4-zod4`, `ai6-zod4` and `ai7-zod4` failed on every replay test). Both now give the same fingerprint for the same schema; existing cassettes stay valid and need no re-recording, and a real change to a tool's parameters still fails the match.
+- Parallel `task` calls now get their `taskId`s, and background tasks start, in call order: allocating an id awaited a SHA-256 digest whose completion order is not fixed, so with `maxConcurrent: 1` the second task could take the slot first (#296, the flaky "queues tasks beyond maxConcurrent" test).
+- `SubprocessSandbox.run()` no longer fails with HTTP 404 "no such container" for a command that exits at once: the container is `AutoRemove`d, and `wait()` was only called after `start()`, so a fast command could be gone by then (10 of 40 parallel `true` runs failed on Docker Desktop). It now begins `wait({ condition: 'next-exit' })` before `start()`, and removes the container if `start()` itself fails.
+- The `cloudflare-worker` build's Node-builtin leak check now accepts the runtime-guarded `loadNodeModule("node:module" | "node:dns")` probes that `@ai-sdk/provider-utils` 4 (installed with `ai` 6) uses, as it already did for `ai` 7's `loadBuiltinModule`; without it a Worker bundle built on `ai` 6 failed with "Node builtins leaked" (found by the new `ai6` matrix entries).
+- `isAgentEvent()` is now exhaustive (the runtime type list is a `Record<AgentEventType, true>`, so the compiler rejects a missing type). It had no `agent.drift`, so remote UI clients (`parseEventStream()`, the React, Vue and Svelte bindings) silently dropped that event.
+- A remote sub-agent's token usage is added to the lead's `result.usage`. It was dropped, so budgets and cost reports undercounted delegation to a `remoteAgent()`. The lead adds what the remote agent reports on its `run.done` event to its totals, to `usage.delegated` and to `byModel['remote:<name>']`, which keeps the remote's own `costUsd` (the lead's `costUsd` is `undefined` when the remote sends none). A remote run that pauses for an approval adds what it spent up to the pause, and the continuation adds only what it spent after it; background remote tasks roll up the same way. A deployment that sends no usage adds nothing. `RemoteRunOptions` has a new optional `onUsage(usage)` callback; `RemoteSubagent.run()` still returns `Promise<string>`, so hand-written ones compile unchanged. See docs/sub-agents.md#remote-sub-agents.
+- `lousho studio` finds the Agent Forge build that ships inside the installed package when it is run from a project that does not have `apps/agent-forge` (it used to fail with "could not find apps/agent-forge" everywhere except the SDK repo). A project's own `apps/agent-forge` still wins, and `.lousho/` is still created in the directory you ran it from. `--dev` from an installed package still needs the TypeScript source and says so.
+- Documentation corrections: install commands, CLI command lists, optional peers, durable execution and compaction descriptions, the Status section, reasoning and file-part notes in the providers guide, and the `KVStore` note in the deployment guide now match the code. Ticket ids are gone from user-facing prose.
+
+### Tests
+- Two more load-sensitive tests fixed. `SandboxShell.test.ts` "passes only set values and allowed host names, never planted secrets" starts two real `node -e` processes and timed out at the 5 s default in 1 of 20 parallel runs; it has a 30 s timeout now (pure slowness, no race: it passes in under a second alone). `backgroundSubagents.test.ts` "reports a sub-agent paused for approval as awaiting-approval" waited a fixed 10 ms for the child's pause and failed in 9 of 20 parallel runs with the task still `running`; the lead now asks `agent_status` again until the task has left `running`.
+- `http.test.ts` "rejects near the configured timeout" no longer compares real elapsed time to a real timeout (flaky under load, #324): it drives the request timer with a fake clock and checks the request is still pending at 499 ms, rejects with "timed out after 500ms" at 500 ms, and that the connection is closed.
+- `src/tools/workspace/checkpoints.node.test.ts` "rewinds three turns" has a 30 s timeout: it takes well under a second alone, but timed out at the 5 s default when eight copies of the suite ran at once. The rewind itself is correct; every failure was the timeout.
+- Live-model cassettes recorded: real gpt-4o-mini runs through OpenRouter are now replayed in CI with no key, for the coding agent in the docs, the Telegram, GitHub and Teams channels, plan mode, `web_fetch`, streaming `send()`, the guardrail starter set, `fromAiSdk()` and PDF/PNG file parts, plus a recorded `lousho traces` fixture. The live files that never ran (`sendStreams`, `guardrailStarterSet`, `fileTraceExporter`, `remoteUsage`) were missing the `import '../providers'` that registers OpenRouter; fixed. New live tests (skipped without a key): ai 6 through OpenRouter and `aiSdkEmbedder()` over OpenRouter embeddings.
+- `pack-smoke` allows a 16 MiB unpacked tarball (was 14 MiB): `main` was 45 KB under the old cap and permission modes went over it; see #316 for shrinking the package instead.
+- Sandbox egress and the credential broker are tested against a real Docker Engine: a new CI workflow, "Docker Engine" (`.github/workflows/docker.yml`, on pull requests touching the sandbox, broker or docker deploy adapter, on demand and weekly), runs `npm run test:docker` on GitHub's `ubuntu-latest` runner (rootful Engine 28.0.4). `src/security/sandboxEgress.docker.test.ts` checks nine cases of `SubprocessSandbox({ network: { allow }, broker })` with `curlimages/curl`: an allowed HTTPS host answers through the broker, another host gets a 403, bypassing the proxy and raw IPs have no route, outside names do not resolve, the broker injects a credential the container never sees, a container outside the internal network cannot use the gateway listener, an aborted run and `close()` leave no container or network, and a reused non-internal network is refused. The docker deploy image test (`/health` and `/chat`) moved to `src/deploy/adapters/docker.docker.test.ts` and runs in the same job; it was skipped in CI before and passes there. No product defect was found. `*.docker.test.ts` files are excluded from `npm test` and `npm run test:coverage`; they skip without a daemon unless `LOUSHO_DOCKER_TESTS=1` is set (the workflow sets it), which makes a missing daemon fail. docs/workspace-tools.md says what the job checks; CONTRIBUTING.md mentions `npm run test:docker`.
+- `src/execution/principal.test.ts` and `principal.test-d.ts`: the principal in tools (send, stream, session and channel turns), policies, rules, hooks and sub-agents (local, background, remote), pause and resume with another approver, a restart, a crash resume on an on-disk `SqliteStore`, old checkpoints and snapshots, forks, the approvals route and channel clicks; frozen in strict mode; absent from events and spans.
+- Test files can be type-checked: `npm run typecheck:tests` runs `tsc` over `src/` including every `*.test.ts` through the new `tsconfig.tests.json`, and the test files under `src/execution`, `src/context`, `src/session`, `src/subagents`, `src/acp` and `src/testing` now pass it. The check is not in CI yet. One type change: `textOf()` also accepts a message or content whose parts are `readonly`, such as a `mockModel` request snapshot.
+
+### Docs
+- The `vendor/` model prefix note: every docs page whose snippets hardcode a `provider/model` string now says the prefix chooses the provider and that with OpenRouter the id is `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`), so `createAgent()` does not throw `LOUSHO_PROVIDER_MISSING_API_KEY` when only `OPENROUTER_API_KEY` is set. Stale model ids refreshed: `anthropic/claude-3-5-haiku-latest` examples are now `anthropic/claude-haiku-4-5`, `'anthropic/claude-3-5-sonnet-latest'` in errors.md is `'anthropic/claude-sonnet-4-5'`, `google('gemini-2.0-flash')` is `google('gemini-2.5-flash')` and the OpenRouter fallback example uses `openrouter/meta-llama/llama-3.3-70b-instruct`. (`anthropic/claude-3-5-sonnet-latest` stays where it documents the `ANTHROPIC_API_KEY` env default, which is still that id in `src/providers/providerSpec.ts`.)
+- Corrections in [Errors](docs/errors.md), [Troubleshooting](docs/troubleshooting.md) and [Testing](docs/testing.md): not every intentional error is an `SDKError` (the named `Error` subclasses — `PropagatingToolError`, `CassetteMismatchError`, `CronExpressionError`, `DecryptionError` — carry no `code`); the `Find a code by area` table now lists the `Auth` section and every code that has one; `LOUSHO_CASSETTE_INVALID` no longer claims to cover request mismatches (that is `CassetteMismatchError`), and its example uses `webhookChannel()` rather than a `webhookTrigger()` that does not exist; `createAgent()`'s default retry is documented as applying only to model strings and env-resolved models, not a `provider` instance; the file-parts entry now matches providers.md (PDFs and `text/plain` do reach providers on `ai` 6/7); `connectMcp().status()` lists `'needs-auth'`; the `mockModel` `usage` default is "none reported" (the run estimates it) rather than zero; and the request-assertion snippet notes where `temperature` comes from, since `createAgent()` has no `temperature` option.
+- [Stream events](docs/stream-events.md) gains the missing `agent.drift` row (emitted on a resume under `onAgentDrift: 'warn'`, before the continuation's first step) and the fields the table understated: `executedBy: 'provider'` on `tool.start` / `tool.done` / `tool.error` (hosted tools), `replacedByHook` on `tool.done`, `hook` on `permission.decision`, `trigger: 'manual'` on `compaction.start` / `compaction.done`, and the full `usage` shape (`inputTokens` / `outputTokens`, `estimated`, `costUsd`, and `modelCalls` / `hostedToolCalls` on `run.done`). The ordering guarantees now say that a streamed approval continuation reports `agent.drift` and the decided call's `tool.start` / `tool.done` before its first `step.start`, so those events fall outside a step. [Runs](docs/runs.md) uses the canonical event names `tool.start` / `tool.done` / `run.done` instead of the deprecated `tool-call` / `tool-result` / `finish`, and [Testing](docs/testing.md) no longer claims a `mockModel` turn without `usage` reports zeros (it reports none).
+- Long-tail corrections across the guides: `lousho eval --config`, `lousho init`'s `InitUsageError` and `-y`, `.cts` among the dev-server module extensions and streamed approval continuations in docs/cli.md; `lousho build --target=...` (not `lousho deploy`) and the public `createRouteHandler().handler` (not the internal `serveFetch()`) in docs/sub-agents.md; `description` as a `createAgent()` option and `createDeployedServer()` as build-internal in docs/agent-directories.md, docs/channels.md and docs/schedules.md; approval continuations on Workers emit `tool.start` / `tool.done`, `deploy-runtime-worker` is bundler-internal and `handleScheduled` needs a store in docs/cloudflare-workers.md; `schedule-<name>` sessions, `checkpoint-history/` and the late-appearing `approvals/` directory in docs/schedules.md and docs/sessions.md; `saveAttachment`/`readAttachment` signatures in docs/utilities.md; 256-bit OAuth state in docs/oauth.md; the `recall_<name>` description's `<name>` in docs/memory.md; `ctx.sessionId` in docs/tools.md; the `throw` flow node in docs/flows.md; the `triggers` spec field in docs/configuration.md; `principal` in a permission rule's `when` in docs/approvals.md; the `'not-a-file'` rewind skip and `NodeWorkspace`'s required `root` in docs/workspace-tools.md; a built-in channel's `name` setting its route in docs/channels.md; the `completed()` 'max-steps' message in docs/evals.md; `formatUsage`'s `$0.0000` in docs/models-and-cost.md; the completed registry static-check list and the leading letter/digit name rule in docs/registry.md; `exporter`, `captureContent` and `redactContent` as `createAgent()` options in docs/migrating-to-create-agent.md; `connectMcp().tools` as a `Record` that combines with array tools in docs/mcp.md; `HookRegistry.size()` as a method in docs/hooks.md; `*.example.com` matching subdomains only in docs/tools.md, docs/workspace-tools.md and docs/registry.md; `resumeAfterApproval()` named as an export, not an executor method, and the fork `divergedAt` comment corrected in docs/durable-execution.md.
+- New page, [Permission modes](docs/permission-modes.md): the modes and their table, which tools are read-only, the `editsFiles` marker, the order of evaluation, switching, the audit log, sub-agents and resume. [Approvals](docs/approvals.md) "Permission policies" links to it; [Tools](docs/tools.md), [Stream events](docs/stream-events.md) and [Sub-agents](docs/sub-agents.md) ("What a sub-agent inherits") gained a row each.
+- New page, [Route auth and principals](docs/auth.md): the ordered list and its three outcomes, each helper, 401 / 403 / `WWW-Authenticate`, which helpers run where (Node, Workers, edge), `createRouteHandler`, the node server and `auth.ts`, reading the principal in the run, and security notes (no session ownership check; `basic()` only over HTTPS). docs/errors.md gains a `## Auth` section at the end (`LOUSHO_AUTH_CONFIG_INVALID`). One-paragraph links from deployment.md (`### Auth`), nextjs.md (`## Routes`), memory.md (`## Scopes`), agent-directories.md (layout and deploy), api-overview.md and a "Route auth" row in the cloudflare-workers.md limits table; no heading of an existing page changed.
+- New page, [Cloudflare Workers](docs/cloudflare-workers.md): a table of what the Worker target supports and what it does not comes first, then build and deploy, bindings, sessions, checkpoints and approvals in KV, scheduled runs, consistency, and bundle size and Node builtins. The Worker sections moved out of docs/deployment.md unchanged (`Bindings, sessions and the API on Workers`, `Cron triggers and handleScheduled` and `Durable execution (pause/resume) on Workers` are gone from it); deployment.md keeps a short `cloudflare-worker` summary that links to the page. Links to `deployment.md#cron-triggers-and-handlescheduled` moved to `cloudflare-workers.md#scheduled-runs`.
+- Two dead heading links fixed: docs/executor-api.md now links to `tools.md#advanced-toolregistry`, and docs/troubleshooting.md links to `mcp.md#use-mcp-servers-in-an-agent` (the configuration anchor moved with the MCP section). No other link in `docs/` or the README points to a missing heading. docs/approvals.md lists `fileStore(dir)` among the approval stores.
+- Long pages split; text moved unchanged. New pages: [Runs](docs/runs.md), [Models and cost](docs/models-and-cost.md), [Stream events](docs/stream-events.md), [Queued input and steering](docs/queue-and-steer.md). Moved anchors (old to new): `api-overview.md#finish-reasons`, `#cancellation` and `#parallel-tool-calls` to `runs.md` (same anchors); `api-overview.md#models-tokens-and-cost` to `models-and-cost.md#models-and-the-price-table`; `api-overview.md#usage-and-cost-of-a-run` to `models-and-cost.md#usage-and-cost-of-a-run`; `api-overview.md#flow-expressions` to `flows.md#flow-expressions`; `api-overview.md#todo-tools` to `tools.md#todo-tools`; `api-overview.md#tool-errors` to `tools.md#errors`; `api-overview.md#context-compaction` to `compaction.md`; `streaming.md#event-schema-version-1`, `#ordering-guarantees`, `#typescript` and `#versioning` to `stream-events.md` (same anchors); `streaming.md#queued-input` and `#steering` to `queue-and-steer.md` (same anchors); the `AgentExecutor.execute()` options table of `configuration.md` to `executor-api.md#options-of-agentexecutorexecute`. The error codes page gained a "Find a code by area" table; its headings are unchanged.
+- The API overview, providers, structured output, tools, tracing, guardrails and testing guides teach `createAgent()` first: usage and multimodal examples use it, the testing tool example uses `defineTool()`, and every executor, `AgentBuilder` or `ToolRegistry` snippet sits under an "Advanced" heading that links to [the executor API](docs/executor-api.md). They say that `createAgent()` does not take `exporter`, `captureContent` or `sandbox` yet.
+- New page, [Triggers](docs/triggers.md): the `@lousho/build-ai-agent/triggers` adapters, a table that says when to use triggers, channels or schedules, the `TriggerAdapter` interface (with a custom adapter and `TriggerRegistry`), and the webhook, Slack and cron sections that moved from the API overview, unchanged. The API overview now points to it; links to `api-overview.md#triggers`, `#webhook-authentication` and `#slack-request-signatures` moved to `triggers.md`. The missing-`auth` warning of `WebhookTriggerAdapter` and the missing-`signingSecret` warning of `SlackTriggerAdapter` now link to `docs/triggers.md`.
+- New page docs/migrating-to-create-agent.md: from `AgentBuilder`, `AgentExecutor`, `ToolRegistry` and `resumeAfterApproval()` to `createAgent()`, with a before-and-after example, a mapping table, the `ExecuteOptions` that `createAgent()` does not take yet (with alternatives), the behavior differences and a step-by-step checklist. Linked from docs/executor-api.md and the README docs table.
+- New page, [Hooks](docs/hooks.md): the four hook points, the outcomes of a `preToolCall` / `postToolCall` hook, four type-checked recipes (deny a tool, add a default argument, redact a result, inject context), ordering, and `HookRegistry`. The `HookRegistry` bullet and the `### Hook outcomes` section moved there from the API overview, which now points to it; links to `api-overview.md#hook-outcomes` moved to `hooks.md#hook-outcomes`.
+- Approvals, sessions, streaming, sub-agents, compaction and skills guides show `createAgent()` first. Executor snippets (`AgentExecutor`, `resumeAfterApproval`, `streamResumeAfterApproval`, `InputQueue`, `HookRegistry`) moved under headings named "Advanced: the executor API" (links to docs/executor-api.md); `approvals` and `streaming` renamed a section to that name. `createAgent({ hooks: [createCompactionHook(...)] })` is the compaction example. Removed a statement from the sub-agents guide that `createAgent()` takes no `approvalStore` (it does, and `agent.approvals` resolves sub-agent pauses).
+- Stale statements removed: ticket ids in the Agent Forge page, the "removed next minor" promise on `AgentType` in the API overview, and the installation note that read as if every user needs Node 22.19 for the `http` tool (it comes from the `undici@8` dependency, which is loaded only for `validateSSL: false` requests). The `ProposedAction` doc comment no longer refers to an unlanded ticket.
+- New page docs/mcp.md, "MCP (Model Context Protocol)": using MCP servers in an agent, `connectMcp()`, approval for MCP tools, `loadMcpTools()`, serving an agent with `serveMcp()` and `lousho mcp`, and a Limits list. These sections moved out of docs/configuration.md, which keeps the `mcpServers` spec field and links to the new page; links from approvals, CLI, tools, API overview and the README now point to `mcp.md`.
+- `docs/durable-execution.md` and `docs/workspace-tools.md` lead with `createAgent()` (`send()` with a `sessionId`, `agent.resume()`, `agent.approvals.resolve()`, `agent.fork()`) instead of `AgentExecutor`. The executor snippets (`execute()` with a `checkpointStore`, `resumeAfterApproval()`, `AgentExecutor.fork()`, the `ToolRegistry` setup) moved under "Advanced: the executor API". In durable-execution the heading "What happens when you call `execute()` again with the same `sessionId`" is now "What happens when you send again with the same `sessionId`".
+- New page docs/troubleshooting.md: start from the symptom (setup, runs that end without an answer, tools, providers, sandbox and MCP), with cause, fix and a link for each. README docs table, `docs/installation.md` and `docs/errors.md` link to it.
+- New guide, [Build a coding agent](docs/build-a-coding-agent.md): a terminal coding agent in six steps (workspace tools confined to the project, approval before writes and risky commands, a streamed UI that handles the approval pause, a session for follow-up questions, offline tests with `MemoryWorkspace` and `mockModel`), with an offline test of the same agent (`docs/buildACodingAgent.test.ts`; its replay of a recorded real-model run is skipped until the cassette `docs/__cassettes__/build-a-coding-agent.json` is recorded).
+- The Quick Start is rewritten around `createAgent()`: hello world, a tool, streaming, a session, an approval, an offline test with `mockModel`, a custom provider and spec files, each runnable with no API key (the first excepted). The `AgentBuilder` + `AgentExecutor` section moved to a new page, docs/executor-api.md (with the `ToolRegistry` note); the Quick Start no longer shows either API.
+- `create-lousho-agent` has a README (its npm page was empty) and `license`, `homepage` and `repository` fields; they appear on npm with its next release. `lousho init --help` no longer says `--sdk-path` is needed until the package is on npm.
+- docs/auth.md gains a section at its end, `## Principals in tools and approvals` (with `### In a tool`, `### Approval policies and permission rules`, `### Who approved`, `### Pauses, crashes and forks`, `### Sub-agents`, `### What is stored and logged`); its "Reading the principal in the run" and "Security notes" text is updated. One-sentence links, no new headings: docs/approvals.md (`needsApproval` context, `approve`), docs/tools.md (`ctx.principal` and `ctx.approval` rows), docs/permission-modes.md (the audit log) and docs/channels.md (`approvers`).
+- UI and server examples corrected: docs/ai-sdk-ui.md's client snippet used `useChat({ api: '/api/chat' })`, the `ai` 4 signature, which is invalid for the documented `ai` 6/7 combos — it now uses `useChat({ transport: new DefaultChatTransport({ api }) })` and a note says which `ai` majors are supported (`ai` 4 keeps `useChat({ api })` and returns `input` / `handleInputChange` / `handleSubmit`; `ai` 5 is not in the peer range). docs/nextjs.md's `useChat` snippet has the same version note. The route handlers of ai-sdk-ui.md and nextjs.md opened `agent.session({ id })` per request with no `store`, so a second turn forgot the first: both now pass `store: memoryStore()` and say to use a durable store on serverless; docs/react.md's server section says the same for a per-request session. The `data-lousho-approval` part no longer reads as if `kind` / `question` only mark an `ask_question`: a tool waiting on an OAuth sign-in carries `kind: 'sign-in'` and `signIn: { provider, displayName?, url }`; docs/react.md's `pendingApproval` row says the same.
+
+## [1.0.0-alpha.8] - 2026-10-02
+
+### Changed
+- No `any` left in the SDK's types (LOU-D16): `npm run lint` now fails on any ESLint warning, and `no-explicit-any`, `no-unused-vars` and `ban-ts-comment` are errors. Runtime behavior is unchanged; some exported types are stricter, which can be a compile error where code read an `any` value without checking it. What changed, and how to migrate:
+  - Values the SDK cannot know are `unknown` (narrow them, or cast to the shape you expect): `FlowExecutionResult.output` and `.variables`, `FlowExecutionContext.variables` / `session` / `memory`, `GenerateResult.rawResponse`, `StreamChunk.toolResult.result`, extra keys of `LLMProviderConfig`, `AgentConfig.expectedResult` / `events` / `metadata`, `AgentExecutionResult.result`, `ResultData.result`, `SessionData.data`, `JiraTicket.customFields`, the extra keys of `formatZodError()`'s result, `ToolConfiguration.options`, `ToolSetting.options`, `FlowToolSetting.options`, `ToolNode.toolOptions`, `UIComponentNode.componentProps`, `FlowChunkEvent.issues` / `input` / `toolResults[].args` / `componentProps`, and `ToolDefinition.function.parameters`.
+  - `FlowExecutionEvent` is a union discriminated on `type`, with `data` typed per event type (new `FlowExecutionEventOf<T>` and `FlowExecutionEventDataMap`): check `event.type` before reading `event.data` (`if (event.type === 'tool-call') event.data?.tool`).
+  - `AgentConfig.settings` (and `AgentBuilder.setSettings()`) is the new `AgentSettings` (`{ model?: string; [key: string]: unknown }`).
+  - `StorageService.readPlainJSONAttachment<T>()` (and `IStorageService`'s) defaults `T` to `unknown`: pass the type you stored, `readPlainJSONAttachment<MyRecord>(key)`.
+  - `OpenRouterProvider.getModelInfo()` returns the new `OpenRouterModel` (`{ id: string; [key: string]: unknown }`), `null` or `undefined`.
+  - `FlowBuilder.addAgent()` / `setAgents()` take `FlowAgentDefinition`; `injectVariables()` and `applyInputTransformation()` take a `FlowDefinitionNode` (`injectVariables()` returns the type it was given); `validateFlowInput()` takes `Record<string, unknown>`; `validateAgentTools()` takes `Record<string, { tool?: unknown }>`; `createDynamicZodSchemaForInputs()` returns `z.ZodObject<Record<string, z.ZodTypeAny>>`.
+  - Still accepted as before: `needsApproval` predicates typed for a tool's own arguments, any argument to `formatAxiosError()` and `hasRequiredKeys()`, and anything as `writePlainJSONAttachment()` data. The deprecated `ExecutionEvent` keeps `toolResult.result: any`.
+- Eval cassettes hook in at the model boundary (LOU-D46.2): `lousho eval --record / --replay / --drift` no longer reassigns `AgentExecutor.execute` at runtime. The run loop routes every model call through a small provider-interception seam (`setProviderInterceptor()` / `interceptProvider()` in `src/providers/interception.ts`; a no-op unless an interceptor is installed), and the eval runner installs one that answers with the per-case `recordReplay()` wrapper. Cassette files, keying, `--drift` output and JUnit reports are unchanged, so existing cassettes keep replaying. Streamed runs and sub-agents inside an eval case are covered by tests.
+- More errors carry SDK error codes (LOU-D2.2): the plain `Error`s thrown by `src/execution` (`historyLimit`, `toolConcurrency`, a second iteration of an `AgentRun`), the tool registry, the built-in tools, `serveMcp()`, `NodeWorkspace` and the `lousho init` / `studio` / chat helpers are now `SDKError`s with an existing code (`LOUSHO_CONFIG_INVALID` via `ConfigurationError`, `LOUSHO_RUN_ALREADY_ITERATED`, `LOUSHO_APPROVAL_NOT_FOUND`, `LOUSHO_PROVIDER_UNKNOWN`, `LOUSHO_TOOL_EXECUTION_FAILED`). Messages are unchanged; `error.code`, `error.hint` and a `[code] hint (docs)` line (not on the built-in tools' run-time failures, whose message is the model-visible tool result) are added. Code that matched `error.constructor === Error` or `error.name === 'Error'` needs `error instanceof SDKError`.
+- The remaining user-reachable plain `Error`s carry SDK error codes (LOU-D2.3): agent directories, flows, memory, skills, storage (SQLite), triggers, deploy, evals, record/replay cassettes, `defineTool()`, sub-agent options, channels, sandbox/credential-broker options and the `llm` registry now throw an `SDKError` (message text unchanged, plus the `[code] hint (docs)` line, except for tool results and messages tests assert, which stay as written). New codes: `LOUSHO_TOOL_ARGS_INVALID` (what `ToolArgumentsValidationError` carries now), `LOUSHO_AGENT_DIR_INVALID`, `LOUSHO_SKILL_INVALID`, `LOUSHO_FLOW_INVALID`, `LOUSHO_STORAGE_FAILED`, `LOUSHO_TRIGGER_INVALID`, `LOUSHO_DEPLOY_FAILED`, `LOUSHO_EVALS_INVALID`, `LOUSHO_TEST_FAILED`, `LOUSHO_CASSETTE_INVALID` and `LOUSHO_CHANNEL_REQUEST_FAILED`, all in `docs/errors.md`. Code that matched these errors by `error.constructor === Error` or `error.name === 'Error'` must check `instanceof SDKError` / `error.code` instead. `ToolExecutionError` takes an optional fourth `code` argument. A new test (`src/utils/plainErrors.test.ts`) fails when new SDK code throws a plain `Error`; the 5 that remain are listed there with the reason.
+- The last two allowlisted plain `Error`s are `SDKError`s (LOU-D16): OpenRouter's model-catalog fetch (`LOUSHO_PROVIDER_REQUEST_FAILED`; `getModels()` / `getModelInfo()` still catch it and fall back) and the UI runner's failed `POST` to a remote agent (`LOUSHO_REMOTE_REQUEST_FAILED`, as used by `useLoushoAgent()` and the Vue/Svelte bindings). Both keep their message text exactly (no help line appended), so the UI's error event shows the same message, now with `name: 'SDKError'` instead of `'Error'`. `SDKError` itself moved to `src/utils/sdkError.ts` (re-exported from the same places as before) so the browser entries can throw it without importing `ai`. The allowlist in `src/utils/plainErrors.test.ts` is down to the 3 intended sites.
+- zod 3 or zod 4 (LOU-D29): the `zod` peer is now `^3.25.76 || ^4.0.0`. Schemas of either major (including `zod/v4` on zod 3.25 and `zod/v3` on zod 4) work in `defineTool({ input })`, structured `output` and argument validation: zod 4 schemas are sent to the model as `z.toJSONSchema` output (also to `ai` v4, whose own converter only reads zod 3), zod 3 schemas through the `ai` SDK's converter as before, and both are parsed with their own `safeParse`. `defineTool` also takes any Standard Schema that exposes `~standard.jsonSchema`; tool arguments validate with any Standard Schema's `~standard.validate`. The SDK's own schemas (AgentSpec, registry documents, built-in tools, MCP tool conversion) run on whichever major is installed, and issue messages read the same on both (zod 4's `Invalid input: expected string, received undefined` is reported as `Required`). `lousho init` keeps zod 3 for the `ai` 4 scaffold (Ollama), whose packages peer on zod 3. Ollama on `ai` 6/7 (`ollama-ai-provider-v2`, which peers on zod 4) is no longer blocked by the SDK's zod peer. CI runs the type check, build and suite on zod 4 too. Migration: `DefineToolOptions`, `DefinedTool` and `ToolDescriptor.inputSchema` are typed with the new exported `StandardSchemaV1` (parsed type: `InferSchemaOutput`) instead of zod 3's `ZodTypeAny`; code that called zod methods on `descriptor.inputSchema` needs a cast. The `task` tool's error for an unknown sub-agent now reads `Unknown sub-agent "x". Expected one of: 'a', 'b'`. `createAgent({ output })` is still typed with the installed major's `ZodType`.
+- Slack and Discord approvals are starter-only by default (LOU-P5.2, behaviour change): without `approvers`, only the user who started the turn (the Slack message author, the Discord command's user) can approve or deny a tool call; before, anyone who could see the message could. Migration: pass `approvers: () => true` for the old behaviour, or a list of user ids / a function for a team. Approval button values (Slack) and custom ids (Discord) now carry the starter (`<starter>:<approval id>`), so buttons posted before the upgrade carry no starter and only an `approvers` list or function can approve them.
+- Package entries share one copy of each module (LOU-D42): tsup code splitting is on, so `@lousho/build-ai-agent`, `/hooks`, `/tools`, `/mcp` and the rest import shared chunks instead of each bundling their own copy. `HookRegistry`, `SDKError` and module-level registries are now the same object across entries (they were duplicated, so `instanceof` and singletons could disagree), and `dist/` shrinks from about 25 MB to 8.8 MB. `instanceof SDKError` and `instanceof HookRegistry` also hold between the ESM and CJS copies a mixed-format process loads (a `Symbol.for` brand). See [Installation](docs/installation.md#entry-points-share-code-esm-and-cjs).
+- A crash resume of a dynamic agent restores the run's config (LOU-V15.2): checkpoints now carry `runConfig` (the `ctx` and model the run was resolved with, as approval snapshots already did), and `agent.resume(id)` / `session.resume()` / `send(…, { sessionId })` on an unfinished run use the saved model and re-resolve `tools` and `instructions` with the saved `ctx`, instead of `input: []` and no `metadata`; a model chosen from `metadata` no longer changes mid-run. Static agents are unchanged.
+- Resumed approved calls must run with the approved arguments (LOU-X3.2, behaviour change): after the pre-tool hooks ran on the resumed call, the arguments are compared (deep, key order ignored) with the approved ones whether a hook returned `{ input }` or changed `ctx.args` in place, and a difference is refused with the existing `kind: 'validation'` error ("approved with different input"); a hook that rebuilds the same arguments in another key order is no longer refused. **Migration:** a hook that rewrites arguments (a redactor, a normalizer) must also run on the original run, so the approval record already holds the rewritten input; a hook added only after the pause, that changes the arguments, now refuses the call. A call whose tool no longer exists after an approval (snapshots with an agent fingerprint) now rejects with `LOUSHO_RESUME_TOOL_MISSING` instead of giving the model a `not-found` tool result; older snapshots keep the old behaviour.
+- Cancelled and settled tool calls use the shared tool-error shape (LOU-U14.2): a tool call cancelled before it ran (the run was aborted or steered) and a sub-agent call dropped because the lead run was already pausing for another approval now reach the model as `{ error: 'ToolNotRunError', toolName, message, kind: 'not-run' }` with the transcript message flagged `isError`. Before, the result was `{ error: '<text>' }` (and the cancelled one was not flagged `isError`); the text is now under `message`.
+- A `permissions` `allow` (or `ask`) rule no longer overrides a tool's own `needsApproval` deny (LOU-X8 follow-up, behaviour change): the tool's `needsApproval` is now called for those calls too, and its `'deny'` / `{ deny }` denies the call; an `allow` still skips the tool's ask. A `deny` rule still wins without calling `needsApproval`. Migration: a tool that should run under an `allow` rule must not deny it from `needsApproval`. See docs/approvals.md.
+- `agent.session()` passes the agent's `createAgent({ compaction })` to the session (LOU-W8 follow-up), so `session.compact()` uses the agent's strategy and sizes unless `agent.session({ compaction })` sets its own.
+- The `cloudflare-worker` target builds with `ai` v7 installed (LOU-D28c). With `ai` v7 (`@ai-sdk/openai`/`@ai-sdk/anthropic` v4), `lousho build --target=cloudflare-worker` failed with "Node builtins leaked" (`node:module`, `node:dns`, `node:diagnostics_channel`, `node:async_hooks`). Those are not imports: `ai` v7 and `@ai-sdk/provider-utils` v5 probe them at run time through `process.getBuiltinModule()`, only when running on Node, so the bundle never loads them on Workers. The build's leak check now exempts exactly those four ids, and only as the argument of a `getBuiltinModule`/`loadBuiltinModule` call; any other `node:` reference still fails the build. No `nodejs_compat` flag is needed. The 16 Worker bundle tests that LOU-D28b skipped on `ai` v7 now run on both majors. The bundle is about 3.4 MB raw on v7 (1.7 MB on v4), well under the 64 MiB limit.
+- BREAKING: sandboxed and workspace commands get an allowlisted environment (LOU-X11). Commands run by `NodeWorkspace.exec()` and `SandboxShell` no longer see the host's `process.env`, so `env`/`printenv` cannot reveal API keys or cloud credentials. They get a small base a shell needs (`PATH`, `HOME`/`USERPROFILE`, `TMP`/`TEMP`/`TMPDIR`, `LANG`, `LC_*`, `TERM`, plus `SystemRoot`, `SystemDrive`, `ComSpec`, `PATHEXT`, `WINDIR` on Windows) and what you add. A container (`SubprocessSandbox`) gets only what you add, never the host env. `SandboxShell` gains `env` and `inheritEnv` options; `NodeWorkspaceOptions.inheritEnv` and `SandboxShellOptions.inheritEnv` accept `true`; `SandboxRunOptions` gains `inheritEnv` (`NoopSandbox` keeps passing the host env unless it is `false`, which `SandboxShell` sets). `SubprocessSandbox` gains `network: 'none' | 'default' | { allow: string[] }` (default `'none'`, as before); `{ allow }` is validated and kept on `sandbox.network` but runs with no network until the egress proxy of LOU-X12 enforces it (fail closed). **Migration:** pass what commands need, either values (`env: { NODE_ENV: 'test' }`) or host names to copy (`inheritEnv: ['CI', 'NODE_OPTIONS']`); to restore the old behavior, pass `inheritEnv: true`. See docs/workspace-tools.md.
+- Internal (LOU-D28b): the test suite runs with `ai` v7 installed as `ai`. A test helper (`src/providers/aiMajor.testkit.ts`: `installedAiMajor`, `describeOnAiV4`, `itOnAiV4`) reads the installed major; tests whose behavior is the same on both majors are made major-agnostic, the 66 that only make sense on v4 (v4 message and call shapes, `MockLanguageModelV1`) or on a Worker bundle that still leaks `node:` built-ins on v7 (LOU-D28c) are skipped there. The `typecheck-ai7` CI job now also builds and runs `npx vitest run`. Test and CI change only; no product change.
+- Internal (LOU-D28a): the SDK source now type-checks against `ai` v7 (with `@ai-sdk/openai`/`@ai-sdk/anthropic` v4) as well as `ai` v4. `AiSdkProvider` builds its `ai` v4 request with SDK-owned structural types instead of the v4-only `CoreMessage`/`CoreAssistantMessage`/`CoreToolMessage`/`Output` types and no longer calls `ai`'s `tool()` (an identity function on v4); the legacy `.tool` that `defineTool()`/`toolDescriptorFromSchema()` hand-build is cast once at that boundary. No runtime change on v4. A new CI job runs `tsc --noEmit` with `ai@7` installed. The `ai`/`@ai-sdk/*` peer ranges are unchanged for now (LOU-D28d).
+- MCP tools without `readOnlyHint` now ask for approval by default (LOU-Z5, BREAKING for MCP users): `loadMcpTools()`, `connectMcp()` and `createAgent({ mcpServers })` set `needsApproval` from each tool's MCP annotations: `readOnlyHint: true` runs, `destructiveHint` true or absent (the MCP spec default) asks, `destructiveHint: false` runs. Choose per server with the new `approval: 'annotations' | 'always' | 'never' | ({ name, annotations }) => boolean` (`loadMcpTools(client, name, { approval })`, `connectMcp()` server entries, `createAgent({ mcpServers })` and `AgentSpec.mcpServers`, which validates it; a spec file takes the three strings). The descriptor keeps the raw annotations on the new `ToolDescriptor.metadata?.mcp.annotations` (types `McpToolAnnotations`, `ToolMetadata`, `McpApproval`) and uses the annotation `title` as `displayName`. Migration: pass `approval: 'never'` to restore the old behaviour (every MCP tool runs without asking). `createAgent()` agents pause with `finishReason: 'awaiting-approval'`, while a bare `AgentExecutor` without an `approvalStore` now throws for such tools. See docs/configuration.md#mcp-tool-approval-approval.
+- Small built-in tools are defined with `defineTool` (LOU-D24, not breaking): `currentDateTool`, `dayNameTool`, `createEmailTool()`, `createHttpTool()`, `createSlackTool()`, `createDelegateTool()` and the descriptors `loadMcpTools()` builds no longer call `ai`'s `tool()`. They now carry canonical `inputSchema` / `execute` (the legacy `.tool` stays), and the built-ins have the tool names `current_date`, `day_name`, `send_email`, `http_request`, `slack_alert` and `delegate_to_<agent>`. Descriptions, schemas, approval and sandbox behaviour and the factory signatures are unchanged. MCP descriptors are built with the new internal `toolDescriptorFromSchema()`, which (unlike `defineTool`) accepts any server-provided name or empty description. `routeFetchThroughSandbox()` reads the canonical `execute` first.
+- GitHub and Jira tools are defined with `defineTool` (LOU-D25, not breaking): the 28 `createGitHubTools()` tools and the 20 `createJiraTools()` tools no longer call `ai`'s `tool()`, so nothing under `src/tools` imports `ai` any more. They now carry canonical `inputSchema` / `execute` (the legacy `.tool` stays). Tool names, descriptions, schemas, the sandbox flags and the factory signatures are unchanged. The GitHub out-of-scope tools (branch/file writes, code search, issue CRUD, merge) are disabled through the canonical `execute` as well as `tool.execute`, so calling one still throws "out of scope" before any HTTP request. `JiraTools.register()` now also routes tools registered with `defineTool` through the sandbox seam.
+- BREAKING (types only): `Message.content` is widened from `string` to `string | ContentPart[]` (LOU-V11). Messages you build keep working unchanged, but code that reads `message.content` as a string (`.length`, `.startsWith()`, a template literal) no longer type-checks. **Migration:** read `textOf(message)` instead, or narrow with `typeof message.content === 'string'`. A custom `LLMProvider` that forwards `content` should handle the parts or send `textOf(message)`.
+- The execute context is our own type (LOU-D23, not breaking): the new exported `ToolExecutionContext` (`{ toolCallId, messages: readonly Message[], abortSignal?, sessionId?, onDelegatedUsage? }`, `Message` from `@lousho/build-ai-agent`) replaces the `ai` SDK's `ToolExecutionOptions` as the type of the second argument of `defineTool()`'s `execute`, `ToolDescriptor.execute`, `DefinedTool.execute` and the third argument of `sandboxExecute`, and is what `buildToolRunContext()` returns; the public types no longer import `ToolExecutionOptions` from `ai`. A function typed for `ai`'s options that only reads `toolCallId` or `abortSignal` stays assignable. `ToolRunContext` is now a deprecated alias of the optional fields of `ToolExecutionContext` (it already existed with `onDelegatedUsage` and `toolCallId`). `AgentExecutionOptions.messages` is typed `Message[]` instead of the `ai` SDK's `CoreMessage[]` (the field is unused by the SDK). The legacy `ToolDescriptor.tool` (`ai` v4 `Tool`) is unchanged. See docs/tools.md#execute-context.
+- BREAKING (small): `SDKError.code` values are now the `LOUSHO_*` codes (LOU-D2): `AGENT_EXECUTION_ERROR` -> `LOUSHO_AGENT_EXECUTION_FAILED`, `TOOL_EXECUTION_ERROR` -> `LOUSHO_TOOL_EXECUTION_FAILED`, `LLM_PROVIDER_ERROR` -> `LOUSHO_PROVIDER_REQUEST_FAILED`, `SESSION_AWAITING_APPROVAL` -> `LOUSHO_SESSION_AWAITING_APPROVAL`, `FLOW_EXECUTION_ERROR` -> `LOUSHO_FLOW_EXECUTION_FAILED`, `CONFIGURATION_ERROR` -> `LOUSHO_CONFIG_INVALID`, `VALIDATION_ERROR` -> `LOUSHO_VALIDATION_FAILED`, `TIMEOUT_ERROR` -> `LOUSHO_OPERATION_TIMEOUT`, `RATE_LIMIT_ERROR` -> `LOUSHO_PROVIDER_RATE_LIMITED`; `code` is no longer optional (`new SDKError(message)` gets `LOUSHO_GENERIC_ERROR`). No class was renamed. The messages of `SDKError`s other than `ToolExecutionError`, `LLMProviderError`, `TimeoutError` and `RateLimitError` gain a second line with the code, hint and docs link, and `loadSpec()` now rejects a spec whose top-level field is a likely typo of a spec field (`LOUSHO_SPEC_UNKNOWN_FIELD`; other unknown fields are still ignored). **Migration:** compare `code` against the new values (or use `instanceof`); match messages with `toContain` / a regex, or compare `error.detail`, instead of exact equality.
+- BREAKING (small): tool failures that did not go through the thrown-error path now use the shared shape (LOU-U14), so `error` is an error name instead of a message. Before: an unknown tool or a missing registry gave `{ error: "Tool 'x' not found" }` / `{ error: 'No tool registry available' }`; a rejected approval gave `{ error: 'Tool execution was rejected by the reviewer', note }`; a tool that threw after an approval gave `{ error: '<message>' }`; a call left without a result on resume gave `{ error: 'Tool call was not run: ...' }`. Now each is `{ error: '<ToolNotFoundError | ToolRejectedError | <thrown error name> | ToolNotRunError>', toolName, message: '<the old text>', kind, ... }`. A tool approved but missing from the registry on resume used to reject `resumeAfterApproval()` with `Tool 'x' not found in registry`; it now resolves with a `not-found` error result. The sandbox guard throws `SandboxRequiredError` (same message, still an `Error`). **Migration:** read `message` instead of `error` when you want the text, and branch on `kind`. `ToolArgumentsValidationError.toToolResult()` now also returns `kind: 'validation'`.
+- Background sub-agents still running when the lead run ends are now cancelled (LOU-Y4.2) instead of running to completion on their own; a lead run that pauses for approval cancels them too (the resumed run starts with none). **Migration:** to keep them, have the lead collect them with `agent_await` before its final answer, or set `subagentOptions: { awaitBackgroundOnFinish: true }`.
+- Heavy dependencies are optional peers (LOU-D40): `dockerode` (Docker sandboxing, `SubprocessSandbox`), `@modelcontextprotocol/sdk` (`serveMcp`, `lousho mcp`, MCP clients) and `prompts` (the interactive questions of `lousho init`) moved from `dependencies` to `peerDependencies`, marked optional in `peerDependenciesMeta`. They were already loaded lazily; now a project that uses none of them does not install them. Using one without its package fails that call with `MissingPeerDependencyError`, which now also carries `feature` and names the exact command (for example `npm install dockerode@^5.0.1`). `lousho doctor` lists the three with what they enable (a missing `dockerode` fails the check when the agent spec uses a sandboxed tool), and its version lookup no longer returns `undefined` for packages whose `exports` map hides `package.json`. **Migration:** install the peer if you use Docker sandboxing (`npm install dockerode`), MCP (`npm install @modelcontextprotocol/sdk`), or interactive `lousho init` (`npm install prompts`; `npm create lousho-agent` already does, and `lousho init --yes` needs nothing). See docs/installation.md.
+- The `http` tool no longer loads `undici` for default requests (LOU-D40): with TLS verification on (the default) it uses the runtime's global `fetch`; `undici` (still a regular dependency) is loaded only for `validateSSL: false`, whose per-request TLS dispatcher the global `fetch` cannot express. `yaml` stays a dependency (agent specs and skills need a YAML parser).
+- Retries no longer stack (LOU-V7.2): the built-in providers (`OpenAIProvider`, `AnthropicProvider`, `OllamaProvider`, `OpenRouterProvider`) now pass `maxRetries` to the `ai` SDK calls: `config.maxRetries`, or 2 (the `ai` SDK's default, so behaviour is unchanged) when unset. `createAgent()` builds the providers it resolves from strings with `maxRetries: 0` and retries in its `withRetry()` wrapper instead, so retries happen in one place (at most 3 calls by default, as before) and each one is observable. If you wrap a built-in provider in `withRetry()` / `resilientProvider()` yourself, build it with `maxRetries: 0`; note that a `maxRetries` you already set in a provider config is now honoured by the `ai` SDK.
+- `AgentType` is optional and deprecated (LOU-D34, not breaking): `AgentBuilder.build()` no longer requires `setType()` and `AgentConfig.agentType` is now optional (`createAgent()` and `specToAgent()` agents carry no type). `AgentType`, `setType()` and the `agent-types` registry/validators are marked `@deprecated`: they have no runtime effect and will be removed in the next minor; they stay exported for now. Drop your `setType(...)` calls.
+- BREAKING: `encrypt()` now generates a random salt per call instead of a hardcoded one. Ciphertext produced before this change cannot be decrypted with the new code and must be re-encrypted.
+- BREAKING: The mock repositories (`MockAgentRepository`, `MockSessionRepository`, `MockResultRepository`, `MockMemoryRepository`, `MockAttachmentRepository` — previously re-exported from `src/data/mocks.ts` via the package root/`./data` subpath; this package has no `createMockRepositories` factory) are no longer exported from the package root. Import them from `@lousho/build-ai-agent/testing` instead.
+- One session-API client behind `remoteAgent()` and `remoteTarget()` (LOU-D53): both now share an internal client (`src/server/sessionClient.ts`) for `POST <url>/chat`, the SSE read, bearer-token scrubbing and the error mapping, and use one pair of codes, `LOUSHO_REMOTE_REQUEST_FAILED` and `LOUSHO_REMOTE_UNAUTHORIZED`. The unreleased `LOUSHO_REMOTE_AGENT_FAILED` (LOU-Y7) is removed: a `remoteAgent()` failure now carries `LOUSHO_REMOTE_REQUEST_FAILED` (network, non-2xx, truncated stream, or a remote run that ends in an error, with "the remote run ended in an error" in the message) or `LOUSHO_REMOTE_UNAUTHORIZED` (401). No option or behavior of either function changed.
+
+### Added
+- Remote sub-agent approvals go through the lead run (LOU-Y7.3): a `remoteAgent()` task whose remote run pauses for a tool approval now pauses the lead run the way a local sub-agent does (it used to fail with `LOUSHO_SESSION_AWAITING_APPROVAL`): the lead's pending approval (`agent.approvals.list()`, channel buttons, the dev chat, ACP permission requests) has the remote tool's name and input and `subagentPath: [<remote agent>]`, and a remote `ask_question` arrives as a question. Deciding it on the lead (`resolve`, `streamResolve`, `answer`) posts the decision to the remote `POST <url>/chat/:sessionId/approvals/:id` and the continuation's final answer is the `task` result; a further pause pauses the lead again. The lead's approval snapshot stores the remote session id, the remote approval id, the `taskId` and the agent name (never the token), so a fresh lead process on the same store can decide it. Failures while deciding (401, other non-2xx including the remote's 404 for an approval no longer pending, network) are the `task` call's structured tool error with `LOUSHO_REMOTE_UNAUTHORIZED` / `LOUSHO_REMOTE_REQUEST_FAILED`. A remote agent with an `output` schema now returns its object as JSON with the footer (the V4.2 shape), read from `run.done`'s `object`. `RemoteSubagent.run()` takes `pausable` and `decision` (type `RemoteRunOptions`); the internal session client gains `resolveRemoteApproval()` and `SessionTurnSummary.object`. Only a lead run without an approval store keeps the old `LOUSHO_SESSION_AWAITING_APPROVAL` error. See docs/sub-agents.md#remote-approvals.
+- Structured output for sessions and sub-agents, typed for either zod major (LOU-V4.2): `createAgent({ output })` and `ExecuteOptions.output` accept a zod 3 schema, a zod 4 schema (`zod/v4` on zod 3.25, or zod 4) or a Standard Schema that can produce JSON Schema, and `result.object` is inferred from each without a cast (`InferSchemaOutput`, as `defineTool`). `AgentSession` is generic (`AgentSession<TObject = unknown>`): `agent.session().send()` and `.stream()` results carry the typed `object`. A sub-agent with its own `output` returns its validated object as JSON (then the `taskId` footer) as the `task` and `agent_await` result; its `output-invalid` finish is a structured tool error. Sub-agents do not inherit the lead's `output`; `remoteAgent()` returns text only. The exported spec schemas (`agentSpecSchema`, ...) are typed as `SpecSchema<T>` / `SpecObjectSchema<T>`, so the published `schema-*.d.ts` no longer depends on zod 3 generics (`skipLibCheck: false` projects on zod 4). The Ollama missing-peer note now says `ollama-ai-provider-v2` needs zod 4 (`npm install zod@^4.0.0`). See docs/structured-output.md.
+- Publish readiness (LOU-D49): `npm run pack-smoke` (scripts/pack-smoke.ts, a CI job) packs the SDK and `create-lousho-agent`, checks the tarball (no `.env`, tests or secret-looking strings; entry count and size caps), runs `npm publish --dry-run` for both (nothing is published), installs the tarballs plus peers from the registry into a fresh project and verifies ESM and CJS loads of every `exports` entry, a mock-model agent turn, the `@linuxdevil/lousho` bin (`--help`, `doctor`) and `tsc` with `moduleResolution` bundler and node16.
+- One event system (LOU-D41): `AgentEvent` listeners for callers who do not iterate a run. `createAgent({ onEvent: (event: AgentEvent) => void })` and the new `ExecuteOptions.onAgentEvent` (also taken by `AgentExecutor.stream()` and `resumeAfterApproval()`) are called synchronously with every `AgentEvent` of the run, on `send()` / `execute()` as on `stream()`, sub-agents' events included: the same events in the same order as the stream yields (a non-streamed run generates each model step whole, so its text is one `text.delta` per step). A run with a listener also reports hook events, permission decisions, budgets and guardrails to it when it is not streamed. A non-streamed `resumeAfterApproval()` with a listener now reports the decided call (`run.start`, `tool.start`, `tool.done`) like a streamed one. See docs/streaming.md#listening-without-iterating.
+- Reasoning (LOU-V13): new `reasoning` option on `createAgent()`, `send()` / `stream()` (per call, overriding the agent's), `ExecuteOptions` and `GenerateOptions`: `'none' | 'minimal' | 'low' | 'medium' | 'high'` or `{ effort?, budgetTokens?, summary?: 'auto' | 'none', force? }` (types `ReasoningOption`, `ReasoningEffort`, `ReasoningSettings`). The built-in providers send it through `providerOptions` on `ai` 4.3 and 6/7: OpenAI `reasoningEffort` (+ `reasoningSummary`), Anthropic `thinking: { type: 'enabled', budgetTokens }` (effort table 1024 / 2048 / 8192 / 24576 tokens), Ollama `think` (`ollama-ai-provider-v2` only; ignored with one warning on `ai` 4), and OpenRouter's unified `reasoning` body field (`effort` or `max_tokens`). It is only sent to model families known to accept it (`force: true` overrides); `'none'` sends nothing. New events `reasoning.start`, `reasoning.delta` (`text`) and `reasoning.done` (`text`, `tokens?`) in the `AgentEvent` union, emitted inside the step before its first text or tool call, from `ai` v4 `reasoning` parts and v6/v7 `reasoning-start/delta/end`; `ExecutionResult.reasoning` holds the run's reasoning text and `GenerateResult.reasoning` a call's blocks (new type `ReasoningBlock`); new stream chunk types `reasoning-delta` / `reasoning-end` (`StreamChunk.reasoning`). Reasoning is not written to the transcript as text; an assistant tool-call turn keeps Anthropic's signed or redacted thinking blocks in the new `Message.reasoning`, which the Anthropic provider sends back unmodified (it survives checkpoints and resumes). The UI reducer keeps `UIMessage.reasoning`, `toUIMessageStream()` emits `reasoning-start` / `reasoning-delta` / `reasoning-end`, `lousho acp` sends `agent_thought_chunk`, `lousho chat` prints reasoning dimmed, and `chat` spans carry `lousho.usage.reasoning_tokens`. Cassettes record the reasoning chunks. See docs/reasoning.md.
+- Tools know their session (LOU-D23.2): `ToolExecutionContext.sessionId` is now set whenever the run has one: `AgentExecutor.execute({ sessionId })`, `send({ sessionId })`, every `agent.session()` turn (the session id; a checkpointed turn's own `<id>.turn-<n>`, as hooks see it), approval resumes (the paused run's), and sub-agents (`<parent session>/<task tool call id>`). A session turn's run now carries the session id even without a checkpoint store (no checkpoint is written), so hooks and the `invoke_agent` span's conversation id see it too.
+- Hardened Slack and Discord channels (LOU-P5.2): `approvers` (a list of platform user ids, or `(user: { id, name?, roles? }, { toolName, input, sessionId }) => boolean | Promise<boolean>`) says who may click Approve / Deny (a refused click gets an ephemeral "not allowed" and the approval stays pending); `onError(error, { channel, stage, sessionId? })` on both channels, on `mountChannels()` and on `defineChannel()` receives failures after the acknowledgment (reply delivery, a failed turn, an approval continuation; default `console.error` with channel, stage, session and SDK error code, never a token) and a failed turn tells the user so; `mountChannels({ onDecision })` reports who decided; `parse` gets a third `ctx` argument (`ChannelContext`: pending approval, session id, `hasSession`) and a `{ decision }` may carry `inbound` and `approver`. Pending approvals now resolve from the click itself and the Slack 'active thread' check asks the session store, so both survive a restart. Slack: the clicked message is replaced with the outcome (buttons removed) and direct messages (`message.im`, scope `im:history`) are sessions keyed on the DM channel. See docs/channels.md.
+- Resumable sub-agent tasks (LOU-Y6): every `task` result ends with a `taskId` (the footer is now `[sub-agent '<name>': N step(s), finish reason '<reason>', taskId 'task_1']`; a remote one gains `, taskId '...'` too), and `task` takes optional `taskId` and `mode: 'new' | 'resume' | 'fork'` (default `new` without a `taskId`, `resume` with one). `resume` continues that sub-agent with its transcript and the new prompt as the next user turn; `fork` starts a new task (new `taskId`) from a copy of it and leaves the original alone. Conversations are kept per lead session in the agent's `store.sessions` (new `SubagentOptions.sessions`, set by `createAgent({ store })`) for lead runs with a `sessionId` (checkpointed `send()` and session turns), under a key hashed from the lead session and the taskId, so they survive a restart and cannot be reached from another session; other runs keep them in memory for the run. Background tasks share the ids (a background task's id is now `task_<n>` counted with the synchronous ones): a finished one can be resumed, a running one is refused with the new `LOUSHO_SUBAGENT_TASK_BUSY`; an unknown, foreign or other sub-agent's id gets the new `LOUSHO_SUBAGENT_TASK_NOT_FOUND`, both as the structured tool error. An approval inside a resumed child pauses and resumes the lead as before (streamed or not), and a resumed child's usage counts toward the lead like a fresh call. `remoteAgent()` tasks resumed by `taskId` continue in the same remote session (LOU-Y7.2; `RemoteSubagent.run()` takes `sessionId` and `taskId`); remote approvals are still not proxied, but a task whose remote run paused can be continued once the approval was decided on the remote agent. The model-facing `task` description and the sub-agents prompt block say how to continue a task. See docs/sub-agents.md#continuing-a-task.
+- Agent-directory and spec builds keep optional peers external, and the node server runs spec cron triggers (LOU-P8.3): `lousho build --target=node-server|docker` leaves every optional peer of the SDK (read from its `peerDependenciesMeta`) out of the bundle, replacing the hand-kept `dockerode` / `ollama-ai-provider-v2` list, so a build no longer needs peers the agent does not use; a spec's `{ type: 'cron' }` triggers now start on the built server (and are validated at build time), as on the Cloudflare Worker target. See [Deployment](docs/deployment.md#optional-peers-in-node-and-docker-builds).
+- Agent fingerprint on resume (LOU-W9.2): every checkpoint and approval snapshot now carries `agentFingerprint` (new type `AgentFingerprint`: the model id, each tool's name with a hash of its JSON input schema, a hash of the instructions, and a SHA-256 prefix over them, via Web Crypto; functions are ignored), and a resume compares it with the resuming agent's before any model call or tool runs. New option `onAgentDrift: 'warn' | 'error' | 'ignore'` (type `AgentDriftMode`) on `createAgent()`, `AgentExecutor.execute()` and `resumeAfterApproval()`: `'warn'` (default) emits the new `agent.drift` event (`AgentDriftEvent`: `model?`, `toolsAdded`, `toolsRemoved`, `toolsChanged`, `instructions`) and a `console.warn`, `'error'` rejects with the new `LOUSHO_AGENT_DRIFT` and leaves the checkpoint (or the pending approval) untouched. A pending tool call whose tool no longer exists always rejects with the new `LOUSHO_RESUME_TOOL_MISSING`. Works for crash resume, `session.resume()` and approval resume, streamed or not; old checkpoints and snapshots have no fingerprint and resume unchecked. A sub-agent's nested approval snapshot carries its own fingerprint, but only the top-level agent is compared. `resumeAfterApproval()`'s options take `currentAgent` (set by `createAgent()`) so instructions can be compared. See docs/durable-execution.md#resuming-with-a-changed-agent.
+- Docker sandbox network allowlists are enforced through the credential broker (LOU-X12.2): `new SubprocessSandbox({ network: { allow }, broker })` creates (or reuses, by `networkName`) an internal Docker network (`Internal: true`, label `com.lousho.sandbox=egress`), has the broker listen on its gateway address for that subnet only, and starts each container on it with `HTTP_PROXY`/`HTTPS_PROXY` pointing there, so the broker (allowlist: its rule hosts plus `allow`) is the container's only route out. New `sandbox.close()` stops the listener and removes the network it created. New `broker.listen({ host, clients, allow? })` adds a listener on another address that drops peers outside the `clients` subnet; the broker still listens on loopback only by default. Enforced on Docker Engine 25.0.5+ for Linux with the agent on the same host; Docker Desktop, rootless Docker, a remote daemon, a non-internal reused network and older Engines are refused with the new code `LOUSHO_SANDBOX_EGRESS_UNSUPPORTED` (no container is started). Without a `broker`, `{ allow }` still means no network. See docs/workspace-tools.md.
+- The Docker sandbox honors cancellation (LOU-U23): `SubprocessSandbox.run()` takes `signal` (`SandboxRunOptions`). When it aborts, the container is killed and force-removed (errors from an already stopped or removed container are ignored) and `run()` rejects with an `AbortError`, like `NoopSandbox`; an already-aborted signal starts no container; a timeout uses the same cleanup. `SandboxShell` passes the tool's abort signal down, so a cancelled `shell` call stops its container (it used to run until the timeout) and reports `aborted: true`. See docs/workspace-tools.md.
+- Schedules on Cloudflare Workers (LOU-P9): the `cloudflare-worker` target writes the spec's `{ type: 'cron', cron, input, name?, timezone? }` triggers (deduplicated) to `wrangler.toml` as `[triggers] crons = [...]`, and the generated Worker exports `scheduled(controller, env, ctx)`, which runs every trigger whose expression equals `controller.cron` as an agent turn inside `ctx.waitUntil()`, in session `schedule:<name>` (visible in the KV store when bound). A failing trigger is logged with `console.error` (name and error code) and never stops the others. The build fails with `LOUSHO_SCHEDULE_INVALID` naming the trigger for what Cloudflare would not fire: a `timezone` (crons are UTC), a seconds field or `@daily` shortcut, a numeric day-of-week (Cloudflare counts 1 as Sunday). New `handleScheduled(agent, schedules, controller, ctx)` (root and `deploy-runtime-worker`) wires `defineSchedule` schedules to a hand-written Worker's `scheduled()`. `startSchedules` shares its fire step with it. See docs/schedules.md#on-cloudflare-workers.
+- `ai` v6 and v7 as peers (LOU-D28d): `peerDependencies` now accept `ai` `^4.3.19 || ^6.0.0 || ^7.0.0` and `@ai-sdk/openai` / `@ai-sdk/anthropic` `^0.0.42 || ^1.0.0 || ^3.0.0 || ^4.0.0` (still optional), plus the new optional peer `ollama-ai-provider-v2` `^2.0.0 || ^3.0.0 || ^4.0.0`, so a project on the current `ai` major installs without peer conflicts. Pairings: `ai` 4 with `@ai-sdk/*` 0.0.x/1.x and `ollama-ai-provider` 1.x; `ai` 6 with `@ai-sdk/*` 3.x and `ollama-ai-provider-v2` 2.x/3.x; `ai` 7 with `@ai-sdk/*` 4.x and `ollama-ai-provider-v2` 4.x. A missing provider package's `MissingPeerDependencyError.installCommand` names the version for the installed `ai` major (`npm install @ai-sdk/openai@^4.0.0` on `ai` 7; unchanged on `ai` 4). `OllamaProvider` loads `ollama-ai-provider-v2` on `ai` 6/7; that package needs zod 4, which the SDK does not support yet, so its install hint says so and Ollama stays on `ai` 4 for now. `lousho doctor` checks provider packages against the installed `ai` major and flags a mismatched pair (e.g. `ai` 7 with `@ai-sdk/openai` 1.x) with the version to install; a missing or unsupported `ai` gets `npm install ai@^7.0.0`. `lousho init` / `npm create lousho-agent` scaffold `ai@^7.0.0` with `@ai-sdk/openai@^4.0.0` / `@ai-sdk/anthropic@^4.0.0` for OpenAI and Anthropic, and keep `ai@^4.3.19` for Ollama (zod 4) and OpenRouter (`@ai-sdk/openai` 2+ defaults to the Responses API, not yet verified there). The hint of `resolveProvider()`'s rare synchronous missing-peer error lists the command for each `ai` major. See [Installation](docs/installation.md#provider-packages).
+- `lousho add` (LOU-D50): `lousho add <name> [--registry <url-or-path>] [--dir <agent-dir>] [--yes] [--overwrite] [--dry-run]` installs a tool, skill, channel, schedule or memory slot from a static JSON registry (an index plus one document per item that carries the file contents) into an agent directory as source you own; `lousho add --list` prints the index. The registry comes from `--registry` or `LOUSHO_REGISTRY` (there is no hosted registry yet). It prints the item's permission manifest (hosts, env vars, filesystem, exec, whether its tools ask for approval) and the files first and asks for confirmation (`--yes` skips it; a non-interactive stdin without `--yes` refuses; `--dry-run` writes nothing). Paths must be relative, inside the folder of the item's type and inside the agent directory (no `..`, absolute paths, drive letters, backslashes or symlink escapes), files and items have size caps, existing files need `--overwrite`, fetches time out and only `http(s)` and local paths are read; nothing from a registry is executed and `dependencies` are only printed as an `npm install` line. New error codes `LOUSHO_REGISTRY_UNREACHABLE`, `LOUSHO_REGISTRY_ITEM_NOT_FOUND`, `LOUSHO_REGISTRY_INVALID`, `LOUSHO_REGISTRY_UNSAFE_PATH`, `LOUSHO_REGISTRY_FILE_EXISTS`. See docs/registry.md.
+- Checkpoint history for `KVCheckpointStore` and Agent Forge's file store (LOU-D43.2): `KVCheckpointStore` (and `KVStore`, with the new `historyLimit` option) keeps the bounded per-session history `memoryStore()` keeps, as one index key (`<prefix><sessionId>#history`) and one key per entry (`<prefix><sessionId>#history/<id>`) next to the unchanged latest-checkpoint key, so `agent.fork()`, `compareTrajectories()` and time travel work for Worker-deployed agents; a store written before this change still loads. A save now makes one `get` and two `put`s more (`historyLimit: 0` turns the history off), and two concurrent saves of one session can lose an index update (KV has no transactions). Agent Forge's `FileCheckpointStore` reads a partially written history file as empty and writes its files atomically. The history contract suite now runs against `KVCheckpointStore` too. See docs/durable-execution.md#checkpoint-history.
+- Hook outcomes (LOU-X3): a `preToolCall` hook may return `{ deny: reason }` (the call does not run; the model gets the same `kind: 'denied'` tool error as a `needsApproval` deny, streams see `tool.error`, and `onPermissionDecision` / `permission.decision` record `decision: 'deny'` with the new `hook` field and `reason`), `{ result: value }` (the call does not run; `value` is its result) or `{ input: args }` (the call runs with `args`, validated against the tool's schema again; a mismatch is a `kind: 'validation'` tool error naming the hook). A `postToolCall` hook may return `{ result: value }` to replace the result the model sees. Pre-hooks run in registration order: the first deny or result skips the later ones, inputs chain. A replaced result is marked `replacedByHook` on the `tool.done` event, the `ToolCallOutcome` / `tool-result` event and the transcript's `tool` message `metadata`. Hooks still run first (after argument validation, before permission rules, tool guardrails and `needsApproval`), so the approval sees the hook's input; on a resumed approved call the pre-hooks run again and an `{ input }` that differs from the approved input is refused. Sub-agents inherit the outcomes. Hooks that return nothing type-check and behave as before; `HookRegistry.runPreToolCall()` now resolves to a `PreToolCallDecision` and `runPostToolCall()` to the name of the replacing hook (new types `PreToolCallOutcome`, `PostToolCallOutcome`, `PreToolCallDecision`). A hook that throws still rejects the run. See docs/api-overview.md#hook-outcomes.
+- `lousho acp` (LOU-Z6): `lousho acp <spec.yaml|spec.json|agent-dir|agent.ts> [--model provider/model]` serves an agent over the Agent Client Protocol (v1) on stdio, so Zed and other ACP editors can run it as an external agent; stdout carries only JSON-RPC lines (the agent's `console.log` goes to stderr). It implements `initialize`, `session/new`, `session/prompt` (text and `resource_link` blocks) and `session/cancel`, streams `session/update`s (`agent_message_chunk`, `tool_call`, `tool_call_update`), asks `session/request_permission` (Allow / Reject) when a tool needs approval and streams the continuation, and maps finish reasons to stop reasons (`max-steps` to `max_turn_requests`, `budget-exceeded` / `length` to `max_tokens`, `guardrail` to `refusal`, a cancel to `cancelled`). One ACP session is one SDK session. An `ask_question` pause ends the turn with the question as the agent's message; the next prompt answers it. A failed run answers a JSON-RPC error whose `data.code` is the SDK error code. The protocol core is exported as `serveAcp(agent, { input, write, store? })` (new type `ServeAcpOptions`), transport-independent. Not supported yet: `session/load`, the client's `fs/*` and `terminal/*` methods, images, audio and embedded resources, `plan` and thought chunks. See docs/acp.md.
+- Agent directories deploy and serve with their schedules and channels (LOU-P8.2): `lousho build <agent-dir> --target=node-server` (and `docker`; the path may also be `--agent`) builds a directory into a server whose entry calls `resolveAgentDir()` and `createDeployedServer(agent, { schedules, channels })`, so the deployed process starts the `schedules/` and mounts the `channels/` under `/channels` and logs which it found. The code files are pre-bundled by the existing tsup step into `dist/agent/**.js` (one ESM build sharing one SDK copy; `dist/` is marked ESM) and the rest of the directory is copied, so nothing needs a TypeScript loader at run time; spec builds are unchanged. `lousho dev <agent-dir>` mounts the directory's channels and starts its schedules, swapping both on hot reload (old schedules stopped first); `--no-schedules` starts none. The deploy runtime also exports `createAgent`, `resolveAgentDir` and `storeFromEnv`. The Cloudflare Worker target is unchanged (P9). See docs/agent-directories.md#deploy-it-with-lousho-build.
+- Route handler (LOU-P4): `createRouteHandler(agent, { basePath?, auth?, uiMessageStream? })` returns `{ GET, POST, handler }`, Fetch handlers (`(request: Request) => Promise<Response>`) that serve the deployed session API under `basePath` (default `/api/agent`; trailing slash accepted, other paths 404) from a Next.js App Router `app/api/agent/[[...path]]/route.ts`, SvelteKit `+server.ts`, Hono or Bun.serve, with no framework or `node:*` import. `auth` is a bearer token or a `(request) => boolean | Promise<boolean>` (default none: a public route needs one; `GET /health` stays open). `useLoushoAgent({ url, approvalsUrl })` works against it (`POST <basePath>` with `{ input, sessionId? }`, `POST <basePath>/approvals/:id`), and `uiMessageStream: true` adds `POST <basePath>/ui` for `useChat`. `hasBearerToken` in `src/server/fetchRoutes.ts` is now exported for it. See docs/nextjs.md.
+- AI SDK UI stream (LOU-P1): `toUIMessageStream(run)` maps a run's events to the Vercel AI SDK's UI message stream chunks (`start`, `start-step`, `text-start` / `text-delta` / `text-end`, `tool-input-start` / `tool-input-available` / `tool-output-available` / `tool-output-error`, `finish-step`, `error`, `finish` with the AI SDK finish reason), and `toUIMessageStreamResponse(run, init?)` returns the SSE `Response` (`data: [DONE]`, header `x-vercel-ai-ui-message-stream: v1`) for a route handler, so `useChat` can render a Lousho run. An approval pause or `ask_question` is a `data-lousho-approval` part (`approvalId`, `toolCallId`, `toolName`, `input`, `kind?`, `question?`); usage and the run's own finish reason are in the `finish` chunk's `messageMetadata`. `fromUIMessages(messages, { lastUserOnly? })` converts the `UIMessage[]` `useChat` posts (text, image and file parts; others ignored) to an `AgentInput`. Own structural chunk types (`LoushoUIMessageChunk`, `UIMessageLike`, ...), no `ai` import and no `node:*`, so it also runs on Workers; exported from the package root (a dedicated subpath can follow). See docs/ai-sdk-ui.md.
+- Approval policies (LOU-X8): a `needsApproval` function may return (or resolve to) `'approve'`, `'deny'`, `'ask'` or `{ deny: reason }` besides a boolean (`true` is `'ask'`, `false` is `'approve'`; new type `ApprovalOutcome`), and gets a second argument `{ toolName, toolCallId, sessionId?, messages }` (new type `ApprovalCheckContext`). A deny does not pause: the call is not run, the model gets a `kind: 'denied'` tool error with the reason, streams see `tool.error`, and `onPermissionDecision` / `permission.decision` record `decision: 'deny'` with the new `reason` field (no `rule`); the audit entry is now reported once the call is decided (after tool guardrails) instead of before them. New helpers `always()`, `never()` and `once({ per?: 'tool' | 'args' })` (with type `ApprovalPolicy`): `once()` asks the first time a tool is called in a session and runs later calls once a human approved one (a rejection is not remembered; `per: 'args'` keys on the arguments' hash). The memory is the approved call's `tool` message (`metadata.approval`, set by `resumeAfterApproval()` and its streamed form), so it persists with sessions, checkpoints and approval snapshots and survives a resume in another process. A `permissions` `deny` rule wins; an `allow` or `ask` rule replaces the tool's ask but not its deny (see Changed); the tool's outcome applies when no rule matches. Existing boolean functions type-check and behave as before; a test asserting `needsApproval` was called with exactly one argument now sees the context too. See docs/approvals.md#approve-deny-or-ask.
+- Approval continuations stream live (LOU-D32.2): `POST /chat/:sessionId/approvals/:id` (node server, Cloudflare Worker, `lousho dev`) now streams the continuation from `agent.approvals.streamResolve()` / `streamAnswer()` instead of replaying it after the turn ends; `createAgentRunner`'s `approve()` / `reject()` / `answer()` (React, Vue, Svelte) read that SSE stream event by event (an `ApprovalOutcome` JSON from an older server still works), and `lousho chat` prints the continuation as it streams. The UI reducer maps a streamed `tool.error` named `ToolRejectedError` to a `rejected` tool call. A second pause arrives as `approval.requested`. The approvals route has always answered with SSE, so no client opt-in was added.
+- `session.compact()` and `session.clear()` (LOU-W8): `await session.compact({ strategy?, protectedTokens?, contextWindow?, signal? })` compacts the session's transcript now, whatever its size, with the given strategy, else `agent.session({ compaction })` (new option, the value of `createAgent({ compaction })`), else by pruning old tool results; it saves the result through the session's store and resolves to `{ messagesBefore, messagesAfter, tokensBefore, tokensAfter, strategy, error? }`. `clear()` (which already existed and forgot the conversation) now emits `context.cleared` (new `ContextClearedEvent` in the `AgentEvent` union) and rejects with `LOUSHO_SESSION_AWAITING_APPROVAL` when a durable turn waits on an approval; it keeps the session id. New `session.on(listener)` receives `compaction.start` / `compaction.done` (which gain an optional `trigger: 'manual'`) and `context.cleared`. Both reject with the new `LOUSHO_SESSION_BUSY` while a turn is in flight; `compact()` also with `LOUSHO_SESSION_TURN_PENDING` for an interrupted durable turn. `lousho chat` gains `/compact` and `/clear`. See docs/compaction.md#compacting-a-session.
+- Discord channel (LOU-P6): `discordChannel({ publicKey, applicationId, botToken?, name?, fetch? })` serves Discord's HTTP Interactions endpoint through `mountChannels()` (Web Crypto and `fetch` only, Worker-safe, no gateway, no new dependency). It verifies `X-Signature-Ed25519` / `X-Signature-Timestamp` (Ed25519 over `timestamp + body`, 401 otherwise) and answers `PING` with `PONG`. A slash command (`/ask prompt:<text>`) is acknowledged at once with a deferred response; its session is keyed on guild + channel (+ thread), and the reply edits the original response, with text over 2000 characters continued in follow-up messages. A tool approval is posted with Approve / Deny buttons and resolved by the click; an `ask_question` is answered by the next `/ask` in the channel. See docs/channels.md#discord.
+- Streaming resume after an approval (LOU-V14): `streamResumeAfterApproval(decision, approvalStore, toolRegistry, provider, options?, checkpointStore?)` takes `resumeAfterApproval()`'s arguments and returns an `AgentRun` whose `result` is what `resumeAfterApproval()` returns. Its events are `run.start`, the decided call's `tool.start` / `tool.done` (`tool.error` for a rejection), then the continuation's events as in a fresh `stream()` run; a further pause ends it with `approval.requested`. Abort, `enqueue()` and `steer()` work as on any run, and the approval can be resolved in another process. `createAgent()` agents get `agent.approvals.streamResolve(decision, { signal })` and `streamAnswer({ id, answer }, { signal })` (a pause made in a session continues in it, `run.done` after the transcript is saved; a dynamic agent keeps the model the paused run used). Also new: the `ResumeRequest` type and `resumeRequest(request)` (`resumeAfterApproval()` with one object argument). Additive: `resolve()`, `answer()` and `resumeAfterApproval()` are unchanged. See docs/streaming.md#streaming-after-an-approval.
+- Credential broker (LOU-X12): `createCredentialBroker({ rules, allow?, allowPrivate?, port?, host?, pathFormScheme? })` starts a host-side HTTP forward proxy (Node-only, on an ephemeral `127.0.0.1` port by default) and resolves to `{ url, env, baseUrl(host), close() }`. `rules` map a host (exact or `*.suffix`) to headers to inject, as strings or per-request functions, so a command the model runs can call an authenticated API without the token entering its environment: pass `broker.env` (`HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY`, both cases) to `NodeWorkspace` or `SandboxShell`'s `env`. Hosts outside the rules and `allow` get a 403 without a connection; hosts resolving to loopback, link-local or private addresses are refused unless in `allowPrivate`; a client `Authorization` header for a brokered host is replaced; hop-by-hop headers are dropped. Injection covers plain-HTTP requests and the `/__broker/<host>/<path>` form (forwarded to `https://<host>/<path>`, returned by `baseUrl(host)`); HTTPS `CONNECT` tunnels are allowlist-checked and passed through untouched (no TLS interception). `SubprocessSandbox`'s `network: { allow }` still fails closed: routing containers through the broker is LOU-X12.2. New types `CredentialBroker`, `CredentialBrokerOptions`, `BrokerHeaderValue`. See docs/workspace-tools.md#credential-broker.
+- Memory in agent directories (LOU-W6.3): `memory/*.ts|js|mjs` files default-export a memory slot (`defineMemory()`, or the same options without a `name`; name = file name unless set). Unlike schedules and channels they are part of the agent: `loadAgentDir()` passes them to `createAgent({ memory })`, `resolveAgentDir()` lists them in `manifest.memory`, and a `memory` override is merged by name (the override wins a clash). A bad file fails with the new `LOUSHO_MEMORY_INVALID` naming the file. A directory without `memory/` is unchanged. See docs/agent-directories.md#memory.
+- Channels in agent directories (LOU-P7.2): `channels/*.ts|js|mjs` files default-export a channel (`defineChannel()` or a built-in factory; name = file name unless set); `resolveAgentDir()` returns them as `channels` and `manifest.channels`, and a file that exports no channel fails with the new `LOUSHO_CHANNEL_INVALID` naming the file. `createDeployedServer(agent, { channels })` mounts them under `/channels` next to the chat routes. `loadSchedules()` and `loadChannels()` share one loader (schedule files that do not export a schedule now throw an `SDKError` with `LOUSHO_SCHEDULE_INVALID`, same message). `lousho dev` and the Cloudflare Worker target do not mount them yet. See docs/agent-directories.md#channels.
+- `serveMcp` annotations (LOU-Z5.2): `defineTool({ annotations })` (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`, `title`; stored as `metadata.mcp.annotations`) is sent in `tools/list` verbatim, and a tool with `needsApproval` is advertised `readOnlyHint: false, destructiveHint: true` (never read-only). An unannotated tool sends none. A Lousho agent consuming the server therefore runs read-only tools without an approval pause, pauses for `needsApproval` ones and keeps asking for unannotated ones. The built-in `read_file`, `list_dir`, `glob`, `grep`, `todo_read`, `current_date` and `day_name` tools are marked read-only. See docs/configuration.md#annotations.
+- Svelte store (LOU-P3): new `@lousho/build-ai-agent/svelte` subpath with `loushoAgent(source, options?)`. It returns a Svelte store (`subscribe(run) => unsubscribe`, so `$agent` works in Svelte 4 and 5) whose value is the same state as the React hook and the Vue composable (`messages`, `status`, `pendingApproval`, `error`, `usage`, `lastEvent`), plus `send()`, `stop()`, `approve()`, `reject()`, `answer()` and `reset()`. The run in flight is aborted by `stop()` and when the last subscriber unsubscribes. The store contract is implemented by hand: the entry imports nothing from `svelte`, so there is no new peer dependency. See docs/svelte.md.
+- Per-run dynamic config (LOU-V15): `createAgent()`'s `model`, `instructions` / `prompt` and `tools` each also take a function of the run, `(ctx) => value | Promise<value>` (new types `PerRun<T>` and `RunConfigContext` = `{ sessionId?, input, metadata? }`), resolved once at the start of each run and of each session turn, before the first model call. `fallbackModels`, `retry`, `projectInstructions`, memory, MCP tools, sub-agents, permissions, approvals and guardrails apply to the resolved values; a dynamic agent used as a sub-agent resolves with the task prompt as `input`. `session.send()` / `session.stream()` gain the `metadata` option (`send()` / `stream()` already had it, and now pass it to these functions too). A function that throws fails the run with the new `LOUSHO_CONFIG_RESOLVER_FAILED` (`field` names the option, `cause` is the error); a session keeps its transcript. A run paused for approval stores its `ctx` and resolved model in the approval snapshot (`agent.metadata.loushoRunConfig`): resuming it uses that model and re-resolves the tools with the same `ctx`; a crash resume from a checkpoint resolves with `input: []`. Static options behave and type as before. `SessionRunner` / `SessionStreamRunner` take an optional fourth `call` argument (new type `SessionTurnCall`). See docs/api-overview.md#dynamic-config.
+- Vue composable (LOU-P2): new `@lousho/build-ai-agent/vue` subpath with `useLoushoAgent(source, options?)` for Vue 3. It takes the same sources and options as the React hook (either may be a `ref`, read when a turn starts) and returns `messages`, `status`, `pendingApproval`, `error`, `usage` and `lastEvent` as read-only refs, plus `send()`, `stop()`, `approve()`, `reject()`, `answer()` and a new `reset()` (aborts, forgets the in-process session, clears the chat). The run in flight is aborted by `stop()` and when the owning scope is disposed (`onScopeDispose`: component unmount, `effectScope().stop()`). `vue` (`^3`) is an optional peer dependency, loaded by no other entry. To share the logic, the reducer and the stream parser moved from `src/react/` to a framework-neutral `src/ui/`, together with the run logic extracted from the React hook (`createAgentRunner()`); the `./react` exports are unchanged, and the reducer gains an additive `ui.reset` action. See docs/vue.md.
+- One flag parser for the `@linuxdevil/lousho` CLI (LOU-U21): every command (`dev`, `chat`, `eval`, `build`, `mcp`, `doctor`, `studio`; `init` already did) parses its flags with `node:util` `parseArgs` in strict mode through `src/cli/args.ts`. `--flag value` and `--flag=value` work everywhere, `--` ends the flags, `-h` / `--help` prints the usage and exits 0, and an unknown flag, a flag without its value or an extra argument fails with `LOUSHO_CONFIG_INVALID` and the command's usage as the hint. **Behaviour change (migration):** `dev`, `studio`, `mcp`, `build` and `doctor` used to ignore unknown flags, and a flag missing its value could take the next flag or a prefix match (`--portx 1` read as `--port`); they now fail with exit 1 and the usage line, so remove typos from scripts. A value that starts with `-` must be written `--flag=-x` (a bare `--flag -x` is a missing value); `--port` must be an integer from 0 to 65535 for `dev`, `studio` and `mcp`; `dev`, `mcp` and `doctor` reject a second path; `studio --prod --dev` is rejected instead of preferring `--prod`. `lousho dev` and `lousho studio` parsing moved from `bin/lousho.js` into `src/cli/dev.ts` / `src/cli/studio.ts` (`parseDevArgs`, `runDev`, `parseStudioArgs`, `runStudio`). See docs/cli.md.
+- `sqliteMemory(store, { maxItems? })` (LOU-W6.2, exported from `@lousho/build-ai-agent/sqlite`) keeps `defineMemory` slots in the agent's `SqliteStore` file: a new `memory_items` table (migration 3, one JSON array per scope key, with the same serialization, `maxItems` and query rules as `fileMemory`). An existing database gains the table on open and keeps its sessions and checkpoints. The memory provider contract tests now run against the in-memory, file and SQLite providers. See docs/memory.md#sqlite.
+- Slack channel (LOU-P5): `slackChannel({ signingSecret, botToken, name?, fetch? })` (new export, with types `SlackChannelOptions`, `SlackChannelEvent`, `SlackThread`) serves a Slack app's Events API and interactivity requests through `mountChannels()`. It verifies the `v0` request signature with Web Crypto (no `node:*` import; the timestamp and header checks are shared with `verifySlackSignature()`), answers the `url_verification` challenge, and acknowledges every request before the turn runs. Each Slack thread is one session (team + channel + thread root `ts`): a mention starts or continues it, and later messages in a thread the bot was mentioned in continue it. Retries (`X-Slack-Retry-Num`) and bot messages are skipped. Replies go to the thread with `chat.postMessage` over `fetch`; a tool approval is posted as Approve / Deny buttons whose click resumes the session, and an `ask_question` as text answered by the next thread message. The channel contract gains two additive hooks for this: `parse(req, respond)` may call `respond` to answer the request before the turn runs, and may return `{ decision }` (new type `ChannelDecision`; `ChannelApprovalDecision` now lives in `defineChannel.ts`, same public export) to resolve a pause instead of starting a turn. See docs/channels.md#slack.
+- Remote sub-agents (LOU-Y7): `remoteAgent({ url, auth?, name?, description?, headers?, fetch? })` (new export, with types `RemoteAgentOptions` and `RemoteSubagent`) makes a deployed agent usable wherever a local sub-agent is: in `createAgent({ subagents })` records and `SubagentCatalog.resolve()`, delegated to by the `task` tool and by `background: true` tasks. Each task opens a fresh session on the remote agent over `POST <url>/chat` (bearer `auth`: a string or a function, called per task), reads the SSE stream to the end and returns the remote agent's final text; the lead run's abort signal aborts the request. Failures (network, 401 or other non-2xx, malformed stream, remote run error) are structured tool errors with the new code `LOUSHO_REMOTE_AGENT_FAILED`, and the token never appears in errors or events; a remote run that pauses for approval fails with `LOUSHO_SESSION_AWAITING_APPROVAL` naming the remote session (proxying approvals is a follow-up). Worker-safe (`fetch` only). See docs/sub-agents.md#remote-sub-agents.
+- Eval against a deployed agent (LOU-D47): `lousho eval --url <baseUrl> [--token <bearer>]` (token also from `LOUSHO_EVAL_TOKEN`) runs every case of the trajectory eval files against a deployment (node server or Cloudflare Worker) instead of the in-process agent: one remote session per case over `POST /chat { sessionId, input }`, the SSE stream read to `run.done` and turned into the usual result (tool calls, reply, finish reason, steps, usage), so checks, scorers, `t.judge()`, the summary and `--junit` work unchanged. A check that needs data the stream lacks (`maxTokens` without usage) fails and names what is missing. Programmatic equivalent: `defineEval({ target: remoteTarget({ url, auth?, fetch? }) })` (new `remoteTarget()`, `EvalTarget`; `agent` is now optional when a `target` is given, and `AgentSource` also accepts any `{ send() }`). `--url` with `--record` / `--replay` / `--drift` is rejected with `LOUSHO_CONFIG_CONFLICTING_OPTIONS`; an unreachable deployment, a non-2xx answer or a truncated stream fails the case with the new `LOUSHO_REMOTE_REQUEST_FAILED`, and 401 with `LOUSHO_REMOTE_UNAUTHORIZED`. The token never reaches output or reports. See docs/evals.md#run-evals-against-a-deployment.
+- Schedules (LOU-P8): `defineSchedule({ cron, timezone?, name?, prompt | run })` declares a cron schedule (a `prompt` sent to the agent as a new turn, or `run({ agent, firedAt, name })`); an invalid cron expression, or not exactly one of `prompt`/`run`, throws the new `LOUSHO_SCHEDULE_INVALID` at definition time. An agent directory's `schedules/*.ts|js|mjs` files default-export one each (name = file name unless set); `resolveAgentDir()` returns them as `schedules` and `manifest.schedules`. `startSchedules(agent, schedules, { now?, setTimer?, onError? })` runs them with injectable clock and timers, isolates errors, skips a fire while the previous one runs and returns `stop()`; `createDeployedServer(agent, { schedules })` starts them on listen and stops them on close. The Cloudflare Worker target is not covered yet. See docs/schedules.md.
+- Channels (LOU-P7): `defineChannel({ name, verify?, parse, reply, onApproval?, sessionId?, stream? })` describes one surface: `verify` authenticates a request (`false` or `{ ok: false }` answers 401), `parse` maps it to `{ sessionKey, input, metadata?, replyTo }` (or `null` to acknowledge it without a turn), `reply` delivers the agent's reply (with `stream: true`, also partial text as the model writes) and `onApproval` renders a pause (default: a text prompt through `reply`). `mountChannels(agent, channels, { store, basePath })` returns a framework-free `(req, res)` handler, in the style of the `/chat` routes, that serves `POST <basePath>/<name>` (verify -> parse -> a turn in session `` `${name}:${sessionKey}` `` -> reply; turns of one session run one at a time) and `POST <basePath>/<name>/approvals/<id>` (`{ approved, note? }` or `{ answer }`); `handler.resolveApproval()` decides a pause from code (e.g. a button callback) and replies through the same channel. Built in: `httpChannel()` (JSON `{ sessionKey, input }` in, `{ sessionId, text, finishReason, approval? }` out) and `webhookChannel({ secret })` (`WebhookTriggerAdapter`'s behaviour; the adapter now delegates its auth and parsing to it, unchanged for callers). Slack and Discord channels are LOU-P5 / LOU-P6. See docs/channels.md.
+- Cloudflare Worker parity (LOU-D51): the `cloudflare-worker` target now serves the same API as the node server: `POST /chat { sessionId, input }` streamed as SSE, history per session, `GET /chat/:sessionId`, `POST /chat/:sessionId/approvals/:id` and `GET /health`; the deprecated `POST /chat { message, sessionId? }` still works and still checkpoints under `sessionId`. `LOUSHO_API_TOKEN` (a Worker secret: `wrangler secret put LOUSHO_API_TOKEN`) makes every route except `/health` require `Authorization: Bearer <token>` (constant-time compare). New `KVStore(kvBinding, { prefix?, ttl? })` (`src/deploy/kvStore.ts`) is an `AgentStore` on a Workers KV namespace: `sessions/<id>` (transcript JSON, bytes as `{ "$bytes" }`), `checkpoints/<id>` (`KVCheckpointStore`, which gains an optional TTL) and `approvals/<id>`, with optional per-kind TTLs; the Worker builds it from the existing `AGENT_CHECKPOINTS` binding, and keeps sessions in the isolate's memory without one. An approval paused on one request can be decided by another request on a new isolate. The routes are now Fetch-native (`src/server/fetchRoutes.ts`: `Request` in, `Response` and a `ReadableStream` SSE body out, bearer auth with Web Crypto); `src/server/chatRoutes.ts` adapts them to `node:http` for `lousho dev` and the node server, and `src/server/bearerAuth.ts` is gone. The built Worker runs a `createAgent()` agent, so the build swaps its Node-only imports for `src/deploy/shims/node.worker.ts`, and the `node:` leak check now also catches bare builtin specifiers; the bundle grows to about 1.7 MB. The generated `wrangler.toml` documents the KV binding and both secrets. The `wrangler dev` test now streams a session turn through workerd with a KV binding and a token. See docs/deployment.md#bindings-sessions-and-the-api-on-workers.
+- Steering (LOU-V10): `run.steer(input)` on `AgentRun` (from `agent.stream()`, `session.stream()` and `AgentExecutor.stream()`), and `InputQueue.steer(input)` for non-streaming callers, redirect a running run to new user input. If a model call is in flight and has not emitted text or tool calls yet, it is aborted with a per-call signal (not the run's), its partial output is discarded, the input is appended as a user message and the model is called again (`applied: 'immediate'`; that step ends with `step.done` `'steered'` and counts toward `maxSteps`; a provider that ignores the signal is not waited for). Once the model has emitted output, the input waits for the next safe point like `enqueue()` (`'queued'`); after the run has finished, `applied` is `false`. Tool calls already running finish and keep their results; calls of that turn not started yet get the usual "cancelled before it ran" result. It returns `{ id, applied, joined }` (new type `SteerResult`; `joined` is a promise of whether the input reached the transcript). New event `input.steered` `{ id, text, mode: 'immediate' | 'queued' }` (`InputSteeredEvent`, additive, schema v1), followed by the existing `input.applied`. With checkpointing, the input is checkpointed when it is taken, before the model is called again, and the discarded partial turn is never checkpointed. `agent.session({ turnPolicy: 'steer' })` makes a `send()` / `stream()` made while a turn runs steer that turn (`'queue'` and `'wait'` are unchanged). `AgentRun` gains the required `steer()` member, so a hand-written `AgentRun` object must add it. See docs/streaming.md#steering and docs/sessions.md.
+- `ai` v6/v7 `stream()` (LOU-D27): the built-in providers' `stream()` (and so `agent.stream()`) now works on `ai` v6 and v7 as well as v4, through the LOU-D26 compatibility layer (`streamCompat()`): the request is mapped as for `generate()`, and either major's `fullStream` is read into the same `StreamChunk`s: text deltas, tool calls (the whole call, or one assembled from `tool-input-start`/`-delta`/`-end` when the model sends none), and a `finish` chunk with the finish reason and usage, including cached and reasoning tokens. An `error` part now rejects the stream with its error on both majors (on v4 the step used to end with finish reason `error` and the partial text), an `abort` part with the signal's reason; reasoning deltas are dropped until a reasoning chunk type exists (LOU-V13). `StreamChunk`/`StreamResult` are unchanged. The protected `AiSdkProvider.convertMessages()` now returns our structural `AiSdkMessage[]` instead of `ai` v4's `CoreMessage[]` (which v6/v7 do not export) and is marked deprecated for LOU-D28; an override returning `CoreMessage[]` still compiles. The `ai`/`@ai-sdk/*` peer ranges still name v4 (LOU-D28). Tested on the real `ai` v7 (`MockLanguageModelV4`), with `agent.stream()` events asserted by one helper on v4 and v7. See docs/providers.md#vercel-ai-sdk-versions.
+- `spec.policy` is enforced (LOU-X5): `specToAgent()` compiles the policy block into `createAgent()` options through the new `compilePolicy()`. `requiresApproval` (`true` or a list of tool names) becomes `permissions: [ask(...)]`; `guardrails` (`max-length`, `secret-scan`, `regex`, `deny-topics`, `llm-judge`, by name or `{ name, ...options, on }`) become input and output guardrails; `limits`, `askQuestion` and `compaction` pass through. `loadSpec()` validates the known fields (an unknown guardrail name fails with the names available and a did-you-mean; unknown policy keys are still kept for the generators), and `lousho doctor <spec>` prints one line per policy block and flags unknown guardrail names. **Behaviour change:** `requiresApproval: true` now actually pauses tool calls (`finishReason: 'awaiting-approval'`); before, a spec that set it ran its tools without asking, and a spec with a guardrail name outside the built-ins (for example `diff-size-cap`) now fails validation. See docs/configuration.md#policy-policy.
+- `ai` v6/v7 `generate()` (LOU-D26): the built-in providers' `generate()` now works on `ai` v6 and v7 as well as v4, through a compatibility layer that detects the installed major (v5+ exports `stepCountIs`). On v6/v7 it sends messages as `ModelMessage`s (tool calls with `input`, tool results as `output`, `mediaType`), `maxTokens` as `maxOutputTokens`, one step as `stopWhen: stepCountIs(1)`, tools as `inputSchema` without `execute` and `responseFormat` as a JSON-mode `output`, and reads usage from `inputTokens`/`outputTokens`/`totalTokens` (cached and reasoning tokens from their details) into the same `GenerateResult`. `LLMProvider`, `GenerateOptions` and `GenerateResult` are unchanged, and v4 behaves as before. `stream()` on v6/v7 throws an error naming LOU-D27 until that ticket lands; the `ai` and `@ai-sdk/*` peer ranges still name v4 (LOU-D28). Tested against the real `ai` v7 (`MockLanguageModelV4`) next to the v4 contract tests. See docs/providers.md#vercel-ai-sdk-versions.
+- Queued follow-up input (LOU-V9): `run.enqueue(input)` on `AgentRun` (from `agent.stream()`, `session.stream()` and `AgentExecutor.stream()`) adds user input to a run that is still going; it joins the transcript at the next safe point (after the current step's tool results, before the next model call) and the run continues as if the user had typed it, with one more step when it arrives during the final reply. It returns `{ id, applied }`: `applied` is `false` when the run had already finished (send the input as a new turn, e.g. `session.send()`), otherwise a promise of whether it was applied. New events `input.queued` `{ id, text }` and `input.applied` `{ id, step }` (additive, schema v1). Non-streaming callers pass an `InputQueue` (new export) as `ExecuteOptions.inputQueue` and call its `push(input)`. With checkpointing, a waiting input is saved right away at the end of the checkpoint (the LOU-U8 queued-input slot), so a crash does not lose it. `agent.session({ turnPolicy: 'queue' })` makes a `send()` / `stream()` made while a turn runs (or waits to start) join that turn instead of waiting for its own (`'wait'`, the default, keeps today's behaviour). `AgentRun` gains the required `enqueue()` member, so a hand-written `AgentRun` object must add it. Steering (aborting the in-flight model call to redirect) is the follow-up, LOU-V10. See docs/streaming.md#queued-input and docs/sessions.md.
+- Input and output guardrails (LOU-X4): `guardrails?: { input?, output?, tools?, onTripped? }` on `createAgent()` and `ExecuteOptions` (new type `AgentGuardrails`). A guardrail is `{ name, check(ctx) }` (new type `IoGuardrail`; `ctx` is `{ kind: 'input' | 'output' | 'tool', text, messages, toolName?, args?, signal? }`) returning `{ ok: true }` or `{ ok: false, reason, action?: 'block' | 'rewrite', replacement? }`. Input guardrails run on each new user message before the first model call; output guardrails on the final reply (in a streamed run, on every step's text, before its `text.done`); tool guardrails on a call's arguments after the permission rules (skipped on `deny`) and before `needsApproval`. A block ends the run with the new `finishReason: 'guardrail'` and `result.guardrail` (`{ name, kind, reason, toolName? }`, new type `GuardrailTrip`), with no model call for an input block; `onTripped: 'throw'` rejects with the new `GuardrailError` (`LOUSHO_GUARDRAIL_TRIPPED`) instead. A rewrite replaces the text. `stream()` emits the new `guardrail.tripped` (before `run.done`) and `guardrail.rewrote` events. Sub-agents run their parent's guardrails, then their own. Built-ins: `maxLengthGuardrail({ maxChars })`, `regexGuardrail({ name, pattern?, action?, replacement? })` (defaults to the secret-scan patterns, now exported as `SECRET_PATTERNS`), `denyTopicsGuardrail({ topics })` and `llmJudgeGuardrail({ model, instruction })`. The patch guardrails (`runGuardrails()`, `secretScanGuardrail`, ...) are unchanged; the new types are named `IoGuardrail*` because `Guardrail` and `GuardrailResult` are theirs. `spec.policy.guardrails` in agent spec files is not wired yet (LOU-X5). See docs/guardrails.md#input-and-output-guardrails.
+- Deployed `/chat` upgrade (LOU-D14): the `node-server` and `docker` targets (`dist/server.js`) now serve the `lousho dev` protocol: `POST /chat { sessionId, input }` streams the turn as SSE (`data: <AgentEvent JSON>`, then `event: done`) with history kept per session, `GET /chat/:sessionId`, `POST /chat/:sessionId/approvals/:id` (`{ approved, note? }` or `{ answer }`) and `GET /health`; the single-turn `POST /chat { message }` still works (now with a `Deprecation: true` header). The routes are one shared module, `src/server/chatRoutes.ts`, used by `lousho dev` and the deployed runtime. `LOUSHO_STORE` (`memory`, the default, or `sqlite:<path>`, Node >= 22) picks where sessions live. Bearer auth: set `LOUSHO_API_TOKEN` (or pass `{ auth: { token } }` as the new optional third argument of `adapter.scaffold()`; the variable wins) and every route except `/health` requires `Authorization: Bearer <token>` (constant-time compare, `401` JSON otherwise); treat it as required for anything not on localhost. The `docker` image is now based on `node:22-slim` (was `node:20-slim`) for `node:sqlite`. `specToAgent(spec, { store })` takes an optional `store`. The Cloudflare Worker target is unchanged (sessions over KV and SSE there are LOU-D51). See docs/deployment.md#http-api.
+- `lousho chat` (LOU-D33): a terminal REPL for an agent. `lousho chat <spec|dir|module> [--model provider/model] [--session id] [--store sqlite:<file>]` loads the target like `lousho dev` and reads one turn per line through `agent.session({ id, store }).stream()`: text deltas as they arrive, each tool call as a dim `[tool_name] {args}` line followed by `  -> result`, `Approve <tool>(args)? [y/N]` for a tool that needs approval, a numbered prompt with free text for an `ask_question` call, and `[usage]` tokens and cost after each turn. Slash commands: `/new`, `/model <provider/model>` (rebuilds the agent, the session continues), `/history`, `/quit`. SDK errors print with their `[LOUSHO_...]` code and fix. The loop is `runChatRepl({ input, output, createAgent })` in `src/cli/chatRepl.ts` (testable with scripted lines and a `mockModel` agent); `loadTarget()` is now exported from `src/cli/devReload.ts`. See docs/cli.md#lousho-chat.
+- Memory slots (LOU-W6): `defineMemory({ name, description?, scope, provider, recall?, expose? })` (new export) defines a named long-term memory, and `createAgent({ memory: [slot] })` wires it in. On the first model call of every run (`send()`, `stream()`, each session turn), a `preGenerate` hook recalls the slot's newest `recall.maxItems` (default 10) items into the system prompt as a `<memory name="...">` block (`recall.query: 'last-input'` passes the last user message as the provider query; `recall.onSessionStart: false` turns recall off). The model gets `remember_<name>({ text })` and `recall_<name>({ query?, limit? })` tools (`expose: { remember?, recall? }`, both on by default). `scope` is `'global'`, `'session'` (keyed by `agent.session({ id })`'s id or `send()`'s `sessionId`) or a function of `{ sessionId, metadata }`; the new `SendOptions.metadata` feeds it. Providers implement `MemoryProvider` (`list` / `add` / `remove`); built in are `inMemoryMemory()` and `fileMemory({ dir })` (one JSON file per scope key), both bounded by `maxItems` (default 1000, oldest dropped). See docs/memory.md.
+- Budgets (LOU-V6): `limits?: { maxTokens?, maxInputTokens?, maxOutputTokens?, maxCostUsd?, maxDurationMs?, maxSteps?, onExceeded? }` on `createAgent()` and `ExecuteOptions` (new type `RunLimits`). Limits are checked before every model call (so after every tool batch) and after a model call that asks for tools, and `maxDurationMs` aborts an in-flight model or tool call through the run's signal. A tripped limit ends the run with the new `finishReason: 'budget-exceeded'` and `result.budget: { limit, value, max, scope }` (`BudgetExceeded`); tool calls of that step get a cancelled result and the run is checkpointed as finished, like `'max-steps'`. `stream()` emits the new typed `budget.exceeded` event (`BudgetExceededEvent`) before `run.done` (additive, the event schema version stays 1). `onExceeded: 'throw'` rejects with the new `BudgetExceededError` (`LOUSHO_BUDGET_EXCEEDED`, no longer reserved) instead. `limits.maxSteps` is an alias of `maxSteps` (the stricter wins; alone it replaces the default of 10). Sub-agents' usage counts toward their lead's budget. `agent.session({ id, limits })` applies limits across a session's turns: what the turns spent is saved as `metadata.sessionUsage` on the transcript's last message (new types `BudgetSpent`, `SessionBudget`, `SessionTurnOptions`; `ExecuteOptions.sessionBudget` carries it to the run), so `maxCostUsd` per session holds across processes. See docs/configuration.md#budgets.
+- Stateful streaming dev chat (LOU-D32): `lousho dev` serves one session per browser tab. `POST /chat` with `{ sessionId, input }` streams the turn as SSE (`data: <AgentEvent JSON>` per event, then `event: done`) through `agent.session({ id, store }).stream(input)` over an in-process `memoryStore()` (or the agent's own `store`, when a module's `createAgent()` options or `overrides` set one); `GET /chat/:sessionId` returns the transcript and the pending approval; `POST /chat/:sessionId/approvals/:id` with `{ approved, note? }` or `{ answer }` decides an approval or answers a question and streams the continuation (rebuilt from the continued run's result, since `agent.approvals.resolve()` is not streamed). The chat page renders text deltas, tool calls with arguments and results, Approve / Reject and question buttons, errors and `run.done` usage and cost, with a "New session" button and the id kept in `sessionStorage`. Sessions survive a hot reload and continue on the new agent. The `{ message }` body of `POST /chat` still works and is deprecated (no session, JSON `ExecutionResult`, `Deprecation: true` header). See docs/cli.md#lousho-dev and docs/streaming.md.
+- Agent Forge History tab (LOU-D45.2): the bottom drawer's new **History** tab lists the loaded agent's run steps (step, status, finish reason, tool calls, tokens, cost). "Edit and replay from here" appends a user message or edits one of the step's tool results, forks the run at that step through `POST /runs/:id/fork`, and shows the fork next to the original as a side-by-side trajectory with the diverging turn and the drift entries highlighted, refreshed when the fork finishes. See docs/agent-forge.md#the-history-tab.
+- `lousho dev` for agent directories and TS agents, with hot reload (LOU-D31): `lousho 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 `LOUSHO_CONFIG_INVALID` / `LOUSHO_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#lousho-dev and docs/agent-directories.md#run-it-with-lousho-dev.
+- Multimodal input through the public API (LOU-V12): `agent.send()` / `agent.stream()`, `session.send()` / `stream()`, `t.send()` in evals and `useLoushoAgent().send()` take the new exported `AgentInput` (`string | ContentPart[] | Message[]`): a string or parts become one user message, a `Message[]` is passed through (in a session it is appended to the transcript). Checkpoints, `agent.resume()` and queued input hold the parts like any message. The React user bubble shows the text with an `[image]` / `[file]` marker per non-text part. `SqliteStore` sessions and checkpoints save `Uint8Array` parts as `{ "$bytes": "<base64>" }`, as `FileSessionStore` does. Finishes LOU-V11 (its note that `agent.send()` / `session.send()` take no parts is out of date). See docs/providers.md#multimodal-input.
+- Built-in `ask_question` tool (LOU-X9): `createAgent({ askQuestion: true })` (off by default) or `askQuestionTool()` gives the agent `ask_question({ question, options?, allowFreeText? })`. A call pauses the run through the approval mechanism, so it waits durably like any approval (sessions, `memoryStore()` / `SqliteStore`, a restart between question and answer). The pending record gains optional `kind: 'question'` and `question: { text, options?, allowFreeText? }` (new types `ApprovalKind`, `ApprovalQuestion`; `describeApproval()` and `ASK_QUESTION_TOOL_NAME` are exported), and so do the `approval.requested` event and the React hook's `pendingApproval`. The new `agent.approvals.answer({ id, answer })` (the same as `resolve({ id, approved: true, note: answer })`) continues the run with `{ answer, option? }` as the tool result (`option`: index of the matching option); `approved: false` gives the model a `kind: 'rejected'` error saying the user declined to answer. `useLoushoAgent()` gets `answer(text)`. The `approve` callback may now return a string (`ApproveToolCall` returns `boolean | string`), which approves with that note, so code can answer questions. A tool run after an approval sees the decision's note as `ctx.approval.note` (new optional `ToolExecutionContext.approval`). See docs/approvals.md "Asking the user a question".
+- Agent Forge time travel API (LOU-D45): Agent Forge's `FileCheckpointStore` keeps the bounded per-session checkpoint history (`history()`, `historyLimit` option, `delete({ keepHistory })`) with the same semantics as `LocalStorageCheckpointStore`, checked by the SDK's history contract suite. The runtime control server gains `GET /runs/:id/history` (each step's status, save time, finish reason, tool calls, tokens and cost), `POST /runs/:id/fork` (`{ fromStep, patch?: { toolResult?, appendInput?, businessState? } }`, forks with `AgentExecutor.fork()` and starts the fork as a run of its own) and `GET /runs/compare?a=&b=` (`compareTrajectories()`). Fixed on the way: Agent Forge's chat transcript compiles against multimodal `Message.content` (LOU-V11) again, keeping each message's text. See docs/agent-forge.md#time-travel.
+- 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 `LOUSHO_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 `lousho 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.
+- Compaction events and the `compaction` option (LOU-W3.2): `agent.stream()`, `session.stream()` and `AgentExecutor.stream()` emit two new typed events whenever the compaction hook compacts a request: `compaction.start` (`strategy`, `tokensBefore`, `contextWindow`, `thresholdTokens`) before the work and `compaction.done` (`strategy`, `tokensBefore`, `tokensAfter`, `prunedToolCallIds`, `summary?`, `error?: { message }`) after it, inside the step and before the model call; `error` is set when the strategy failed and the hook fell back. Additive: the event schema version stays 1. `GenerateHookContext` gains the optional `emit(event)` (set in streamed runs only) that the hook uses. `createAgent({ compaction })` takes `true` (the prune hook with its defaults) or `{ strategy?, thresholdPercent?, contextWindow?, protectedTokens?, summarizer? }`, where `summarizer` (a `'provider/model'` string or an `LLMProvider`) selects `twoPhaseStrategy()` with that model; `summarizer` together with `strategy` is a `ConfigurationError`. `createAgent({ hooks })` (new) takes any `AgentHook[]`, run before the compaction hook. See docs/compaction.md.
+- Connect MCP servers from config (LOU-Z4): `connectMcp(servers, { lazy?, onError?, logger? })` (`@lousho/build-ai-agent/mcp` and the root) connects stdio (`command`/`args`/`env`) and streamable HTTP (`url`/`headers`) servers, lists their tools as `<server>__<tool>` descriptors and returns `{ tools, close(), status() }`. Every server connects up front (listing tools needs a connection); `lazy` (default `true`) reconnects on the next tool call after `close()` or a dropped connection. `onError: 'skip'` leaves a failing server out with a warning instead of rejecting. `createAgent({ mcpServers })` connects them on the new `agent.ready()` or the first `send()` / `stream()` and adds their tools; the new `agent.close()` disconnects them (both are no-ops without `mcpServers`). `specToAgent()` now connects `spec.mcpServers` the same way (closes TODO(LOU-D20.2)); `agent.mcpServers` still lists them. `loadMcpTools()` accepts any `{ listTools, callTool }` (`McpClientLike`). See docs/configuration.md#connect-mcp-servers-mcpservers-connectmcp.
+- Error codes with fixes (LOU-D2): every `SDKError` now has a stable `code` (`LOUSHO_<AREA>_<NAME>`, e.g. `LOUSHO_CONFIG_MISSING_PROVIDER`, `LOUSHO_PEER_MISSING`, `LOUSHO_SPEC_INVALID`, `LOUSHO_SESSION_AWAITING_APPROVAL`), a one-sentence `hint` and a `docs` link to its section of the new docs/errors.md; its message ends with a `[code] hint (docs)` line (`detail` is the message without it), and `toString()` always shows it. `ERROR_CODES` / `ErrorCode` (new exports) are the registry, and a test keeps it, the codes used in `src/` and docs/errors.md in sync. The plain `Error`s thrown by `createAgent()` (no model, `instructions` + `prompt`, `sessionId` without checkpoints), `resolveProvider()` (bad spec, unknown prefix, missing API key, missing peer), `AgentExecutor.execute()` / `stream()` (missing `provider` / `agent` / `input`, approval with no `approvalStore`), `resumeAfterApproval()` (unknown approval), sessions (invalid id, corrupt file, second iteration, no stream runner), `loadSpec()` and `specToAgent()` are now `ConfigurationError` / `ValidationError` / `SDKError` with codes; `MissingPeerDependencyError` extends `SDKError`. Existing message text is unchanged (the help line is appended). `loadSpec()` suggests the field a top-level typo meant (`unknown field 'promt' (did you mean 'prompt'?)`). See docs/errors.md.
+- Checkpoint history (LOU-D43): `memoryStore()`, `SqliteStore` and `LocalStorageCheckpointStore` keep a bounded history per session: every `save()` also appends the record to a ring (`historyLimit` option, default 50, `0` keeps none; the oldest are dropped), and the new optional `CheckpointStore.history(sessionId, { limit? })` returns `{ step, savedAt, status, checkpoint }` entries newest first. `CheckpointStore.delete(sessionId, { keepHistory: true })` keeps the history (by default `delete()` clears it too), `getCheckpointHistory(store, sessionId)` reads it and returns `undefined` for a store without `history()`, and `SqliteStore` gains the `checkpoint_history` table (added when an existing database file is opened; `prune()` removes old entries). New types `CheckpointHistoryEntry`, `CheckpointHistoryOptions`, `CheckpointDeleteOptions` and `MemoryStoreOptions`. `KVCheckpointStore` and Agent Forge's file store keep no history yet (LOU-D43.2). This is the first step of time-travel from a past step. See docs/durable-execution.md#checkpoint-history.
+- `lousho eval --record / --replay / --drift` (LOU-D46): `--record` runs every eval case against its agent's real provider through `recordReplay()` and writes one cassette per case next to the eval file (`__cassettes__/<eval-name>/<case>.json`, the normal cassette format); `--replay` runs every case from its cassette with no network, and a missing cassette fails the case with the `--record` command to run. Plain `lousho eval` with `CI` set replays the cases that have a cassette; without `CI` it is unchanged. `--drift` re-records into a temp directory and compares each case with its committed cassette (ordered tool names, JSON-normalized tool arguments, step count, finish reason; tokens with `--drift-usage`): the summary gets a `Drift:` table and each drifted case a soft `drift` assertion (a JUnit `<system-out>` note), or a gate failure with `--strict`. Existing eval files need no change: while a case runs, `AgentExecutor.execute()` wraps its provider for that case. `EvalResult` gains `cassettes`. Fixed on the way: trajectory and classic eval results now carry their `file` (it was read before the test ran and was always empty). See docs/evals.md#record-replay-and-drift.
+- OpenTelemetry GenAI metrics and cost (LOU-D48): `createOtelTraceExporter()` (`@lousho/build-ai-agent/otel`) now also records the GenAI client metrics `gen_ai.client.token.usage` (histogram, `{token}`, one record per `gen_ai.token.type` `input`/`output`) and `gen_ai.client.operation.duration` (histogram, `s`, for every model call and tool call) through `@opentelemetry/api`'s metrics API: the global `MeterProvider`, or the new `meter` option; `metrics: false` turns them off. Without a registered `MeterProvider` they are discarded by OpenTelemetry's no-op meter. Spans gain `lousho.cost_usd` (estimated USD: per step on `chat` spans, cumulative on `invoke_agent` spans, absent when the price table does not know a model) and `lousho.usage.estimated` on `invoke_agent` spans (it was already on `chat` spans). Any `TraceExporter` sees the cumulative attributes: `withSpan()` sums the cost of finished child spans onto their parent. See docs/observability.md.
+- One `store` option (LOU-D30): `createAgent({ store })` takes an `AgentStore` (`{ sessions?, checkpoints?, approvals? }`, new export) and wires all three from it. `SqliteStore` is one; the new `memoryStore()` returns in-memory sessions, checkpoints and approvals, and docs/sessions.md shows the file-based combination (`FileSessionStore`, `LocalStorageCheckpointStore`, `StorageServiceApprovalStore`). `agent.session({ id })` then keeps its transcript in `store.sessions` and checkpoints every turn in `store.checkpoints`; `store.approvals` is the default `approvalStore`. `SendOptions.sessionId` makes `send()` / `stream()` a durable run checkpointed in `store.checkpoints` (an error without one), so a one-shot durable job needs no `AgentExecutor`, and `agent.approvals.resolve()` keeps checkpointing it. The new `agent.resume(sessionId)` finishes an interrupted `send(..., { sessionId })` run, or else the session's pending turn (as `session.resume()`), and returns `null` when nothing is pending. A session's own `store` / `checkpointStore` and an explicit `approvalStore` still win, part by part. Without `store`, nothing changes.
+- One tool-error shape (LOU-U14): every failed tool call reaches the model as `{ error, toolName, message, kind }` (message capped at 2,000 characters, transcript message flagged `isError`), whichever path failed: `kind` is `'execution'`, `'validation'` (plus `issues`), `'not-found'`, `'rejected'` (plus `note`), `'not-run'`, `'mcp'` or `'sandbox'`. New exports `toolErrorResult()`, `ToolErrorResult`, `ToolErrorKind` and `ToolErrorInput`; `McpToolError` and the sandbox guard's error (named `SandboxRequiredError`, not exported) carry a `toolErrorKind`. `kind` is additive on thrown-error and validation results. The paths that built their own shapes changed, see Changed. See docs/tools.md.
+- Background sub-agents end with the lead run (LOU-Y4.2): when a run ends (any `finishReason`, or an error), its background sub-agents still queued or running are cancelled, and the run resolves once their runs have stopped, so none of their events reaches `onEvent` afterwards. `withSubagentOptions(subagents, { awaitBackgroundOnFinish: true })` waits for them instead (an aborted or failed lead still cancels them). The new `result.backgroundTasks` lists the run's background tasks as `{ taskId, agent, status, elapsedMs, ... }` (absent when it started none). `createAgent({ subagentOptions: { maxConcurrent, awaitBackgroundOnFinish } })` sets the same options (over any attached with `withSubagentOptions()`, without changing the `subagents` value). The executor hook behind it is public: `ExecuteOptions.onRunEnd({ result } | { error })` is called exactly once per `execute()` / `stream()` run, however it ends; an error it throws rejects the run. See docs/sub-agents.md.
+- Durable sessions (LOU-W9): `agent.session({ id, store, checkpointStore })` (or a `store` that carries both, `{ sessions, checkpoints }`, such as a `SqliteStore`) runs each turn with `sessionId: '<id>.turn-<n>'` and that `CheckpointStore`, so it is checkpointed after every model response and tool result. `session.resume()` finishes a turn interrupted by a crash, a failed checkpoint write or a `PropagatingToolError` (also in a new process) without re-running recorded tool calls or model responses, adds it to the transcript as `send()` would and returns its result (`null` when nothing is pending); `session.pending()` reports an unfinished turn and `session.discardPending()` drops it. `send()` / `stream()` resume a pending turn before sending the new message. A turn paused for approval stays in its checkpoint until it finishes: `resume()` / `send()` throw `SessionAwaitingApprovalError`, and `agent.approvals.resolve()` continues it in the session. Sessions without a checkpoint store are unchanged. See docs/sessions.md.
+- Structured output (LOU-V4): `createAgent({ output: zodSchema })` (and `ExecuteOptions.output`) makes the final reply a JSON object validated by the schema. `send()`, `run.result` and `agent.approvals.resolve()` resolve with it as `result.object`, typed `z.output<typeof schema>` from `send()` and `stream()` of `createAgent()` agents (`SimpleAgent`, `AgentRun` and `ExecutionResult` gain a type parameter that defaults to `unknown`); `result.text` keeps the raw JSON. The system prompt gets an `## Output format` section with the schema as JSON Schema, and each model call carries the new `GenerateOptions.responseFormat: { type: 'json', schema? }` hint, which the `ai`-SDK providers map to `experimental_output` JSON mode. The reply is parsed (a code fence is tolerated) and validated; when invalid, one repair step sends the model the issues (it counts against `maxSteps`), and a reply still invalid ends the run with the new `finishReason: 'output-invalid'`, no `object` and `outputError: { message, issues }`. `run.done` gains an optional `object` field (additive: the event schema version stays 1). See docs/structured-output.md.
+- Background sub-agents (LOU-Y4): the `task` tool takes `background: true`, which starts the sub-agent and returns `{ taskId, status: 'running', agent }` at once. Agents with `subagents` also get `agent_status({ taskId? })` (`queued`/`running`/`done`/`failed`/`cancelled`/`awaiting-approval`, plus `elapsedMs`), `agent_await({ taskId | taskIds, timeoutMs? })` (the synchronous `task` result, or `status: 'timeout'`) and `agent_cancel({ taskId })`. `withSubagentOptions(subagents, { maxConcurrent })` bounds how many run at once per lead run (default 3; the rest queue). Background sub-agents inherit the lead run's runtime and `maxSubagentDepth`, and aborting the lead cancels them. Not yet: resuming one that paused for approval (it reports `awaiting-approval` with its `approvalId`). A user tool named `agent_status`, `agent_await` or `agent_cancel` now conflicts with `subagents`, like `task`. See docs/sub-agents.md.
+- React hook (LOU-D15): new `@lousho/build-ai-agent/react` subpath with `useLoushoAgent(source, options?)`. `source` is `{ agent, sessionId? }` (in process, via `agent.stream()` or `agent.session({ id }).stream()`) or `{ url, headers?, fetch? }` (POSTs `{ input }` and reads the SSE or NDJSON event stream). It returns `messages` (text and tool calls with status, args and result), `status` (`idle`/`streaming`/`awaiting-approval`/`error`), `pendingApproval`, `error`, `usage`, `lastEvent`, `send()`, `stop()` (aborts; unmount aborts too), `approve(note?)` and `reject(note?)` (via `agent.approvals.resolve()` in process, or `POST ${approvalsUrl}/${id}` remotely). The framework-neutral `reduceAgentEvents()` reducer and `parseEventStream()` parser are exported from the same subpath. `react` (`^18 || ^19`) is an optional peer dependency. See docs/react.md.
+- Summarizing compaction (LOU-W3): `summarizeStrategy({ model, protectedTokens?, prompt?, maxSummaryTokens? })` replaces the turns before the protected tail with one `[Conversation summary]` user message written by `model` (an `LLMProvider` or a `"provider/model"` spec), keeping system and pinned messages and each assistant turn together with its tool results; if the summary call fails it falls back to pruning and reports `error`. `twoPhaseStrategy()` (the recommended strategy) prunes first and summarizes only when still above the threshold. `pinMessage()` / `isPinned()` and the new optional `Message.metadata` (never sent to providers) mark messages no built-in strategy compacts. `CompactionStrategy.compact()` may now be async, so `compactMessages()` returns a Promise; `CompactionResult` / `CompactionInfo` gain `summary` and `error`, and `CompactionInput` gains `thresholdTokens` and `signal`. A strategy that throws no longer fails the run: the hook reports the `error` to `onCompaction`. See docs/compaction.md.
+- `createAgent({ retry, fallbackModels })` (LOU-V7.2): `retry` (`withRetry()` options, or `false`) retries failed model calls and defaults to `{ maxRetries: 2 }` for models given as `provider/model` strings (or picked from the environment); a `provider` instance is wrapped only when `retry` is set. `fallbackModels` are `provider/model` strings tried in order once the primary model's retries are used up (`withFallback([withRetry(primary), withRetry(fallback), ...])`). `agent.stream()`, `session.stream()` and `AgentExecutor.stream()` report them as two new typed events, `provider.retry` (`attempt`, `maxRetries`, `delayMs`, `error: { message, category? }`, `provider`) and `provider.fallback` (`from`, `to`, `error: { message }`), for any `withRetry()` / `withFallback()` provider. Additive: the event schema version stays 1.
+- Context compaction (LOU-W2): `createCompactionHook()` returns an `AgentHook` that, before a model call estimated above `thresholdPercent` (default 0.9) of the model's context window, replaces tool results older than the newest `protectedTokens` (default 40,000) with a `[pruned: <tool> result, N chars]` marker, in the run's transcript itself. `compactMessages()` compacts a conversation by hand; `CompactionStrategy` / `pruneToolResultsStrategy()` make the strategy pluggable. See docs/compaction.md.
+- `AgentSpec.mcpServers` (LOU-D20): a validated map of MCP servers (stdio `command`/`args`/`env` or HTTP `url`/`headers`) in agent spec files. `loadSpec()` reports a bad entry with its name, `lousho doctor` reads the validated field instead of the raw file, and `specToAgent()` exposes the parsed servers as `agent.mcpServers` (connecting them is TODO(LOU-D20.2)). Existing specs are unaffected.
+- `createAgent()` agents can pause for approval (LOU-D21): a `needsApproval` tool no longer fails the run with "requires approval but no approvalStore". The run pauses (`finishReason: 'awaiting-approval'`) in a per-agent `InMemoryApprovalStore` (or the new `approvalStore` option), and `agent.approvals.list()` / `agent.approvals.resolve({ id, approved, note? })` continue it, in its session if it paused in one. The `approve` option decides calls in code without pausing.
+- Tools own their contract (LOU-D22): `ToolDescriptor` gains optional `inputSchema` (zod) and `execute(args, ctx)`, which are now the canonical fields. `defineTool()` sets both and no longer calls `ai`'s `tool()`. Argument validation, the schema sent to the model, and tool execution read them first and fall back to `tool.parameters` / `tool.execute`. `ToolDescriptor.tool` (the `ai` v4 `Tool`) is now legacy: it is still built by `defineTool()` and still accepted on hand-written descriptors this release, but new code should set `inputSchema` and `execute`.
+- ✅ Complete Phase 5 migration: Security, Storage, Templates, and Utils modules
+- ✅ Security module with encryption, hashing, and quota validation
+- ✅ Storage service with file locking mechanism
+- ✅ Template rendering engine with Jinja2-like syntax
+- ✅ Comprehensive utility functions (errors, formatters, validators)
+- ✅ File extraction and processing utilities
+- ✅ JSON path navigation utilities
+- ✅ Framework-agnostic architecture (zero framework dependencies)
+
+### Fixed
+- `lousho --help`, `-h` and `help` print the usage and exit 0 (they were "unknown command" with exit 1) (LOU-D49).
+- Install truth (LOU-U20): the README, installation, CLI, quick start and Agent Forge docs, `lousho init --help` and the message after a failed `lousho init` install now say the package is not on npm yet and point to one section, "Installing before the first release" (docs/installation.md); `npm install github:LinuxDevil/agent-sdk` is documented as not working. Stale "planned / not yet" statements about agent-directory channels, `toolCallId` in sandboxed tools and the Agent Forge Settings tab are corrected.
+- On `ai` 5+ the providers send images as `file` parts with an image `mediaType` (`image/*` when unknown) instead of the deprecated `image` part, which made `ai` 7 log a deprecation warning for every image. `ai` 4 still gets `image` parts.
+- OpenRouter on `@ai-sdk/openai` 2+, and the Ollama base URL (LOU-D28f, behaviour fix): `OpenRouterProvider` now builds its model with `provider.chat(modelId)` (Chat Completions, the only API OpenRouter implements) instead of the bare call, which targets the Responses API from `@ai-sdk/openai` 2 on; no change on `ai` 4. `OllamaProvider` appends `/api` to a base URL that has no path (`http://host:11434` or `http://host:11434/`), the form `ollama-ai-provider` and `ollama-ai-provider-v2` expect, so a configured bare host no longer hits `/chat` outside `/api` (before, `getModels()` hit `<baseURL>/api/tags` but chat requests went to `<baseURL>/chat`); a URL ending in `/api` or with any other path is used as it is, and `getModels()` no longer doubles `/api` for a base URL that has it. `lousho init` (and `create-lousho-agent`) now scaffolds OpenRouter projects on `ai@^7.0.0` with `@ai-sdk/openai@^4.0.0`.
+
+### Deprecated
+- `ExecuteOptions.onEvent`, `ExecutionEvent` and `ExecutionEventType` (LOU-D41). `onEvent` keeps working: the executor now emits only `AgentEvent`s, and an adapter derives the old events from them in the old order (`start`, `text-complete`, `tool-call`, `tool-result`, `error`, `abort`, `finish`, sub-agents' tagged with `subagent`), with a one-time `console.warn`. Differences: `finish` now comes after the run's checkpoint is written (it was just before), and a run that fails outside a step (an input guardrail that throws, `onRunEnd` throwing) now gets an `error` event too. Migration: replace `onEvent` with `onAgentEvent` (or `createAgent({ onEvent })`); `start` -> `run.start`, `text-complete` -> `text.done` (step usage on `step.done`), `tool-call` -> `tool.start`, `tool-result` -> `tool.done` / `tool.error`, `abort` / `finish` -> `run.done` (`finishReason`), `error` -> `error` (`{ name, message }`). The full table is in docs/streaming.md#migrating-from-onevent--executionevent.
+
+### Removed
+- `ExecuteOptions.streaming` (LOU-D41): it was never read. Use `AgentExecutor.stream()` / `agent.stream()` to stream a run. Passing it in an object literal is now a type error; remove the property.
+- `ToolDescriptor.injectStreamingController` and `defineTool({ injectStreamingController })` (LOU-D41.2, deprecated earlier in this release): no SDK path ever called it, so removing the property changes nothing at runtime. Passing it is now a type error; remove the property.
+- `AgentExecutionOptions.streaming` (LOU-D41.2): it was never read (`AgentExecutionOptions` is a legacy type no SDK API takes). Remove the property; stream a run with `agent.stream()` / `AgentExecutor.stream()`.
+- BREAKING: `validateTokenQuotas()` (`src/security/quotas.ts`) and the SaaS-era types `SaaSContext`, `QuotaConfig`, `UsageStats` and `QuotaValidationResult` (LOU-D36) no longer ship from the package root. Nothing in the SDK called them. No replacement; copy the file into your project if you relied on it.
+- BREAKING: `ConfigManager` and `SDKConfig` (`src/core/ConfigManager.ts`) (LOU-D36) no longer ship from the package root or `./core` (which still exports `AgentBuilder`). Nothing in the SDK used them. No replacement; copy the file into your project if you relied on it.
+- BREAKING: The formatters (LOU-D36) `getCurrentTS()`, `getTS()`, `formatDate()`, `safeJsonParse()`, `removeCodeBlocks()`, `findCodeBlocks()`, `checkApiKey()` and the types `CodeBlock`, `CodeBlockError`, `CodeBlockResult` (`src/utils/formatters.ts`) no longer ship from the package root. No replacement; copy the file into your project if you relied on it.
+- BREAKING: The JSON path helpers `getObjectByPath()` and `setRecursiveNames()` (`src/utils/json-path.ts`) (LOU-D36) no longer ship from the package root. No replacement; copy the file into your project if you relied on it.
+- BREAKING: The file extraction helpers `getMimeType()`, `getFileExtensionFromMimeType()`, `replaceBase64Content()`, `isBinaryData()`, `extractBase64Data()`, `createDataUri()` and `ProcessFilesParams` (`src/utils/file-extractor.ts`) (LOU-D36) no longer ship from the package root. No replacement; copy the file into your project if you relied on it.
+- BREAKING: The flows-ai converters (LOU-D35) are gone: `convertToFlowDefinition()` and `convertFromFlowDefinition()` (`src/flows/converters.ts`) no longer ship from the package root or `./flows`. There is no replacement: the flows-ai engine they targeted was never a dependency of this package and `FlowExecutor` never used them. Run flows with `FlowExecutor` directly.
+- BREAKING: `MemoryManager` and its types `MemoryManagerConfig`, `StoreMemoryOptions`, `RecallMemoryOptions` and `MemorySearchResult` (`src/execution/MemoryManager.ts`) (LOU-D38) no longer ship from the package root. Nothing in the SDK used them (`AgentExecutor`, `createAgent`, `resume` and the flows never called them; only their own test and the `execution/index.ts` re-export). Migrate to `defineMemory()` and `createAgent({ memory })` (memory slots, see docs/memory.md).
+- BREAKING: `ContextBuilder`, `ContextBuilderOptions` and `ExecutionContext` (`src/execution/ContextBuilder.ts`) (LOU-D38) no longer ship from the package root. Nothing in the SDK used them; they truncated by message count only. Migrate to `createAgent({ compaction })` (token-aware compaction, see docs/compaction.md).
+- BREAKING: The `retry()` family (`retry`, `retryOnError`, `retryWithTimeout`, `retryBatch`, `RetryableOperation`, `RetryOptions`, `RetryResult`; `src/execution/retry.ts`) (LOU-D38) no longer ships from the package root. Provider calls retry through the provider wrappers; nothing else in the SDK used it. Migrate to `createAgent({ retry, fallbackModels })`, or copy the file into your project for general-purpose retries.
+- BREAKING: The `data/` module (LOU-D39) is gone: the classes `Agent`, `Session`, `Result`, `Memory`, `Attachment` and the repository interfaces `BaseRepository`, `AgentRepository`, `SessionRepository`, `ResultRepository`, `MemoryRepository`, `AttachmentRepository`, `RepositoryCollection`, `RepositoryFactory`, `PaginationOptions`, `PaginatedResult` no longer ship from the package root. They were donor-product data tables that nothing in the SDK used once `MemoryManager` was removed. No replacement: unused. Use `AgentConfig`, sessions (`agent.session()`) and `defineMemory()` for the SDK's own concepts.
+- BREAKING: `@lousho/build-ai-agent/testing` exports test utilities only (LOU-D39). The in-memory repository mocks `MockAgentRepository`, `MockSessionRepository`, `MockResultRepository`, `MockMemoryRepository` and `MockAttachmentRepository` are removed with the `data/` module. No replacement: unused. `mockModel` and `recordReplay` are unchanged.
+- BREAKING: The template engine (`TemplateManager`, `renderTemplate()` and the types `TemplateFilter`, `TemplateContext`, `TemplateOptions`, `ITemplateManager`; `src/templates`) (LOU-D37) no longer ships from the package root. Nothing in the SDK, `lousho init` or Agent Forge used it (the executor never rendered prompts through it; the scaffold templates are separate files under `src/cli/init`). No replacement: unused; use a template literal or your own renderer.
+- `nanoid` is no longer a dependency (LOU-D35). Generated ids (agent, run, trace, memory ids) now come from `globalThis.crypto.randomUUID()` via an internal `newId()`, so they are UUIDs instead of 21-character nanoids. Nothing public depended on the old format.
+- `finishReason: 'max-steps'` (LOU-U19): a run that exhausts `maxSteps` while the model still wanted to continue (last turn ended in tool calls) now resolves with `finishReason: 'max-steps'` instead of the stale last-turn reason (usually `'tool_calls'`), on `ExecutionResult`, the `finish` event and `run.done`. Resumed runs count `initialSteps` toward the budget. A run that finishes naturally within the budget is unchanged. Code that treated `'tool_calls'` as "hit maxSteps" should check `'max-steps'` instead (the eval `completed()` message and the MCP server's agent tool do).
+
+### Docs
+- README revamped into a short front page (LOU-D52); the details it dropped moved to `docs/` (new pages: tools, approvals, providers, cli, flows, guardrails, utilities).
+
+### Renamed
+- The project is now **lousho** (it was `loushy`), before the first npm release, so nothing was ever published under the old name. Everything that carried the name changed with it, and this changelog uses the new names throughout, including in older entries: the package `@lousho/build-ai-agent` (was `@loushy/build-ai-agent`), the `@linuxdevil/lousho` CLI (was `loushy`), `create-lousho-agent` (was `create-loushy-agent`), the exports `useLoushoAgent`, `loushoAgent`, `LoushoAgentSource`, `LoushoUIMessageChunk` and the other `Lousho*` types, every `LOUSHO_*` error code and environment variable (`LOUSHO_MODEL`, `LOUSHO_API_TOKEN`, `LOUSHO_STORE`, ...), the `.lousho/` directory, the `lousho.*` span attributes and the `data-lousho-approval` stream part. Migration for a checkout that used the old name: replace `loushy` with `@linuxdevil/lousho` (keeping the case) in imports, scripts, environment variables and config, and rename an existing `.loushy/` directory to `.lousho/`.
+
+### Published
+- `@lousho/build-ai-agent` and `create-lousho-agent` are on npm. The README and the installation, quick start, CLI and Agent Forge docs no longer say the package is unpublished; "Installing before the first release" is now "Installing from a local build" (docs/installation.md#installing-from-a-local-build) and covers trying an unreleased commit. The hint printed after a failed `lousho init` install no longer mentions a 404; it points to `--sdk-path`. The docs site moved to https://lousho.com.
diff --git a/README.md b/README.md
index 58a5231cf..58789f75a 100644
--- a/README.md
+++ b/README.md
@@ -8,11 +8,11 @@
 
 # Lousho — TypeScript AI agent SDK
 
-[![npm](https://img.shields.io/npm/v/lousho)](https://www.npmjs.com/package/lousho)
+[![npm](https://img.shields.io/npm/v/@linuxdevil/lousho)](https://www.npmjs.com/package/@linuxdevil/lousho)
 ![CI](https://github.com/LinuxDevil/lousho/actions/workflows/ci.yml/badge.svg?branch=main)
 [![Docs](https://img.shields.io/badge/docs-lousho.com-0F9D74)](https://lousho.com)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Node](https://img.shields.io/node/v/lousho)](https://www.npmjs.com/package/lousho)
+[![Node](https://img.shields.io/node/v/@linuxdevil/lousho)](https://www.npmjs.com/package/@linuxdevil/lousho)
 [![GitHub stars](https://img.shields.io/github/stars/LinuxDevil/lousho)](https://github.com/LinuxDevil/lousho)
 
 </div>
@@ -23,11 +23,11 @@ TypeScript AI agents you can test in CI, pause for approval, and resume after a
   <a href="https://lousho.com/agent-forge">
     <picture>
       <source media="(prefers-color-scheme: dark)" srcset="docs/images/studio-trace-dark.png">
-      <img alt="Agent Forge, the local studio, showing one agent run as a trace" src="docs/images/studio-trace.png" width="560">
+      <img alt="Lousho Studio, the local studio, showing one agent run as a trace" src="docs/images/studio-trace.png" width="560">
     </picture>
   </a>
   <br>
-  <sub>Agent Forge, the local studio. Open it with <code>npx lousho studio</code>.</sub>
+  <sub>Lousho Studio, the local studio. Open it with <code>npx @linuxdevil/studio</code> (a separate install).</sub>
 </div>
 
 ![Lousho demo: scaffold a project, replay an eval offline, change the prompt, and see the replay flag it](.github/assets/demo.gif)
@@ -37,7 +37,7 @@ TypeScript AI agents you can test in CI, pause for approval, and resume after a
 - **Test agents in CI without an API key.** `lousho eval` records a real run once, replays it with no network, and reports when the tool-call trajectory drifts. [Evals](https://lousho.com/evals)
 - **Resume after a crash.** Give the agent a store and `agent.resume()` finishes an interrupted run. Tool calls that already have a result do not run again. [Durable execution](https://lousho.com/durable-execution)
 - **Pause for a human.** A tool marked `needsApproval` pauses the run. Another request, or with a durable store another process, can approve it later, and the run continues where it stopped. [Approvals](https://lousho.com/approvals)
-- **Runs in your own Node process.** There is no hosted runtime. `lousho build` targets a Node server, Docker or Cloudflare Workers, and `lousho studio` runs on your machine. [Deployment](https://lousho.com/deployment)
+- **Runs in your own Node process.** There is no hosted runtime. `lousho build` targets a Node server, Docker or Cloudflare Workers, and Lousho Studio (`@linuxdevil/studio`, a separate install) runs on your machine. [Deployment](https://lousho.com/deployment)
 - **Works with the Vercel AI SDK.** `fromAiSdk()` and `fromAiSdkTools()` wrap AI SDK models and tools, so you can move over one piece at a time. [Migrating from the AI SDK](https://lousho.com/migrating-from-ai-sdk)
 
 ## Try it in 60 seconds, no API key
@@ -55,8 +55,8 @@ npm test
 Now add an eval. Save this as `src/weather.eval.ts`:
 
 ```ts no-run
-import { createAgent, defineEval, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineEval, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const getWeather = defineTool({
@@ -89,7 +89,7 @@ defineEval({
 Then run it:
 
 ```bash
-npx lousho eval
+npx @linuxdevil/lousho eval
 ```
 
 ```text
@@ -102,9 +102,9 @@ weather advice  -     PASS    -       14ms
 To test against a real model, use `model: 'openai/gpt-4.1-mini'` in place of `provider`, set your key and record once. This step needs the key. Commit the cassettes it writes. CI then replays them with no network and no key:
 
 ```bash
-npx lousho eval --record
-npx lousho eval --replay
-npx lousho eval --drift
+npx @linuxdevil/lousho eval --record
+npx @linuxdevil/lousho eval --replay
+npx @linuxdevil/lousho eval --drift
 ```
 
 `--drift` re-records each case and shows where the tool calls, arguments or step count changed. See [Record, replay and drift](https://lousho.com/evals#record-replay-and-drift).
@@ -128,17 +128,17 @@ Requires Node.js 22.19 or newer. To start a new project, see [Try it](#try-it-in
 To add Lousho to an existing project:
 
 ```bash
-npm install lousho ai@^7.0.0 zod @ai-sdk/openai@^4.0.0
+npm install @linuxdevil/lousho ai@^7.0.0 zod @ai-sdk/openai@^4.0.0
 ```
 
-See [Installation](https://lousho.com/installation#provider-packages) for other providers. `npx lousho doctor` checks your setup and prints a fix for anything missing.
+See [Installation](https://lousho.com/installation#provider-packages) for other providers. `npx @linuxdevil/lousho doctor` checks your setup and prints a fix for anything missing.
 
 ## Quickstart
 
 This file uses top-level `await`, so it must be an ES module (`.mts`, or `"type": "module"` in `package.json`). Set `OPENAI_API_KEY` to run it.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const getWeather = defineTool({
@@ -160,7 +160,7 @@ console.log(text);
 
 ### Agent folders
 
-An agent can also be a folder, which you run with `npx lousho dev ./my-agent`:
+An agent can also be a folder, which you run with `npx @linuxdevil/lousho dev ./my-agent`:
 
 ```text
 my-agent/
@@ -178,9 +178,9 @@ Loading a folder runs its code, so only load ones you trust. See [Agent director
 - **Multi-agent**: [sub-agents](https://lousho.com/sub-agents) that run in parallel, and [handoffs](https://lousho.com/handoffs) to specialists.
 - **UI**: bindings for [React](https://lousho.com/react), [Vue](https://lousho.com/vue) and [Svelte](https://lousho.com/svelte), plus [AI SDK `useChat`](https://lousho.com/ai-sdk-ui) and [Next.js routes](https://lousho.com/nextjs).
 - **Tracing**: OpenTelemetry GenAI spans and a local trace viewer. [Observability](https://lousho.com/observability)
-- **Agent Forge**: `lousho studio` opens a local visual canvas, run debugger and chat. [Agent Forge](https://lousho.com/agent-forge)
+- **Lousho Studio**: a separate install (`npx @linuxdevil/studio`) opens a local visual canvas, run debugger and chat across all your projects. [Lousho Studio](https://lousho.com/agent-forge)
 - **Self-healing (experimental)**: `lousho improve` turns an agent's failed runs into tested edits to its instructions and skills, applies one that passes (or queues it for a person), and rolls it back on a regression. [Self-healing](docs/self-healing.md)
-- **Workspaces (experimental)**: `lousho/workspaces` holds the contracts for a workspace of pages, harnesses and shared policy: schemas, validation, harness composition and typed authoring operations. [Workspaces](docs/workspaces.md)
+- **Workspaces (experimental)**: `@linuxdevil/lousho/workspaces` holds the contracts for a workspace of pages, harnesses and shared policy: schemas, validation, harness composition and typed authoring operations. [Workspaces](docs/workspaces.md)
 - **Coding agents**: workspace tools, permission rules and starter kits from `lousho add`. [Build a coding agent](https://lousho.com/build-a-coding-agent)
 
 ## Documentation
diff --git a/api/auth.api.md b/api/auth.api.md
index 6f180cee0..af597439d 100644
--- a/api/auth.api.md
+++ b/api/auth.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/executor.api.md b/api/executor.api.md
index 44cab4d9c..25e2412c4 100644
--- a/api/executor.api.md
+++ b/api/executor.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/flows.api.md b/api/flows.api.md
index ab6664d6b..57a5ca7a4 100644
--- a/api/flows.api.md
+++ b/api/flows.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/goals.api.md b/api/goals.api.md
index da19c1f90..ee2c3884d 100644
--- a/api/goals.api.md
+++ b/api/goals.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/hooks.api.md b/api/hooks.api.md
index 5e6146d6c..9b0ba4138 100644
--- a/api/hooks.api.md
+++ b/api/hooks.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/improve.api.md b/api/improve.api.md
index a6b5dbe10..f66bf32a5 100644
--- a/api/improve.api.md
+++ b/api/improve.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/index.api.md b/api/index.api.md
index 030a73861..167a4ca75 100644
--- a/api/index.api.md
+++ b/api/index.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/integrations.api.md b/api/integrations.api.md
index a3feca042..bf30135e4 100644
--- a/api/integrations.api.md
+++ b/api/integrations.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/kv.api.md b/api/kv.api.md
index a7ec21753..de19a692e 100644
--- a/api/kv.api.md
+++ b/api/kv.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/mcp.api.md b/api/mcp.api.md
index 18792b86e..6dbc96985 100644
--- a/api/mcp.api.md
+++ b/api/mcp.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/observe.api.md b/api/observe.api.md
index 5637206d7..2e8fcbed7 100644
--- a/api/observe.api.md
+++ b/api/observe.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/otel.api.md b/api/otel.api.md
index 54669478c..752e96d11 100644
--- a/api/otel.api.md
+++ b/api/otel.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/react.api.md b/api/react.api.md
index b130de141..ba9bc1d16 100644
--- a/api/react.api.md
+++ b/api/react.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/spec.api.md b/api/spec.api.md
index 72d87393a..b5c56dda7 100644
--- a/api/spec.api.md
+++ b/api/spec.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/sqlite.api.md b/api/sqlite.api.md
index 31c7cee08..57dbf154c 100644
--- a/api/sqlite.api.md
+++ b/api/sqlite.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/svelte.api.md b/api/svelte.api.md
index 84c7ab500..d3e1a4df2 100644
--- a/api/svelte.api.md
+++ b/api/svelte.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/testing.api.md b/api/testing.api.md
index ecd855c9f..e7c7308df 100644
--- a/api/testing.api.md
+++ b/api/testing.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/tools.api.md b/api/tools.api.md
index 6d0c7688d..6a9c4d76d 100644
--- a/api/tools.api.md
+++ b/api/tools.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/traces.api.md b/api/traces.api.md
index 60551ab1d..e2edd096e 100644
--- a/api/traces.api.md
+++ b/api/traces.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/triggers.api.md b/api/triggers.api.md
index 702b2d30a..920ffd7c5 100644
--- a/api/triggers.api.md
+++ b/api/triggers.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/types.api.md b/api/types.api.md
index 0438a9224..ee0f4b6fd 100644
--- a/api/types.api.md
+++ b/api/types.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/utils.api.md b/api/utils.api.md
index 6285152f3..10d3b5f9f 100644
--- a/api/utils.api.md
+++ b/api/utils.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/vue.api.md b/api/vue.api.md
index b2ddc23f0..c653cef6e 100644
--- a/api/vue.api.md
+++ b/api/vue.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/worker.api.md b/api/worker.api.md
index bf1baa62b..ab036a1c9 100644
--- a/api/worker.api.md
+++ b/api/worker.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/workspaces-client.api.md b/api/workspaces-client.api.md
index 9f69585e2..d7fcb2c28 100644
--- a/api/workspaces-client.api.md
+++ b/api/workspaces-client.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/api/workspaces.api.md b/api/workspaces.api.md
index a695e38ad..79b6df2df 100644
--- a/api/workspaces.api.md
+++ b/api/workspaces.api.md
@@ -1,4 +1,4 @@
-## API Report File for "lousho"
+## API Report File for "@linuxdevil/lousho"
 
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
diff --git a/apps/agent-forge/LICENSE b/apps/agent-forge/LICENSE
new file mode 100644
index 000000000..06c4dd43a
--- /dev/null
+++ b/apps/agent-forge/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ali Mohammad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/apps/agent-forge/README.md b/apps/agent-forge/README.md
new file mode 100644
index 000000000..66015c12c
--- /dev/null
+++ b/apps/agent-forge/README.md
@@ -0,0 +1,53 @@
+# Lousho Studio
+
+A local web app for building, testing and watching every agent across your
+projects — powered by [`@linuxdevil/lousho`](https://www.npmjs.com/package/@linuxdevil/lousho).
+
+## Install & run
+
+```sh
+npx @linuxdevil/studio            # open Studio on the current folder
+npx @linuxdevil/studio --workspace ~/code/my-app --port 5000
+```
+
+Or install it globally and use the `lousho-studio` command:
+
+```sh
+npm i -g @linuxdevil/studio
+lousho-studio --workspace ~/code/my-app
+```
+
+If your project already has the SDK, `lousho studio` (from
+`@linuxdevil/lousho`) launches the same app.
+
+Studio prints a URL with a per-launch token — every API and WebSocket
+request needs it, so keep the URL private to your machine (it binds to
+`127.0.0.1` by default; pass `--host` to change that).
+
+## Workspaces
+
+A **workspace** is a project folder. Studio reads and writes each workspace's
+agents under its `.lousho/` directory, so one Studio instance can follow many
+projects. `--workspace <dir>` opens that folder and adds it to your workspace
+list; the first run uses the current folder.
+
+Runs use the project's own SDK when the workspace has `@linuxdevil/lousho`
+installed, so Studio works across SDK versions. See
+[Agent Forge](https://lousho.com/agent-forge) for the full guide.
+
+## Options
+
+```
+Usage: lousho-studio [--workspace <dir>] [--port N] [--host H]
+
+  --workspace <dir>  a project folder to open (default: the current folder)
+  --port N           the port (default 4750)
+  --host H           the interface to listen on (default 127.0.0.1)
+  -v, --version      print the version
+  -h, --help         show this help
+```
+
+## Requirements
+
+Node.js >= 22.19. Provider API keys are configured inside Studio's Settings;
+no keys are needed to open the app.
diff --git a/apps/agent-forge/eslint.config.mjs b/apps/agent-forge/eslint.config.mjs
index 482ea2e31..4de262acf 100644
--- a/apps/agent-forge/eslint.config.mjs
+++ b/apps/agent-forge/eslint.config.mjs
@@ -13,8 +13,8 @@ export default tseslint.config(
   ...tseslint.configs.recommended,
   {
     files: ['{src,server,shared,e2e,evals}/**/*.{ts,tsx,mjs}'],
-    plugins: { lousho: { rules: { 'no-sdk-source': noSdkSource } } },
-    rules: { 'lousho/no-sdk-source': 'error' },
+    plugins: { '@linuxdevil/lousho': { rules: { 'no-sdk-source': noSdkSource } } },
+    rules: { '@linuxdevil/lousho/no-sdk-source': 'error' },
   },
   {
     files: ['src/**/*.{ts,tsx}', 'server/**/*.ts', 'evals/**/*.ts'],
diff --git a/apps/agent-forge/eslint.imports.config.mjs b/apps/agent-forge/eslint.imports.config.mjs
index 643b05d3d..86daba395 100644
--- a/apps/agent-forge/eslint.imports.config.mjs
+++ b/apps/agent-forge/eslint.imports.config.mjs
@@ -1,22 +1,22 @@
-// Minimal flat config for `npm run lint:imports`: the TypeScript parser and
-// only the no-sdk-source rule, so CI can gate on it without the rest of the
-// Studio lint debt (PLAN §19.7 — Studio imports only public SDK exports).
-import tseslint from 'typescript-eslint';
-import { noSdkSource } from './eslintRules/noSdkSource.mjs';
-
-export default [
-  {
-    ignores: ['dist/**', 'node_modules/**', 'coverage/**'],
-  },
-  {
-    files: ['{src,server,shared,e2e}/**/*.{ts,tsx,mjs}'],
-    languageOptions: { parser: tseslint.parser },
-    // This gate runs one rule; disables aimed at rules it does not enable
-    // are none of its business.
-    linterOptions: { reportUnusedDisableDirectives: 'off' },
-    // The plugin is registered (not its rules) so inline
-    // `eslint-disable @typescript-eslint/...` comments still resolve.
-    plugins: { '@typescript-eslint': tseslint.plugin, lousho: { rules: { 'no-sdk-source': noSdkSource } } },
-    rules: { 'lousho/no-sdk-source': 'error' },
-  },
-];
+// Minimal flat config for `npm run lint:imports`: the TypeScript parser and
+// only the no-sdk-source rule, so CI can gate on it without the rest of the
+// Studio lint debt (PLAN §19.7 — Studio imports only public SDK exports).
+import tseslint from 'typescript-eslint';
+import { noSdkSource } from './eslintRules/noSdkSource.mjs';
+
+export default [
+  {
+    ignores: ['dist/**', 'node_modules/**', 'coverage/**'],
+  },
+  {
+    files: ['{src,server,shared,e2e,evals}/**/*.{ts,tsx,mjs}'],
+    languageOptions: { parser: tseslint.parser },
+    // This gate runs one rule; disables aimed at rules it does not enable
+    // are none of its business.
+    linterOptions: { reportUnusedDisableDirectives: 'off' },
+    // The plugin is registered (not its rules) so inline
+    // `eslint-disable @typescript-eslint/...` comments still resolve.
+    plugins: { '@typescript-eslint': tseslint.plugin, '@linuxdevil/lousho': { rules: { 'no-sdk-source': noSdkSource } } },
+    rules: { '@linuxdevil/lousho/no-sdk-source': 'error' },
+  },
+];
diff --git a/apps/agent-forge/eslintRules/noSdkSource.mjs b/apps/agent-forge/eslintRules/noSdkSource.mjs
index 34fc9e592..82c22266f 100644
--- a/apps/agent-forge/eslintRules/noSdkSource.mjs
+++ b/apps/agent-forge/eslintRules/noSdkSource.mjs
@@ -1,48 +1,48 @@
-/** Studio must import the SDK through its package exports, never its files (PLAN §19.7). */
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const APP_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-
-/** `@lousho/build-ai-agent` after the rename, `lousho` until W13 lands. */
-const SDK_DEEP_IMPORT = /^(?:@lousho\/build-ai-agent|lousho)\/(?:src|dist)(?:\/|$)/;
-
-function isOutsideAppRoot(filename, specifier) {
-  if (!specifier.startsWith('.')) return false;
-  const resolved = path.resolve(path.dirname(filename), specifier);
-  return path.relative(APP_ROOT, resolved).startsWith('..');
-}
-
-export const noSdkSource = {
-  meta: {
-    type: 'problem',
-    docs: { description: 'Forbid importing SDK source files; use package exports only.' },
-    messages: { deep: "Import the SDK as '@lousho/build-ai-agent' or a public subpath, not '{{source}}'." },
-    schema: [],
-  },
-  create(context) {
-    const filename = context.filename;
-    const check = (node, specifier) => {
-      if (typeof specifier !== 'string') return;
-      if (SDK_DEEP_IMPORT.test(specifier) || isOutsideAppRoot(filename, specifier)) {
-        context.report({ node, messageId: 'deep', data: { source: specifier } });
-      }
-    };
-    const sourceOf = (node) => (typeof node?.source?.value === 'string' ? node.source.value : undefined);
-    return {
-      ImportDeclaration: (node) => check(node, sourceOf(node)),
-      ExportNamedDeclaration: (node) => check(node, sourceOf(node)),
-      ExportAllDeclaration: (node) => check(node, sourceOf(node)),
-      ImportExpression(node) {
-        if (node.source?.type === 'Literal' && typeof node.source.value === 'string') check(node.source, node.source.value);
-      },
-      CallExpression(node) {
-        const callee = node.callee;
-        if (callee?.type !== 'MemberExpression' || callee.object?.type !== 'Identifier' || callee.object.name !== 'vi') return;
-        if (callee.property?.type !== 'Identifier' || !['mock', 'importActual', 'importMock'].includes(callee.property.name)) return;
-        const first = node.arguments[0];
-        if (first?.type === 'Literal' && typeof first.value === 'string') check(first, first.value);
-      },
-    };
-  },
-};
+/** Studio must import the SDK through its package exports, never its files (PLAN §19.7). */
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const APP_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+/** The published names the rule guards: `@linuxdevil/lousho` now, `lousho`/`@lousho/build-ai-agent` for older layouts. */
+const SDK_DEEP_IMPORT = /^(?:@linuxdevil\/lousho|@lousho\/build-ai-agent|lousho)\/(?:src|dist)(?:\/|$)/;
+
+function isOutsideAppRoot(filename, specifier) {
+  if (!specifier.startsWith('.')) return false;
+  const resolved = path.resolve(path.dirname(filename), specifier);
+  return path.relative(APP_ROOT, resolved).startsWith('..');
+}
+
+export const noSdkSource = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'Forbid importing SDK source files; use package exports only.' },
+    messages: { deep: "Import the SDK as '@linuxdevil/lousho' or a public subpath, not '{{source}}'." },
+    schema: [],
+  },
+  create(context) {
+    const filename = context.filename;
+    const check = (node, specifier) => {
+      if (typeof specifier !== 'string') return;
+      if (SDK_DEEP_IMPORT.test(specifier) || isOutsideAppRoot(filename, specifier)) {
+        context.report({ node, messageId: 'deep', data: { source: specifier } });
+      }
+    };
+    const sourceOf = (node) => (typeof node?.source?.value === 'string' ? node.source.value : undefined);
+    return {
+      ImportDeclaration: (node) => check(node, sourceOf(node)),
+      ExportNamedDeclaration: (node) => check(node, sourceOf(node)),
+      ExportAllDeclaration: (node) => check(node, sourceOf(node)),
+      ImportExpression(node) {
+        if (node.source?.type === 'Literal' && typeof node.source.value === 'string') check(node.source, node.source.value);
+      },
+      CallExpression(node) {
+        const callee = node.callee;
+        if (callee?.type !== 'MemberExpression' || callee.object?.type !== 'Identifier' || callee.object.name !== 'vi') return;
+        if (callee.property?.type !== 'Identifier' || !['mock', 'importActual', 'importMock'].includes(callee.property.name)) return;
+        const first = node.arguments[0];
+        if (first?.type === 'Literal' && typeof first.value === 'string') check(first, first.value);
+      },
+    };
+  },
+};
diff --git a/apps/agent-forge/evals/author/harness.ts b/apps/agent-forge/evals/author/harness.ts
index d9990d2e0..2c77a28d8 100644
--- a/apps/agent-forge/evals/author/harness.ts
+++ b/apps/agent-forge/evals/author/harness.ts
@@ -15,9 +15,9 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { parse as parseYaml } from 'yaml';
-import { agentSpecV2Schema, upgradeSpec, VERSION, type LLMProvider } from 'lousho';
+import { agentSpecV2Schema, upgradeSpec, VERSION, type LLMProvider } from '@linuxdevil/lousho';
 import { envCollector } from '../../server/host/hostSelector';
-import { mockModel, type MockRequest, type MockStaticTurn, type MockToolCall } from 'lousho/testing';
+import { mockModel, type MockRequest, type MockStaticTurn, type MockToolCall } from '@linuxdevil/lousho/testing';
 import type { AuthorMessage, AuthorServerEvent } from '../../shared/authorWire';
 import { SecretsStore } from '../../server/secretsStore';
 import { SettingsStore } from '../../server/settingsStore';
diff --git a/apps/agent-forge/evals/author/judge.ts b/apps/agent-forge/evals/author/judge.ts
index 0ae736a1f..423547d0e 100644
--- a/apps/agent-forge/evals/author/judge.ts
+++ b/apps/agent-forge/evals/author/judge.ts
@@ -6,7 +6,7 @@
  * or tool input in the transcript zeroes the score, so the judge cannot
  * pass a scenario on invented evidence.
  */
-import { createAgent, type LLMProvider } from 'lousho';
+import { createAgent, type LLMProvider } from '@linuxdevil/lousho';
 import { z } from 'zod';
 import type { AuthorMessage } from '../../shared/authorWire';
 import { userMessageText } from '../../server/author/modelMessages';
diff --git a/apps/agent-forge/evals/author/run.ts b/apps/agent-forge/evals/author/run.ts
index 5affe162c..f8242807f 100644
--- a/apps/agent-forge/evals/author/run.ts
+++ b/apps/agent-forge/evals/author/run.ts
@@ -19,7 +19,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import type { LLMProvider } from 'lousho';
+import type { LLMProvider } from '@linuxdevil/lousho';
 import type { AuthorMessage, AuthorSettings } from '../../shared/authorWire';
 import { SecretsStore } from '../../server/secretsStore';
 import { passReview } from '../../server/author/proposal/review';
diff --git a/apps/agent-forge/package.json b/apps/agent-forge/package.json
index 30741e24c..87fa88e97 100644
--- a/apps/agent-forge/package.json
+++ b/apps/agent-forge/package.json
@@ -1,33 +1,61 @@
 {
-  "name": "@lousho/agent-forge",
-  "version": "0.0.1",
-  "private": true,
-  "description": "Agent Forge - visual dashboard for creating, running and debugging agents built with lousho (app shell & data model).",
+  "name": "@linuxdevil/studio",
+  "version": "0.1.0-alpha.0",
+  "description": "Lousho Studio: build, test and watch every agent across your projects. A local web app for @linuxdevil/lousho.",
   "type": "module",
+  "bin": {
+    "lousho-studio": "dist-server/cli.cjs"
+  },
+  "files": [
+    "dist",
+    "dist-server",
+    "!dist-server/*.map",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LinuxDevil/agent-sdk.git",
+    "directory": "apps/agent-forge"
+  },
+  "homepage": "https://lousho.com/introduction",
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "dev": "vite",
     "build": "tsc --noEmit -p tsconfig.json && vite build",
     "preview": "vite preview",
     "test": "vitest",
     "lint": "eslint src server shared evals",
-    "lint:imports": "eslint -c eslint.imports.config.mjs src server shared e2e --max-warnings 0",
+    "lint:imports": "eslint -c eslint.imports.config.mjs src server shared evals e2e --max-warnings 0",
     "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p e2e/tsconfig.json",
     "server:dev": "tsx watch server/index.ts",
     "server:start": "tsx server/index.ts",
     "server:build": "tsup --config server/tsup.config.ts",
     "server:start:prod": "node dist-server/index.cjs",
     "build:studio": "npm run build && npm run build:widget && npm run server:build",
+    "prepack": "node scripts/pin-sdk-range.mjs pin",
+    "postpack": "node scripts/pin-sdk-range.mjs restore",
     "test:server": "vitest run -c server/vitest.config.ts",
+    "test:bridge-compat": "vitest run -c server/vitest.compat.config.ts",
     "typecheck:server": "tsc --noEmit -p server/tsconfig.json && tsc --noEmit -p evals/tsconfig.json",
     "eval:author": "tsx evals/author/run.ts",
     "test:e2e:studio": "npm run build:studio && playwright test",
     "build:widget": "vite build -c vite.widget.config.ts"
   },
   "dependencies": {
+    "@ai-sdk/anthropic": "^4.0.0",
+    "@ai-sdk/openai": "^4.0.0",
     "@codemirror/lang-javascript": "^6.2.5",
-    "lousho": "file:../..",
+    "@linuxdevil/lousho": "file:../..",
     "@uiw/react-codemirror": "^4.25.12",
     "@xyflow/react": "^12.12.0",
+    "ai": "^7.0.0",
     "elkjs": "^0.9.3",
     "express": "^5.2.1",
     "react": "^18.3.1",
@@ -37,9 +65,8 @@
     "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@ai-sdk/anthropic": "^0.0.42",
-    "@ai-sdk/openai": "^0.0.42",
     "@axe-core/playwright": "4.13.0",
+    "@codemirror/lang-javascript": "^6.2.5",
     "@fontsource-variable/inter": "^5.3.0",
     "@playwright/test": "^1.63.0",
     "@types/express": "^5.0.5",
@@ -47,17 +74,23 @@
     "@types/react-dom": "^18.3.1",
     "@types/supertest": "^6.0.3",
     "@types/ws": "^8.18.1",
-    "diff": "^8.0.4",
+    "@uiw/react-codemirror": "^4.25.12",
     "@vitejs/plugin-react": "^4.3.4",
+    "@xyflow/react": "^12.12.0",
+    "diff": "^8.0.4",
+    "express": "^5.2.1",
     "jsdom": "^25.0.1",
     "lucide-react": "^1.63.0",
     "ollama-ai-provider": "^1.2.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
     "supertest": "^7.3.0",
     "tsup": "^8.0.0",
     "tsx": "^4.23.15",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.71.0",
     "vite": "^5.4.11",
-    "vitest": "^1.0.0"
+    "vitest": "^1.0.0",
+    "ws": "^8.18.3"
   }
 }
diff --git a/apps/agent-forge/scripts/pin-sdk-range.mjs b/apps/agent-forge/scripts/pin-sdk-range.mjs
new file mode 100644
index 000000000..2af900346
--- /dev/null
+++ b/apps/agent-forge/scripts/pin-sdk-range.mjs
@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * Rewrites the Studio package's SDK dependency for packing.
+ *
+ * In the monorepo `dependencies['@linuxdevil/lousho']` stays `file:../..`
+ * so the dev loop always runs the checkout next door. `npm pack`/`publish`
+ * run `prepack` (`pin`) first: when the repo root package is the SDK
+ * (`@linuxdevil/lousho`), the range is rewritten to `^<its version>` and the
+ * original file is kept as `.package.json.prepack`; `postpack` (`restore`)
+ * puts it back. Outside that layout `pin` is a no-op.
+ *
+ * Usage: node scripts/pin-sdk-range.mjs pin|restore   (cwd: apps/agent-forge)
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const SDK_PACKAGE = '@linuxdevil/lousho';
+const DEP_KEY = SDK_PACKAGE;
+const BACKUP = '.package.json.prepack';
+
+const appDir = process.cwd();
+const pkgPath = path.join(appDir, 'package.json');
+const rootPkgPath = path.join(appDir, '..', '..', 'package.json');
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function pin() {
+  const backupPath = path.join(appDir, BACKUP);
+  if (fs.existsSync(backupPath)) {
+    console.error('pin-sdk-range: restore first (.package.json.prepack already exists)');
+    process.exit(1);
+  }
+  if (!fs.existsSync(rootPkgPath) || !fs.existsSync(pkgPath)) return;
+  const root = readJson(rootPkgPath);
+  if (root.name !== SDK_PACKAGE) return;
+  const pkg = readJson(pkgPath);
+  if (pkg.dependencies?.[DEP_KEY] === undefined) return;
+  fs.writeFileSync(backupPath, fs.readFileSync(pkgPath));
+  pkg.dependencies[DEP_KEY] = `^${root.version}`;
+  fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+  console.log(`pin-sdk-range: ${DEP_KEY} -> ^${root.version}`);
+}
+
+function restore() {
+  const backupPath = path.join(appDir, BACKUP);
+  if (!fs.existsSync(backupPath)) return;
+  fs.renameSync(backupPath, pkgPath);
+  console.log('pin-sdk-range: restored package.json');
+}
+
+const command = process.argv[2];
+if (command === 'pin') pin();
+else if (command === 'restore') restore();
+else {
+  console.error('pin-sdk-range: usage: pin-sdk-range.mjs pin|restore');
+  process.exit(2);
+}
diff --git a/apps/agent-forge/server/__tests__/abort.test.ts b/apps/agent-forge/server/__tests__/abort.test.ts
index 638d7ed5a..d74933c98 100644
--- a/apps/agent-forge/server/__tests__/abort.test.ts
+++ b/apps/agent-forge/server/__tests__/abort.test.ts
@@ -29,7 +29,7 @@ import {
   type AgentSpecV2,
   type GenerateOptions,
   type LLMProvider,
-} from 'lousho';
+} from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
diff --git a/apps/agent-forge/server/__tests__/abortListeners.test.ts b/apps/agent-forge/server/__tests__/abortListeners.test.ts
index 36bc25a23..9dc7de40d 100644
--- a/apps/agent-forge/server/__tests__/abortListeners.test.ts
+++ b/apps/agent-forge/server/__tests__/abortListeners.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 
 import { applyAbortListeners, type AbortListenerInput } from '../triggers/abortListeners';
 import type { HostRun } from '../triggers/triggerHost';
diff --git a/apps/agent-forge/server/__tests__/agentRequirements.test.ts b/apps/agent-forge/server/__tests__/agentRequirements.test.ts
index f7d1819cc..9b204bf4b 100644
--- a/apps/agent-forge/server/__tests__/agentRequirements.test.ts
+++ b/apps/agent-forge/server/__tests__/agentRequirements.test.ts
@@ -9,7 +9,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
diff --git a/apps/agent-forge/server/__tests__/agentRoutes.create.test.ts b/apps/agent-forge/server/__tests__/agentRoutes.create.test.ts
index d9b6ec68e..b5f2fc259 100644
--- a/apps/agent-forge/server/__tests__/agentRoutes.create.test.ts
+++ b/apps/agent-forge/server/__tests__/agentRoutes.create.test.ts
@@ -8,7 +8,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
diff --git a/apps/agent-forge/server/__tests__/agentRoutes.test.ts b/apps/agent-forge/server/__tests__/agentRoutes.test.ts
index 7e3277fd5..e59aa51c7 100644
--- a/apps/agent-forge/server/__tests__/agentRoutes.test.ts
+++ b/apps/agent-forge/server/__tests__/agentRoutes.test.ts
@@ -10,7 +10,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
 import { parse as parseYaml } from 'yaml';
-import type { AgentSpec, AgentSpecV2 } from 'lousho';
+import type { AgentSpec, AgentSpecV2 } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
diff --git a/apps/agent-forge/server/__tests__/allAgentsRoute.test.ts b/apps/agent-forge/server/__tests__/allAgentsRoute.test.ts
index 27b783039..1939b4f01 100644
--- a/apps/agent-forge/server/__tests__/allAgentsRoute.test.ts
+++ b/apps/agent-forge/server/__tests__/allAgentsRoute.test.ts
@@ -4,7 +4,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
-import { VERSION, type AgentSpecV2 } from 'lousho';
+import { VERSION, type AgentSpecV2 } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import type { Express } from 'express';
 import { createWorkspaceContext, type WorkspaceContext, type WorkspaceServices } from '../workspace/context';
diff --git a/apps/agent-forge/server/__tests__/app.test.ts b/apps/agent-forge/server/__tests__/app.test.ts
index 4bf6f3398..159cc6e10 100644
--- a/apps/agent-forge/server/__tests__/app.test.ts
+++ b/apps/agent-forge/server/__tests__/app.test.ts
@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import request from 'supertest';
-import type { AgentSpec, AgentSpecV2 } from 'lousho';
+import type { AgentSpec, AgentSpecV2 } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
diff --git a/apps/agent-forge/server/__tests__/approvalFlow.test.ts b/apps/agent-forge/server/__tests__/approvalFlow.test.ts
index 5d7b46416..380d08a88 100644
--- a/apps/agent-forge/server/__tests__/approvalFlow.test.ts
+++ b/apps/agent-forge/server/__tests__/approvalFlow.test.ts
@@ -18,8 +18,8 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import { AgentExecutor, ToolRegistry, AgentBuilder, resumeAfterApproval } from 'lousho/executor';
-import { createMockProvider, type ToolDescriptor } from 'lousho';
+import { AgentExecutor, ToolRegistry, AgentBuilder, resumeAfterApproval } from '@linuxdevil/lousho/executor';
+import { createMockProvider, type ToolDescriptor } from '@linuxdevil/lousho';
 import { FileApprovalStore } from '../approvalStore';
 import { FileCheckpointStore } from '../checkpointStore';
 
diff --git a/apps/agent-forge/server/__tests__/authorEnable.test.ts b/apps/agent-forge/server/__tests__/authorEnable.test.ts
index 45f97f4a6..fdeb9a83c 100644
--- a/apps/agent-forge/server/__tests__/authorEnable.test.ts
+++ b/apps/agent-forge/server/__tests__/authorEnable.test.ts
@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { STUDIO_TOKEN_HEADER } from '../auth';
 import { RunManager } from '../runRegistry';
diff --git a/apps/agent-forge/server/__tests__/authorSave.test.ts b/apps/agent-forge/server/__tests__/authorSave.test.ts
index 2ae121601..cad57c721 100644
--- a/apps/agent-forge/server/__tests__/authorSave.test.ts
+++ b/apps/agent-forge/server/__tests__/authorSave.test.ts
@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { STUDIO_TOKEN_HEADER } from '../auth';
 import { RunManager } from '../runRegistry';
diff --git a/apps/agent-forge/server/__tests__/authorSecret.test.ts b/apps/agent-forge/server/__tests__/authorSecret.test.ts
index 178b89b1c..915307fdc 100644
--- a/apps/agent-forge/server/__tests__/authorSecret.test.ts
+++ b/apps/agent-forge/server/__tests__/authorSecret.test.ts
@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
-import { mockModel } from 'lousho/testing';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { createApp } from '../app';
 import { STUDIO_TOKEN_HEADER } from '../auth';
 import { RunManager } from '../runRegistry';
diff --git a/apps/agent-forge/server/__tests__/authorSessions.test.ts b/apps/agent-forge/server/__tests__/authorSessions.test.ts
index b4dfab310..e155cb392 100644
--- a/apps/agent-forge/server/__tests__/authorSessions.test.ts
+++ b/apps/agent-forge/server/__tests__/authorSessions.test.ts
@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
-import { mockModel } from 'lousho/testing';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { createApp } from '../app';
 import { STUDIO_TOKEN_HEADER } from '../auth';
 import { RunManager } from '../runRegistry';
diff --git a/apps/agent-forge/server/__tests__/authorStream.test.ts b/apps/agent-forge/server/__tests__/authorStream.test.ts
index ed741e9a4..c2118500a 100644
--- a/apps/agent-forge/server/__tests__/authorStream.test.ts
+++ b/apps/agent-forge/server/__tests__/authorStream.test.ts
@@ -3,8 +3,8 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { WebSocket } from 'ws';
-import { mockModel } from 'lousho/testing';
-import type { LLMProvider, StreamChunk } from 'lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
+import type { LLMProvider, StreamChunk } from '@linuxdevil/lousho';
 import { startStudioServer, type StudioServerHandle } from '../index';
 import { STUDIO_TOKEN_HEADER } from '../auth';
 import { AuthorSessionStore } from '../author/sessionStore';
diff --git a/apps/agent-forge/server/__tests__/autoApproval.test.ts b/apps/agent-forge/server/__tests__/autoApproval.test.ts
index 9459a2da0..e4bdfcd5c 100644
--- a/apps/agent-forge/server/__tests__/autoApproval.test.ts
+++ b/apps/agent-forge/server/__tests__/autoApproval.test.ts
@@ -2,7 +2,7 @@ import { mkdtempSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import * as path from 'node:path';
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import type { AutoApprovalDecision, AutoApprovalRequest } from 'lousho';
+import type { AutoApprovalDecision, AutoApprovalRequest } from '@linuxdevil/lousho';
 import { autoApprovalLogEntry, studioAutoApprover } from '../autoApproval';
 import { SpendLog } from '../passes/spendLog';
 import { SecretsStore } from '../secretsStore';
diff --git a/apps/agent-forge/server/__tests__/bridge.compat.test.ts b/apps/agent-forge/server/__tests__/bridge.compat.test.ts
new file mode 100644
index 000000000..b1cf5db81
--- /dev/null
+++ b/apps/agent-forge/server/__tests__/bridge.compat.test.ts
@@ -0,0 +1,251 @@
+/**
+ * W15b: bridge compatibility matrix. Proves the CURRENT Studio drives
+ * `lousho bridge` from (a) the SDK in this checkout and (b) the oldest SDK
+ * release Studio still supports (`MIN_BRIDGE_SDK_VERSION`), so an SDK
+ * change that breaks protocol 1 - or a Studio change that needs a newer
+ * bridge - fails a PR instead of a user.
+ *
+ * `LOUSHO_BRIDGE_SDK_DIR` points at the SDK under test (default: this
+ * repo's root, i.e. the SDK in this commit). Each case builds a throwaway
+ * workspace `<tmp>/ws` whose `node_modules/<sdk>` is a junction to that
+ * directory, then drives every run through `WorkspaceHostSelector` +
+ * `BridgeAgentHost` - the same path production traffic takes; no protocol
+ * lines are written by hand.
+ *
+ * Scripted turns come from `scriptedProvider.mjs` (W11b's preload),
+ * loaded with `nodeArgs: ['--import', ...]`; `LOUSHO_BRIDGE_SDK_DIR` in
+ * the child env makes the preload import THAT SDK's dist entries (the
+ * bare specifier would resolve Studio's own checkout - a different module
+ * instance than the bridge child's).
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import type { AgentSpecV2, Message } from '@linuxdevil/lousho';
+import { WorkspaceHostSelector, type SelectHostDeps } from '../host/hostSelector';
+import type { HostEvent, HostRunInput } from '../host/agentHost';
+import { HostStartError } from '../host/bridgeAgentHost';
+import { FileCheckpointStore } from '../checkpointStore';
+import { FileApprovalStore } from '../approvalStore';
+import { InProcessAgentHost } from '../host/inProcessAgentHost';
+import { workspaceRefFor } from '../workspace/workspaceId';
+import { SecretsStore } from '../secretsStore';
+import { VERSION } from '@linuxdevil/lousho';
+
+const REPO_ROOT = fileURLToPath(new URL('../../../../', import.meta.url));
+const SDK_DIR = process.env.LOUSHO_BRIDGE_SDK_DIR ?? REPO_ROOT;
+const SCRIPTED_PROVIDER = fileURLToPath(new URL('./fixtures/scriptedProvider.mjs', import.meta.url));
+
+interface SdkUnderTest {
+  dir: string;
+  name: string;
+  version: string;
+}
+
+let sdk: SdkUnderTest;
+let ws: string;
+let secretsDir: string;
+let secretsStore: SecretsStore;
+let cleanups: Array<() => Promise<void>>;
+
+beforeEach(() => {
+  const pkg = JSON.parse(fs.readFileSync(path.join(SDK_DIR, 'package.json'), 'utf8')) as { name: string; version: string };
+  sdk = { dir: SDK_DIR, name: pkg.name, version: pkg.version };
+  ws = fs.mkdtempSync(path.join(os.tmpdir(), 'lou-w15b-ws-'));
+  secretsDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lou-w15b-sec-'));
+  secretsStore = new SecretsStore(secretsDir);
+  cleanups = [];
+});
+
+afterEach(async () => {
+  for (const cleanup of cleanups.splice(0)) await cleanup();
+  fs.rmSync(ws, { recursive: true, force: true });
+  fs.rmSync(secretsDir, { recursive: true, force: true });
+});
+
+/** `<tmp>/ws` with `package.json` and `node_modules/<sdk>` junctioned to the SDK under test. No `.env`. */
+function makeWorkspace(): string {
+  const root = path.join(ws, 'project');
+  fs.mkdirSync(root, { recursive: true });
+  fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name: 'compat-ws', private: true }));
+  const pkgDir = path.join(root, 'node_modules', ...sdk.name.split('/'));
+  fs.mkdirSync(path.dirname(pkgDir), { recursive: true });
+  fs.symlinkSync(sdk.dir, pkgDir, process.platform === 'win32' ? 'junction' : 'dir');
+  return root;
+}
+
+function selectorDeps(root: string, options: { turns?: unknown; preload?: boolean } = {}): SelectHostDeps {
+  return {
+    inProcess: () =>
+      new InProcessAgentHost({
+        baseDir: root,
+        checkpointStore: new FileCheckpointStore(root),
+        approvalStore: new FileApprovalStore(root),
+        secretsStore,
+      }),
+    secretsStore,
+    collector: () => ({ url: 'http://127.0.0.1:9' }),
+    studioVersion: VERSION,
+    ...(options.preload === true && {
+      nodeArgs: ['--import', pathToFileURL(SCRIPTED_PROVIDER).href],
+      extraEnv: {
+        SCRIPTED_TURNS: JSON.stringify(options.turns ?? ['ok']),
+        LOUSHO_BRIDGE_SDK_DIR: sdk.dir,
+      },
+    }),
+  };
+}
+
+async function readyHost(root: string, options: { turns?: unknown; preload?: boolean } = {}) {
+  const selector = new WorkspaceHostSelector(workspaceRefFor(root), selectorDeps(root, options));
+  cleanups.push(async () => {
+    await selector.host.dispose();
+  });
+  const selection = await selector.ready();
+  return { selector, selection, host: selector.host };
+}
+
+function inputFor(events: HostEvent[], spec: AgentSpecV2, input: HostRunInput['input']): HostRunInput {
+  return { agentId: 'compat', spec, sessionId: 'compat-s', input, onEvent: (e) => events.push(e) };
+}
+
+async function waitFor(predicate: () => boolean, what: string, timeoutMs = 60_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (predicate()) return;
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  throw new Error(`timed out waiting for ${what}`);
+}
+
+const settledEvents = (events: HostEvent[]) => events.filter((e) => e.type === 'settled');
+const agentTypes = (events: HostEvent[]) => events.filter((e) => e.type === 'agent').map((e) => (e.type === 'agent' ? e.event.type : ''));
+
+describe('bridge compat: current Studio x SDK under test', () => {
+  it('case 1: ready() yields bridge mode, protocol 1, spec v2, and the SDK version', async () => {
+    const root = makeWorkspace();
+    const { selection, host } = await readyHost(root);
+    expect(selection.mode).toBe('bridge');
+    expect(selection.protocol).toBe(1);
+    expect(selection.specVersions).toContain(2);
+    expect(selection.sdkVersion).toBe(sdk.version);
+    expect(host.kind).toBe('bridge');
+  });
+
+  it('case 2: catalog() returns four non-empty arrays of named items', async () => {
+    const root = makeWorkspace();
+    const { host } = await readyHost(root);
+    const catalog = await host.catalog();
+    for (const key of ['tools', 'models', 'guardrails', 'triggers'] as const) {
+      expect(catalog[key].length, key).toBeGreaterThan(0);
+      for (const item of catalog[key]) {
+        // Trigger catalog entries key on `type`; tools/models/guardrails on `name`; some on `id`.
+        const identifiable = item as { name?: unknown; id?: unknown; type?: unknown };
+        expect(
+          typeof identifiable.name === 'string' || typeof identifiable.id === 'string' || typeof identifiable.type === 'string',
+          `${key} item has no name/id/type`
+        ).toBe(true);
+      }
+    }
+  });
+
+  it('case 3: a minimal scripted spec runs to a settled stop', async () => {
+    const root = makeWorkspace();
+    const { host } = await readyHost(root, { preload: true, turns: ['hi there'] });
+    const spec: AgentSpecV2 = { version: 2, name: 'compat', model: 'scripted/x', instructions: 'Say hi.' };
+    const events: HostEvent[] = [];
+    await host.start(inputFor(events, spec, 'hi'));
+    await waitFor(() => settledEvents(events).length > 0, 'settled');
+    const settled = settledEvents(events)[0]!;
+    expect(settled.type === 'settled' && settled.result.finishReason).toBe('stop');
+    expect(settled.type === 'settled' && (settled.result.text ?? '').length).toBeGreaterThan(0);
+  });
+
+  it('case 3b: the same minimal spec on mock/mock-1, without the preload', async () => {
+    const spec: AgentSpecV2 = { version: 2, name: 'compat', model: 'mock/mock-1', instructions: 'Say hi.' };
+    const root = makeWorkspace();
+    const { host } = await readyHost(root);
+    const events: HostEvent[] = [];
+    await host.start(inputFor(events, spec, 'hi'));
+    await waitFor(() => settledEvents(events).length > 0, 'settled');
+    const types = agentTypes(events);
+    expect(types).toContain('run.start');
+    expect(types).toContain('run.done');
+    const spanPhases = events.filter((e) => e.type === 'span').map((e) => (e.type === 'span' ? e.phase : ''));
+    expect(spanPhases).toContain('start');
+    expect(spanPhases).toContain('end');
+    const settled = settledEvents(events)[0]!;
+    expect(settled.type === 'settled' && settled.result.finishReason).toBe('stop');
+    expect(settled.type === 'settled' && (settled.result.text ?? '').length).toBeGreaterThan(0);
+  });
+
+  it('case 4: chat continuation input settles', async () => {
+    const spec: AgentSpecV2 = { version: 2, name: 'compat', model: 'mock/mock-1', instructions: 'Say hi.' };
+    const root = makeWorkspace();
+    const { host } = await readyHost(root);
+    const events: HostEvent[] = [];
+    const messages: Message[] = [
+      { role: 'user', content: 'a' },
+      { role: 'assistant', content: 'b' },
+      { role: 'user', content: 'c' },
+    ];
+    await host.start(inputFor(events, spec, messages));
+    await waitFor(() => settledEvents(events).length > 0, 'settled');
+    const settled = settledEvents(events)[0]!;
+    expect(settled.type === 'settled').toBe(true);
+  });
+
+  it('case 5: an asked permission pauses, then resolveApproval continues to a stop', async () => {
+    const root = makeWorkspace();
+    const { host } = await readyHost(root, {
+      preload: true,
+      turns: [{ toolCalls: [{ name: 'current_date', args: {} }] }, 'done'],
+    });
+    const spec: AgentSpecV2 = {
+      version: 2,
+      name: 'compat',
+      model: 'scripted/x',
+      instructions: 'Say hi.',
+      tools: [{ builtin: 'current_date' }],
+      permissions: [{ id: 'p1', tool: 'current_date', action: 'ask' }],
+    };
+    const events: HostEvent[] = [];
+    const run = await host.start(inputFor(events, spec, 'hi'));
+    await waitFor(() => settledEvents(events).length > 0, 'first settle');
+    const paused = settledEvents(events)[0]!;
+    expect(paused.type === 'settled' && paused.result.finishReason).toBe('awaiting-approval');
+    const pending = paused.type === 'settled' ? paused.result.pendingApproval : undefined;
+    expect(pending).toBeDefined();
+    const approvalId = (pending as { id: string }).id;
+
+    await host.resolveApproval(run.runId, approvalId, { approved: true });
+    await waitFor(() => settledEvents(events).length > 1, 'continuation settle');
+    const done = settledEvents(events)[1]!;
+    expect(done.type === 'settled' && done.result.finishReason).toBe('stop');
+  });
+
+  it('case 6: abort after the first agent event settles aborted', async () => {
+    const root = makeWorkspace();
+    const { host } = await readyHost(root, { preload: true, turns: [{ text: 'thinking', delayMs: 2_000 }] });
+    const spec: AgentSpecV2 = { version: 2, name: 'compat', model: 'scripted/x', instructions: 'Say hi.' };
+    const events: HostEvent[] = [];
+    const run = await host.start(inputFor(events, spec, 'hi'));
+    await waitFor(() => agentTypes(events).length > 0, 'first agent event', 15_000);
+    await host.abort(run.runId, 'user');
+    await waitFor(() => settledEvents(events).length > 0, 'aborted settle', 15_000);
+    const settled = settledEvents(events)[0]!;
+    expect(settled.type === 'settled' && settled.result.finishReason).toBe('aborted');
+  });
+
+  it('case 7: an unknown model rejects start with a LOUSHO_* HostStartError', async () => {
+    const root = makeWorkspace();
+    const { host } = await readyHost(root);
+    const spec: AgentSpecV2 = { version: 2, name: 'compat', model: 'nope/x', instructions: 'Say hi.' };
+    const events: HostEvent[] = [];
+    const failure = await host.start(inputFor(events, spec, 'hi')).catch((e: unknown) => e);
+    expect(failure).toBeInstanceOf(HostStartError);
+    expect((failure as HostStartError).code).toMatch(/^LOUSHO_/);
+  });
+});
diff --git a/apps/agent-forge/server/__tests__/bridgeAgentHost.test.ts b/apps/agent-forge/server/__tests__/bridgeAgentHost.test.ts
index b6e8ea59f..83eaec6b7 100644
--- a/apps/agent-forge/server/__tests__/bridgeAgentHost.test.ts
+++ b/apps/agent-forge/server/__tests__/bridgeAgentHost.test.ts
@@ -1,402 +1,403 @@
-/**
- * W11b: `BridgeAgentHost` - the `AgentHost` over `lousho bridge`.
- *
- * Unit half: a stub `BridgeClient` pins the request/push mapping,
- * secrets/env params, error translation and the read-only gate.
- * Integration half: a temp workspace whose `node_modules/lousho` is a
- * junction to this repo runs the REAL built bridge (`dist/cli/bridge.mjs`)
- * with the `scripted` provider preloaded.
- */
-import * as fs from 'node:fs';
-import * as os from 'node:os';
-import * as path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from 'vitest';
-import type { AgentSpecV2, BridgePush, Message } from 'lousho';
-import { BridgeAgentHost, HostReadOnlyError, HostStartError } from '../host/bridgeAgentHost';
-import { BridgeClient, BridgeError } from '../host/bridgeClient';
-import { HostRunNotActiveError } from '../host/agentHost';
-import type { HostCatalog, HostEvent, HostRunInput } from '../host/agentHost';
-import type { HostSelection } from '../host/hostSelector';
-import { findWorkspaceSdk, type WorkspaceSdk } from '../host/workspaceSdk';
-import { SecretsStore } from '../secretsStore';
-
-const SPEC: AgentSpecV2 = { version: 2, name: 'a', model: 'mock/m', instructions: 'Be brief.' };
-const SDK: WorkspaceSdk = { version: '1.0.0', packageDir: '/sdk', binPath: '/sdk/bin/lousho.js', source: 'node_modules', built: true };
-const BRIDGE_SELECTION: HostSelection = { mode: 'bridge', sdk: SDK, sdkVersion: '1.0.0', banner: null };
-const READ_ONLY_SELECTION: HostSelection = {
-  mode: 'read-only',
-  sdk: SDK,
-  sdkVersion: '1.0.0',
-  banner: { tone: 'warning', text: 'read-only for tests' },
-};
-const FALLBACK: HostCatalog = { tools: [], models: [], guardrails: [], triggers: [] };
-
-let dir: string;
-let secretsDir: string;
-let secretsStore: SecretsStore;
-
-beforeEach(() => {
-  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'lou-w11b-host-'));
-  secretsDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lou-w11b-hsec-'));
-  secretsStore = new SecretsStore(secretsDir);
-});
-
-afterEach(() => {
-  fs.rmSync(dir, { recursive: true, force: true });
-  fs.rmSync(secretsDir, { recursive: true, force: true });
-});
-
-// -- stub client -------------------------------------------------------------
-
-interface Stub {
-  client: BridgeClient;
-  requests: Array<{ method: string; params: unknown }>;
-  pushes: Map<string, (push: BridgePush) => void>;
-  emit(runId: string, push: BridgePush): void;
-  stop: Mock<[], Promise<void>>;
-}
-
-function stubClient(options: { hello?: { catalogHash: string; sdkVersion: string }; respond?: (method: string, params: unknown) => unknown; reject?: (method: string) => Error | undefined } = {}): Stub {
-  const requests: Stub['requests'] = [];
-  const pushes = new Map<string, (push: BridgePush) => void>();
-  const stop = vi.fn<[], Promise<void>>(async () => undefined);
-  const client = {
-    hello: options.hello ?? { catalogHash: 'h1', sdkVersion: '1.0.0' },
-    request: vi.fn(async (method: string, params: unknown) => {
-      requests.push({ method, params });
-      const failure = options.reject?.(method);
-      if (failure !== undefined) throw failure;
-      return (
-        options.respond?.(method, params) ??
-        (method === 'run' || method === 'chat'
-          ? { runId: 'run-1', modelLabel: 'mock/m' }
-          : method === 'catalog'
-            ? { tools: [], models: [], guardrails: [], triggers: [] }
-            : method === 'abort'
-              ? { state: 'aborting' }
-              : { ok: true })
-      );
-    }),
-    onPush: vi.fn((runId: string, listener: (push: BridgePush) => void) => {
-      pushes.set(runId, listener);
-      return () => pushes.delete(runId);
-    }),
-    stop,
-  } as unknown as BridgeClient;
-  return { client, requests, pushes, emit: (runId, push) => pushes.get(runId)?.(push), stop };
-}
-
-function hostWith(stub: Stub, selection: HostSelection = BRIDGE_SELECTION): { host: BridgeAgentHost; events: HostEvent[]; input: HostRunInput } {
-  const events: HostEvent[] = [];
-  const host = new BridgeAgentHost(stub.client, {
-    secretsStore,
-    ready: async () => selection,
-    fallbackCatalog: async () => FALLBACK,
-    sdk: SDK,
-  });
-  const input: HostRunInput = { agentId: 'agent1', spec: SPEC, sessionId: 's1', input: 'hello', onEvent: (e) => events.push(e) };
-  return { host, events, input };
-}
-
-const settledPush = (runId: string, finishReason = 'stop'): BridgePush =>
-  ({ event: 'run.settled', runId, data: { finishReason, text: 'done' } }) as BridgePush;
-
-// -- unit: start / pushes ------------------------------------------------------
-
-describe('BridgeAgentHost.start', () => {
-  it('sends run params and maps pushes to HostEvents until the terminal settle', async () => {
-    const stub = stubClient();
-    const { host, events, input } = hostWith(stub);
-    const run = await host.start(input);
-    expect(run).toEqual({ runId: 'run-1', modelLabel: 'mock/m' });
-    expect(stub.requests).toHaveLength(1);
-    expect(stub.requests[0]).toMatchObject({
-      method: 'run',
-      params: { agentId: 'agent1', spec: SPEC, sessionId: 's1', input: 'hello' },
-    });
-    expect(stub.pushes.has('run-1')).toBe(true);
-
-    stub.emit('run-1', { event: 'agent', runId: 'run-1', data: { type: 'text-delta', text: 'hi' } } as unknown as BridgePush);
-    stub.emit('run-1', { event: 'span.start', runId: 'run-1', data: { id: 'sp1' } } as unknown as BridgePush);
-    stub.emit('run-1', { event: 'span.end', runId: 'run-1', data: { id: 'sp1' } } as unknown as BridgePush);
-    stub.emit('run-1', settledPush('run-1'));
-    expect(events.map((e) => e.type)).toEqual(['agent', 'span', 'span', 'settled']);
-    // Terminal settle unsubscribes: later pushes for the run go nowhere.
-    expect(stub.pushes.has('run-1')).toBe(false);
-    stub.emit('run-1', settledPush('run-1'));
-    expect(events).toHaveLength(4);
-  });
-
-  it('keeps the subscription across an awaiting-approval settle', async () => {
-    const stub = stubClient();
-    const { host, input } = hostWith(stub);
-    await host.start(input);
-    stub.emit('run-1', settledPush('run-1', 'awaiting-approval'));
-    expect(stub.pushes.has('run-1')).toBe(true);
-  });
-
-  it('uses chat with Message[] input and TypeErrors on ContentPart[]', async () => {
-    const stub = stubClient();
-    const { host, input } = hostWith(stub);
-    const messages: Message[] = [
-      { role: 'user', content: 'one' },
-      { role: 'assistant', content: 'two' },
-      { role: 'user', content: 'three' },
-    ];
-    await host.start({ ...input, input: messages });
-    expect(stub.requests[0]).toMatchObject({ method: 'chat', params: { messages } });
-
-    const stub2 = stubClient();
-    const { host: host2 } = hostWith(stub2);
-    await expect(
-      host2.start({ ...input, input: [{ type: 'text', text: 'parts' }] as never })
-    ).rejects.toBeInstanceOf(TypeError);
-    expect(stub2.requests).toHaveLength(0);
-  });
-
-  it('sends named secrets and provider env, omitting unset values', async () => {
-    secretsStore.setSecret('GH', 'ghp_x');
-    secretsStore.setKey('openai', 'sk-test');
-    const spec: AgentSpecV2 = {
-      ...SPEC,
-      mcpServers: { api: { url: 'https://x.test/mcp', headers: { Authorization: { secret: 'GH' }, Missing: { secret: 'NOPE' } } } } as AgentSpecV2['mcpServers'],
-    };
-    const stub = stubClient();
-    const { host, input } = hostWith(stub);
-    await host.start({ ...input, spec });
-    const params = stub.requests[0]!.params as { secrets?: Record<string, string>; env?: Record<string, string> };
-    expect(params.secrets).toEqual({ GH: 'ghp_x' });
-    expect(params.env).toEqual({ OPENAI_API_KEY: 'sk-test' });
-  });
-
-  it('sends no secrets/env keys when the spec has no refs and no keys are stored', async () => {
-    const stub = stubClient();
-    const { host, input } = hostWith(stub);
-    await host.start(input);
-    const params = stub.requests[0]!.params as Record<string, unknown>;
-    expect(params).not.toHaveProperty('secrets');
-    expect(params).not.toHaveProperty('env');
-  });
-
-  it('wraps start failures in HostStartError with the bridge code', async () => {
-    const stub = stubClient({ reject: () => new BridgeError('boom', 'LOUSHO_BRIDGE_CRASHED') });
-    const { host, input } = hostWith(stub);
-    const failure = await host.start(input).catch((e: unknown) => e);
-    expect(failure).toBeInstanceOf(HostStartError);
-    expect((failure as HostStartError).code).toBe('LOUSHO_BRIDGE_CRASHED');
-  });
-});
-
-// -- unit: run controls ---------------------------------------------------------
-
-describe('BridgeAgentHost run controls', () => {
-  it('steer/abort/resolveApproval/answerQuestion send the bridge params', async () => {
-    const stub = stubClient({ respond: (m) => (m === 'abort' ? { state: 'discarded' } : m === 'steer' ? { id: 'st1', applied: 'immediate' } : { ok: true }) });
-    const { host } = hostWith(stub);
-    await host.start({ agentId: 'a', spec: SPEC, sessionId: 's', input: 'hi', onEvent: () => {} });
-    await expect(host.steer('run-1', 'more')).resolves.toEqual({ id: 'st1', applied: 'immediate' });
-    await host.abort('run-1', 'user');
-    await host.resolveApproval('run-1', 'ap1', { approved: true, note: 'n' });
-    await host.answerQuestion('run-1', 'q1', 'yes');
-    expect(stub.requests.map((r) => r.method)).toEqual(['run', 'steer', 'abort', 'resolveApproval', 'answerQuestion']);
-    expect(stub.requests[1]!.params).toEqual({ runId: 'run-1', message: 'more' });
-    expect(stub.requests[2]!.params).toEqual({ runId: 'run-1', reason: 'user' });
-    expect(stub.requests[3]!.params).toEqual({ runId: 'run-1', approvalId: 'ap1', approved: true, note: 'n' });
-    expect(stub.requests[4]!.params).toEqual({ runId: 'run-1', questionId: 'q1', answer: 'yes' });
-    // 'discarded' abort unsubscribed the run's push listener.
-    expect(stub.pushes.has('run-1')).toBe(false);
-  });
-
-  it.each(['LOUSHO_NO_ACTIVE_RUN', 'LOUSHO_BRIDGE_RUN_NOT_FOUND', 'LOUSHO_APPROVAL_NOT_FOUND'])(
-    'maps %s to HostRunNotActiveError',
-    async (code) => {
-      const stub = stubClient({ reject: () => new BridgeError('gone', code) });
-      const { host } = hostWith(stub);
-      await expect(host.steer('run-1', 'x')).rejects.toBeInstanceOf(HostRunNotActiveError);
-      await expect(host.abort('run-1')).rejects.toBeInstanceOf(HostRunNotActiveError);
-      await expect(host.resolveApproval('run-1', 'a', { approved: true })).rejects.toBeInstanceOf(HostRunNotActiveError);
-      await expect(host.answerQuestion('run-1', 'q', 'a')).rejects.toBeInstanceOf(HostRunNotActiveError);
-    }
-  );
-
-  it('leaves other bridge errors unmapped', async () => {
-    const stub = stubClient({ reject: () => new BridgeError('bad', 'LOUSHO_BRIDGE_TIMEOUT') });
-    const { host } = hostWith(stub);
-    const failure = await host.steer('run-1', 'x').catch((e: unknown) => e);
-    expect(failure).toBeInstanceOf(BridgeError);
-    expect(failure).not.toBeInstanceOf(HostRunNotActiveError);
-  });
-});
-
-// -- unit: read-only + catalog + dispose ----------------------------------------
-
-describe('BridgeAgentHost read-only and catalog', () => {
-  it('read-only: mutating methods throw HostReadOnlyError, catalog falls back, dispose works', async () => {
-    const stub = stubClient();
-    const { host, input } = hostWith(stub, READ_ONLY_SELECTION);
-    await expect(host.start(input)).rejects.toBeInstanceOf(HostReadOnlyError);
-    await expect(host.steer('r', 'm')).rejects.toBeInstanceOf(HostReadOnlyError);
-    await expect(host.catalog()).resolves.toBe(FALLBACK);
-    expect(stub.requests).toHaveLength(0);
-    await host.dispose();
-    expect(stub.stop).toHaveBeenCalled();
-  });
-
-  it('catalog goes through the bridge and caches per hello catalogHash', async () => {
-    const stub = stubClient();
-    const { host } = hostWith(stub);
-    const first = await host.catalog();
-    const second = await host.catalog();
-    expect(first).toEqual(second);
-    expect(stub.requests.filter((r) => r.method === 'catalog')).toHaveLength(1);
-    // A new handshake hash busts the cache.
-    (stub.client as { hello: { catalogHash: string; sdkVersion: string } }).hello = { catalogHash: 'h2', sdkVersion: '1.0.0' };
-    await host.catalog();
-    expect(stub.requests.filter((r) => r.method === 'catalog')).toHaveLength(2);
-  });
-
-  it('dispose unsubscribes every run and stops the client', async () => {
-    const stub = stubClient();
-    const { host, input } = hostWith(stub);
-    await host.start(input);
-    expect(stub.pushes.size).toBe(1);
-    await host.dispose();
-    expect(stub.pushes.size).toBe(0);
-    expect(stub.stop).toHaveBeenCalledTimes(1);
-  });
-});
-
-// -- integration: the real built bridge -----------------------------------------
-
-const REPO_ROOT = fileURLToPath(new URL('../../../../', import.meta.url));
-const SDK_DIST = path.join(REPO_ROOT, 'dist', 'cli', 'bridge.mjs');
-const SCRIPTED_PROVIDER = fileURLToPath(new URL('./fixtures/scriptedProvider.mjs', import.meta.url));
-
-interface RealBridge {
-  host: BridgeAgentHost;
-  client: BridgeClient;
-  root: string;
-  events: HostEvent[];
-  stop(): Promise<void>;
-}
-
-async function realBridge(turns: unknown): Promise<RealBridge> {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'lou-w11b-real-'));
-  const nm = path.join(root, 'node_modules');
-  fs.mkdirSync(nm, { recursive: true });
-  fs.symlinkSync(REPO_ROOT, path.join(nm, 'lousho'), 'junction');
-  const sdk = findWorkspaceSdk(root);
-  if (sdk === undefined) throw new Error('junction workspace did not resolve the SDK');
-  const client = new BridgeClient(
-    {
-      command: process.execPath,
-      args: ['--import', pathToFileURL(SCRIPTED_PROVIDER).href, sdk.binPath, 'bridge'],
-      cwd: root,
-      env: { ...process.env, LOUSHO_BRIDGE: '1', SCRIPTED_TURNS: JSON.stringify(turns) },
-      label: 'w11b-real',
-    },
-    { clientVersion: 'w11b-test', stderr: () => undefined }
-  );
-  const host = new BridgeAgentHost(client, {
-    secretsStore,
-    ready: async () => BRIDGE_SELECTION,
-    fallbackCatalog: async () => FALLBACK,
-    sdk,
-  });
-  const events: HostEvent[] = [];
-  return {
-    host,
-    client,
-    root,
-    events,
-    stop: async () => {
-      await host.dispose();
-      fs.rmSync(root, { recursive: true, force: true });
-    },
-  };
-}
-
-function inputFor(events: HostEvent[], spec: AgentSpecV2, input: HostRunInput['input']): HostRunInput {
-  return { agentId: 'agent1', spec, sessionId: 's1', input, onEvent: (e) => events.push(e) };
-}
-
-async function waitFor(predicate: () => boolean, what: string, timeoutMs = 30_000): Promise<void> {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    if (predicate()) return;
-    await new Promise((r) => setTimeout(r, 50));
-  }
-  throw new Error(`timed out waiting for ${what}`);
-}
-
-const settledEvents = (events: HostEvent[]) => events.filter((e) => e.type === 'settled');
-
-describe('BridgeAgentHost against the real bridge', () => {
-  beforeEach(() => {
-    if (!fs.existsSync(SDK_DIST)) {
-      throw new Error('dist/cli/bridge.mjs missing - run npm run build at the repo root first');
-    }
-  });
-
-  it('runs a scripted spec end to end: agent, span and settled HostEvents', async () => {
-    const b = await realBridge(['ok']);
-    try {
-      const spec: AgentSpecV2 = { ...SPEC, model: 'scripted/x' };
-      const run = await b.host.start(inputFor(b.events, spec, 'hello'));
-      expect(run.runId).toBeTruthy();
-      await waitFor(() => settledEvents(b.events).length > 0, 'run.settled');
-      const types = b.events.map((e) => e.type);
-      expect(types).toContain('agent');
-      expect(types).toContain('span');
-      const settled = settledEvents(b.events)[0]!;
-      expect(settled.type === 'settled' && settled.result.finishReason).toBe('stop');
-      expect(settled.type === 'settled' && settled.result.text).toBe('ok');
-    } finally {
-      await b.stop();
-    }
-  });
-
-  it('pauses on an asked permission, then resolveApproval settles the continuation', async () => {
-    const b = await realBridge([{ toolCalls: [{ name: 'current_date', args: {} }] }, 'after approval']);
-    try {
-      const spec: AgentSpecV2 = {
-        ...SPEC,
-        model: 'scripted/x',
-        tools: [{ builtin: 'current_date' }],
-        permissions: [{ id: 'p1', tool: 'current_date', action: 'ask' }],
-      };
-      const run = await b.host.start(inputFor(b.events, spec, 'hi'));
-      await waitFor(() => settledEvents(b.events).length > 0, 'first settle');
-      const paused = settledEvents(b.events)[0]!;
-      expect(paused.type === 'settled' && paused.result.finishReason).toBe('awaiting-approval');
-      const pending = paused.type === 'settled' ? paused.result.pendingApproval : undefined;
-      expect(pending).toBeDefined();
-      const approvalId = (pending as { id: string }).id;
-
-      await b.host.resolveApproval(run.runId, approvalId, { approved: true });
-      await waitFor(() => settledEvents(b.events).length > 1, 'continuation settle');
-      const done = settledEvents(b.events)[1]!;
-      expect(done.type === 'settled' && done.result.finishReason).toBe('stop');
-      expect(done.type === 'settled' && done.result.text).toBe('after approval');
-    } finally {
-      await b.stop();
-    }
-  });
-
-  it('abort winds a live run down to an aborted settle', async () => {
-    const b = await realBridge([{ text: 'thinking', delayMs: 30_000 }]);
-    try {
-      const spec: AgentSpecV2 = { ...SPEC, model: 'scripted/x' };
-      const run = await b.host.start(inputFor(b.events, spec, 'hi'));
-      // The scripted turn delays 30 s; abort well inside that window.
-      await new Promise((r) => setTimeout(r, 200));
-      await b.host.abort(run.runId, 'user');
-      await waitFor(() => settledEvents(b.events).length > 0, 'aborted settle', 15_000);
-      const settled = settledEvents(b.events)[0]!;
-      expect(settled.type === 'settled' && settled.result.finishReason).toBe('aborted');
-    } finally {
-      await b.stop();
-    }
-  });
-});
+/**
+ * W11b: `BridgeAgentHost` - the `AgentHost` over `lousho bridge`.
+ *
+ * Unit half: a stub `BridgeClient` pins the request/push mapping,
+ * secrets/env params, error translation and the read-only gate.
+ * Integration half: a temp workspace whose `node_modules/lousho` is a
+ * junction to this repo runs the REAL built bridge (`dist/cli/bridge.mjs`)
+ * with the `scripted` provider preloaded.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from 'vitest';
+import type { AgentSpecV2, BridgePush, Message } from '@linuxdevil/lousho';
+import { BridgeAgentHost, HostReadOnlyError, HostStartError } from '../host/bridgeAgentHost';
+import { BridgeClient, BridgeError } from '../host/bridgeClient';
+import { HostRunNotActiveError } from '../host/agentHost';
+import type { HostCatalog, HostEvent, HostRunInput } from '../host/agentHost';
+import type { HostSelection } from '../host/hostSelector';
+import { findWorkspaceSdk, type WorkspaceSdk } from '../host/workspaceSdk';
+import { SecretsStore } from '../secretsStore';
+
+const SPEC: AgentSpecV2 = { version: 2, name: 'a', model: 'mock/m', instructions: 'Be brief.' };
+const SDK: WorkspaceSdk = { version: '1.0.0', packageDir: '/sdk', binPath: '/sdk/bin/lousho.js', source: 'node_modules', built: true };
+const BRIDGE_SELECTION: HostSelection = { mode: 'bridge', sdk: SDK, sdkVersion: '1.0.0', banner: null };
+const READ_ONLY_SELECTION: HostSelection = {
+  mode: 'read-only',
+  sdk: SDK,
+  sdkVersion: '1.0.0',
+  banner: { tone: 'warning', text: 'read-only for tests' },
+};
+const FALLBACK: HostCatalog = { tools: [], models: [], guardrails: [], triggers: [] };
+
+let dir: string;
+let secretsDir: string;
+let secretsStore: SecretsStore;
+
+beforeEach(() => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'lou-w11b-host-'));
+  secretsDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lou-w11b-hsec-'));
+  secretsStore = new SecretsStore(secretsDir);
+});
+
+afterEach(() => {
+  fs.rmSync(dir, { recursive: true, force: true });
+  fs.rmSync(secretsDir, { recursive: true, force: true });
+});
+
+// -- stub client -------------------------------------------------------------
+
+interface Stub {
+  client: BridgeClient;
+  requests: Array<{ method: string; params: unknown }>;
+  pushes: Map<string, (push: BridgePush) => void>;
+  emit(runId: string, push: BridgePush): void;
+  stop: Mock<[], Promise<void>>;
+}
+
+function stubClient(options: { hello?: { catalogHash: string; sdkVersion: string }; respond?: (method: string, params: unknown) => unknown; reject?: (method: string) => Error | undefined } = {}): Stub {
+  const requests: Stub['requests'] = [];
+  const pushes = new Map<string, (push: BridgePush) => void>();
+  const stop = vi.fn<[], Promise<void>>(async () => undefined);
+  const client = {
+    hello: options.hello ?? { catalogHash: 'h1', sdkVersion: '1.0.0' },
+    request: vi.fn(async (method: string, params: unknown) => {
+      requests.push({ method, params });
+      const failure = options.reject?.(method);
+      if (failure !== undefined) throw failure;
+      return (
+        options.respond?.(method, params) ??
+        (method === 'run' || method === 'chat'
+          ? { runId: 'run-1', modelLabel: 'mock/m' }
+          : method === 'catalog'
+            ? { tools: [], models: [], guardrails: [], triggers: [] }
+            : method === 'abort'
+              ? { state: 'aborting' }
+              : { ok: true })
+      );
+    }),
+    onPush: vi.fn((runId: string, listener: (push: BridgePush) => void) => {
+      pushes.set(runId, listener);
+      return () => pushes.delete(runId);
+    }),
+    stop,
+  } as unknown as BridgeClient;
+  return { client, requests, pushes, emit: (runId, push) => pushes.get(runId)?.(push), stop };
+}
+
+function hostWith(stub: Stub, selection: HostSelection = BRIDGE_SELECTION): { host: BridgeAgentHost; events: HostEvent[]; input: HostRunInput } {
+  const events: HostEvent[] = [];
+  const host = new BridgeAgentHost(stub.client, {
+    secretsStore,
+    ready: async () => selection,
+    fallbackCatalog: async () => FALLBACK,
+    sdk: SDK,
+  });
+  const input: HostRunInput = { agentId: 'agent1', spec: SPEC, sessionId: 's1', input: 'hello', onEvent: (e) => events.push(e) };
+  return { host, events, input };
+}
+
+const settledPush = (runId: string, finishReason = 'stop'): BridgePush =>
+  ({ event: 'run.settled', runId, data: { finishReason, text: 'done' } }) as BridgePush;
+
+// -- unit: start / pushes ------------------------------------------------------
+
+describe('BridgeAgentHost.start', () => {
+  it('sends run params and maps pushes to HostEvents until the terminal settle', async () => {
+    const stub = stubClient();
+    const { host, events, input } = hostWith(stub);
+    const run = await host.start(input);
+    expect(run).toEqual({ runId: 'run-1', modelLabel: 'mock/m' });
+    expect(stub.requests).toHaveLength(1);
+    expect(stub.requests[0]).toMatchObject({
+      method: 'run',
+      params: { agentId: 'agent1', spec: SPEC, sessionId: 's1', input: 'hello' },
+    });
+    expect(stub.pushes.has('run-1')).toBe(true);
+
+    stub.emit('run-1', { event: 'agent', runId: 'run-1', data: { type: 'text-delta', text: 'hi' } } as unknown as BridgePush);
+    stub.emit('run-1', { event: 'span.start', runId: 'run-1', data: { id: 'sp1' } } as unknown as BridgePush);
+    stub.emit('run-1', { event: 'span.end', runId: 'run-1', data: { id: 'sp1' } } as unknown as BridgePush);
+    stub.emit('run-1', settledPush('run-1'));
+    expect(events.map((e) => e.type)).toEqual(['agent', 'span', 'span', 'settled']);
+    // Terminal settle unsubscribes: later pushes for the run go nowhere.
+    expect(stub.pushes.has('run-1')).toBe(false);
+    stub.emit('run-1', settledPush('run-1'));
+    expect(events).toHaveLength(4);
+  });
+
+  it('keeps the subscription across an awaiting-approval settle', async () => {
+    const stub = stubClient();
+    const { host, input } = hostWith(stub);
+    await host.start(input);
+    stub.emit('run-1', settledPush('run-1', 'awaiting-approval'));
+    expect(stub.pushes.has('run-1')).toBe(true);
+  });
+
+  it('uses chat with Message[] input and TypeErrors on ContentPart[]', async () => {
+    const stub = stubClient();
+    const { host, input } = hostWith(stub);
+    const messages: Message[] = [
+      { role: 'user', content: 'one' },
+      { role: 'assistant', content: 'two' },
+      { role: 'user', content: 'three' },
+    ];
+    await host.start({ ...input, input: messages });
+    expect(stub.requests[0]).toMatchObject({ method: 'chat', params: { messages } });
+
+    const stub2 = stubClient();
+    const { host: host2 } = hostWith(stub2);
+    await expect(
+      host2.start({ ...input, input: [{ type: 'text', text: 'parts' }] as never })
+    ).rejects.toBeInstanceOf(TypeError);
+    expect(stub2.requests).toHaveLength(0);
+  });
+
+  it('sends named secrets and provider env, omitting unset values', async () => {
+    secretsStore.setSecret('GH', 'ghp_x');
+    secretsStore.setKey('openai', 'sk-test');
+    const spec: AgentSpecV2 = {
+      ...SPEC,
+      mcpServers: { api: { url: 'https://x.test/mcp', headers: { Authorization: { secret: 'GH' }, Missing: { secret: 'NOPE' } } } } as AgentSpecV2['mcpServers'],
+    };
+    const stub = stubClient();
+    const { host, input } = hostWith(stub);
+    await host.start({ ...input, spec });
+    const params = stub.requests[0]!.params as { secrets?: Record<string, string>; env?: Record<string, string> };
+    expect(params.secrets).toEqual({ GH: 'ghp_x' });
+    expect(params.env).toEqual({ OPENAI_API_KEY: 'sk-test' });
+  });
+
+  it('sends no secrets/env keys when the spec has no refs and no keys are stored', async () => {
+    const stub = stubClient();
+    const { host, input } = hostWith(stub);
+    await host.start(input);
+    const params = stub.requests[0]!.params as Record<string, unknown>;
+    expect(params).not.toHaveProperty('secrets');
+    expect(params).not.toHaveProperty('env');
+  });
+
+  it('wraps start failures in HostStartError with the bridge code', async () => {
+    const stub = stubClient({ reject: () => new BridgeError('boom', 'LOUSHO_BRIDGE_CRASHED') });
+    const { host, input } = hostWith(stub);
+    const failure = await host.start(input).catch((e: unknown) => e);
+    expect(failure).toBeInstanceOf(HostStartError);
+    expect((failure as HostStartError).code).toBe('LOUSHO_BRIDGE_CRASHED');
+  });
+});
+
+// -- unit: run controls ---------------------------------------------------------
+
+describe('BridgeAgentHost run controls', () => {
+  it('steer/abort/resolveApproval/answerQuestion send the bridge params', async () => {
+    const stub = stubClient({ respond: (m) => (m === 'abort' ? { state: 'discarded' } : m === 'steer' ? { id: 'st1', applied: 'immediate' } : { ok: true }) });
+    const { host } = hostWith(stub);
+    await host.start({ agentId: 'a', spec: SPEC, sessionId: 's', input: 'hi', onEvent: () => {} });
+    await expect(host.steer('run-1', 'more')).resolves.toEqual({ id: 'st1', applied: 'immediate' });
+    await host.abort('run-1', 'user');
+    await host.resolveApproval('run-1', 'ap1', { approved: true, note: 'n' });
+    await host.answerQuestion('run-1', 'q1', 'yes');
+    expect(stub.requests.map((r) => r.method)).toEqual(['run', 'steer', 'abort', 'resolveApproval', 'answerQuestion']);
+    expect(stub.requests[1]!.params).toEqual({ runId: 'run-1', message: 'more' });
+    expect(stub.requests[2]!.params).toEqual({ runId: 'run-1', reason: 'user' });
+    expect(stub.requests[3]!.params).toEqual({ runId: 'run-1', approvalId: 'ap1', approved: true, note: 'n' });
+    expect(stub.requests[4]!.params).toEqual({ runId: 'run-1', questionId: 'q1', answer: 'yes' });
+    // 'discarded' abort unsubscribed the run's push listener.
+    expect(stub.pushes.has('run-1')).toBe(false);
+  });
+
+  it.each(['LOUSHO_NO_ACTIVE_RUN', 'LOUSHO_BRIDGE_RUN_NOT_FOUND', 'LOUSHO_APPROVAL_NOT_FOUND'])(
+    'maps %s to HostRunNotActiveError',
+    async (code) => {
+      const stub = stubClient({ reject: () => new BridgeError('gone', code) });
+      const { host } = hostWith(stub);
+      await expect(host.steer('run-1', 'x')).rejects.toBeInstanceOf(HostRunNotActiveError);
+      await expect(host.abort('run-1')).rejects.toBeInstanceOf(HostRunNotActiveError);
+      await expect(host.resolveApproval('run-1', 'a', { approved: true })).rejects.toBeInstanceOf(HostRunNotActiveError);
+      await expect(host.answerQuestion('run-1', 'q', 'a')).rejects.toBeInstanceOf(HostRunNotActiveError);
+    }
+  );
+
+  it('leaves other bridge errors unmapped', async () => {
+    const stub = stubClient({ reject: () => new BridgeError('bad', 'LOUSHO_BRIDGE_TIMEOUT') });
+    const { host } = hostWith(stub);
+    const failure = await host.steer('run-1', 'x').catch((e: unknown) => e);
+    expect(failure).toBeInstanceOf(BridgeError);
+    expect(failure).not.toBeInstanceOf(HostRunNotActiveError);
+  });
+});
+
+// -- unit: read-only + catalog + dispose ----------------------------------------
+
+describe('BridgeAgentHost read-only and catalog', () => {
+  it('read-only: mutating methods throw HostReadOnlyError, catalog falls back, dispose works', async () => {
+    const stub = stubClient();
+    const { host, input } = hostWith(stub, READ_ONLY_SELECTION);
+    await expect(host.start(input)).rejects.toBeInstanceOf(HostReadOnlyError);
+    await expect(host.steer('r', 'm')).rejects.toBeInstanceOf(HostReadOnlyError);
+    await expect(host.catalog()).resolves.toBe(FALLBACK);
+    expect(stub.requests).toHaveLength(0);
+    await host.dispose();
+    expect(stub.stop).toHaveBeenCalled();
+  });
+
+  it('catalog goes through the bridge and caches per hello catalogHash', async () => {
+    const stub = stubClient();
+    const { host } = hostWith(stub);
+    const first = await host.catalog();
+    const second = await host.catalog();
+    expect(first).toEqual(second);
+    expect(stub.requests.filter((r) => r.method === 'catalog')).toHaveLength(1);
+    // A new handshake hash busts the cache.
+    (stub.client as { hello: { catalogHash: string; sdkVersion: string } }).hello = { catalogHash: 'h2', sdkVersion: '1.0.0' };
+    await host.catalog();
+    expect(stub.requests.filter((r) => r.method === 'catalog')).toHaveLength(2);
+  });
+
+  it('dispose unsubscribes every run and stops the client', async () => {
+    const stub = stubClient();
+    const { host, input } = hostWith(stub);
+    await host.start(input);
+    expect(stub.pushes.size).toBe(1);
+    await host.dispose();
+    expect(stub.pushes.size).toBe(0);
+    expect(stub.stop).toHaveBeenCalledTimes(1);
+  });
+});
+
+// -- integration: the real built bridge -----------------------------------------
+
+const REPO_ROOT = fileURLToPath(new URL('../../../../', import.meta.url));
+const SDK_DIST = path.join(REPO_ROOT, 'dist', 'cli', 'bridge.mjs');
+const SCRIPTED_PROVIDER = fileURLToPath(new URL('./fixtures/scriptedProvider.mjs', import.meta.url));
+
+interface RealBridge {
+  host: BridgeAgentHost;
+  client: BridgeClient;
+  root: string;
+  events: HostEvent[];
+  stop(): Promise<void>;
+}
+
+async function realBridge(turns: unknown): Promise<RealBridge> {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'lou-w11b-real-'));
+  const nm = path.join(root, 'node_modules');
+  fs.mkdirSync(nm, { recursive: true });
+  fs.mkdirSync(path.join(nm, '@linuxdevil'), { recursive: true });
+  fs.symlinkSync(REPO_ROOT, path.join(nm, '@linuxdevil', 'lousho'), 'junction');
+  const sdk = findWorkspaceSdk(root);
+  if (sdk === undefined) throw new Error('junction workspace did not resolve the SDK');
+  const client = new BridgeClient(
+    {
+      command: process.execPath,
+      args: ['--import', pathToFileURL(SCRIPTED_PROVIDER).href, sdk.binPath, 'bridge'],
+      cwd: root,
+      env: { ...process.env, LOUSHO_BRIDGE: '1', SCRIPTED_TURNS: JSON.stringify(turns) },
+      label: 'w11b-real',
+    },
+    { clientVersion: 'w11b-test', stderr: () => undefined }
+  );
+  const host = new BridgeAgentHost(client, {
+    secretsStore,
+    ready: async () => BRIDGE_SELECTION,
+    fallbackCatalog: async () => FALLBACK,
+    sdk,
+  });
+  const events: HostEvent[] = [];
+  return {
+    host,
+    client,
+    root,
+    events,
+    stop: async () => {
+      await host.dispose();
+      fs.rmSync(root, { recursive: true, force: true });
+    },
+  };
+}
+
+function inputFor(events: HostEvent[], spec: AgentSpecV2, input: HostRunInput['input']): HostRunInput {
+  return { agentId: 'agent1', spec, sessionId: 's1', input, onEvent: (e) => events.push(e) };
+}
+
+async function waitFor(predicate: () => boolean, what: string, timeoutMs = 30_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (predicate()) return;
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  throw new Error(`timed out waiting for ${what}`);
+}
+
+const settledEvents = (events: HostEvent[]) => events.filter((e) => e.type === 'settled');
+
+describe('BridgeAgentHost against the real bridge', () => {
+  beforeEach(() => {
+    if (!fs.existsSync(SDK_DIST)) {
+      throw new Error('dist/cli/bridge.mjs missing - run npm run build at the repo root first');
+    }
+  });
+
+  it('runs a scripted spec end to end: agent, span and settled HostEvents', async () => {
+    const b = await realBridge(['ok']);
+    try {
+      const spec: AgentSpecV2 = { ...SPEC, model: 'scripted/x' };
+      const run = await b.host.start(inputFor(b.events, spec, 'hello'));
+      expect(run.runId).toBeTruthy();
+      await waitFor(() => settledEvents(b.events).length > 0, 'run.settled');
+      const types = b.events.map((e) => e.type);
+      expect(types).toContain('agent');
+      expect(types).toContain('span');
+      const settled = settledEvents(b.events)[0]!;
+      expect(settled.type === 'settled' && settled.result.finishReason).toBe('stop');
+      expect(settled.type === 'settled' && settled.result.text).toBe('ok');
+    } finally {
+      await b.stop();
+    }
+  });
+
+  it('pauses on an asked permission, then resolveApproval settles the continuation', async () => {
+    const b = await realBridge([{ toolCalls: [{ name: 'current_date', args: {} }] }, 'after approval']);
+    try {
+      const spec: AgentSpecV2 = {
+        ...SPEC,
+        model: 'scripted/x',
+        tools: [{ builtin: 'current_date' }],
+        permissions: [{ id: 'p1', tool: 'current_date', action: 'ask' }],
+      };
+      const run = await b.host.start(inputFor(b.events, spec, 'hi'));
+      await waitFor(() => settledEvents(b.events).length > 0, 'first settle');
+      const paused = settledEvents(b.events)[0]!;
+      expect(paused.type === 'settled' && paused.result.finishReason).toBe('awaiting-approval');
+      const pending = paused.type === 'settled' ? paused.result.pendingApproval : undefined;
+      expect(pending).toBeDefined();
+      const approvalId = (pending as { id: string }).id;
+
+      await b.host.resolveApproval(run.runId, approvalId, { approved: true });
+      await waitFor(() => settledEvents(b.events).length > 1, 'continuation settle');
+      const done = settledEvents(b.events)[1]!;
+      expect(done.type === 'settled' && done.result.finishReason).toBe('stop');
+      expect(done.type === 'settled' && done.result.text).toBe('after approval');
+    } finally {
+      await b.stop();
+    }
+  });
+
+  it('abort winds a live run down to an aborted settle', async () => {
+    const b = await realBridge([{ text: 'thinking', delayMs: 30_000 }]);
+    try {
+      const spec: AgentSpecV2 = { ...SPEC, model: 'scripted/x' };
+      const run = await b.host.start(inputFor(b.events, spec, 'hi'));
+      // The scripted turn delays 30 s; abort well inside that window.
+      await new Promise((r) => setTimeout(r, 200));
+      await b.host.abort(run.runId, 'user');
+      await waitFor(() => settledEvents(b.events).length > 0, 'aborted settle', 15_000);
+      const settled = settledEvents(b.events)[0]!;
+      expect(settled.type === 'settled' && settled.result.finishReason).toBe('aborted');
+    } finally {
+      await b.stop();
+    }
+  });
+});
diff --git a/apps/agent-forge/server/__tests__/bridgeClient.test.ts b/apps/agent-forge/server/__tests__/bridgeClient.test.ts
index 9e91fec27..020dad233 100644
--- a/apps/agent-forge/server/__tests__/bridgeClient.test.ts
+++ b/apps/agent-forge/server/__tests__/bridgeClient.test.ts
@@ -3,7 +3,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { afterEach, describe, expect, it } from 'vitest';
-import type { BridgePush } from 'lousho';
+import type { BridgePush } from '@linuxdevil/lousho';
 import { BridgeClient, type BridgeState } from '../host/bridgeClient';
 
 const FAKE_BRIDGE = fileURLToPath(new URL('../host/__tests__/fakeBridge.mjs', import.meta.url));
diff --git a/apps/agent-forge/server/__tests__/bridgeGuards.test.ts b/apps/agent-forge/server/__tests__/bridgeGuards.test.ts
index d17cc9bfd..928615075 100644
--- a/apps/agent-forge/server/__tests__/bridgeGuards.test.ts
+++ b/apps/agent-forge/server/__tests__/bridgeGuards.test.ts
@@ -12,7 +12,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import type { Express } from 'express';
 import request from 'supertest';
-import { upgradeSpec, type AgentSpec } from 'lousho';
+import { upgradeSpec, type AgentSpec } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import {
   createWorkspaceContext,
diff --git a/apps/agent-forge/server/__tests__/buildAgentV2.test.ts b/apps/agent-forge/server/__tests__/buildAgentV2.test.ts
index 01379255d..3679af014 100644
--- a/apps/agent-forge/server/__tests__/buildAgentV2.test.ts
+++ b/apps/agent-forge/server/__tests__/buildAgentV2.test.ts
@@ -14,7 +14,7 @@ import {
   createAgentConfigOf,
   type AgentEvent,
   type AgentSpecV2,
-} from 'lousho';
+} from '@linuxdevil/lousho';
 type Global = { __hookOrder?: string[] };
 import { buildRunnableAgent, scopedApprovalStore, type RunWiring } from '../buildAgentV2';
 import { FileApprovalStore } from '../approvalStore';
diff --git a/apps/agent-forge/server/__tests__/builderReporting.test.ts b/apps/agent-forge/server/__tests__/builderReporting.test.ts
index ae95784d6..4e2a715d1 100644
--- a/apps/agent-forge/server/__tests__/builderReporting.test.ts
+++ b/apps/agent-forge/server/__tests__/builderReporting.test.ts
@@ -8,7 +8,7 @@ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
 import { agentTraceDir } from '../traceStore';
diff --git a/apps/agent-forge/server/__tests__/catalogRoutes.test.ts b/apps/agent-forge/server/__tests__/catalogRoutes.test.ts
index 61a7ca423..6d6b12d59 100644
--- a/apps/agent-forge/server/__tests__/catalogRoutes.test.ts
+++ b/apps/agent-forge/server/__tests__/catalogRoutes.test.ts
@@ -4,7 +4,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import express, { type Express } from 'express';
 import request from 'supertest';
-import { listBuiltinTools, listGuardrails, listModels, listTriggerTypes } from 'lousho';
+import { listBuiltinTools, listGuardrails, listModels, listTriggerTypes } from '@linuxdevil/lousho';
 import { registerCatalogRoutes } from '../routes/catalogRoutes';
 import { SecretsStore } from '../secretsStore';
 import { sdkRootDir } from '../sdkRoot';
diff --git a/apps/agent-forge/server/__tests__/chainTriggers.test.ts b/apps/agent-forge/server/__tests__/chainTriggers.test.ts
index 0256531ce..2c9bc3a9d 100644
--- a/apps/agent-forge/server/__tests__/chainTriggers.test.ts
+++ b/apps/agent-forge/server/__tests__/chainTriggers.test.ts
@@ -2,8 +2,8 @@ import { EventEmitter } from 'node:events';
 
 import { describe, expect, it, vi } from 'vitest';
 
-import type { AgentSpecV2 } from 'lousho';
-import type { TriggerSpec } from 'lousho/spec';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
+import type { TriggerSpec } from '@linuxdevil/lousho/spec';
 
 import type { AgentRepo } from '../storage/agentRepo';
 import type { RunManager } from '../runRegistry';
diff --git a/apps/agent-forge/server/__tests__/channelTriggers.test.ts b/apps/agent-forge/server/__tests__/channelTriggers.test.ts
index 53b712dab..4b51953e0 100644
--- a/apps/agent-forge/server/__tests__/channelTriggers.test.ts
+++ b/apps/agent-forge/server/__tests__/channelTriggers.test.ts
@@ -11,9 +11,9 @@ import * as path from 'node:path';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import express, { type Express } from 'express';
 import request from 'supertest';
-import { createAgent, type AgentSpecV2, type SimpleAgent } from 'lousho';
-import { mockModel } from 'lousho/testing';
-import type { SecretRef, TriggerSpec } from 'lousho/spec';
+import { createAgent, type AgentSpecV2, type SimpleAgent } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
+import type { SecretRef, TriggerSpec } from '@linuxdevil/lousho/spec';
 
 import { AgentRepo } from '../storage/agentRepo';
 import { DraftStore } from '../storage/draftStore';
@@ -31,7 +31,7 @@ import type { CronTriggers } from '../triggers/cronTriggers';
 import type { WorkspaceContext } from '../workspace/context';
 import type { WorkspaceHostSelector } from '../host/hostSelector';
 import { workspaceRefFor } from '../workspace/workspaceId';
-import { TriggerRegistry } from 'lousho/triggers';
+import { TriggerRegistry } from '@linuxdevil/lousho/triggers';
 import {
   CHANNEL_SECRET_KEYS,
   ChannelTriggers,
diff --git a/apps/agent-forge/server/__tests__/chat.test.ts b/apps/agent-forge/server/__tests__/chat.test.ts
index 84fa86c82..6bc3a023f 100644
--- a/apps/agent-forge/server/__tests__/chat.test.ts
+++ b/apps/agent-forge/server/__tests__/chat.test.ts
@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import request from 'supertest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { RunManager, AlreadyRunningError, ApprovalPendingError } from '../runRegistry';
 import { newTestHost } from './testHost';
diff --git a/apps/agent-forge/server/__tests__/chatReconcile.test.ts b/apps/agent-forge/server/__tests__/chatReconcile.test.ts
index 0658e0b18..301193905 100644
--- a/apps/agent-forge/server/__tests__/chatReconcile.test.ts
+++ b/apps/agent-forge/server/__tests__/chatReconcile.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import type { Message } from 'lousho';
+import type { Message } from '@linuxdevil/lousho';
 import { reconcileChatMessages, markSteerInputs } from '../chatReconcile';
 import type { ChatMessage, SteerInfo } from '../../shared/wireTypes';
 
diff --git a/apps/agent-forge/server/__tests__/checkpointStore.test.ts b/apps/agent-forge/server/__tests__/checkpointStore.test.ts
index 38070e038..2cadda077 100644
--- a/apps/agent-forge/server/__tests__/checkpointStore.test.ts
+++ b/apps/agent-forge/server/__tests__/checkpointStore.test.ts
@@ -7,8 +7,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import { FileCheckpointStore } from '../checkpointStore';
-import type { Checkpoint } from 'lousho';
-// eslint-disable-next-line lousho/no-sdk-source -- the SDK's shared CheckpointStore contract suite; this test runs only in the SDK repo
+import type { Checkpoint } from '@linuxdevil/lousho';
+// eslint-disable-next-line @linuxdevil/lousho/no-sdk-source -- the SDK's shared CheckpointStore contract suite; this test runs only in the SDK repo
 import { describeCheckpointHistoryContract } from '../../../../src/execution/__fixtures__/checkpointHistoryContract';
 
 const dirs: string[] = [];
diff --git a/apps/agent-forge/server/__tests__/cli.test.ts b/apps/agent-forge/server/__tests__/cli.test.ts
new file mode 100644
index 000000000..ef7b2af29
--- /dev/null
+++ b/apps/agent-forge/server/__tests__/cli.test.ts
@@ -0,0 +1,125 @@
+/**
+ * `lousho-studio` argument parsing and a real boot of `server/cli.ts`.
+ */
+import { afterEach, describe, expect, it } from 'vitest';
+import { spawn, type ChildProcess } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseStudioCliArgs, StudioCliUsageError, studioVersion, USAGE } from '../cli';
+
+const APP_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+describe('parseStudioCliArgs', () => {
+  it('parses the documented flags', () => {
+    expect(parseStudioCliArgs(['--workspace', '/tmp/x', '--port', '5000', '--host', '0.0.0.0'])).toEqual({
+      workspace: '/tmp/x',
+      port: 5000,
+      host: '0.0.0.0',
+    });
+    expect(parseStudioCliArgs(['--port=0'])).toEqual({ port: 0 });
+    expect(parseStudioCliArgs(['-v'])).toEqual({ version: true });
+    expect(parseStudioCliArgs(['-h'])).toEqual({ help: true });
+    expect(parseStudioCliArgs([])).toEqual({});
+  });
+
+  it('rejects unknown flags, missing values and bad ports', () => {
+    for (const argv of [['--bogus'], ['--port'], ['--workspace'], ['positional']]) {
+      expect(() => parseStudioCliArgs(argv)).toThrow(StudioCliUsageError);
+    }
+    for (const port of ['x', '-1', '1.5', '70000']) {
+      expect(() => parseStudioCliArgs(['--port', port])).toThrow(StudioCliUsageError);
+    }
+    expect(() => parseStudioCliArgs(['--port', 'x'])).toThrow(/--port must be an integer between 0 and 65535/);
+  });
+});
+
+describe('studioVersion', () => {
+  it('reads the package version relative to the module dir', () => {
+    const version = studioVersion(path.join(APP_DIR, 'server'));
+    expect(version).toMatch(/^\d+\.\d+\.\d+/);
+    const pkg = JSON.parse(fs.readFileSync(path.join(APP_DIR, 'package.json'), 'utf8')) as { version: string };
+    expect(version).toBe(pkg.version);
+  });
+});
+
+describe('lousho-studio boot', () => {
+  let child: ChildProcess | undefined;
+  let tmp: string | undefined;
+
+  afterEach(async () => {
+    if (child && child.exitCode === null) {
+      child.kill('SIGTERM');
+      await new Promise((resolve) => child!.once('exit', resolve));
+    }
+    child = undefined;
+    if (tmp) fs.rmSync(tmp, { recursive: true, force: true });
+    tmp = undefined;
+  });
+
+  it('--help exits 0 with usage; bad args exit 2', async () => {
+    const run = (args: string[]) =>
+      new Promise<{ code: number | null; stdout: string; stderr: string }>((resolve) => {
+        const p = spawn(process.execPath, ['--import', 'tsx', path.join(APP_DIR, 'server', 'cli.ts'), ...args], {
+          cwd: APP_DIR,
+          env: { ...process.env, LOUSHO_STUDIO_COLLECTOR: '0', LOUSHO_STUDIO_JUDGE: '0' },
+        });
+        let stdout = '';
+        let stderr = '';
+        p.stdout!.on('data', (d) => (stdout += d));
+        p.stderr!.on('data', (d) => (stderr += d));
+        p.on('exit', (code) => resolve({ code, stdout, stderr }));
+      });
+    const help = await run(['--help']);
+    expect(help.code).toBe(0);
+    expect(help.stdout).toContain('Usage: lousho-studio');
+    expect(USAGE).toContain('--workspace <dir>');
+    const bad = await run(['--port', 'x']);
+    expect(bad.code).toBe(2);
+    expect(bad.stderr).toContain('lousho-studio:');
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'lousho-cli-'));
+    const noFolder = await run(['--workspace', path.join(tmp, 'nope')]);
+    expect(noFolder.code).toBe(2);
+    expect(noFolder.stderr).toContain("is not a folder");
+  }, 60_000);
+
+  it('boots on --port 0, prints the tokened URL, /health answers, SIGTERM exits 0', async () => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'lousho-cli-'));
+    child = spawn(
+      process.execPath,
+      ['--import', 'tsx', path.join(APP_DIR, 'server', 'cli.ts'), '--port', '0', '--workspace', tmp],
+      {
+        cwd: APP_DIR,
+        env: { ...process.env, LOUSHO_STUDIO_COLLECTOR: '0', LOUSHO_STUDIO_JUDGE: '0' },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      }
+    );
+    const url = await new Promise<string>((resolve, reject) => {
+      let out = '';
+      const timer = setTimeout(() => reject(new Error(`timed out waiting for URL; output so far:\n${out}`)), 45_000);
+      child!.stdout!.on('data', (d) => {
+        out += d;
+        const match = /Lousho Studio \S+: (\S+)/.exec(out);
+        if (match) {
+          clearTimeout(timer);
+          resolve(match[1]);
+        }
+      });
+      child!.stderr!.on('data', (d) => (out += d));
+      child!.on('exit', (code) => {
+        clearTimeout(timer);
+        reject(new Error(`cli exited early (${code}); output:\n${out}`));
+      });
+    });
+    expect(url).toContain('/?token=');
+    const health = await fetch(new URL('/health', url)).then((r) => r.text());
+    expect(health).toBe('ok');
+    child.kill('SIGTERM');
+    const code = await new Promise<number | null>((resolve) => child!.once('exit', resolve));
+    // Windows has no POSIX signals: kill() is TerminateProcess there, so the
+    // graceful-shutdown exit code is only observable on POSIX.
+    if (process.platform !== 'win32') expect(code).toBe(0);
+    child = undefined;
+  }, 90_000);
+});
diff --git a/apps/agent-forge/server/__tests__/collector.test.ts b/apps/agent-forge/server/__tests__/collector.test.ts
index 060b6e11d..1fe411e12 100644
--- a/apps/agent-forge/server/__tests__/collector.test.ts
+++ b/apps/agent-forge/server/__tests__/collector.test.ts
@@ -11,7 +11,7 @@ import * as http from 'node:http';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import type { AddressInfo } from 'node:net';
-import { startObserveDaemon, type ObserveDaemon } from 'lousho/observe';
+import { startObserveDaemon, type ObserveDaemon } from '@linuxdevil/lousho/observe';
 import {
   COLLECTOR_TOKEN_SECRET,
   CollectorLockedError,
diff --git a/apps/agent-forge/server/__tests__/copyAgent.test.ts b/apps/agent-forge/server/__tests__/copyAgent.test.ts
index 3bbb10a31..7a245e1ac 100644
--- a/apps/agent-forge/server/__tests__/copyAgent.test.ts
+++ b/apps/agent-forge/server/__tests__/copyAgent.test.ts
@@ -9,7 +9,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
diff --git a/apps/agent-forge/server/__tests__/cronTriggers.test.ts b/apps/agent-forge/server/__tests__/cronTriggers.test.ts
index 08ca2d6be..4df861ec0 100644
--- a/apps/agent-forge/server/__tests__/cronTriggers.test.ts
+++ b/apps/agent-forge/server/__tests__/cronTriggers.test.ts
@@ -4,7 +4,7 @@ import * as path from 'node:path';
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-import type { TriggerSpec } from 'lousho/spec';
+import type { TriggerSpec } from '@linuxdevil/lousho/spec';
 
 import type { DispatchRequest, DispatchResult, TriggerHost } from '../triggers/triggerHost';
 import { CronTriggers, type CronState } from '../triggers/cronTriggers';
diff --git a/apps/agent-forge/server/__tests__/deployPublished.test.ts b/apps/agent-forge/server/__tests__/deployPublished.test.ts
index bf70ec4bd..e43a465ef 100644
--- a/apps/agent-forge/server/__tests__/deployPublished.test.ts
+++ b/apps/agent-forge/server/__tests__/deployPublished.test.ts
@@ -13,7 +13,7 @@ import * as path from 'node:path';
 import type { ChildProcess } from 'node:child_process';
 import { parse as parseYaml } from 'yaml';
 import request from 'supertest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
diff --git a/apps/agent-forge/server/__tests__/deployRunner.test.ts b/apps/agent-forge/server/__tests__/deployRunner.test.ts
index a73d921ca..ba7f71f47 100644
--- a/apps/agent-forge/server/__tests__/deployRunner.test.ts
+++ b/apps/agent-forge/server/__tests__/deployRunner.test.ts
@@ -15,7 +15,7 @@ import type { ChildProcess } from 'node:child_process';
 import { parse as parseYaml } from 'yaml';
 import { publishedSpecPath, runDeploy, writePublishedSpec, DEPLOY_ADAPTERS, isDeployAdapter } from '../deployRunner';
 import { mergeLegacySave } from '../storage/legacySpec';
-import type { AgentSpec } from 'lousho';
+import type { AgentSpec } from '@linuxdevil/lousho';
 
 const V1_SPEC: AgentSpec = {
   name: 'deploy-me',
diff --git a/apps/agent-forge/server/__tests__/draftRoutes.test.ts b/apps/agent-forge/server/__tests__/draftRoutes.test.ts
index 3d8d4a2cf..fb42cdfef 100644
--- a/apps/agent-forge/server/__tests__/draftRoutes.test.ts
+++ b/apps/agent-forge/server/__tests__/draftRoutes.test.ts
@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
-import type { AgentSpec } from 'lousho';
+import type { AgentSpec } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
diff --git a/apps/agent-forge/server/__tests__/draftView.test.ts b/apps/agent-forge/server/__tests__/draftView.test.ts
index b1b6926ca..b9829b33d 100644
--- a/apps/agent-forge/server/__tests__/draftView.test.ts
+++ b/apps/agent-forge/server/__tests__/draftView.test.ts
@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
-import type { AgentSpec } from 'lousho';
+import type { AgentSpec } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
diff --git a/apps/agent-forge/server/__tests__/ejectRoute.test.ts b/apps/agent-forge/server/__tests__/ejectRoute.test.ts
new file mode 100644
index 000000000..871780fb4
--- /dev/null
+++ b/apps/agent-forge/server/__tests__/ejectRoute.test.ts
@@ -0,0 +1,123 @@
+/**
+ * A08b `POST /agents/:id/eject`: writes the agent-directory form
+ * (`specToAgentDir`) to `agents/<id>/` under the workspace root - 200 with
+ * the written paths, 409 `LOUSHO_EJECT_EXISTS` when the folder exists,
+ * `{ overwrite: true }` to replace, 404 for an unknown agent, 400 when a
+ * generated path would escape the target folder.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import request from 'supertest';
+import { specToAgentDir } from '@linuxdevil/lousho/spec';
+import { createApp } from '../app';
+import { RunManager } from '../runRegistry';
+import { newTestHost } from './testHost';
+import { FileCheckpointStore } from '../checkpointStore';
+import { FileApprovalStore } from '../approvalStore';
+import { createFsAgentStore } from '../../src/persistence/fsAgentStore';
+import { AgentRepo } from '../storage/agentRepo';
+import { SecretsStore } from '../secretsStore';
+import { studioPathsFor } from '../workspace/studioPaths';
+import type { EjectResult } from '../../shared/wireTypes';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
+
+vi.mock('@linuxdevil/lousho/spec', async (importOriginal) => {
+  const mod = await importOriginal<typeof import('@linuxdevil/lousho/spec')>();
+  return { ...mod, specToAgentDir: vi.fn(mod.specToAgentDir) };
+});
+
+const V2_SPEC: AgentSpecV2 = {
+  version: 2,
+  name: 'ops',
+  model: 'mock/mock-1',
+  instructions: 'Check the queues.',
+};
+
+describe('POST /agents/:id/eject', () => {
+  let baseDir: string;
+  let studioHome: string;
+  let repo: AgentRepo;
+  let app: () => ReturnType<typeof createApp>;
+
+  beforeEach(async () => {
+    baseDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lou-a08b-eject-'));
+    studioHome = path.join(baseDir, '.lousho');
+    const agentStore = createFsAgentStore(baseDir);
+    repo = new AgentRepo(baseDir);
+    const runManager = new RunManager({
+      baseDir,
+      checkpointStore: new FileCheckpointStore(baseDir),
+      approvalStore: new FileApprovalStore(baseDir),
+      host: newTestHost(baseDir),
+      loadSpec: (id) => repo.readSpec(id),
+      saveSpec: (id, spec) => repo.writeSpec(id, spec),
+    });
+    app = () =>
+      createApp({
+        agentStore,
+        runManager,
+        baseDir,
+        studioHome,
+        secretsStore: new SecretsStore(studioPathsFor(studioHome)),
+      });
+    await repo.writeSpec('x', V2_SPEC);
+    vi.mocked(specToAgentDir).mockClear();
+  });
+
+  afterEach(() => {
+    fs.rmSync(baseDir, { recursive: true, force: true });
+  });
+
+  it('writes agents/x/agent.yaml and returns the written paths', async () => {
+    const res = await request(app()).post('/agents/x/eject').send({});
+    expect(res.status).toBe(200);
+    const body = res.body as EjectResult;
+    expect(body.dir).toBe('agents/x');
+    expect(body.files).toContain('agent.yaml');
+    const written = path.join(baseDir, 'agents', 'x', 'agent.yaml');
+    expect(fs.existsSync(written)).toBe(true);
+    expect(fs.readFileSync(written, 'utf8')).toContain('ops');
+  });
+
+  it('answers 409 LOUSHO_EJECT_EXISTS with the existing files, then 200 on overwrite', async () => {
+    await request(app()).post('/agents/x/eject').send({}).expect(200);
+    const again = await request(app()).post('/agents/x/eject').send({});
+    expect(again.status).toBe(409);
+    expect(again.body.code).toBe('LOUSHO_EJECT_EXISTS');
+    expect(again.body.error).toBe('agents/x/ already exists.');
+    expect(again.body.details.files).toContain('agent.yaml');
+
+    const overwrite = await request(app()).post('/agents/x/eject').send({ overwrite: true });
+    expect(overwrite.status).toBe(200);
+  });
+
+  it('answers 404 for an unknown agent', async () => {
+    const res = await request(app()).post('/agents/nope/eject').send({});
+    expect(res.status).toBe(404);
+    expect(res.body.error).toBe('Agent nope not found.');
+  });
+
+  it('answers 400 and writes nothing when a generated path escapes the target', async () => {
+    vi.mocked(specToAgentDir).mockReturnValueOnce({
+      files: [{ path: '../evil.ts', content: 'export {}' }],
+      dropped: [],
+    });
+    const res = await request(app()).post('/agents/x/eject').send({ overwrite: true });
+    expect(res.status).toBe(400);
+    expect(res.body.code).toBe('LOUSHO_EJECT_INVALID');
+    expect(fs.existsSync(path.join(baseDir, 'agents', 'evil.ts'))).toBe(false);
+    expect(fs.existsSync(path.join(baseDir, 'evil.ts'))).toBe(false);
+  });
+
+  it('answers 400 LOUSHO_EJECT_INVALID when specToAgentDir throws', async () => {
+    vi.mocked(specToAgentDir).mockImplementationOnce(() => {
+      throw new Error('spec cannot be a directory');
+    });
+    const res = await request(app()).post('/agents/x/eject').send({});
+    expect(res.status).toBe(400);
+    expect(res.body.code).toBe('LOUSHO_EJECT_INVALID');
+    expect(res.body.error).toBe('spec cannot be a directory');
+  });
+});
diff --git a/apps/agent-forge/server/__tests__/evalGateRunner.test.ts b/apps/agent-forge/server/__tests__/evalGateRunner.test.ts
index e8d77cd1c..e6a97168d 100644
--- a/apps/agent-forge/server/__tests__/evalGateRunner.test.ts
+++ b/apps/agent-forge/server/__tests__/evalGateRunner.test.ts
@@ -2,7 +2,7 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import type { AgentSpecV2, EvalGateSpec } from 'lousho/spec';
+import type { AgentSpecV2, EvalGateSpec } from '@linuxdevil/lousho/spec';
 import type { PassRunner, PassResult } from '../passes/passRunner';
 import { SettingsStore } from '../settingsStore';
 import { SecretsStore } from '../secretsStore';
diff --git a/apps/agent-forge/server/__tests__/eventsAll.test.ts b/apps/agent-forge/server/__tests__/eventsAll.test.ts
index 43af7059c..4e0958e5f 100644
--- a/apps/agent-forge/server/__tests__/eventsAll.test.ts
+++ b/apps/agent-forge/server/__tests__/eventsAll.test.ts
@@ -5,7 +5,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
 import { WebSocket } from 'ws';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { startStudioServer, type StudioServerHandle } from '../index';
 import { STUDIO_TOKEN_HEADER } from '../auth';
 import { createUpgradeRouter } from '../ws/upgradeRouter';
diff --git a/apps/agent-forge/server/__tests__/eventsWs.test.ts b/apps/agent-forge/server/__tests__/eventsWs.test.ts
index 08b051c9b..28cfc93eb 100644
--- a/apps/agent-forge/server/__tests__/eventsWs.test.ts
+++ b/apps/agent-forge/server/__tests__/eventsWs.test.ts
@@ -4,7 +4,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
 import { WebSocket } from 'ws';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { startStudioServer, type StudioServerHandle } from '../index';
 import { STUDIO_TOKEN_HEADER } from '../auth';
 import { createApp } from '../app';
diff --git a/apps/agent-forge/server/__tests__/export.test.ts b/apps/agent-forge/server/__tests__/export.test.ts
index 1e2a3f57f..e1e5590e4 100644
--- a/apps/agent-forge/server/__tests__/export.test.ts
+++ b/apps/agent-forge/server/__tests__/export.test.ts
@@ -4,7 +4,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
diff --git a/apps/agent-forge/server/__tests__/fixtures/scriptedProvider.mjs b/apps/agent-forge/server/__tests__/fixtures/scriptedProvider.mjs
index ac288462d..2d2100243 100644
--- a/apps/agent-forge/server/__tests__/fixtures/scriptedProvider.mjs
+++ b/apps/agent-forge/server/__tests__/fixtures/scriptedProvider.mjs
@@ -1,19 +1,18 @@
-// W11b test preload: registers a scripted `scripted` provider inside the
-// bridge child process (passed as `node --import <file URL>` before
-// `bin/lousho.js bridge`), where providers registered in the Studio test
-// process cannot reach. The turn script comes from SCRIPTED_TURNS (a JSON
-// array of mockModel turns - see src/testing/mockModel.ts).
-//
-// The mockModel is created ONCE here, not per factory call: the bridge
-// rebuilds the runnable agent when an approval pause continues, and a
-// fresh script per build would replay turn 1 (pausing again) instead of
-// advancing to the continuation turn - the same reason the SDK's own
-// bridge tests register one shared `model`.
-//
-// Imports `lousho`, not `@lousho/build-ai-agent`: that is the name the
-// package ships under today; the scoped rename lands with W13a/W13b.
-import { LLMProviderRegistry } from 'lousho';
-import { mockModel } from 'lousho/testing';
-
-const model = mockModel(JSON.parse(process.env.SCRIPTED_TURNS ?? '["ok"]'), { onExhausted: 'repeat-last' });
-LLMProviderRegistry.register('scripted', () => model);
+// W11b test preload: registers a scripted `scripted` provider inside the
+// bridge child process (passed as `node --import <file URL>` before
+// `bin/lousho.js bridge`), where providers registered in the Studio test
+// process cannot reach. The turn script comes from SCRIPTED_TURNS (a JSON
+// array of mockModel turns - see src/testing/mockModel.ts).
+//
+// The mockModel is created ONCE here, not per factory call: the bridge
+// rebuilds the runnable agent when an approval pause continues, and a
+// fresh script per build would replay turn 1 (pausing again) instead of
+// advancing to the continuation turn - the same reason the SDK's own
+// bridge tests register one shared `model`.
+//
+// Imports `@linuxdevil/lousho`, the name the package ships under.
+import { LLMProviderRegistry } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
+
+const model = mockModel(JSON.parse(process.env.SCRIPTED_TURNS ?? '["ok"]'), { onExhausted: 'repeat-last' });
+LLMProviderRegistry.register('scripted', () => model);
diff --git a/apps/agent-forge/server/__tests__/hooksRoute.test.ts b/apps/agent-forge/server/__tests__/hooksRoute.test.ts
index 1a38d49ff..5736e0c5f 100644
--- a/apps/agent-forge/server/__tests__/hooksRoute.test.ts
+++ b/apps/agent-forge/server/__tests__/hooksRoute.test.ts
@@ -3,8 +3,8 @@ import { createHmac } from 'node:crypto';
 import { describe, expect, it, vi, type Mock } from 'vitest';
 import type { Express } from 'express';
 import request from 'supertest';
-import { TriggerRegistry } from 'lousho/triggers';
-import type { TriggerSpec } from 'lousho/spec';
+import { TriggerRegistry } from '@linuxdevil/lousho/triggers';
+import type { TriggerSpec } from '@linuxdevil/lousho/spec';
 
 import { createApp } from '../app';
 import { SecretsStore } from '../secretsStore';
diff --git a/apps/agent-forge/server/__tests__/hostRoutes.test.ts b/apps/agent-forge/server/__tests__/hostRoutes.test.ts
index 00af6a3ab..f1cf3aee3 100644
--- a/apps/agent-forge/server/__tests__/hostRoutes.test.ts
+++ b/apps/agent-forge/server/__tests__/hostRoutes.test.ts
@@ -1,265 +1,265 @@
-/**
- * W11c: `GET /workspaces/:ws/host` + `POST /workspaces/:ws/host/restart`
- * over real `createWorkspaceContext`s whose `WorkspaceHostSelector`s are
- * driven by W11a's `fakeBridge.mjs` installed as each workspace's SDK.
- * The `selectHost` services seam injects short client timeouts and
- * per-workspace `FAKE_BRIDGE_*` env; `process.env` propagation covers the
- * rest (bridgeEnv spreads it).
- */
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import * as fs from 'node:fs';
-import * as os from 'node:os';
-import * as path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import type { Express } from 'express';
-import request from 'supertest';
-import type { StudioEvent } from '../../shared/wireTypes';
-import type { WorkspaceRef } from '../../shared/workspace';
-import { createApp } from '../app';
-import { createWorkspaceContext, type WorkspaceContext, type WorkspaceResolver, type WorkspaceServices } from '../workspace/context';
-import { WorkspaceHostSelector } from '../host/hostSelector';
-import { WorkspaceRegistry } from '../workspace/workspaceRegistry';
-import { SecretsStore } from '../secretsStore';
-import { SettingsStore } from '../settingsStore';
-import { SpendLog } from '../passes/spendLog';
-import { AlertStore } from '../inbox/alertStore';
-import { PassRunner } from '../passes/passRunner';
-
-const FAKE_BRIDGE = fileURLToPath(new URL('../host/__tests__/fakeBridge.mjs', import.meta.url));
-
-/** A workspace whose node_modules SDK's `bin/lousho.js` IS the fake bridge. */
-function sdkWorkspace(root: string): void {
-  const pkgDir = path.join(root, 'node_modules', '@lousho', 'build-ai-agent');
-  fs.mkdirSync(path.join(pkgDir, 'bin'), { recursive: true });
-  fs.mkdirSync(path.join(pkgDir, 'dist', 'cli'), { recursive: true });
-  fs.writeFileSync(path.join(pkgDir, 'package.json'), JSON.stringify({ name: '@lousho/build-ai-agent', version: '9.9.9-test' }));
-  fs.copyFileSync(FAKE_BRIDGE, path.join(pkgDir, 'bin', 'lousho.js'));
-  fs.writeFileSync(path.join(pkgDir, 'dist', 'cli', 'bridge.mjs'), '// built\n');
-}
-
-describe('host routes (W11c)', () => {
-  let dir: string;
-  let studioDir: string;
-  let registry: WorkspaceRegistry;
-  let services: WorkspaceServices;
-  /** root -> extra env for that workspace's bridge child. */
-  let envByRoot: Map<string, Record<string, string>>;
-  let contexts: WorkspaceContext[];
-  let app: Express;
-  let launch: WorkspaceContext;
-  let inProcessCtx: WorkspaceContext;
-  let bridgeCtx: WorkspaceContext;
-  let readOnlyCtx: WorkspaceContext;
-  let failedCtx: WorkspaceContext;
-  let gateFile: string;
-
-  async function ctxFor(root: string): Promise<WorkspaceContext> {
-    const ref: WorkspaceRef = await registry.ensure(root);
-    const ctx = createWorkspaceContext(ref, services);
-    contexts.push(ctx);
-    return ctx;
-  }
-
-  beforeEach(async () => {
-    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'lou-w11c-host-'));
-    studioDir = path.join(dir, 'studio');
-    fs.mkdirSync(studioDir, { recursive: true });
-    const secretsStore = new SecretsStore(studioDir);
-    const settingsStore = new SettingsStore(studioDir);
-    const spendLog = new SpendLog(path.join(studioDir, 'spend.jsonl'));
-    const alerts = new AlertStore(path.join(studioDir, 'alerts.json'));
-    registry = new WorkspaceRegistry(path.join(studioDir, 'workspaces.json'));
-    envByRoot = new Map();
-    contexts = [];
-    services = {
-      secretsStore,
-      settingsStore,
-      observe: false,
-      passRunner: new PassRunner({ baseDir: studioDir, spendLog, isEnabled: () => false }),
-      spendLog,
-      alerts,
-      collector: { url: () => 'http://127.0.0.1:9', token: () => undefined },
-      studioVersion: '9.9.9-studio',
-      selectHost: (ref, deps) =>
-        new WorkspaceHostSelector(ref, {
-          ...deps,
-          clientOptions: { stderr: () => undefined, timeouts: { hello: 400, shutdown: 200 } },
-          extraEnv: envByRoot.get(ref.root),
-        }),
-    };
-
-    const roots = {
-      inProcess: path.join(dir, 'plain'),
-      bridge: path.join(dir, 'sdk-ok'),
-      readOnly: path.join(dir, 'sdk-old'),
-      failed: path.join(dir, 'sdk-gate'),
-    };
-    for (const root of Object.values(roots)) fs.mkdirSync(root, { recursive: true });
-    sdkWorkspace(roots.bridge);
-    sdkWorkspace(roots.readOnly);
-    sdkWorkspace(roots.failed);
-    envByRoot.set(roots.readOnly, { FAKE_BRIDGE_SPEC_VERSIONS: '[1]' });
-    gateFile = path.join(dir, 'gate');
-    envByRoot.set(roots.failed, { FAKE_BRIDGE_SILENT_UNTIL: gateFile });
-
-    inProcessCtx = await ctxFor(roots.inProcess);
-    bridgeCtx = await ctxFor(roots.bridge);
-    readOnlyCtx = await ctxFor(roots.readOnly);
-    failedCtx = await ctxFor(roots.failed);
-    launch = inProcessCtx;
-
-    const byId = new Map(contexts.map((c) => [c.ref.id, c]));
-    const resolver: WorkspaceResolver = {
-      resolve: async (id) => byId.get(id ?? launch.ref.id),
-      defaultId: () => launch.ref.id,
-      retain: () => () => undefined,
-    };
-    app = createApp({
-      workspace: launch,
-      workspaces: resolver,
-      baseDir: roots.inProcess,
-      studioHome: studioDir,
-      secretsStore,
-      settingsStore,
-      spendLog,
-      passRunner: services.passRunner,
-      alerts,
-    });
-  });
-
-  afterEach(async () => {
-    await Promise.all(contexts.map((c) => c.dispose().catch(() => undefined)));
-    fs.rmSync(dir, { recursive: true, force: true });
-  });
-
-  const get = (ws: string) => request(app).get(`/workspaces/${ws}/host`);
-  const post = (ws: string) => request(app).post(`/workspaces/${ws}/host/restart`);
-
-  it('GET on an in-process workspace reports the info banner and ready state', async () => {
-    const res = await get(inProcessCtx.ref.id);
-    expect(res.status).toBe(200);
-    expect(res.body).toMatchObject({
-      workspaceId: inProcessCtx.ref.id,
-      mode: 'in-process',
-      state: 'ready',
-      sdkVersion: '9.9.9-studio',
-      studioSdkVersion: expect.any(String),
-    });
-    expect(res.body.banner).toMatchObject({ tone: 'info' });
-    expect(res.body.banner.text).toContain('no @lousho/build-ai-agent');
-    expect(res.body.recentStderr).toBeUndefined();
-  });
-
-  it('GET on a bridge workspace reports bridge/ready with the hello sdkVersion', async () => {
-    const res = await get(bridgeCtx.ref.id);
-    expect(res.status).toBe(200);
-    expect(res.body).toMatchObject({
-      workspaceId: bridgeCtx.ref.id,
-      mode: 'bridge',
-      state: 'ready',
-      sdkVersion: '0.0.0-fake',
-      studioSdkVersion: expect.any(String),
-      banner: null,
-    });
-  });
-
-  it('GET on a read-only workspace reports the update warning', async () => {
-    const res = await get(readOnlyCtx.ref.id);
-    expect(res.status).toBe(200);
-    expect(res.body).toMatchObject({ workspaceId: readOnlyCtx.ref.id, mode: 'read-only', state: 'ready' });
-    expect(res.body.banner).toMatchObject({ tone: 'warning' });
-    expect(res.body.banner.text).toContain('@lousho/build-ai-agent');
-  });
-
-  it('GET on a crashed bridge reports failed with the restart banner and stderr', async () => {
-    const res = await get(failedCtx.ref.id);
-    expect(res.status).toBe(200);
-    expect(res.body).toMatchObject({
-      workspaceId: failedCtx.ref.id,
-      mode: 'bridge',
-      state: 'failed',
-      banner: { tone: 'danger', action: 'restart' },
-    });
-    expect(res.body.recentStderr).toEqual(
-      expect.arrayContaining([expect.stringContaining('silent until the gate file')])
-    );
-  });
-
-  it('GET answers 404 for an unknown workspace and 400 for a malformed id', async () => {
-    const missing = await get('unknown-000001');
-    expect(missing.status).toBe(404);
-    expect(missing.body.code).toBe('LOUSHO_WORKSPACE_NOT_FOUND');
-    const bad = await get('not a workspace!');
-    expect(bad.status).toBe(400);
-    expect(bad.body.code).toBe('LOUSHO_WORKSPACE_ID_INVALID');
-  });
-
-  it('POST restart on an in-process workspace is a 409 LOUSHO_HOST_NOT_BRIDGE', async () => {
-    const res = await post(inProcessCtx.ref.id);
-    expect(res.status).toBe(409);
-    expect(res.body).toEqual({ error: 'Only a project bridge can be restarted.', code: 'LOUSHO_HOST_NOT_BRIDGE' });
-  });
-
-  it('POST restart on a read-only workspace re-runs the handshake (still read-only)', async () => {
-    const res = await post(readOnlyCtx.ref.id);
-    expect(res.status).toBe(202);
-    expect(res.body.mode).toBe('read-only');
-  });
-
-  it('a read-only workspace reads agents but refuses writes and runs', async () => {
-    const ws = { 'x-lousho-workspace': readOnlyCtx.ref.id };
-    const list = await request(app).get('/agents').set(ws);
-    expect(list.status).toBe(200);
-    const save = await request(app).put('/agents/some-agent').set(ws).send({ spec: { version: 2 } });
-    expect(save.status).toBe(409);
-    expect(save.body.code).toBe('LOUSHO_WORKSPACE_READ_ONLY');
-    const run = await request(app).post('/agents/some-agent/run').set(ws).send({});
-    expect(run.status).toBe(409);
-    expect(run.body.code).toBe('LOUSHO_WORKSPACE_READ_ONLY');
-    // Studio-global routes are never gated.
-    const catalog = await request(app).get('/catalog/tools').set(ws);
-    expect(catalog.status).toBe(200);
-  });
-
-  it('POST restart revives a crashed bridge and publishes host.status events', async () => {
-    const events: StudioEvent[] = [];
-    const off = failedCtx.events.subscribe((e) => events.push(e));
-    try {
-      // The gate file flips the fake bridge from silent to answering hello.
-      fs.writeFileSync(gateFile, 'go');
-      const res = await post(failedCtx.ref.id);
-      expect(res.status).toBe(202);
-      expect(res.body).toMatchObject({ mode: 'bridge', state: 'ready', banner: null, sdkVersion: '0.0.0-fake' });
-      const statuses = events.filter((e) => e.type === 'host.status');
-      expect(statuses.length).toBeGreaterThan(0);
-      expect(statuses.at(-1)).toMatchObject({
-        type: 'host.status',
-        payload: { workspaceId: failedCtx.ref.id, mode: 'bridge', state: 'ready', banner: null },
-      });
-    } finally {
-      off();
-    }
-  });
-
-  it('a settling handshake publishes host.status on the workspace bus', async () => {
-    // A fresh bridge context: subscribe before its handshake settles.
-    const lateRoot = path.join(dir, 'sdk-late');
-    fs.mkdirSync(lateRoot, { recursive: true });
-    sdkWorkspace(lateRoot);
-    const events: StudioEvent[] = [];
-    const ctx = await ctxFor(lateRoot);
-    const off = ctx.events.subscribe((e) => events.push(e));
-    try {
-      await ctx.hostSelector.ready();
-      // Selection settle AND the client's ready transition each publish once.
-      const statuses = events.filter((e) => e.type === 'host.status');
-      expect(statuses.length).toBeGreaterThanOrEqual(1);
-      expect(statuses.at(-1)).toMatchObject({
-        type: 'host.status',
-        payload: { workspaceId: ctx.ref.id, mode: 'bridge', state: 'ready', banner: null },
-      });
-    } finally {
-      off();
-    }
-  });
-});
+/**
+ * W11c: `GET /workspaces/:ws/host` + `POST /workspaces/:ws/host/restart`
+ * over real `createWorkspaceContext`s whose `WorkspaceHostSelector`s are
+ * driven by W11a's `fakeBridge.mjs` installed as each workspace's SDK.
+ * The `selectHost` services seam injects short client timeouts and
+ * per-workspace `FAKE_BRIDGE_*` env; `process.env` propagation covers the
+ * rest (bridgeEnv spreads it).
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { Express } from 'express';
+import request from 'supertest';
+import type { StudioEvent } from '../../shared/wireTypes';
+import type { WorkspaceRef } from '../../shared/workspace';
+import { createApp } from '../app';
+import { createWorkspaceContext, type WorkspaceContext, type WorkspaceResolver, type WorkspaceServices } from '../workspace/context';
+import { WorkspaceHostSelector } from '../host/hostSelector';
+import { WorkspaceRegistry } from '../workspace/workspaceRegistry';
+import { SecretsStore } from '../secretsStore';
+import { SettingsStore } from '../settingsStore';
+import { SpendLog } from '../passes/spendLog';
+import { AlertStore } from '../inbox/alertStore';
+import { PassRunner } from '../passes/passRunner';
+
+const FAKE_BRIDGE = fileURLToPath(new URL('../host/__tests__/fakeBridge.mjs', import.meta.url));
+
+/** A workspace whose node_modules SDK's `bin/lousho.js` IS the fake bridge. */
+function sdkWorkspace(root: string): void {
+  const pkgDir = path.join(root, 'node_modules', '@linuxdevil', 'lousho');
+  fs.mkdirSync(path.join(pkgDir, 'bin'), { recursive: true });
+  fs.mkdirSync(path.join(pkgDir, 'dist', 'cli'), { recursive: true });
+  fs.writeFileSync(path.join(pkgDir, 'package.json'), JSON.stringify({ name: '@linuxdevil/lousho', version: '9.9.9-test' }));
+  fs.copyFileSync(FAKE_BRIDGE, path.join(pkgDir, 'bin', 'lousho.js'));
+  fs.writeFileSync(path.join(pkgDir, 'dist', 'cli', 'bridge.mjs'), '// built\n');
+}
+
+describe('host routes (W11c)', () => {
+  let dir: string;
+  let studioDir: string;
+  let registry: WorkspaceRegistry;
+  let services: WorkspaceServices;
+  /** root -> extra env for that workspace's bridge child. */
+  let envByRoot: Map<string, Record<string, string>>;
+  let contexts: WorkspaceContext[];
+  let app: Express;
+  let launch: WorkspaceContext;
+  let inProcessCtx: WorkspaceContext;
+  let bridgeCtx: WorkspaceContext;
+  let readOnlyCtx: WorkspaceContext;
+  let failedCtx: WorkspaceContext;
+  let gateFile: string;
+
+  async function ctxFor(root: string): Promise<WorkspaceContext> {
+    const ref: WorkspaceRef = await registry.ensure(root);
+    const ctx = createWorkspaceContext(ref, services);
+    contexts.push(ctx);
+    return ctx;
+  }
+
+  beforeEach(async () => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'lou-w11c-host-'));
+    studioDir = path.join(dir, 'studio');
+    fs.mkdirSync(studioDir, { recursive: true });
+    const secretsStore = new SecretsStore(studioDir);
+    const settingsStore = new SettingsStore(studioDir);
+    const spendLog = new SpendLog(path.join(studioDir, 'spend.jsonl'));
+    const alerts = new AlertStore(path.join(studioDir, 'alerts.json'));
+    registry = new WorkspaceRegistry(path.join(studioDir, 'workspaces.json'));
+    envByRoot = new Map();
+    contexts = [];
+    services = {
+      secretsStore,
+      settingsStore,
+      observe: false,
+      passRunner: new PassRunner({ baseDir: studioDir, spendLog, isEnabled: () => false }),
+      spendLog,
+      alerts,
+      collector: { url: () => 'http://127.0.0.1:9', token: () => undefined },
+      studioVersion: '9.9.9-studio',
+      selectHost: (ref, deps) =>
+        new WorkspaceHostSelector(ref, {
+          ...deps,
+          clientOptions: { stderr: () => undefined, timeouts: { hello: 400, shutdown: 200 } },
+          extraEnv: envByRoot.get(ref.root),
+        }),
+    };
+
+    const roots = {
+      inProcess: path.join(dir, 'plain'),
+      bridge: path.join(dir, 'sdk-ok'),
+      readOnly: path.join(dir, 'sdk-old'),
+      failed: path.join(dir, 'sdk-gate'),
+    };
+    for (const root of Object.values(roots)) fs.mkdirSync(root, { recursive: true });
+    sdkWorkspace(roots.bridge);
+    sdkWorkspace(roots.readOnly);
+    sdkWorkspace(roots.failed);
+    envByRoot.set(roots.readOnly, { FAKE_BRIDGE_SPEC_VERSIONS: '[1]' });
+    gateFile = path.join(dir, 'gate');
+    envByRoot.set(roots.failed, { FAKE_BRIDGE_SILENT_UNTIL: gateFile });
+
+    inProcessCtx = await ctxFor(roots.inProcess);
+    bridgeCtx = await ctxFor(roots.bridge);
+    readOnlyCtx = await ctxFor(roots.readOnly);
+    failedCtx = await ctxFor(roots.failed);
+    launch = inProcessCtx;
+
+    const byId = new Map(contexts.map((c) => [c.ref.id, c]));
+    const resolver: WorkspaceResolver = {
+      resolve: async (id) => byId.get(id ?? launch.ref.id),
+      defaultId: () => launch.ref.id,
+      retain: () => () => undefined,
+    };
+    app = createApp({
+      workspace: launch,
+      workspaces: resolver,
+      baseDir: roots.inProcess,
+      studioHome: studioDir,
+      secretsStore,
+      settingsStore,
+      spendLog,
+      passRunner: services.passRunner,
+      alerts,
+    });
+  });
+
+  afterEach(async () => {
+    await Promise.all(contexts.map((c) => c.dispose().catch(() => undefined)));
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  const get = (ws: string) => request(app).get(`/workspaces/${ws}/host`);
+  const post = (ws: string) => request(app).post(`/workspaces/${ws}/host/restart`);
+
+  it('GET on an in-process workspace reports the info banner and ready state', async () => {
+    const res = await get(inProcessCtx.ref.id);
+    expect(res.status).toBe(200);
+    expect(res.body).toMatchObject({
+      workspaceId: inProcessCtx.ref.id,
+      mode: 'in-process',
+      state: 'ready',
+      sdkVersion: '9.9.9-studio',
+      studioSdkVersion: expect.any(String),
+    });
+    expect(res.body.banner).toMatchObject({ tone: 'info' });
+    expect(res.body.banner.text).toContain('no @linuxdevil/lousho');
+    expect(res.body.recentStderr).toBeUndefined();
+  });
+
+  it('GET on a bridge workspace reports bridge/ready with the hello sdkVersion', async () => {
+    const res = await get(bridgeCtx.ref.id);
+    expect(res.status).toBe(200);
+    expect(res.body).toMatchObject({
+      workspaceId: bridgeCtx.ref.id,
+      mode: 'bridge',
+      state: 'ready',
+      sdkVersion: '0.0.0-fake',
+      studioSdkVersion: expect.any(String),
+      banner: null,
+    });
+  });
+
+  it('GET on a read-only workspace reports the update warning', async () => {
+    const res = await get(readOnlyCtx.ref.id);
+    expect(res.status).toBe(200);
+    expect(res.body).toMatchObject({ workspaceId: readOnlyCtx.ref.id, mode: 'read-only', state: 'ready' });
+    expect(res.body.banner).toMatchObject({ tone: 'warning' });
+    expect(res.body.banner.text).toContain('@linuxdevil/lousho');
+  });
+
+  it('GET on a crashed bridge reports failed with the restart banner and stderr', async () => {
+    const res = await get(failedCtx.ref.id);
+    expect(res.status).toBe(200);
+    expect(res.body).toMatchObject({
+      workspaceId: failedCtx.ref.id,
+      mode: 'bridge',
+      state: 'failed',
+      banner: { tone: 'danger', action: 'restart' },
+    });
+    expect(res.body.recentStderr).toEqual(
+      expect.arrayContaining([expect.stringContaining('silent until the gate file')])
+    );
+  });
+
+  it('GET answers 404 for an unknown workspace and 400 for a malformed id', async () => {
+    const missing = await get('unknown-000001');
+    expect(missing.status).toBe(404);
+    expect(missing.body.code).toBe('LOUSHO_WORKSPACE_NOT_FOUND');
+    const bad = await get('not a workspace!');
+    expect(bad.status).toBe(400);
+    expect(bad.body.code).toBe('LOUSHO_WORKSPACE_ID_INVALID');
+  });
+
+  it('POST restart on an in-process workspace is a 409 LOUSHO_HOST_NOT_BRIDGE', async () => {
+    const res = await post(inProcessCtx.ref.id);
+    expect(res.status).toBe(409);
+    expect(res.body).toEqual({ error: 'Only a project bridge can be restarted.', code: 'LOUSHO_HOST_NOT_BRIDGE' });
+  });
+
+  it('POST restart on a read-only workspace re-runs the handshake (still read-only)', async () => {
+    const res = await post(readOnlyCtx.ref.id);
+    expect(res.status).toBe(202);
+    expect(res.body.mode).toBe('read-only');
+  });
+
+  it('a read-only workspace reads agents but refuses writes and runs', async () => {
+    const ws = { 'x-lousho-workspace': readOnlyCtx.ref.id };
+    const list = await request(app).get('/agents').set(ws);
+    expect(list.status).toBe(200);
+    const save = await request(app).put('/agents/some-agent').set(ws).send({ spec: { version: 2 } });
+    expect(save.status).toBe(409);
+    expect(save.body.code).toBe('LOUSHO_WORKSPACE_READ_ONLY');
+    const run = await request(app).post('/agents/some-agent/run').set(ws).send({});
+    expect(run.status).toBe(409);
+    expect(run.body.code).toBe('LOUSHO_WORKSPACE_READ_ONLY');
+    // Studio-global routes are never gated.
+    const catalog = await request(app).get('/catalog/tools').set(ws);
+    expect(catalog.status).toBe(200);
+  });
+
+  it('POST restart revives a crashed bridge and publishes host.status events', async () => {
+    const events: StudioEvent[] = [];
+    const off = failedCtx.events.subscribe((e) => events.push(e));
+    try {
+      // The gate file flips the fake bridge from silent to answering hello.
+      fs.writeFileSync(gateFile, 'go');
+      const res = await post(failedCtx.ref.id);
+      expect(res.status).toBe(202);
+      expect(res.body).toMatchObject({ mode: 'bridge', state: 'ready', banner: null, sdkVersion: '0.0.0-fake' });
+      const statuses = events.filter((e) => e.type === 'host.status');
+      expect(statuses.length).toBeGreaterThan(0);
+      expect(statuses.at(-1)).toMatchObject({
+        type: 'host.status',
+        payload: { workspaceId: failedCtx.ref.id, mode: 'bridge', state: 'ready', banner: null },
+      });
+    } finally {
+      off();
+    }
+  });
+
+  it('a settling handshake publishes host.status on the workspace bus', async () => {
+    // A fresh bridge context: subscribe before its handshake settles.
+    const lateRoot = path.join(dir, 'sdk-late');
+    fs.mkdirSync(lateRoot, { recursive: true });
+    sdkWorkspace(lateRoot);
+    const events: StudioEvent[] = [];
+    const ctx = await ctxFor(lateRoot);
+    const off = ctx.events.subscribe((e) => events.push(e));
+    try {
+      await ctx.hostSelector.ready();
+      // Selection settle AND the client's ready transition each publish once.
+      const statuses = events.filter((e) => e.type === 'host.status');
+      expect(statuses.length).toBeGreaterThanOrEqual(1);
+      expect(statuses.at(-1)).toMatchObject({
+        type: 'host.status',
+        payload: { workspaceId: ctx.ref.id, mode: 'bridge', state: 'ready', banner: null },
+      });
+    } finally {
+      off();
+    }
+  });
+});
diff --git a/apps/agent-forge/server/__tests__/hostSelector.test.ts b/apps/agent-forge/server/__tests__/hostSelector.test.ts
index c062eb7ef..365bf7efb 100644
--- a/apps/agent-forge/server/__tests__/hostSelector.test.ts
+++ b/apps/agent-forge/server/__tests__/hostSelector.test.ts
@@ -1,211 +1,211 @@
-/**
- * W11b: `WorkspaceHostSelector` rows 1-7. Rows 1-2 decide from disk and
- * never spawn; rows 3-7 run the real `BridgeClient` handshake against
- * `fakeBridge.mjs` (installed as the workspace's `node_modules` SDK).
- */
-import * as fs from 'node:fs';
-import * as os from 'node:os';
-import * as path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import type { WorkspaceRef } from '../../shared/workspace';
-import { BridgeAgentHost, HostReadOnlyError } from '../host/bridgeAgentHost';
-import { envCollector, WorkspaceHostSelector, type SelectHostDeps } from '../host/hostSelector';
-import { InProcessAgentHost } from '../host/inProcessAgentHost';
-import { FileCheckpointStore } from '../checkpointStore';
-import { FileApprovalStore } from '../approvalStore';
-import { MIN_BRIDGE_SDK_VERSION } from '../host/sdkCompat';
-import { workspaceRefFor } from '../workspace/workspaceId';
-import { SecretsStore } from '../secretsStore';
-
-const FAKE_BRIDGE = fileURLToPath(new URL('../host/__tests__/fakeBridge.mjs', import.meta.url));
-
-let dir: string;
-let secretsDir: string;
-
-beforeEach(() => {
-  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'lou-w11b-sel-'));
-  secretsDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lou-w11b-sec-'));
-});
-
-afterEach(() => {
-  fs.rmSync(dir, { recursive: true, force: true });
-  fs.rmSync(secretsDir, { recursive: true, force: true });
-});
-
-/** A workspace whose node_modules SDK's `bin/lousho.js` IS the fake bridge. */
-function sdkWorkspace(root: string, sdkName = '@lousho/build-ai-agent'): string {
-  const pkgDir = path.join(root, 'node_modules', ...sdkName.split('/'));
-  fs.mkdirSync(path.join(pkgDir, 'bin'), { recursive: true });
-  fs.mkdirSync(path.join(pkgDir, 'dist', 'cli'), { recursive: true });
-  fs.writeFileSync(
-    path.join(pkgDir, 'package.json'),
-    JSON.stringify({ name: sdkName, version: '9.9.9-test' })
-  );
-  fs.copyFileSync(FAKE_BRIDGE, path.join(pkgDir, 'bin', 'lousho.js'));
-  fs.writeFileSync(path.join(pkgDir, 'dist', 'cli', 'bridge.mjs'), '// built\n');
-  return pkgDir;
-}
-
-function deps(root: string, extraEnv: Record<string, string> = {}, timeouts: Record<string, number> = {}): SelectHostDeps {
-  return {
-    inProcess: () =>
-      new InProcessAgentHost({
-        baseDir: root,
-        checkpointStore: new FileCheckpointStore(root),
-        approvalStore: new FileApprovalStore(root),
-      }),
-    secretsStore: new SecretsStore(secretsDir),
-    collector: () => ({ url: 'http://127.0.0.1:9' }),
-    studioVersion: '9.9.9-studio',
-    clientOptions: { stderr: () => undefined, timeouts: { hello: 2_000, shutdown: 500, ...timeouts } },
-    extraEnv: { FAKE_BRIDGE_REPORT_ENV: '1', ...extraEnv },
-  };
-}
-
-const refFor = (root: string): WorkspaceRef => workspaceRefFor(root);
-
-describe('WorkspaceHostSelector', () => {
-  it('row 1: no SDK on disk -> in-process, info banner, no client, reports to observe', async () => {
-    const root = path.join(dir, 'plain');
-    fs.mkdirSync(root, { recursive: true });
-    const selector = new WorkspaceHostSelector(refFor(root), deps(root));
-    expect(selector.host).toBeInstanceOf(InProcessAgentHost);
-    expect(selector.client).toBeUndefined();
-    expect(selector.reportsToObserve).toBe(true);
-    expect(selector.current()).toEqual({
-      mode: 'in-process',
-      sdkVersion: '9.9.9-studio',
-      banner: {
-        tone: 'info',
-        text: "This project has no @lousho/build-ai-agent installed. Runs use Studio's built-in SDK 9.9.9-studio.",
-      },
-    });
-    await expect(selector.ready()).resolves.toMatchObject({ mode: 'in-process' });
-  });
-
-  it('row 2: the SDK checkout itself, unbuilt -> in-process with the build hint', () => {
-    const root = path.join(dir, 'sdk-src');
-    fs.mkdirSync(path.join(root, 'bin'), { recursive: true });
-    fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name: 'lousho', version: '9.9.9' }));
-    fs.writeFileSync(path.join(root, 'bin', 'lousho.js'), '// bin\n');
-    const selector = new WorkspaceHostSelector(refFor(root), deps(root));
-    expect(selector.host).toBeInstanceOf(InProcessAgentHost);
-    expect(selector.client).toBeUndefined();
-    expect(selector.current().banner).toEqual({
-      tone: 'info',
-      text: "This SDK checkout is not built, so runs use Studio's built-in SDK 9.9.9-studio. Run npm run build to use it.",
-    });
-  });
-
-  it('row 3: bridge child without the command -> read-only with the update warning', async () => {
-    const root = path.join(dir, 'ws');
-    fs.mkdirSync(root, { recursive: true });
-    sdkWorkspace(root);
-    const selector = new WorkspaceHostSelector(refFor(root), deps(root, { FAKE_BRIDGE_MODE: 'unknown-command' }));
-    expect(selector.host).toBeInstanceOf(BridgeAgentHost);
-    expect(selector.client).toBeDefined();
-    expect(selector.reportsToObserve).toBe(false);
-    // Provisional snapshot before the handshake settles.
-    expect(selector.current()).toMatchObject({ mode: 'bridge', sdkVersion: '9.9.9-test', banner: null });
-    const settled = await selector.ready();
-    expect(settled.mode).toBe('read-only');
-    expect(settled.banner).toEqual({
-      tone: 'warning',
-      text: `Update @lousho/build-ai-agent in this project to ${MIN_BRIDGE_SDK_VERSION} or later to edit agents here.`,
-    });
-    await expect(selector.host.start({ agentId: 'a', spec: {} as never, sessionId: 's', input: 'hi', onEvent: () => {} })).rejects.toBeInstanceOf(HostReadOnlyError);
-  });
-
-  it('row 4: hello without spec v2 -> read-only with the same update warning', async () => {
-    const root = path.join(dir, 'ws');
-    fs.mkdirSync(root, { recursive: true });
-    sdkWorkspace(root);
-    const selector = new WorkspaceHostSelector(refFor(root), deps(root, { FAKE_BRIDGE_SPEC_VERSIONS: '[1]' }));
-    const settled = await selector.ready();
-    expect(settled.mode).toBe('read-only');
-    expect(settled.banner?.tone).toBe('warning');
-    expect(settled.banner?.text).toContain(MIN_BRIDGE_SDK_VERSION);
-  });
-
-  it('row 5: protocol newer than Studio -> read-only with the newer-SDK warning', async () => {
-    const root = path.join(dir, 'ws');
-    fs.mkdirSync(root, { recursive: true });
-    sdkWorkspace(root);
-    const selector = new WorkspaceHostSelector(
-      refFor(root),
-      deps(root, { FAKE_BRIDGE_PROTOCOL: '2', FAKE_BRIDGE_SDK_VERSION: '99.0.0' })
-    );
-    const settled = await selector.ready();
-    expect(settled.mode).toBe('read-only');
-    expect(settled.banner).toEqual({
-      tone: 'warning',
-      text: "This project's @lousho/build-ai-agent 99.0.0 is newer than this Studio understands. Update Studio to edit agents here.",
-    });
-  });
-
-  it('row 6: a good hello -> bridge mode, no banner, hello sdkVersion wins', async () => {
-    const root = path.join(dir, 'ws');
-    fs.mkdirSync(root, { recursive: true });
-    sdkWorkspace(root);
-    const onChange = vi.fn();
-    const selector = new WorkspaceHostSelector(refFor(root), deps(root, { FAKE_BRIDGE_SDK_VERSION: '8.8.8' }));
-    selector.onChange(onChange);
-    const settled = await selector.ready();
-    expect(settled).toMatchObject({ mode: 'bridge', sdkVersion: '8.8.8', banner: null });
-    expect(selector.current().mode).toBe('bridge');
-    expect(onChange).toHaveBeenCalled();
-    // The child env: observe target + workspace id + bridge flag, no studio token.
-    // The fake reports env on stderr after answering hello, so poll for it.
-    const deadline = Date.now() + 5_000;
-    let envLines: string[] = [];
-    while (Date.now() < deadline && envLines.length === 0) {
-      envLines = selector.client!.recentStderr().filter((l) => l.startsWith('env '));
-      if (envLines.length === 0) await new Promise((r) => setTimeout(r, 50));
-    }
-    try {
-    const env = Object.fromEntries(envLines.map((l) => l.slice(4).split(/=(.*)/s).slice(0, 2) as [string, string]));
-    expect(env.LOUSHO_OBSERVE).toBe('http://127.0.0.1:9');
-    expect(env.LOUSHO_OBSERVE_PROJECT).toBe(refFor(root).id);
-    expect(env.LOUSHO_BRIDGE).toBe('1');
-    expect(env.LOUSHO_STUDIO_TOKEN).toBe('<unset>');
-    } finally {
-      await selector.client!.stop();
-    }
-  });
-
-  it('row 7: handshake failure -> bridge mode with the restart banner', async () => {
-    const root = path.join(dir, 'ws');
-    fs.mkdirSync(root, { recursive: true });
-    sdkWorkspace(root);
-    const selector = new WorkspaceHostSelector(
-      refFor(root),
-      deps(root, { FAKE_BRIDGE_MODE: 'silent' }, { hello: 300 })
-    );
-    const settled = await selector.ready();
-    expect(settled.mode).toBe('bridge');
-    expect(settled.banner).toEqual({
-      tone: 'danger',
-      text: "This project's agent process keeps stopping. Check the Studio terminal for its output, then restart it.",
-      action: 'restart',
-    });
-    await selector.client!.stop();
-  });
-
-  it('envCollector reads LOUSHO_OBSERVE_URL/TOKEN per call', () => {
-    const prevUrl = process.env.LOUSHO_OBSERVE_URL;
-    const prevToken = process.env.LOUSHO_OBSERVE_TOKEN;
-    try {
-      process.env.LOUSHO_OBSERVE_URL = 'http://127.0.0.1:9999/';
-      process.env.LOUSHO_OBSERVE_TOKEN = 'tok';
-      expect(envCollector()).toEqual({ url: 'http://127.0.0.1:9999', token: 'tok' });
-      delete process.env.LOUSHO_OBSERVE_TOKEN;
-      expect(envCollector()).toEqual({ url: 'http://127.0.0.1:9999' });
-    } finally {
-      if (prevUrl === undefined) delete process.env.LOUSHO_OBSERVE_URL;
-      else process.env.LOUSHO_OBSERVE_URL = prevUrl;
-      if (prevToken === undefined) delete process.env.LOUSHO_OBSERVE_TOKEN;
-      else process.env.LOUSHO_OBSERVE_TOKEN = prevToken;
-    }
-  });
-});
+/**
+ * W11b: `WorkspaceHostSelector` rows 1-7. Rows 1-2 decide from disk and
+ * never spawn; rows 3-7 run the real `BridgeClient` handshake against
+ * `fakeBridge.mjs` (installed as the workspace's `node_modules` SDK).
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { WorkspaceRef } from '../../shared/workspace';
+import { BridgeAgentHost, HostReadOnlyError } from '../host/bridgeAgentHost';
+import { envCollector, WorkspaceHostSelector, type SelectHostDeps } from '../host/hostSelector';
+import { InProcessAgentHost } from '../host/inProcessAgentHost';
+import { FileCheckpointStore } from '../checkpointStore';
+import { FileApprovalStore } from '../approvalStore';
+import { MIN_BRIDGE_SDK_VERSION } from '../host/sdkCompat';
+import { workspaceRefFor } from '../workspace/workspaceId';
+import { SecretsStore } from '../secretsStore';
+
+const FAKE_BRIDGE = fileURLToPath(new URL('../host/__tests__/fakeBridge.mjs', import.meta.url));
+
+let dir: string;
+let secretsDir: string;
+
+beforeEach(() => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'lou-w11b-sel-'));
+  secretsDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lou-w11b-sec-'));
+});
+
+afterEach(() => {
+  fs.rmSync(dir, { recursive: true, force: true });
+  fs.rmSync(secretsDir, { recursive: true, force: true });
+});
+
+/** A workspace whose node_modules SDK's `bin/lousho.js` IS the fake bridge. */
+function sdkWorkspace(root: string, sdkName = '@linuxdevil/lousho'): string {
+  const pkgDir = path.join(root, 'node_modules', ...sdkName.split('/'));
+  fs.mkdirSync(path.join(pkgDir, 'bin'), { recursive: true });
+  fs.mkdirSync(path.join(pkgDir, 'dist', 'cli'), { recursive: true });
+  fs.writeFileSync(
+    path.join(pkgDir, 'package.json'),
+    JSON.stringify({ name: sdkName, version: '9.9.9-test' })
+  );
+  fs.copyFileSync(FAKE_BRIDGE, path.join(pkgDir, 'bin', 'lousho.js'));
+  fs.writeFileSync(path.join(pkgDir, 'dist', 'cli', 'bridge.mjs'), '// built\n');
+  return pkgDir;
+}
+
+function deps(root: string, extraEnv: Record<string, string> = {}, timeouts: Record<string, number> = {}): SelectHostDeps {
+  return {
+    inProcess: () =>
+      new InProcessAgentHost({
+        baseDir: root,
+        checkpointStore: new FileCheckpointStore(root),
+        approvalStore: new FileApprovalStore(root),
+      }),
+    secretsStore: new SecretsStore(secretsDir),
+    collector: () => ({ url: 'http://127.0.0.1:9' }),
+    studioVersion: '9.9.9-studio',
+    clientOptions: { stderr: () => undefined, timeouts: { hello: 2_000, shutdown: 500, ...timeouts } },
+    extraEnv: { FAKE_BRIDGE_REPORT_ENV: '1', ...extraEnv },
+  };
+}
+
+const refFor = (root: string): WorkspaceRef => workspaceRefFor(root);
+
+describe('WorkspaceHostSelector', () => {
+  it('row 1: no SDK on disk -> in-process, info banner, no client, reports to observe', async () => {
+    const root = path.join(dir, 'plain');
+    fs.mkdirSync(root, { recursive: true });
+    const selector = new WorkspaceHostSelector(refFor(root), deps(root));
+    expect(selector.host).toBeInstanceOf(InProcessAgentHost);
+    expect(selector.client).toBeUndefined();
+    expect(selector.reportsToObserve).toBe(true);
+    expect(selector.current()).toEqual({
+      mode: 'in-process',
+      sdkVersion: '9.9.9-studio',
+      banner: {
+        tone: 'info',
+        text: "This project has no @linuxdevil/lousho installed. Runs use Studio's built-in SDK 9.9.9-studio.",
+      },
+    });
+    await expect(selector.ready()).resolves.toMatchObject({ mode: 'in-process' });
+  });
+
+  it('row 2: the SDK checkout itself, unbuilt -> in-process with the build hint', () => {
+    const root = path.join(dir, 'sdk-src');
+    fs.mkdirSync(path.join(root, 'bin'), { recursive: true });
+    fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name: '@linuxdevil/lousho', version: '9.9.9' }));
+    fs.writeFileSync(path.join(root, 'bin', 'lousho.js'), '// bin\n');
+    const selector = new WorkspaceHostSelector(refFor(root), deps(root));
+    expect(selector.host).toBeInstanceOf(InProcessAgentHost);
+    expect(selector.client).toBeUndefined();
+    expect(selector.current().banner).toEqual({
+      tone: 'info',
+      text: "This SDK checkout is not built, so runs use Studio's built-in SDK 9.9.9-studio. Run npm run build to use it.",
+    });
+  });
+
+  it('row 3: bridge child without the command -> read-only with the update warning', async () => {
+    const root = path.join(dir, 'ws');
+    fs.mkdirSync(root, { recursive: true });
+    sdkWorkspace(root);
+    const selector = new WorkspaceHostSelector(refFor(root), deps(root, { FAKE_BRIDGE_MODE: 'unknown-command' }));
+    expect(selector.host).toBeInstanceOf(BridgeAgentHost);
+    expect(selector.client).toBeDefined();
+    expect(selector.reportsToObserve).toBe(false);
+    // Provisional snapshot before the handshake settles.
+    expect(selector.current()).toMatchObject({ mode: 'bridge', sdkVersion: '9.9.9-test', banner: null });
+    const settled = await selector.ready();
+    expect(settled.mode).toBe('read-only');
+    expect(settled.banner).toEqual({
+      tone: 'warning',
+      text: `Update @linuxdevil/lousho in this project to ${MIN_BRIDGE_SDK_VERSION} or later to edit agents here.`,
+    });
+    await expect(selector.host.start({ agentId: 'a', spec: {} as never, sessionId: 's', input: 'hi', onEvent: () => {} })).rejects.toBeInstanceOf(HostReadOnlyError);
+  });
+
+  it('row 4: hello without spec v2 -> read-only with the same update warning', async () => {
+    const root = path.join(dir, 'ws');
+    fs.mkdirSync(root, { recursive: true });
+    sdkWorkspace(root);
+    const selector = new WorkspaceHostSelector(refFor(root), deps(root, { FAKE_BRIDGE_SPEC_VERSIONS: '[1]' }));
+    const settled = await selector.ready();
+    expect(settled.mode).toBe('read-only');
+    expect(settled.banner?.tone).toBe('warning');
+    expect(settled.banner?.text).toContain(MIN_BRIDGE_SDK_VERSION);
+  });
+
+  it('row 5: protocol newer than Studio -> read-only with the newer-SDK warning', async () => {
+    const root = path.join(dir, 'ws');
+    fs.mkdirSync(root, { recursive: true });
+    sdkWorkspace(root);
+    const selector = new WorkspaceHostSelector(
+      refFor(root),
+      deps(root, { FAKE_BRIDGE_PROTOCOL: '2', FAKE_BRIDGE_SDK_VERSION: '99.0.0' })
+    );
+    const settled = await selector.ready();
+    expect(settled.mode).toBe('read-only');
+    expect(settled.banner).toEqual({
+      tone: 'warning',
+      text: "This project's @linuxdevil/lousho 99.0.0 is newer than this Studio understands. Update Studio to edit agents here.",
+    });
+  });
+
+  it('row 6: a good hello -> bridge mode, no banner, hello sdkVersion wins', async () => {
+    const root = path.join(dir, 'ws');
+    fs.mkdirSync(root, { recursive: true });
+    sdkWorkspace(root);
+    const onChange = vi.fn();
+    const selector = new WorkspaceHostSelector(refFor(root), deps(root, { FAKE_BRIDGE_SDK_VERSION: '8.8.8' }));
+    selector.onChange(onChange);
+    const settled = await selector.ready();
+    expect(settled).toMatchObject({ mode: 'bridge', sdkVersion: '8.8.8', banner: null });
+    expect(selector.current().mode).toBe('bridge');
+    expect(onChange).toHaveBeenCalled();
+    // The child env: observe target + workspace id + bridge flag, no studio token.
+    // The fake reports env on stderr after answering hello, so poll for it.
+    const deadline = Date.now() + 5_000;
+    let envLines: string[] = [];
+    while (Date.now() < deadline && envLines.length === 0) {
+      envLines = selector.client!.recentStderr().filter((l) => l.startsWith('env '));
+      if (envLines.length === 0) await new Promise((r) => setTimeout(r, 50));
+    }
+    try {
+    const env = Object.fromEntries(envLines.map((l) => l.slice(4).split(/=(.*)/s).slice(0, 2) as [string, string]));
+    expect(env.LOUSHO_OBSERVE).toBe('http://127.0.0.1:9');
+    expect(env.LOUSHO_OBSERVE_PROJECT).toBe(refFor(root).id);
+    expect(env.LOUSHO_BRIDGE).toBe('1');
+    expect(env.LOUSHO_STUDIO_TOKEN).toBe('<unset>');
+    } finally {
+      await selector.client!.stop();
+    }
+  });
+
+  it('row 7: handshake failure -> bridge mode with the restart banner', async () => {
+    const root = path.join(dir, 'ws');
+    fs.mkdirSync(root, { recursive: true });
+    sdkWorkspace(root);
+    const selector = new WorkspaceHostSelector(
+      refFor(root),
+      deps(root, { FAKE_BRIDGE_MODE: 'silent' }, { hello: 300 })
+    );
+    const settled = await selector.ready();
+    expect(settled.mode).toBe('bridge');
+    expect(settled.banner).toEqual({
+      tone: 'danger',
+      text: "This project's agent process keeps stopping. Check the Studio terminal for its output, then restart it.",
+      action: 'restart',
+    });
+    await selector.client!.stop();
+  });
+
+  it('envCollector reads LOUSHO_OBSERVE_URL/TOKEN per call', () => {
+    const prevUrl = process.env.LOUSHO_OBSERVE_URL;
+    const prevToken = process.env.LOUSHO_OBSERVE_TOKEN;
+    try {
+      process.env.LOUSHO_OBSERVE_URL = 'http://127.0.0.1:9999/';
+      process.env.LOUSHO_OBSERVE_TOKEN = 'tok';
+      expect(envCollector()).toEqual({ url: 'http://127.0.0.1:9999', token: 'tok' });
+      delete process.env.LOUSHO_OBSERVE_TOKEN;
+      expect(envCollector()).toEqual({ url: 'http://127.0.0.1:9999' });
+    } finally {
+      if (prevUrl === undefined) delete process.env.LOUSHO_OBSERVE_URL;
+      else process.env.LOUSHO_OBSERVE_URL = prevUrl;
+      if (prevToken === undefined) delete process.env.LOUSHO_OBSERVE_TOKEN;
+      else process.env.LOUSHO_OBSERVE_TOKEN = prevToken;
+    }
+  });
+});
diff --git a/apps/agent-forge/server/__tests__/idleVersions.test.ts b/apps/agent-forge/server/__tests__/idleVersions.test.ts
index f69774b66..d765f62c3 100644
--- a/apps/agent-forge/server/__tests__/idleVersions.test.ts
+++ b/apps/agent-forge/server/__tests__/idleVersions.test.ts
@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
-import type { AgentSpec } from 'lousho';
+import type { AgentSpec } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { startStudioServer } from '../index';
 import { STUDIO_TOKEN_HEADER } from '../auth';
diff --git a/apps/agent-forge/server/__tests__/importRoutes.test.ts b/apps/agent-forge/server/__tests__/importRoutes.test.ts
index 2babe3844..02ee3dc2f 100644
--- a/apps/agent-forge/server/__tests__/importRoutes.test.ts
+++ b/apps/agent-forge/server/__tests__/importRoutes.test.ts
@@ -10,7 +10,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
diff --git a/apps/agent-forge/server/__tests__/inProcessAgentHost.test.ts b/apps/agent-forge/server/__tests__/inProcessAgentHost.test.ts
index d05b1f702..3ba1cb967 100644
--- a/apps/agent-forge/server/__tests__/inProcessAgentHost.test.ts
+++ b/apps/agent-forge/server/__tests__/inProcessAgentHost.test.ts
@@ -10,7 +10,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { InProcessAgentHost } from '../host/inProcessAgentHost';
 import {
   HostRunNotActiveError,
diff --git a/apps/agent-forge/server/__tests__/inboxRoutes.test.ts b/apps/agent-forge/server/__tests__/inboxRoutes.test.ts
index c215bf658..8deb96ba5 100644
--- a/apps/agent-forge/server/__tests__/inboxRoutes.test.ts
+++ b/apps/agent-forge/server/__tests__/inboxRoutes.test.ts
@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
-import type { AgentSpec } from 'lousho';
+import type { AgentSpec } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
diff --git a/apps/agent-forge/server/__tests__/judge.test.ts b/apps/agent-forge/server/__tests__/judge.test.ts
index d268e407b..a2d9def8c 100644
--- a/apps/agent-forge/server/__tests__/judge.test.ts
+++ b/apps/agent-forge/server/__tests__/judge.test.ts
@@ -12,7 +12,7 @@ import * as os from 'node:os';
 import * as http from 'node:http';
 import { once } from 'node:events';
 import request from 'supertest';
-import { startObserveDaemon, type ObserveDaemon } from 'lousho/observe';
+import { startObserveDaemon, type ObserveDaemon } from '@linuxdevil/lousho/observe';
 import { createApp } from '../app';
 import { judgePrompt, parseJudgeReply, startJudgeLoop, type JudgeFn, type JudgeLoop, type JudgeLoopOptions } from '../judge';
 import { RunManager } from '../runRegistry';
diff --git a/apps/agent-forge/server/__tests__/localTools.test.ts b/apps/agent-forge/server/__tests__/localTools.test.ts
index 3570349c8..965eb0c30 100644
--- a/apps/agent-forge/server/__tests__/localTools.test.ts
+++ b/apps/agent-forge/server/__tests__/localTools.test.ts
@@ -12,7 +12,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
 import { FileCheckpointStore } from '../checkpointStore';
diff --git a/apps/agent-forge/server/__tests__/mcpProbe.test.ts b/apps/agent-forge/server/__tests__/mcpProbe.test.ts
index d2a2fde0c..7ab780a2e 100644
--- a/apps/agent-forge/server/__tests__/mcpProbe.test.ts
+++ b/apps/agent-forge/server/__tests__/mcpProbe.test.ts
@@ -4,8 +4,8 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import express, { type Express } from 'express';
 import request from 'supertest';
-import type { NamedToolDescriptor } from 'lousho';
-import type { connectMcp, McpConnections } from 'lousho/mcp';
+import type { NamedToolDescriptor } from '@linuxdevil/lousho';
+import type { connectMcp, McpConnections } from '@linuxdevil/lousho/mcp';
 import { createApp } from '../app';
 import { STUDIO_TOKEN_HEADER } from '../auth';
 import { registerMcpProbeRoute } from '../routes/mcpProbe';
diff --git a/apps/agent-forge/server/__tests__/mcpServers.test.ts b/apps/agent-forge/server/__tests__/mcpServers.test.ts
index 95820f4af..89996ff94 100644
--- a/apps/agent-forge/server/__tests__/mcpServers.test.ts
+++ b/apps/agent-forge/server/__tests__/mcpServers.test.ts
@@ -2,10 +2,10 @@ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import type { AgentSpecV2, SimpleAgent } from 'lousho';
-import { ConfigurationError, createAgent } from 'lousho';
-import { mockModel } from 'lousho/testing';
-import type { ServeMcpHandle, ServeMcpOptions } from 'lousho/mcp';
+import type { AgentSpecV2, SimpleAgent } from '@linuxdevil/lousho';
+import { ConfigurationError, createAgent } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
+import type { ServeMcpHandle, ServeMcpOptions } from '@linuxdevil/lousho/mcp';
 import { AgentRepo } from '../storage/agentRepo';
 import { VersionStore } from '../storage/versionStore';
 import { ServeConfigStore } from '../serve/serveConfigStore';
diff --git a/apps/agent-forge/server/__tests__/missingProviderKey.test.ts b/apps/agent-forge/server/__tests__/missingProviderKey.test.ts
index 006ca4afd..8b5926dff 100644
--- a/apps/agent-forge/server/__tests__/missingProviderKey.test.ts
+++ b/apps/agent-forge/server/__tests__/missingProviderKey.test.ts
@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import request from 'supertest';
-import type { AgentSpec } from 'lousho';
+import type { AgentSpec } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
diff --git a/apps/agent-forge/server/__tests__/multiWorkspace.test.ts b/apps/agent-forge/server/__tests__/multiWorkspace.test.ts
index 668ac8658..f15203b8f 100644
--- a/apps/agent-forge/server/__tests__/multiWorkspace.test.ts
+++ b/apps/agent-forge/server/__tests__/multiWorkspace.test.ts
@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
-import type { AgentSpec, AgentSpecV2 } from 'lousho';
+import type { AgentSpec, AgentSpecV2 } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import type { Express } from 'express';
 import { createWorkspaceContext, type WorkspaceContext, type WorkspaceServices } from '../workspace/context';
diff --git a/apps/agent-forge/server/__tests__/multiWorkspaceWs.test.ts b/apps/agent-forge/server/__tests__/multiWorkspaceWs.test.ts
index 80e1248c6..58e59a197 100644
--- a/apps/agent-forge/server/__tests__/multiWorkspaceWs.test.ts
+++ b/apps/agent-forge/server/__tests__/multiWorkspaceWs.test.ts
@@ -4,7 +4,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
 import { WebSocket } from 'ws';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { startStudioServer, type StudioServerHandle } from '../index';
 import { deferred, resetSteerGate, setSteerGateScript } from './steerGate';
 
diff --git a/apps/agent-forge/server/__tests__/noSdkSource.test.ts b/apps/agent-forge/server/__tests__/noSdkSource.test.ts
index b2dbe7358..8753c4d4a 100644
--- a/apps/agent-forge/server/__tests__/noSdkSource.test.ts
+++ b/apps/agent-forge/server/__tests__/noSdkSource.test.ts
@@ -1,74 +1,74 @@
-/**
- * W14 (PLAN §19.7): Studio imports the SDK through its package exports only.
- * Exercises the `lousho/no-sdk-source` ESLint rule the `lint:imports` gate runs.
- */
-import { RuleTester } from 'eslint';
-import tseslint from 'typescript-eslint';
-import { createRequire } from 'node:module';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const require = createRequire(import.meta.url);
-const { noSdkSource } = require('../../eslintRules/noSdkSource.mjs') as {
-  noSdkSource: import('eslint').Rule.RuleModule;
-};
-
-const APP = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
-const appFile = (rel: string) => path.join(APP, rel);
-
-new RuleTester({ languageOptions: { parser: tseslint.parser } }).run('no-sdk-source', noSdkSource, {
-  valid: [
-    { code: "import { AgentExecutor } from 'lousho';", filename: appFile('server/x.ts') },
-    { code: "import { agentSpecSchema } from 'lousho/spec';", filename: appFile('src/x.ts') },
-    { code: "import { startObserveDaemon } from 'lousho/observe';", filename: appFile('server/__tests__/x.test.ts') },
-    { code: "import type { ToolRef } from 'lousho/spec';", filename: appFile('src/graph/v2/specTypes.ts') },
-    { code: "import { helper } from '../../state/AppState';", filename: appFile('src/screens/x.ts') },
-    { code: "import { helper } from './local';", filename: appFile('server/x.ts') },
-    { code: "vi.mock('../../state/AppState');", filename: appFile('src/screens/x.test.ts') },
-    { code: "vi.mock('lousho/spec', () => ({}));", filename: appFile('src/x.test.ts') },
-    // In-app relative specifiers that stay inside apps/agent-forge are fine.
-    { code: "import { graphToSpec } from '../../src/graph/graphToSpec';", filename: appFile('server/__tests__/x.test.ts') },
-  ],
-  invalid: [
-    {
-      code: "import { x } from '../../../../src/index';",
-      filename: appFile('server/__tests__/x.test.ts'),
-      errors: [{ messageId: 'deep' }],
-    },
-    {
-      code: "import { x } from '@lousho/build-ai-agent/dist/spec/schema';",
-      filename: appFile('src/x.ts'),
-      errors: [{ messageId: 'deep' }],
-    },
-    {
-      code: "import { x } from 'lousho/src/spec/schema';",
-      filename: appFile('src/x.ts'),
-      errors: [{ messageId: 'deep' }],
-    },
-    {
-      code: "const m = await import('../../../../src/y');",
-      filename: appFile('server/__tests__/x.test.ts'),
-      errors: [{ messageId: 'deep' }],
-    },
-    {
-      code: "export * from '../../../../src/z';",
-      filename: appFile('server/x.ts'),
-      errors: [{ messageId: 'deep' }],
-    },
-    {
-      code: "export { x } from '../../../../src/w';",
-      filename: appFile('src/x.ts'),
-      errors: [{ messageId: 'deep' }],
-    },
-    {
-      code: "vi.mock('../../../../src/observe/daemon');",
-      filename: appFile('server/__tests__/x.test.ts'),
-      errors: [{ messageId: 'deep' }],
-    },
-    {
-      code: "vi.importActual('../../../../src/store');",
-      filename: appFile('server/__tests__/x.test.ts'),
-      errors: [{ messageId: 'deep' }],
-    },
-  ],
-});
+/**
+ * W14 (PLAN §19.7): Studio imports the SDK through its package exports only.
+ * Exercises the `lousho/no-sdk-source` ESLint rule the `lint:imports` gate runs.
+ */
+import { RuleTester } from 'eslint';
+import tseslint from 'typescript-eslint';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const { noSdkSource } = require('../../eslintRules/noSdkSource.mjs') as {
+  noSdkSource: import('eslint').Rule.RuleModule;
+};
+
+const APP = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const appFile = (rel: string) => path.join(APP, rel);
+
+new RuleTester({ languageOptions: { parser: tseslint.parser } }).run('no-sdk-source', noSdkSource, {
+  valid: [
+    { code: "import { AgentExecutor } from '@linuxdevil/lousho';", filename: appFile('server/x.ts') },
+    { code: "import { agentSpecSchema } from '@linuxdevil/lousho/spec';", filename: appFile('src/x.ts') },
+    { code: "import { startObserveDaemon } from '@linuxdevil/lousho/observe';", filename: appFile('server/__tests__/x.test.ts') },
+    { code: "import type { ToolRef } from '@linuxdevil/lousho/spec';", filename: appFile('src/graph/v2/specTypes.ts') },
+    { code: "import { helper } from '../../state/AppState';", filename: appFile('src/screens/x.ts') },
+    { code: "import { helper } from './local';", filename: appFile('server/x.ts') },
+    { code: "vi.mock('../../state/AppState');", filename: appFile('src/screens/x.test.ts') },
+    { code: "vi.mock('@linuxdevil/lousho/spec', () => ({}));", filename: appFile('src/x.test.ts') },
+    // In-app relative specifiers that stay inside apps/agent-forge are fine.
+    { code: "import { graphToSpec } from '../../src/graph/graphToSpec';", filename: appFile('server/__tests__/x.test.ts') },
+  ],
+  invalid: [
+    {
+      code: "import { x } from '../../../../src/index';",
+      filename: appFile('server/__tests__/x.test.ts'),
+      errors: [{ messageId: 'deep' }],
+    },
+    {
+      code: "import { x } from '@lousho/build-ai-agent/dist/spec/schema';",
+      filename: appFile('src/x.ts'),
+      errors: [{ messageId: 'deep' }],
+    },
+    {
+      code: "import { x } from '@linuxdevil/lousho/src/spec/schema';",
+      filename: appFile('src/x.ts'),
+      errors: [{ messageId: 'deep' }],
+    },
+    {
+      code: "const m = await import('../../../../src/y');",
+      filename: appFile('server/__tests__/x.test.ts'),
+      errors: [{ messageId: 'deep' }],
+    },
+    {
+      code: "export * from '../../../../src/z';",
+      filename: appFile('server/x.ts'),
+      errors: [{ messageId: 'deep' }],
+    },
+    {
+      code: "export { x } from '../../../../src/w';",
+      filename: appFile('src/x.ts'),
+      errors: [{ messageId: 'deep' }],
+    },
+    {
+      code: "vi.mock('../../../../src/observe/daemon');",
+      filename: appFile('server/__tests__/x.test.ts'),
+      errors: [{ messageId: 'deep' }],
+    },
+    {
+      code: "vi.importActual('../../../../src/store');",
+      filename: appFile('server/__tests__/x.test.ts'),
+      errors: [{ messageId: 'deep' }],
+    },
+  ],
+});
diff --git a/apps/agent-forge/server/__tests__/nodeFrames.test.ts b/apps/agent-forge/server/__tests__/nodeFrames.test.ts
index abc237859..3b14e9a4e 100644
--- a/apps/agent-forge/server/__tests__/nodeFrames.test.ts
+++ b/apps/agent-forge/server/__tests__/nodeFrames.test.ts
@@ -13,7 +13,7 @@ import {
   emptyRunUsage,
   type AgentSpecV2,
   type Span,
-} from 'lousho';
+} from '@linuxdevil/lousho';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
 import { attachWebSocketServer } from '../wsServer';
diff --git a/apps/agent-forge/server/__tests__/nodeStates.test.ts b/apps/agent-forge/server/__tests__/nodeStates.test.ts
index ff2b4f820..b5c147164 100644
--- a/apps/agent-forge/server/__tests__/nodeStates.test.ts
+++ b/apps/agent-forge/server/__tests__/nodeStates.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { APPROVAL_WAIT_SPAN_NAME, SdkAttr, type Span } from 'lousho';
+import { APPROVAL_WAIT_SPAN_NAME, SdkAttr, type Span } from '@linuxdevil/lousho';
 import { nodeStateFor } from '../nodeStates';
 
 const NOW = new Date('2026-10-29T12:00:00.000Z');
diff --git a/apps/agent-forge/server/__tests__/observeReporting.test.ts b/apps/agent-forge/server/__tests__/observeReporting.test.ts
index 553c7587e..2538a7b12 100644
--- a/apps/agent-forge/server/__tests__/observeReporting.test.ts
+++ b/apps/agent-forge/server/__tests__/observeReporting.test.ts
@@ -4,7 +4,7 @@
  * content is captured only for a loopback target.
  */
 import { describe, it, expect, afterEach } from 'vitest';
-import { observeExporterFromEnv, type ObserveReporter } from 'lousho/traces';
+import { observeExporterFromEnv, type ObserveReporter } from '@linuxdevil/lousho/traces';
 import { isLoopbackUrl, observeReporting } from '../observeReporting';
 
 const noFetch = (async () => new Response('{}', { status: 200 })) as typeof fetch;
diff --git a/apps/agent-forge/server/__tests__/pinSdkRange.test.ts b/apps/agent-forge/server/__tests__/pinSdkRange.test.ts
new file mode 100644
index 000000000..7919acbf9
--- /dev/null
+++ b/apps/agent-forge/server/__tests__/pinSdkRange.test.ts
@@ -0,0 +1,112 @@
+/**
+ * `scripts/pin-sdk-range.mjs` - the pack-time rewrite of the SDK dependency
+ * from `file:../..` to `^<sdk version>`, exercised against a temp monorepo
+ * layout (`<tmp>/apps/x` + `<tmp>/package.json`).
+ */
+import { 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';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+  'scripts',
+  'pin-sdk-range.mjs'
+);
+
+interface Fixture {
+  root: string;
+  app: string;
+  pkgPath: string;
+  backupPath: string;
+}
+
+function makeFixture({ withSdkRoot = true }: { withSdkRoot?: boolean } = {}): Fixture {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'lousho-pin-'));
+  const app = path.join(root, 'apps', 'x');
+  fs.mkdirSync(path.join(app, 'scripts'), { recursive: true });
+  fs.copyFileSync(SCRIPT, path.join(app, 'scripts', 'pin-sdk-range.mjs'));
+  if (withSdkRoot) {
+    fs.writeFileSync(
+      path.join(root, 'package.json'),
+      `${JSON.stringify({ name: '@linuxdevil/lousho', version: '9.9.9' }, null, 2)}\n`
+    );
+  }
+  const pkgPath = path.join(app, 'package.json');
+  fs.writeFileSync(
+    pkgPath,
+    `${JSON.stringify(
+      {
+        name: '@linuxdevil/studio',
+        version: '0.1.0-alpha.0',
+        dependencies: { '@linuxdevil/lousho': 'file:../..', yaml: '^2.9.1' },
+      },
+      null,
+      2
+    )}\n`
+  );
+  return { root, app, pkgPath, backupPath: path.join(app, '.package.json.prepack') };
+}
+
+function run(script: string, args: string[], cwd: string) {
+  return spawnSync(process.execPath, [script, ...args], { cwd, encoding: 'utf8' });
+}
+
+describe('pin-sdk-range.mjs', () => {
+  it('pin rewrites the SDK dep to ^<root version>, keeps a backup, refuses a second pin, restore puts it back', () => {
+    const fx = makeFixture();
+    try {
+      const original = fs.readFileSync(fx.pkgPath, 'utf8');
+      const pin = run('scripts/pin-sdk-range.mjs', ['pin'], fx.app);
+      expect(pin.status).toBe(0);
+      const pinned = JSON.parse(fs.readFileSync(fx.pkgPath, 'utf8')) as {
+        dependencies: Record<string, string>;
+      };
+      expect(pinned.dependencies['@linuxdevil/lousho']).toBe('^9.9.9');
+      expect(pinned.dependencies.yaml).toBe('^2.9.1');
+      expect(fs.existsSync(fx.backupPath)).toBe(true);
+      expect(fs.readFileSync(fx.backupPath, 'utf8')).toBe(original);
+
+      const second = run('scripts/pin-sdk-range.mjs', ['pin'], fx.app);
+      expect(second.status).toBe(1);
+      expect(second.stderr).toContain('restore first');
+
+      const restore = run('scripts/pin-sdk-range.mjs', ['restore'], fx.app);
+      expect(restore.status).toBe(0);
+      expect(fs.readFileSync(fx.pkgPath, 'utf8')).toBe(original);
+      expect(fs.existsSync(fx.backupPath)).toBe(false);
+    } finally {
+      fs.rmSync(fx.root, { recursive: true, force: true });
+    }
+  });
+
+  it('pin is a no-op when there is no SDK root package', () => {
+    const fx = makeFixture({ withSdkRoot: false });
+    try {
+      const original = fs.readFileSync(fx.pkgPath, 'utf8');
+      const pin = run('scripts/pin-sdk-range.mjs', ['pin'], fx.app);
+      expect(pin.status).toBe(0);
+      expect(fs.readFileSync(fx.pkgPath, 'utf8')).toBe(original);
+      expect(fs.existsSync(fx.backupPath)).toBe(false);
+    } finally {
+      fs.rmSync(fx.root, { recursive: true, force: true });
+    }
+  });
+
+  it('pin is a no-op when the root package is not the SDK', () => {
+    const fx = makeFixture();
+    try {
+      fs.writeFileSync(path.join(fx.root, 'package.json'), JSON.stringify({ name: 'other', version: '1.0.0' }));
+      const original = fs.readFileSync(fx.pkgPath, 'utf8');
+      const pin = run('scripts/pin-sdk-range.mjs', ['pin'], fx.app);
+      expect(pin.status).toBe(0);
+      expect(fs.readFileSync(fx.pkgPath, 'utf8')).toBe(original);
+    } finally {
+      fs.rmSync(fx.root, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/apps/agent-forge/server/__tests__/pins.test.ts b/apps/agent-forge/server/__tests__/pins.test.ts
index 943f44d53..2bc291e21 100644
--- a/apps/agent-forge/server/__tests__/pins.test.ts
+++ b/apps/agent-forge/server/__tests__/pins.test.ts
@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import type { AgentSpecV2, ToolCallHookContext } from 'lousho';
+import type { AgentSpecV2, ToolCallHookContext } from '@linuxdevil/lousho';
 import { MAX_PINS, pinsProblem, pinnedResultsHook } from '../pins';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
@@ -87,7 +87,7 @@ describe('pinnedResultsHook', () => {
 
 describe('RunManager run with pins', () => {
   // The `{ file }` tool ref resolves under the SpecHost baseDir
-  // (`<baseDir>/.lousho/agents`), and the tool file imports 'lousho'/'zod' -
+  // (`<baseDir>/.lousho/agents`), and the tool file imports '@linuxdevil/lousho'/'zod' -
   // so baseDir must live inside this repo for Node's resolution to find
   // them. `.tmp-pins-*` dirs are removed in afterEach.
   const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url));
@@ -111,7 +111,7 @@ describe('RunManager run with pins', () => {
       [
         "import { appendFileSync } from 'node:fs';",
         "import { z } from 'zod';",
-        "import { defineTool } from 'lousho';",
+        "import { defineTool } from '@linuxdevil/lousho';",
         `const MARKER = ${JSON.stringify(markerPath)};`,
         'export default defineTool({',
         "  name: 'spy-tool',",
diff --git a/apps/agent-forge/server/__tests__/playground.test.ts b/apps/agent-forge/server/__tests__/playground.test.ts
index ffe6e729d..e0bdc7822 100644
--- a/apps/agent-forge/server/__tests__/playground.test.ts
+++ b/apps/agent-forge/server/__tests__/playground.test.ts
@@ -4,7 +4,7 @@ import * as path from 'node:path';
 import * as os from 'node:os';
 import * as http from 'node:http';
 import type { AddressInfo } from 'node:net';
-import { LLMProviderRegistry, createMockProvider, type AgentEvent } from 'lousho';
+import { LLMProviderRegistry, createMockProvider, type AgentEvent } from '@linuxdevil/lousho';
 import request from 'supertest';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
diff --git a/apps/agent-forge/server/__tests__/portabilityRoutes.test.ts b/apps/agent-forge/server/__tests__/portabilityRoutes.test.ts
index 618d2baca..316ea0fae 100644
--- a/apps/agent-forge/server/__tests__/portabilityRoutes.test.ts
+++ b/apps/agent-forge/server/__tests__/portabilityRoutes.test.ts
@@ -11,7 +11,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import request from 'supertest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
diff --git a/apps/agent-forge/server/__tests__/publishEvalGate.test.ts b/apps/agent-forge/server/__tests__/publishEvalGate.test.ts
index 7aff514a8..c51d4347b 100644
--- a/apps/agent-forge/server/__tests__/publishEvalGate.test.ts
+++ b/apps/agent-forge/server/__tests__/publishEvalGate.test.ts
@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { EvalGateResult } from '../../shared/wireTypes';
 import type { EvalGateDeps } from '../evals/gateRunner';
 import { createApp } from '../app';
diff --git a/apps/agent-forge/server/__tests__/publishRoute.test.ts b/apps/agent-forge/server/__tests__/publishRoute.test.ts
index fb0e85dad..0b54c51a5 100644
--- a/apps/agent-forge/server/__tests__/publishRoute.test.ts
+++ b/apps/agent-forge/server/__tests__/publishRoute.test.ts
@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { AgentRecord } from '../../shared/wireTypes';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
diff --git a/apps/agent-forge/server/__tests__/questions.test.ts b/apps/agent-forge/server/__tests__/questions.test.ts
index 627d6713e..dcafaabfe 100644
--- a/apps/agent-forge/server/__tests__/questions.test.ts
+++ b/apps/agent-forge/server/__tests__/questions.test.ts
@@ -17,8 +17,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import request from 'supertest';
-import { LLMProviderRegistry, type AgentSpecV2 } from 'lousho';
-import { mockModel, type MockTurn } from 'lousho/testing';
+import { LLMProviderRegistry, type AgentSpecV2 } from '@linuxdevil/lousho';
+import { mockModel, type MockTurn } from '@linuxdevil/lousho/testing';
 import type { LogEntry } from '../../shared/wireTypes';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
diff --git a/apps/agent-forge/server/__tests__/ratings.test.ts b/apps/agent-forge/server/__tests__/ratings.test.ts
index 6ae784ac8..e56bbb164 100644
--- a/apps/agent-forge/server/__tests__/ratings.test.ts
+++ b/apps/agent-forge/server/__tests__/ratings.test.ts
@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
-import type { AgentSpec } from 'lousho';
+import type { AgentSpec } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
diff --git a/apps/agent-forge/server/__tests__/runRegistry.test.ts b/apps/agent-forge/server/__tests__/runRegistry.test.ts
index e5ea509ab..ee4cd789c 100644
--- a/apps/agent-forge/server/__tests__/runRegistry.test.ts
+++ b/apps/agent-forge/server/__tests__/runRegistry.test.ts
@@ -5,7 +5,7 @@ import * as os from 'node:os';
 import * as http from 'node:http';
 import type { AddressInfo } from 'node:net';
 import { WebSocket } from 'ws';
-import { upgradeSpec, type AgentSpec, type AgentSpecV2 } from 'lousho';
+import { upgradeSpec, type AgentSpec, type AgentSpecV2 } from '@linuxdevil/lousho';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
 import { deferred, resetSteerGate, setSteerGateScript } from './steerGate';
diff --git a/apps/agent-forge/server/__tests__/runSource.test.ts b/apps/agent-forge/server/__tests__/runSource.test.ts
index aa6e52668..e36bac670 100644
--- a/apps/agent-forge/server/__tests__/runSource.test.ts
+++ b/apps/agent-forge/server/__tests__/runSource.test.ts
@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { AgentRunStatusPayload, RunStatus } from '../../shared/wireTypes';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
diff --git a/apps/agent-forge/server/__tests__/sdkRoot.test.ts b/apps/agent-forge/server/__tests__/sdkRoot.test.ts
new file mode 100644
index 000000000..8e9c0639c
--- /dev/null
+++ b/apps/agent-forge/server/__tests__/sdkRoot.test.ts
@@ -0,0 +1,61 @@
+/**
+ * `sdkRootDir()` must find the SDK both from the monorepo (workspace
+ * symlink) and from an installed `node_modules/@linuxdevil/studio` layout.
+ */
+import { afterEach, describe, expect, it } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { sdkRootDir } from '../sdkRoot';
+
+const SDK_PACKAGE = '@linuxdevil/lousho';
+let tmp: string | undefined;
+
+afterEach(() => {
+  delete process.env.LOUSHO_SDK_ROOT;
+  if (tmp) fs.rmSync(tmp, { recursive: true, force: true });
+  tmp = undefined;
+});
+
+function pkgName(dir: string): string | undefined {
+  const pkgPath = path.join(dir, 'package.json');
+  return fs.existsSync(pkgPath) ? (JSON.parse(fs.readFileSync(pkgPath, 'utf8')) as { name?: string }).name : undefined;
+}
+
+describe('sdkRootDir', () => {
+  it('resolves the monorepo checkout to the SDK package root', () => {
+    const root = sdkRootDir();
+    expect(pkgName(root)).toBe(SDK_PACKAGE);
+    expect(fs.existsSync(path.join(root, 'registry', 'dist', 'index.json'))).toBe(true);
+  });
+
+  it('honours LOUSHO_SDK_ROOT', () => {
+    process.env.LOUSHO_SDK_ROOT = '/custom/sdk';
+    expect(sdkRootDir()).toBe('/custom/sdk');
+  });
+
+  it('finds the SDK from an installed node_modules/@linuxdevil/studio layout', () => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'lousho-sdkroot-'));
+    const sdkDir = path.join(tmp, 'node_modules', '@linuxdevil', 'lousho');
+    const studioDir = path.join(tmp, 'node_modules', '@linuxdevil', 'studio');
+    fs.mkdirSync(path.join(sdkDir, 'dist'), { recursive: true });
+    fs.mkdirSync(path.join(studioDir, 'dist-server'), { recursive: true });
+    fs.writeFileSync(
+      path.join(sdkDir, 'package.json'),
+      JSON.stringify({ name: SDK_PACKAGE, version: '1.0.0', main: 'dist/index.js' })
+    );
+    fs.writeFileSync(path.join(sdkDir, 'dist', 'index.js'), 'module.exports = {};\n');
+    const moduleDir = path.join(studioDir, 'dist-server');
+    expect(sdkRootDir(moduleDir)).toBe(sdkDir);
+  });
+
+  it('throws a clear error when the SDK cannot be resolved', () => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'lousho-sdkroot-'));
+    const moduleDir = path.join(tmp, 'dist-server');
+    fs.mkdirSync(moduleDir, { recursive: true });
+    // A temp dir outside any node_modules tree: resolution walks up to the
+    // filesystem root without finding the package (unless the machine has a
+    // global install, which the env override covers in real use).
+    expect(() => sdkRootDir(moduleDir)).toThrow(/could not locate the @linuxdevil\/lousho package/);
+  });
+});
diff --git a/apps/agent-forge/server/__tests__/serveRoutes.test.ts b/apps/agent-forge/server/__tests__/serveRoutes.test.ts
index 1f2a7ded5..70a6e20fc 100644
--- a/apps/agent-forge/server/__tests__/serveRoutes.test.ts
+++ b/apps/agent-forge/server/__tests__/serveRoutes.test.ts
@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
@@ -268,7 +268,7 @@ describe('/serve/<id> published-agent surface (X02a)', () => {
     });
 
     it('POST maps a missing MCP peer to 422 LOUSHO_MCP_PEER_MISSING', async () => {
-      const { ConfigurationError } = await import('lousho');
+      const { ConfigurationError } = await import('@linuxdevil/lousho');
       vi.mocked(mcpStub.start).mockRejectedValueOnce(
         new ConfigurationError('serveMcp: optional peer @modelcontextprotocol/sdk is not installed', 'mcp')
       );
diff --git a/apps/agent-forge/server/__tests__/serveWidget.test.ts b/apps/agent-forge/server/__tests__/serveWidget.test.ts
index aa4c67759..cda6c3b92 100644
--- a/apps/agent-forge/server/__tests__/serveWidget.test.ts
+++ b/apps/agent-forge/server/__tests__/serveWidget.test.ts
@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
diff --git a/apps/agent-forge/server/__tests__/serveWidgetKey.test.ts b/apps/agent-forge/server/__tests__/serveWidgetKey.test.ts
index c94bfef65..cace5884b 100644
--- a/apps/agent-forge/server/__tests__/serveWidgetKey.test.ts
+++ b/apps/agent-forge/server/__tests__/serveWidgetKey.test.ts
@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
diff --git a/apps/agent-forge/server/__tests__/steer.test.ts b/apps/agent-forge/server/__tests__/steer.test.ts
index fdf475c51..c1a5d1bd2 100644
--- a/apps/agent-forge/server/__tests__/steer.test.ts
+++ b/apps/agent-forge/server/__tests__/steer.test.ts
@@ -17,7 +17,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import { type AgentSpecV2 } from 'lousho';
+import { type AgentSpecV2 } from '@linuxdevil/lousho';
 import { RunManager, NoActiveRunError, SteerUnsupportedError } from '../runRegistry';
 import { newTestHost } from './testHost';
 import { FileCheckpointStore } from '../checkpointStore';
diff --git a/apps/agent-forge/server/__tests__/steerGate.ts b/apps/agent-forge/server/__tests__/steerGate.ts
index c2a34b6f9..2489a6738 100644
--- a/apps/agent-forge/server/__tests__/steerGate.ts
+++ b/apps/agent-forge/server/__tests__/steerGate.ts
@@ -15,7 +15,7 @@ import {
   type LLMProvider,
   type StreamChunk,
   type StreamResult,
-} from 'lousho';
+} from '@linuxdevil/lousho';
 
 export function deferred(): { promise: Promise<void>; resolve: () => void } {
   let resolve!: () => void;
diff --git a/apps/agent-forge/server/__tests__/suggestionRoutes.test.ts b/apps/agent-forge/server/__tests__/suggestionRoutes.test.ts
index 81244ef85..bdb39fa7a 100644
--- a/apps/agent-forge/server/__tests__/suggestionRoutes.test.ts
+++ b/apps/agent-forge/server/__tests__/suggestionRoutes.test.ts
@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
-import type { AgentSpec, AgentSpecV2 } from 'lousho';
+import type { AgentSpec, AgentSpecV2 } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
diff --git a/apps/agent-forge/server/__tests__/timeTravel.test.ts b/apps/agent-forge/server/__tests__/timeTravel.test.ts
index 39dea2dc0..27c7f6685 100644
--- a/apps/agent-forge/server/__tests__/timeTravel.test.ts
+++ b/apps/agent-forge/server/__tests__/timeTravel.test.ts
@@ -8,7 +8,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import request from 'supertest';
-import type { AgentSpec } from 'lousho';
+import type { AgentSpec } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
diff --git a/apps/agent-forge/server/__tests__/traces.test.ts b/apps/agent-forge/server/__tests__/traces.test.ts
index ec4bb2b98..2f0dbd1db 100644
--- a/apps/agent-forge/server/__tests__/traces.test.ts
+++ b/apps/agent-forge/server/__tests__/traces.test.ts
@@ -7,8 +7,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import request from 'supertest';
-import { listTraces } from 'lousho/traces';
-import type { AgentSpec } from 'lousho';
+import { listTraces } from '@linuxdevil/lousho/traces';
+import type { AgentSpec } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
diff --git a/apps/agent-forge/server/__tests__/triggerHost.test.ts b/apps/agent-forge/server/__tests__/triggerHost.test.ts
index d01ad9458..b1427f0fd 100644
--- a/apps/agent-forge/server/__tests__/triggerHost.test.ts
+++ b/apps/agent-forge/server/__tests__/triggerHost.test.ts
@@ -2,8 +2,8 @@ import { EventEmitter } from 'node:events';
 
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
-import type { AgentSpecV2 } from 'lousho';
-import type { TriggerSpec } from 'lousho/spec';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
+import type { TriggerSpec } from '@linuxdevil/lousho/spec';
 
 import type { AgentRepo } from '../storage/agentRepo';
 import { AlreadyRunningError, type RunManager } from '../runRegistry';
diff --git a/apps/agent-forge/server/__tests__/versionRoutes.test.ts b/apps/agent-forge/server/__tests__/versionRoutes.test.ts
index 0b85f0ef8..af3afd2b7 100644
--- a/apps/agent-forge/server/__tests__/versionRoutes.test.ts
+++ b/apps/agent-forge/server/__tests__/versionRoutes.test.ts
@@ -4,7 +4,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
 import { stringify as stringifyYaml } from 'yaml';
-import type { AgentSpec } from 'lousho';
+import type { AgentSpec } from '@linuxdevil/lousho';
 import { createApp } from '../app';
 import { StudioEventBus } from '../events/eventBus';
 import { RunManager } from '../runRegistry';
diff --git a/apps/agent-forge/server/__tests__/workspaceScanRoute.test.ts b/apps/agent-forge/server/__tests__/workspaceScanRoute.test.ts
index 4c65143f5..2379455bd 100644
--- a/apps/agent-forge/server/__tests__/workspaceScanRoute.test.ts
+++ b/apps/agent-forge/server/__tests__/workspaceScanRoute.test.ts
@@ -10,7 +10,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { Express } from 'express';
 import { createApp } from '../app';
 import { STUDIO_TOKEN_HEADER } from '../auth';
diff --git a/apps/agent-forge/server/__tests__/workspaceSdk.test.ts b/apps/agent-forge/server/__tests__/workspaceSdk.test.ts
index 27849019b..a9416285a 100644
--- a/apps/agent-forge/server/__tests__/workspaceSdk.test.ts
+++ b/apps/agent-forge/server/__tests__/workspaceSdk.test.ts
@@ -1,101 +1,101 @@
-/**
- * W11b: `findWorkspaceSdk` - Node's node_modules walk done by hand, the
- * SDK-checkout self case, and the `bin/lousho.js`/`built` gates.
- */
-import * as fs from 'node:fs';
-import * as os from 'node:os';
-import * as path from 'node:path';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { findWorkspaceSdk } from '../host/workspaceSdk';
-
-let dir: string;
-
-beforeEach(() => {
-  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'lou-w11b-sdk-'));
-});
-
-afterEach(() => {
-  fs.rmSync(dir, { recursive: true, force: true });
-});
-
-/** Writes a minimal SDK install: manifest + bin + optional dist marker. */
-function installSdk(nodeModulesDir: string, name: string, options: { built?: boolean; bin?: boolean } = {}): string {
-  const pkgDir = path.join(nodeModulesDir, ...name.split('/'));
-  fs.mkdirSync(path.join(pkgDir, 'bin'), { recursive: true });
-  fs.writeFileSync(path.join(pkgDir, 'package.json'), JSON.stringify({ name, version: '1.2.3' }));
-  if (options.bin !== false) fs.writeFileSync(path.join(pkgDir, 'bin', 'lousho.js'), '// bin\n');
-  if (options.built) {
-    fs.mkdirSync(path.join(pkgDir, 'dist', 'cli'), { recursive: true });
-    fs.writeFileSync(path.join(pkgDir, 'dist', 'cli', 'bridge.mjs'), '// bridge\n');
-  }
-  return pkgDir;
-}
-
-describe('findWorkspaceSdk', () => {
-  it('returns undefined for a folder with no SDK anywhere up the tree', () => {
-    // os.tmpdir() has no node_modules/@lousho or /lousho above it.
-    expect(findWorkspaceSdk(dir)).toBeUndefined();
-  });
-
-  it('returns undefined for a nonexistent root', () => {
-    expect(findWorkspaceSdk(path.join(dir, 'nope'))).toBeUndefined();
-  });
-
-  it('finds @lousho/build-ai-agent in the workspace root node_modules', () => {
-    const pkgDir = installSdk(path.join(dir, 'node_modules'), '@lousho/build-ai-agent', { built: true });
-    const sdk = findWorkspaceSdk(dir);
-    expect(sdk).toMatchObject({
-      version: '1.2.3',
-      packageDir: fs.realpathSync(pkgDir),
-      binPath: path.join(fs.realpathSync(pkgDir), 'bin', 'lousho.js'),
-      source: 'node_modules',
-      built: true,
-    });
-  });
-
-  it('finds lousho (the name the package ships under today) the same way', () => {
-    installSdk(path.join(dir, 'node_modules'), 'lousho');
-    expect(findWorkspaceSdk(dir)?.source).toBe('node_modules');
-  });
-
-  it('walks up to a parent folder node_modules (nearest hit wins)', () => {
-    installSdk(path.join(dir, 'node_modules'), 'lousho', { built: true });
-    const nested = path.join(dir, 'a', 'b');
-    fs.mkdirSync(nested, { recursive: true });
-    // A nearer install shadows the parent's.
-    installSdk(path.join(dir, 'a', 'node_modules'), 'lousho');
-    const sdk = findWorkspaceSdk(nested);
-    expect(sdk?.packageDir).toBe(fs.realpathSync(path.join(dir, 'a', 'node_modules', 'lousho')));
-  });
-
-  it('prefers the scoped name over lousho at the same level', () => {
-    installSdk(path.join(dir, 'node_modules'), 'lousho');
-    installSdk(path.join(dir, 'node_modules'), '@lousho/build-ai-agent');
-    const sdk = findWorkspaceSdk(dir);
-    expect(sdk?.packageDir).toContain(`${path.sep}@lousho${path.sep}build-ai-agent`);
-  });
-
-  it('classifies the SDK checkout itself as self, built only with dist/cli/bridge.mjs', () => {
-    fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name: 'lousho', version: '9.9.9' }));
-    fs.mkdirSync(path.join(dir, 'bin'), { recursive: true });
-    fs.writeFileSync(path.join(dir, 'bin', 'lousho.js'), '// bin\n');
-    const unbuilt = findWorkspaceSdk(dir);
-    expect(unbuilt).toMatchObject({ source: 'self', version: '9.9.9', built: false });
-    fs.mkdirSync(path.join(dir, 'dist', 'cli'), { recursive: true });
-    fs.writeFileSync(path.join(dir, 'dist', 'cli', 'bridge.mjs'), '// bridge\n');
-    expect(findWorkspaceSdk(dir)?.built).toBe(true);
-  });
-
-  it('returns undefined when bin/lousho.js is missing', () => {
-    installSdk(path.join(dir, 'node_modules'), 'lousho', { bin: false });
-    expect(findWorkspaceSdk(dir)).toBeUndefined();
-  });
-
-  it('returns undefined when the manifest name is not the SDK', () => {
-    const pkgDir = path.join(dir, 'node_modules', 'lousho');
-    fs.mkdirSync(path.join(pkgDir, 'bin'), { recursive: true });
-    fs.writeFileSync(path.join(pkgDir, 'package.json'), JSON.stringify({ name: 'not-lousho', version: '1.0.0' }));
-    fs.writeFileSync(path.join(pkgDir, 'bin', 'lousho.js'), '// bin\n');
-    expect(findWorkspaceSdk(dir)).toBeUndefined();
-  });
-});
+/**
+ * W11b: `findWorkspaceSdk` - Node's node_modules walk done by hand, the
+ * SDK-checkout self case, and the `bin/lousho.js`/`built` gates.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { findWorkspaceSdk } from '../host/workspaceSdk';
+
+let dir: string;
+
+beforeEach(() => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'lou-w11b-sdk-'));
+});
+
+afterEach(() => {
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+/** Writes a minimal SDK install: manifest + bin + optional dist marker. */
+function installSdk(nodeModulesDir: string, name: string, options: { built?: boolean; bin?: boolean } = {}): string {
+  const pkgDir = path.join(nodeModulesDir, ...name.split('/'));
+  fs.mkdirSync(path.join(pkgDir, 'bin'), { recursive: true });
+  fs.writeFileSync(path.join(pkgDir, 'package.json'), JSON.stringify({ name, version: '1.2.3' }));
+  if (options.bin !== false) fs.writeFileSync(path.join(pkgDir, 'bin', 'lousho.js'), '// bin\n');
+  if (options.built) {
+    fs.mkdirSync(path.join(pkgDir, 'dist', 'cli'), { recursive: true });
+    fs.writeFileSync(path.join(pkgDir, 'dist', 'cli', 'bridge.mjs'), '// bridge\n');
+  }
+  return pkgDir;
+}
+
+describe('findWorkspaceSdk', () => {
+  it('returns undefined for a folder with no SDK anywhere up the tree', () => {
+    // os.tmpdir() has no node_modules/@linuxdevil or /lousho above it.
+    expect(findWorkspaceSdk(dir)).toBeUndefined();
+  });
+
+  it('returns undefined for a nonexistent root', () => {
+    expect(findWorkspaceSdk(path.join(dir, 'nope'))).toBeUndefined();
+  });
+
+  it('finds @linuxdevil/lousho in the workspace root node_modules', () => {
+    const pkgDir = installSdk(path.join(dir, 'node_modules'), '@linuxdevil/lousho', { built: true });
+    const sdk = findWorkspaceSdk(dir);
+    expect(sdk).toMatchObject({
+      version: '1.2.3',
+      packageDir: fs.realpathSync(pkgDir),
+      binPath: path.join(fs.realpathSync(pkgDir), 'bin', 'lousho.js'),
+      source: 'node_modules',
+      built: true,
+    });
+  });
+
+  it('finds lousho (the legacy name) the same way', () => {
+    installSdk(path.join(dir, 'node_modules'), 'lousho');
+    expect(findWorkspaceSdk(dir)?.source).toBe('node_modules');
+  });
+
+  it('walks up to a parent folder node_modules (nearest hit wins)', () => {
+    installSdk(path.join(dir, 'node_modules'), 'lousho', { built: true });
+    const nested = path.join(dir, 'a', 'b');
+    fs.mkdirSync(nested, { recursive: true });
+    // A nearer install shadows the parent's.
+    installSdk(path.join(dir, 'a', 'node_modules'), 'lousho');
+    const sdk = findWorkspaceSdk(nested);
+    expect(sdk?.packageDir).toBe(fs.realpathSync(path.join(dir, 'a', 'node_modules', 'lousho')));
+  });
+
+  it('prefers the scoped name over lousho at the same level', () => {
+    installSdk(path.join(dir, 'node_modules'), 'lousho');
+    installSdk(path.join(dir, 'node_modules'), '@linuxdevil/lousho');
+    const sdk = findWorkspaceSdk(dir);
+    expect(sdk?.packageDir).toContain(`${path.sep}@linuxdevil${path.sep}lousho`);
+  });
+
+  it('classifies the SDK checkout itself as self, built only with dist/cli/bridge.mjs', () => {
+    fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name: '@linuxdevil/lousho', version: '9.9.9' }));
+    fs.mkdirSync(path.join(dir, 'bin'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'bin', 'lousho.js'), '// bin\n');
+    const unbuilt = findWorkspaceSdk(dir);
+    expect(unbuilt).toMatchObject({ source: 'self', version: '9.9.9', built: false });
+    fs.mkdirSync(path.join(dir, 'dist', 'cli'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'dist', 'cli', 'bridge.mjs'), '// bridge\n');
+    expect(findWorkspaceSdk(dir)?.built).toBe(true);
+  });
+
+  it('returns undefined when bin/lousho.js is missing', () => {
+    installSdk(path.join(dir, 'node_modules'), 'lousho', { bin: false });
+    expect(findWorkspaceSdk(dir)).toBeUndefined();
+  });
+
+  it('returns undefined when the manifest name is not the SDK', () => {
+    const pkgDir = path.join(dir, 'node_modules', '@linuxdevil/lousho');
+    fs.mkdirSync(path.join(pkgDir, 'bin'), { recursive: true });
+    fs.writeFileSync(path.join(pkgDir, 'package.json'), JSON.stringify({ name: 'not-lousho', version: '1.0.0' }));
+    fs.writeFileSync(path.join(pkgDir, 'bin', 'lousho.js'), '// bin\n');
+    expect(findWorkspaceSdk(dir)).toBeUndefined();
+  });
+});
diff --git a/apps/agent-forge/server/__tests__/workspaceSeam.test.ts b/apps/agent-forge/server/__tests__/workspaceSeam.test.ts
index cbb589002..08ddcf616 100644
--- a/apps/agent-forge/server/__tests__/workspaceSeam.test.ts
+++ b/apps/agent-forge/server/__tests__/workspaceSeam.test.ts
@@ -3,8 +3,8 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import request from 'supertest';
-import type { AgentSpec } from 'lousho';
-import { TriggerRegistry } from 'lousho/triggers';
+import type { AgentSpec } from '@linuxdevil/lousho';
+import { TriggerRegistry } from '@linuxdevil/lousho/triggers';
 import { createApp } from '../app';
 import { RunManager } from '../runRegistry';
 import { newTestHost } from './testHost';
diff --git a/apps/agent-forge/server/abortableProvider.test.ts b/apps/agent-forge/server/abortableProvider.test.ts
index c49d96463..1dae503ee 100644
--- a/apps/agent-forge/server/abortableProvider.test.ts
+++ b/apps/agent-forge/server/abortableProvider.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { MockLLMProvider } from 'lousho';
+import { MockLLMProvider } from '@linuxdevil/lousho';
 import { RunAbortedError, withAbortSignal } from './abortableProvider';
 
 const request = { model: 'mock-1', messages: [{ role: 'user' as const, content: 'hi' }] };
diff --git a/apps/agent-forge/server/abortableProvider.ts b/apps/agent-forge/server/abortableProvider.ts
index 14ae5be26..aa6452149 100644
--- a/apps/agent-forge/server/abortableProvider.ts
+++ b/apps/agent-forge/server/abortableProvider.ts
@@ -40,7 +40,7 @@
  * cancellation; this wrapper's shape (signal checked, forwarded if the
  * real provider accepts one) is what that wiring would build on.
  */
-import type { LLMProvider, GenerateOptions, GenerateResult, StreamChunk, StreamResult } from 'lousho';
+import type { LLMProvider, GenerateOptions, GenerateResult, StreamChunk, StreamResult } from '@linuxdevil/lousho';
 
 /**
  * Named `AbortError` (the fetch/AbortSignal convention) on purpose: the SDK's
diff --git a/apps/agent-forge/server/app.ts b/apps/agent-forge/server/app.ts
index c04777feb..c21f1b8a4 100644
--- a/apps/agent-forge/server/app.ts
+++ b/apps/agent-forge/server/app.ts
@@ -92,8 +92,8 @@ import {
   type AgentSpec,
   type AgentSpecV2,
   type ForkPatch,
-} from 'lousho';
-import type { connectMcp } from 'lousho/mcp';
+} from '@linuxdevil/lousho';
+import type { connectMcp } from '@linuxdevil/lousho/mcp';
 import type { LegacyAgentStore } from '../src/persistence/AgentStore';
 import {
   RunManager,
@@ -148,6 +148,7 @@ import { envCollector, WorkspaceHostSelector } from './host/hostSelector';
 import { HostReadOnlyError, HostStartError } from './host/bridgeAgentHost';
 import { HostUnsupportedError } from './host/hostStatus';
 import { registerAgentRoutes } from './routes/agentRoutes';
+import { registerEjectRoutes } from './ejectRoute';
 import { registerAllAgentsRoute } from './routes/allAgentsRoute';
 import { registerDraftRoutes } from './routes/draftRoutes';
 import { registerVersionRoutes } from './routes/versionRoutes';
@@ -1516,6 +1517,9 @@ export function createApp(options: CreateAppOptions): Express {
   // wire shapes, with ?view=legacy for the still-v1 canvas; stores come
   // from workspaceOf(req), the workspace seam).
   registerAgentRoutes(app, { templates, secrets });
+  // Eject to project (A08b): POST /agents/:id/eject writes the agent
+  // directory form under <workspace>/agents/<id>/ (workspaceOf seam).
+  registerEjectRoutes(app);
   // Draft routes: get/create/withdraw/approve/reject the per-agent pending
   // ChangeDraft (server/routes/draftRoutes.ts - stores come from
   // workspaceOf(req), the workspace seam).
diff --git a/apps/agent-forge/server/approvalStore.ts b/apps/agent-forge/server/approvalStore.ts
index 047eb89c3..1a24160f0 100644
--- a/apps/agent-forge/server/approvalStore.ts
+++ b/apps/agent-forge/server/approvalStore.ts
@@ -8,7 +8,7 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import type { ApprovalStore, ExecutionSnapshot, PendingApproval, ResolvedApproval } from 'lousho';
+import type { ApprovalStore, ExecutionSnapshot, PendingApproval, ResolvedApproval } from '@linuxdevil/lousho';
 
 export class FileApprovalStore implements ApprovalStore {
   constructor(private readonly baseDir: string) {}
diff --git a/apps/agent-forge/server/author/__tests__/provider.test.ts b/apps/agent-forge/server/author/__tests__/provider.test.ts
index 791352eb2..8b3dd1ea1 100644
--- a/apps/agent-forge/server/author/__tests__/provider.test.ts
+++ b/apps/agent-forge/server/author/__tests__/provider.test.ts
@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach, vi, type MockInstance } fr
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { LLMProviderRegistry, type LLMProvider } from 'lousho';
+import { LLMProviderRegistry, type LLMProvider } from '@linuxdevil/lousho';
 import { SecretsStore } from '../../secretsStore';
 import { resolveAuthorProvider } from '../provider';
 
diff --git a/apps/agent-forge/server/author/__tests__/requirements.test.ts b/apps/agent-forge/server/author/__tests__/requirements.test.ts
index bb46e50c7..181ed9c31 100644
--- a/apps/agent-forge/server/author/__tests__/requirements.test.ts
+++ b/apps/agent-forge/server/author/__tests__/requirements.test.ts
@@ -8,7 +8,7 @@ import { describe, it, expect, afterEach, vi } from 'vitest';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { computeRequirements, requirementDeps, type RequirementDeps } from '../requirements';
 import type { Requirement } from '../../../shared/authorWire';
 import type { SecretsStore } from '../../secretsStore';
diff --git a/apps/agent-forge/server/author/__tests__/saveFlow.test.ts b/apps/agent-forge/server/author/__tests__/saveFlow.test.ts
index 03a167c59..eb04c7531 100644
--- a/apps/agent-forge/server/author/__tests__/saveFlow.test.ts
+++ b/apps/agent-forge/server/author/__tests__/saveFlow.test.ts
@@ -2,8 +2,8 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { mockModel, type MockModel } from 'lousho/testing';
-import type { AgentSpecV2 } from 'lousho';
+import { mockModel, type MockModel } from '@linuxdevil/lousho/testing';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { AuthorSessionStore } from '../sessionStore';
 import { SettingsStore } from '../../settingsStore';
 import { SecretsStore } from '../../secretsStore';
diff --git a/apps/agent-forge/server/author/__tests__/turnContext.test.ts b/apps/agent-forge/server/author/__tests__/turnContext.test.ts
index b78156454..31720422f 100644
--- a/apps/agent-forge/server/author/__tests__/turnContext.test.ts
+++ b/apps/agent-forge/server/author/__tests__/turnContext.test.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { buildTurnContext, specSummary, TURN_CONTEXT_HEADER, type TurnContextInput } from '../turnContext';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 
 /**
  * buildTurnContext: the per-turn block the runner prepends to the user
diff --git a/apps/agent-forge/server/author/__tests__/turnRunner.test.ts b/apps/agent-forge/server/author/__tests__/turnRunner.test.ts
index 91d3dad80..6f630674b 100644
--- a/apps/agent-forge/server/author/__tests__/turnRunner.test.ts
+++ b/apps/agent-forge/server/author/__tests__/turnRunner.test.ts
@@ -2,8 +2,8 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { mockModel, type MockModel } from 'lousho/testing';
-import type { NamedToolDescriptor, ToolDescriptor } from 'lousho';
+import { mockModel, type MockModel } from '@linuxdevil/lousho/testing';
+import type { NamedToolDescriptor, ToolDescriptor } from '@linuxdevil/lousho';
 import { AuthorSessionStore } from '../sessionStore';
 import { SettingsStore } from '../../settingsStore';
 import { SecretsStore } from '../../secretsStore';
diff --git a/apps/agent-forge/server/author/authorScript.ts b/apps/agent-forge/server/author/authorScript.ts
index 13ec9fdf7..85e1b5d4a 100644
--- a/apps/agent-forge/server/author/authorScript.ts
+++ b/apps/agent-forge/server/author/authorScript.ts
@@ -14,8 +14,8 @@
  * outside e2e.
  */
 import { readFileSync } from 'node:fs';
-import { mockModel, type MockModel, type MockTurnObject } from 'lousho/testing';
-import type { LLMProvider } from 'lousho';
+import { mockModel, type MockModel, type MockTurnObject } from '@linuxdevil/lousho/testing';
+import type { LLMProvider } from '@linuxdevil/lousho';
 
 /** The env var naming the JSON file of scripted Author turns. */
 export const AUTHOR_SCRIPT_ENV = 'LOUSHO_FORGE_AUTHOR_SCRIPT';
diff --git a/apps/agent-forge/server/author/draft/__tests__/toSpec.test.ts b/apps/agent-forge/server/author/draft/__tests__/toSpec.test.ts
index eb76081a5..fc3e14fbe 100644
--- a/apps/agent-forge/server/author/draft/__tests__/toSpec.test.ts
+++ b/apps/agent-forge/server/author/draft/__tests__/toSpec.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { isValidAgentId } from '../../../../shared/agentId';
 import type { AuthorDraft, AuthorPatch } from '../schema';
 import { applyAuthorPatch, deriveAgentId, draftInvalidFailure, draftToSpec } from '../toSpec';
diff --git a/apps/agent-forge/server/author/draft/schema.ts b/apps/agent-forge/server/author/draft/schema.ts
index 1b73514fa..b24c577d4 100644
--- a/apps/agent-forge/server/author/draft/schema.ts
+++ b/apps/agent-forge/server/author/draft/schema.ts
@@ -13,8 +13,8 @@
  * JSON Schema surfaces to the model.
  */
 import { z } from 'zod';
-import { agentSpecV2Schema } from 'lousho';
-import type { AgentSpecV2 } from 'lousho';
+import { agentSpecV2Schema } from '@linuxdevil/lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 
 /** The spec keys the Author never sets: `version` is forced to 2, `evals` and `flow` are not in v1 of the Author. */
 export const DRAFT_OMITTED_KEYS = ['version', 'evals', 'flow'] as const;
diff --git a/apps/agent-forge/server/author/draft/toSpec.ts b/apps/agent-forge/server/author/draft/toSpec.ts
index bae53fa62..52310862c 100644
--- a/apps/agent-forge/server/author/draft/toSpec.ts
+++ b/apps/agent-forge/server/author/draft/toSpec.ts
@@ -10,8 +10,8 @@
  * Studio could not store. Catalog checks (is the model real, is the tool
  * known) and diffs are the propose tools' job, not this layer's.
  */
-import { agentSpecV2Schema } from 'lousho';
-import type { AgentSpecV2 } from 'lousho';
+import { agentSpecV2Schema } from '@linuxdevil/lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { AuthorToolFailure } from '../../../shared/authorWire';
 import { toolFailure } from '../tools/failure';
 import type { AuthorDraft, AuthorPatch } from './schema';
diff --git a/apps/agent-forge/server/author/modelMessages.ts b/apps/agent-forge/server/author/modelMessages.ts
index 4ed08e054..2372ad5be 100644
--- a/apps/agent-forge/server/author/modelMessages.ts
+++ b/apps/agent-forge/server/author/modelMessages.ts
@@ -11,7 +11,7 @@
  * messages (button saves, secret cards) arrive as user text starting with
  * `[UI event]` so the model never mistakes them for its own tool calls.
  */
-import type { Message, ToolCall } from 'lousho';
+import type { Message, ToolCall } from '@linuxdevil/lousho';
 import type {
   AuthorAssistantMessage,
   AuthorMessage,
diff --git a/apps/agent-forge/server/author/proposal/__tests__/catalogChecks.test.ts b/apps/agent-forge/server/author/proposal/__tests__/catalogChecks.test.ts
index 4d5379179..7ff31e677 100644
--- a/apps/agent-forge/server/author/proposal/__tests__/catalogChecks.test.ts
+++ b/apps/agent-forge/server/author/proposal/__tests__/catalogChecks.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { AuthorToolDeps, CatalogService } from '../../tools/index';
 import type { AuthorTurn } from '../../turnRunner';
 import type { WorkspaceContext } from '../../../workspace/context';
diff --git a/apps/agent-forge/server/author/proposal/__tests__/gate.test.ts b/apps/agent-forge/server/author/proposal/__tests__/gate.test.ts
index ec4ad3368..41dfe677c 100644
--- a/apps/agent-forge/server/author/proposal/__tests__/gate.test.ts
+++ b/apps/agent-forge/server/author/proposal/__tests__/gate.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type {
   AuthorAssistantMessage,
   AuthorMessage,
diff --git a/apps/agent-forge/server/author/proposal/__tests__/save.test.ts b/apps/agent-forge/server/author/proposal/__tests__/save.test.ts
index ee705354b..735df0bbc 100644
--- a/apps/agent-forge/server/author/proposal/__tests__/save.test.ts
+++ b/apps/agent-forge/server/author/proposal/__tests__/save.test.ts
@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import * as path from 'node:path';
-import { agentSpecV2Schema, type AgentSpecV2 } from 'lousho';
+import { agentSpecV2Schema, type AgentSpecV2 } from '@linuxdevil/lousho';
 import type { AuthorToolFailure, ProposalOutput } from '../../../../shared/authorWire';
 import type { StudioEvent } from '../../../../shared/wireTypes';
 import { AgentRepo, defaultMeta } from '../../../storage/agentRepo';
diff --git a/apps/agent-forge/server/author/proposal/catalogChecks.ts b/apps/agent-forge/server/author/proposal/catalogChecks.ts
index b17e537e5..662e94e61 100644
--- a/apps/agent-forge/server/author/proposal/catalogChecks.ts
+++ b/apps/agent-forge/server/author/proposal/catalogChecks.ts
@@ -15,7 +15,7 @@
  * `turn.state['catalogFacts']`): the model may propose several drafts in
  * a turn and the catalogs cannot change mid-turn.
  */
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { AuthorFailureCode, AuthorToolFailure } from '../../../shared/authorWire';
 import type { AuthorTurn } from '../turnRunner';
 import { toolFailure } from '../tools/failure';
diff --git a/apps/agent-forge/server/author/proposal/fold.ts b/apps/agent-forge/server/author/proposal/fold.ts
index dceda2df5..52f7ab816 100644
--- a/apps/agent-forge/server/author/proposal/fold.ts
+++ b/apps/agent-forge/server/author/proposal/fold.ts
@@ -12,7 +12,7 @@
  * returned here but ignored by the caller - folding is keyed on the spec
  * the card was built against, not on the card alone.
  */
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { ProposalOutput } from '../../../shared/authorWire';
 import { SPEC_FIELD_ORDER } from '../../../shared/specFields';
 import { stableStringify } from '../../../shared/stableJson';
diff --git a/apps/agent-forge/server/author/proposal/review.ts b/apps/agent-forge/server/author/proposal/review.ts
index a6338a5c6..742840cc8 100644
--- a/apps/agent-forge/server/author/proposal/review.ts
+++ b/apps/agent-forge/server/author/proposal/review.ts
@@ -9,7 +9,7 @@
  * `AuthorToolFailure` the tool hands back to the model), never a throw -
  * the review bouncing a draft is data, not an error.
  */
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { AuthorToolFailure, Requirement, SpecChange } from '../../../shared/authorWire';
 import type { AuthorTurn } from '../turnRunner';
 import type { ProposalIdentity } from './turnState';
diff --git a/apps/agent-forge/server/author/proposal/save.ts b/apps/agent-forge/server/author/proposal/save.ts
index a48681f28..0681b449c 100644
--- a/apps/agent-forge/server/author/proposal/save.ts
+++ b/apps/agent-forge/server/author/proposal/save.ts
@@ -12,7 +12,7 @@
  * (gate.ts) decides WHICH card may save - this module only performs the
  * write itself once a caller has resolved one.
  */
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type {
   AuthorToolFailure,
   ProposalOutput,
diff --git a/apps/agent-forge/server/author/provider.ts b/apps/agent-forge/server/author/provider.ts
index 0b40ec014..139e42c38 100644
--- a/apps/agent-forge/server/author/provider.ts
+++ b/apps/agent-forge/server/author/provider.ts
@@ -6,7 +6,7 @@
  * hatch: with no usable key the Author shows a setup card instead of
  * pretending to answer (PLAN 16 decision 4).
  */
-import { LLMProviderRegistry, type LLMProvider } from 'lousho';
+import { LLMProviderRegistry, type LLMProvider } from '@linuxdevil/lousho';
 import { PROVIDER_KEY_ENV, isSecretProvider, type SecretsStore } from '../secretsStore';
 
 /** The outcome of {@link resolveAuthorProvider}: a ready provider, or why the Author cannot run. */
diff --git a/apps/agent-forge/server/author/requirements.ts b/apps/agent-forge/server/author/requirements.ts
index 07f09fdf3..933c18547 100644
--- a/apps/agent-forge/server/author/requirements.ts
+++ b/apps/agent-forge/server/author/requirements.ts
@@ -19,7 +19,7 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { listBuiltinTools, listModels, type AgentSpecV2 } from 'lousho';
+import { listBuiltinTools, listModels, type AgentSpecV2 } from '@linuxdevil/lousho';
 import type { Requirement } from '../../shared/authorWire';
 import { isSecretProvider, PROVIDER_KEY_ENV, type SecretProvider, type SecretsStore } from '../secretsStore';
 
diff --git a/apps/agent-forge/server/author/review/__tests__/reviewDraft.test.ts b/apps/agent-forge/server/author/review/__tests__/reviewDraft.test.ts
index c5e45bbd7..caa3cd5de 100644
--- a/apps/agent-forge/server/author/review/__tests__/reviewDraft.test.ts
+++ b/apps/agent-forge/server/author/review/__tests__/reviewDraft.test.ts
@@ -2,8 +2,8 @@ import { mkdtempSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import * as path from 'node:path';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { mockModel, type MockModel } from 'lousho/testing';
-import type { AgentSpecV2 } from 'lousho';
+import { mockModel, type MockModel } from '@linuxdevil/lousho/testing';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { DRAFT_REVIEW_DIMENSIONS, isDraftReviewFailure, type AuthorToolFailure } from '../../../../shared/authorWire';
 import { SettingsStore } from '../../../settingsStore';
 import { SecretsStore } from '../../../secretsStore';
diff --git a/apps/agent-forge/server/author/review/__tests__/state.test.ts b/apps/agent-forge/server/author/review/__tests__/state.test.ts
index 820528ab7..f4bdba405 100644
--- a/apps/agent-forge/server/author/review/__tests__/state.test.ts
+++ b/apps/agent-forge/server/author/review/__tests__/state.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { AuthorMessage, Requirement, SpecChange } from '../../../../shared/authorWire';
 import type { AuthorTurn } from '../../turnRunner';
 import type { ReviewInput } from '../../proposal/review';
diff --git a/apps/agent-forge/server/author/review/reviewDraft.ts b/apps/agent-forge/server/author/review/reviewDraft.ts
index 7214e6af8..3e3eec320 100644
--- a/apps/agent-forge/server/author/review/reviewDraft.ts
+++ b/apps/agent-forge/server/author/review/reviewDraft.ts
@@ -9,7 +9,7 @@
  * no steps left to redraft in) fails open: the review never hides a card
  * it could not judge.
  */
-import { createAgent, listBuiltinTools, listGuardrails, listTriggerTypes, type LLMProvider } from 'lousho';
+import { createAgent, listBuiltinTools, listGuardrails, listTriggerTypes, type LLMProvider } from '@linuxdevil/lousho';
 import { z } from 'zod';
 import {
   DRAFT_REVIEW_DIMENSIONS,
diff --git a/apps/agent-forge/server/author/review/state.ts b/apps/agent-forge/server/author/review/state.ts
index 23ef692a6..e5a7f1d01 100644
--- a/apps/agent-forge/server/author/review/state.ts
+++ b/apps/agent-forge/server/author/review/state.ts
@@ -7,7 +7,7 @@
  * cannot blow the review prompt up, and the catalog facts the judge
  * checks membership against.
  */
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { AuthorMessage, Requirement, SpecChange } from '../../../shared/authorWire';
 import type { CatalogFacts } from '../proposal/catalogChecks';
 import type { ReviewInput } from '../proposal/review';
diff --git a/apps/agent-forge/server/author/services.ts b/apps/agent-forge/server/author/services.ts
index 252b60e1f..c63fad76d 100644
--- a/apps/agent-forge/server/author/services.ts
+++ b/apps/agent-forge/server/author/services.ts
@@ -12,8 +12,8 @@
  * seams (`providerFor`, `reviewDraft`, `mcpConnect`) exist for tests and
  * the eval's `--mock`/`--no-review` modes.
  */
-import type { LLMProvider } from 'lousho';
-import type { connectMcp } from 'lousho/mcp';
+import type { LLMProvider } from '@linuxdevil/lousho';
+import type { connectMcp } from '@linuxdevil/lousho/mcp';
 import type { AuthorSession } from '../../shared/authorWire';
 import type { SettingsStore } from '../settingsStore';
 import type { SecretsStore } from '../secretsStore';
diff --git a/apps/agent-forge/server/author/tools/__tests__/condenseTrace.test.ts b/apps/agent-forge/server/author/tools/__tests__/condenseTrace.test.ts
index 5f1f7d273..d2092edfe 100644
--- a/apps/agent-forge/server/author/tools/__tests__/condenseTrace.test.ts
+++ b/apps/agent-forge/server/author/tools/__tests__/condenseTrace.test.ts
@@ -2,8 +2,8 @@ import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'nod
 import { tmpdir } from 'node:os';
 import * as path from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
-import { testToolContext } from 'lousho/testing';
-import type { ToolDescriptor } from 'lousho';
+import { testToolContext } from '@linuxdevil/lousho/testing';
+import type { ToolDescriptor } from '@linuxdevil/lousho';
 import { condenseTrace, TRACE_STEP_LIMIT, type GetTraceOutput } from '../condenseTrace';
 import { agentTraceDir } from '../../../traceStore';
 import { AgentRepo } from '../../../storage/agentRepo';
diff --git a/apps/agent-forge/server/author/tools/__tests__/proposeAgent.test.ts b/apps/agent-forge/server/author/tools/__tests__/proposeAgent.test.ts
index c40899f0b..d346afdd1 100644
--- a/apps/agent-forge/server/author/tools/__tests__/proposeAgent.test.ts
+++ b/apps/agent-forge/server/author/tools/__tests__/proposeAgent.test.ts
@@ -2,8 +2,8 @@ import { mkdirSync, mkdtempSync, readdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import * as path from 'node:path';
 import { describe, expect, it } from 'vitest';
-import { testToolContext } from 'lousho/testing';
-import type { AgentSpecV2 } from 'lousho';
+import { testToolContext } from '@linuxdevil/lousho/testing';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { AuthorToolDeps, CatalogService } from '../index';
 import type { AuthorTurn } from '../../turnRunner';
 import type { WorkspaceContext } from '../../../workspace/context';
diff --git a/apps/agent-forge/server/author/tools/__tests__/proposeAgentUpdate.test.ts b/apps/agent-forge/server/author/tools/__tests__/proposeAgentUpdate.test.ts
index 58a7f8e13..aec2584c7 100644
--- a/apps/agent-forge/server/author/tools/__tests__/proposeAgentUpdate.test.ts
+++ b/apps/agent-forge/server/author/tools/__tests__/proposeAgentUpdate.test.ts
@@ -2,8 +2,8 @@ import { mkdtempSync, readdirSync, readFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import * as path from 'node:path';
 import { describe, expect, it } from 'vitest';
-import { testToolContext } from 'lousho/testing';
-import type { AgentSpecV2 } from 'lousho';
+import { testToolContext } from '@linuxdevil/lousho/testing';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { AuthorToolDeps, CatalogService } from '../index';
 import type { AuthorTurn } from '../../turnRunner';
 import type { WorkspaceContext } from '../../../workspace/context';
diff --git a/apps/agent-forge/server/author/tools/__tests__/readTools.test.ts b/apps/agent-forge/server/author/tools/__tests__/readTools.test.ts
index f328db04c..3ca6c1ef2 100644
--- a/apps/agent-forge/server/author/tools/__tests__/readTools.test.ts
+++ b/apps/agent-forge/server/author/tools/__tests__/readTools.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { AgentRepo } from '../../../storage/agentRepo';
 import type { VersionStore } from '../../../storage/versionStore';
 import type { WorkspaceContext } from '../../../workspace/context';
diff --git a/apps/agent-forge/server/author/tools/__tests__/requestSecret.test.ts b/apps/agent-forge/server/author/tools/__tests__/requestSecret.test.ts
index 74cb27c2f..ef6af340d 100644
--- a/apps/agent-forge/server/author/tools/__tests__/requestSecret.test.ts
+++ b/apps/agent-forge/server/author/tools/__tests__/requestSecret.test.ts
@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { testToolContext } from 'lousho/testing';
+import { testToolContext } from '@linuxdevil/lousho/testing';
 import { AUTHOR_TOOL_FACTORIES, buildAuthorTools, type AuthorToolDeps } from '../index';
 import type { AuthorTurn } from '../../turnRunner';
 import type { AuthorToolFailure, RequestSecretOutput } from '../../../../shared/authorWire';
diff --git a/apps/agent-forge/server/author/tools/__tests__/runDraft.test.ts b/apps/agent-forge/server/author/tools/__tests__/runDraft.test.ts
index 769ecf8bb..f8aee0117 100644
--- a/apps/agent-forge/server/author/tools/__tests__/runDraft.test.ts
+++ b/apps/agent-forge/server/author/tools/__tests__/runDraft.test.ts
@@ -3,8 +3,8 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import * as path from 'node:path';
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { testToolContext } from 'lousho/testing';
-import { ConfigurationError, type AgentSpecV2, type ToolDescriptor } from 'lousho';
+import { testToolContext } from '@linuxdevil/lousho/testing';
+import { ConfigurationError, type AgentSpecV2, type ToolDescriptor } from '@linuxdevil/lousho';
 import { AlreadyRunningError, RunManager } from '../../../runRegistry';
 import { readAgentTrace } from '../../../traceStore';
 import { AgentRepo } from '../../../storage/agentRepo';
diff --git a/apps/agent-forge/server/author/tools/__tests__/stateTools.test.ts b/apps/agent-forge/server/author/tools/__tests__/stateTools.test.ts
index 6818feb7d..646c8bf0b 100644
--- a/apps/agent-forge/server/author/tools/__tests__/stateTools.test.ts
+++ b/apps/agent-forge/server/author/tools/__tests__/stateTools.test.ts
@@ -2,8 +2,8 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import * as path from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
-import { testToolContext } from 'lousho/testing';
-import type { AgentSpecV2, ToolDescriptor } from 'lousho';
+import { testToolContext } from '@linuxdevil/lousho/testing';
+import type { AgentSpecV2, ToolDescriptor } from '@linuxdevil/lousho';
 import { buildAuthorTools, type AuthorToolDeps, type CatalogService } from '../index';
 import type { AuthorTurn } from '../../turnRunner';
 import type { WorkspaceContext } from '../../../workspace/context';
diff --git a/apps/agent-forge/server/author/tools/catalogService.ts b/apps/agent-forge/server/author/tools/catalogService.ts
index a97ed5fbf..fea8bc250 100644
--- a/apps/agent-forge/server/author/tools/catalogService.ts
+++ b/apps/agent-forge/server/author/tools/catalogService.ts
@@ -6,7 +6,7 @@
  * (shared with the route's reader so the two never parse it
  * differently).
  */
-import { listModels } from 'lousho';
+import { listModels } from '@linuxdevil/lousho';
 import type { SecretsStore } from '../../secretsStore';
 import { loadStaticCatalog, withStoredKeyAvailability } from '../../routes/catalogRoutes';
 import type { CatalogService } from './index';
diff --git a/apps/agent-forge/server/author/tools/getTraceTool.ts b/apps/agent-forge/server/author/tools/getTraceTool.ts
index bd360e620..3fb5679a3 100644
--- a/apps/agent-forge/server/author/tools/getTraceTool.ts
+++ b/apps/agent-forge/server/author/tools/getTraceTool.ts
@@ -8,7 +8,7 @@
  * `.lousho/agents/<id>/traces`. With `agentId` the lookup is scoped;
  * without it every saved agent's folder is tried in turn.
  */
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 import { isValidTraceId, readAgentTrace } from '../../traceStore';
 import { isValidAgentId } from '../../../shared/agentId';
diff --git a/apps/agent-forge/server/author/tools/index.ts b/apps/agent-forge/server/author/tools/index.ts
index adfa2f079..061dec273 100644
--- a/apps/agent-forge/server/author/tools/index.ts
+++ b/apps/agent-forge/server/author/tools/index.ts
@@ -14,7 +14,7 @@
  * is D17's catalog, `probeMcp` is D11's probe as a function, and
  * `docsDir` is the bundled SDK docs folder `searchDocs` reads.
  */
-import type { AgentSpecV2, ToolDescriptor } from 'lousho';
+import type { AgentSpecV2, ToolDescriptor } from '@linuxdevil/lousho';
 import type { Requirement } from '../../../shared/authorWire';
 import type {
   CatalogGuardrail,
diff --git a/apps/agent-forge/server/author/tools/mcpProbeTool.ts b/apps/agent-forge/server/author/tools/mcpProbeTool.ts
index a8e8eb20e..9e6ec10bf 100644
--- a/apps/agent-forge/server/author/tools/mcpProbeTool.ts
+++ b/apps/agent-forge/server/author/tools/mcpProbeTool.ts
@@ -17,7 +17,7 @@
  * deadline, `MCP_PROBE_FAILED` for everything else, and the `UNAVAILABLE`
  * catch-all for a thrown dep error (guardedToolCall).
  */
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 import type { McpServerSpecV2 } from '../../../shared/wireTypes';
 import { guardedToolCall, toolFailure } from './failure';
diff --git a/apps/agent-forge/server/author/tools/openPageTool.ts b/apps/agent-forge/server/author/tools/openPageTool.ts
index 35aa4de69..715a6c7ec 100644
--- a/apps/agent-forge/server/author/tools/openPageTool.ts
+++ b/apps/agent-forge/server/author/tools/openPageTool.ts
@@ -9,7 +9,7 @@
  * the tool's output ends up in a client `history.push`, so anything
  * else is `INVALID_INPUT`, not a navigation.
  */
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 import { guardedToolCall, toolFailure } from './failure';
 import type { AuthorToolFactory } from './index';
diff --git a/apps/agent-forge/server/author/tools/proposeAgentTool.ts b/apps/agent-forge/server/author/tools/proposeAgentTool.ts
index 5a97c27a1..7637f29b0 100644
--- a/apps/agent-forge/server/author/tools/proposeAgentTool.ts
+++ b/apps/agent-forge/server/author/tools/proposeAgentTool.ts
@@ -13,7 +13,7 @@
  * 'create' identity in {@link proposalTurnState} and returned - a failed
  * step leaves `proposed` untouched.
  */
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 import type { ProposalOutput } from '../../../shared/authorWire';
 import { authorDraftSchema } from '../draft/schema';
diff --git a/apps/agent-forge/server/author/tools/proposeAgentUpdateTool.ts b/apps/agent-forge/server/author/tools/proposeAgentUpdateTool.ts
index d717b9f11..d3e5538dd 100644
--- a/apps/agent-forge/server/author/tools/proposeAgentUpdateTool.ts
+++ b/apps/agent-forge/server/author/tools/proposeAgentUpdateTool.ts
@@ -14,9 +14,9 @@
  * and fall back to the saved instructions, then the merged patch runs the
  * same build / catalog / requirements / review gauntlet as `proposeAgent`.
  */
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { AuthorToolFailure, ProposalOutput } from '../../../shared/authorWire';
 import { diffSpecs } from '../../diff/specChange';
 import { specHash } from '../../storage/specHash';
diff --git a/apps/agent-forge/server/author/tools/readTools.ts b/apps/agent-forge/server/author/tools/readTools.ts
index 797024ead..2dc5583c7 100644
--- a/apps/agent-forge/server/author/tools/readTools.ts
+++ b/apps/agent-forge/server/author/tools/readTools.ts
@@ -11,9 +11,9 @@
  * `AGENT_NOT_FOUND` of `getCurrentSpec` and the `UNAVAILABLE` catch-all
  * of `guardedToolCall`.
  */
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { McpServerSpecV2 } from '../../../shared/wireTypes';
 import type { WorkspaceContext } from '../../workspace/context';
 import { specHash } from '../../storage/specHash';
diff --git a/apps/agent-forge/server/author/tools/requestSecretTool.ts b/apps/agent-forge/server/author/tools/requestSecretTool.ts
index 2818d36ef..83d6eb393 100644
--- a/apps/agent-forge/server/author/tools/requestSecretTool.ts
+++ b/apps/agent-forge/server/author/tools/requestSecretTool.ts
@@ -12,7 +12,7 @@
  * Settings, and letting the Author store a second copy under a named
  * secret would silently shadow the Settings value.
  */
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 import type { RequestSecretOutput } from '../../../shared/authorWire';
 import { guardedToolCall, toolFailure } from './failure';
diff --git a/apps/agent-forge/server/author/tools/runDraftTool.ts b/apps/agent-forge/server/author/tools/runDraftTool.ts
index 679887487..17a6ed7d6 100644
--- a/apps/agent-forge/server/author/tools/runDraftTool.ts
+++ b/apps/agent-forge/server/author/tools/runDraftTool.ts
@@ -9,7 +9,7 @@
  * proposal: `run(agentId, input)` with no spec argument is, by
  * definition, the saved working copy.
  */
-import { defineTool, SDKError } from 'lousho';
+import { defineTool, SDKError } from '@linuxdevil/lousho';
 import { z } from 'zod';
 import { AgentNotFoundError, AlreadyRunningError, type RunManager } from '../../runRegistry';
 import { isValidAgentId } from '../../../shared/agentId';
diff --git a/apps/agent-forge/server/author/tools/saveTools.ts b/apps/agent-forge/server/author/tools/saveTools.ts
index 21b4febdc..70e65eca8 100644
--- a/apps/agent-forge/server/author/tools/saveTools.ts
+++ b/apps/agent-forge/server/author/tools/saveTools.ts
@@ -11,7 +11,7 @@
  * marks the identity in `proposalTurnState().saved` so a second save in
  * the same turn refuses `ALREADY_SAVED`.
  */
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 import type { AuthorToolFailure } from '../../../shared/authorWire';
 import { resolveStoredProposal, saveBlockingError } from '../proposal/gate';
diff --git a/apps/agent-forge/server/author/tools/searchDocsTool.ts b/apps/agent-forge/server/author/tools/searchDocsTool.ts
index 714e6f009..6627b8497 100644
--- a/apps/agent-forge/server/author/tools/searchDocsTool.ts
+++ b/apps/agent-forge/server/author/tools/searchDocsTool.ts
@@ -9,7 +9,7 @@
  * bundled docs (docsIndex.ts normalizes an unreadable folder to
  * `undefined`).
  */
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 import { loadDocsIndex, searchDocs } from './docsIndex';
 import { guardedToolCall, toolFailure } from './failure';
diff --git a/apps/agent-forge/server/author/tools/stateTools.ts b/apps/agent-forge/server/author/tools/stateTools.ts
index 454af8264..846cd8948 100644
--- a/apps/agent-forge/server/author/tools/stateTools.ts
+++ b/apps/agent-forge/server/author/tools/stateTools.ts
@@ -16,9 +16,9 @@
  * `POST /assistant/sessions/:id/enable` (the SuccessCard's "Enable agent"
  * button) so the button and the model switch an agent identically.
  */
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type {
   AuthorToolFailure,
   Requirement,
diff --git a/apps/agent-forge/server/author/turnContext.ts b/apps/agent-forge/server/author/turnContext.ts
index 8854e82b4..b421be2a9 100644
--- a/apps/agent-forge/server/author/turnContext.ts
+++ b/apps/agent-forge/server/author/turnContext.ts
@@ -11,7 +11,7 @@
  * appear here: the summary names `mcpServers` keys and `SecretRef` refs,
  * never their payloads.
  */
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { AuthorFocus } from '../../shared/authorWire';
 
 /** The first line of every turn-context block: tells the model the block is app data, not user text. */
diff --git a/apps/agent-forge/server/author/turnRunner.ts b/apps/agent-forge/server/author/turnRunner.ts
index 652b9aba1..25c842276 100644
--- a/apps/agent-forge/server/author/turnRunner.ts
+++ b/apps/agent-forge/server/author/turnRunner.ts
@@ -20,7 +20,7 @@ import {
   type AgentEvent,
   type LLMProvider,
   type ToolDescriptor,
-} from 'lousho';
+} from '@linuxdevil/lousho';
 import type {
   AuthorAssistantMessage,
   AuthorFocus,
diff --git a/apps/agent-forge/server/author/wiring.ts b/apps/agent-forge/server/author/wiring.ts
index aea672607..6ed7ad0f9 100644
--- a/apps/agent-forge/server/author/wiring.ts
+++ b/apps/agent-forge/server/author/wiring.ts
@@ -10,8 +10,8 @@
  * second runner would have its own turn slots and the one-running-turn-
  * per-session rule (and the DELETE 409) would stop holding.
  */
-import { listBuiltinTools, listGuardrails, listModels, listTriggerTypes, type LLMProvider } from 'lousho';
-import type { connectMcp } from 'lousho/mcp';
+import { listBuiltinTools, listGuardrails, listModels, listTriggerTypes, type LLMProvider } from '@linuxdevil/lousho';
+import type { connectMcp } from '@linuxdevil/lousho/mcp';
 import type { SettingsStore } from '../settingsStore';
 import type { SecretsStore } from '../secretsStore';
 import type { TemplateCatalog } from '../templates/templateCatalog';
diff --git a/apps/agent-forge/server/autoApproval.ts b/apps/agent-forge/server/autoApproval.ts
index 11f213557..f2d031337 100644
--- a/apps/agent-forge/server/autoApproval.ts
+++ b/apps/agent-forge/server/autoApproval.ts
@@ -27,7 +27,7 @@ import {
   type GenerateOptions,
   type LLMProvider,
   type ProviderUsage,
-} from 'lousho';
+} from '@linuxdevil/lousho';
 import type { LogEntry } from '../shared/wireTypes';
 import { resolveProviderForModel } from './buildAgent';
 import type { PassRecord } from './passes/passRunner';
diff --git a/apps/agent-forge/server/buildAgent.test.ts b/apps/agent-forge/server/buildAgent.test.ts
index bf88bd9d7..a19757dee 100644
--- a/apps/agent-forge/server/buildAgent.test.ts
+++ b/apps/agent-forge/server/buildAgent.test.ts
@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import { ConfigurationError, type AgentSpec } from 'lousho';
+import { ConfigurationError, type AgentSpec } from '@linuxdevil/lousho';
 import { buildAgentFromSpec, resolveProviderForModel } from './buildAgent';
 import { SecretsStore } from './secretsStore';
 
diff --git a/apps/agent-forge/server/buildAgent.ts b/apps/agent-forge/server/buildAgent.ts
index 3a4914faa..472ed91c3 100644
--- a/apps/agent-forge/server/buildAgent.ts
+++ b/apps/agent-forge/server/buildAgent.ts
@@ -14,7 +14,7 @@
  * all public SDK exports) itself, rather than reaching past `specToAgent()`
  * into SDK internals.
  */
-import { AgentBuilder, ToolRegistry } from 'lousho/executor';
+import { AgentBuilder, ToolRegistry } from '@linuxdevil/lousho/executor';
 import {
   ConfigurationError,
   NoopSandbox,
@@ -28,8 +28,8 @@ import {
   type LLMProvider,
   type SandboxAdapter,
   type ToolDescriptor,
-} from 'lousho';
-import type { AgentFlow } from 'lousho/flows';
+} from '@linuxdevil/lousho';
+import type { AgentFlow } from '@linuxdevil/lousho/flows';
 import { compileHooksFromSpecPolicy } from './compileHooks';
 import { PROVIDER_KEY_ENV, isSecretProvider, type SecretsStore } from './secretsStore';
 
diff --git a/apps/agent-forge/server/buildAgentV2.ts b/apps/agent-forge/server/buildAgentV2.ts
index be31cfe4a..42adde8f3 100644
--- a/apps/agent-forge/server/buildAgentV2.ts
+++ b/apps/agent-forge/server/buildAgentV2.ts
@@ -46,8 +46,8 @@ import {
   type SpecHost,
   type ToolDescriptor,
   type TraceExporter,
-} from 'lousho';
-import type { AgentFlow } from 'lousho/flows';
+} from '@linuxdevil/lousho';
+import type { AgentFlow } from '@linuxdevil/lousho/flows';
 import { studioAutoApprover } from './autoApproval';
 import { asAgentFlow, LOCAL_TOOLS, resolveProviderForModel } from './buildAgent';
 import type { FileApprovalStore } from './approvalStore';
diff --git a/apps/agent-forge/server/chatReconcile.ts b/apps/agent-forge/server/chatReconcile.ts
index e8f90ac3b..5b3fdd2ba 100644
--- a/apps/agent-forge/server/chatReconcile.ts
+++ b/apps/agent-forge/server/chatReconcile.ts
@@ -24,7 +24,7 @@
  * fresh ones for genuinely new messages.
  */
 import { randomUUID } from 'node:crypto';
-import { textOf, type Message } from 'lousho';
+import { textOf, type Message } from '@linuxdevil/lousho';
 import type { ChatMessage, SteerInfo } from '../shared/wireTypes';
 
 /** The transcript keeps text only (content parts are flattened with `textOf()`). */
diff --git a/apps/agent-forge/server/chatTriggerAdapter.ts b/apps/agent-forge/server/chatTriggerAdapter.ts
index c5a9cc368..22d055f38 100644
--- a/apps/agent-forge/server/chatTriggerAdapter.ts
+++ b/apps/agent-forge/server/chatTriggerAdapter.ts
@@ -4,7 +4,7 @@
  * Wraps Agent Forge's existing chat transport - `RunManager.sendMessage()`
  * (see runRegistry.ts's doc comment on that method for the full
  * continuation semantics) - behind the SDK's `TriggerAdapter` shape
- * (`lousho/triggers`), so `POST /agents/:id/message`
+ * (`@linuxdevil/lousho/triggers`), so `POST /agents/:id/message`
  * (app.ts) is registered as `'chat'` in a `TriggerRegistry` alongside the
  * webhook/cron/Slack built-ins, instead of being a bespoke, unregistered
  * code path - closing the last of the four ad hoc "ways an agent can be
@@ -40,8 +40,8 @@
  * if ever actually called, rather than silently no-op-ing; `trigger()` is
  * the real, per-request entrypoint `app.ts` uses.
  */
-import type { AgentSpecV2, ExecutionResult } from 'lousho';
-import type { RunnableAgent, TriggerAdapter, TriggerContext, TriggerHandle } from 'lousho/triggers';
+import type { AgentSpecV2, ExecutionResult } from '@linuxdevil/lousho';
+import type { RunnableAgent, TriggerAdapter, TriggerContext, TriggerHandle } from '@linuxdevil/lousho/triggers';
 import type { RunManager } from './runRegistry';
 
 export class ChatTriggerAdapter implements TriggerAdapter {
diff --git a/apps/agent-forge/server/checkpointStore.ts b/apps/agent-forge/server/checkpointStore.ts
index ed90e2e76..6f17ed377 100644
--- a/apps/agent-forge/server/checkpointStore.ts
+++ b/apps/agent-forge/server/checkpointStore.ts
@@ -35,7 +35,7 @@ import {
   type CheckpointHistoryEntry,
   type CheckpointHistoryOptions,
   type CheckpointStore,
-} from 'lousho';
+} from '@linuxdevil/lousho';
 
 /** Write to a temp file and rename it over `file`, so a crash never leaves half a file there. */
 function writeFileAtomic(file: string, content: string): void {
diff --git a/apps/agent-forge/server/cli.ts b/apps/agent-forge/server/cli.ts
new file mode 100644
index 000000000..cc6d8ac80
--- /dev/null
+++ b/apps/agent-forge/server/cli.ts
@@ -0,0 +1,145 @@
+/**
+ * `lousho-studio` - the packaged Studio's own command.
+ *
+ * Bundled by `server/tsup.config.ts` to `dist-server/cli.cjs` (the package's
+ * `bin`), it parses its flags, starts the same `startStudioServer()` the
+ * `lousho studio` launcher spawns, prints the tokened URL and shuts down
+ * cleanly on SIGINT/SIGTERM.
+ *
+ *   Usage: lousho-studio [--workspace <dir>] [--port N] [--host H]
+ *
+ *   Options:
+ *     --workspace <dir>  a project folder to open (default: the current folder)
+ *     --port N           the port (default 4750)
+ *     --host H           the interface to listen on (default 127.0.0.1)
+ *     -v, --version      print the version
+ *     -h, --help         show this help
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { parseArgs } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { shutdownOnSignals, startStudioServer } from './index';
+
+export const USAGE = `Usage: lousho-studio [--workspace <dir>] [--port N] [--host H]
+
+Opens Lousho Studio. It prints a URL with a per-launch token; every API and WebSocket request needs that token.
+
+Options:
+  --workspace <dir>  a project folder to open (default: the current folder); it is added to your workspaces
+  --port N           the port (default 4750)
+  --host H           the interface to listen on (default 127.0.0.1)
+  -v, --version      print the version
+  -h, --help         show this help`;
+
+export interface StudioCliArgs {
+  workspace?: string;
+  port?: number;
+  host?: string;
+  version?: boolean;
+  help?: boolean;
+}
+
+/** Thrown for a bad flag/value: the message is printed after `lousho-studio: ` with the usage. */
+export class StudioCliUsageError extends Error {}
+
+function parsePort(value: string | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new StudioCliUsageError('--port must be an integer between 0 and 65535.');
+  }
+  return port;
+}
+
+/** Parses `lousho-studio` argv (without the node/script entries). Throws StudioCliUsageError on bad input. */
+export function parseStudioCliArgs(argv: string[]): StudioCliArgs {
+  let values: Record<string, string | boolean | (string | boolean)[] | undefined>;
+  try {
+    ({ values } = parseArgs({
+      args: argv,
+      strict: true,
+      allowPositionals: false,
+      options: {
+        workspace: { type: 'string' },
+        port: { type: 'string' },
+        host: { type: 'string' },
+        version: { type: 'boolean', short: 'v' },
+        help: { type: 'boolean', short: 'h' },
+      },
+    }));
+  } catch (error) {
+    throw new StudioCliUsageError((error as Error).message);
+  }
+  const workspace = values.workspace as string | undefined;
+  const host = values.host as string | undefined;
+  const port = parsePort(values.port as string | undefined);
+  return {
+    ...(workspace !== undefined ? { workspace } : {}),
+    ...(port !== undefined ? { port } : {}),
+    ...(host !== undefined ? { host } : {}),
+    ...(values.version === true ? { version: true } : {}),
+    ...(values.help === true ? { help: true } : {}),
+  };
+}
+
+/** The installed package's version: `../package.json` from both `server/` (tsx) and `dist-server/` (the bundle). */
+export function studioVersion(moduleDir: string): string {
+  const pkg = JSON.parse(fs.readFileSync(path.join(moduleDir, '..', 'package.json'), 'utf8')) as { version?: string };
+  return pkg.version ?? '0.0.0';
+}
+
+async function main(): Promise<void> {
+  let args: StudioCliArgs;
+  try {
+    args = parseStudioCliArgs(process.argv.slice(2));
+  } catch (error) {
+    console.error(`lousho-studio: ${(error as Error).message}`);
+    console.error(USAGE);
+    process.exit(2);
+  }
+  const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+  if (args.help) {
+    console.log(USAGE);
+    return;
+  }
+  if (args.version) {
+    console.log(studioVersion(moduleDir));
+    return;
+  }
+  let workspaceDir = process.cwd();
+  if (args.workspace !== undefined) {
+    workspaceDir = path.resolve(args.workspace);
+    if (!fs.existsSync(workspaceDir) || !fs.statSync(workspaceDir).isDirectory()) {
+      console.error(`lousho-studio: --workspace '${args.workspace}' is not a folder.`);
+      process.exit(2);
+    }
+  }
+  const port = args.port ?? 4750;
+  const host = args.host ?? '127.0.0.1';
+  let handle;
+  try {
+    handle = await startStudioServer({ port, host, baseDir: workspaceDir });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/already in use/.test(message)) {
+      console.error(`lousho-studio: port ${port} is in use. Is Studio already running? Start this one with --port ${port + 1}.`);
+    } else {
+      console.error(`lousho-studio: ${message}`);
+    }
+    process.exit(1);
+  }
+  console.log(`Lousho Studio ${studioVersion(moduleDir)}: ${handle.url}`);
+  console.log(`Workspace: ${workspaceDir}`);
+  shutdownOnSignals(handle);
+}
+
+// npm's bin is a symlink to this file on POSIX: argv[1] keeps the `.bin`
+// path while import.meta.url is the real file, so compare realpaths.
+const invokedAs = process.argv[1];
+const isMainModule =
+  invokedAs !== undefined && fs.realpathSync(invokedAs) === fs.realpathSync(fileURLToPath(import.meta.url));
+
+if (isMainModule) {
+  void main();
+}
diff --git a/apps/agent-forge/server/collector.ts b/apps/agent-forge/server/collector.ts
index 400f3acb4..30b625d44 100644
--- a/apps/agent-forge/server/collector.ts
+++ b/apps/agent-forge/server/collector.ts
@@ -23,8 +23,8 @@ import {
   type HealthProbe,
   type ObserveDaemon,
   type ObserveDaemonOptions,
-} from 'lousho/observe';
-import { VERSION } from 'lousho';
+} from '@linuxdevil/lousho/observe';
+import { VERSION } from '@linuxdevil/lousho';
 import type { CollectorStatus, CollectorUpdate } from '../shared/wireTypes';
 import type { SecretsStore } from './secretsStore';
 import type { SettingsStore } from './settingsStore';
diff --git a/apps/agent-forge/server/compileHooks.test.ts b/apps/agent-forge/server/compileHooks.test.ts
index fbe922e0d..73566e6eb 100644
--- a/apps/agent-forge/server/compileHooks.test.ts
+++ b/apps/agent-forge/server/compileHooks.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest';
-import { AgentExecutor, ToolRegistry, AgentBuilder } from 'lousho/executor';
-import { NoopSandbox, createMockProvider } from 'lousho';
+import { AgentExecutor, ToolRegistry, AgentBuilder } from '@linuxdevil/lousho/executor';
+import { NoopSandbox, createMockProvider } from '@linuxdevil/lousho';
 import { compileHooksFromSpecPolicy, isSerializedHookList, type SerializedHook } from './compileHooks';
 
 describe('isSerializedHookList', () => {
diff --git a/apps/agent-forge/server/compileHooks.ts b/apps/agent-forge/server/compileHooks.ts
index 1a2c73478..4fba1295d 100644
--- a/apps/agent-forge/server/compileHooks.ts
+++ b/apps/agent-forge/server/compileHooks.ts
@@ -8,8 +8,8 @@
  * `sandboxRunHook()` (hookSandbox.ts) rather than running the user's code
  * in this server process - see that file's doc comment for why.
  */
-import { HookRegistry, type AgentHook } from 'lousho';
-import type { SandboxAdapter, GenerateOptions, Message } from 'lousho';
+import { HookRegistry, type AgentHook } from '@linuxdevil/lousho';
+import type { SandboxAdapter, GenerateOptions, Message } from '@linuxdevil/lousho';
 import { sandboxRunHook } from './hookSandbox';
 
 /** Shape graphToSpec.ts serializes each hook as, under `spec.policy.hooks`. */
diff --git a/apps/agent-forge/server/debugController.ts b/apps/agent-forge/server/debugController.ts
index 280e8122c..98395bc16 100644
--- a/apps/agent-forge/server/debugController.ts
+++ b/apps/agent-forge/server/debugController.ts
@@ -29,7 +29,7 @@
  * only supported on `llm` and `tool` nodes, matching this app's graph model
  * (graph/types.ts) - see the epic report for the full breakdown.
  */
-import type { AgentHook, Message } from 'lousho';
+import type { AgentHook, Message } from '@linuxdevil/lousho';
 
 export type DebugBoundary = 'before' | 'after';
 
diff --git a/apps/agent-forge/server/deployRunner.ts b/apps/agent-forge/server/deployRunner.ts
index a1652039f..e944e424b 100644
--- a/apps/agent-forge/server/deployRunner.ts
+++ b/apps/agent-forge/server/deployRunner.ts
@@ -13,7 +13,7 @@
 import { spawn } from 'node:child_process';
 import * as path from 'node:path';
 import { stringify as stringifyYaml } from 'yaml';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { DeployResult } from '../shared/wireTypes';
 import { writeFileAtomic } from './storage/atomic';
 import { toLegacySpec } from './storage/legacySpec';
diff --git a/apps/agent-forge/server/diff/__tests__/specChange.test.ts b/apps/agent-forge/server/diff/__tests__/specChange.test.ts
index 749692f6c..736906506 100644
--- a/apps/agent-forge/server/diff/__tests__/specChange.test.ts
+++ b/apps/agent-forge/server/diff/__tests__/specChange.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { diffSpecs } from '../specChange';
 import type { SpecSnapshot } from '../../../shared/wireTypes';
 
diff --git a/apps/agent-forge/server/ejectRoute.ts b/apps/agent-forge/server/ejectRoute.ts
new file mode 100644
index 000000000..c27ee98a7
--- /dev/null
+++ b/apps/agent-forge/server/ejectRoute.ts
@@ -0,0 +1,114 @@
+/**
+ * Eject route (A08b): `POST /agents/:id/eject` writes the agent's
+ * agent-directory form (`specToAgentDir`) to `agents/<id>/` under the
+ * request's workspace root - the Code tab's exit from the read-only canvas
+ * to hand-written code (PLAN §16 decision 1).
+ *
+ * The workspace seam applies: `workspaceOf(req)` names the root, so a
+ * `?ws=` request ejects into its own folder. Writes go through
+ * `writeFileAtomic` inside `withAgentLock(id)` like every other spec write.
+ * Generated paths are re-validated before touching disk: anything absolute
+ * or containing `..` is a 400, and the resolved target must stay inside the
+ * eject directory (checked with `path.relative`, not string prefixes).
+ */
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+import type { Express, Request, Response } from 'express';
+import { specToAgentDir } from '@linuxdevil/lousho/spec';
+import type { EjectResult } from '../shared/wireTypes';
+import { asyncRoute, sendError } from './http/routeUtils';
+import { withAgentLock, writeFileAtomic } from './storage/atomic';
+import { readSpecOr404 } from './workspace/specLookup';
+
+/** The eject body: `{ overwrite?: boolean }`, default false; anything else reads as false. */
+function wantsOverwrite(body: unknown): boolean {
+  return typeof body === 'object' && body !== null && (body as { overwrite?: unknown }).overwrite === true;
+}
+
+/**
+ * Whether a generated path could escape the eject directory: absolute
+ * (POSIX or Windows), a `..` segment, or a NUL byte. `specToAgentDir`
+ * never emits these today; the check is the contract's safety rail.
+ */
+function isUnsafeRelPath(rel: string): boolean {
+  return (
+    rel === '' ||
+    rel.includes(String.fromCharCode(0)) ||
+    path.isAbsolute(rel) ||
+    /^[a-zA-Z]:[\\/]/.test(rel) ||
+    rel.split(/[\\/]/).some((seg) => seg === '..')
+  );
+}
+
+/** Every file under `dir`, paths relative to it with '/' separators; [] when `dir` is absent. */
+async function listFiles(dir: string): Promise<string[]> {
+  if (!existsSync(dir)) return [];
+  const out: string[] = [];
+  const walk = async (cur: string, prefix: string): Promise<void> => {
+    for (const entry of await readdir(cur, { withFileTypes: true })) {
+      const abs = path.join(cur, entry.name);
+      const rel = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
+      if (entry.isDirectory()) await walk(abs, rel);
+      else if (entry.isFile()) out.push(rel);
+    }
+  };
+  await walk(dir, '');
+  return out.sort();
+}
+
+/** The `{ overwrite }` parse plus the spec read; undefined means a response was already sent. */
+async function loadEjectInput(req: Request, res: Response) {
+  const input = await readSpecOr404(req, res, (id) => `Agent ${id} not found.`);
+  if (input === undefined) return undefined;
+  const { ws, id, spec } = input;
+  let generated;
+  try {
+    generated = specToAgentDir(spec);
+  } catch (error) {
+    sendError(res, 400, error instanceof Error ? error.message : String(error), 'LOUSHO_EJECT_INVALID');
+    return undefined;
+  }
+  if (generated.files.some((f) => isUnsafeRelPath(f.path))) {
+    sendError(res, 400, 'The agent directory generated a path outside the target folder.', 'LOUSHO_EJECT_INVALID');
+    return undefined;
+  }
+  return { ws, id, files: generated.files };
+}
+
+export function registerEjectRoutes(app: Express): void {
+  app.post(
+    '/agents/:id/eject',
+    asyncRoute(async (req: Request, res: Response) => {
+      const input = await loadEjectInput(req, res);
+      if (input === undefined) return;
+      const { ws, id, files } = input;
+      const dirRel = `agents/${id}`;
+      const dirAbs = path.join(ws.ref.root, 'agents', id);
+      const overwrite = wantsOverwrite(req.body);
+
+      const existing = await listFiles(dirAbs);
+      if (existing.length > 0 && !overwrite) {
+        sendError(res, 409, `${dirRel}/ already exists.`, 'LOUSHO_EJECT_EXISTS', { files: existing });
+        return;
+      }
+
+      const dirResolved = path.resolve(dirAbs);
+      await withAgentLock(id, async () => {
+        for (const file of files) {
+          const target = path.resolve(dirResolved, file.path);
+          // Belt to the generation check's braces: a resolved target must
+          // stay inside the eject directory.
+          const rel = path.relative(dirResolved, target);
+          if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+            throw new Error(`Refusing to write outside ${dirRel}: ${file.path}`);
+          }
+          await writeFileAtomic(target, file.content);
+        }
+      });
+
+      const result: EjectResult = { dir: dirRel, files: files.map((f) => f.path) };
+      res.json(result);
+    })
+  );
+}
diff --git a/apps/agent-forge/server/evals/candidateRun.ts b/apps/agent-forge/server/evals/candidateRun.ts
index 62908a204..2b8574d94 100644
--- a/apps/agent-forge/server/evals/candidateRun.ts
+++ b/apps/agent-forge/server/evals/candidateRun.ts
@@ -14,8 +14,8 @@
  *   tools pause for approval leaves the pending record where the agent's
  *   own approvals UI never lists it.
  */
-import type { AgentSpecV2, TraceExporter } from 'lousho';
-import type { Span } from 'lousho/traces';
+import type { AgentSpecV2, TraceExporter } from '@linuxdevil/lousho';
+import type { Span } from '@linuxdevil/lousho/traces';
 import { buildRunnableAgent, type StudioRunDeps } from '../buildAgentV2';
 import { FileApprovalStore } from '../approvalStore';
 import { FileCheckpointStore } from '../checkpointStore';
diff --git a/apps/agent-forge/server/evals/gateRunner.ts b/apps/agent-forge/server/evals/gateRunner.ts
index 127d8afbe..26484a5f9 100644
--- a/apps/agent-forge/server/evals/gateRunner.ts
+++ b/apps/agent-forge/server/evals/gateRunner.ts
@@ -18,7 +18,7 @@
  *   answer fails the example - a gate that could not be checked never
  *   passes.
  */
-import type { AgentSpecV2, EvalGate, EvalGateSpec } from 'lousho/spec';
+import type { AgentSpecV2, EvalGate, EvalGateSpec } from '@linuxdevil/lousho/spec';
 import type { EvalExampleResult, EvalGateResult, EvalGateSetResult } from '../../shared/wireTypes';
 import type { PassRunner } from '../passes/passRunner';
 import type { SecretsStore } from '../secretsStore';
diff --git a/apps/agent-forge/server/evals/judgeGate.ts b/apps/agent-forge/server/evals/judgeGate.ts
index 8081fe47b..0e1b8e23b 100644
--- a/apps/agent-forge/server/evals/judgeGate.ts
+++ b/apps/agent-forge/server/evals/judgeGate.ts
@@ -12,7 +12,7 @@
  */
 import { createHash } from 'node:crypto';
 import { z } from 'zod';
-import type { EvalGateSpec } from 'lousho/spec';
+import type { EvalGateSpec } from '@linuxdevil/lousho/spec';
 import { callPassModel } from '../passes/passModel';
 import type { PassRunner } from '../passes/passRunner';
 import type { SecretsStore } from '../secretsStore';
diff --git a/apps/agent-forge/server/hookSandbox.test.ts b/apps/agent-forge/server/hookSandbox.test.ts
index 03ead7a37..5c77136cc 100644
--- a/apps/agent-forge/server/hookSandbox.test.ts
+++ b/apps/agent-forge/server/hookSandbox.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { NoopSandbox } from 'lousho';
+import { NoopSandbox } from '@linuxdevil/lousho';
 import { sandboxRunHook } from './hookSandbox';
 
 describe('sandboxRunHook', () => {
diff --git a/apps/agent-forge/server/hookSandbox.ts b/apps/agent-forge/server/hookSandbox.ts
index ea04e2069..9876a3f89 100644
--- a/apps/agent-forge/server/hookSandbox.ts
+++ b/apps/agent-forge/server/hookSandbox.ts
@@ -24,7 +24,7 @@
  * chance to mediate it exactly like it would for a sandboxed tool.
  */
 
-import type { SandboxAdapter } from 'lousho';
+import type { SandboxAdapter } from '@linuxdevil/lousho';
 
 /** Generic ctx payload shape a hook script receives/returns (HookContext family, minus non-serializable fields like `messages`/`toolCall`). */
 export type HookSandboxCtx = Record<string, unknown>;
diff --git a/apps/agent-forge/server/host/agentHost.ts b/apps/agent-forge/server/host/agentHost.ts
index d0bb14869..c41b1532d 100644
--- a/apps/agent-forge/server/host/agentHost.ts
+++ b/apps/agent-forge/server/host/agentHost.ts
@@ -24,7 +24,7 @@ import type {
   ExecutionResult,
   PendingApproval,
   Span,
-} from 'lousho';
+} from '@linuxdevil/lousho';
 import type { CatalogGuardrail, CatalogModel, CatalogTool, CatalogTriggerType } from '../../shared/wireTypes';
 
 export interface AgentHost {
diff --git a/apps/agent-forge/server/host/bridgeAgentHost.ts b/apps/agent-forge/server/host/bridgeAgentHost.ts
index 6785b32b4..a67ff3bd5 100644
--- a/apps/agent-forge/server/host/bridgeAgentHost.ts
+++ b/apps/agent-forge/server/host/bridgeAgentHost.ts
@@ -12,7 +12,7 @@
  * `HostReadOnlyError` except `catalog` (the in-process fallback) and
  * `dispose`.
  */
-import type { Message } from 'lousho';
+import type { Message } from '@linuxdevil/lousho';
 import { BridgeError, type BridgeClient } from './bridgeClient';
 import { providerEnv, secretsFor, toHostEvent } from './bridgeMapping';
 import type { WorkspaceSdk } from './workspaceSdk';
diff --git a/apps/agent-forge/server/host/bridgeClient.ts b/apps/agent-forge/server/host/bridgeClient.ts
index d0d4e9f54..4de44415a 100644
--- a/apps/agent-forge/server/host/bridgeClient.ts
+++ b/apps/agent-forge/server/host/bridgeClient.ts
@@ -24,7 +24,7 @@ import {
   type BridgeParams,
   type BridgePush,
   type BridgeResults,
-} from 'lousho';
+} from '@linuxdevil/lousho';
 
 /** Lifecycle of the bridge child this client owns. */
 export type BridgeState = 'idle' | 'starting' | 'ready' | 'restarting' | 'failed' | 'unsupported' | 'stopped';
diff --git a/apps/agent-forge/server/host/bridgeMapping.ts b/apps/agent-forge/server/host/bridgeMapping.ts
index c1cb777b5..c36b71987 100644
--- a/apps/agent-forge/server/host/bridgeMapping.ts
+++ b/apps/agent-forge/server/host/bridgeMapping.ts
@@ -9,7 +9,7 @@
  * resolves them by name in the project, so Studio ships exactly the
  * names the spec mentions, nothing more.
  */
-import type { AgentSpecV2, BridgePush, BridgePushData } from 'lousho';
+import type { AgentSpecV2, BridgePush, BridgePushData } from '@linuxdevil/lousho';
 import type { HostEvent, HostRunResult } from './agentHost';
 import type { SecretsStore } from '../secretsStore';
 
diff --git a/apps/agent-forge/server/host/hostSelector.ts b/apps/agent-forge/server/host/hostSelector.ts
index 27340fbf5..1828ad787 100644
--- a/apps/agent-forge/server/host/hostSelector.ts
+++ b/apps/agent-forge/server/host/hostSelector.ts
@@ -15,7 +15,7 @@
  * token and listener vars are stripped so project code never sees them.
  */
 import type { WorkspaceRef } from '../../shared/workspace';
-import { BRIDGE_PROTOCOL_VERSION } from 'lousho';
+import { BRIDGE_PROTOCOL_VERSION } from '@linuxdevil/lousho';
 import { observeTarget } from '../observeProxy';
 import type { HostBanner, HostMode } from '../../shared/wireTypes';
 import { BridgeClient, BridgeError, type BridgeClientOptions, type BridgeState } from './bridgeClient';
@@ -34,6 +34,10 @@ export interface HostSelection {
   /** The SDK version runs execute under, or null before it is known. */
   sdkVersion: string | null;
   banner: HostBanner | null;
+  /** The bridge protocol the SDK answered with (rows 4-7 only). */
+  protocol?: number;
+  /** The spec versions the SDK's bridge accepts (rows 4-7 only). */
+  specVersions?: readonly number[];
 }
 
 /** Everything the selector needs that the workspace context cannot build synchronously. */
@@ -55,7 +59,7 @@ export interface SelectHostDeps {
 
 const INFO_NO_SDK = (v: string): HostBanner => ({
   tone: 'info',
-  text: `This project has no @lousho/build-ai-agent installed. Runs use Studio's built-in SDK ${v}.`,
+  text: `This project has no @linuxdevil/lousho installed. Runs use Studio's built-in SDK ${v}.`,
 });
 const INFO_UNBUILT = (v: string): HostBanner => ({
   tone: 'info',
@@ -63,11 +67,11 @@ const INFO_UNBUILT = (v: string): HostBanner => ({
 });
 const WARNING_OLD_SDK = (): HostBanner => ({
   tone: 'warning',
-  text: `Update @lousho/build-ai-agent in this project to ${MIN_BRIDGE_SDK_VERSION} or later to edit agents here.`,
+  text: `Update @linuxdevil/lousho in this project to ${MIN_BRIDGE_SDK_VERSION} or later to edit agents here.`,
 });
 const WARNING_NEWER_SDK = (v: string): HostBanner => ({
   tone: 'warning',
-  text: `This project's @lousho/build-ai-agent ${v} is newer than this Studio understands. Update Studio to edit agents here.`,
+  text: `This project's @linuxdevil/lousho ${v} is newer than this Studio understands. Update Studio to edit agents here.`,
 });
 const DANGER_CRASHED = (): HostBanner => ({
   tone: 'danger',
@@ -198,14 +202,14 @@ export class WorkspaceHostSelector {
       // The handshake's version is the SDK that answered - record it over the disk read.
       if (!hello.specVersions.includes(2)) {
         await client.stop();
-        return this.settle({ mode: 'read-only', banner: WARNING_OLD_SDK(), sdkVersion: hello.sdkVersion });
+        return this.settle({ mode: 'read-only', banner: WARNING_OLD_SDK(), sdkVersion: hello.sdkVersion, protocol: hello.protocol, specVersions: hello.specVersions });
       }
       if (hello.protocol !== BRIDGE_PROTOCOL_VERSION) {
         await client.stop();
-        return this.settle({ mode: 'read-only', banner: WARNING_NEWER_SDK(hello.sdkVersion), sdkVersion: hello.sdkVersion });
+        return this.settle({ mode: 'read-only', banner: WARNING_NEWER_SDK(hello.sdkVersion), sdkVersion: hello.sdkVersion, protocol: hello.protocol, specVersions: hello.specVersions });
       }
       // Row 6.
-      return this.settle({ mode: 'bridge', banner: null, sdkVersion: hello.sdkVersion });
+      return this.settle({ mode: 'bridge', banner: null, sdkVersion: hello.sdkVersion, protocol: hello.protocol, specVersions: hello.specVersions });
     } catch (error) {
       if (error instanceof BridgeError && error.code === 'LOUSHO_BRIDGE_UNSUPPORTED') {
         // Row 3: no hello ever answered - the SDK version is unknown.
@@ -227,20 +231,24 @@ export class WorkspaceHostSelector {
     }
   }
 
-  private settle(patch: { mode: HostMode; banner: HostBanner | null; sdkVersion?: string | null }): HostSelection {
+  private settle(patch: { mode: HostMode; banner: HostBanner | null; sdkVersion?: string | null; protocol?: number; specVersions?: readonly number[] }): HostSelection {
     const next: HostSelection = {
       mode: patch.mode,
       sdk: this.sdk,
       sdkVersion: patch.sdkVersion !== undefined ? patch.sdkVersion : this.selection.sdkVersion,
       banner: patch.banner,
+      protocol: patch.protocol ?? this.selection.protocol,
+      specVersions: patch.specVersions ?? this.selection.specVersions,
     };
     const before = this.selection;
     const unchanged =
       before.mode === next.mode &&
       before.sdkVersion === next.sdkVersion &&
+      before.protocol === next.protocol &&
       before.banner?.tone === next.banner?.tone &&
       before.banner?.text === next.banner?.text &&
-      before.banner?.action === next.banner?.action;
+      before.banner?.action === next.banner?.action &&
+      (before.specVersions === undefined || next.specVersions === undefined || before.specVersions.join() === next.specVersions.join());
     if (unchanged) return before;
     this.selection = next;
     for (const listener of this.listeners) listener(this.selection);
diff --git a/apps/agent-forge/server/host/inProcessAgentHost.ts b/apps/agent-forge/server/host/inProcessAgentHost.ts
index ce0cc7252..77fb01482 100644
--- a/apps/agent-forge/server/host/inProcessAgentHost.ts
+++ b/apps/agent-forge/server/host/inProcessAgentHost.ts
@@ -24,7 +24,7 @@ import {
   VERSION,
   type AgentRun,
   type ExecutionResult,
-} from 'lousho';
+} from '@linuxdevil/lousho';
 import { buildRunnableAgent, type RunWiring, type StudioRunDeps } from '../buildAgentV2';
 import {
   HostRunNotActiveError,
diff --git a/apps/agent-forge/server/host/sdkCompat.ts b/apps/agent-forge/server/host/sdkCompat.ts
index 897a81c74..d06e867fe 100644
--- a/apps/agent-forge/server/host/sdkCompat.ts
+++ b/apps/agent-forge/server/host/sdkCompat.ts
@@ -1,10 +1,10 @@
-/**
- * sdkCompat: the minimum `@lousho/build-ai-agent` version whose `lousho
- * bridge` speaks protocol 1 (W10a/W10b). Studio and the SDK ship from the
- * same repo, so the floor is this package's own version at the merge -
- * W15b's compatibility matrix is the consumer that revisits it.
- */
-import { VERSION } from 'lousho';
-
-/** First SDK version that ships `lousho bridge`. */
-export const MIN_BRIDGE_SDK_VERSION = VERSION;
+/**
+ * sdkCompat: the minimum `@linuxdevil/lousho` version whose `lousho
+ * bridge` speaks protocol 1 (W10a/W10b). Studio and the SDK ship from the
+ * same repo, so the floor is this package's own version at the merge -
+ * W15b's compatibility matrix is the consumer that revisits it.
+ */
+import { VERSION } from '@linuxdevil/lousho';
+
+/** First SDK version that ships `lousho bridge`. */
+export const MIN_BRIDGE_SDK_VERSION = VERSION;
diff --git a/apps/agent-forge/server/host/workspaceSdk.ts b/apps/agent-forge/server/host/workspaceSdk.ts
index 5f0fd64a1..62b4da9b7 100644
--- a/apps/agent-forge/server/host/workspaceSdk.ts
+++ b/apps/agent-forge/server/host/workspaceSdk.ts
@@ -1,100 +1,101 @@
-/**
- * workspaceSdk: finds the SDK install a workspace's runs should execute
- * under (PLAN §19.4 "Selection per workspace").
- *
- * The lookup is Node's own algorithm done by hand: the SDK's `exports`
- * map does not expose `./package.json`, so `require.resolve(
- * '@lousho/build-ai-agent/package.json')` throws ERR_PACKAGE_PATH_NOT_EXPORTED
- * on every supported version. Walking `node_modules` upwards from the
- * workspace root (nearest hit wins) matches what `import` would resolve.
- *
- * Two package names are accepted: `@lousho/build-ai-agent`, the scoped
- * name the packaging waves (W13a/W13b) move to, and `lousho`, the name
- * the package ships under today - a project on either gets its own SDK
- * bridged. A workspace that IS an SDK checkout (`source: 'self'`) uses
- * its own `bin/lousho.js`; `built` tells the selector whether `dist/`
- * exists - an unbuilt checkout falls back to Studio's in-process host.
- */
-import { existsSync, readFileSync, realpathSync } from 'node:fs';
-import { join, parse } from 'node:path';
-
-/** Package names the SDK answers to: the scoped future name, then today's `lousho`. */
-const SDK_PACKAGE_NAMES = ['@lousho/build-ai-agent', 'lousho'] as const;
-
-/** The project's own SDK install, as the bridge spawns it. */
-export interface WorkspaceSdk {
-  /** The SDK's `package.json` `version`. */
-  version: string;
-  /** Real path of the SDK package folder. */
-  packageDir: string;
-  /** `<packageDir>/bin/lousho.js` - spawned as `node <binPath> bridge`. */
-  binPath: string;
-  /** `'self'` when the workspace root IS the SDK checkout, else `'node_modules'`. */
-  source: 'node_modules' | 'self';
-  /** `<packageDir>/dist/cli/bridge.mjs` exists - the checkout has been built. */
-  built: boolean;
-}
-
-interface SdkPackageJson {
-  name?: string;
-  version?: string;
-}
-
-function readPackageJson(dir: string): SdkPackageJson | undefined {
-  try {
-    return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as SdkPackageJson;
-  } catch {
-    return undefined;
-  }
-}
-
-function isSdkPackageJson(pkg: SdkPackageJson | undefined): boolean {
-  return pkg !== undefined && (SDK_PACKAGE_NAMES as readonly string[]).includes(pkg.name ?? '');
-}
-
-function sdkAt(packageDir: string, source: WorkspaceSdk['source']): WorkspaceSdk | undefined {
-  const binPath = join(packageDir, 'bin', 'lousho.js');
-  if (!existsSync(binPath)) return undefined;
-  const version = readPackageJson(packageDir)?.version;
-  if (version === undefined) return undefined;
-  return {
-    version,
-    packageDir,
-    binPath,
-    source,
-    built: existsSync(join(packageDir, 'dist', 'cli', 'bridge.mjs')),
-  };
-}
-
-/**
- * Finds the SDK a workspace runs under, or `undefined` when it has none
- * (or the install lacks `bin/lousho.js`). Nearest `node_modules` hit
- * wins; the workspace's own checkout wins over any install.
- */
-export function findWorkspaceSdk(root: string): WorkspaceSdk | undefined {
-  let real: string;
-  try {
-    real = realpathSync(root);
-  } catch {
-    return undefined;
-  }
-  if (isSdkPackageJson(readPackageJson(real))) {
-    return sdkAt(real, 'self');
-  }
-  for (let dir = real, prev = ''; dir !== prev; prev = dir, dir = parse(dir).dir) {
-    for (const name of SDK_PACKAGE_NAMES) {
-      const pkgDir = join(dir, 'node_modules', ...name.split('/'));
-      // The directory name alone is not proof: verify the manifest's own
-      // `name` (a junction to the SDK checkout carries `lousho` today,
-      // `@lousho/build-ai-agent` after the packaging rename).
-      if (!isSdkPackageJson(readPackageJson(pkgDir))) continue;
-      try {
-        const sdk = sdkAt(realpathSync(pkgDir), 'node_modules');
-        if (sdk !== undefined) return sdk;
-      } catch {
-        // An unreadable symlinked install is not an SDK.
-      }
-    }
-  }
-  return undefined;
-}
+/**
+ * workspaceSdk: finds the SDK install a workspace's runs should execute
+ * under (PLAN §19.4 "Selection per workspace").
+ *
+ * The lookup is Node's own algorithm done by hand: the SDK's `exports`
+ * map does not expose `./package.json`, so `require.resolve(
+ * '@linuxdevil/lousho/package.json')` throws ERR_PACKAGE_PATH_NOT_EXPORTED
+ * on every supported version. Walking `node_modules` upwards from the
+ * workspace root (nearest hit wins) matches what `import` would resolve.
+ *
+ * Two package names are accepted: `@linuxdevil/lousho`, the scoped
+ * name the package ships under, and `lousho`, the pre-rename name kept
+ * for projects that still depend on it.
+ * the package ships under today - a project on either gets its own SDK
+ * bridged. A workspace that IS an SDK checkout (`source: 'self'`) uses
+ * its own `bin/lousho.js`; `built` tells the selector whether `dist/`
+ * exists - an unbuilt checkout falls back to Studio's in-process host.
+ */
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { join, parse } from 'node:path';
+
+/** Package names the SDK answers to: the scoped name, then the legacy `lousho`. */
+const SDK_PACKAGE_NAMES = ['@linuxdevil/lousho', 'lousho'] as const;
+
+/** The project's own SDK install, as the bridge spawns it. */
+export interface WorkspaceSdk {
+  /** The SDK's `package.json` `version`. */
+  version: string;
+  /** Real path of the SDK package folder. */
+  packageDir: string;
+  /** `<packageDir>/bin/lousho.js` - spawned as `node <binPath> bridge`. */
+  binPath: string;
+  /** `'self'` when the workspace root IS the SDK checkout, else `'node_modules'`. */
+  source: 'node_modules' | 'self';
+  /** `<packageDir>/dist/cli/bridge.mjs` exists - the checkout has been built. */
+  built: boolean;
+}
+
+interface SdkPackageJson {
+  name?: string;
+  version?: string;
+}
+
+function readPackageJson(dir: string): SdkPackageJson | undefined {
+  try {
+    return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as SdkPackageJson;
+  } catch {
+    return undefined;
+  }
+}
+
+function isSdkPackageJson(pkg: SdkPackageJson | undefined): boolean {
+  return pkg !== undefined && (SDK_PACKAGE_NAMES as readonly string[]).includes(pkg.name ?? '');
+}
+
+function sdkAt(packageDir: string, source: WorkspaceSdk['source']): WorkspaceSdk | undefined {
+  const binPath = join(packageDir, 'bin', 'lousho.js');
+  if (!existsSync(binPath)) return undefined;
+  const version = readPackageJson(packageDir)?.version;
+  if (version === undefined) return undefined;
+  return {
+    version,
+    packageDir,
+    binPath,
+    source,
+    built: existsSync(join(packageDir, 'dist', 'cli', 'bridge.mjs')),
+  };
+}
+
+/**
+ * Finds the SDK a workspace runs under, or `undefined` when it has none
+ * (or the install lacks `bin/lousho.js`). Nearest `node_modules` hit
+ * wins; the workspace's own checkout wins over any install.
+ */
+export function findWorkspaceSdk(root: string): WorkspaceSdk | undefined {
+  let real: string;
+  try {
+    real = realpathSync(root);
+  } catch {
+    return undefined;
+  }
+  if (isSdkPackageJson(readPackageJson(real))) {
+    return sdkAt(real, 'self');
+  }
+  for (let dir = real, prev = ''; dir !== prev; prev = dir, dir = parse(dir).dir) {
+    for (const name of SDK_PACKAGE_NAMES) {
+      const pkgDir = join(dir, 'node_modules', ...name.split('/'));
+      // The directory name alone is not proof: verify the manifest's own
+      // `name` (a junction to the SDK checkout carries `@linuxdevil/lousho`
+      // or the legacy `lousho`).
+      if (!isSdkPackageJson(readPackageJson(pkgDir))) continue;
+      try {
+        const sdk = sdkAt(realpathSync(pkgDir), 'node_modules');
+        if (sdk !== undefined) return sdk;
+      } catch {
+        // An unreadable symlinked install is not an SDK.
+      }
+    }
+  }
+  return undefined;
+}
diff --git a/apps/agent-forge/server/inbox/__tests__/inboxAggregate.test.ts b/apps/agent-forge/server/inbox/__tests__/inboxAggregate.test.ts
index 89e0c128d..ea622809c 100644
--- a/apps/agent-forge/server/inbox/__tests__/inboxAggregate.test.ts
+++ b/apps/agent-forge/server/inbox/__tests__/inboxAggregate.test.ts
@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { listAllInbox, countAllInbox, type InboxAggregateDeps } from '../inboxAggregate';
 import { AlertStore } from '../alertStore';
 import { WorkspaceRegistry, type WorkspaceEntry } from '../../workspace/workspaceRegistry';
diff --git a/apps/agent-forge/server/index.ts b/apps/agent-forge/server/index.ts
index f17f8f733..93c93c4e7 100644
--- a/apps/agent-forge/server/index.ts
+++ b/apps/agent-forge/server/index.ts
@@ -6,6 +6,7 @@
  * for tests/embedding.
  */
 import { once } from 'node:events';
+import * as fs from 'node:fs';
 import * as http from 'node:http';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -38,7 +39,8 @@ import { ServeConfigStore } from './serve/serveConfigStore';
 import { buildServeAgent } from './serve/serveRoutes';
 import { McpServerManager } from './serve/mcpServers';
 import type { StudioEvent } from '../shared/wireTypes';
-import { VERSION } from 'lousho';
+import { VERSION } from '@linuxdevil/lousho';
+import { sdkRootDir } from './sdkRoot';
 
 export interface StudioServerHandle {
   server: http.Server;
@@ -149,14 +151,16 @@ function resolveStaticDir(staticDir: string | false | undefined, moduleDir: stri
 }
 
 /**
- * The bundled SDK docs folder `searchDocs` reads: three levels above this
- * file's dir lands on the package root (server/ and dist-server/ are both
- * at apps/agent-forge/<x>, same resolution as the default staticDir).
- * `docs/*.md` ships in the package's `files`; a missing folder makes
+ * The bundled docs folder `searchDocs` reads. In the monorepo three levels
+ * above this file's dir lands on the repo root's `docs/`; in the packaged
+ * layout that path does not exist, so fall back to the SDK package's own
+ * `docs/` (which ships in its `files`). A missing folder makes
  * `searchDocs` answer UNAVAILABLE rather than fail.
  */
 function resolveDocsDir(moduleDir: string): string {
-  return path.join(moduleDir, '..', '..', '..', 'docs');
+  const repoDocs = path.join(moduleDir, '..', '..', '..', 'docs');
+  if (fs.existsSync(repoDocs)) return repoDocs;
+  return path.join(sdkRootDir(moduleDir), 'docs');
 }
 
 /**
@@ -404,6 +408,15 @@ export async function startStudioServer(
   };
 }
 
+/** SIGINT/SIGTERM → `handle.close()` (collector, bridges, socket) then exit 0. Shared by both entry points. */
+export function shutdownOnSignals(handle: Pick<StudioServerHandle, 'close'>): void {
+  const shutdown = () => {
+    void handle.close().finally(() => process.exit(0));
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
 // Allow `tsx server/index.ts` (or `node --import tsx server/index.ts`) to
 // boot the server directly, reading PORT/HOST/BASE_DIR from the
 // environment - this is how `lousho studio` (src/cli/studio.ts) launches it
@@ -411,16 +424,20 @@ export async function startStudioServer(
 // so this module runs as real ESM under tsx - there is no CJS `require`/
 // `module` to compare against, hence the `import.meta.url` check instead of
 // the usual `require.main === module` idiom.
+// The basename check matters in the packaged bundle: `cli.cjs` inlines this
+// module too, and without it `lousho-studio --help` would boot a second
+// server on 4750 (argv[1] is cli.cjs there, not an index.* entry).
 const isMainModule =
-  process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+  process.argv[1] !== undefined &&
+  /^index\.(cjs|mjs|js|ts)$/.test(path.basename(process.argv[1])) &&
+  import.meta.url === pathToFileURL(process.argv[1]).href;
 
 if (isMainModule) {
   const port = process.env.PORT ? Number(process.env.PORT) : undefined;
   const host = process.env.HOST;
-  const moduleDir = path.dirname(fileURLToPath(import.meta.url));
-  // moduleDir is apps/agent-forge/server - the repo root (where `.lousho/`
-  // should live) is three levels up, unless BASE_DIR is set explicitly.
-  const baseDir = process.env.BASE_DIR ?? path.resolve(moduleDir, '..', '..', '..');
+  // The launch workspace defaults to the folder the command ran in, unless
+  // BASE_DIR is set explicitly.
+  const baseDir = process.env.BASE_DIR ?? process.cwd();
   // `src/cli/studio.ts` sets NO_STATIC=1 in dev mode (separate Vite dev
   // server process serves the UI there) and STATIC_DIR to override the
   // default `apps/agent-forge/dist` lookup in prod mode.
@@ -442,11 +459,7 @@ if (isMainModule) {
       }
       // `lousho studio` mints the token itself and prints this URL; only print it when launched directly.
       if (!process.env[STUDIO_TOKEN_ENV]) console.log(`[lousho studio] Agent Forge: ${handle.url}`);
-      const shutdown = () => {
-        void handle.close().finally(() => process.exit(0));
-      };
-      process.on('SIGINT', shutdown);
-      process.on('SIGTERM', shutdown);
+      shutdownOnSignals(handle);
     })
     .catch((error) => {
       console.error(error instanceof Error ? error.message : String(error));
diff --git a/apps/agent-forge/server/judge.ts b/apps/agent-forge/server/judge.ts
index f65cfb109..8080032dd 100644
--- a/apps/agent-forge/server/judge.ts
+++ b/apps/agent-forge/server/judge.ts
@@ -25,8 +25,8 @@
  *   daemon unchanged.
  */
 import type { Express, Request, Response } from 'express';
-import type { AgentSpec } from 'lousho';
-import { evaluatorTraceFrom, type EvaluatorTrace, type ObservationRow } from 'lousho/traces';
+import type { AgentSpec } from '@linuxdevil/lousho';
+import { evaluatorTraceFrom, type EvaluatorTrace, type ObservationRow } from '@linuxdevil/lousho/traces';
 import { buildAgentFromSpec } from './buildAgent';
 import { daemonHeaders, observeTarget } from './observeProxy';
 import { firstJsonObject } from './passes/jsonReply';
diff --git a/apps/agent-forge/server/lifecycle/__tests__/failureStreak.test.ts b/apps/agent-forge/server/lifecycle/__tests__/failureStreak.test.ts
index ec20f3b7d..069bab7a1 100644
--- a/apps/agent-forge/server/lifecycle/__tests__/failureStreak.test.ts
+++ b/apps/agent-forge/server/lifecycle/__tests__/failureStreak.test.ts
@@ -3,7 +3,7 @@ import { EventEmitter } from 'node:events';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { AgentRunStatusPayload, StudioEvent } from '../../../shared/wireTypes';
 import { AgentRepo } from '../../storage/agentRepo';
 import { StudioEventBus } from '../../events/eventBus';
diff --git a/apps/agent-forge/server/lifecycle/__tests__/publish.test.ts b/apps/agent-forge/server/lifecycle/__tests__/publish.test.ts
index 2dd8ea380..12e76514d 100644
--- a/apps/agent-forge/server/lifecycle/__tests__/publish.test.ts
+++ b/apps/agent-forge/server/lifecycle/__tests__/publish.test.ts
@@ -2,7 +2,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 type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { AgentMeta, StudioEvent, VersionListItem } from '../../../shared/wireTypes';
 import { StudioEventBus } from '../../events/eventBus';
 import { AgentRepo } from '../../storage/agentRepo';
diff --git a/apps/agent-forge/server/lifecycle/copy.ts b/apps/agent-forge/server/lifecycle/copy.ts
index e674117ac..5689fbd57 100644
--- a/apps/agent-forge/server/lifecycle/copy.ts
+++ b/apps/agent-forge/server/lifecycle/copy.ts
@@ -10,7 +10,7 @@
  * the new id has no sidecar dir until this write.
  */
 import { randomUUID } from 'node:crypto';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 
 import { isValidAgentId } from '../../shared/agentId';
 import type { AgentMeta, AgentRecord, CanvasLayout } from '../../shared/wireTypes';
diff --git a/apps/agent-forge/server/lifecycle/export.ts b/apps/agent-forge/server/lifecycle/export.ts
index 797d04489..10dfa299f 100644
--- a/apps/agent-forge/server/lifecycle/export.ts
+++ b/apps/agent-forge/server/lifecycle/export.ts
@@ -10,7 +10,7 @@
  */
 import type { Express, Request, Response } from 'express';
 import { stringify as stringifyYaml } from 'yaml';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { AgentBundle } from '../../shared/wireTypes';
 import { asyncRoute, paramId, sendError } from '../http/routeUtils';
 import { daemonHeaders, observeTarget } from '../observeProxy';
diff --git a/apps/agent-forge/server/lifecycle/import.ts b/apps/agent-forge/server/lifecycle/import.ts
index 55dcf4b09..2986c9429 100644
--- a/apps/agent-forge/server/lifecycle/import.ts
+++ b/apps/agent-forge/server/lifecycle/import.ts
@@ -20,7 +20,7 @@
  */
 import type { Express, Request, Response } from 'express';
 import { parse as parseYaml } from 'yaml';
-import { agentSpecV2Schema, upgradeSpec, type AgentSpecV2 } from 'lousho';
+import { agentSpecV2Schema, upgradeSpec, type AgentSpecV2 } from '@linuxdevil/lousho';
 import { isValidAgentId } from '../../shared/agentId';
 import { LabelError, normalizeLabels } from '../../shared/labels';
 import type { AgentBundle, AgentMeta, AgentRecord, ImportMode, ImportPreview, ImportRequest } from '../../shared/wireTypes';
diff --git a/apps/agent-forge/server/lifecycle/publish.ts b/apps/agent-forge/server/lifecycle/publish.ts
index 1bd98f5e4..5e2e5e192 100644
--- a/apps/agent-forge/server/lifecycle/publish.ts
+++ b/apps/agent-forge/server/lifecycle/publish.ts
@@ -21,7 +21,7 @@
  * the `published.yaml` write inside the final lock.
  */
 import type { Express, Request, Response } from 'express';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type {
   AgentMeta,
   EvalGateResult,
diff --git a/apps/agent-forge/server/logEntries.ts b/apps/agent-forge/server/logEntries.ts
index b207444ea..7eeb14552 100644
--- a/apps/agent-forge/server/logEntries.ts
+++ b/apps/agent-forge/server/logEntries.ts
@@ -3,8 +3,8 @@
  * `LogEntry` rows the Logs tab renders. Used by runRegistry.ts.
  */
 import { randomUUID } from 'node:crypto';
-import type { AgentEvent, AgentEventOf, AgentEventType } from 'lousho';
-import type { FlowExecutionEvent, FlowExecutionEventOf } from 'lousho/flows';
+import type { AgentEvent, AgentEventOf, AgentEventType } from '@linuxdevil/lousho';
+import type { FlowExecutionEvent, FlowExecutionEventOf } from '@linuxdevil/lousho/flows';
 import type { LogEntry } from '../shared/wireTypes';
 
 /** The event-specific part of a `LogEntry`; id/agentId/timestamp are added by the translators. */
diff --git a/apps/agent-forge/server/nodeStates.ts b/apps/agent-forge/server/nodeStates.ts
index d64a965c4..687c782b7 100644
--- a/apps/agent-forge/server/nodeStates.ts
+++ b/apps/agent-forge/server/nodeStates.ts
@@ -8,7 +8,7 @@
  * guessing from span names. Frames carry node ids and state only -
  * never secret values.
  */
-import { APPROVAL_WAIT_SPAN_NAME, SdkAttr, type Span } from 'lousho';
+import { APPROVAL_WAIT_SPAN_NAME, SdkAttr, type Span } from '@linuxdevil/lousho';
 import type { NodeRunState, NodeStatePayload } from '../shared/wireTypes';
 
 /**
diff --git a/apps/agent-forge/server/observeReporting.ts b/apps/agent-forge/server/observeReporting.ts
index b57821334..ae3766565 100644
--- a/apps/agent-forge/server/observeReporting.ts
+++ b/apps/agent-forge/server/observeReporting.ts
@@ -17,7 +17,7 @@ import {
   type ObserveExporterOptions,
   type Span,
   type TraceExporter,
-} from 'lousho/traces';
+} from '@linuxdevil/lousho/traces';
 import { observeTarget } from './observeProxy';
 import type { CollectorSource } from './collector';
 
diff --git a/apps/agent-forge/server/passes/__tests__/draftReview.test.ts b/apps/agent-forge/server/passes/__tests__/draftReview.test.ts
index d475501d2..cd0980f2c 100644
--- a/apps/agent-forge/server/passes/__tests__/draftReview.test.ts
+++ b/apps/agent-forge/server/passes/__tests__/draftReview.test.ts
@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach, vi, type Mock } from 'vite
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { SpecChange } from '../../../shared/wireTypes';
 import { AgentRepo } from '../../storage/agentRepo';
 import { DraftStore, type NewDraftInput } from '../../storage/draftStore';
diff --git a/apps/agent-forge/server/passes/__tests__/passModel.test.ts b/apps/agent-forge/server/passes/__tests__/passModel.test.ts
index 0448ca421..eb451f942 100644
--- a/apps/agent-forge/server/passes/__tests__/passModel.test.ts
+++ b/apps/agent-forge/server/passes/__tests__/passModel.test.ts
@@ -3,8 +3,8 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { z } from 'zod';
-import { ConfigurationError } from 'lousho';
-import type { GenerateOptions, GenerateResult } from 'lousho';
+import { ConfigurationError } from '@linuxdevil/lousho';
+import type { GenerateOptions, GenerateResult } from '@linuxdevil/lousho';
 import { callPassModel } from '../passModel';
 import { SettingsStore } from '../../settingsStore';
 import { SecretsStore } from '../../secretsStore';
diff --git a/apps/agent-forge/server/passes/__tests__/passRunner.test.ts b/apps/agent-forge/server/passes/__tests__/passRunner.test.ts
index 7553e4c7a..b133139e2 100644
--- a/apps/agent-forge/server/passes/__tests__/passRunner.test.ts
+++ b/apps/agent-forge/server/passes/__tests__/passRunner.test.ts
@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import type { Span, TraceExporter } from 'lousho/traces';
+import type { Span, TraceExporter } from '@linuxdevil/lousho/traces';
 import {
   PassOutputError,
   PassRefusedError,
diff --git a/apps/agent-forge/server/passes/__tests__/portability.test.ts b/apps/agent-forge/server/passes/__tests__/portability.test.ts
index 0ab76caeb..c118af8fd 100644
--- a/apps/agent-forge/server/passes/__tests__/portability.test.ts
+++ b/apps/agent-forge/server/passes/__tests__/portability.test.ts
@@ -8,7 +8,7 @@ import { describe, it, expect, beforeEach, afterEach, vi, type Mock } from 'vite
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { AgentRepo } from '../../storage/agentRepo';
 import { SuggestionStore } from '../../storage/suggestionStore';
 import { specHash } from '../../storage/specHash';
diff --git a/apps/agent-forge/server/passes/__tests__/promptSuggestion.digest.test.ts b/apps/agent-forge/server/passes/__tests__/promptSuggestion.digest.test.ts
index 892b588a5..1967bf5de 100644
--- a/apps/agent-forge/server/passes/__tests__/promptSuggestion.digest.test.ts
+++ b/apps/agent-forge/server/passes/__tests__/promptSuggestion.digest.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import type { ObservationRow } from 'lousho/traces';
+import type { ObservationRow } from '@linuxdevil/lousho/traces';
 import { buildFrictionDigest } from '../promptSuggestion';
 
 /** A minimal ObservationRow; every field the digest does not read defaults sanely. */
diff --git a/apps/agent-forge/server/passes/__tests__/promptSuggestion.test.ts b/apps/agent-forge/server/passes/__tests__/promptSuggestion.test.ts
index 026d8c901..680879793 100644
--- a/apps/agent-forge/server/passes/__tests__/promptSuggestion.test.ts
+++ b/apps/agent-forge/server/passes/__tests__/promptSuggestion.test.ts
@@ -2,8 +2,8 @@ import { describe, it, expect, beforeEach, afterEach, vi, type Mock } from 'vite
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import type { AgentSpecV2 } from 'lousho';
-import type { ObservationRow } from 'lousho/traces';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
+import type { ObservationRow } from '@linuxdevil/lousho/traces';
 import type { PromptSuggestion } from '../../../shared/wireTypes';
 import { AgentRepo } from '../../storage/agentRepo';
 import { VersionStore } from '../../storage/versionStore';
diff --git a/apps/agent-forge/server/passes/__tests__/versionSummary.test.ts b/apps/agent-forge/server/passes/__tests__/versionSummary.test.ts
index 37f673bed..f8c9411b6 100644
--- a/apps/agent-forge/server/passes/__tests__/versionSummary.test.ts
+++ b/apps/agent-forge/server/passes/__tests__/versionSummary.test.ts
@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach, vi, type Mock } from 'vite
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { SpecSnapshot, VersionKind, VersionListItem, VersionRecord } from '../../../shared/wireTypes';
 import { AgentRepo } from '../../storage/agentRepo';
 import { VersionStore } from '../../storage/versionStore';
diff --git a/apps/agent-forge/server/passes/draftReview.ts b/apps/agent-forge/server/passes/draftReview.ts
index e05bdf16f..ef4c8a90f 100644
--- a/apps/agent-forge/server/passes/draftReview.ts
+++ b/apps/agent-forge/server/passes/draftReview.ts
@@ -20,7 +20,7 @@
  * only the pass kind, key and outcome reach the runner's own records.
  */
 import { z } from 'zod';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { nodeIdList, toolKey } from '../../shared/nodeIds';
 import type {
   ChangeDraft,
diff --git a/apps/agent-forge/server/passes/passModel.ts b/apps/agent-forge/server/passes/passModel.ts
index 742b2fe6f..5ac168081 100644
--- a/apps/agent-forge/server/passes/passModel.ts
+++ b/apps/agent-forge/server/passes/passModel.ts
@@ -17,8 +17,8 @@
  *
  * Prompts and replies are never logged - they hold user instructions.
  */
-import { estimateCost, SDKError } from 'lousho';
-import type { LLMProvider } from 'lousho';
+import { estimateCost, SDKError } from '@linuxdevil/lousho';
+import type { LLMProvider } from '@linuxdevil/lousho';
 import { z } from 'zod';
 import type { PassKind } from '../../shared/wireTypes';
 import { buildAgentFromSpec } from '../buildAgent';
diff --git a/apps/agent-forge/server/passes/passRunner.ts b/apps/agent-forge/server/passes/passRunner.ts
index 0692f1a29..9a6276496 100644
--- a/apps/agent-forge/server/passes/passRunner.ts
+++ b/apps/agent-forge/server/passes/passRunner.ts
@@ -18,8 +18,8 @@
  * (`callPassModel` in L06b throws them for a missing key, a provider
  * refusal, or a disabled kind).
  */
-import { recordSpanError, withSpan } from 'lousho';
-import type { TraceExporter } from 'lousho/traces';
+import { recordSpanError, withSpan } from '@linuxdevil/lousho';
+import type { TraceExporter } from '@linuxdevil/lousho/traces';
 import type { PassKind } from '../../shared/wireTypes';
 import { observeReporting } from '../observeReporting';
 import { studioPaths } from '../workspace/studioPaths';
diff --git a/apps/agent-forge/server/passes/portability.ts b/apps/agent-forge/server/passes/portability.ts
index 188c2fda0..a057f2a4c 100644
--- a/apps/agent-forge/server/passes/portability.ts
+++ b/apps/agent-forge/server/passes/portability.ts
@@ -17,7 +17,7 @@
  * only the pass kind, key and outcome reach the runner's own records.
  */
 import { z } from 'zod';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { PassOutcome, PassRunner } from './passRunner';
 import type { SecretsStore } from '../secretsStore';
 import type { SettingsStore } from '../settingsStore';
diff --git a/apps/agent-forge/server/passes/portabilityRoutes.ts b/apps/agent-forge/server/passes/portabilityRoutes.ts
index d7136c4cc..a85cd71ac 100644
--- a/apps/agent-forge/server/passes/portabilityRoutes.ts
+++ b/apps/agent-forge/server/passes/portabilityRoutes.ts
@@ -12,13 +12,14 @@
  * Studio-global secrets/settings stores from the registration deps.
  */
 import type { Express, Request, Response } from 'express';
-import type { AgentSpecV2 } from 'lousho';
-import { asyncRoute, paramId, sendError } from '../http/routeUtils';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
+import { asyncRoute, sendError } from '../http/routeUtils';
 import { ImportError, parseImportText } from '../lifecycle/import';
 import type { SecretsStore } from '../secretsStore';
 import type { SettingsStore } from '../settingsStore';
 import type { WorkspaceContext } from '../workspace/context';
 import { workspaceOf } from '../workspace/middleware';
+import { readSpecOr404 } from '../workspace/specLookup';
 import { checkPortability, PortabilityError, type PortabilityDeps } from './portability';
 
 /** The Studio-global stores the portability routes need (per-workspace stores come from `workspaceOf(req)`). */
@@ -103,13 +104,9 @@ export function registerPortabilityRoutes(app: Express, deps: PortabilityRouteDe
   app.post(
     '/agents/:id/portability',
     asyncRoute(async (req: Request, res: Response) => {
-      const ws = workspaceOf(req);
-      const id = paramId(req);
-      const spec = await ws.repo.readSpec(id);
-      if (spec === undefined) {
-        sendError(res, 404, `No agent '${id}'`, 'LOUSHO_AGENT_NOT_FOUND');
-        return;
-      }
+      const input = await readSpecOr404(req, res, (id) => `No agent '${id}'`);
+      if (input === undefined) return;
+      const { ws, id, spec } = input;
       await sendAnalysis(res, spec, id, ws, deps);
     })
   );
diff --git a/apps/agent-forge/server/passes/promptSuggestion.ts b/apps/agent-forge/server/passes/promptSuggestion.ts
index d2fa54b83..9a7fd7360 100644
Binary files a/apps/agent-forge/server/passes/promptSuggestion.ts and b/apps/agent-forge/server/passes/promptSuggestion.ts differ
diff --git a/apps/agent-forge/server/passes/versionSummary.ts b/apps/agent-forge/server/passes/versionSummary.ts
index 9ffac51aa..add937d7a 100644
--- a/apps/agent-forge/server/passes/versionSummary.ts
+++ b/apps/agent-forge/server/passes/versionSummary.ts
@@ -12,7 +12,7 @@
  */
 import { diffLines, type Change } from 'diff';
 import { z } from 'zod';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { fieldLabel } from '../../shared/specFieldLabels';
 import { nodeIdList, skillKey, toolKey } from '../../shared/nodeIds';
 import type { SpecFieldKey } from '../../shared/specFields';
diff --git a/apps/agent-forge/server/pins.ts b/apps/agent-forge/server/pins.ts
index 7731ed1a2..c98003625 100644
--- a/apps/agent-forge/server/pins.ts
+++ b/apps/agent-forge/server/pins.ts
@@ -11,7 +11,7 @@
  * approve). The hook matches the FIRST pin whose `toolName` equals the
  * call's and whose `args` (when set) stable-stringify-equal the call's.
  */
-import type { AgentHook, ToolCallHookContext } from 'lousho';
+import type { AgentHook, ToolCallHookContext } from '@linuxdevil/lousho';
 import { stableStringify } from '../shared/stableJson';
 import type { ToolPin } from '../shared/wireTypes';
 
diff --git a/apps/agent-forge/server/playground.ts b/apps/agent-forge/server/playground.ts
index cc5fd2c2b..c5545ea6a 100644
--- a/apps/agent-forge/server/playground.ts
+++ b/apps/agent-forge/server/playground.ts
@@ -15,15 +15,15 @@
  * messages, so the server does not fetch the prompt again.
  */
 import type { Express, Response } from 'express';
-import { AgentExecutor } from 'lousho/executor';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
 import {
   InMemoryApprovalStore,
   SDKError,
   type AgentEvent,
   type AgentSpec,
   type Message,
-} from 'lousho';
-import { fanOutExporters, type ObserveExporterOptions, type Span, type TraceExporter } from 'lousho/traces';
+} from '@linuxdevil/lousho';
+import { fanOutExporters, type ObserveExporterOptions, type Span, type TraceExporter } from '@linuxdevil/lousho/traces';
 import { buildAgentFromSpec } from './buildAgent';
 import { observeReporting, type ObserveReporting } from './observeReporting';
 import type { SecretsStore } from './secretsStore';
diff --git a/apps/agent-forge/server/routes/__tests__/agentListItems.test.ts b/apps/agent-forge/server/routes/__tests__/agentListItems.test.ts
index 80eeb7269..f4fa466ae 100644
--- a/apps/agent-forge/server/routes/__tests__/agentListItems.test.ts
+++ b/apps/agent-forge/server/routes/__tests__/agentListItems.test.ts
@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { AgentRepo } from '../../storage/agentRepo';
 import { buildAgentListItems } from '../agentListItems';
 import type { AgentRunStatusPayload } from '../../../shared/wireTypes';
diff --git a/apps/agent-forge/server/routes/agentListItems.ts b/apps/agent-forge/server/routes/agentListItems.ts
index 284c5638b..3583e7982 100644
--- a/apps/agent-forge/server/routes/agentListItems.ts
+++ b/apps/agent-forge/server/routes/agentListItems.ts
@@ -7,7 +7,7 @@
  * bare `new AgentRepo(root)` and no RunManager - `runStatus` is simply
  * absent there, so `lastRun` falls back to the newest persisted trace.
  */
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { AgentLastRun, AgentListItem, AgentRunStatusPayload } from '../../shared/wireTypes';
 import type { AgentRepo } from '../storage/agentRepo';
 import { listAgentTraces } from '../traceStore';
diff --git a/apps/agent-forge/server/routes/agentRoutes.ts b/apps/agent-forge/server/routes/agentRoutes.ts
index 884d72002..b0e85a0fd 100644
--- a/apps/agent-forge/server/routes/agentRoutes.ts
+++ b/apps/agent-forge/server/routes/agentRoutes.ts
@@ -33,7 +33,7 @@
  * `?ws=all` route reuses them verbatim (W06a).
  */
 import type { Express, Response } from 'express';
-import type { AgentSpec, AgentSpecV2 } from 'lousho';
+import type { AgentSpec, AgentSpecV2 } from '@linuxdevil/lousho';
 import { LabelError, MAX_LABEL_LENGTH, MAX_LABELS, normalizeLabels } from '../../shared/labels';
 import type {
   AgentMeta,
diff --git a/apps/agent-forge/server/routes/catalogRoutes.ts b/apps/agent-forge/server/routes/catalogRoutes.ts
index 259c039bc..297c4df54 100644
--- a/apps/agent-forge/server/routes/catalogRoutes.ts
+++ b/apps/agent-forge/server/routes/catalogRoutes.ts
@@ -17,13 +17,13 @@
  *
  * Tools, guardrails, trigger types and the parsed registry index are
  * memoised per `registerCatalogRoutes` call (static until the next
- * `lousho` upgrade); models are computed per request because stored keys
+ * `@linuxdevil/lousho` upgrade); models are computed per request because stored keys
  * change at runtime. `/catalog/mcp/probe` is a later ticket.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import type { Express } from 'express';
-import { listBuiltinTools, listGuardrails, listTriggerTypes } from 'lousho';
+import { listBuiltinTools, listGuardrails, listTriggerTypes } from '@linuxdevil/lousho';
 import type {
   CatalogGuardrail,
   CatalogKit,
diff --git a/apps/agent-forge/server/routes/draftRoutes.ts b/apps/agent-forge/server/routes/draftRoutes.ts
index 45504a260..98ae52aab 100644
--- a/apps/agent-forge/server/routes/draftRoutes.ts
+++ b/apps/agent-forge/server/routes/draftRoutes.ts
@@ -15,7 +15,7 @@
  * the stores themselves stay lock-free.
  */
 import type { Express, Response } from 'express';
-import { agentSpecV2Schema } from 'lousho';
+import { agentSpecV2Schema } from '@linuxdevil/lousho';
 import { computeChangedFields, SPEC_FIELD_ORDER } from '../../shared/specFields';
 import { LabelError, normalizeLabels } from '../../shared/labels';
 import type {
diff --git a/apps/agent-forge/server/routes/mcpProbe.ts b/apps/agent-forge/server/routes/mcpProbe.ts
index e33e4a417..e8ecfee05 100644
--- a/apps/agent-forge/server/routes/mcpProbe.ts
+++ b/apps/agent-forge/server/routes/mcpProbe.ts
@@ -23,8 +23,8 @@
  * spawns a command on this machine; the token gate is the guard).
  */
 import type { Express } from 'express';
-import { agentSpecV2Schema, resolveSecretRef, type McpServerSpec } from 'lousho';
-import { connectMcp, type McpConnections } from 'lousho/mcp';
+import { agentSpecV2Schema, resolveSecretRef, type McpServerSpec } from '@linuxdevil/lousho';
+import { connectMcp, type McpConnections } from '@linuxdevil/lousho/mcp';
 import type { McpProbeResponse, McpProbeTool, McpServerSpecV2 } from '../../shared/wireTypes';
 import { asyncRoute, sendError } from '../http/routeUtils';
 
diff --git a/apps/agent-forge/server/routes/versionRoutes.ts b/apps/agent-forge/server/routes/versionRoutes.ts
index a0579880e..fee151d82 100644
--- a/apps/agent-forge/server/routes/versionRoutes.ts
+++ b/apps/agent-forge/server/routes/versionRoutes.ts
@@ -15,7 +15,7 @@
  * deps to close over.
  */
 import type { Express, Response } from 'express';
-import { agentSpecV2Schema } from 'lousho';
+import { agentSpecV2Schema } from '@linuxdevil/lousho';
 import { diffSpecs } from '../diff/specChange';
 import { asyncRoute, paramId, sendError } from '../http/routeUtils';
 import { withAgentLock } from '../storage/atomic';
diff --git a/apps/agent-forge/server/runRegistry.ts b/apps/agent-forge/server/runRegistry.ts
index bd48781eb..f83b13fb2 100644
--- a/apps/agent-forge/server/runRegistry.ts
+++ b/apps/agent-forge/server/runRegistry.ts
@@ -15,10 +15,10 @@
  */
 import { EventEmitter } from 'node:events';
 import { randomUUID } from 'node:crypto';
-import { fanOutExporters, fileTraceExporter, type ObserveExporterOptions } from 'lousho/traces';
+import { fanOutExporters, fileTraceExporter, type ObserveExporterOptions } from '@linuxdevil/lousho/traces';
 import { agentTraceDir } from './traceStore';
 import { observeReporting, withoutCapturedContent, type ObserveReporting } from './observeReporting';
-import { AgentExecutor } from 'lousho/executor';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
 import {
   type AgentEvent,
   type AgentInput,
@@ -35,8 +35,8 @@ import {
   type CheckpointHistoryEntry,
   type ForkPatch,
   type TrajectoryComparison,
-} from 'lousho';
-import { FlowExecutor, type AgentFlow } from 'lousho/flows';
+} from '@linuxdevil/lousho';
+import { FlowExecutor, type AgentFlow } from '@linuxdevil/lousho/flows';
 import { buildAgentFromSpec, extractFlowFromSpec } from './buildAgent';
 import { toLegacySpec } from './storage/legacySpec';
 import { HostRunNotActiveError, type AgentHost, type HostEvent, type HostRunResult } from './host/agentHost';
@@ -883,7 +883,7 @@ export class RunManager extends EventEmitter {
     agentId: string,
     flow: AgentFlow,
     resolvedSpec: AgentSpecV2,
-    legacySpec: import('lousho').AgentSpec,
+    legacySpec: import('@linuxdevil/lousho').AgentSpec,
     existing: RunEntry | undefined,
     options: { runInput?: string; source?: 'manual' | 'trigger'; triggerId?: string }
   ): Promise<void> {
diff --git a/apps/agent-forge/server/sdkRoot.ts b/apps/agent-forge/server/sdkRoot.ts
index 770f0fe37..1fb051ab8 100644
--- a/apps/agent-forge/server/sdkRoot.ts
+++ b/apps/agent-forge/server/sdkRoot.ts
@@ -1,19 +1,48 @@
 /**
  * The lousho SDK package root - where package-shipped assets like
- * `registry/dist/index.json` live, for the catalog routes
- * (server/routes/catalogRoutes.ts).
+ * `registry/dist/index.json` and `docs/` live, for the catalog routes
+ * (server/routes/catalogRoutes.ts) and the docs tools.
  *
- * Resolution: `LOUSHO_SDK_ROOT` when set (tests, unusual layouts), else
- * three levels above this file's own directory. Both places this code runs
- * from sit at `apps/agent-forge/<x>` - `server/` under tsx and the bundled
- * `dist-server/index.cjs` in prod - so `../../..` lands on the repo root in
- * this monorepo and on `node_modules/lousho` (the package root)
- * in an installed deployment, never assuming it runs from `server/`.
+ * Resolution: `LOUSHO_SDK_ROOT` when set (tests, unusual layouts), else the
+ * installed `@linuxdevil/lousho` package itself - `createRequire` resolves
+ * its entry and we walk up to the first folder whose `package.json` is
+ * named `@linuxdevil/lousho`. That works from the monorepo (the workspace
+ * symlink lands on the repo root) and from `node_modules/@linuxdevil/studio`
+ * (the SDK is a real dependency there), where the old "three levels up"
+ * rule broke.
  */
+import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 
-/** The SDK package root: env LOUSHO_SDK_ROOT, else three levels above this file's dir (server/ and dist-server/ are both at apps/agent-forge/<x>). */
-export function sdkRootDir(): string {
-  return process.env.LOUSHO_SDK_ROOT ?? path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const SDK_PACKAGE = '@linuxdevil/lousho';
+
+/** The SDK package root: env LOUSHO_SDK_ROOT, else the resolved `@linuxdevil/lousho` install. */
+export function sdkRootDir(moduleDir?: string): string {
+  const env = process.env.LOUSHO_SDK_ROOT;
+  if (env) return env;
+  const from = moduleDir ?? path.dirname(fileURLToPath(import.meta.url));
+  const require = createRequire(path.join(from, 'noop.cjs'));
+  let entry: string;
+  try {
+    entry = require.resolve(SDK_PACKAGE);
+  } catch {
+    throw new Error(`lousho-studio: could not locate the ${SDK_PACKAGE} package. Set LOUSHO_SDK_ROOT.`);
+  }
+  let dir = path.dirname(entry);
+  for (;;) {
+    const pkgPath = path.join(dir, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      try {
+        if ((JSON.parse(fs.readFileSync(pkgPath, 'utf8')) as { name?: string }).name === SDK_PACKAGE) return dir;
+      } catch {
+        // Unreadable package.json - keep walking up.
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(`lousho-studio: could not locate the ${SDK_PACKAGE} package. Set LOUSHO_SDK_ROOT.`);
 }
diff --git a/apps/agent-forge/server/serve/mcpServers.ts b/apps/agent-forge/server/serve/mcpServers.ts
index a564eaa51..87b80c634 100644
--- a/apps/agent-forge/server/serve/mcpServers.ts
+++ b/apps/agent-forge/server/serve/mcpServers.ts
@@ -12,8 +12,8 @@
  *   moved, and stops one whose agent lost its publish pointer.
  * - `closeAll` runs on Studio shutdown.
  */
-import type { AgentSpecV2, SimpleAgent } from 'lousho';
-import { serveMcp, type ServeMcpHandle, type ServeMcpOptions } from 'lousho/mcp';
+import type { AgentSpecV2, SimpleAgent } from '@linuxdevil/lousho';
+import { serveMcp, type ServeMcpHandle, type ServeMcpOptions } from '@linuxdevil/lousho/mcp';
 import type { McpServeStatus } from '../../shared/wireTypes';
 import type { AgentRepo } from '../storage/agentRepo';
 import type { VersionStore } from '../storage/versionStore';
diff --git a/apps/agent-forge/server/serve/serveRoutes.ts b/apps/agent-forge/server/serve/serveRoutes.ts
index 82b3b1ce7..392cf7952 100644
--- a/apps/agent-forge/server/serve/serveRoutes.ts
+++ b/apps/agent-forge/server/serve/serveRoutes.ts
@@ -30,8 +30,8 @@ import {
   FileSessionStore,
   type AgentSpecV2,
   type SimpleAgent,
-} from 'lousho';
-import { fileTraceExporter } from 'lousho/traces';
+} from '@linuxdevil/lousho';
+import { fileTraceExporter } from '@linuxdevil/lousho/traces';
 import type { McpServeStatus, ServeAgentConfig, ServeStatus, ServeTokenReveal } from '../../shared/wireTypes';
 import { asyncRoute, paramId, sendError } from '../http/routeUtils';
 import { isValidAgentId } from '../types';
diff --git a/apps/agent-forge/server/storage/__tests__/agentIds.test.ts b/apps/agent-forge/server/storage/__tests__/agentIds.test.ts
index 335894064..da73c6fc2 100644
--- a/apps/agent-forge/server/storage/__tests__/agentIds.test.ts
+++ b/apps/agent-forge/server/storage/__tests__/agentIds.test.ts
@@ -8,7 +8,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { isValidAgentId } from '../../../shared/agentId';
 import { AgentRepo } from '../agentRepo';
 import { slugAgentId, uniqueAgentId } from '../agentIds';
diff --git a/apps/agent-forge/server/storage/__tests__/agentRepo.test.ts b/apps/agent-forge/server/storage/__tests__/agentRepo.test.ts
index 5d484d043..0d6ba2643 100644
--- a/apps/agent-forge/server/storage/__tests__/agentRepo.test.ts
+++ b/apps/agent-forge/server/storage/__tests__/agentRepo.test.ts
@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { AgentRepo, InvalidSpecError } from '../agentRepo';
 import { specHash } from '../specHash';
 import type { AgentMeta, CanvasLayout } from '../../../shared/wireTypes';
diff --git a/apps/agent-forge/server/storage/__tests__/legacySpec.test.ts b/apps/agent-forge/server/storage/__tests__/legacySpec.test.ts
index 1a3d5f6ed..f12111275 100644
--- a/apps/agent-forge/server/storage/__tests__/legacySpec.test.ts
+++ b/apps/agent-forge/server/storage/__tests__/legacySpec.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { upgradeSpec, type AgentSpec, type AgentSpecV2 } from 'lousho';
+import { upgradeSpec, type AgentSpec, type AgentSpecV2 } from '@linuxdevil/lousho';
 import { mergeLegacySave, toLegacySpec } from '../legacySpec';
 
 const base: AgentSpec = { name: 'bot', prompt: 'Be helpful.', provider: { type: 'mock', model: 'm1' } };
diff --git a/apps/agent-forge/server/storage/__tests__/specFields.test.ts b/apps/agent-forge/server/storage/__tests__/specFields.test.ts
index d1508c947..fd05980d9 100644
--- a/apps/agent-forge/server/storage/__tests__/specFields.test.ts
+++ b/apps/agent-forge/server/storage/__tests__/specFields.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { computeChangedFields } from '../../../shared/specFields';
 import type { SpecSnapshot } from '../../../shared/wireTypes';
 
diff --git a/apps/agent-forge/server/storage/__tests__/specHash.test.ts b/apps/agent-forge/server/storage/__tests__/specHash.test.ts
index 8d5b7cada..844744691 100644
--- a/apps/agent-forge/server/storage/__tests__/specHash.test.ts
+++ b/apps/agent-forge/server/storage/__tests__/specHash.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { sortKeysDeep } from '../../../shared/stableJson';
 import { specHash } from '../specHash';
 
diff --git a/apps/agent-forge/server/storage/__tests__/versionStore.summary.test.ts b/apps/agent-forge/server/storage/__tests__/versionStore.summary.test.ts
index d1643d07e..dd3fb0cce 100644
--- a/apps/agent-forge/server/storage/__tests__/versionStore.summary.test.ts
+++ b/apps/agent-forge/server/storage/__tests__/versionStore.summary.test.ts
@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { stringify as stringifyYaml } from 'yaml';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { AgentRepo } from '../agentRepo';
 import { VersionStore, type CaptureInput } from '../versionStore';
 import type { VersionListItem, VersionRecord } from '../../../shared/wireTypes';
diff --git a/apps/agent-forge/server/storage/__tests__/versionStore.test.ts b/apps/agent-forge/server/storage/__tests__/versionStore.test.ts
index 2eac7c2d7..4d0d841af 100644
--- a/apps/agent-forge/server/storage/__tests__/versionStore.test.ts
+++ b/apps/agent-forge/server/storage/__tests__/versionStore.test.ts
@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { stringify as stringifyYaml } from 'yaml';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { AgentRepo } from '../agentRepo';
 import { VersionStore, type CaptureInput } from '../versionStore';
 import type { VersionListItem, VersionRecord } from '../../../shared/wireTypes';
diff --git a/apps/agent-forge/server/storage/agentRepo.ts b/apps/agent-forge/server/storage/agentRepo.ts
index 88184283e..4f4043363 100644
--- a/apps/agent-forge/server/storage/agentRepo.ts
+++ b/apps/agent-forge/server/storage/agentRepo.ts
@@ -21,7 +21,7 @@ import * as fs from 'node:fs';
 import { promises as fsPromises } from 'node:fs';
 import * as path from 'node:path';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
-import { agentSpecV2Schema, loadSpecV2, upgradeSpec, type AgentSpecV2 } from 'lousho';
+import { agentSpecV2Schema, loadSpecV2, upgradeSpec, type AgentSpecV2 } from '@linuxdevil/lousho';
 import { isValidAgentId } from '../../shared/agentId';
 import type { AgentMeta, CanvasLayout } from '../../shared/wireTypes';
 import { readJsonFile, writeFileAtomic, writeJsonAtomic } from './atomic';
diff --git a/apps/agent-forge/server/storage/draftStore.ts b/apps/agent-forge/server/storage/draftStore.ts
index 0c5e1893c..16d5eea1e 100644
--- a/apps/agent-forge/server/storage/draftStore.ts
+++ b/apps/agent-forge/server/storage/draftStore.ts
@@ -18,7 +18,7 @@
 import { promises as fsPromises } from 'node:fs';
 import * as path from 'node:path';
 import { randomUUID } from 'node:crypto';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type {
   ChangeDraft,
   DraftFieldClasses,
diff --git a/apps/agent-forge/server/storage/legacySpec.ts b/apps/agent-forge/server/storage/legacySpec.ts
index 3e52d03b7..3bb4ce622 100644
--- a/apps/agent-forge/server/storage/legacySpec.ts
+++ b/apps/agent-forge/server/storage/legacySpec.ts
@@ -12,7 +12,7 @@
  * Deleted once the routes (D06a), RunManager (D12b) and the canvas (C02)
  * speak spec v2 directly.
  */
-import { agentSpecV2Schema, upgradeSpec, type AgentSpec, type AgentSpecGuardrail, type AgentSpecPolicy, type AgentSpecV2 } from 'lousho';
+import { agentSpecV2Schema, upgradeSpec, type AgentSpec, type AgentSpecGuardrail, type AgentSpecPolicy, type AgentSpecV2 } from '@linuxdevil/lousho';
 import type { SerializedHook } from '../compileHooks';
 import { sortKeysDeep } from '../../shared/stableJson';
 
diff --git a/apps/agent-forge/server/storage/specHash.ts b/apps/agent-forge/server/storage/specHash.ts
index 66a1651e7..a79f98fdf 100644
--- a/apps/agent-forge/server/storage/specHash.ts
+++ b/apps/agent-forge/server/storage/specHash.ts
@@ -10,7 +10,7 @@
  */
 import { createHash } from 'node:crypto';
 import { stringify as stringifyYaml } from 'yaml';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { sortKeysDeep } from '../../shared/stableJson';
 
 /** The canonical YAML a spec hashes as: `yaml.stringify` of the deep key-sorted spec. */
diff --git a/apps/agent-forge/server/templates/templateCatalog.ts b/apps/agent-forge/server/templates/templateCatalog.ts
index d5636f6cb..c4a56cba9 100644
--- a/apps/agent-forge/server/templates/templateCatalog.ts
+++ b/apps/agent-forge/server/templates/templateCatalog.ts
@@ -22,7 +22,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import type { Express } from 'express';
-import { loadSpecV2, type AgentSpecV2 } from 'lousho';
+import { loadSpecV2, type AgentSpecV2 } from '@linuxdevil/lousho';
 import type { RequirementKind, TemplateDetail, TemplateSummary } from '../../shared/wireTypes';
 import { asyncRoute, paramId, sendError } from '../http/routeUtils';
 import { sdkRootDir } from '../sdkRoot';
diff --git a/apps/agent-forge/server/traceStore.ts b/apps/agent-forge/server/traceStore.ts
index 56f3ca964..9143b2702 100644
--- a/apps/agent-forge/server/traceStore.ts
+++ b/apps/agent-forge/server/traceStore.ts
@@ -10,7 +10,7 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { listTraces, readTrace, type TraceSummary } from 'lousho/traces';
+import { listTraces, readTrace, type TraceSummary } from '@linuxdevil/lousho/traces';
 import type { SpanEvent, TraceSummaryPayload } from '../shared/wireTypes';
 
 /** A trace id is a UUID in practice; this is the strictest shape that still allows prefixes. */
diff --git a/apps/agent-forge/server/triggers/abortListeners.ts b/apps/agent-forge/server/triggers/abortListeners.ts
index 2f22eece8..1c5ff346b 100644
--- a/apps/agent-forge/server/triggers/abortListeners.ts
+++ b/apps/agent-forge/server/triggers/abortListeners.ts
@@ -16,8 +16,8 @@
  * never blocks the dispatch. Event bodies are never logged (they may
  * carry secrets); only listener ids and expressions are.
  */
-import type { AgentSpecV2 } from 'lousho';
-import { evaluateSafeExpression, ExpressionError } from 'lousho/flows';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
+import { evaluateSafeExpression, ExpressionError } from '@linuxdevil/lousho/flows';
 
 import type { HostRun, TriggerHost } from './triggerHost';
 
diff --git a/apps/agent-forge/server/triggers/chainTriggers.ts b/apps/agent-forge/server/triggers/chainTriggers.ts
index 8395f6eaa..3d21e9bb0 100644
--- a/apps/agent-forge/server/triggers/chainTriggers.ts
+++ b/apps/agent-forge/server/triggers/chainTriggers.ts
@@ -22,8 +22,8 @@
  * A cancelled run (`RunEnd.cancelled`, or a manual `stopped`/abort)
  * chains nothing, and `paused` is not an end.
  */
-import type { AgentSpecV2 } from 'lousho';
-import type { TriggerSpec } from 'lousho/spec';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
+import type { TriggerSpec } from '@linuxdevil/lousho/spec';
 
 import type { AgentRepo } from '../storage/agentRepo';
 import type { RunManager } from '../runRegistry';
diff --git a/apps/agent-forge/server/triggers/channelTriggers.ts b/apps/agent-forge/server/triggers/channelTriggers.ts
index 4a56be6d8..e2a134ccc 100644
--- a/apps/agent-forge/server/triggers/channelTriggers.ts
+++ b/apps/agent-forge/server/triggers/channelTriggers.ts
@@ -39,9 +39,9 @@ import {
   type Channel,
   type ChannelsHandler,
   type SimpleAgent,
-} from 'lousho';
-import type { SecretRef, TriggerSpec } from 'lousho/spec';
-import { evaluateSafeExpression } from 'lousho/flows';
+} from '@linuxdevil/lousho';
+import type { SecretRef, TriggerSpec } from '@linuxdevil/lousho/spec';
+import { evaluateSafeExpression } from '@linuxdevil/lousho/flows';
 
 import type { ChannelTriggerStatus } from '../../shared/wireTypes';
 import type { AgentRepo } from '../storage/agentRepo';
diff --git a/apps/agent-forge/server/triggers/cronTriggers.ts b/apps/agent-forge/server/triggers/cronTriggers.ts
index 8b05d8445..f56b27731 100644
--- a/apps/agent-forge/server/triggers/cronTriggers.ts
+++ b/apps/agent-forge/server/triggers/cronTriggers.ts
@@ -17,8 +17,8 @@
  */
 import * as path from 'node:path';
 
-import { CronExpressionError, parseCronExpression, type CronSchedule } from 'lousho/triggers';
-import type { TriggerSpec } from 'lousho/spec';
+import { CronExpressionError, parseCronExpression, type CronSchedule } from '@linuxdevil/lousho/triggers';
+import type { TriggerSpec } from '@linuxdevil/lousho/spec';
 
 import { readJsonFile, withAgentLock, writeJsonAtomic } from '../storage/atomic';
 import { AgentRepo } from '../storage/agentRepo';
diff --git a/apps/agent-forge/server/triggers/runtime.ts b/apps/agent-forge/server/triggers/runtime.ts
index 3f7b8dec4..26897538e 100644
--- a/apps/agent-forge/server/triggers/runtime.ts
+++ b/apps/agent-forge/server/triggers/runtime.ts
@@ -8,8 +8,8 @@
  */
 import { randomUUID } from 'node:crypto';
 
-import type { SimpleAgent, TraceExporter } from 'lousho';
-import { fanOutExporters, fileTraceExporter } from 'lousho/traces';
+import type { SimpleAgent, TraceExporter } from '@linuxdevil/lousho';
+import { fanOutExporters, fileTraceExporter } from '@linuxdevil/lousho/traces';
 
 import type { LogEntry } from '../../shared/wireTypes';
 import { buildRunnableAgent, type StudioRunDeps } from '../buildAgentV2';
diff --git a/apps/agent-forge/server/triggers/triggerHost.ts b/apps/agent-forge/server/triggers/triggerHost.ts
index 59289bca3..aaa6f9004 100644
--- a/apps/agent-forge/server/triggers/triggerHost.ts
+++ b/apps/agent-forge/server/triggers/triggerHost.ts
@@ -15,8 +15,8 @@
  */
 import { randomUUID } from 'node:crypto';
 
-import type { AgentSpecV2 } from 'lousho';
-import type { TriggerSpec } from 'lousho/spec';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
+import type { TriggerSpec } from '@linuxdevil/lousho/spec';
 
 import type { AgentRepo } from '../storage/agentRepo';
 import type { RunManager } from '../runRegistry';
diff --git a/apps/agent-forge/server/triggers/webhookRoute.ts b/apps/agent-forge/server/triggers/webhookRoute.ts
index 5501c0b66..71c6d6ad8 100644
--- a/apps/agent-forge/server/triggers/webhookRoute.ts
+++ b/apps/agent-forge/server/triggers/webhookRoute.ts
@@ -31,10 +31,10 @@
  * workspace mode. Secrets are Studio-global (`resolveSecret` dep).
  */
 import type { Express, Request, Response } from 'express';
-import { evaluateSafeExpression } from 'lousho/flows';
-import { resolveSecretRef } from 'lousho';
-import type { TriggerSpec } from 'lousho/spec';
-import { checkWebhookAuth } from 'lousho/triggers';
+import { evaluateSafeExpression } from '@linuxdevil/lousho/flows';
+import { resolveSecretRef } from '@linuxdevil/lousho';
+import type { TriggerSpec } from '@linuxdevil/lousho/spec';
+import { checkWebhookAuth } from '@linuxdevil/lousho/triggers';
 
 import { isLoopbackHost } from '../auth';
 import { asyncRoute, sendError } from '../http/routeUtils';
diff --git a/apps/agent-forge/server/tsup.config.ts b/apps/agent-forge/server/tsup.config.ts
index fdac6c4f1..c8192044b 100644
--- a/apps/agent-forge/server/tsup.config.ts
+++ b/apps/agent-forge/server/tsup.config.ts
@@ -39,8 +39,10 @@ import { defineConfig } from 'tsup';
  * bundled here instead of left as a real `require`/`import`.
  */
 export default defineConfig({
-  entry: { index: 'server/index.ts' },
+  entry: { index: 'server/index.ts', cli: 'server/cli.ts' },
   outDir: 'dist-server',
+  // The `lousho-studio` bin. Harmless on index.cjs (a comment line).
+  banner: { js: '#!/usr/bin/env node' },
   // CJS, not ESM: bundling `express` (and its own dependency `debug`, which
   // does `require('tty')`/`require('util')` conditionally at runtime to
   // detect a TTY) as ESM makes esbuild emit those as its own
@@ -61,6 +63,6 @@ export default defineConfig({
   clean: true,
   treeshake: true,
   minify: false,
-  external: ['lousho', 'yaml'],
+  external: ['@linuxdevil/lousho', 'yaml', 'ai', 'zod', '@ai-sdk/openai', '@ai-sdk/anthropic'],
   noExternal: ['express', 'ws'],
 });
diff --git a/apps/agent-forge/server/vitest.compat.config.ts b/apps/agent-forge/server/vitest.compat.config.ts
new file mode 100644
index 000000000..e6e5cf967
--- /dev/null
+++ b/apps/agent-forge/server/vitest.compat.config.ts
@@ -0,0 +1,17 @@
+import { defineConfig } from 'vitest/config';
+
+// W15b: the bridge compatibility matrix runs ONLY here - it needs a built
+// SDK (default: this checkout; `LOUSHO_BRIDGE_SDK_DIR` points at another,
+// e.g. the minimum supported release) and spawns real `lousho bridge`
+// children, so it stays out of `test:server` (see vitest.config.ts).
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['server/__tests__/bridge.compat.test.ts'],
+    testTimeout: 60_000,
+    env: {
+      LOUSHO_STUDIO_COLLECTOR: '0',
+    },
+  },
+});
diff --git a/apps/agent-forge/server/workspace/__tests__/middleware.test.ts b/apps/agent-forge/server/workspace/__tests__/middleware.test.ts
index 001304cb0..9c5f07ba0 100644
--- a/apps/agent-forge/server/workspace/__tests__/middleware.test.ts
+++ b/apps/agent-forge/server/workspace/__tests__/middleware.test.ts
@@ -1,7 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import express from 'express';
 import request from 'supertest';
-import { TriggerRegistry } from 'lousho/triggers';
+import { TriggerRegistry } from '@linuxdevil/lousho/triggers';
 import { ALL_WORKSPACES } from '../../../shared/workspace';
 import type { LegacyAgentStore } from '../../../src/persistence/AgentStore';
 import type { RunManager } from '../../runRegistry';
diff --git a/apps/agent-forge/server/workspace/__tests__/workspaceManager.test.ts b/apps/agent-forge/server/workspace/__tests__/workspaceManager.test.ts
index dd1e407ef..90c16d305 100644
--- a/apps/agent-forge/server/workspace/__tests__/workspaceManager.test.ts
+++ b/apps/agent-forge/server/workspace/__tests__/workspaceManager.test.ts
@@ -16,7 +16,7 @@ import type { InboxService } from '../../inbox/inboxService';
 import type { TriggerHost } from '../../triggers/triggerHost';
 import type { CronTriggers } from '../../triggers/cronTriggers';
 import type { LegacyAgentStore } from '../../../src/persistence/AgentStore';
-import { TriggerRegistry } from 'lousho/triggers';
+import { TriggerRegistry } from '@linuxdevil/lousho/triggers';
 import type { WorkspaceContext } from '../context';
 import type { WorkspaceRef } from '../../../shared/workspace';
 import { WorkspaceRegistry } from '../workspaceRegistry';
diff --git a/apps/agent-forge/server/workspace/agentDirRoutes.ts b/apps/agent-forge/server/workspace/agentDirRoutes.ts
index 573e3b673..82142bcfd 100644
--- a/apps/agent-forge/server/workspace/agentDirRoutes.ts
+++ b/apps/agent-forge/server/workspace/agentDirRoutes.ts
@@ -12,7 +12,7 @@
  */
 import { stat } from 'node:fs/promises';
 import type { Express, Request, Response } from 'express';
-import { agentDirToSpec, SDKError } from 'lousho';
+import { agentDirToSpec, SDKError } from '@linuxdevil/lousho';
 import type { CodeAgentSpecResponse, WorkspaceScanResult } from '../../shared/wireTypes';
 import { asyncRoute, sendError } from '../http/routeUtils';
 import { workspaceOf } from './middleware';
diff --git a/apps/agent-forge/server/workspace/context.ts b/apps/agent-forge/server/workspace/context.ts
index 13ffeb8e8..aa0f45f3a 100644
--- a/apps/agent-forge/server/workspace/context.ts
+++ b/apps/agent-forge/server/workspace/context.ts
@@ -13,7 +13,7 @@
  * Studio was launched in; `WorkspaceResolver` is the seam a lazy,
  * registry-backed multi-workspace resolver plugs into later.
  */
-import { TriggerRegistry } from 'lousho/triggers';
+import { TriggerRegistry } from '@linuxdevil/lousho/triggers';
 import { ALL_WORKSPACES, type WorkspaceRef } from '../../shared/workspace';
 import type { LegacyAgentStore } from '../../src/persistence/AgentStore';
 import { createFsAgentStore } from '../../src/persistence/fsAgentStore';
diff --git a/apps/agent-forge/server/workspace/specLookup.ts b/apps/agent-forge/server/workspace/specLookup.ts
new file mode 100644
index 000000000..944ac6ac4
--- /dev/null
+++ b/apps/agent-forge/server/workspace/specLookup.ts
@@ -0,0 +1,27 @@
+/**
+ * The shared "load this agent's spec or answer 404" lookup the per-agent
+ * POST routes repeat: `workspaceOf(req)` picks the workspace, `paramId`
+ * the id, `repo.readSpec` the spec. `notFoundMessage` formats the 404
+ * body per route. Returns `undefined` once the 404 is sent so the caller
+ * can early-return.
+ */
+import type { Request, Response } from 'express';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
+import { paramId, sendError } from '../http/routeUtils';
+import { workspaceOf } from './middleware';
+import type { WorkspaceContext } from './context';
+
+export async function readSpecOr404(
+  req: Request,
+  res: Response,
+  notFoundMessage: (id: string) => string
+): Promise<{ ws: WorkspaceContext; id: string; spec: AgentSpecV2 } | undefined> {
+  const ws = workspaceOf(req);
+  const id = paramId(req);
+  const spec = await ws.repo.readSpec(id);
+  if (spec === undefined) {
+    sendError(res, 404, notFoundMessage(id), 'LOUSHO_AGENT_NOT_FOUND');
+    return undefined;
+  }
+  return { ws, id, spec };
+}
diff --git a/apps/agent-forge/shared/authorWire.ts b/apps/agent-forge/shared/authorWire.ts
index a52bd6ec2..db5db5078 100644
--- a/apps/agent-forge/shared/authorWire.ts
+++ b/apps/agent-forge/shared/authorWire.ts
@@ -9,7 +9,7 @@
  * module instead of re-declaring them.
  */
 
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { Requirement, SpecChange } from './wireTypes';
 
 // The readiness row AA13's `computeRequirements` returns and the Author's
diff --git a/apps/agent-forge/shared/nodeIds.ts b/apps/agent-forge/shared/nodeIds.ts
index 0823dc703..828e99022 100644
--- a/apps/agent-forge/shared/nodeIds.ts
+++ b/apps/agent-forge/shared/nodeIds.ts
@@ -8,7 +8,7 @@
  * `shared/` ships in the browser bundle, so basenames are computed by hand
  * (`node:path` is not available here).
  */
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 
 /** One `spec.tools` entry (the SDK's ToolRef union, derived here since it is not a public export). */
 type ToolRef = NonNullable<AgentSpecV2['tools']>[number];
diff --git a/apps/agent-forge/shared/specFields.ts b/apps/agent-forge/shared/specFields.ts
index b2db0a542..b69c7cb78 100644
--- a/apps/agent-forge/shared/specFields.ts
+++ b/apps/agent-forge/shared/specFields.ts
@@ -7,7 +7,7 @@
  * `diffSpecs` (the `SpecChange[]` the diff route returns), so the Versions
  * tab's chips and the diff sheet never disagree or reshuffle.
  */
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { stableStringify } from './stableJson';
 import type { SpecSection, SpecSnapshot } from './wireTypes';
 
diff --git a/apps/agent-forge/shared/wireTypes.ts b/apps/agent-forge/shared/wireTypes.ts
index 9bbcc6654..e6cf21401 100644
--- a/apps/agent-forge/shared/wireTypes.ts
+++ b/apps/agent-forge/shared/wireTypes.ts
@@ -20,7 +20,7 @@ import type {
   listGuardrails,
   listModels,
   listTriggerTypes,
-} from 'lousho';
+} from '@linuxdevil/lousho';
 import type { WorkspaceRef } from './workspace';
 import type { AuthorSettings } from './authorWire';
 
@@ -1601,3 +1601,14 @@ export interface ChannelTriggerStatus {
   /** Mount failure (`Channel <kind> needs <key>`, duplicate kind), `null` when served. */
   error: string | null;
 }
+
+/**
+ * `POST /agents/:id/eject` (A08b): the agent directory `specToAgentDir`
+ * wrote under `agents/<id>/` in the workspace, and the file paths written.
+ */
+export interface EjectResult {
+  /** The directory, relative to the workspace root (`agents/<id>`). */
+  dir: string;
+  /** Paths of the files written, relative to `dir`, '/'-separated. */
+  files: string[];
+}
diff --git a/apps/agent-forge/src/canvas/kinds/flow/FlowInputsEditor.tsx b/apps/agent-forge/src/canvas/kinds/flow/FlowInputsEditor.tsx
index 12283787f..f1be0dad1 100644
--- a/apps/agent-forge/src/canvas/kinds/flow/FlowInputsEditor.tsx
+++ b/apps/agent-forge/src/canvas/kinds/flow/FlowInputsEditor.tsx
@@ -8,7 +8,7 @@ import type { ChangeEvent } from 'react';
 import { Plus, X } from 'lucide-react';
 import { Field } from '../../../ui/Field';
 import { Checkbox, Input, Select } from '../../../ui/controls';
-import type { FlowInputType, FlowInputVariable } from 'lousho/flows';
+import type { FlowInputType, FlowInputVariable } from '@linuxdevil/lousho/flows';
 import './flow.css';
 
 const INPUT_TYPES: FlowInputType[] = ['shortText', 'url', 'longText', 'number', 'json', 'fileBase64'];
diff --git a/apps/agent-forge/src/canvas/kinds/flow/FlowMetaSection.tsx b/apps/agent-forge/src/canvas/kinds/flow/FlowMetaSection.tsx
index b9c055282..6b3fcca0d 100644
--- a/apps/agent-forge/src/canvas/kinds/flow/FlowMetaSection.tsx
+++ b/apps/agent-forge/src/canvas/kinds/flow/FlowMetaSection.tsx
@@ -9,7 +9,7 @@ import { InspectorSection } from '../../../components/InspectorSection';
 import { Field } from '../../../ui/Field';
 import { Input, Textarea } from '../../../ui/controls';
 import { JsonField } from '../../fields/JsonField';
-import type { AgentFlow, FlowInputVariable } from 'lousho/flows';
+import type { AgentFlow, FlowInputVariable } from '@linuxdevil/lousho/flows';
 import type { KindFieldsProps } from '../index';
 import { FLOW_CODE_PATTERN } from './flowForm';
 import { FlowInputsEditor } from './FlowInputsEditor';
diff --git a/apps/agent-forge/src/canvas/kinds/flow/RunOptionsSection.tsx b/apps/agent-forge/src/canvas/kinds/flow/RunOptionsSection.tsx
index 5699cab06..b8c801498 100644
--- a/apps/agent-forge/src/canvas/kinds/flow/RunOptionsSection.tsx
+++ b/apps/agent-forge/src/canvas/kinds/flow/RunOptionsSection.tsx
@@ -6,7 +6,7 @@
  * object and deleted when Attempts is cleared; `timeoutMs` deletes on
  * empty.
  */
-import type { NodeRetry } from 'lousho/flows';
+import type { NodeRetry } from '@linuxdevil/lousho/flows';
 import { InspectorSection } from '../../../components/InspectorSection';
 import { OptionalNumberField } from '../../fields/OptionalNumberField';
 import type { KindFieldsProps } from '../index';
diff --git a/apps/agent-forge/src/canvas/kinds/mcp/OAuthForm.tsx b/apps/agent-forge/src/canvas/kinds/mcp/OAuthForm.tsx
index 8b2f5c723..28465d1b5 100644
--- a/apps/agent-forge/src/canvas/kinds/mcp/OAuthForm.tsx
+++ b/apps/agent-forge/src/canvas/kinds/mcp/OAuthForm.tsx
@@ -6,7 +6,7 @@
 import type { ChangeEvent } from 'react';
 import { Field } from '../../../ui/Field';
 import { Input, Switch } from '../../../ui/controls';
-import type { SecretRef } from '../../../graph/v2/specTypes';
+import type { SecretRef } from '../../../../shared/wireTypes';
 import { SecretRefField } from '../../fields/SecretRefField';
 import { StringListField } from '../../fields/StringListField';
 import type { KindFieldsProps } from '../index';
diff --git a/apps/agent-forge/src/canvas/kinds/subagent.tsx b/apps/agent-forge/src/canvas/kinds/subagent.tsx
index c8f29dc5f..06bd4e8c0 100644
--- a/apps/agent-forge/src/canvas/kinds/subagent.tsx
+++ b/apps/agent-forge/src/canvas/kinds/subagent.tsx
@@ -10,7 +10,7 @@
 import { Users } from 'lucide-react';
 import { uniqueName } from '../../graph/v2/nodeIds';
 import { subagentSiblingKeys } from '../../graph/v2/order';
-import type { SecretRef } from '../../graph/v2/specTypes';
+import type { SecretRef } from '../../../shared/wireTypes';
 import type { NodeOfKind } from '../../graph/v2/types';
 import { SubagentFields } from './subagent/SubagentFields';
 import { urlHost } from './urlHost';
diff --git a/apps/agent-forge/src/canvas/kinds/subagent/SubagentFields.tsx b/apps/agent-forge/src/canvas/kinds/subagent/SubagentFields.tsx
index dfcbf50fd..d22a09109 100644
--- a/apps/agent-forge/src/canvas/kinds/subagent/SubagentFields.tsx
+++ b/apps/agent-forge/src/canvas/kinds/subagent/SubagentFields.tsx
@@ -12,7 +12,7 @@ import { Field } from '../../../ui/Field';
 import { Input, Select, Textarea } from '../../../ui/controls';
 import { remoteUrlOk, SUBAGENT_KEY_PATTERN } from '../../../graph/v2/kinds/subagent';
 import { subagentEntryKey } from '../../../graph/v2/order';
-import type { SecretRef } from '../../../graph/v2/specTypes';
+import type { SecretRef } from '../../../../shared/wireTypes';
 import type { NodeOfKind, SubagentNodeData } from '../../../graph/v2/types';
 import { ChoiceField } from '../../fields/ChoiceField';
 import { SecretRefField } from '../../fields/SecretRefField';
diff --git a/apps/agent-forge/src/canvas/templates.ts b/apps/agent-forge/src/canvas/templates.ts
index f1a81afa9..c98544768 100644
--- a/apps/agent-forge/src/canvas/templates.ts
+++ b/apps/agent-forge/src/canvas/templates.ts
@@ -1,4 +1,4 @@
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { specToGraph } from '../graph/v2/specToGraph';
 import type { Graph } from '../graph/v2/types';
 
diff --git a/apps/agent-forge/src/components/debug/forkReplay.tsx b/apps/agent-forge/src/components/debug/forkReplay.tsx
index 2f2095807..6ddccb210 100644
--- a/apps/agent-forge/src/components/debug/forkReplay.tsx
+++ b/apps/agent-forge/src/components/debug/forkReplay.tsx
@@ -1,5 +1,5 @@
 import { useEffect, useState } from 'react';
-import type { TrajectoryStep } from 'lousho';
+import type { TrajectoryStep } from '@linuxdevil/lousho';
 import { runtimeClient } from '../../runtime/runtimeClient';
 import { errorMessage } from '../errorMessage';
 import type { ForkRunRequest, RunComparisonPayload, RunHistoryStep } from '../../../shared/wireTypes';
diff --git a/apps/agent-forge/src/graph/v2/__tests__/types.test.ts b/apps/agent-forge/src/graph/v2/__tests__/types.test.ts
index 31d8e5e8d..7dff7d63d 100644
--- a/apps/agent-forge/src/graph/v2/__tests__/types.test.ts
+++ b/apps/agent-forge/src/graph/v2/__tests__/types.test.ts
@@ -34,12 +34,12 @@ import type {
   McpServerSpec,
   MemorySpec,
   PermissionRuleSpec,
-  SecretRef,
   SkillRef,
   SubagentSpec,
   ToolRef,
   TriggerSpec,
 } from '../specTypes';
+import type { SecretRef } from '../../../../shared/wireTypes';
 
 describe('spec key coverage', () => {
   /**
diff --git a/apps/agent-forge/src/graph/v2/schemaIssues.ts b/apps/agent-forge/src/graph/v2/schemaIssues.ts
index 2c37ad76d..c3daee56d 100644
--- a/apps/agent-forge/src/graph/v2/schemaIssues.ts
+++ b/apps/agent-forge/src/graph/v2/schemaIssues.ts
@@ -6,7 +6,7 @@
  * schema's own complaints (bad enums, patterns, missing required fields,
  * and the "not supported yet" placeholders, which become warnings).
  */
-import { agentSpecV2Schema, UNSUPPORTED_PREFIX } from 'lousho/spec';
+import { agentSpecV2Schema, UNSUPPORTED_PREFIX } from '@linuxdevil/lousho/spec';
 import type { AgentSpecV2 } from './specTypes';
 import type { Problem } from './types';
 
diff --git a/apps/agent-forge/src/graph/v2/specTypes.ts b/apps/agent-forge/src/graph/v2/specTypes.ts
index 85fa96e12..7bf012d84 100644
--- a/apps/agent-forge/src/graph/v2/specTypes.ts
+++ b/apps/agent-forge/src/graph/v2/specTypes.ts
@@ -3,16 +3,17 @@
  * every `graph/v2` module imports spec types from here, so the SDK import
  * path (and any SDK renames) lives in exactly one file.
  *
- * The SDK's `lousho/spec` subpath only carries browser-safe exports, so the
- * spec v2 types come from the SDK source tree directly — the same deviation
- * `src/persistence/importExport.ts` already makes and documents.
+ * The `@linuxdevil/lousho/spec` subpath carries every spec v2 type and the
+ * Inspector's value lists Studio needs (the browser-safe `src/spec/v2`
+ * layer), so every import here is a public SDK export — no source-tree
+ * paths (PLAN §19.7, enforced by lint:imports).
  */
 
-/** The flow the run follows (from the published `lousho/flows` subpath). */
-export type { AgentFlow } from 'lousho/flows';
+/** The flow the run follows (from the published `@linuxdevil/lousho/flows` subpath). */
+export type { AgentFlow } from '@linuxdevil/lousho/flows';
 
 /** The agent spec the canvas edits, plus its subagent union. */
-export type { AgentSpecV2, SubagentSpec } from 'lousho/spec';
+export type { AgentSpecV2, SubagentSpec } from '@linuxdevil/lousho/spec';
 /**
  * One `spec.tools` entry, plus the SDK's own lists for the tool Inspector:
  * the credential keys each integration takes (`INTEGRATION_CREDENTIALS`),
@@ -20,54 +21,52 @@ export type { AgentSpecV2, SubagentSpec } from 'lousho/spec';
  * pattern a `ToolRef`'s `id` follows (`SPEC_ID_PATTERN`). Value exports
  * alongside the type exports — the seam is the same.
  */
-export type { ToolRef, IntegrationName, OpenApiToolRefOptions } from 'lousho/spec';
-export { INTEGRATION_CREDENTIALS, SECRET_CREDENTIALS } from 'lousho/spec';
-export { isSafeRelativePath, SPEC_ID_PATTERN } from 'lousho/spec';
-/** A reference to an env var or a named Studio secret. */
-export type { SecretRef } from 'lousho/spec';
+export type { ToolRef, IntegrationName, OpenApiToolRefOptions } from '@linuxdevil/lousho/spec';
+export { INTEGRATION_CREDENTIALS, SECRET_CREDENTIALS } from '@linuxdevil/lousho/spec';
+export { isSafeRelativePath, SPEC_ID_PATTERN } from '@linuxdevil/lousho/spec';
 /** One `spec.skills` entry. */
-export type { SkillRef } from 'lousho/spec';
+export type { SkillRef } from '@linuxdevil/lousho/spec';
 /** One `spec.memory` entry, plus its `scope`/`provider` union members for the Inspector's sub-forms. */
-export type { MemorySpec, MemoryScopeSpec, MemoryProviderSpec } from 'lousho/spec';
+export type { MemorySpec, MemoryScopeSpec, MemoryProviderSpec } from '@linuxdevil/lousho/spec';
 /**
  * One `spec.mcpServers` value. The SDK names it `McpServerSpecV2`; the canvas
  * uses the shorter `McpServerSpec` everywhere, aliased once here.
  */
-export type { McpServerSpecV2 as McpServerSpec } from 'lousho/spec';
+export type { McpServerSpecV2 as McpServerSpec } from '@linuxdevil/lousho/spec';
 /** The `mcpServers` record-key pattern the SDK enforces (`^[A-Za-z0-9_-]{1,64}$`). */
-export { MCP_SERVER_NAME } from 'lousho/spec';
+export { MCP_SERVER_NAME } from '@linuxdevil/lousho/spec';
 /** The longest approval deadline the spec schema accepts (`approvalTtlMs`/`ttlMs`), in ms. */
-export { MAX_APPROVAL_TTL_MS } from 'lousho/spec';
+export { MAX_APPROVAL_TTL_MS } from '@linuxdevil/lousho/spec';
 /** One `spec.handoffs` entry. */
-export type { HandoffSpec } from 'lousho/spec';
+export type { HandoffSpec } from '@linuxdevil/lousho/spec';
 /**
  * One `spec.guardrails` entry, plus the `guardrailSidesOf` helper the
  * Inspector and the kind validator share to read `on` (a side or a side
  * list; absent means input and output).
  */
-export type { GuardrailSpec } from 'lousho/spec';
-export { guardrailSidesOf, REWRITABLE_GUARDRAILS } from 'lousho/spec';
+export type { GuardrailSpec } from '@linuxdevil/lousho/spec';
+export { guardrailSidesOf, REWRITABLE_GUARDRAILS } from '@linuxdevil/lousho/spec';
 /** One `spec.permissions` entry. */
-export type { PermissionRuleSpec } from 'lousho/spec';
+export type { PermissionRuleSpec } from '@linuxdevil/lousho/spec';
 /** One `spec.hooks` entry, plus the `inline` member's shape for the hook Inspector. */
-export type { HookSpec, InlineHookSpec } from 'lousho/spec';
+export type { HookSpec, InlineHookSpec } from '@linuxdevil/lousho/spec';
 /** The agent's `spec.output` section (`jsonSchema` plus `promptSchema`/`responseFormat`). */
-export type { OutputSpecV2 } from 'lousho/spec';
+export type { OutputSpecV2 } from '@linuxdevil/lousho/spec';
 /** The executable `AgentFlow` step types (excludes editor-only shapes) — the flow kind's validation list. */
-export { EXECUTABLE_TYPES } from 'lousho/spec';
+export { EXECUTABLE_TYPES } from '@linuxdevil/lousho/spec';
 /**
  * One `spec.triggers` entry, plus the channel union and the required
  * `secrets` keys per channel kind (`CHANNEL_SECRET_KEYS`) — the SDK's own
  * list, shared by the trigger Inspector's prefill and `triggerRules`.
  */
-export type { TriggerSpec, ChannelKind } from 'lousho/spec';
-export { CHANNEL_SECRET_KEYS } from 'lousho/spec';
+export type { TriggerSpec, ChannelKind } from '@linuxdevil/lousho/spec';
+export { CHANNEL_SECRET_KEYS } from '@linuxdevil/lousho/spec';
 
 /** One `spec.abortListeners` entry — the SDK's own type (R03a), re-exported like the trigger types. */
-export type { AbortListenerSpec } from 'lousho/spec';
+export type { AbortListenerSpec } from '@linuxdevil/lousho/spec';
 
 /**
  * The `spec.evals` gate types (X01a): the SDK's own `evals` section, shared
  * with the publish gate runner the same way the trigger/abort types are.
  */
-export type { EvalGateSpec } from 'lousho/spec';
+export type { EvalGateSpec } from '@linuxdevil/lousho/spec';
diff --git a/apps/agent-forge/src/persistence/AgentStore.ts b/apps/agent-forge/src/persistence/AgentStore.ts
index 28b050011..13a813b17 100644
--- a/apps/agent-forge/src/persistence/AgentStore.ts
+++ b/apps/agent-forge/src/persistence/AgentStore.ts
@@ -1,4 +1,4 @@
-import type { AgentSpec, AgentSpecV2 } from 'lousho';
+import type { AgentSpec, AgentSpecV2 } from '@linuxdevil/lousho';
 import type { AgentListItem, AgentRecord, CanvasLayout } from '../../shared/wireTypes';
 
 /**
diff --git a/apps/agent-forge/src/persistence/HttpAgentStore.ts b/apps/agent-forge/src/persistence/HttpAgentStore.ts
index 7fcd1a9d2..98989561f 100644
--- a/apps/agent-forge/src/persistence/HttpAgentStore.ts
+++ b/apps/agent-forge/src/persistence/HttpAgentStore.ts
@@ -1,4 +1,4 @@
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { AgentListItem, AgentRecord, CanvasLayout } from '../../shared/wireTypes';
 import type { AgentStore } from './AgentStore';
 
diff --git a/apps/agent-forge/src/persistence/__tests__/HttpAgentStore.test.ts b/apps/agent-forge/src/persistence/__tests__/HttpAgentStore.test.ts
index c5963e7c7..230ee8e11 100644
--- a/apps/agent-forge/src/persistence/__tests__/HttpAgentStore.test.ts
+++ b/apps/agent-forge/src/persistence/__tests__/HttpAgentStore.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from 'vitest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { HttpAgentStore, type AgentApi } from '../HttpAgentStore';
 import type { AgentListItem, AgentMeta, AgentRecord, CanvasLayout } from '../../../shared/wireTypes';
 
diff --git a/apps/agent-forge/src/persistence/__tests__/fsAgentStore.test.ts b/apps/agent-forge/src/persistence/__tests__/fsAgentStore.test.ts
index f3efdf9f5..2424f2220 100644
--- a/apps/agent-forge/src/persistence/__tests__/fsAgentStore.test.ts
+++ b/apps/agent-forge/src/persistence/__tests__/fsAgentStore.test.ts
@@ -3,7 +3,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import type { AgentSpec, AgentSpecV2 } from 'lousho';
+import type { AgentSpec, AgentSpecV2 } from '@linuxdevil/lousho';
 import { AgentRepo } from '../../../server/storage/agentRepo';
 import { createFsAgentStore } from '../fsAgentStore';
 
diff --git a/apps/agent-forge/src/persistence/__tests__/importExport.test.ts b/apps/agent-forge/src/persistence/__tests__/importExport.test.ts
index a84680837..e0d348850 100644
--- a/apps/agent-forge/src/persistence/__tests__/importExport.test.ts
+++ b/apps/agent-forge/src/persistence/__tests__/importExport.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { downloadSpec, importSpecFile, parseSpecText, serializeSpec } from '../importExport';
 
 const spec: AgentSpecV2 = {
diff --git a/apps/agent-forge/src/persistence/fsAgentStore.ts b/apps/agent-forge/src/persistence/fsAgentStore.ts
index 644266cd5..093013a23 100644
--- a/apps/agent-forge/src/persistence/fsAgentStore.ts
+++ b/apps/agent-forge/src/persistence/fsAgentStore.ts
@@ -1,4 +1,4 @@
-import type { AgentSpec } from 'lousho';
+import type { AgentSpec } from '@linuxdevil/lousho';
 import type { LegacyAgentStore, LegacyAgentStoreEntry } from './AgentStore';
 import { AgentRepo } from '../../server/storage/agentRepo';
 import { mergeLegacySave, toLegacySpec } from '../../server/storage/legacySpec';
diff --git a/apps/agent-forge/src/persistence/importExport.ts b/apps/agent-forge/src/persistence/importExport.ts
index 6bc0ad895..640d72290 100644
--- a/apps/agent-forge/src/persistence/importExport.ts
+++ b/apps/agent-forge/src/persistence/importExport.ts
@@ -1,9 +1,9 @@
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
-import type { AgentSpecV2 } from 'lousho/spec';
+import type { AgentSpecV2 } from '@linuxdevil/lousho/spec';
 // `lousho/spec` is the SDK's browser-safe spec entry (schema, types and
 // pure helpers only, no Node-only deps), so this value import is safe in
 // the Vite/browser bundle where the package root is not.
-import { agentSpecV2Schema } from 'lousho/spec';
+import { agentSpecV2Schema } from '@linuxdevil/lousho/spec';
 
 export type ExportFormat = 'yaml' | 'json';
 
diff --git a/apps/agent-forge/src/runtime/runtimeClient.ts b/apps/agent-forge/src/runtime/runtimeClient.ts
index 2ba8c60fe..45d277a25 100644
--- a/apps/agent-forge/src/runtime/runtimeClient.ts
+++ b/apps/agent-forge/src/runtime/runtimeClient.ts
@@ -6,7 +6,7 @@
  * so the two can evolve together without every component knowing the HTTP
  * details.
  */
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type {
   AddWorkspaceRequest,
   AgentListItem,
@@ -55,6 +55,7 @@ import type {
   ProviderKeyStatus,
   PortabilityAnalysis,
   Requirement,
+  EjectResult,
   RunComparisonPayload,
   RunHistoryPayload,
   SecretStatus,
@@ -1064,6 +1065,18 @@ class RuntimeClient implements AgentApi {
     });
   }
 
+  /**
+   * `POST /agents/:id/eject` (A08b): writes the agent-directory form to
+   * `agents/<id>/` in this workspace. `overwrite` resends after the 409
+   * "already exists" answer; the `EjectResult` lists what was written.
+   */
+  async ejectAgent(agentId: string, overwrite = false): Promise<EjectResult> {
+    return this.request<EjectResult>(`/agents/${encodeURIComponent(agentId)}/eject`, {
+      method: 'POST',
+      body: JSON.stringify({ overwrite }),
+    });
+  }
+
   /**
    * Subscribes to `WS /agents/:id/stream`. Returns an unsubscribe function.
    * Reconnects are NOT handled here - a dropped connection just stops
diff --git a/apps/agent-forge/src/screens/agentDetail/AgentOverviewTab.tsx b/apps/agent-forge/src/screens/agentDetail/AgentOverviewTab.tsx
index 5f8156d14..827719888 100644
--- a/apps/agent-forge/src/screens/agentDetail/AgentOverviewTab.tsx
+++ b/apps/agent-forge/src/screens/agentDetail/AgentOverviewTab.tsx
@@ -1,6 +1,6 @@
 import { ChevronRight, TriangleAlert } from 'lucide-react';
 import { useEffect, useState, type ReactNode } from 'react';
-import type { AgentSpecV2 } from 'lousho/spec';
+import type { AgentSpecV2 } from '@linuxdevil/lousho/spec';
 
 import type { AgentMeta, ChannelTriggerStatus, TraceSummaryPayload } from '../../../shared/wireTypes';
 import { agentTabPath, BUILT_AGENT_TABS } from '../agents/agentTabs';
diff --git a/apps/agent-forge/src/screens/agentDetail/__tests__/AgentOverviewTab.test.tsx b/apps/agent-forge/src/screens/agentDetail/__tests__/AgentOverviewTab.test.tsx
index 64e929f3b..a4454b7e6 100644
--- a/apps/agent-forge/src/screens/agentDetail/__tests__/AgentOverviewTab.test.tsx
+++ b/apps/agent-forge/src/screens/agentDetail/__tests__/AgentOverviewTab.test.tsx
@@ -3,7 +3,7 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { AgentRecord, Requirement, TraceSummaryPayload } from '../../../../shared/wireTypes';
 import { render } from '../../../ui/__tests__/render';
-import type { AgentSpecV2 } from 'lousho/spec';
+import type { AgentSpecV2 } from '@linuxdevil/lousho/spec';
 
 const mocks = vi.hoisted(() => ({ listTraces: vi.fn(), channelTriggerStatus: vi.fn() }));
 
diff --git a/apps/agent-forge/src/screens/agentDetail/__tests__/DraftCard.test.tsx b/apps/agent-forge/src/screens/agentDetail/__tests__/DraftCard.test.tsx
index f6562cdbd..96cdb5510 100644
--- a/apps/agent-forge/src/screens/agentDetail/__tests__/DraftCard.test.tsx
+++ b/apps/agent-forge/src/screens/agentDetail/__tests__/DraftCard.test.tsx
@@ -2,7 +2,7 @@ import { act } from 'react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { AgentRecord, DraftAutoReview, DraftView, SpecChange } from '../../../../shared/wireTypes';
-import type { AgentSpecV2 } from 'lousho/spec';
+import type { AgentSpecV2 } from '@linuxdevil/lousho/spec';
 import { render } from '../../../ui/__tests__/render';
 import { ToastProvider } from '../../../ui/Toast';
 
diff --git a/apps/agent-forge/src/screens/agentDetail/__tests__/SuggestionsTab.test.tsx b/apps/agent-forge/src/screens/agentDetail/__tests__/SuggestionsTab.test.tsx
index 835b78632..7af7b970c 100644
--- a/apps/agent-forge/src/screens/agentDetail/__tests__/SuggestionsTab.test.tsx
+++ b/apps/agent-forge/src/screens/agentDetail/__tests__/SuggestionsTab.test.tsx
@@ -2,7 +2,7 @@ import { act } from 'react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { AgentRecord, DraftView, PromptSuggestion, StudioEvent } from '../../../../shared/wireTypes';
-import type { AgentSpecV2 } from 'lousho/spec';
+import type { AgentSpecV2 } from '@linuxdevil/lousho/spec';
 import { render } from '../../../ui/__tests__/render';
 import { ToastProvider } from '../../../ui/Toast';
 
diff --git a/apps/agent-forge/src/screens/agentDetail/__tests__/VersionsTab.test.tsx b/apps/agent-forge/src/screens/agentDetail/__tests__/VersionsTab.test.tsx
index 41e4e9889..873466444 100644
--- a/apps/agent-forge/src/screens/agentDetail/__tests__/VersionsTab.test.tsx
+++ b/apps/agent-forge/src/screens/agentDetail/__tests__/VersionsTab.test.tsx
@@ -2,7 +2,7 @@ import { act } from 'react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { AgentRecord, StudioEvent, VersionListItem } from '../../../../shared/wireTypes';
-import type { AgentSpecV2 } from 'lousho/spec';
+import type { AgentSpecV2 } from '@linuxdevil/lousho/spec';
 import { render } from '../../../ui/__tests__/render';
 import { ToastProvider } from '../../../ui/Toast';
 
diff --git a/apps/agent-forge/src/screens/agentDetail/__tests__/overviewModel.test.ts b/apps/agent-forge/src/screens/agentDetail/__tests__/overviewModel.test.ts
index 39b9de574..a75d77a0b 100644
--- a/apps/agent-forge/src/screens/agentDetail/__tests__/overviewModel.test.ts
+++ b/apps/agent-forge/src/screens/agentDetail/__tests__/overviewModel.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import type { AgentSpecV2 } from 'lousho/spec';
+import type { AgentSpecV2 } from '@linuxdevil/lousho/spec';
 
 import type { Requirement } from '../../../../shared/wireTypes';
 import { capabilityRows, missingRequirements, permissionRuleText, safetySummary, triggerLine } from '../overviewModel';
diff --git a/apps/agent-forge/src/screens/agentDetail/code/CodeTab.tsx b/apps/agent-forge/src/screens/agentDetail/code/CodeTab.tsx
index a3326bb48..4165811c5 100644
--- a/apps/agent-forge/src/screens/agentDetail/code/CodeTab.tsx
+++ b/apps/agent-forge/src/screens/agentDetail/code/CodeTab.tsx
@@ -4,7 +4,7 @@ import { stringify as stringifyYaml } from 'yaml';
 // `lousho/spec` is the SDK's browser-safe spec entry (S23): `specToCode`
 // (S18) and `specToAgentDir` (S19) are both pure renderers, so the Code tab
 // generates every view in the browser with no server round-trip.
-import { specToAgentDir, specToCode, type AgentSpecV2 } from 'lousho/spec';
+import { specToAgentDir, specToCode, type AgentSpecV2 } from '@linuxdevil/lousho/spec';
 
 import { errorMessage } from '../../../components/errorMessage';
 import { downloadText } from '../../../persistence/importExport';
@@ -14,6 +14,7 @@ import { EmptyState } from '../../../ui/EmptyState';
 import { useToast } from '../../../ui/Toast';
 import { useAgentDetail } from '../AgentDetailContext';
 import { ServeCard } from '../ServeCard';
+import { EjectToProject } from './EjectToProject';
 import { buildTree, CODE_VIEW_LABELS, downloadName, parseCodeView, type CodeView, type TreeNode } from './codeViews';
 import '../../../ui/filterBar.css';
 import './code.css';
@@ -287,6 +288,7 @@ export function CodeTab(): JSX.Element {
             <Download size={14} strokeWidth={1.75} aria-hidden="true" />
             Download
           </button>
+          <EjectToProject agentId={record.id} spec={record.spec} updatedAt={record.updatedAt} />
         </div>
       </div>
       <p className="code-note">Generated from the spec. Read-only — edit on the canvas or in Configure.</p>
diff --git a/apps/agent-forge/src/screens/agentDetail/code/EjectToProject.tsx b/apps/agent-forge/src/screens/agentDetail/code/EjectToProject.tsx
new file mode 100644
index 000000000..42a59e50c
--- /dev/null
+++ b/apps/agent-forge/src/screens/agentDetail/code/EjectToProject.tsx
@@ -0,0 +1,98 @@
+import { useMemo, useState, type JSX } from 'react';
+import { FolderOutput } from 'lucide-react';
+import { specToAgentDir, type AgentSpecV2 } from '@linuxdevil/lousho/spec';
+
+import { errorMessage } from '../../../components/errorMessage';
+import { runtimeClient, RuntimeApiError } from '../../../runtime/runtimeClient';
+import { ConfirmDialog } from '../../../ui/Dialog';
+import { useToast } from '../../../ui/Toast';
+import { Checkbox } from '../../../ui/controls';
+
+interface EjectToProjectProps {
+  agentId: string;
+  spec: AgentSpecV2;
+  /** The spec's change signal (`record.updatedAt`): the file count memoizes on it. */
+  updatedAt: string;
+}
+
+/**
+ * The "Eject to project" action (A08b): POSTs `/agents/:id/eject` after a
+ * confirmation that states the generated file count. A 409
+ * LOUSHO_EJECT_EXISTS keeps the dialog open, lists the count and offers an
+ * overwrite checkbox that resends with `overwrite: true`.
+ */
+export function EjectToProject({ agentId, spec, updatedAt }: EjectToProjectProps): JSX.Element {
+  const toast = useToast();
+  const [open, setOpen] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string>();
+  const [exists, setExists] = useState<number>();
+  const [overwrite, setOverwrite] = useState(false);
+
+  // The dialog's file count: the same pure generator the dir view runs.
+  // A spec that cannot render as a directory shows 0 - the server reports
+  // the real error on confirm.
+  const fileCount = useMemo(() => {
+    try {
+      return specToAgentDir(spec).files.length;
+    } catch {
+      return 0;
+    }
+  }, [updatedAt]);
+
+  const close = () => {
+    setOpen(false);
+    setError(undefined);
+    setExists(undefined);
+    setOverwrite(false);
+  };
+
+  const confirm = async () => {
+    setBusy(true);
+    setError(undefined);
+    try {
+      await runtimeClient.ejectAgent(agentId, overwrite);
+      close();
+      toast.show({ message: `Ejected to agents/${agentId}/`, tone: 'success' });
+    } catch (err) {
+      setError(errorMessage(err));
+      if (err instanceof RuntimeApiError && err.status === 409 && err.code === 'LOUSHO_EJECT_EXISTS') {
+        const files = (err.details as { files?: unknown } | undefined)?.files;
+        setExists(Array.isArray(files) ? files.length : 0);
+      }
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <>
+      <button type="button" className="btn btn-sm" onClick={() => setOpen(true)}>
+        <FolderOutput size={14} strokeWidth={1.75} aria-hidden="true" />
+        Eject to project
+      </button>
+      <ConfirmDialog
+        open={open}
+        tone="primary"
+        title="Eject to project?"
+        description={`Writes ${fileCount} files to agents/${agentId}/ in this workspace. The Studio keeps editing .lousho/agents/${agentId}.yaml; the ejected copy won’t follow later changes.`}
+        confirmLabel="Eject"
+        pendingLabel="Ejecting…"
+        pending={busy}
+        error={error}
+        onConfirm={() => void confirm()}
+        onCancel={close}
+      >
+        {exists !== undefined ? (
+          <Checkbox
+            label="Overwrite existing files"
+            description={`${exists} files will be replaced.`}
+            checked={overwrite}
+            disabled={busy}
+            onChange={(event) => setOverwrite(event.target.checked)}
+          />
+        ) : null}
+      </ConfirmDialog>
+    </>
+  );
+}
diff --git a/apps/agent-forge/src/screens/agentDetail/code/__tests__/CodeTab.test.tsx b/apps/agent-forge/src/screens/agentDetail/code/__tests__/CodeTab.test.tsx
index 8f208ab97..fafa99214 100644
--- a/apps/agent-forge/src/screens/agentDetail/code/__tests__/CodeTab.test.tsx
+++ b/apps/agent-forge/src/screens/agentDetail/code/__tests__/CodeTab.test.tsx
@@ -2,7 +2,7 @@ import { act } from 'react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { AgentRecord } from '../../../../../shared/wireTypes';
-import type { AgentSpecV2 } from 'lousho/spec';
+import type { AgentSpecV2 } from '@linuxdevil/lousho/spec';
 import { parseHash } from '../../../../router/router';
 import { render } from '../../../../ui/__tests__/render';
 import { ToastProvider } from '../../../../ui/Toast';
@@ -20,7 +20,7 @@ const mocks = vi.hoisted(() => ({
 
 // The Code tab calls the real SDK generators in the browser; here they are
 // stubbed so the assertions are about the tab, not the generators.
-vi.mock('lousho/spec', () => ({
+vi.mock('@linuxdevil/lousho/spec', () => ({
   specToCode: () => mocks.specToCode(),
   specToAgentDir: () => mocks.specToAgentDir(),
 }));
@@ -28,21 +28,26 @@ vi.mock('lousho/spec', () => ({
 // The Serve card (X02b) loads `/agents/:id/serve` on mount and subscribes
 // to `/events`; the tab's assertions are about the code views, so both are
 // stubbed to an unpublished, disabled status.
-vi.mock('../../../../runtime/runtimeClient', () => ({
-  runtimeClient: {
-    getServe: vi.fn(async () => ({
-      agentId: 'support-bot',
-      enabled: false,
-      allowedOrigins: [],
-      publishedVersion: null,
-      tokenMasked: 'tok…tok',
-      baseUrl: '/serve/support-bot',
-    })),
-    putServe: vi.fn(),
-    serveToken: vi.fn(),
-    rotateServeToken: vi.fn(),
-  },
-}));
+vi.mock('../../../../runtime/runtimeClient', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../../../../runtime/runtimeClient')>();
+  return {
+    ...actual,
+    runtimeClient: {
+      getServe: vi.fn(async () => ({
+        agentId: 'support-bot',
+        enabled: false,
+        allowedOrigins: [],
+        publishedVersion: null,
+        tokenMasked: 'tok…tok',
+        baseUrl: '/serve/support-bot',
+      })),
+      putServe: vi.fn(),
+      serveToken: vi.fn(),
+      rotateServeToken: vi.fn(),
+      ejectAgent: vi.fn(),
+    },
+  };
+});
 
 vi.mock('../../../../state/useStudioEvents', () => ({
   useStudioEvents: () => {},
@@ -50,6 +55,7 @@ vi.mock('../../../../state/useStudioEvents', () => ({
 
 import { AgentDetailContext } from '../../AgentDetailContext';
 import { CodeTab } from '../CodeTab';
+import { runtimeClient, RuntimeApiError } from '../../../../runtime/runtimeClient';
 
 function record(): AgentRecord {
   return {
@@ -261,4 +267,72 @@ describe('CodeTab', () => {
     expect(host.querySelector('pre.code-view')?.textContent).toContain('name: Support bot');
     expect(host.querySelector('.empty-state-title')).toBeNull();
   });
+
+  it('Eject to project opens the dialog with the generated file count and posts on confirm', async () => {
+    const eject = vi.spyOn(runtimeClient, 'ejectAgent').mockResolvedValue({ dir: 'agents/support-bot', files: ['agent.yaml'] });
+    const host = renderTab();
+    await flush();
+
+    const ejectButton = [...host.querySelectorAll<HTMLButtonElement>('button')].find((b) =>
+      b.textContent?.includes('Eject to project'),
+    )!;
+    act(() => ejectButton.click());
+    await flush();
+
+    const dialog = document.querySelector<HTMLElement>('.dialog, [role="dialog"], [role="alertdialog"]')!;
+    expect(dialog.textContent).toContain('Writes 2 files to agents/support-bot/');
+
+    const confirm = [...dialog.querySelectorAll<HTMLButtonElement>('button')].find((b) =>
+      b.textContent?.includes('Eject'),
+    )!;
+    act(() => confirm.click());
+    await flush();
+
+    expect(eject).toHaveBeenCalledWith('support-bot', false);
+    expect(dialog.isConnected).toBe(false);
+    expect(host.querySelector('.toast-message')?.textContent).toBe('Ejected to agents/support-bot/');
+    eject.mockRestore();
+  });
+
+  it('a 409 LOUSHO_EJECT_EXISTS shows the overwrite checkbox and resends with overwrite', async () => {
+    const err = new RuntimeApiError('agents/support-bot/ already exists.', 409, 'LOUSHO_EJECT_EXISTS', {
+      files: ['agent.yaml', 'prompts/system.md'],
+    });
+    const eject = vi
+      .spyOn(runtimeClient, 'ejectAgent')
+      .mockRejectedValueOnce(err)
+      .mockResolvedValueOnce({ dir: 'agents/support-bot', files: ['agent.yaml'] });
+    const host = renderTab();
+    await flush();
+
+    const ejectButton = [...host.querySelectorAll<HTMLButtonElement>('button')].find((b) =>
+      b.textContent?.includes('Eject to project'),
+    )!;
+    act(() => ejectButton.click());
+    await flush();
+
+    const confirm = [...document.querySelectorAll<HTMLButtonElement>('button')].find((b) =>
+      b.textContent?.trim() === 'Eject',
+    )!;
+    act(() => confirm.click());
+    await flush();
+
+    expect(eject).toHaveBeenLastCalledWith('support-bot', false);
+    const checkbox = document.querySelector<HTMLInputElement>('input[type="checkbox"]')!;
+    expect(checkbox).not.toBeNull();
+    expect(document.body.textContent).toContain('agents/support-bot/ already exists.');
+
+    act(() => {
+      checkbox.click();
+    });
+    await flush();
+    const confirmAgain = [...document.querySelectorAll<HTMLButtonElement>('button')].find((b) =>
+      b.textContent?.trim() === 'Eject',
+    )!;
+    act(() => confirmAgain.click());
+    await flush();
+
+    expect(eject).toHaveBeenLastCalledWith('support-bot', true);
+    eject.mockRestore();
+  });
 });
diff --git a/apps/agent-forge/src/screens/agentDetail/configure/ConfigureTab.tsx b/apps/agent-forge/src/screens/agentDetail/configure/ConfigureTab.tsx
index 03aaa830f..172946e5f 100644
--- a/apps/agent-forge/src/screens/agentDetail/configure/ConfigureTab.tsx
+++ b/apps/agent-forge/src/screens/agentDetail/configure/ConfigureTab.tsx
@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
-import { agentSpecV2JsonSchema } from 'lousho/spec';
+import { agentSpecV2JsonSchema } from '@linuxdevil/lousho/spec';
 
 import { useQueryState } from '../../../router/useRoute';
 import { useAppState } from '../../../state/AppState';
diff --git a/apps/agent-forge/src/screens/agentDetail/configure/__tests__/ConfigureTab.test.tsx b/apps/agent-forge/src/screens/agentDetail/configure/__tests__/ConfigureTab.test.tsx
index 6fa7094c2..47344bbf5 100644
--- a/apps/agent-forge/src/screens/agentDetail/configure/__tests__/ConfigureTab.test.tsx
+++ b/apps/agent-forge/src/screens/agentDetail/configure/__tests__/ConfigureTab.test.tsx
@@ -2,7 +2,7 @@ import { act, useCallback, useState } from 'react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { AgentRecord } from '../../../../../shared/wireTypes';
-import type { AgentSpecV2 } from 'lousho/spec';
+import type { AgentSpecV2 } from '@linuxdevil/lousho/spec';
 import { render } from '../../../../ui/__tests__/render';
 import { ToastProvider } from '../../../../ui/Toast';
 
diff --git a/apps/agent-forge/src/screens/agentDetail/configure/__tests__/sections.test.ts b/apps/agent-forge/src/screens/agentDetail/configure/__tests__/sections.test.ts
index 8882c9bca..8d7e6675b 100644
--- a/apps/agent-forge/src/screens/agentDetail/configure/__tests__/sections.test.ts
+++ b/apps/agent-forge/src/screens/agentDetail/configure/__tests__/sections.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 
-import { agentSpecV2JsonSchema, type AgentSpecV2 } from 'lousho/spec';
+import { agentSpecV2JsonSchema, type AgentSpecV2 } from '@linuxdevil/lousho/spec';
 
 import type { JsonSchema } from '../../../../ui/schemaForm/types';
 import {
diff --git a/apps/agent-forge/src/screens/agentDetail/configure/sections.ts b/apps/agent-forge/src/screens/agentDetail/configure/sections.ts
index e3b890c1e..ee6814097 100644
--- a/apps/agent-forge/src/screens/agentDetail/configure/sections.ts
+++ b/apps/agent-forge/src/screens/agentDetail/configure/sections.ts
@@ -4,7 +4,7 @@
  * SchemaForm draws, and the dirty bookkeeping that compares the draft
  * against the saved spec section by section.
  */
-import type { AgentSpecV2 } from 'lousho/spec';
+import type { AgentSpecV2 } from '@linuxdevil/lousho/spec';
 
 import { stableStringify } from '../../../../shared/stableJson';
 import type { JsonSchema } from '../../../ui/schemaForm/types';
diff --git a/apps/agent-forge/src/screens/agentDetail/configure/useConfigureDraft.ts b/apps/agent-forge/src/screens/agentDetail/configure/useConfigureDraft.ts
index 18a251ffb..c4f2f3d09 100644
--- a/apps/agent-forge/src/screens/agentDetail/configure/useConfigureDraft.ts
+++ b/apps/agent-forge/src/screens/agentDetail/configure/useConfigureDraft.ts
@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useMemo, useState } from 'react';
 
-import { agentSpecV2JsonSchema, type AgentSpecV2 } from 'lousho/spec';
+import { agentSpecV2JsonSchema, type AgentSpecV2 } from '@linuxdevil/lousho/spec';
 
 import type { AgentRecord } from '../../../../shared/wireTypes';
 import { RuntimeApiError, runtimeClient } from '../../../runtime/runtimeClient';
diff --git a/apps/agent-forge/src/screens/agentDetail/overviewModel.ts b/apps/agent-forge/src/screens/agentDetail/overviewModel.ts
index dca27b435..508bd9330 100644
--- a/apps/agent-forge/src/screens/agentDetail/overviewModel.ts
+++ b/apps/agent-forge/src/screens/agentDetail/overviewModel.ts
@@ -5,7 +5,7 @@
  * capability rows and the safety rows.
  */
 import { Clock, MessageSquare, Radio, Webhook, Workflow, type LucideIcon } from 'lucide-react';
-import type { AgentSpecV2 } from 'lousho/spec';
+import type { AgentSpecV2 } from '@linuxdevil/lousho/spec';
 
 import type { Requirement } from '../../../shared/wireTypes';
 
diff --git a/apps/agent-forge/src/screens/agentDetail/runs/__tests__/RunsTab.test.tsx b/apps/agent-forge/src/screens/agentDetail/runs/__tests__/RunsTab.test.tsx
index 6233bb90a..6dd1722ed 100644
--- a/apps/agent-forge/src/screens/agentDetail/runs/__tests__/RunsTab.test.tsx
+++ b/apps/agent-forge/src/screens/agentDetail/runs/__tests__/RunsTab.test.tsx
@@ -2,7 +2,7 @@ import { act } from 'react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { AgentRecord, TraceSummaryPayload } from '../../../../../shared/wireTypes';
-import type { AgentSpecV2 } from 'lousho/spec';
+import type { AgentSpecV2 } from '@linuxdevil/lousho/spec';
 import type { ObserveScoreRow } from '../../../../observe/types';
 import { render } from '../../../../ui/__tests__/render';
 
diff --git a/apps/agent-forge/src/screens/codeAgent/CodeAgentScreen.tsx b/apps/agent-forge/src/screens/codeAgent/CodeAgentScreen.tsx
index 4488e0b91..df4e182ae 100644
--- a/apps/agent-forge/src/screens/codeAgent/CodeAgentScreen.tsx
+++ b/apps/agent-forge/src/screens/codeAgent/CodeAgentScreen.tsx
@@ -9,7 +9,7 @@
  */
 import { useEffect, useMemo, useState } from 'react';
 import { Folder, Info } from 'lucide-react';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { stringify } from 'yaml';
 import type { Graph } from '../../graph/v2/types';
 import { specToGraph } from '../../graph/v2/specToGraph';
diff --git a/apps/agent-forge/src/screens/codeAgent/__tests__/CodeAgentCanvas.test.tsx b/apps/agent-forge/src/screens/codeAgent/__tests__/CodeAgentCanvas.test.tsx
index f805d1653..9d45751e7 100644
--- a/apps/agent-forge/src/screens/codeAgent/__tests__/CodeAgentCanvas.test.tsx
+++ b/apps/agent-forge/src/screens/codeAgent/__tests__/CodeAgentCanvas.test.tsx
@@ -35,7 +35,7 @@ vi.mock('../../../state/AppState', () => ({
   }),
 }));
 
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { specToGraph } from '../../../graph/v2/specToGraph';
 import type { Graph } from '../../../graph/v2/types';
 import { CodeAgentCanvas, CodeAgentInspector } from '../CodeAgentCanvas';
diff --git a/apps/agent-forge/src/screens/codeAgent/__tests__/CodeAgentScreen.test.tsx b/apps/agent-forge/src/screens/codeAgent/__tests__/CodeAgentScreen.test.tsx
index d31cddabe..84db34d48 100644
--- a/apps/agent-forge/src/screens/codeAgent/__tests__/CodeAgentScreen.test.tsx
+++ b/apps/agent-forge/src/screens/codeAgent/__tests__/CodeAgentScreen.test.tsx
@@ -48,7 +48,7 @@ vi.mock('../../../canvas/layout', async (importActual) => {
   return { ...actual, autoLayout: vi.fn(async (graph: unknown) => graph) };
 });
 
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { AgentRecord } from '../../../../shared/wireTypes';
 import { RuntimeApiError } from '../../../runtime/runtimeClient';
 import { CodeAgentScreen } from '../CodeAgentScreen';
diff --git a/apps/agent-forge/src/screens/workspaces/OverviewSection.tsx b/apps/agent-forge/src/screens/workspaces/OverviewSection.tsx
index 5fccaf920..ffb9ebb2d 100644
--- a/apps/agent-forge/src/screens/workspaces/OverviewSection.tsx
+++ b/apps/agent-forge/src/screens/workspaces/OverviewSection.tsx
@@ -1,6 +1,6 @@
 import { useState } from 'react';
-import workspaceJsonSchema from 'lousho/schemas/lousho.workspace.v1.json';
-import type { ProblemView } from 'lousho/workspaces/client';
+import workspaceJsonSchema from '@linuxdevil/lousho/schemas/lousho.workspace.v1.json';
+import type { ProblemView } from '@linuxdevil/lousho/workspaces/client';
 import { SchemaForm } from '../../ui/schemaForm/SchemaForm';
 import type { JsonSchema } from '../../ui/schemaForm/types';
 import { useWorkspace } from './WorkspaceContext';
diff --git a/apps/agent-forge/src/screens/workspaces/PagesSection.tsx b/apps/agent-forge/src/screens/workspaces/PagesSection.tsx
index 1913e1597..7bf2ded30 100644
--- a/apps/agent-forge/src/screens/workspaces/PagesSection.tsx
+++ b/apps/agent-forge/src/screens/workspaces/PagesSection.tsx
@@ -1,6 +1,6 @@
 import { useEffect, useState } from 'react';
 import { ArrowDown, ArrowUp, Trash2 } from 'lucide-react';
-import type { PageDetail } from 'lousho/workspaces/client';
+import type { PageDetail } from '@linuxdevil/lousho/workspaces/client';
 import { ConfirmDialog, Dialog } from '../../ui/Dialog';
 import { EmptyState } from '../../ui/EmptyState';
 import { Field } from '../../ui/Field';
diff --git a/apps/agent-forge/src/screens/workspaces/WorkspaceContext.tsx b/apps/agent-forge/src/screens/workspaces/WorkspaceContext.tsx
index 6cc40f9fa..ec3cbccda 100644
--- a/apps/agent-forge/src/screens/workspaces/WorkspaceContext.tsx
+++ b/apps/agent-forge/src/screens/workspaces/WorkspaceContext.tsx
@@ -1,5 +1,5 @@
 import { createContext, useContext } from 'react';
-import type { DraftView, ProblemView, WorkspaceDetail } from 'lousho/workspaces/client';
+import type { DraftView, ProblemView, WorkspaceDetail } from '@linuxdevil/lousho/workspaces/client';
 import type { OpsSender } from './useWorkspaceOps';
 
 export interface WorkspaceContextValue {
diff --git a/apps/agent-forge/src/screens/workspaces/WorkspaceRoute.tsx b/apps/agent-forge/src/screens/workspaces/WorkspaceRoute.tsx
index 4b5e4a7ce..4e1f8733d 100644
--- a/apps/agent-forge/src/screens/workspaces/WorkspaceRoute.tsx
+++ b/apps/agent-forge/src/screens/workspaces/WorkspaceRoute.tsx
@@ -1,7 +1,7 @@
 import './workspaces.css';
 import { useState } from 'react';
 import { CircleAlert, SearchX } from 'lucide-react';
-import type { ApiClient } from 'lousho/workspaces/client';
+import type { ApiClient } from '@linuxdevil/lousho/workspaces/client';
 import { matchRoute } from '../../router/router';
 import { useRoute } from '../../router/useRoute';
 import { EmptyState } from '../../ui/EmptyState';
diff --git a/apps/agent-forge/src/screens/workspaces/WorkspacesScreen.tsx b/apps/agent-forge/src/screens/workspaces/WorkspacesScreen.tsx
index d25ae0bf6..821a57ebf 100644
--- a/apps/agent-forge/src/screens/workspaces/WorkspacesScreen.tsx
+++ b/apps/agent-forge/src/screens/workspaces/WorkspacesScreen.tsx
@@ -1,6 +1,6 @@
 import { useMemo } from 'react';
 import { CircleAlert } from 'lucide-react';
-import type { WorkspaceSummary } from 'lousho/workspaces/client';
+import type { WorkspaceSummary } from '@linuxdevil/lousho/workspaces/client';
 import { navigate } from '../../router/router';
 import { useRoute } from '../../router/useRoute';
 import { ScreenHeader } from '../../shell/ScreenHeader';
diff --git a/apps/agent-forge/src/screens/workspaces/__tests__/WorkspaceRoute.test.tsx b/apps/agent-forge/src/screens/workspaces/__tests__/WorkspaceRoute.test.tsx
index 95cf9837f..ba78840f2 100644
--- a/apps/agent-forge/src/screens/workspaces/__tests__/WorkspaceRoute.test.tsx
+++ b/apps/agent-forge/src/screens/workspaces/__tests__/WorkspaceRoute.test.tsx
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { ROUTE_NAMES, WorkspaceApiError } from 'lousho/workspaces/client';
+import { ROUTE_NAMES, WorkspaceApiError } from '@linuxdevil/lousho/workspaces/client';
 
 import { WorkspaceRoute } from '../WorkspaceRoute';
 import { buttonByName, click, conflict, flush, renderWithClient, spyClient, typeInto } from './workspaceTestKit';
diff --git a/apps/agent-forge/src/screens/workspaces/__tests__/WorkspacesScreen.test.tsx b/apps/agent-forge/src/screens/workspaces/__tests__/WorkspacesScreen.test.tsx
index 56c0a879a..a5f5d34d2 100644
--- a/apps/agent-forge/src/screens/workspaces/__tests__/WorkspacesScreen.test.tsx
+++ b/apps/agent-forge/src/screens/workspaces/__tests__/WorkspacesScreen.test.tsx
@@ -1,10 +1,10 @@
 import { act } from 'react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import type { WorkspaceSummary } from 'lousho/workspaces/client';
+import type { WorkspaceSummary } from '@linuxdevil/lousho/workspaces/client';
 
 import { WorkspacesScreen } from '../WorkspacesScreen';
 import type { ScreenHeaderProps } from '../../../shell/ScreenHeader';
-import { WorkspaceApiError } from 'lousho/workspaces/client';
+import { WorkspaceApiError } from '@linuxdevil/lousho/workspaces/client';
 import { buttonByName, click, flush, renderWithClient, spyClient } from './workspaceTestKit';
 
 vi.mock('../../../shell/ScreenHeader', () => ({
diff --git a/apps/agent-forge/src/screens/workspaces/__tests__/workspaceTestKit.tsx b/apps/agent-forge/src/screens/workspaces/__tests__/workspaceTestKit.tsx
index a9e64912c..ec6651a86 100644
--- a/apps/agent-forge/src/screens/workspaces/__tests__/workspaceTestKit.tsx
+++ b/apps/agent-forge/src/screens/workspaces/__tests__/workspaceTestKit.tsx
@@ -1,5 +1,5 @@
 import { act, type ReactNode } from 'react';
-import { fixtureClient, WorkspaceApiError, type ApiClient, type JsonRouteName } from 'lousho/workspaces/client';
+import { fixtureClient, WorkspaceApiError, type ApiClient, type JsonRouteName } from '@linuxdevil/lousho/workspaces/client';
 import { render } from '../../../ui/__tests__/render';
 import { ToastProvider } from '../../../ui/Toast';
 import { WorkspacesClientProvider } from '../workspacesClient';
diff --git a/apps/agent-forge/src/screens/workspaces/useClientQuery.ts b/apps/agent-forge/src/screens/workspaces/useClientQuery.ts
index cec164e8b..4c36b4e09 100644
--- a/apps/agent-forge/src/screens/workspaces/useClientQuery.ts
+++ b/apps/agent-forge/src/screens/workspaces/useClientQuery.ts
@@ -1,6 +1,6 @@
 // fallow-ignore-file code-duplication -- intentionally the useAgentRecord load shape (ticket P2.5 step 3).
 import { useCallback, useEffect, useRef, useState } from 'react';
-import { WorkspaceApiError, type ApiClient } from 'lousho/workspaces/client';
+import { WorkspaceApiError, type ApiClient } from '@linuxdevil/lousho/workspaces/client';
 import { useWorkspacesClient } from './workspacesClient';
 
 export interface QueryState<T> {
diff --git a/apps/agent-forge/src/screens/workspaces/useWorkspaceOps.ts b/apps/agent-forge/src/screens/workspaces/useWorkspaceOps.ts
index 6a110bb6f..66aa9c344 100644
--- a/apps/agent-forge/src/screens/workspaces/useWorkspaceOps.ts
+++ b/apps/agent-forge/src/screens/workspaces/useWorkspaceOps.ts
@@ -1,5 +1,5 @@
 import { useCallback, useState } from 'react';
-import { WorkspaceApiError, type ApplyOpsView, type ProblemView } from 'lousho/workspaces/client';
+import { WorkspaceApiError, type ApplyOpsView, type ProblemView } from '@linuxdevil/lousho/workspaces/client';
 import { useToast } from '../../ui/Toast';
 import { useWorkspacesClient } from './workspacesClient';
 import type { AuthoringOp } from './workspaceTypes';
diff --git a/apps/agent-forge/src/screens/workspaces/workspaceTypes.ts b/apps/agent-forge/src/screens/workspaces/workspaceTypes.ts
index 5cfc8c86d..07bc07651 100644
--- a/apps/agent-forge/src/screens/workspaces/workspaceTypes.ts
+++ b/apps/agent-forge/src/screens/workspaces/workspaceTypes.ts
@@ -1,4 +1,4 @@
-import type { ApplyOpsBody, HarnessView, MainHarnessView, PageDetail, WorkspaceDetail } from 'lousho/workspaces/client';
+import type { ApplyOpsBody, HarnessView, MainHarnessView, PageDetail, WorkspaceDetail } from '@linuxdevil/lousho/workspaces/client';
 
 export type AuthoringOp = ApplyOpsBody['ops'][number];
 export type WorkspaceManifest = WorkspaceDetail['manifest'];
diff --git a/apps/agent-forge/src/screens/workspaces/workspacesClient.tsx b/apps/agent-forge/src/screens/workspaces/workspacesClient.tsx
index 6d39119b2..ea3166968 100644
--- a/apps/agent-forge/src/screens/workspaces/workspacesClient.tsx
+++ b/apps/agent-forge/src/screens/workspaces/workspacesClient.tsx
@@ -1,5 +1,5 @@
 import { createContext, useContext, useMemo, type ReactNode } from 'react';
-import { createFetchClient, type ApiClient } from 'lousho/workspaces/client';
+import { createFetchClient, type ApiClient } from '@linuxdevil/lousho/workspaces/client';
 import { STUDIO_TOKEN_HEADER, loadStudioToken } from '../../runtime/studioToken';
 
 // fallow-ignore-next-line unused-export -- contract surface: P2.21's password auth changes its headers; tests inject their own client.
diff --git a/apps/agent-forge/src/state/AppState.tsx b/apps/agent-forge/src/state/AppState.tsx
index 52bc603b7..96d35e107 100644
--- a/apps/agent-forge/src/state/AppState.tsx
+++ b/apps/agent-forge/src/state/AppState.tsx
@@ -1,6 +1,6 @@
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
 import type { ReactNode } from 'react';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { mergeProposal, type ProposalOverlay } from '../graph/v2/proposal';
 import { HttpAgentStore } from '../persistence/HttpAgentStore';
 import { runtimeClient } from '../runtime/runtimeClient';
diff --git a/apps/agent-forge/src/state/history/__tests__/history.test.ts b/apps/agent-forge/src/state/history/__tests__/history.test.ts
index 21b65d8f9..b003979fc 100644
--- a/apps/agent-forge/src/state/history/__tests__/history.test.ts
+++ b/apps/agent-forge/src/state/history/__tests__/history.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { CanvasLayout } from '../../../../shared/wireTypes';
 import {
   COALESCE_MS,
diff --git a/apps/agent-forge/src/state/useAgentControls.ts b/apps/agent-forge/src/state/useAgentControls.ts
index 6e9c14ae5..fc1ca9fa0 100644
--- a/apps/agent-forge/src/state/useAgentControls.ts
+++ b/apps/agent-forge/src/state/useAgentControls.ts
@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useState } from 'react';
 import type { Dispatch, SetStateAction } from 'react';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { runtimeClient, RuntimeApiError } from '../runtime/runtimeClient';
 import type {
   AgentRunStatusPayload,
diff --git a/apps/agent-forge/src/state/useAgentDocument.ts b/apps/agent-forge/src/state/useAgentDocument.ts
index e8e20eea7..3a9bbd276 100644
--- a/apps/agent-forge/src/state/useAgentDocument.ts
+++ b/apps/agent-forge/src/state/useAgentDocument.ts
@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useMemo, useRef, useState, type Dispatch, type MutableRefObject, type SetStateAction } from 'react';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import type { AgentStore } from '../persistence/AgentStore';
 import { graphToSpec, type GraphToSpecResult } from '../graph/v2/graphToSpec';
 import { specToGraph } from '../graph/v2/specToGraph';
diff --git a/apps/agent-forge/src/state/usePins.ts b/apps/agent-forge/src/state/usePins.ts
index 8f7d3bb01..68d4ebe30 100644
--- a/apps/agent-forge/src/state/usePins.ts
+++ b/apps/agent-forge/src/state/usePins.ts
@@ -1,6 +1,6 @@
 import { useCallback, useState } from 'react';
 import type { Dispatch, SetStateAction } from 'react';
-import type { AgentSpecV2 } from 'lousho';
+import type { AgentSpecV2 } from '@linuxdevil/lousho';
 import { runtimeClient } from '../runtime/runtimeClient';
 import type {
   AgentRunStatusPayload,
diff --git a/apps/agent-forge/src/ui/Dialog.tsx b/apps/agent-forge/src/ui/Dialog.tsx
index 61d05c6e4..ec7a7c03a 100644
--- a/apps/agent-forge/src/ui/Dialog.tsx
+++ b/apps/agent-forge/src/ui/Dialog.tsx
@@ -104,6 +104,8 @@ export interface ConfirmDialogProps {
   pending?: boolean;
   /** Failure from the last attempt, shown above the footer in danger text. */
   error?: string;
+  /** Extra body content between the error line and the footer (e.g. an overwrite checkbox). */
+  children?: ReactNode;
   onConfirm(): void;
   onCancel(): void;
 }
@@ -122,6 +124,7 @@ export function ConfirmDialog({
   tone = 'danger',
   pending = false,
   error,
+  children,
   onConfirm,
   onCancel,
 }: ConfirmDialogProps): JSX.Element | null {
@@ -162,6 +165,7 @@ export function ConfirmDialog({
           {error}
         </p>
       ) : null}
+      {children}
     </Dialog>
   );
 }
diff --git a/bin/lousho.js b/bin/lousho.js
index 0980480d8..6db64a17e 100755
--- a/bin/lousho.js
+++ b/bin/lousho.js
@@ -23,8 +23,8 @@ const USAGE = [
   '      Install a tool, skill, channel, schedule or kit from a registry into an agent directory.',
   '  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.',
+  '  lousho studio [--port N] [--host H]',
+  '      Open Lousho Studio on this project (a separate install: npm i -g @linuxdevil/studio).',
   '  lousho bridge',
   '      Speak Studio\'s bridge protocol on stdio (Lousho Studio starts it in a project).',
   '  lousho workspace <init|ls|show|validate|run> [args] [--source <dir> | --service <url>]',
@@ -52,7 +52,7 @@ const USAGE = [
 
 /**
  * Loads a command module from the ESM build (dist/cli/*.mjs). A user's tool
- * file (`tools/*.ts`) is an ES module, so its `import 'lousho'`
+ * file (`tools/*.ts`) is an ES module, so its `import '@linuxdevil/lousho'`
  * resolves to the ESM build: loading the CLI from the same build means the
  * agent directory and the tools it loads share one copy of the SDK.
  */
@@ -72,9 +72,9 @@ const COMMANDS = new Map([
   // Installs a tool, skill, channel, schedule or memory slot from a JSON registry; see src/cli/add.ts.
   ['add', { module: 'add', run: 'runAdd' }],
   ['build', { module: 'build', run: 'runBuild', env: true }],
-  // Default 'auto': prod (single built server+UI) when apps/agent-forge has
-  // been built (`npm run build:studio`), dev (Vite + tsx, two processes)
-  // otherwise. --prod/--dev force one or the other - see src/cli/studio.ts.
+  // Finds an installed @linuxdevil/studio (or the SDK checkout's
+  // apps/agent-forge) and opens this folder as a workspace; inside the
+  // checkout, --prod/--dev pick the launch mode - see src/cli/studio.ts.
   ['studio', { module: 'studio', run: 'runStudio' }],
   // Speaks Studio's NDJSON bridge protocol on stdio; see src/cli/bridge.ts.
   ['bridge', { module: 'bridge', run: 'runBridge', env: true }],
diff --git a/docs/acp.md b/docs/acp.md
index e08df220d..59ed22c99 100644
--- a/docs/acp.md
+++ b/docs/acp.md
@@ -10,9 +10,9 @@ it, watch its tool calls and approve them from the editor's agent panel.
 ## The command
 
 ```bash
-npx lousho acp agent.yaml                          # a spec file
-npx lousho acp ./my-agent --model openai/gpt-4o    # an agent directory, on another model
-npx lousho acp src/agent.ts                        # a .ts/.js module (createAgent() options or an agent)
+npx @linuxdevil/lousho acp agent.yaml                          # a spec file
+npx @linuxdevil/lousho acp ./my-agent --model openai/gpt-4o    # an agent directory, on another model
+npx @linuxdevil/lousho acp src/agent.ts                        # a .ts/.js module (createAgent() options or an agent)
 ```
 
 ```text
@@ -118,7 +118,7 @@ It resolves once `input` ends, after aborting any running turn.
 
 ```ts
 import * as readline from 'node:readline';
-import { createAgent, serveAcp } from 'lousho';
+import { createAgent, serveAcp } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You are a coding assistant.' });
 
diff --git a/docs/agent-directories.md b/docs/agent-directories.md
index d167bd470..933ee5e50 100644
--- a/docs/agent-directories.md
+++ b/docs/agent-directories.md
@@ -11,7 +11,7 @@ code at any time without a rewrite.
 > implied; the files run with your process's full permissions.
 
 ```ts
-import { loadAgentDir } from 'lousho';
+import { loadAgentDir } from '@linuxdevil/lousho';
 
 const agent = await loadAgentDir('./my-agent');
 const { text } = await agent.send('Hello!');
@@ -108,7 +108,7 @@ rule decides.
 
 ```ts
 // hooks.ts — the default export is a hook or a list of them
-import type { AgentHook } from 'lousho';
+import type { AgentHook } from '@linuxdevil/lousho';
 const audit: AgentHook = {
   name: 'audit',
   postToolCall(ctx) {
@@ -120,7 +120,7 @@ export default audit;
 
 ```ts
 // approve.ts — the default export decides every `ask`ed call
-import type { ApproveToolCall } from 'lousho';
+import type { ApproveToolCall } from '@linuxdevil/lousho';
 const approve: ApproveToolCall = ({ args }) => !String(args.path ?? '').endsWith('.test.js');
 export default approve;
 ```
@@ -145,7 +145,7 @@ that exports no tool at all is an error, as are two tools with the same name
 ```ts no-verify
 // tools/send_email.ts
 import { z } from 'zod';
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 
 export default defineTool({
   name: 'send_email',
@@ -236,7 +236,7 @@ internal helper of the generated bundle); with your own server, use
 
 ```ts
 import { createServer } from 'node:http';
-import { createAgent, mountChannels, resolveAgentDir } from 'lousho';
+import { createAgent, mountChannels, resolveAgentDir } from '@linuxdevil/lousho';
 
 // channels/support.ts: export default webhookChannel({ secret: process.env.HOOK_SECRET ?? '' })
 const { config, channels } = await resolveAgentDir('./my-agent');
@@ -259,7 +259,7 @@ naming the file. A `memory` override passed to `loadAgentDir(dir, { overrides })
 is merged with the directory's slots by name: the override wins a name clash.
 
 ```ts
-import { defineMemory, fileMemory, resolveAgentDir } from 'lousho';
+import { defineMemory, fileMemory, resolveAgentDir } from '@linuxdevil/lousho';
 
 // memory/notes.ts: export default { scope: 'global', provider: fileMemory({ dir: './.lousho/memory' }) }
 const { manifest } = await resolveAgentDir('./my-agent', {
@@ -273,7 +273,7 @@ A relative `dir` in a `memory/*.ts` file resolves against the process working di
 ```ts
 // memory/notes.ts
 import { fileURLToPath } from 'node:url';
-import { fileMemory } from 'lousho';
+import { fileMemory } from '@linuxdevil/lousho';
 
 export default {
   scope: 'global',
@@ -297,7 +297,7 @@ The path follows the module: a copied or bundled build keeps its memory next to
 handy for tests and tooling:
 
 ```ts
-import { resolveAgentDir, createAgent } from 'lousho';
+import { resolveAgentDir, createAgent } from '@linuxdevil/lousho';
 
 const { config, manifest } = await resolveAgentDir('./my-agent');
 console.log(manifest.tools, manifest.skills, manifest.subagents);
@@ -317,8 +317,8 @@ declares (`guardrails`, `onEvent`, `retry`, `reasoning`, `redactContent`,
 `output`, ...). Use it to swap the model in tests:
 
 ```ts no-run
-import { loadAgentDir } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { loadAgentDir } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const agent = await loadAgentDir('./my-agent', { provider: mockModel(['Hi there.']) });
 ```
@@ -349,7 +349,7 @@ says so. Compile the directory first, or use `.js`/`.mjs` tools with an
 ## Run it with `lousho dev`
 
 ```bash
-npx lousho dev ./my-agent
+npx @linuxdevil/lousho dev ./my-agent
 ```
 
 Serves the chat UI and `POST /chat` for the directory and reloads it when
@@ -368,7 +368,7 @@ dev](schedules.md#in-lousho-dev)).
 ## Deploy it with `lousho build`
 
 ```bash
-npx lousho build ./my-agent --target=node-server    # or docker
+npx @linuxdevil/lousho build ./my-agent --target=node-server    # or docker
 ```
 
 The agent directory is the unit of deployment: the built server loads it with
diff --git a/docs/agent-forge.md b/docs/agent-forge.md
index 2a793c371..43f91cdf3 100644
--- a/docs/agent-forge.md
+++ b/docs/agent-forge.md
@@ -1,67 +1,75 @@
-# Agent Forge
-
-Agent Forge (`apps/agent-forge`, also called the Studio) is this SDK's
-companion dashboard: one app with a left navigation to build and run agents,
-try prompts, and read what your agents did from the observe daemon. Build an
-agent's graph on a canvas, run it, chat with it and author sandboxed
-pre/post hooks (all reading and writing the same `AgentSpec` YAML that
-`lousho dev` and `lousho build` use), try prompts in a playground, and read
-the [observe daemon](./observability.md#the-observe-daemon)'s traces,
-threads, fleet monitoring, eval scores, datasets, annotation queues, prompt
-registry and context hub. It's launched with one command,
-`lousho studio`, and ships as part of this SDK's npm package.
-
-This doc covers: installation, the `lousho studio` quickstart, the
-[navigation and screens](#navigation), a first-agent walkthrough, hook
-authoring, time travel (replaying a run from a past step), the playground
-endpoint, and how settings/secrets/deploy wiring works.
-
-Three features have their own pages: [the visual
-builder](./forge-builder.md) — the canvas, Inspector, Configure tab,
-in-place testing and Code tab — [the Agent
-Author](./forge-author.md) — the chat that drafts agents as proposals you
-review before anything is saved — and [versions, triggers and
-publishing](./forge-lifecycle.md) — the working copy, drafts, the inbox,
-the eval gate, Serve and Deploy.
-
-![The builder: nav, agent rail, the fitted canvas with the Inspector folded, and the bottom drawer](./images/studio-agents.png)
-
-## Installation
-
-Agent Forge ships inside `lousho` itself - there's no
-separate package to install:
+# Lousho Studio
+
+Lousho Studio is a local web app for building, testing and watching every agent across your projects.
+
+It is a separate npm package, `@linuxdevil/studio` — the SDK (`@linuxdevil/lousho`)
+does not contain it. One Studio server shows every agent you have: the spec-v2
+graph agents saved in your project folders, code agents Studio finds by scanning
+a workspace, and agents running anywhere that report to the observe collector.
+
+This page covers installing and starting Studio, workspaces, which SDK runs a
+workspace's agents (and what each banner means), the collector, and how agents
+deployed on other machines show up here. [Using Studio](#using-studio) covers
+the builder, the playground, traces and the rest of the app; the builder,
+Author and lifecycle screens have their own pages: [the visual
+builder](./forge-builder.md), [the Agent
+Author](./forge-author.md) and [versions, triggers and
+publishing](./forge-lifecycle.md).
+
+## Install and start
+
+Any of these works:
 
 ```bash
-npm install lousho
+npx @linuxdevil/studio
 ```
 
-That's it. `lousho studio` (below) runs a pre-built copy of the app; you
-don't need `apps/agent-forge`'s own source or its devDependencies (Vite,
-`tsx`, etc.) to use it.
-
-If you're working inside this SDK's own monorepo instead (contributing to
-Agent Forge itself), see [Dev mode](#dev-mode) below.
+```bash
+npm i -g @linuxdevil/studio
+lousho-studio
+```
 
-## Quickstart
+Or, inside a project that already has `@linuxdevil/lousho` installed, the SDK's
+launcher finds the installed Studio and opens this folder as a workspace:
 
 ```bash
-npx lousho studio
+lousho studio
+```
+
+When no Studio is installed the launcher says so instead of bundling one:
+
 ```
+Studio is a separate install: npx @linuxdevil/studio
+```
+
+`lousho studio` accepts `--port` and `--host` and passes them through; run
+`lousho studio --help` for its options. `--prod` and `--dev` only apply inside
+the SDK's own repository checkout (see [Dev mode](#dev-mode)).
+
+`lousho-studio` (and `npx @linuxdevil/studio`) take the same flags:
 
-This starts one local server and prints its URL (default
-`http://127.0.0.1:4750/?token=<random>`). Open that exact URL in a browser.
-It lands on the Agents list (`#/agents`): your saved agents as cards, plus
-a **New agent** menu. Opening or creating one takes you to its Canvas tab
-(`#/agents/<id>/canvas`) — the builder: the build toolbar (the agent's name
-and run status, the model badge, then Debug, Stop, Run, Import, Export and
-Save), the agent rail (your saved agents plus a node/hook palette), the
-canvas, the Inspector (right), and a bottom drawer with Test, Problems,
-Logs, Trace, Output, History and Settings tabs. An agent opens with
-nothing selected and the whole graph fitted in view; the Inspector stays
-folded away until you select a node, or press the **Inspector** button at
-the canvas's top-right (its accessible name is "Show inspector"), which is
-remembered. The other screens are one click away in the navigation; see
-[Navigation](#navigation).
+| Flag | Default | Meaning |
+| --- | --- | --- |
+| `--workspace <dir>` | the current folder | A project folder to open; it is added to your workspaces. |
+| `--port N` | `4750` | The port to listen on. |
+| `--host H` | `127.0.0.1` | The interface to bind to. |
+
+The server prints its URL, `http://127.0.0.1:4750/?token=<random>`. The
+`?token=` is a per-launch access token: the page keeps it for that tab and
+sends it on every API call, so open the printed URL, not the bare host (see
+[Access token](#access-token)).
+
+Opening Studio lands on the Agents list (`#/agents`): your saved agents as
+cards, plus a **New agent** menu. Opening or creating one takes you to its
+Canvas tab — the builder: the build toolbar (the agent's name and run
+status, the model badge, then Debug, Stop, Run, Import, Export and Save),
+the agent rail (your saved agents plus a node/hook palette), the canvas, the
+Inspector (right), and a bottom drawer with Test, Problems, Logs, Trace,
+Output, History and Settings tabs. An agent opens with nothing selected and
+the whole graph fitted in view; the Inspector stays folded away until you
+select a node, or press the **Inspector** button at the canvas's top-right
+(its accessible name is "Show inspector"), which is remembered. The other
+screens are one click away in the navigation; see [Navigation](#navigation).
 
 Below 860px wide the navigation becomes a drawer opened from the
 **Navigation** (menu) button at the top; picking a screen, the scrim or Esc
@@ -70,15 +78,145 @@ slide-over panels you open from the top bar; Run (or Stop) and Save stay in
 the bar, and Debug, Import, Export and the model badge move into its **More
 actions** (`⋯`) menu.
 
-Useful flags:
+## Workspaces
+
+A workspace is a project folder on disk. The folder you launch Studio from is
+added automatically; add more with **Add workspace → folder path** (or the
+**Add workspace…** entry in the switcher).
+
+The switcher at the top of the nav lists **All workspaces**, each workspace,
+and **Add workspace…**. `#/agents` is the all-workspaces list; an agent route
+is `#/w/<workspace>/agents/<id>/<tab>`.
+
+Things live in three places:
+
+| Where | What |
+| --- | --- |
+| `~/.lousho/studio/` | Studio-wide state: the workspace registry, settings, secrets, assistant sessions, pass spend, inbox alerts. Shared across workspaces. |
+| `<workspace>/.lousho/agents/` | The project's agents: spec, metadata, layout, working copy, versions, drafts, suggestions, traces, chats, approvals, checkpoints. Travels with the project. |
+| `~/.lousho/observe.db` | The observe collector's database (traces, scores, sessions). |
+
+On first launch after the split, if a workspace still has a project-level
+`.lousho/settings.json` or `.lousho/secrets.json`, Studio offers **Import
+settings and keys from <workspace>** once, copies them into
+`~/.lousho/studio/`, and leaves the originals alone.
+
+## Three kinds of agent
+
+The all-workspaces agent list mixes three kinds:
+
+| Kind | Source | What you can do |
+| --- | --- | --- |
+| Workspace agent | `<workspace>/.lousho/agents/<id>.yaml` (Agent spec v2) | Everything: canvas, Author, versions, test, publish. |
+| Code agent | An agent directory or `agent.ts` found by scanning a workspace | Read-only canvas, traces, runs. |
+| Observed agent | Any agent reporting to the observe collector (`GET /api/v1/agents`): deployed workers, CI, other machines | Read-only card: name, project, instances, last seen, traces, scores, evals. |
+
+Observed agents whose collector `project` matches a workspace id appear under
+that workspace (see [See agents running elsewhere](#see-agents-running-elsewhere)).
+The rest are grouped under **Elsewhere**.
+
+## Which SDK runs your agents
+
+For each workspace Studio picks how agent processes run:
+
+- **Bridge** — the normal case. Studio spawns `lousho bridge` from the SDK
+  installed in that project (`@linuxdevil/lousho`), so runs use the project's
+  own SDK version. This matters because a project's `{ file }` tools and
+  skills import that project's dependencies, which only resolve inside the
+  project.
+- **In-process** — Studio's own built-in SDK, used when the project has no
+  SDK installed or its checkout is not built.
+- **Read-only** — the project's SDK is too old or speaks a protocol this
+  Studio does not know, so edits are refused until it is fixed.
+
+Each non-default state shows a banner at the top of the workspace's pages:
+
+| Banner | What to do |
+| --- | --- |
+| `This project has no @linuxdevil/lousho installed. Runs use Studio's built-in SDK <version>.` | Runs still work on Studio's SDK. Install `@linuxdevil/lousho` in the project to run its own version. |
+| `This SDK checkout is not built, so runs use Studio's built-in SDK <version>. Run npm run build to use it.` | Inside the SDK repository: run `npm run build` in the checkout. |
+| `Update @linuxdevil/lousho in this project to <minimum> or later to edit agents here.` | The project's SDK is older than this Studio understands. The workspace is read-only: update `@linuxdevil/lousho` in the project to edit. |
+| `This project's @linuxdevil/lousho <version> is newer than this Studio understands. Update Studio to edit agents here.` | The project has a newer SDK than this Studio was built for. Update Studio (`npm i -g @linuxdevil/studio@latest`) to edit. |
+| `This project's agent process keeps stopping. Check the Studio terminal for its output, then restart it.` | The bridge process crashed repeatedly. Its output is in the terminal that started Studio; use **Restart** on the banner to try again. |
+
+While a workspace is read-only, writes under its agents (saves, drafts, runs,
+deploys) are refused; reads still work.
+
+A few features still need Studio's built-in SDK and are unavailable on
+bridge workspaces:
+
+- Flow runs: `Flow runs need Studio's built-in SDK for now. Remove the project's SDK from this workspace or run the flow from code.`
+- Breakpoints: `Breakpoints need Studio's built-in SDK for now.`
+- Time travel: `Time travel is not available yet for projects that run their own SDK.`
+
+## The collector
+
+Everything under Observe, Evaluate and Assets — and run reporting — reads the
+observe collector. On boot Studio probes the configured URL (default
+`http://127.0.0.1:7777`):
+
+- **Attached** — a `lousho observe` daemon is already running there; Studio
+  uses it.
+- **Started** — none answered on loopback, so Studio started its own and
+  stops it on exit. It never stops a daemon it did not start.
+- **Remote** — a non-loopback URL (team or hosted collector); Studio probes
+  it but does not start or stop anything there.
+- **Down** — nothing answers; daemon screens show the start command instead
+  of data and recover on their own.
+
+The collector card at the bottom of the nav shows the mode (`Attached to
+<url>`, `Started by Studio on <url>`, `Remote collector at <url>`, `Not
+reachable: <error>`). **Settings → Collector** sets a remote URL and bearer
+token; create a token with `lousho observe token create --project <name>`.
+`LOUSHO_OBSERVE_URL` and `LOUSHO_OBSERVE_TOKEN` in Studio's own environment
+override the stored setting, and `LOUSHO_STUDIO_COLLECTOR=0` stops Studio
+from auto-starting a local daemon.
+
+## See agents running elsewhere
+
+An agent deployed on another machine — a server, CI, a teammate's laptop —
+shows up in Studio once it reports to a collector Studio can read. Reporting
+is pure SDK configuration; nothing in the agent is Studio-specific:
+
+```ts no-run
+import { createAgent } from '@linuxdevil/lousho';
+
+// LOUSHO_OBSERVE, LOUSHO_OBSERVE_TOKEN and LOUSHO_OBSERVE_PROJECT are read
+// from the environment - no Studio-specific code.
+export const agent = createAgent({ model: 'openai/gpt-4.1-mini' });
+```
+
+Set these in the deployed environment:
+
+| Variable | Meaning |
+| --- | --- |
+| `LOUSHO_OBSERVE` | The collector URL, e.g. `http://127.0.0.1:7777` or a tunnel/remote URL. `1`/`true` uses the default. |
+| `LOUSHO_OBSERVE_TOKEN` | Bearer token, when the collector requires one (`lousho observe token create`). |
+| `LOUSHO_OBSERVE_PROJECT` | The workspace id to group the agent under — shown in **Settings → Workspaces**. Without it the project name is the package name and the agent appears under **Elsewhere**. |
+
+Point Studio at the same collector under **Settings → Collector** (or with
+`LOUSHO_OBSERVE_URL`/`LOUSHO_OBSERVE_TOKEN` in Studio's environment), and the
+deployed agent's traces, scores and sessions appear in Studio's Observe
+screens.
+
+## Updating
+
+Studio (`@linuxdevil/studio`) and the SDK (`@linuxdevil/lousho`) are separate
+packages and update independently:
 
 ```bash
-npx lousho studio --port 5000       # pick a different port
-npx lousho studio --host 0.0.0.0    # bind to all interfaces
-npx lousho studio --prod            # force production mode (see below)
-npx lousho studio --dev             # force dev mode (monorepo only)
+npm i -g @linuxdevil/studio@latest   # Studio itself
+npm i @linuxdevil/lousho@latest      # inside each project, its SDK
 ```
 
+A workspace's agents edit only when the project's SDK is at least
+`MIN_BRIDGE_SDK_VERSION` — the SDK version this Studio was built against. Older
+SDKs get the read-only banner above; newer ones get the "update Studio" banner.
+Bridge workspaces also need `lousho bridge` in the project's SDK, which speaks
+bridge protocol `1`.
+
+## Using Studio
+
 ### Access token
 
 The studio can store provider keys, start runs and execute hook code, so its
@@ -110,40 +248,38 @@ without the CLI:
 
 ### Where agents live
 
-Agent specs and run state are stored under `.lousho/` in the directory you
-ran `lousho studio` from (agent YAML files under `.lousho/agents/`,
-checkpoints and approvals alongside them) - the same `.lousho/` layout
-`lousho dev`/`lousho build` use. Those YAML files are
-[Agent spec v2](./agent-spec.md) documents, which that page explains field
-by field.
-
-The agents list and the builder's agent rail show exactly the agents in that `.lousho/agents/`: a YAML
-file you add there shows up, and an agent you create in the studio is
-written there at once (autosave and **Save** both write the file), so it
-can be chatted with straight away. Another project, opened in its own
-`lousho studio`, shows only its own agents. The browser keeps nothing but a
-draft of an edit that could not reach the server (it is pushed on the next
-load), stored per workspace directory. A file in `.lousho/agents/` that no
-longer parses is skipped with a warning in the server log.
+Each workspace's agent specs and run state live under `.lousho/` in that
+project folder (agent YAML files under `.lousho/agents/`, checkpoints and
+approvals alongside them) - the same `.lousho/` layout `lousho dev`/`lousho
+build` use, so the files travel with the project and stay diffable.
+Studio-wide state (settings, secrets, the workspace registry) lives in
+`~/.lousho/studio/` instead; see [Workspaces](#workspaces). Those YAML files
+are [Agent spec v2](./agent-spec.md) documents, which that page explains
+field by field.
+
+The Agents screen's agent rail lists exactly the agents in that workspace's
+`.lousho/agents/`: a YAML file you add there shows up, and an agent you
+create in the studio is written there at once (autosave and **Save** both
+write the file), so it can be chatted with straight away. Another workspace
+shows only its own agents. The browser keeps nothing but a draft of an edit
+that could not reach the server (it is pushed on the next load), stored per
+workspace directory. A file in `.lousho/agents/` that no longer parses is
+skipped with a warning in the server log.
 
 ### Production vs. dev mode
 
-`lousho studio` has two modes, and picks the right one automatically:
+An installed Studio (`lousho-studio`, `npx @linuxdevil/studio`, or
+`lousho studio` finding it) is always production mode: a single Express
+server serves both the REST/WebSocket API *and* the pre-built client (React
+app) as static files, on one port. There is no separate Vite dev server and
+no TypeScript loader involved.
 
-- **Production** (the default once Agent Forge has been built): a single
-  Express server serves both the REST/WebSocket API *and* the pre-built
-  client (React app) as static files, on one port. This is what runs when
-  you `npm install` the published package - there's no separate Vite dev
-  server and no TypeScript loader involved.
-- **Dev** (falls back to this if the build hasn't been run yet, i.e. inside
-  a source checkout of this monorepo): the API server runs straight off
-  its TypeScript source via `tsx`, alongside a real Vite dev server (with
-  hot-module reload) that proxies API requests to it. Two processes, two
-  ports internally, one command.
-
-`--prod`/`--dev` force one or the other; run without either flag and
-`lousho studio` auto-detects based on whether `apps/agent-forge/dist-server`
-exists.
+Dev mode - the API server running from TypeScript via `tsx` next to a Vite
+dev server with hot-module reload - exists only inside the SDK's own
+repository checkout, for people contributing to Studio itself. There
+`lousho studio --dev` (or `--prod` to force the built bundle) picks the mode;
+run without either flag it auto-detects based on whether
+`apps/agent-forge/dist-server` exists. See [Dev mode](#dev-mode).
 
 ## Navigation
 
@@ -248,30 +384,27 @@ Every status in the Studio is the same pill:
 
 ### The collector (observe daemon)
 
-Everything under Observe, Evaluate and Assets reads the observe daemon
-(`lousho observe start`) through the Studio server's `/observe` proxy. The
-proxy reads only `LOUSHO_OBSERVE_URL` (default `http://127.0.0.1:7777`);
-`LOUSHO_OBSERVE` does not change where the screens read (it only picks where
-builder runs report, see the [walkthrough](#first-agent-walkthrough)). When
-`LOUSHO_OBSERVE_TOKEN` is set, the proxy sends it to the daemon as the bearer
-token on every read and write (as run reporting and the judge evaluators do),
-so the screens also work against a daemon started with `--require-token`.
-Without it, such a daemon answers `401` to every `/api/` read and the screens
-show that error instead of data (`/health` still answers, so the collector
-card says running). The browser's own credentials (the Studio token, cookies,
-`Authorization`) are never passed on. The proxy only forwards reads plus the
-writes the screens make (feedback scores, new prompt versions from the
-Playground, prompt label moves, hub entry edits, dataset and example writes,
-annotation queue writes, evaluator rule writes); every other write, ingest
-above all, is refused with `405`. It always calls the daemon at
-`LOUSHO_OBSERVE_URL`, whatever host the request line names.
-
-The collector card at the bottom of the nav says whether the daemon answers:
-**Checking collector…** until the first probe, then **Collector running**
-or **Collector unreachable**, with the daemon URL underneath. The probe keeps polling. While the daemon is down, each
-daemon screen shows the command to start it instead of an error, keeps its
-URL, and swaps the data back in by itself once the daemon answers. Builder
-and Playground runs do not need the daemon.
+Everything under Observe, Evaluate and Assets reads the observe collector
+through the Studio server's `/observe` proxy, which calls whatever URL the
+collector manager resolved (see [The collector](#the-collector)). The proxy
+forwards reads plus the writes the screens make (feedback scores, new prompt
+versions from the Playground, prompt label moves, hub entry edits, dataset
+and example writes, annotation queue writes, evaluator rule writes); every
+other write, ingest above all, is refused with `405`. When a bearer token is
+configured the proxy sends it to the collector on every read and write (as
+run reporting and the judge evaluators do), so the screens also work against
+a collector started with `--require-token`. Without it, such a collector
+answers `401` to every `/api/` read and the screens show that error instead
+of data (`/health` still answers, so the collector card says running). The
+browser's own credentials (the Studio token, cookies, `Authorization`) are
+never passed on.
+
+The collector card at the bottom of the nav shows the resolved mode —
+**Attached to \<url\>**, **Started by Studio on \<url\>**, **Remote collector
+at \<url\>** or **Not reachable: \<error\>** — and keeps polling. While the
+collector is down, each daemon screen shows the command to start it instead
+of an error, keeps its URL, and swaps the data back in by itself once it
+answers. The Agents screen and Playground runs do not need the collector.
 
 ## Screens
 
@@ -484,7 +617,7 @@ filter (agent, status `ok` or `error`, name contains), and the kind:
   the provider's environment variable where the Studio runs (the stored key
   wins); the provider list offers the providers that have either, plus
   `ollama` and `mock`. With no key at all the judge option is disabled, with
-  a link to Settings. Judges run only while `lousho studio` is running; until
+  a link to Settings. Judges run only while Studio is running; until
   then their jobs wait in the daemon (see
   [Judge rules](./observability.md#judge-rules-through-agent-forge)). Set
   `LOUSHO_STUDIO_JUDGE=0` on the Studio server to turn its judge loop off.
@@ -584,10 +717,10 @@ and deploy cards; see [Settings, secrets and deploy wiring](#settings-secrets-an
    `awaiting approval`), and once the run's trace id is known an **Open
    trace** link next to it opens the run at `#/traces/<traceId>` (in the
    narrow layout it is in the **More** menu). Builder runs report to the
-   observe daemon as agent `<agent id>`, the same way the Playground does:
-   when `LOUSHO_OBSERVE` is set its reporter is used (nothing is reported
-   twice), a daemon that is down only drops events and never fails the run,
-   and message content is sent only to a loopback daemon (never to the
+   observe collector as agent `<agent id>`, the same way the Playground
+   does (see [The collector](#the-collector)): a collector that is down
+   only drops events and never fails the run, and message content is sent
+   only to a loopback collector (never to the
    trace files or the live Trace tab). Run sends a fixed
    prompt, which the Test tab's chat shows
    as a **Run input** bubble instead of a message from you. If the studio
@@ -618,9 +751,9 @@ and deploy cards; see [Settings, secrets and deploy wiring](#settings-secrets-an
    live. Selecting a step highlights its node on the canvas. The list
    refreshes when a run ends. The files are the ones `lousho traces` reads, in
    `.lousho/agents/<agent id>/traces/<day>/<trace id>.jsonl` under the
-   directory `lousho studio` was started in (see
+   workspace folder (see
    [Local traces](observability.md#local-traces)):
-   `npx lousho traces --dir .lousho/agents/<agent id>/traces` shows the same
+   `npx @linuxdevil/lousho traces --dir .lousho/agents/<agent id>/traces` shows the same
    runs in the terminal, and deleting the agent's folder deletes its traces.
    The tab shows what the spans hold: model and tool names, token counts,
    cost, durations and error messages, and in the inspector's Input,
@@ -803,36 +936,36 @@ Every stream ends with exactly one `done` or `error`, even a run that stops
 without a result. `usage` has the `run.done` event's usage shape
 (`AgentEventUsage`).
 
-Closing the connection aborts the run. Every run reports to the observe
-daemon the Studio reads (`LOUSHO_OBSERVE_URL`, default
-`http://127.0.0.1:7777`, or `LOUSHO_OBSERVE` when set) as agent
+Closing the connection aborts the run. Every run reports to the collector
+the Studio reads (see [The collector](#the-collector)) as agent
 `playground`, with `lousho.prompt.ref` on the run's root span when
-`promptRef` is given. `LOUSHO_OBSERVE_TOKEN` is sent as the bearer token, for a
-daemon bound beyond loopback. A daemon that is down does not slow or fail the run.
+`promptRef` is given. A bearer token is sent when one is configured, for a
+collector bound beyond loopback. A collector that is down does not slow or
+fail the run.
 
 ## Settings, secrets and deploy wiring
 
 The Settings screen (`#/settings`, the last screen in the nav) and the builder
 drawer's **Settings** tab share three parts: provider API keys
-(OpenAI and Anthropic, stored encrypted under `.lousho/` and never shown
+(OpenAI and Anthropic, stored encrypted under `~/.lousho/studio/` and never shown
 again; each key shows **Set** with its masked last characters, **From
 environment** when only `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` is set, or
 **Not set**), named settings profiles (provider, deploy adapter, hook timeout,
-OpenTelemetry toggle; kept in `.lousho/settings.json`, which holds no
+OpenTelemetry toggle; kept in `~/.lousho/studio/settings.json`, which holds no
 secrets), and a **Deploy** section that picks an adapter (`node-server`,
 `docker` or `cloudflare-worker`) and runs `lousho build` for the selected
 agent. Other providers still read their environment variables, the same way
 `lousho dev`/`lousho build` do (see [Configuration](./configuration.md)), and
 the `mock` provider needs no credentials.
 
-Stored keys are encrypted with AES-256-GCM in `.lousho/secrets.json`. The
-encryption key is generated on first use and kept next to it in
-`.lousho/secrets.key` (both `0600` on POSIX). This keeps keys out of
+Stored keys are encrypted with AES-256-GCM in `~/.lousho/studio/secrets.json`.
+The encryption key is generated on first use and kept next to it in
+`~/.lousho/studio/secrets.key` (both `0600` on POSIX). This keeps keys out of
 anything that copies the ciphertext alone - a backup, a zip of the project,
 a shared agent YAML - but anyone who can read both files as your user can
-decrypt them. It is not an OS keychain. Keep `.lousho/` out of version
-control and out of shared archives, and prefer environment variables on
-shared machines.
+decrypt them. It is not an OS keychain. Keep `~/.lousho/studio/` out of
+version control and out of shared archives, and prefer environment variables
+on shared machines.
 
 An agent whose provider has no key (no stored key and no environment
 variable) does not run. **Run** and **Chat** fail with
@@ -844,16 +977,18 @@ mock agent carries a **MOCK** badge.
 
 ## Dev mode
 
-If you're working inside this SDK's own monorepo (contributing to Agent
-Forge itself, not just using it), `lousho studio` falls back to dev mode
-automatically as long as `apps/agent-forge/dist-server` hasn't been built
-yet:
+Dev mode exists only for people contributing to Studio inside the SDK's own
+monorepo - an installed Studio is always the production bundle (see
+[Production vs. dev mode](#production-vs-dev-mode)). From a checkout of this
+repository, `lousho studio` detects the Studio source and falls back to dev
+mode automatically as long as `apps/agent-forge/dist-server` hasn't been
+built yet:
 
 ```bash
 git clone https://github.com/LinuxDevil/lousho.git
 cd agent-sdk
 npm install
-npx lousho studio --dev   # or just `npx lousho studio` before building
+node bin/lousho.js studio --dev   # or just `node bin/lousho.js studio` before building
 ```
 
 This runs the API server straight from TypeScript (`tsx`) and a real Vite
@@ -865,7 +1000,7 @@ is pinned to port 5173 and the API server accepts that origin. To build the prod
 ```bash
 npm run build:studio   # builds apps/agent-forge/dist (client) and
                         # apps/agent-forge/dist-server (bundled server)
-npx lousho studio       # now runs in production mode
+node bin/lousho.js studio       # now runs in production mode
 ```
 
 `npm run build:studio` also runs automatically as part of the root
@@ -931,3 +1066,4 @@ review shots included.
 LOUSHO_DOC_SHOTS=1 LOUSHO_DOC_SHOTS_OUT=/tmp/shots-dark LOUSHO_DOC_SHOTS_SCHEME=dark npx playwright test -c apps/agent-forge/playwright.config.ts docShots
 ```
 
+
diff --git a/docs/agent-spec.md b/docs/agent-spec.md
index 973a65feb..a39e8b2a2 100644
--- a/docs/agent-spec.md
+++ b/docs/agent-spec.md
@@ -74,8 +74,8 @@ A minimal spec is four fields. This snippet parses one and runs it on the
 built-in `mock` provider, so it works offline with no API key:
 
 ```ts
-import { createMockProvider, LLMProviderRegistry, specV2ToAgent } from 'lousho';
-import { parseAgentSpecV2 } from 'lousho/spec';
+import { createMockProvider, LLMProviderRegistry, specV2ToAgent } from '@linuxdevil/lousho';
+import { parseAgentSpecV2 } from '@linuxdevil/lousho/spec';
 
 // 'mock' is a registered provider name; scripting its reply keeps the output deterministic.
 LLMProviderRegistry.register('mock', () => createMockProvider({ responses: ['Hello!'] }));
@@ -274,8 +274,8 @@ for when you want to build the agent yourself. v1's `specToAgent()` stays
 separate: it is synchronous and takes a v1 spec, not v2 data.
 
 ```ts
-import { compileSpec, specV2ToAgent, type SpecHost } from 'lousho';
-import { parseAgentSpecV2 } from 'lousho/spec';
+import { compileSpec, specV2ToAgent, type SpecHost } from '@linuxdevil/lousho';
+import { parseAgentSpecV2 } from '@linuxdevil/lousho/spec';
 
 const host: SpecHost = { baseDir: process.cwd() };
 const spec = parseAgentSpecV2({ version: 2, name: 'Greeter', model: 'mock/greeter', instructions: 'Say hello.' });
@@ -303,14 +303,14 @@ and v1's `agentSpecSchema`. Node-only helpers (`specV2ToAgent`,
 stay on the package root.
 
 ```ts
-import { agentSpecV2JsonSchema } from 'lousho/spec';
+import { agentSpecV2JsonSchema } from '@linuxdevil/lousho/spec';
 
 const schema = agentSpecV2JsonSchema(); // the draft-07 JSON Schema of a spec, for forms and editors
 console.log(schema.title); // 'AgentSpec v2'
 ```
 
 ```ts
-import { parseAgentSpecV2, specToCode } from 'lousho/spec';
+import { parseAgentSpecV2, specToCode } from '@linuxdevil/lousho/spec';
 
 const spec = parseAgentSpecV2({ version: 2, name: 'Greeter', model: 'mock/greeter', instructions: 'Say hello.' });
 console.log(specToCode(spec)); // the same spec as a readable createAgent({...}) module
@@ -325,7 +325,7 @@ is not re-validated - run it through `parseAgentSpecV2()` or use
 version and always returns a validated `AgentSpecV2`.
 
 ```ts
-import { loadSpecV2, upgradeSpec } from 'lousho';
+import { loadSpecV2, upgradeSpec } from '@linuxdevil/lousho';
 
 const v1 = {
   name: 'support-bot',
diff --git a/docs/ai-sdk-ui.md b/docs/ai-sdk-ui.md
index 45a309764..6f5719182 100644
--- a/docs/ai-sdk-ui.md
+++ b/docs/ai-sdk-ui.md
@@ -18,7 +18,7 @@ The `vendor/` model prefix chooses the provider; with OpenRouter use
 `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent, fromUIMessages, memoryStore, toUIMessageStreamResponse, type UIMessageLike } from 'lousho';
+import { createAgent, fromUIMessages, memoryStore, toUIMessageStreamResponse, type UIMessageLike } from '@linuxdevil/lousho';
 
 // The store must outlive the request: without one, every `agent.session({ id })`
 // gets a fresh in-memory transcript and the next turn would start empty.
@@ -155,5 +155,5 @@ kept: a `system` message (or any other role, or an entry that is not a message)
 is dropped, so a caller cannot add instructions to the agent's prompt. Set
 instructions on the agent (`createAgent({ instructions })`), not in the request.
 
-A dedicated `lousho/ai-sdk-ui` subpath may follow; for now the
+A dedicated `@linuxdevil/lousho/ai-sdk-ui` subpath may follow; for now the
 functions come from the package root.
diff --git a/docs/api-overview.md b/docs/api-overview.md
index ac41b769a..bbfe2e48a 100644
--- a/docs/api-overview.md
+++ b/docs/api-overview.md
@@ -44,9 +44,9 @@ How the pieces fit:
 | Export                        | Description                                                                 |
 | ----------------------------- | --------------------------------------------------------------------------- |
 | `createAgent(config)`         | Zero-config `{ send(message) }` agent from a `model` string or provider (+ instructions, tools). |
-| `AgentBuilder` (from `lousho/executor`) | Fluent builder for an `AgentConfig` (`AgentBuilder.create().setName(...)...build()`). Advanced: see [the executor API](./executor-api.md). |
-| `AgentExecutor.execute(opts)` (from `lousho/executor`) | Static executor: runs an agent (LLM + tool-calling loop) and resolves to an `ExecutionResult`. Advanced: see [the executor API](./executor-api.md). |
-| `resumeAfterApproval()` (from `lousho/executor`) | Resume an execution paused for human approval. Advanced: see [the executor API](./executor-api.md). |
+| `AgentBuilder` (from `@linuxdevil/lousho/executor`) | Fluent builder for an `AgentConfig` (`AgentBuilder.create().setName(...)...build()`). Advanced: see [the executor API](./executor-api.md). |
+| `AgentExecutor.execute(opts)` (from `@linuxdevil/lousho/executor`) | Static executor: runs an agent (LLM + tool-calling loop) and resolves to an `ExecutionResult`. Advanced: see [the executor API](./executor-api.md). |
+| `resumeAfterApproval()` (from `@linuxdevil/lousho/executor`) | Resume an execution paused for human approval. Advanced: see [the executor API](./executor-api.md). |
 | `InMemoryApprovalStore`       | Process-local `ApprovalStore`; the default store of `createAgent()` agents. |
 | `StorageServiceApprovalStore`, `LocalStorageCheckpointStore` (from `/utils`) | File-backed approval and checkpoint stores over a `StorageService` (see [Approvals](./approvals.md), [Durable execution](./durable-execution.md)). |
 | `SqliteStore` (from `/sqlite`) | Sessions, checkpoints and approvals in one SQLite file (see [Sessions](./sessions.md#choosing-a-store)). |
@@ -74,8 +74,8 @@ resolves with the task prompt as `input` and the lead run's `sessionId`,
 `metadata` and `principal`.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const refund = defineTool({ name: 'refund', description: 'Refunds an order', input: z.object({ orderId: z.string() }), execute: async () => 'ok' });
@@ -104,14 +104,14 @@ when it is created.
 
 ### UI bindings
 
-`lousho/react` exports `useLoushoAgent(source, options?)`, a
+`@linuxdevil/lousho/react` exports `useLoushoAgent(source, options?)`, a
 React hook that runs an agent in process (`{ agent, sessionId? }`) or over HTTP
 (`{ url }`) and returns `messages`, `status`, `pendingApproval`,
 `send()`, `stop()`, `approve()` and `reject()`. Its framework-neutral parts,
 `reduceAgentEvents()` and `parseEventStream()`, are exported too. See
-[React](./react.md). `lousho/vue` exports the same
+[React](./react.md). `@linuxdevil/lousho/vue` exports the same
 `useLoushoAgent()` as a Vue 3 composable, with the state as refs. See
-[Vue](./vue.md). `lousho/svelte` exports `loushoAgent()`, the
+[Vue](./vue.md). `@linuxdevil/lousho/svelte` exports `loushoAgent()`, the
 same state and actions as a Svelte store (`$agent`). See [Svelte](./svelte.md).
 
 ### Sub-agents
@@ -209,7 +209,7 @@ See [Providers](./providers.md) for how a model string is resolved and which mod
 
 ## Testing
 
-Exported from `lousho/testing` (see [Testing agents](testing.md)).
+Exported from `@linuxdevil/lousho/testing` (see [Testing agents](testing.md)).
 
 | Export                | Description                                                                              |
 | --------------------- | ---------------------------------------------------------------------------------------- |
@@ -222,18 +222,18 @@ Exported from `lousho/testing` (see [Testing agents](testing.md)).
 | -------------------------------------------- | --------------------------------------------- |
 | `defineTool({ name, description, input, execute, ... })` | Define a tool; `execute`/`needsApproval` args are inferred from the zod `input`. Accepted by `createAgent({ tools: [...] })`, `ToolRegistry.register(tool)` and `AgentBuilder.addTool(tool)`. |
 | `ToolInput<typeof t>`, `ToolOutput<typeof t>` | Argument and result types of a defined tool. |
-| `ToolRegistry` (from `lousho/tools` or `lousho/executor`) | Holds the tools an agent config refers to (advanced: `register(tool)` or `register(name, descriptor)`). |
+| `ToolRegistry` (from `@linuxdevil/lousho/tools` or `@linuxdevil/lousho/executor`) | Holds the tools an agent config refers to (advanced: `register(tool)` or `register(name, descriptor)`). |
 | `httpTool`, `currentDateTool`, `dayNameTool` | Built-in tools.                               |
 | `createFsTools(fs, options?)`, `createShellTool(shell, options?)` | Workspace tools (`read_file`, `write_file`, `edit_file`, `list_dir`, `glob`, `grep`, `shell`) over an `FsProvider` / `ShellProvider`. See [Workspace tools](workspace-tools.md). |
 | `NodeWorkspace`, `MemoryWorkspace`, `SandboxShell` | Workspace providers: a real directory (paths confined to `root`, minimal shell env), an in-memory tree with a scripted `exec` for tests, and a `ShellProvider` over a `SandboxAdapter` (Docker). |
 | `createTodoTools({ store?, onChange? })`     | `todo_write` / `todo_read` tools (plus `getTodos()`) so agents can plan and track multi-step work; see [Todo tools](./tools.md#todo-tools). |
 | `connectMcp(servers, options?)`             | Connect MCP servers from config (stdio or HTTP) and load their tools; see [Share servers with `connectMcp()`](./mcp.md#share-servers-with-connectmcp). |
-| `loadMcpTools(client, connectionName)`       | Load a connected MCP server's tools as `ToolDescriptor`s. Available from the package root, `lousho/tools`, and `lousho/mcp`. |
+| `loadMcpTools(client, connectionName)`       | Load a connected MCP server's tools as `ToolDescriptor`s. Available from the package root, `@linuxdevil/lousho/tools`, and `@linuxdevil/lousho/mcp`. |
 
 See [Tools](./tools.md) for a guide to defining and registering tools.
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
@@ -259,7 +259,7 @@ execute }`) is legacy, still built for compatibility, and used only for
 descriptors that do not set `inputSchema` / `execute`.
 
 ```ts
-import { loadMcpTools } from 'lousho/mcp';
+import { loadMcpTools } from '@linuxdevil/lousho/mcp';
 
 const tools = await loadMcpTools(mcpClient, 'my-server');
 ```
@@ -286,7 +286,7 @@ warning naming the server, the tool and the reason, and `onSkip` to collect
 what was left out:
 
 ```ts
-import { loadMcpTools, type SkippedMcpTool } from 'lousho/mcp';
+import { loadMcpTools, type SkippedMcpTool } from '@linuxdevil/lousho/mcp';
 
 const skipped: SkippedMcpTool[] = [];
 const tools = await loadMcpTools(mcpClient, 'my-server', {
@@ -315,13 +315,13 @@ Token estimates, the model price table, and the usage and cost of a run: see [Mo
 
 ## Flows, evals, observability and security
 
-- `FlowBuilder` / `FlowExecutor` (`lousho/flows`) - multi-step
+- `FlowBuilder` / `FlowExecutor` (`@linuxdevil/lousho/flows`) - multi-step
   workflow graphs; see [Flows](./flows.md).
-- `TriggerAdapter` and `TriggerRegistry` (`lousho/triggers`) -
+- `TriggerAdapter` and `TriggerRegistry` (`@linuxdevil/lousho/triggers`) -
   the extension point for your own wake-up mechanism, plus `verifySlackSignature()`,
   `parseCronExpression()` and the `WebhookAuth` helpers; see [Triggers](./triggers.md).
 - `jwt()`, `oidc()`, `basic()`, `apiToken()`, `anonymous()` and `routeAuth()`
-  (`lousho/auth`) - route auth as an ordered list; the caller
+  (`@linuxdevil/lousho/auth`) - route auth as an ordered list; the caller
   it accepts reaches the run as `principal`; see [Route auth and principals](./auth.md).
 - `defineEval()`, scorers such as `exactMatch`, `toolCallOrder` and `budget`, checks such
   as `includes` and `atLeast`, and `llmJudge()` - agent evals run under vitest
@@ -329,7 +329,7 @@ Token estimates, the model price table, and the usage and cost of a run: see [Mo
 - `withSpan()` and `TraceExporter` - tracing for `AgentExecutor.execute()`.
   `TraceExporter` is a bring-your-own-exporter interface (no exporter
   ships by default); for real OpenTelemetry spans, import
-  `createOtelTraceExporter()` from the `lousho/otel`
+  `createOtelTraceExporter()` from the `@linuxdevil/lousho/otel`
   subpath (requires the optional peer dependency `@opentelemetry/api`)
   instead of hand-rolling the OTel bridge - see
   `examples/tracing/run-otel.ts`. Spans follow the OpenTelemetry GenAI
@@ -343,7 +343,7 @@ Token estimates, the model price table, and the usage and cost of a run: see [Mo
   `GenerateHookContext` - hooks that observe, deny, rewrite or redact tool calls
   and model calls. See [Hooks](./hooks.md).
 - `EncryptionUtils`, `sha256`, `StorageService`
-  (`lousho/utils`) - supporting utilities; see
+  (`@linuxdevil/lousho/utils`) - supporting utilities; see
   [Utilities](./utilities.md).
 
 ## Deployment
diff --git a/docs/approvals.md b/docs/approvals.md
index 01de151e3..3c6874dc8 100644
--- a/docs/approvals.md
+++ b/docs/approvals.md
@@ -10,7 +10,7 @@ See also: [Pause, restart, resume](./pause-and-resume.md), a short end-to-end tu
 > Snippets on this page leave some names to you: `provider` is any `LLMProvider` (offline: `createMockProvider()`); `agent` is a `createAgent()` result; `input` is the user's text, a `string`; `emailTool` is a tool built with `defineTool()`; `storage` is a `StorageService`; `toolRegistry` is a `ToolRegistry`.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
@@ -36,7 +36,7 @@ if (paused.finishReason === 'awaiting-approval') {
 arguments, typed from the tool's zod `input`:
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
@@ -89,7 +89,7 @@ error. `allow(tools)`, `deny(tools, reason?)` and `ask(tools)` build the
 common rules.
 
 ```ts
-import { allow, ask, createAgent, defineTool, deny, type PermissionRule } from 'lousho';
+import { allow, ask, createAgent, defineTool, deny, type PermissionRule } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const shell = defineTool({
@@ -168,7 +168,7 @@ session, each `send()` is its own transcript. Compacting away that message
 makes the tool ask again.
 
 ```ts
-import { createAgent, defineTool, once } from 'lousho';
+import { createAgent, defineTool, once } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const askOnce = once();
@@ -234,8 +234,8 @@ restart, give the agent a durable store, such as the SQLite one (see
 [Choosing a store](./sessions.md#choosing-a-store)):
 
 ```ts
-import { createAgent } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
+import { createAgent } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
 
 const store = new SqliteStore('./.lousho/agent.db');
 const agent = createAgent({ provider, tools: [emailTool], store }); // or approvalStore: store.approvals
@@ -269,7 +269,7 @@ The step's calls that need no approval do not wait: they run when the step
 does, before the pause.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' /* , tools: [payInvoice, archiveThread] */ });
 const paused = await agent.send('Pay the invoice and archive the thread');
@@ -311,7 +311,7 @@ decided.
   `approved: false`.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', tools: [emailTool] });
 const support = agent.session({ id: 'support-42' });
@@ -338,7 +338,7 @@ approval. There is no option on `resolve()` that ends the run. To stop that:
   model gets the reason and answers:
 
 ```ts
-import { createAgent, type AgentHook } from 'lousho';
+import { createAgent, type AgentHook } from '@linuxdevil/lousho';
 
 const noRefile: AgentHook = {
   name: 'no-refile',
@@ -369,7 +369,7 @@ is only on the audit entry (`onPermissionDecision`). An expired pause resolved
 with `approved: true` does not run the tool.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
@@ -436,7 +436,7 @@ Its argument's `principal` is whose call it is, and
 tool's `ctx.approval.by` (see [auth](./auth.md#who-approved)).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const trusted = createAgent({
   provider,
@@ -454,10 +454,10 @@ score, a timeout, a model error, arguments too long to judge — defers to a
 human exactly like `'defer'`. It never denies a call on its own.
 
 ```ts
-import { ask, createAgent, createAutoApprove, modelAutoApprover } from 'lousho';
+import { ask, createAgent, createAutoApprove, modelAutoApprover } from '@linuxdevil/lousho';
 
 declare const issueTool: any;
-declare const cheapProvider: import('lousho').LLMProvider;
+declare const cheapProvider: import('@linuxdevil/lousho').LLMProvider;
 
 const agent = createAgent({
   provider,
@@ -492,11 +492,11 @@ permissions:
 ```
 
 ```ts
-import { modelAutoApprover, specV2ToAgent } from 'lousho';
+import { modelAutoApprover, specV2ToAgent } from '@linuxdevil/lousho';
 
-declare const spec: import('lousho').AgentSpecV2;
+declare const spec: import('@linuxdevil/lousho').AgentSpecV2;
 declare const baseDir: string;
-declare const cheapProvider: import('lousho').LLMProvider;
+declare const cheapProvider: import('@linuxdevil/lousho').LLMProvider;
 
 const agent = await specV2ToAgent(spec, {
   baseDir,
@@ -523,7 +523,7 @@ is what `resolve()` resolves with. A continuation that pauses again ends with
 continues in that session, and `run.done` comes once the transcript is saved.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider, tools: [emailTool] });
 const paused = await agent.send('Email Sam the report');
@@ -560,7 +560,7 @@ approval: in sessions, in durable stores and across a restart.
   in tests and scripted agents.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'Plan the trip with the user.', provider, askQuestion: true });
 
@@ -597,8 +597,8 @@ tool. Resume later, after a real restart if you like, with
 `resumeAfterApproval()`:
 
 ```ts
-import { AgentExecutor, resumeAfterApproval } from 'lousho/executor';
-import { StorageServiceApprovalStore } from 'lousho/utils';
+import { AgentExecutor, resumeAfterApproval } from '@linuxdevil/lousho/executor';
+import { StorageServiceApprovalStore } from '@linuxdevil/lousho/utils';
 
 const approvalStore = new StorageServiceApprovalStore(storage);
 
diff --git a/docs/auth.md b/docs/auth.md
index af3a7081a..d38d9023e 100644
--- a/docs/auth.md
+++ b/docs/auth.md
@@ -1,7 +1,7 @@
 # Route auth and principals
 
 An agent served over HTTP needs to know two things about each request: may it
-call at all, and who is it. `lousho/auth` answers both. You
+call at all, and who is it. `@linuxdevil/lousho/auth` answers both. You
 give a route an ordered list of auth entries (`jwt()`, `oidc()`, `basic()`,
 `apiToken()`, `anonymous()` or your own function); the first entry that
 accepts the request returns a **principal**, and that principal goes into the
@@ -9,9 +9,9 @@ run, where your `model` / `instructions` / `tools` functions and memory scopes
 can read it.
 
 ```ts no-run
-import { createAgent, createRouteHandler } from 'lousho';
-import { apiToken, jwt } from 'lousho/auth';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createRouteHandler } from '@linuxdevil/lousho';
+import { apiToken, jwt } from '@linuxdevil/lousho/auth';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const agent = createAgent({
   provider: mockModel(['Hello!']),
@@ -83,7 +83,7 @@ exactly one key source:
 | `jwksUrl` | a JWKS endpoint (https, or http on localhost) | `RS256`, `ES256` by default; RSA and EC keys only |
 
 ```ts
-import { jwt } from 'lousho/auth';
+import { jwt } from '@linuxdevil/lousho/auth';
 
 const fromOurAuthServer = jwt({
   jwksUrl: 'https://auth.example.com/.well-known/jwks.json',
@@ -123,7 +123,7 @@ or http on `localhost` / `127.0.0.1` / `[::1]` — the same rule as `jwt()`'s
 `jwksUrl`). Algorithms default to `RS256` and `ES256`; HMAC is not allowed.
 
 ```ts
-import { oidc } from 'lousho/auth';
+import { oidc } from '@linuxdevil/lousho/auth';
 
 const google = oidc({ issuer: 'https://accounts.google.com', audience: process.env.GOOGLE_CLIENT_ID ?? 'client-id' });
 ```
@@ -139,7 +139,7 @@ carries `WWW-Authenticate: Basic realm="<realm>", charset="UTF-8"` so browsers
 show their login prompt.
 
 ```ts
-import { basic } from 'lousho/auth';
+import { basic } from '@linuxdevil/lousho/auth';
 
 const operators = basic({ users: { ops: process.env.OPS_PASSWORD! }, realm: 'agent' });
 // Or check against your own store (compare in constant time there):
@@ -168,7 +168,7 @@ Any function of the `Request` is an entry. Declare the challenges it answers a
 `401` with, or it advertises `Bearer`:
 
 ```ts
-import { AuthError, type AuthFn } from 'lousho/auth';
+import { AuthError, type AuthFn } from '@linuxdevil/lousho/auth';
 
 const tenantKey: AuthFn = async (request) => {
   const key = request.headers.get('x-tenant-key');
@@ -228,7 +228,7 @@ In an [agent directory](./agent-directories.md), put the list in `auth.ts` (or
 
 ```ts no-verify
 // my-agent/auth.ts
-import { apiToken, oidc } from 'lousho/auth';
+import { apiToken, oidc } from '@linuxdevil/lousho/auth';
 
 export default [
   oidc({ issuer: 'https://login.example.com', audience: 'agent-api' }),
@@ -258,8 +258,8 @@ The principal is on the run context next to `sessionId` and `metadata`. The
 `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent, defineMemory, inMemoryMemory, type Principal } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineMemory, inMemoryMemory, type Principal } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const notes = defineMemory({
   name: 'notes',
@@ -343,7 +343,7 @@ none in any of these places.
 ### In a tool
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 export const myOrders = defineTool({
@@ -364,8 +364,8 @@ from the request body or the model, and a tool cannot change it.
 ### Approval policies and permission rules
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const deploy = defineTool({
@@ -393,8 +393,8 @@ A decision can name who made it. The approved tool sees the decider as
 `ctx.approval.by`, next to `ctx.approval.note`:
 
 ```ts
-import { createAgent, defineTool, type Principal } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool, type Principal } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
@@ -464,8 +464,8 @@ see the example under [Who may decide an approval](#who-may-decide-an-approval))
 caller keeps the check stateless:
 
 ```ts
-import { createAgent, createRouteHandler, memoryStore } from 'lousho';
-import { jwt } from 'lousho/auth';
+import { createAgent, createRouteHandler, memoryStore } from '@linuxdevil/lousho';
+import { jwt } from '@linuxdevil/lousho/auth';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', store: memoryStore() });
 // The user id a session id starts with: everything before its last `-`. A prefix match would let
@@ -521,7 +521,7 @@ Behind a reverse proxy:
   rewrites `Host`, list the upstream name the proxy sends, not the public one.
 
 ```ts
-import { createAgent, createRouteHandler } from 'lousho';
+import { createAgent, createRouteHandler } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 
@@ -551,8 +551,8 @@ customer can no longer approve their own refund, and a supervisor can read any
 session (to see what they are approving) and decide in it:
 
 ```ts
-import { createAgent, createRouteHandler, memoryStore } from 'lousho';
-import { jwt } from 'lousho/auth';
+import { createAgent, createRouteHandler, memoryStore } from '@linuxdevil/lousho';
+import { jwt } from '@linuxdevil/lousho/auth';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', store: memoryStore() });
 const isSupervisor = (principal?: { claims?: Readonly<Record<string, unknown>> }) => principal?.claims?.role === 'supervisor';
@@ -574,8 +574,8 @@ claims, a manager decides them, and nobody approves their own:
 
 ```ts no-verify
 // my-agent/auth.ts
-import { apiToken } from 'lousho/auth';
-import type { ApprovalAccessRequest, SessionAccessRequest } from 'lousho';
+import { apiToken } from '@linuxdevil/lousho/auth';
+import type { ApprovalAccessRequest, SessionAccessRequest } from '@linuxdevil/lousho';
 
 export default [
   apiToken(process.env.ALICE_TOKEN!, { id: 'alice' }),
diff --git a/docs/build-a-coding-agent.md b/docs/build-a-coding-agent.md
index 8a09bcf50..08387b791 100644
--- a/docs/build-a-coding-agent.md
+++ b/docs/build-a-coding-agent.md
@@ -16,7 +16,7 @@ file system and a shell for it, and `createFsTools()` and `createShellTool()`
 turn it into tools.
 
 ```ts
-import { NodeWorkspace, createFsTools, createShellTool } from 'lousho';
+import { NodeWorkspace, createFsTools, createShellTool } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({ root: process.cwd() });
 const tools = [...createFsTools(workspace), createShellTool(workspace)];
@@ -41,7 +41,7 @@ per-tool map. For the shell, pass a predicate over the command string and gate
 only the commands you consider risky.
 
 ```ts
-import { NodeWorkspace, createFsTools, createShellTool } from 'lousho';
+import { NodeWorkspace, createFsTools, createShellTool } from '@linuxdevil/lousho';
 
 const DESTRUCTIVE = /\b(rm|mv|chmod|chown|git\s+(push|reset|clean|checkout))\b|>/;
 
@@ -73,7 +73,7 @@ written and `tool.start` announces each tool call (see
 [Streaming](./streaming.md)).
 
 ```ts
-import { NodeWorkspace, createAgent, createFsTools, createShellTool } from 'lousho';
+import { NodeWorkspace, createAgent, createFsTools, createShellTool } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({ root: process.cwd() });
 const agent = createAgent({
@@ -110,7 +110,7 @@ the rest of the work. That run can pause again, so loop until there is no
 
 ```ts
 import { createInterface } from 'node:readline/promises';
-import { createAgent, type AgentRun } from 'lousho';
+import { createAgent, type AgentRun } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You are a coding agent.' });
 const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -165,7 +165,7 @@ same pause handling.
 // coding.ts
 // Run: OPENAI_API_KEY=... npx tsx coding.ts "Fix the failing test"
 import { createInterface } from 'node:readline/promises';
-import { NodeWorkspace, createAgent, createFsTools, createShellTool, type AgentRun } from 'lousho';
+import { NodeWorkspace, createAgent, createFsTools, createShellTool, type AgentRun } from '@linuxdevil/lousho';
 
 const DESTRUCTIVE = /\b(rm|mv|chmod|chown|git\s+(push|reset|clean|checkout))\b|>/;
 
@@ -249,8 +249,8 @@ memory and takes a scripted `exec` for the shell, and `mockModel` plays the
 model. Assert on `workspace.snapshot()` and `workspace.commands`.
 
 ```ts
-import { createAgent, createFsTools, createShellTool, MemoryWorkspace } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createFsTools, createShellTool, MemoryWorkspace } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const workspace = new MemoryWorkspace({
   files: { 'math.js': 'exports.add = (a, b) => a - b;\n' },
@@ -277,8 +277,8 @@ To test the approval path, gate `write_file` the way the real agent does.
 runs the write and finishes the turn.
 
 ```ts
-import { createAgent, createFsTools, MemoryWorkspace } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createFsTools, MemoryWorkspace } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const workspace = new MemoryWorkspace({ files: { 'notes.txt': 'old\n' } });
 const agent = createAgent({
diff --git a/docs/channels.md b/docs/channels.md
index 4302b3577..98b916d20 100644
--- a/docs/channels.md
+++ b/docs/channels.md
@@ -43,7 +43,7 @@ const channels = mountFetchChannels(agent, [slack], { waitUntil: (turn) => void
 
 ```ts no-run
 import * as http from 'node:http';
-import { createAgent, createMockProvider, httpChannel, mountChannels } from 'lousho';
+import { createAgent, createMockProvider, httpChannel, mountChannels } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider() });
 const channels = mountChannels(agent, [
@@ -118,7 +118,7 @@ Discord, Telegram, Teams, GitHub) keeps its own answer and tells the user the
 request failed in the conversation.
 
 ```ts
-import { createAgent, defineChannel, mountChannels } from 'lousho';
+import { createAgent, defineChannel, mountChannels } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You answer text messages.', provider });
 
@@ -202,7 +202,7 @@ dropped silently once the surface was acknowledged. `resolveApproval()`
 throws `LOUSHO_APPROVAL_CONFLICT` for an approval another request is deciding.
 
 ```ts
-import { createAgent, defineChannel, mountChannels } from 'lousho';
+import { createAgent, defineChannel, mountChannels } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You are helpful.', provider, askQuestion: true });
 
@@ -247,7 +247,7 @@ the verified request (the alerting system that sent the hook, an integration
 user); `body` is the parsed JSON body, `undefined` when it is not JSON.
 
 ```ts
-import { createAgent, httpChannel, mountChannels, webhookChannel } from 'lousho';
+import { createAgent, httpChannel, mountChannels, webhookChannel } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You are helpful.', provider });
 
@@ -340,7 +340,7 @@ Set up the app at [api.slack.com/apps](https://api.slack.com/apps):
 
 ```ts
 import * as http from 'node:http';
-import { createAgent, mountChannels, slackChannel } from 'lousho';
+import { createAgent, mountChannels, slackChannel } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You are a helpful Slack bot.', provider });
 
@@ -415,7 +415,7 @@ curl -X POST "https://discord.com/api/v10/applications/$APP_ID/guilds/$GUILD_ID/
 
 ```ts
 import * as http from 'node:http';
-import { createAgent, discordChannel, mountChannels } from 'lousho';
+import { createAgent, discordChannel, mountChannels } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You are a helpful Discord bot.', provider });
 
@@ -499,7 +499,7 @@ curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" -H "Co
 
 ```ts
 import * as http from 'node:http';
-import { createAgent, mountChannels, telegramChannel } from 'lousho';
+import { createAgent, mountChannels, telegramChannel } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You are a helpful Telegram bot.', provider });
 
@@ -551,7 +551,7 @@ so it also runs on Workers.
   them somewhere shared and durable, e.g. Redis `SET NX EX`:
 
   ```ts
-  import { githubChannel, type DeliveryStore } from 'lousho';
+  import { githubChannel, type DeliveryStore } from '@linuxdevil/lousho';
 
   const seenIds = new Set<string>(); // stands in for Redis or a database table
   const deliveries: DeliveryStore = { seen: (id) => seenIds.has(id) || (seenIds.add(id), false) };
@@ -652,7 +652,7 @@ agent from answering its own comments.
 
 ```ts
 import * as http from 'node:http';
-import { createAgent, githubChannel, mountChannels } from 'lousho';
+import { createAgent, githubChannel, mountChannels } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You answer questions about this repository.', provider });
 
@@ -748,7 +748,7 @@ Set up the bot:
 
 ```ts
 import * as http from 'node:http';
-import { createAgent, mountChannels, teamsChannel } from 'lousho';
+import { createAgent, mountChannels, teamsChannel } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You help the team with questions.', provider });
 
diff --git a/docs/claude-projects.md b/docs/claude-projects.md
index c2712c403..19d2084e0 100644
--- a/docs/claude-projects.md
+++ b/docs/claude-projects.md
@@ -7,8 +7,8 @@ into `createAgent()`, so the same directory drives both harnesses. Nothing is
 copied or renamed; Lousho reads the files where they already are.
 
 ```ts no-run
-import { createAgent, claudeProject } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, claudeProject } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const provider = mockModel([{ text: 'ok' }]);
 
@@ -65,8 +65,8 @@ task-shaped notes, hooks can pause on `scratchpad` writes like any tool.
 ## Options
 
 ```ts no-run
-import { claudeProject } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { claudeProject } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const provider = mockModel([{ text: 'ok' }]);
 
diff --git a/docs/cli.md b/docs/cli.md
index 7d01e8624..816381b01 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -1,597 +1,616 @@
-# CLI
-
-Installing the package also installs the `lousho` command. It scaffolds
-projects, checks your setup, runs an agent locally, serves it over MCP, runs
-evals, shows saved traces, builds a deployable artifact and launches the Agent Forge dashboard.
-Run it with `npx lousho <command>` inside a project that has the SDK installed.
-
-| Command | What it does | Details |
-| ------- | ------------ | ------- |
-| `lousho 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) |
-| `lousho doctor [spec\|agent-dir\|agent.ts] [--json] [--ping]` | Check Node, peer packages, provider keys, and optionally a spec file, agent directory or agent module (its provider's key is then required); `--ping` also checks each configured provider endpoint answers and accepts the key. Prints a fix for every problem. | [Installation](./installation.md#troubleshooting-lousho-doctor) |
-| `lousho dev <path>` | Local dev server for a spec file, an agent directory or a TS agent: chat UI with a session per tab and streamed events, hot reload on save. | [Below](#lousho-dev) |
-| `lousho chat <path>` | Terminal REPL for a spec file, an agent directory or a TS agent: streams replies, shows tool calls, asks for approvals and questions. | [Below](#lousho-chat) |
-| `lousho acp <path>` | Serve a spec file, an agent directory or a TS agent to an editor (Zed and other ACP clients) over the Agent Client Protocol on stdio. | [ACP](./acp.md) |
-| `lousho add <name>` | Install a tool, skill, channel, schedule or memory slot from a JSON registry into an agent directory, after showing its permission manifest and checking the code against it. | [Registry](./registry.md) |
-| `lousho mcp <spec>` | Serve the agent as an MCP server (stdio, or HTTP with `--http`). | [MCP](./mcp.md#serve-an-agent-over-mcp) |
-| `lousho eval [globs...]` | Run `*.eval.ts` files under vitest; print a summary and write JUnit/JSON reports. | [Evals](./evals.md#lousho-eval) |
-| `lousho traces [id]` | List the recent runs saved by `fileTraceExporter()` (duration, model and tool calls, tokens, cost), or print one run as a span tree. | [Observability](./observability.md#local-traces) |
-| `lousho build --target=<t> --agent=<spec>` | Build a deployable Node server, Docker image or Cloudflare Worker. | [Deployment](./deployment.md) |
-| `lousho studio` | Launch Agent Forge, the visual dashboard, on one local port. | [Agent Forge](./agent-forge.md) |
-| `lousho improve <path> --check <module>` | Experimental. Run one self-healing cycle on an agent directory: propose edits to its instructions and skills from failed runs in your local observe database, gate them, replay them on fresh runs, and apply (auto mode, the default) or queue (manual mode) one that passes. `--watch` keeps it running; `pause`, `status`, `rollback`, `approve` and the other subcommands manage it. `--dry-run` prints the review card and applies nothing. | [Below](#lousho-improve) |
-
-Every command that takes a `<spec>` reads an agent spec file (`.yaml`,
-`.yml` or `.json`, see [Configuration](./configuration.md#agent-spec-files-agentspec)).
-
-## Usage
-
-```text
-lousho init [dir] [--provider P] [--template T] [--yes] [--no-install] [--no-git] [--package-manager PM] [--force] [--sdk-path <dir|tgz>]
-lousho dev <spec.yaml|spec.json|agent-dir|agent.ts> [--port N] [--host H] [--allowed-hosts a,b] [--no-schedules] [--traces[=dir]]
-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|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|agent.ts] [--json] [--ping]
-lousho eval [globs...] [--tag t] [--junit path] [--json path] [--strict] [--judge] [--record | --replay | --drift [--drift-usage]] [--url <base> [--token <bearer>]] [--config vitest.config.ts] [--timeout <ms>]
-lousho traces [traceId|prefix] [--dir D] [--limit N] [--json] [--content]
-lousho observe <start|status|stop|rebuild-rollups|prune|export|failures|token> [--port N] [--db path] [--host H] [--require-token] [--project X] [--webhook URL] [--retention-days N] [--session-idle-minutes N] [--older-than <N>d] [--since <N>d|<N>h|<N>m] [--agent X] [--out file]
-lousho prompt <push <file|->|list|get <name[@version|@label]>|label <name> <label> <version>> [--url U] [--port N] [--token T] [--json] [--name N] [--labels a,b] [--variables x,y]
-lousho improve <agent-dir|agent.ts> --check <module> [--model provider/model] [--editor provider/model] [--db path] [--since <N>d|<N>h|<N>m] [--agent X] [--protect traceId]... [--read-only tool]... [--max-tokens n] [--out file] [--with-recoveries] [--approval auto|manual] [--proposers 1-4] [--mode agg|seq] [--select] [--no-parallel-editors] [--dry-run] [--watch [--interval 15m]]
-lousho improve <revisions|rollback|audit|pending|approve|reject|pause|resume|status> <agent-dir> ...
-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` (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:
-it takes it only in the `=` form (`--traces=./t`), so `--traces agent.yaml` is
-still the flag followed by the path.
-
-**Exit codes.** Every command exits 0 on success, 1 when it ran and failed
-(an agent that cannot load, a build error, `lousho eval`'s gate failure, no
-matching trace, `lousho add` refusing an item without `--yes`), and 2 for a
-usage error: an unknown command, an unknown flag, a missing or invalid
-value, an extra argument, or a missing `--target` or agent path. `lousho build` prints where it wrote the build (default
-`.lousho/build/<target>`) and the command to run there.
-
-**`.env`.** The commands that run an agent (`dev`, `chat`, `acp`, `mcp`),
-`doctor`, `eval` (judge evals need provider keys) and `build` load `./.env` from the working directory when it exists, like
-`node --env-file-if-exists=.env`: a variable already set in the environment
-wins over the file. A UTF-8 byte order mark at the start of the file (which
-PowerShell 5.1's `Set-Content -Encoding utf8` writes) is ignored.
-
-`lousho init` is the exception: it parses its own flags, and a bad flag or
-value fails with `InitUsageError` — its message printed as-is, exit code 2 —
-not the shared `LOUSHO_CONFIG_INVALID` path. The only short flags besides
-`-h` are `-y` for `--yes`, on `init` and on `add`.
-
-`lousho eval` also takes `--config <file>` to run under your own vitest config
-instead of the generated one; globs then narrow that config's files as vitest
-filters.
-
-`npm create lousho my-agent` runs `lousho init` with the same arguments.
-To scaffold against an unreleased build of the SDK, pass `--sdk-path` (see
-[Installing from a local build](./installation.md#installing-from-a-local-build)).
-
-## `lousho dev`
-
-```bash
-npx lousho dev agent.yaml                  # a spec file
-npx lousho dev ./my-agent                  # an agent directory
-npx lousho dev src/agent.ts                # a TypeScript (or JavaScript) module
-npx lousho dev agent.yaml --port 4000 --host 0.0.0.0
-npx lousho dev ./my-agent --no-schedules   # do not fire cron schedules or a spec's cron triggers
-```
-
-For an agent directory, `channels/` are mounted under `/channels` and
-`schedules/` are started (and both are swapped on reload, the old schedules
-stopped first); `--no-schedules` starts none. See
-[Agent directories](./agent-directories.md#run-it-with-lousho-dev).
-
-Serves a chat UI on `GET /`, `GET /health`, `GET /dev/status` and the chat
-endpoints below (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`, `.cts`, `.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 (`LOUSHO_SPEC_UNSUPPORTED_FORMAT`, `LOUSHO_CONFIG_INVALID`)
-and its fix. A `.ts` module is imported by the running Node (22.18 or later
-strips types, so relative imports need their file extension); use `.js` for
-code that needs a transpiler.
-
-**Chat sessions.** The chat UI keeps one session per browser tab (its id is in
-`sessionStorage`; "New session" starts another) and shows the streamed turn:
-text as it arrives, tool calls with their arguments and results, errors, and
-tokens and cost from `run.done`. A tool call that needs approval shows
-Approve / Reject buttons; an `ask_question` call shows its options as buttons
-plus a free-text field. The same endpoints work from `curl` or your own page:
-
-| Endpoint | What it does |
-| -------- | ------------ |
-| `POST /chat` `{ "sessionId", "input" }` | Runs `agent.session({ id: sessionId }).stream(input)` and streams the turn as SSE: one `data: <AgentEvent JSON>` per event ([Streaming](./streaming.md)), then `event: done`. History is kept per `sessionId` (1-128 characters of `A-Za-z0-9_-`). |
-| `GET /chat/:sessionId` | The session's transcript: `{ sessionId, messages, pending }`; `pending` is `{ status, approvalId? }` while a turn waits on an approval, else `null`. A turn's messages are saved when it finishes, so while it is paused `messages` does not hold that turn yet: use `pending`. |
-| `POST /chat/:sessionId/approvals/:id` `{ "approved", "note"? }` or `{ "answer" }` | Decides the pending approval (`agent.approvals.streamResolve()`), or answers a question (`agent.approvals.streamAnswer()`), and streams the continued turn as SSE. It can pause again with another `approval.requested`. `404` when `id` is not pending. When the turn's step paused on several calls, each id is decided on its own; a decision that leaves others pending streams `run.done` with `finishReason: 'awaiting-approval'`, and the last one runs the step. |
-| `POST /chat` `{ "message" }` | Deprecated: no session, no streaming. Returns the agent's `ExecutionResult` as JSON, with a `Deprecation: true` header. |
-
-`--traces` (or `--traces=<dir>`) writes every run to local trace files with
-`fileTraceExporter()`, in `.lousho/traces` unless you name a directory, so
-`npx lousho traces` shows what the agent did. It is off by default because the
-files hold prompt, tool argument and tool result content, and the flag prints
-the directory it writes to. It applies to spec files, agent directories and
-modules alike (a module's own `exporter` is replaced while the flag is set).
-See [Local traces](./observability.md#local-traces).
-
-Sessions live in an in-process `memoryStore()` (gone when `lousho dev` stops),
-or in the agent's own `store` when a module's `createAgent()` options set one.
-The continuation of an approval is streamed too: the endpoint runs it with
-`agent.approvals.streamResolve()` (or `streamAnswer()` for a question) and
-sends the continued turn's events — the decided tool call, text deltas, a
-further pause and `run.done` — as they happen.
-
-`lousho build` servers (`node-server`, `docker`) serve these same endpoints from
-the same code, with sessions in a store chosen by `LOUSHO_STORE` and optional
-bearer auth: see [Deployment: HTTP API](./deployment.md#http-api).
-
-**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, 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
-is logged and shown in a banner on the chat page (and as `error` in
-`GET /dev/status`); the next good edit clears it. Sessions survive a reload: the
-store outlives the agent swap, so the next message continues the conversation
-on the new agent. An approval that was pending on the old agent is not known to
-the new one (`404`); start a new session.
-
-Directories and modules are your code and run with your permissions; only run
-`lousho dev` on ones you trust.
-
-- `--port` - default `3737`.
-- `--host` - default `127.0.0.1` (localhost only). Pass e.g. `--host=0.0.0.0`
-  to opt in to LAN access; `lousho dev` has no auth and shows raw provider
-  errors, so it then prints a warning.
-- `--allowed-hosts a,b` - extra host names the `Host` header may carry. To
-  stop DNS rebinding (a web page re-pointing its own domain at your machine),
-  every route but `/health` and the channels that `verify` their requests
-  answers `403` (`LOUSHO_REQUEST_FORBIDDEN`) unless `Host` is `localhost`, a
-  `127.x.x.x` address or `[::1]`; off loopback, IP addresses and the `--host`
-  name are accepted too. The list adds to that rule (a tunnel's name, e.g.);
-  `*` accepts any host. A channel without `verify` (`httpChannel()` with no
-  `verify`) is checked like the dev routes, so reach it through a tunnel only
-  with its name in the list.
-- POST bodies must be `Content-Type: application/json` (`415` otherwise), and
-  a browser POST from another origin is `403`, as on the deployed server
-  ([Cross-site requests](./auth.md#cross-site-requests)).
-
-## `lousho chat`
-
-```bash
-npx lousho chat agent.yaml                          # a spec file
-npx lousho chat ./my-agent --model openai/gpt-4o    # an agent directory, on another model
-npx lousho chat src/agent.ts --store sqlite:.lousho/chat.db --session support
-```
-
-A terminal REPL: each line you type is one turn of a session. `<path>` is
-loaded like `lousho dev` loads it (spec file, agent directory or `.ts`/`.js`
-module, see [`lousho dev`](#lousho-dev)); a missing path or bad extension fails
-with the same coded error (`LOUSHO_CONFIG_INVALID`,
-`LOUSHO_SPEC_UNSUPPORTED_FORMAT`), and so does an invalid `--session` id
-(`LOUSHO_SESSION_ID_INVALID`).
-
-```text
-> look up cats
-[lookup] {"q":"cats"}
-  -> found cats
-Cats are great.
-[usage] 20 in / 6 out tokens, $0.0004
-> email the report to sam
-Approve send_email({"to":"sam@example.com"})? [y/N] y
-  -> sent
-Done, the report is on its way.
-```
-
-- Text is written as the model produces it. Each tool call is one dim line,
-  `[tool_name] {args}`, followed by `  -> result` (or `  -> error: ...`).
-- A tool call that needs approval asks `Approve <tool>(args)? [y/N]`: `y` or
-  `yes` runs it, anything else rejects it and the model carries on. An
-  `ask_question` call (`askQuestion: true`) prints the question with numbered
-  options; answer with the number or with free text.
-- After each turn `[usage]` shows the tokens and, when every model used has
-  known pricing, the cost (`~` marks estimated tokens).
-- Errors from the SDK print with their `[LOUSHO_...]` code and fix, and the
-  session continues. A provider failure also names its category and HTTP
-  status, e.g. `error: User not found. (auth-failure, HTTP 401)` for a wrong
-  API key.
-- `--traces` or `--traces=<dir>` writes the session's runs to local trace files,
-  as for `lousho dev`; a line on stderr says where.
-
-| Command | What it does |
-| ------- | ------------ |
-| `/new` | Start a new session (the old one is kept in the store). |
-| `/model <provider/model>` | Rebuild the agent on another model; the session continues. A failure keeps the current model. |
-| `/compact` | Compact the session's transcript now (old tool results are pruned) and print the before/after size. |
-| `/clear` | Empty the session's transcript; the session id stays. |
-| `/history` | Print the session's transcript. |
-| `/quit` | Leave (Ctrl-D works too). |
-
-| Option | Meaning |
-| ------ | ------- |
-| `--model provider/model` | Use this model instead of the one the target names. Applies to spec files, agent directories and `createAgent()` options exports; a module that exports an already built agent keeps its model. The `vendor/` model prefix chooses the provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o`). |
-| `--session id` | Open this session (1-128 characters of `A-Za-z0-9_-`); default is a new `chat-<id>`. |
-| `--store sqlite:<file>` | Keep sessions in a SQLite file ([`SqliteStore`](./durable-execution.md)), so `--session id` continues a conversation after a restart. Default: in memory. Pending approvals are not restored after a restart. |
-
-The REPL itself is `runChatRepl()` in `src/cli/chatRepl.ts`; it takes the
-input lines, an output stream and an agent factory, so it can be tested with
-scripted lines and a `mockModel` agent and no terminal.
-
-## `lousho build`
-
-```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
-the command to run or deploy it. Building needs `tsup`
-(`npm install --save-dev tsup`). Targets, the HTTP API they serve and the
-Workers limits are in [Deployment](./deployment.md).
-
-## `lousho studio`
-
-```bash
-npx lousho studio            # prints http://127.0.0.1:4750/?token=<per-launch token>
-npx lousho studio --port 5000
-```
-
-Starts one local server for the Agent Forge API and UI. Agents and run state
-are stored under `.lousho/` in the current directory. The app has a left
-navigation: Agents (the builder) and Playground, then Traces, Threads and
-Monitoring, Evaluations (Scores, Datasets, Evaluators, Annotation queues),
-Prompts, Context Hub and Settings; everything past the Playground reads the
-`lousho observe` daemon. See [Agent Forge](./agent-forge.md) for the screens
-and the walkthrough.
-
-## `lousho observe`
-
-```bash
-npx lousho observe start                        # collector on http://127.0.0.1:7777
-npx lousho observe status                       # health + fleet counts
-npx lousho observe stop                         # <db>.pid + SIGTERM (checks the daemon serves --db)
-npx lousho observe rebuild-rollups              # recompute insight aggregates
-npx lousho observe prune --older-than 30d       # delete finished runs older than 30 days, then VACUUM
-npx lousho observe export --since 7d --out runs.jsonl # traces as JSONL, one per line
-npx lousho observe failures --since 7d          # recurring tool and model failures, by agent
-npx lousho observe failures --traces .lousho/traces --json # the same from trace files, no database
-npx lousho observe score --agent support        # continuous score, pass rate and trajectory gate state
-npx lousho observe token create --project myapp # bearer key for non-loopback auth
-```
-
-Runs the local collector every agent reports to when `LOUSHO_OBSERVE` is
-set: traces, fleet monitoring, eval scores, the prompt registry and the
-context hub in one SQLite file (default `~/.lousho/observe.db`). Studio's
-[daemon screens](./agent-forge.md#screens) read it. `start` takes
-`--port` (or `LOUSHO_OBSERVE_PORT`), `--db`, `--host`, `--require-token`
-and a repeatable `--webhook` for alert hooks. Each daemon writes its own `<db name>.pid` beside the db
-(`observe.db` gives `observe.pid`), so two dbs in one folder never share a
-pidfile. `start` exits 1 when the port already serves a different db, and
-`stop` refuses to signal when the daemon at the pidfile's port reports another
-db or the port answers as a different service, and falls back to signalling
-when it cannot verify (unreachable, or an old one-line pidfile). `/health`
-tells which db a daemon serves only to callers on the same machine. See
-[The observe daemon](./observability.md#the-observe-daemon).
-
-`start --retention-days N` sets how long finished runs are kept (default 30;
-`0` keeps everything). Once a day the daemon deletes traces whose
-observations all finished more than N days ago. A trace with any run still
-open, and a session that is still `active`, is kept whatever its age. Rollups,
-prompts and hub entries are never pruned. `prune --older-than <N>d` (whole
-days, N >= 1) does the same pass now, prints the observation, score and session
-counts it deleted, and then runs `VACUUM` to reclaim disk space (the daily pass
-never does). If only the `VACUUM` fails (for example, the db is busy), the
-prune stays committed, the error goes to stderr and the exit code is 0. It is
-safe to run while the daemon is up. A bad N is a usage
-error (exit 2). See [Retention](./observability.md#retention).
-
-`start --session-idle-minutes N` sets when a conversation counts as finished
-(default 30; `0` turns it off, so a session stays `active` until its agent goes
-down). The daemon's sweep marks a session `ended` once none of its runs is
-still open (a run marked `interrupted` does not count) and nothing in it has started or finished for N minutes; its
-`ended_at` is the time of that last activity. A new run in an `ended` (or
-`interrupted`) session makes it `active` again. Ended sessions are then pruned
-by `--retention-days` like any other finished session. A bad N is a usage
-error (exit 2). See [Idle sessions](./observability.md#idle-sessions).
-
-`export` writes traces as JSONL: one line per trace, `{ trace, observations,
-scores }` (the same rows the trace API returns), oldest first, with no cap on
-how many. `--since <N>d` (or `<N>h`, `<N>m`) keeps traces that started within
-that window; `--agent X` keeps one agent, matched by `agent_id` or, when no
-agent has that id, by its registered name (a name shared by two agents is a
-usage error, exit 2). Without `--out` the lines go to stdout and nothing else
-does (the count goes to stderr, so a pipe stays clean); `--out file` creates or
-overwrites the file and prints the count to stdout. It reads the db directly, so
-no daemon needs to be running. See [Export](./observability.md#export).
-
-## `lousho prompt`
-
-```bash
-npx lousho prompt push prompt.md --name mira    # publishes a new version
-npx lousho prompt list
-npx lousho prompt get mira@latest
-npx lousho prompt label mira prod 3             # mira@prod -> 3 (was 2)
-npx lousho prompt get mira@prod
-```
-
-Publishes and reads prompt versions in the observe daemon's registry. Agents
-resolve them with `createAgent({ prompt: 'mira@latest' })` (or a label,
-`'mira@prod'`) or `LOUSHO_PROMPT`.
-
-- `push` publishes the file (`-` reads stdin) as the next version. A push
-  whose text and `--variables` equal the latest version's mints nothing and
-  prints `mira@2 is unchanged` (exit 0). `--labels prod,canary` points those
-  labels at the resulting version, the new one or the unchanged latest.
-- `get <name>[@ref]` prints a version's text; `ref` is an integer, `latest`
-  (the default) or a label. `--json` prints the row, whose `labels` are the
-  labels currently pointing at that version.
-- `label <name> <label> <version>` moves a label: a label points at exactly
-  one version, so this takes it off the one that held it, and prints
-  `mira@prod -> 3 (was 2)` (or `(was unset)` for a new label). A label is a
-  name without whitespace, `@` or `/`, and not `latest` or all digits. See [The observe daemon](./observability.md#the-observe-daemon).
-
-## `lousho improve`
-
-Experimental, like the [`improveAgent()`](./improve.md) it runs.
-
-```bash
-npx lousho improve ./my-agent --check ./check.mjs --since 7d --out proposal.md
-```
-
-```js
-export default (input, answer) => !answer.includes('I cannot help');
-```
-
-It takes the failed runs in your local observe database (default
-`~/.lousho/observe.db`, or `--db`), replays each recorded input through the
-agent, scores each answer with your check, and prints the review card from
-`formatImproveResult()`. On an agent directory it then runs one self-healing
-cycle with `healOnce()`: only failed runs of the current harness revision count,
-a proposal that passes the gate is replayed on fresh runs (the canary), and in
-auto mode (the default) it is written to `instructions.md` and
-`skills/<name>/SKILL.md`, after which the corpus guard replays the protected
-cases and rolls back on a regression. In manual mode it is queued for
-`lousho improve approve`. Every step is audited, and `improve.json`'s daily caps,
-the cooldown after a rollback and the `.lousho/improve.stop` kill switch apply.
-`--dry-run` keeps the old behaviour: every failed run counts, the card is
-printed, and nothing is written. An agent module, or an agent whose instructions
-don't live in `instructions.md`, always runs dry.
-
-- `<path>` is an agent directory or a `.ts`/`.js` agent module whose
-  instructions are plain text. Editors may change only the instructions and
-  skills.
-- `--check <module>` is required. Its default export is a `CaseCheck`,
-  `(input, answer) => boolean | null | { passed, failure? }`; `null` means the
-  answer can't be scored. Return `{ passed: false, failure }` to name the check
-  a failed answer missed: the editors read it in that run's record, and without
-  it a failed run whose answer looks right gives them nothing to fix.
-  `input` is the user's message for a one-message run, else the recorded
-  messages as JSON text.
-- `--since` and `--agent` pick which failed runs become cases, as for
-  `lousho observe export`.
-- `--protect <traceId>` names a run that went well. It joins the gate only
-  after it passes 6 of 6 fresh runs; otherwise stderr says why it was left out.
-  A trace that is also a failed run stays a case to learn from.
-- Tools are simulated during replays, except `load_skill` and
-  `read_skill_file`. `--read-only <tool>` lets a tool that is safe to call
-  again run for real. Replays aren't traced: `LOUSHO_OBSERVE`, the agent's
-  `exporter` and `onEvent` are off while it runs, so they never reach your
-  database.
-- `--model` runs the agent on another model; `--editor` picks the editors'
-  model (default `--model`, else the agent's own).
-- `--out file` also writes the card, or the JSON result for a `.json` path. It
-  must be a new file, outside the agent's files.
-- `--max-tokens <n>` passes `maxTokens` to `improveAgent()`: it stops once `n`
-  tokens are spent on agent runs and editor calls. The total is checked after
-  each run or editor call, so the last one can go over. The card and the JSON
-  then report `budget-exceeded` with the reason, nothing is proposed, and
-  stderr suggests raising it. `n` must be a positive integer; anything else is
-  a usage error (exit 2). It is unset by default, so there is no cap. The runs
-  that admit `--protect` traces happen before and don't count toward it.
-- `--with-recoveries` also shows the editors, for each failed run, the
-  `<id>.heal` fork from `agent.recover()` that finished and whose answer passes
-  `--check`, if there is one. It's evidence only: it never counts as a run and
-  never protects a case, and a fork you `--protect` is left out. See
-  [Recovery forks as evidence](./improve.md#recovery-forks-as-evidence).
-- `--approval auto|manual` sets the approval mode, over the
-  `LOUSHO_IMPROVE_APPROVAL` variable, which wins over `"approval"` in
-  `improve.json` beside the agent. The default is `auto`. In `manual` mode an
-  edit that quotes a failed check word for word is kept and flagged on the card
-  for the person who approves it; in `auto` mode it is sent back to the editor
-  once and then dropped. An `improve.json` that doesn't validate stops the
-  run. See [Approval modes](./improve.md#approval-modes).
-- `--proposers <1-4>`, `--mode agg|seq`, `--select` and
-  `--no-parallel-editors` set the cycle's
-  [Harness² options](./improve.md#harness-options), over the `editors` block in
-  `improve.json`. `--select` can only turn the selector on and
-  `--no-parallel-editors` can only turn parallel off. `--proposers k` runs k invariant and k domain editors (or k
-  rounds with `--mode seq`), and costs about k times the editor sessions and
-  proposal runs. `--select` gates every candidate and lets the advisory selector
-  choose among those that pass. `--no-parallel-editors` runs the editors and
-  their probes one at a time, for a rate-limited model. They apply to dry runs
-  and `--watch` too.
-- `--dry-run` writes nothing: no apply, no queue, no audit entry. It reads
-  every failed run whatever its revision, and ignores the kill switch and the
-  daily caps.
-- `--watch` keeps running cycles on a timer; `--interval` (default `15m`, as
-  `<N>s`, `<N>m` or `<N>h`) sets the spacing. It needs an agent directory, takes
-  its budget from `improve.json`, and can't be combined with `--dry-run`,
-  `--max-tokens` or `--out`. See below.
-
-Before it starts, a cycle prints its approval mode and whether it applies or
-queues; a dry run prints how many runs it will make at least, and the token
-budget if any. Every run and every editor call is billed to your models.
-`--max-tokens` caps one cycle within `improve.json`'s daily caps.
-It exits 1 on an `outage`: no run could be scored, or the editors' provider
-failed. A `budget-exceeded` run exits 0, since you set the cap. Each run's error goes to
-stderr. It reads nothing but your own database. See [Improving an agent](./improve.md#from-the-command-line).
-
-### Revisions, rollback and the audit log
-
-Every change to an agent directory's `instructions.md` and
-`skills/<name>/SKILL.md` made through `applyProposal()` is saved as a revision
-under `.lousho/revisions/` and recorded in the hash-chained
-`.lousho/audit.jsonl`. Three subcommands read and undo that history:
-
-```bash
-npx lousho improve revisions ./my-agent
-npx lousho improve rollback ./my-agent --by ali --reason "answers got worse"
-npx lousho improve audit ./my-agent --verify
-```
-
-- `revisions <dir> [--json]` lists the saved revisions, newest first, with their
-  source (`baseline`, `apply` or `rollback`), who made them and when. `*` marks
-  the one the directory holds now.
-- `rollback <dir> --by <name> [--to <revision>] [--reason text]` restores a
-  saved revision through the same writer as an apply: it changes only
-  instructions and skills, makes a new revision and writes one `rollback` audit
-  entry. It never rewrites history. Without `--to` it goes to the parent of the
-  current revision. It refuses instead when the current revision came from a
-  rollback, or when the directory holds hand edits that match no revision; pass
-  `--to` then. A hand edit that a rollback replaces is saved as a revision
-  first. `--to` takes an id or a unique prefix of at least 4 characters. `--by`
-  is required. If an apply lands between your command and the write, the
-  rollback is refused as stale.
-- `audit <dir> [--verify] [--json]` prints the audit log, oldest first.
-  `--verify` checks the hash chain and exits 1 at the first edited, removed or
-  truncated line.
-
-A directory literally named `revisions`, `rollback`, `audit`, `pending`,
-`approve`, `reject`, `pause`, `resume` or `status` must be passed as
-`./revisions` and so on.
-
-### Pending proposals (manual mode)
-
-In manual mode a proposal that passed the gate waits in
-`.lousho/proposals/<id>.json` until a person decides:
-
-```bash
-npx lousho improve pending ./my-agent
-npx lousho improve approve ./my-agent 3f9c0a1b2d4e --by ali --check ./check.mjs
-npx lousho improve reject ./my-agent 3f9c0a1b2d4e --by ali --reason "too broad"
-```
-
-- `pending <dir> [--show <id>] [--json]` lists the queue, newest first, marking
-  stale and refused entries. The id is the first 12 characters of the proposed
-  harness's hash, and a file whose content doesn't match its id is left out.
-  `--show <id>` prints that proposal's review card.
-- `approve <dir> <id> --by <name> [--check <module>] [--model provider/model]
-  [--read-only tool]... [--no-guard] [--db path]` applies the proposal through
-  `applyProposal()` as that person's approval and removes it from the queue.
-  With `canary.traffic` set, it starts the
-  [traffic canary](./improve.md#live-traffic-canary-opt-in) instead and writes
-  nothing yet, reading the observe database at `--db` (default
-  `~/.lousho/observe.db`); the proposal is applied as that approval when the
-  canary passes, and the watcher guards it then. A
-  proposal whose agent directory changed since it was made is refused and
-  marked stale; run improve again. Any other refusal is recorded on the entry
-  and shown by `pending`. Right after the write it runs the corpus guard, as an
-  automatic apply does: `guard.runs` fresh runs of every corpus case, scored by
-  `--check`, with tools simulated unless `--read-only` names them. If a case
-  regressed or the guard can't judge (a run that errors counts as unscored, and
-  its error goes to stderr), the edit is rolled back to the approved
-  revision's parent and `approve` exits 1. If the directory changed between the
-  write and the guard, the guard doesn't run and `approve` exits 1 too. The guard's tokens count toward
-  today's budget. With cases in the corpus, `--check` is required, and the
-  agent and the check are loaded before anything is written. `--no-guard`
-  skips the guard and leaves it to a watcher's next scheduled guard. An empty
-  corpus needs neither.
-- `reject <dir> <id> --by <name> [--reason text]` records a `reject` audit entry
-  and moves the file to `.lousho/proposals/rejected/`. A rejected proposal is
-  never queued again.
-
-### Watching, pausing and status
-
-`--watch` keeps the loop running on an agent directory:
-
-```bash
-npx lousho improve ./my-agent --check ./check.mjs --watch --interval 15m
-npx lousho improve pause ./my-agent --reason "release freeze" --by ali
-npx lousho improve resume ./my-agent --by ali
-```
-
-Each tick checks the kill switch (`.lousho/improve.stop`, `LOUSHO_IMPROVE=off`
-or `"enabled": false`, audited once as `pause`), takes a lease so only one
-watcher runs per directory, runs the post-apply monitor, replays the corpus
-every `guard.everyHours`, and then runs one cycle within the daily caps. A tick
-with the same failures as the last one and no new failed run is skipped.
-Three outages in a row write the stop file. Editor calls are limited to
-`rateLimit.rpm` a minute. Ctrl-C stops after the current step. `pause` writes
-the stop file and `resume` removes it; both are audited. `resume` doesn't
-undo `LOUSHO_IMPROVE=off` or `"enabled": false`. While the loop is paused, the
-monitor doesn't run either, so nothing is rolled back automatically. Only a
-watcher runs the monitor: a single `lousho improve` cycle doesn't. See
-[Running it continuously](./improve.md#running-it-continuously).
-
-`lousho improve status <dir> [--json]` prints the mode and active revision, the
-last 5 audit entries, pending proposals, the monitor's verdict (with a warning
-while it waits for runs or kept an edit unverified), what is left of today's
-budget, the cooldown, the kill switch, the canary and the editor options a
-cycle uses (from `improve.json` and the defaults). The watcher's events go
-to the `alerts.json` webhooks beside the observe db (see
-[Observability](./observability.md)).
-
-### `improve.json`
-
-Self-healing settings live in `improve.json` beside the agent. Every key is
-optional, and an unknown key or a bad value is an error
-(`LOUSHO_CONFIG_INVALID`):
-
-```json
-{
-  "approval": "auto",
-  "budget": { "maxTokensPerDay": 2000000, "maxCyclesPerDay": 4, "maxAppliesPerDay": 1 },
-  "trigger": { "minNewFailures": 3, "requireRecurring": true },
-  "canary": { "replayRuns": 6 },
-  "monitor": { "minRuns": 20, "window": 20, "maxDrop": 0.05, "autoRollback": true, "giveUpDays": 7 },
-  "guard": { "runs": 3, "everyHours": 24, "maxCases": 30 },
-  "cooldownHours": 24,
-  "rateLimit": { "rpm": 20 },
-  "library": { "enabled": true },
-  "editors": { "proposers": 1, "mode": "agg", "select": false, "parallel": true }
-}
-```
-
-These are the defaults. Counts are whole numbers of 1 or more, and `maxDrop` is
-between 0 and 1, and `editors.proposers` is 1 to 4. `requireRecurring`
-defaults to `false` in manual mode.
-`"enabled": false` stops the loop for this agent. `budget.maxTokensPerCycle`,
-`canary.traffic` (`share` up to 0.25, `sessions` up to 50) and `library.domain`
-are unset unless you set them. With `canary.traffic` set, a proposal that
-passes the replay canary (in auto mode), or that a person approves (in manual
-mode), starts the
-[live traffic canary](./improve.md#live-traffic-canary-opt-in), which serves it
-to real sessions, instead of being written.
-`loadImproveSettings()` reads the file. See
-[Settings](./improve.md#settings) for what each key does.
+# CLI
+
+Installing the package also installs the `@linuxdevil/lousho` command. It scaffolds
+projects, checks your setup, runs an agent locally, serves it over MCP, runs
+evals, shows saved traces, builds a deployable artifact and opens Lousho Studio.
+Run it with `npx @linuxdevil/lousho <command>` inside a project that has the SDK installed.
+
+| Command | What it does | Details |
+| ------- | ------------ | ------- |
+| `lousho 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) |
+| `lousho doctor [spec\|agent-dir\|agent.ts] [--json] [--ping]` | Check Node, peer packages, provider keys, and optionally a spec file, agent directory or agent module (its provider's key is then required); `--ping` also checks each configured provider endpoint answers and accepts the key. Prints a fix for every problem. | [Installation](./installation.md#troubleshooting-lousho-doctor) |
+| `lousho dev <path>` | Local dev server for a spec file, an agent directory or a TS agent: chat UI with a session per tab and streamed events, hot reload on save. | [Below](#lousho-dev) |
+| `lousho chat <path>` | Terminal REPL for a spec file, an agent directory or a TS agent: streams replies, shows tool calls, asks for approvals and questions. | [Below](#lousho-chat) |
+| `lousho acp <path>` | Serve a spec file, an agent directory or a TS agent to an editor (Zed and other ACP clients) over the Agent Client Protocol on stdio. | [ACP](./acp.md) |
+| `lousho add <name>` | Install a tool, skill, channel, schedule or memory slot from a JSON registry into an agent directory, after showing its permission manifest and checking the code against it. | [Registry](./registry.md) |
+| `lousho mcp <spec>` | Serve the agent as an MCP server (stdio, or HTTP with `--http`). | [MCP](./mcp.md#serve-an-agent-over-mcp) |
+| `lousho eval [globs...]` | Run `*.eval.ts` files under vitest; print a summary and write JUnit/JSON reports. | [Evals](./evals.md#lousho-eval) |
+| `lousho traces [id]` | List the recent runs saved by `fileTraceExporter()` (duration, model and tool calls, tokens, cost), or print one run as a span tree. | [Observability](./observability.md#local-traces) |
+| `lousho build --target=<t> --agent=<spec>` | Build a deployable Node server, Docker image or Cloudflare Worker. | [Deployment](./deployment.md) |
+| `lousho studio` | Open Lousho Studio (the separate `@linuxdevil/studio` package) on this project. | [Lousho Studio](./agent-forge.md) |
+| `lousho bridge` | Speak Studio's bridge protocol on stdio; started by Studio, not run by hand. | [Below](#lousho-bridge) |
+| `lousho workspace <init\|ls\|show\|validate\|run>` | Create, inspect, validate and run a workspace from a folder or a running service. | [Workspaces](./workspaces.md) |
+| `lousho observe <sub>` | Run the local collector every agent reports to when `LOUSHO_OBSERVE` is set: `start`, `status`, `stop`, `rebuild-rollups`, `prune`, `export`, `failures`, `score`, `token`. | [Below](#lousho-observe) |
+| `lousho improve <path> --check <module>` | Experimental. Run one self-healing cycle on an agent directory: propose edits to its instructions and skills from failed runs in your local observe database, gate them, replay them on fresh runs, and apply (auto mode, the default) or queue (manual mode) one that passes. `--watch` keeps it running; `pause`, `status`, `rollback`, `approve` and the other subcommands manage it. `--dry-run` prints the review card and applies nothing. | [Below](#lousho-improve) |
+
+Every command that takes a `<spec>` reads an agent spec file (`.yaml`,
+`.yml` or `.json`, see [Configuration](./configuration.md#agent-spec-files-agentspec)).
+
+## Usage
+
+```text
+lousho init [dir] [--provider P] [--template T] [--yes] [--no-install] [--no-git] [--package-manager PM] [--force] [--sdk-path <dir|tgz>]
+lousho dev <spec.yaml|spec.json|agent-dir|agent.ts> [--port N] [--host H] [--allowed-hosts a,b] [--no-schedules] [--traces[=dir]]
+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|agent.ts> --target=<node-server|cloudflare-worker|docker> [--out=<dir>]    (or --agent=<path>)
+lousho studio [--port N] [--host H]
+lousho bridge
+lousho workspace <init|ls|show|validate|run> [args] [--source <dir> | --service <url>]
+lousho mcp <agent.yaml|json|agent-dir|agent.ts> [--http --port N --host H]
+lousho doctor [agent.yaml|json|agent-dir|agent.ts] [--json] [--ping]
+lousho eval [globs...] [--tag t] [--junit path] [--json path] [--strict] [--judge] [--record | --replay | --drift [--drift-usage]] [--url <base> [--token <bearer>]] [--config vitest.config.ts] [--timeout <ms>]
+lousho traces [traceId|prefix] [--dir D] [--limit N] [--json] [--content]
+lousho observe <start|status|stop|rebuild-rollups|prune|export|failures|token> [--port N] [--db path] [--host H] [--require-token] [--project X] [--webhook URL] [--retention-days N] [--session-idle-minutes N] [--older-than <N>d] [--since <N>d|<N>h|<N>m] [--agent X] [--out file]
+lousho prompt <push <file|->|list|get <name[@version|@label]>|label <name> <label> <version>> [--url U] [--port N] [--token T] [--json] [--name N] [--labels a,b] [--variables x,y]
+lousho improve <agent-dir|agent.ts> --check <module> [--model provider/model] [--editor provider/model] [--db path] [--since <N>d|<N>h|<N>m] [--agent X] [--protect traceId]... [--read-only tool]... [--max-tokens n] [--out file] [--with-recoveries] [--approval auto|manual] [--proposers 1-4] [--mode agg|seq] [--select] [--no-parallel-editors] [--dry-run] [--watch [--interval 15m]]
+lousho improve <revisions|rollback|audit|pending|approve|reject|pause|resume|status> <agent-dir> ...
+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` (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:
+it takes it only in the `=` form (`--traces=./t`), so `--traces agent.yaml` is
+still the flag followed by the path.
+
+**Exit codes.** Every command exits 0 on success, 1 when it ran and failed
+(an agent that cannot load, a build error, `lousho eval`'s gate failure, no
+matching trace, `lousho add` refusing an item without `--yes`), and 2 for a
+usage error: an unknown command, an unknown flag, a missing or invalid
+value, an extra argument, or a missing `--target` or agent path. `lousho build` prints where it wrote the build (default
+`.lousho/build/<target>`) and the command to run there.
+
+**`.env`.** The commands that run an agent (`dev`, `chat`, `acp`, `mcp`),
+`doctor`, `eval` (judge evals need provider keys) and `build` load `./.env` from the working directory when it exists, like
+`node --env-file-if-exists=.env`: a variable already set in the environment
+wins over the file. A UTF-8 byte order mark at the start of the file (which
+PowerShell 5.1's `Set-Content -Encoding utf8` writes) is ignored.
+
+`lousho init` is the exception: it parses its own flags, and a bad flag or
+value fails with `InitUsageError` — its message printed as-is, exit code 2 —
+not the shared `LOUSHO_CONFIG_INVALID` path. The only short flags besides
+`-h` are `-y` for `--yes`, on `init` and on `add`.
+
+`lousho eval` also takes `--config <file>` to run under your own vitest config
+instead of the generated one; globs then narrow that config's files as vitest
+filters.
+
+`npm create @linuxdevil/lousho my-agent` runs `lousho init` with the same arguments.
+To scaffold against an unreleased build of the SDK, pass `--sdk-path` (see
+[Installing from a local build](./installation.md#installing-from-a-local-build)).
+
+## `lousho dev`
+
+```bash
+npx @linuxdevil/lousho dev agent.yaml                  # a spec file
+npx @linuxdevil/lousho dev ./my-agent                  # an agent directory
+npx @linuxdevil/lousho dev src/agent.ts                # a TypeScript (or JavaScript) module
+npx @linuxdevil/lousho dev agent.yaml --port 4000 --host 0.0.0.0
+npx @linuxdevil/lousho dev ./my-agent --no-schedules   # do not fire cron schedules or a spec's cron triggers
+```
+
+For an agent directory, `channels/` are mounted under `/channels` and
+`schedules/` are started (and both are swapped on reload, the old schedules
+stopped first); `--no-schedules` starts none. See
+[Agent directories](./agent-directories.md#run-it-with-lousho-dev).
+
+Serves a chat UI on `GET /`, `GET /health`, `GET /dev/status` and the chat
+endpoints below (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`, `.cts`, `.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 (`LOUSHO_SPEC_UNSUPPORTED_FORMAT`, `LOUSHO_CONFIG_INVALID`)
+and its fix. A `.ts` module is imported by the running Node (22.18 or later
+strips types, so relative imports need their file extension); use `.js` for
+code that needs a transpiler.
+
+**Chat sessions.** The chat UI keeps one session per browser tab (its id is in
+`sessionStorage`; "New session" starts another) and shows the streamed turn:
+text as it arrives, tool calls with their arguments and results, errors, and
+tokens and cost from `run.done`. A tool call that needs approval shows
+Approve / Reject buttons; an `ask_question` call shows its options as buttons
+plus a free-text field. The same endpoints work from `curl` or your own page:
+
+| Endpoint | What it does |
+| -------- | ------------ |
+| `POST /chat` `{ "sessionId", "input" }` | Runs `agent.session({ id: sessionId }).stream(input)` and streams the turn as SSE: one `data: <AgentEvent JSON>` per event ([Streaming](./streaming.md)), then `event: done`. History is kept per `sessionId` (1-128 characters of `A-Za-z0-9_-`). |
+| `GET /chat/:sessionId` | The session's transcript: `{ sessionId, messages, pending }`; `pending` is `{ status, approvalId? }` while a turn waits on an approval, else `null`. A turn's messages are saved when it finishes, so while it is paused `messages` does not hold that turn yet: use `pending`. |
+| `POST /chat/:sessionId/approvals/:id` `{ "approved", "note"? }` or `{ "answer" }` | Decides the pending approval (`agent.approvals.streamResolve()`), or answers a question (`agent.approvals.streamAnswer()`), and streams the continued turn as SSE. It can pause again with another `approval.requested`. `404` when `id` is not pending. When the turn's step paused on several calls, each id is decided on its own; a decision that leaves others pending streams `run.done` with `finishReason: 'awaiting-approval'`, and the last one runs the step. |
+| `POST /chat` `{ "message" }` | Deprecated: no session, no streaming. Returns the agent's `ExecutionResult` as JSON, with a `Deprecation: true` header. |
+
+`--traces` (or `--traces=<dir>`) writes every run to local trace files with
+`fileTraceExporter()`, in `.lousho/traces` unless you name a directory, so
+`npx @linuxdevil/lousho traces` shows what the agent did. It is off by default because the
+files hold prompt, tool argument and tool result content, and the flag prints
+the directory it writes to. It applies to spec files, agent directories and
+modules alike (a module's own `exporter` is replaced while the flag is set).
+See [Local traces](./observability.md#local-traces).
+
+Sessions live in an in-process `memoryStore()` (gone when `lousho dev` stops),
+or in the agent's own `store` when a module's `createAgent()` options set one.
+The continuation of an approval is streamed too: the endpoint runs it with
+`agent.approvals.streamResolve()` (or `streamAnswer()` for a question) and
+sends the continued turn's events — the decided tool call, text deltas, a
+further pause and `run.done` — as they happen.
+
+`lousho build` servers (`node-server`, `docker`) serve these same endpoints from
+the same code, with sessions in a store chosen by `LOUSHO_STORE` and optional
+bearer auth: see [Deployment: HTTP API](./deployment.md#http-api).
+
+**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, 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
+is logged and shown in a banner on the chat page (and as `error` in
+`GET /dev/status`); the next good edit clears it. Sessions survive a reload: the
+store outlives the agent swap, so the next message continues the conversation
+on the new agent. An approval that was pending on the old agent is not known to
+the new one (`404`); start a new session.
+
+Directories and modules are your code and run with your permissions; only run
+`lousho dev` on ones you trust.
+
+- `--port` - default `3737`.
+- `--host` - default `127.0.0.1` (localhost only). Pass e.g. `--host=0.0.0.0`
+  to opt in to LAN access; `lousho dev` has no auth and shows raw provider
+  errors, so it then prints a warning.
+- `--allowed-hosts a,b` - extra host names the `Host` header may carry. To
+  stop DNS rebinding (a web page re-pointing its own domain at your machine),
+  every route but `/health` and the channels that `verify` their requests
+  answers `403` (`LOUSHO_REQUEST_FORBIDDEN`) unless `Host` is `localhost`, a
+  `127.x.x.x` address or `[::1]`; off loopback, IP addresses and the `--host`
+  name are accepted too. The list adds to that rule (a tunnel's name, e.g.);
+  `*` accepts any host. A channel without `verify` (`httpChannel()` with no
+  `verify`) is checked like the dev routes, so reach it through a tunnel only
+  with its name in the list.
+- POST bodies must be `Content-Type: application/json` (`415` otherwise), and
+  a browser POST from another origin is `403`, as on the deployed server
+  ([Cross-site requests](./auth.md#cross-site-requests)).
+
+## `lousho chat`
+
+```bash
+npx @linuxdevil/lousho chat agent.yaml                          # a spec file
+npx @linuxdevil/lousho chat ./my-agent --model openai/gpt-4o    # an agent directory, on another model
+npx @linuxdevil/lousho chat src/agent.ts --store sqlite:.lousho/chat.db --session support
+```
+
+A terminal REPL: each line you type is one turn of a session. `<path>` is
+loaded like `lousho dev` loads it (spec file, agent directory or `.ts`/`.js`
+module, see [`lousho dev`](#lousho-dev)); a missing path or bad extension fails
+with the same coded error (`LOUSHO_CONFIG_INVALID`,
+`LOUSHO_SPEC_UNSUPPORTED_FORMAT`), and so does an invalid `--session` id
+(`LOUSHO_SESSION_ID_INVALID`).
+
+```text
+> look up cats
+[lookup] {"q":"cats"}
+  -> found cats
+Cats are great.
+[usage] 20 in / 6 out tokens, $0.0004
+> email the report to sam
+Approve send_email({"to":"sam@example.com"})? [y/N] y
+  -> sent
+Done, the report is on its way.
+```
+
+- Text is written as the model produces it. Each tool call is one dim line,
+  `[tool_name] {args}`, followed by `  -> result` (or `  -> error: ...`).
+- A tool call that needs approval asks `Approve <tool>(args)? [y/N]`: `y` or
+  `yes` runs it, anything else rejects it and the model carries on. An
+  `ask_question` call (`askQuestion: true`) prints the question with numbered
+  options; answer with the number or with free text.
+- After each turn `[usage]` shows the tokens and, when every model used has
+  known pricing, the cost (`~` marks estimated tokens).
+- Errors from the SDK print with their `[LOUSHO_...]` code and fix, and the
+  session continues. A provider failure also names its category and HTTP
+  status, e.g. `error: User not found. (auth-failure, HTTP 401)` for a wrong
+  API key.
+- `--traces` or `--traces=<dir>` writes the session's runs to local trace files,
+  as for `lousho dev`; a line on stderr says where.
+
+| Command | What it does |
+| ------- | ------------ |
+| `/new` | Start a new session (the old one is kept in the store). |
+| `/model <provider/model>` | Rebuild the agent on another model; the session continues. A failure keeps the current model. |
+| `/compact` | Compact the session's transcript now (old tool results are pruned) and print the before/after size. |
+| `/clear` | Empty the session's transcript; the session id stays. |
+| `/history` | Print the session's transcript. |
+| `/quit` | Leave (Ctrl-D works too). |
+
+| Option | Meaning |
+| ------ | ------- |
+| `--model provider/model` | Use this model instead of the one the target names. Applies to spec files, agent directories and `createAgent()` options exports; a module that exports an already built agent keeps its model. The `vendor/` model prefix chooses the provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o`). |
+| `--session id` | Open this session (1-128 characters of `A-Za-z0-9_-`); default is a new `chat-<id>`. |
+| `--store sqlite:<file>` | Keep sessions in a SQLite file ([`SqliteStore`](./durable-execution.md)), so `--session id` continues a conversation after a restart. Default: in memory. Pending approvals are not restored after a restart. |
+
+The REPL itself is `runChatRepl()` in `src/cli/chatRepl.ts`; it takes the
+input lines, an output stream and an agent factory, so it can be tested with
+scripted lines and a `mockModel` agent and no terminal.
+
+## `lousho build`
+
+```bash
+npx @linuxdevil/lousho build --target=node-server --agent=agent.yaml        # or docker / cloudflare-worker
+npx @linuxdevil/lousho build ./my-agent --target=node-server                # an agent directory (node-server, docker)
+npx @linuxdevil/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
+the command to run or deploy it. Building needs `tsup`
+(`npm install --save-dev tsup`). Targets, the HTTP API they serve and the
+Workers limits are in [Deployment](./deployment.md).
+
+## `lousho studio`
+
+```bash
+npx @linuxdevil/lousho studio            # prints http://127.0.0.1:4750/?token=<per-launch token>
+npx @linuxdevil/lousho studio --port 5000
+```
+
+Opens Lousho Studio on this project. Studio is a separate package
+(`@linuxdevil/studio`): install it with `npm i -g @linuxdevil/studio` (or run
+`npx @linuxdevil/studio`); this command finds it and opens the current folder
+as a workspace. When no Studio is installed it prints
+`Studio is a separate install: npx @linuxdevil/studio` and exits.
+
+Options: `--port N` and `--host H` pass through to Studio (defaults 4750 and
+`127.0.0.1`). `--prod` and `--dev` only apply inside the SDK's own repository
+checkout. See [Lousho Studio](./agent-forge.md) for workspaces, the screens
+and the walkthrough.
+
+## `lousho bridge`
+
+```bash
+lousho bridge
+```
+
+Speaks Studio's bridge protocol (NDJSON) on stdin/stdout so Studio can build
+and run agents with this project's own SDK. Studio starts it for each
+workspace that has `@linuxdevil/lousho` installed; you do not run it
+yourself.
+
+## `lousho observe`
+
+```bash
+npx @linuxdevil/lousho observe start                        # collector on http://127.0.0.1:7777
+npx @linuxdevil/lousho observe status                       # health + fleet counts
+npx @linuxdevil/lousho observe stop                         # <db>.pid + SIGTERM (checks the daemon serves --db)
+npx @linuxdevil/lousho observe rebuild-rollups              # recompute insight aggregates
+npx @linuxdevil/lousho observe prune --older-than 30d       # delete finished runs older than 30 days, then VACUUM
+npx @linuxdevil/lousho observe export --since 7d --out runs.jsonl # traces as JSONL, one per line
+npx @linuxdevil/lousho observe failures --since 7d          # recurring tool and model failures, by agent
+npx @linuxdevil/lousho observe failures --traces .lousho/traces --json # the same from trace files, no database
+npx @linuxdevil/lousho observe score --agent support        # continuous score, pass rate and trajectory gate state
+npx @linuxdevil/lousho observe token create --project myapp # bearer key for non-loopback auth
+```
+
+Runs the local collector every agent reports to when `LOUSHO_OBSERVE` is
+set: traces, fleet monitoring, eval scores, the prompt registry and the
+context hub in one SQLite file (default `~/.lousho/observe.db`). Studio's
+[daemon screens](./agent-forge.md#screens) read it. `start` takes
+`--port` (or `LOUSHO_OBSERVE_PORT`), `--db`, `--host`, `--require-token`
+and a repeatable `--webhook` for alert hooks. Each daemon writes its own `<db name>.pid` beside the db
+(`observe.db` gives `observe.pid`), so two dbs in one folder never share a
+pidfile. `start` exits 1 when the port already serves a different db, and
+`stop` refuses to signal when the daemon at the pidfile's port reports another
+db or the port answers as a different service, and falls back to signalling
+when it cannot verify (unreachable, or an old one-line pidfile). `/health`
+tells which db a daemon serves only to callers on the same machine. See
+[The observe daemon](./observability.md#the-observe-daemon).
+
+`start --retention-days N` sets how long finished runs are kept (default 30;
+`0` keeps everything). Once a day the daemon deletes traces whose
+observations all finished more than N days ago. A trace with any run still
+open, and a session that is still `active`, is kept whatever its age. Rollups,
+prompts and hub entries are never pruned. `prune --older-than <N>d` (whole
+days, N >= 1) does the same pass now, prints the observation, score and session
+counts it deleted, and then runs `VACUUM` to reclaim disk space (the daily pass
+never does). If only the `VACUUM` fails (for example, the db is busy), the
+prune stays committed, the error goes to stderr and the exit code is 0. It is
+safe to run while the daemon is up. A bad N is a usage
+error (exit 2). See [Retention](./observability.md#retention).
+
+`start --session-idle-minutes N` sets when a conversation counts as finished
+(default 30; `0` turns it off, so a session stays `active` until its agent goes
+down). The daemon's sweep marks a session `ended` once none of its runs is
+still open (a run marked `interrupted` does not count) and nothing in it has started or finished for N minutes; its
+`ended_at` is the time of that last activity. A new run in an `ended` (or
+`interrupted`) session makes it `active` again. Ended sessions are then pruned
+by `--retention-days` like any other finished session. A bad N is a usage
+error (exit 2). See [Idle sessions](./observability.md#idle-sessions).
+
+`export` writes traces as JSONL: one line per trace, `{ trace, observations,
+scores }` (the same rows the trace API returns), oldest first, with no cap on
+how many. `--since <N>d` (or `<N>h`, `<N>m`) keeps traces that started within
+that window; `--agent X` keeps one agent, matched by `agent_id` or, when no
+agent has that id, by its registered name (a name shared by two agents is a
+usage error, exit 2). Without `--out` the lines go to stdout and nothing else
+does (the count goes to stderr, so a pipe stays clean); `--out file` creates or
+overwrites the file and prints the count to stdout. It reads the db directly, so
+no daemon needs to be running. See [Export](./observability.md#export).
+
+## `lousho prompt`
+
+```bash
+npx @linuxdevil/lousho prompt push prompt.md --name mira    # publishes a new version
+npx @linuxdevil/lousho prompt list
+npx @linuxdevil/lousho prompt get mira@latest
+npx @linuxdevil/lousho prompt label mira prod 3             # mira@prod -> 3 (was 2)
+npx @linuxdevil/lousho prompt get mira@prod
+```
+
+Publishes and reads prompt versions in the observe daemon's registry. Agents
+resolve them with `createAgent({ prompt: 'mira@latest' })` (or a label,
+`'mira@prod'`) or `LOUSHO_PROMPT`.
+
+- `push` publishes the file (`-` reads stdin) as the next version. A push
+  whose text and `--variables` equal the latest version's mints nothing and
+  prints `mira@2 is unchanged` (exit 0). `--labels prod,canary` points those
+  labels at the resulting version, the new one or the unchanged latest.
+- `get <name>[@ref]` prints a version's text; `ref` is an integer, `latest`
+  (the default) or a label. `--json` prints the row, whose `labels` are the
+  labels currently pointing at that version.
+- `label <name> <label> <version>` moves a label: a label points at exactly
+  one version, so this takes it off the one that held it, and prints
+  `mira@prod -> 3 (was 2)` (or `(was unset)` for a new label). A label is a
+  name without whitespace, `@` or `/`, and not `latest` or all digits. See [The observe daemon](./observability.md#the-observe-daemon).
+
+## `lousho improve`
+
+Experimental, like the [`improveAgent()`](./improve.md) it runs.
+
+```bash
+npx @linuxdevil/lousho improve ./my-agent --check ./check.mjs --since 7d --out proposal.md
+```
+
+```js
+export default (input, answer) => !answer.includes('I cannot help');
+```
+
+It takes the failed runs in your local observe database (default
+`~/.lousho/observe.db`, or `--db`), replays each recorded input through the
+agent, scores each answer with your check, and prints the review card from
+`formatImproveResult()`. On an agent directory it then runs one self-healing
+cycle with `healOnce()`: only failed runs of the current harness revision count,
+a proposal that passes the gate is replayed on fresh runs (the canary), and in
+auto mode (the default) it is written to `instructions.md` and
+`skills/<name>/SKILL.md`, after which the corpus guard replays the protected
+cases and rolls back on a regression. In manual mode it is queued for
+`lousho improve approve`. Every step is audited, and `improve.json`'s daily caps,
+the cooldown after a rollback and the `.lousho/improve.stop` kill switch apply.
+`--dry-run` keeps the old behaviour: every failed run counts, the card is
+printed, and nothing is written. An agent module, or an agent whose instructions
+don't live in `instructions.md`, always runs dry.
+
+- `<path>` is an agent directory or a `.ts`/`.js` agent module whose
+  instructions are plain text. Editors may change only the instructions and
+  skills.
+- `--check <module>` is required. Its default export is a `CaseCheck`,
+  `(input, answer) => boolean | null | { passed, failure? }`; `null` means the
+  answer can't be scored. Return `{ passed: false, failure }` to name the check
+  a failed answer missed: the editors read it in that run's record, and without
+  it a failed run whose answer looks right gives them nothing to fix.
+  `input` is the user's message for a one-message run, else the recorded
+  messages as JSON text.
+- `--since` and `--agent` pick which failed runs become cases, as for
+  `lousho observe export`.
+- `--protect <traceId>` names a run that went well. It joins the gate only
+  after it passes 6 of 6 fresh runs; otherwise stderr says why it was left out.
+  A trace that is also a failed run stays a case to learn from.
+- Tools are simulated during replays, except `load_skill` and
+  `read_skill_file`. `--read-only <tool>` lets a tool that is safe to call
+  again run for real. Replays aren't traced: `LOUSHO_OBSERVE`, the agent's
+  `exporter` and `onEvent` are off while it runs, so they never reach your
+  database.
+- `--model` runs the agent on another model; `--editor` picks the editors'
+  model (default `--model`, else the agent's own).
+- `--out file` also writes the card, or the JSON result for a `.json` path. It
+  must be a new file, outside the agent's files.
+- `--max-tokens <n>` passes `maxTokens` to `improveAgent()`: it stops once `n`
+  tokens are spent on agent runs and editor calls. The total is checked after
+  each run or editor call, so the last one can go over. The card and the JSON
+  then report `budget-exceeded` with the reason, nothing is proposed, and
+  stderr suggests raising it. `n` must be a positive integer; anything else is
+  a usage error (exit 2). It is unset by default, so there is no cap. The runs
+  that admit `--protect` traces happen before and don't count toward it.
+- `--with-recoveries` also shows the editors, for each failed run, the
+  `<id>.heal` fork from `agent.recover()` that finished and whose answer passes
+  `--check`, if there is one. It's evidence only: it never counts as a run and
+  never protects a case, and a fork you `--protect` is left out. See
+  [Recovery forks as evidence](./improve.md#recovery-forks-as-evidence).
+- `--approval auto|manual` sets the approval mode, over the
+  `LOUSHO_IMPROVE_APPROVAL` variable, which wins over `"approval"` in
+  `improve.json` beside the agent. The default is `auto`. In `manual` mode an
+  edit that quotes a failed check word for word is kept and flagged on the card
+  for the person who approves it; in `auto` mode it is sent back to the editor
+  once and then dropped. An `improve.json` that doesn't validate stops the
+  run. See [Approval modes](./improve.md#approval-modes).
+- `--proposers <1-4>`, `--mode agg|seq`, `--select` and
+  `--no-parallel-editors` set the cycle's
+  [Harness² options](./improve.md#harness-options), over the `editors` block in
+  `improve.json`. `--select` can only turn the selector on and
+  `--no-parallel-editors` can only turn parallel off. `--proposers k` runs k invariant and k domain editors (or k
+  rounds with `--mode seq`), and costs about k times the editor sessions and
+  proposal runs. `--select` gates every candidate and lets the advisory selector
+  choose among those that pass. `--no-parallel-editors` runs the editors and
+  their probes one at a time, for a rate-limited model. They apply to dry runs
+  and `--watch` too.
+- `--dry-run` writes nothing: no apply, no queue, no audit entry. It reads
+  every failed run whatever its revision, and ignores the kill switch and the
+  daily caps.
+- `--watch` keeps running cycles on a timer; `--interval` (default `15m`, as
+  `<N>s`, `<N>m` or `<N>h`) sets the spacing. It needs an agent directory, takes
+  its budget from `improve.json`, and can't be combined with `--dry-run`,
+  `--max-tokens` or `--out`. See below.
+
+Before it starts, a cycle prints its approval mode and whether it applies or
+queues; a dry run prints how many runs it will make at least, and the token
+budget if any. Every run and every editor call is billed to your models.
+`--max-tokens` caps one cycle within `improve.json`'s daily caps.
+It exits 1 on an `outage`: no run could be scored, or the editors' provider
+failed. A `budget-exceeded` run exits 0, since you set the cap. Each run's error goes to
+stderr. It reads nothing but your own database. See [Improving an agent](./improve.md#from-the-command-line).
+
+### Revisions, rollback and the audit log
+
+Every change to an agent directory's `instructions.md` and
+`skills/<name>/SKILL.md` made through `applyProposal()` is saved as a revision
+under `.lousho/revisions/` and recorded in the hash-chained
+`.lousho/audit.jsonl`. Three subcommands read and undo that history:
+
+```bash
+npx @linuxdevil/lousho improve revisions ./my-agent
+npx @linuxdevil/lousho improve rollback ./my-agent --by ali --reason "answers got worse"
+npx @linuxdevil/lousho improve audit ./my-agent --verify
+```
+
+- `revisions <dir> [--json]` lists the saved revisions, newest first, with their
+  source (`baseline`, `apply` or `rollback`), who made them and when. `*` marks
+  the one the directory holds now.
+- `rollback <dir> --by <name> [--to <revision>] [--reason text]` restores a
+  saved revision through the same writer as an apply: it changes only
+  instructions and skills, makes a new revision and writes one `rollback` audit
+  entry. It never rewrites history. Without `--to` it goes to the parent of the
+  current revision. It refuses instead when the current revision came from a
+  rollback, or when the directory holds hand edits that match no revision; pass
+  `--to` then. A hand edit that a rollback replaces is saved as a revision
+  first. `--to` takes an id or a unique prefix of at least 4 characters. `--by`
+  is required. If an apply lands between your command and the write, the
+  rollback is refused as stale.
+- `audit <dir> [--verify] [--json]` prints the audit log, oldest first.
+  `--verify` checks the hash chain and exits 1 at the first edited, removed or
+  truncated line.
+
+A directory literally named `revisions`, `rollback`, `audit`, `pending`,
+`approve`, `reject`, `pause`, `resume` or `status` must be passed as
+`./revisions` and so on.
+
+### Pending proposals (manual mode)
+
+In manual mode a proposal that passed the gate waits in
+`.lousho/proposals/<id>.json` until a person decides:
+
+```bash
+npx @linuxdevil/lousho improve pending ./my-agent
+npx @linuxdevil/lousho improve approve ./my-agent 3f9c0a1b2d4e --by ali --check ./check.mjs
+npx @linuxdevil/lousho improve reject ./my-agent 3f9c0a1b2d4e --by ali --reason "too broad"
+```
+
+- `pending <dir> [--show <id>] [--json]` lists the queue, newest first, marking
+  stale and refused entries. The id is the first 12 characters of the proposed
+  harness's hash, and a file whose content doesn't match its id is left out.
+  `--show <id>` prints that proposal's review card.
+- `approve <dir> <id> --by <name> [--check <module>] [--model provider/model]
+  [--read-only tool]... [--no-guard] [--db path]` applies the proposal through
+  `applyProposal()` as that person's approval and removes it from the queue.
+  With `canary.traffic` set, it starts the
+  [traffic canary](./improve.md#live-traffic-canary-opt-in) instead and writes
+  nothing yet, reading the observe database at `--db` (default
+  `~/.lousho/observe.db`); the proposal is applied as that approval when the
+  canary passes, and the watcher guards it then. A
+  proposal whose agent directory changed since it was made is refused and
+  marked stale; run improve again. Any other refusal is recorded on the entry
+  and shown by `pending`. Right after the write it runs the corpus guard, as an
+  automatic apply does: `guard.runs` fresh runs of every corpus case, scored by
+  `--check`, with tools simulated unless `--read-only` names them. If a case
+  regressed or the guard can't judge (a run that errors counts as unscored, and
+  its error goes to stderr), the edit is rolled back to the approved
+  revision's parent and `approve` exits 1. If the directory changed between the
+  write and the guard, the guard doesn't run and `approve` exits 1 too. The guard's tokens count toward
+  today's budget. With cases in the corpus, `--check` is required, and the
+  agent and the check are loaded before anything is written. `--no-guard`
+  skips the guard and leaves it to a watcher's next scheduled guard. An empty
+  corpus needs neither.
+- `reject <dir> <id> --by <name> [--reason text]` records a `reject` audit entry
+  and moves the file to `.lousho/proposals/rejected/`. A rejected proposal is
+  never queued again.
+
+### Watching, pausing and status
+
+`--watch` keeps the loop running on an agent directory:
+
+```bash
+npx @linuxdevil/lousho improve ./my-agent --check ./check.mjs --watch --interval 15m
+npx @linuxdevil/lousho improve pause ./my-agent --reason "release freeze" --by ali
+npx @linuxdevil/lousho improve resume ./my-agent --by ali
+```
+
+Each tick checks the kill switch (`.lousho/improve.stop`, `LOUSHO_IMPROVE=off`
+or `"enabled": false`, audited once as `pause`), takes a lease so only one
+watcher runs per directory, runs the post-apply monitor, replays the corpus
+every `guard.everyHours`, and then runs one cycle within the daily caps. A tick
+with the same failures as the last one and no new failed run is skipped.
+Three outages in a row write the stop file. Editor calls are limited to
+`rateLimit.rpm` a minute. Ctrl-C stops after the current step. `pause` writes
+the stop file and `resume` removes it; both are audited. `resume` doesn't
+undo `LOUSHO_IMPROVE=off` or `"enabled": false`. While the loop is paused, the
+monitor doesn't run either, so nothing is rolled back automatically. Only a
+watcher runs the monitor: a single `lousho improve` cycle doesn't. See
+[Running it continuously](./improve.md#running-it-continuously).
+
+`lousho improve status <dir> [--json]` prints the mode and active revision, the
+last 5 audit entries, pending proposals, the monitor's verdict (with a warning
+while it waits for runs or kept an edit unverified), what is left of today's
+budget, the cooldown, the kill switch, the canary and the editor options a
+cycle uses (from `improve.json` and the defaults). The watcher's events go
+to the `alerts.json` webhooks beside the observe db (see
+[Observability](./observability.md)).
+
+### `improve.json`
+
+Self-healing settings live in `improve.json` beside the agent. Every key is
+optional, and an unknown key or a bad value is an error
+(`LOUSHO_CONFIG_INVALID`):
+
+```json
+{
+  "approval": "auto",
+  "budget": { "maxTokensPerDay": 2000000, "maxCyclesPerDay": 4, "maxAppliesPerDay": 1 },
+  "trigger": { "minNewFailures": 3, "requireRecurring": true },
+  "canary": { "replayRuns": 6 },
+  "monitor": { "minRuns": 20, "window": 20, "maxDrop": 0.05, "autoRollback": true, "giveUpDays": 7 },
+  "guard": { "runs": 3, "everyHours": 24, "maxCases": 30 },
+  "cooldownHours": 24,
+  "rateLimit": { "rpm": 20 },
+  "library": { "enabled": true },
+  "editors": { "proposers": 1, "mode": "agg", "select": false, "parallel": true }
+}
+```
+
+These are the defaults. Counts are whole numbers of 1 or more, and `maxDrop` is
+between 0 and 1, and `editors.proposers` is 1 to 4. `requireRecurring`
+defaults to `false` in manual mode.
+`"enabled": false` stops the loop for this agent. `budget.maxTokensPerCycle`,
+`canary.traffic` (`share` up to 0.25, `sessions` up to 50) and `library.domain`
+are unset unless you set them. With `canary.traffic` set, a proposal that
+passes the replay canary (in auto mode), or that a person approves (in manual
+mode), starts the
+[live traffic canary](./improve.md#live-traffic-canary-opt-in), which serves it
+to real sessions, instead of being written.
+`loadImproveSettings()` reads the file. See
+[Settings](./improve.md#settings) for what each key does.
diff --git a/docs/cloudflare-workers.md b/docs/cloudflare-workers.md
index e9db8a126..261d84a03 100644
--- a/docs/cloudflare-workers.md
+++ b/docs/cloudflare-workers.md
@@ -1,6 +1,6 @@
 # Cloudflare Workers
 
-`npx lousho build --target=cloudflare-worker --agent=agent.yaml` generates a module Worker (`worker.ts`), a `wrangler.toml` and a bundle, `dist/worker.js`, that the build checks for `node:` imports. It needs `tsup` and `wrangler` installed, and it takes an [agent spec file](./configuration.md) or an [agent directory](./agent-directories.md) (`npx lousho build ./my-agent --target=cloudflare-worker`). The Worker serves the same [HTTP API](./deployment.md#http-api) as the other targets. This target has the tightest limits of the three, so they come first.
+`npx @linuxdevil/lousho build --target=cloudflare-worker --agent=agent.yaml` generates a module Worker (`worker.ts`), a `wrangler.toml` and a bundle, `dist/worker.js`, that the build checks for `node:` imports. It needs `tsup` and `wrangler` installed, and it takes an [agent spec file](./configuration.md) or an [agent directory](./agent-directories.md) (`npx @linuxdevil/lousho build ./my-agent --target=cloudflare-worker`). The Worker serves the same [HTTP API](./deployment.md#http-api) as the other targets. This target has the tightest limits of the three, so they come first.
 
 ## What works and what does not
 
@@ -12,7 +12,7 @@
 | [Agent directories](./agent-directories.md) | yes: config, `instructions.md`, `tools/`, `skills/`, `subagents/`, `schedules/` (Worker cron rules), `channels/` (mounted under `/channels`), `memory/` (`kvMemory()`, or `inMemoryMemory()` per isolate) and `projectInstructions` (embedded at build time) | yes, all of it |
 | Providers | `mock`, `openai`, `anthropic`, `openrouter` | `mock`, `openai`, `anthropic`, `ollama`, `openrouter` |
 | Built-in tools | `current-date`, `day-name`, `http` (listed host names only, from the `LOUSHO_HTTP_ALLOW` binding) | all, including `http` and `web-fetch` |
-| Tools written in TypeScript | yes, in an agent directory: no Node builtins, and from `lousho` only the names listed under [Agent directories on a Worker](#build-and-deploy) | yes, in an agent directory |
+| Tools written in TypeScript | yes, in an agent directory: no Node builtins, and from `@linuxdevil/lousho` only the names listed under [Agent directories on a Worker](#build-and-deploy) | yes, in an agent directory |
 | Sandboxed tool execution | no (the build swaps the sandbox for a shim that fails when used) | yes |
 | MCP servers over stdio | no (the child process cannot start; the shim fails when used) | yes |
 | [Code mode](./code-mode.md) (`codeMode`) | no (the build swaps QuickJS for a shim that fails the run at its start) | yes |
@@ -105,7 +105,7 @@ Worker builds the agent with the same rules as `resolveAgentDir()` (config
 keys, tool exports, duplicate tool names):
 
 ```bash
-npx lousho build ./my-agent --target=cloudflare-worker
+npx @linuxdevil/lousho build ./my-agent --target=cloudflare-worker
 cd .lousho/build/cloudflare-worker && npx wrangler deploy
 ```
 
@@ -211,8 +211,8 @@ binding typed as `KVBinding` (the `get`/`put`/`delete` part of Cloudflare's
 from the `/worker` subpath - see [Writing your own Worker](#writing-your-own-worker):
 
 ```ts
-import { createAgent } from 'lousho/worker';
-import { KVStore, type KVBinding } from 'lousho/kv';
+import { createAgent } from '@linuxdevil/lousho/worker';
+import { KVStore, type KVBinding } from '@linuxdevil/lousho/kv';
 
 interface Env {
   AGENT_KV: KVBinding;
@@ -275,7 +275,7 @@ new call, which gets a new approval id, so a tool that must act once per
 invoice also needs a key from its own arguments (the invoice number here):
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 // `payments` stands in for your payment client.
@@ -317,7 +317,7 @@ day-of-week (`LOUSHO_SCHEDULE_INVALID`).
 
 In a Worker you write yourself, wire an agent defined in code with
 `handleScheduled(agent, schedules, controller, ctx)` (exported from
-`lousho/worker` — the `lousho/deploy-runtime-worker`
+`@linuxdevil/lousho/worker` — the `@linuxdevil/lousho/deploy-runtime-worker`
 specifier in the generated code is a virtual one that only `lousho build`'s
 bundler resolves; do not import it yourself). It runs the schedules whose
 `cron` equals `controller.cron` inside `ctx.waitUntil()` and never throws; list
@@ -326,9 +326,9 @@ the same expressions under `[triggers] crons` yourself. Give the agent a store
 isolate's memory and is gone when it is recycled:
 
 ```ts
-import { createAgent, createMockProvider, defineSchedule, handleScheduled } from 'lousho/worker';
-import type { ScheduledContext, ScheduledController } from 'lousho/worker';
-import { KVStore, type KVBinding } from 'lousho/kv';
+import { createAgent, createMockProvider, defineSchedule, handleScheduled } from '@linuxdevil/lousho/worker';
+import type { ScheduledContext, ScheduledController } from '@linuxdevil/lousho/worker';
+import { KVStore, type KVBinding } from '@linuxdevil/lousho/kv';
 
 interface Env {
   AGENT_CHECKPOINTS: KVBinding;
@@ -350,7 +350,7 @@ export default {
 
 ## Writing your own Worker
 
-Import from `lousho/worker`, not the package root. The root entry
+Import from `@linuxdevil/lousho/worker`, not the package root. The root entry
 also exports file stores, the agent-directory loader, MCP over stdio, sandboxes
 and other Node-only modules, so bundling it for `platform: 'browser'` fails with
 `Could not resolve "async_hooks"` and friends. `/worker` is `createAgent` plus the
@@ -362,8 +362,8 @@ import {
   createAgent, createMockProvider, defineSchedule, defineTool, handleScheduled,
   memoryStore, serveFetch, OpenAIProvider, AnthropicProvider, OpenRouterProvider,
   LLMProviderRegistry, SDKError, /* ... */
-} from 'lousho/worker';
-import { KVStore } from 'lousho/kv'; // also re-exported from /worker
+} from '@linuxdevil/lousho/worker';
+import { KVStore } from '@linuxdevil/lousho/kv'; // also re-exported from /worker
 ```
 
 The exports: `createAgent` (and its config types), `memoryStore`, the KV stores
@@ -436,8 +436,8 @@ read-modify-write is not atomic.
 ## Bundle size and Node builtins
 
 The KV-backed stores (`KVStore`, `KVCheckpointStore` and `CHECKPOINT_KV_BINDING`,
-exported from `lousho/kv`) have no `node:*` references anywhere
-in their dependency graph, and neither does the `lousho/worker`
+exported from `@linuxdevil/lousho/kv`) have no `node:*` references anywhere
+in their dependency graph, and neither does the `@linuxdevil/lousho/worker`
 entry a hand-written Worker bundles (its build is checked the same way; see
 [Writing your own Worker](#writing-your-own-worker)). The Worker runs the spec as a `createAgent()` agent, whose
 Node-only imports (project instructions, the file session store, guardrail
diff --git a/docs/code-mode.md b/docs/code-mode.md
index cf579bd78..9371564d0 100644
--- a/docs/code-mode.md
+++ b/docs/code-mode.md
@@ -35,7 +35,7 @@ npm install quickjs-emscripten@^0.32.0
 ```
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const prices: Record<string, number> = { apple: 1.2, pear: 0.8, plum: 2 };
diff --git a/docs/compaction.md b/docs/compaction.md
index 7bc52c931..e657942c0 100644
--- a/docs/compaction.md
+++ b/docs/compaction.md
@@ -18,7 +18,7 @@ OpenRouter use `openrouter/<vendor>/<model>` (e.g.
 `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const simple = createAgent({ model: 'openai/gpt-4o', compaction: true });
 
@@ -84,7 +84,7 @@ listeners (`createAgent({ onEvent })`, `onAgentEvent`) or is streamed.
 a cheap summarizer model:
 
 ```ts
-import { createAgent, createCompactionHook, twoPhaseStrategy } from 'lousho';
+import { createAgent, createCompactionHook, twoPhaseStrategy } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   provider,
@@ -157,7 +157,7 @@ model's loaded context length (`loaded_context_length` from
 prints the model's default).
 
 ```ts
-import { createAgent, registerModel } from 'lousho';
+import { createAgent, registerModel } from '@linuxdevil/lousho';
 
 // Either on the agent...
 const agent = createAgent({
@@ -183,8 +183,8 @@ Registering the hook in a `HookRegistry` is for code that calls the executor
 directly (see [the executor API](./executor-api.md)):
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { HookRegistry, createCompactionHook, twoPhaseStrategy } from 'lousho';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { HookRegistry, createCompactionHook, twoPhaseStrategy } from '@linuxdevil/lousho';
 
 const hooks = new HookRegistry();
 hooks.register(
@@ -270,7 +270,7 @@ message; a pinned tool result keeps its whole assistant turn. Pin what the
 agent must always see in full, such as the task statement or a key document:
 
 ```ts
-import { pinMessage, isPinned, type Message } from 'lousho';
+import { pinMessage, isPinned, type Message } from '@linuxdevil/lousho';
 
 const messages: Message[] = [
   { role: 'system', content: 'You are a research assistant.' },
@@ -288,7 +288,7 @@ of the conversation, and resolves to a new array (its input is not modified).
 Use it to shrink a stored transcript before you continue it:
 
 ```ts
-import { compactMessages, summarizeStrategy, type Message } from 'lousho';
+import { compactMessages, summarizeStrategy, type Message } from '@linuxdevil/lousho';
 
 declare const history: Message[];
 
@@ -322,8 +322,8 @@ durable turn is unfinished. Listeners added with `session.on()` get
 checkpoint and checkpoint history, and emits `context.cleared`.
 
 ```ts
-import { createAgent, twoPhaseStrategy } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, twoPhaseStrategy } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const agent = createAgent({ provider: mockModel(['ok']) });
 const session = agent.session({ compaction: { strategy: twoPhaseStrategy({ model: 'openai/gpt-4o-mini' }) } });
@@ -348,7 +348,7 @@ unchanged when there is nothing to do: the hook then leaves the run alone and
 does not call `onCompaction`.
 
 ```ts
-import { createCompactionHook, isPinned, type CompactionStrategy } from 'lousho';
+import { createCompactionHook, isPinned, type CompactionStrategy } from '@linuxdevil/lousho';
 
 // Keep the system prompt, pinned messages and the last 20 messages.
 const keepRecent: CompactionStrategy = {
diff --git a/docs/configuration.md b/docs/configuration.md
index 2d0f6d3c0..c6c0bf86f 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -142,7 +142,7 @@ mcpServers:
 ```
 
 ```ts
-import { agentSpecSchema, specToAgent, type McpServerSpec } from 'lousho';
+import { agentSpecSchema, specToAgent, type McpServerSpec } from '@linuxdevil/lousho';
 
 const filesystem: McpServerSpec = { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem'] };
 const spec = agentSpecSchema.parse({
@@ -185,7 +185,7 @@ other models. The `vendor/` model prefix chooses the provider; with OpenRouter
 use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -227,7 +227,7 @@ To build the same thing by hand, or for providers you construct yourself,
 anywhere a provider is accepted:
 
 ```ts
-import { createAgent, resolveProvider, withFallback, withRetry } from 'lousho';
+import { createAgent, resolveProvider, withFallback, withRetry } from '@linuxdevil/lousho';
 
 const provider = withFallback(
   [
@@ -298,7 +298,7 @@ flow waves and eval suites cannot burst unbounded model calls. Every limit is
 optional:
 
 ```ts
-import { withRateLimit, resolveProvider } from 'lousho';
+import { withRateLimit, resolveProvider } from '@linuxdevil/lousho';
 
 const provider = withRateLimit(resolveProvider('openai/gpt-4o-mini'), {
   requestsPerMinute: 60, // calls started per rolling minute
@@ -328,7 +328,7 @@ its own provider is queued too). Give several agents the same
 `createRateLimiter()` to share it across them.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const researcher = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You research.', description: 'Finds sources' });
 createAgent({ model: 'openai/gpt-4o-mini', subagents: { researcher }, rateLimit: { maxConcurrent: 2 } });
@@ -407,7 +407,7 @@ A `send()` or `stream()` call can pass its own, which win key by key over the
 agent's:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -442,7 +442,7 @@ Besides `modelSettings`, a `send()` or `stream()` call can set its own
 instructions for that run:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You triage support tickets.' });
 await agent.send('Summarize the ticket.', { maxSteps: 2, instructions: 'Answer in French.' });
@@ -460,7 +460,7 @@ keeps `model` / `provider` and `instructions` / `prompt` mutually exclusive,
 so TypeScript rejects spreading it next to a literal that sets one of them.
 
 ```ts
-import { createAgent, type CreateAgentBase } from 'lousho';
+import { createAgent, type CreateAgentBase } from '@linuxdevil/lousho';
 
 const shared: CreateAgentBase = { maxSteps: 8, modelSettings: { temperature: 0 } };
 
@@ -519,7 +519,7 @@ with a checkpoint store it is checkpointed as finished, like `'max-steps'`.
 (`LOUSHO_BUDGET_EXCEEDED`, with the same `budget`) instead.
 
 ```ts
-import { BudgetExceededError, createAgent } from 'lousho';
+import { BudgetExceededError, createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   provider,
@@ -548,7 +548,7 @@ continued from its store keeps its budget. Both apply together; the first limit
 reached stops the turn. A turn that was aborted is not counted.
 
 ```ts
-import { createAgent, memoryStore } from 'lousho';
+import { createAgent, memoryStore } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider, store: memoryStore(), limits: { maxTokens: 20_000 } });
 const session = agent.session({ id: 'user-42', limits: { maxCostUsd: 1 } });
@@ -562,7 +562,7 @@ Many repositories keep guidance for coding agents in an `AGENTS.md` (or
 `CLAUDE.md`) file. `createAgent` can append it to the agent's instructions:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   instructions: 'You review pull requests.',
diff --git a/docs/connectors.md b/docs/connectors.md
index 127f68347..7072fede8 100644
--- a/docs/connectors.md
+++ b/docs/connectors.md
@@ -6,7 +6,7 @@ connector is an **MCP server**: add it to `mcpServers` and its tools join the
 agent's registry namespaced as `<server>__<tool>`.
 
 ```ts no-run
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openrouter/openai/gpt-4o-mini',
@@ -47,8 +47,8 @@ into the SDK's approval gate: a `slack.post_message` pauses the run until
 approved, `docs.get_document` does not. Tune it per server:
 
 ```ts no-run
-import { createAgent } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const provider = mockModel([{ text: 'ok' }]);
 
diff --git a/docs/decisions.md b/docs/decisions.md
index 00a7d83ab..51be42df9 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -5,7 +5,7 @@
 Public beta: `gpt-6-luna` is the only model the endpoint serves, and the surface may still change. The endpoint is not part of chat completions, so it does not go through `createAgent()` providers or OpenRouter — it needs `OPENAI_API_KEY` (or `apiKey`/`baseURL` for a compatible endpoint).
 
 ```ts
-import { decide } from 'lousho';
+import { decide } from '@linuxdevil/lousho';
 
 const { answers } = await decide({
   input: 'I was charged twice for my order.',
@@ -32,7 +32,7 @@ if (route.type === 'choice' && route.confidence >= 0.7) {
 ## Question types
 
 ```ts no-run
-import { decide, type DecisionQuestion } from 'lousho';
+import { decide, type DecisionQuestion } from '@linuxdevil/lousho';
 
 const questions: DecisionQuestion[] = [
   // predicate: probability 0-1 that a condition holds
@@ -69,7 +69,7 @@ const questions: DecisionQuestion[] = [
 Independent questions share one `input` and one request:
 
 ```ts no-run
-import { decide, type DecisionQuestion } from 'lousho';
+import { decide, type DecisionQuestion } from '@linuxdevil/lousho';
 
 const questions: DecisionQuestion[] = [
   { type: 'predicate', name: 'is_spam', instructions: 'Is this spam?' },
@@ -91,7 +91,7 @@ const byName = Object.fromEntries(answers.map((a) => [a.name, a]));
 ## Options
 
 ```ts no-run
-import { decide } from 'lousho';
+import { decide } from '@linuxdevil/lousho';
 
 const result = await decide({
   input: '...',
diff --git a/docs/deployment.md b/docs/deployment.md
index 987585752..c215d4825 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -4,7 +4,7 @@
 into a deployable artifact for one target platform:
 
 ```bash
-npx lousho build --target=<target> --agent=agent.yaml [--out=<dir>]
+npx @linuxdevil/lousho build --target=<target> --agent=agent.yaml [--out=<dir>]
 ```
 
 It runs the target's adapter through three steps - **scaffold** (write the
@@ -30,7 +30,7 @@ All three targets also take an [agent directory](./agent-directories.md)
 in place of a spec file (the path may be positional or `--agent`):
 
 ```bash
-npx lousho build ./my-agent --target=node-server
+npx @linuxdevil/lousho build ./my-agent --target=node-server
 node .lousho/build/node-server/dist/server.js
 ```
 
@@ -41,7 +41,7 @@ directory's [schedules](./schedules.md) when it listens, mounts its
 routes keep the bearer token), and logs `schedules: ...; channels: ...`.
 The directory's code files are pre-bundled with the build's tsup step into
 `dist/agent/**.js` (one ESM build sharing one copy of the SDK, so a `from
-'lousho'` import in a tool is the SDK the server runs), and
+'@linuxdevil/lousho'` import in a tool is the SDK the server runs), and
 only the files the server reads as data are copied: `instructions.md`,
 `instructions/`, `skills/`, a JSON/YAML config, and the same in each
 `subagents/<name>/`. Nothing else in the directory reaches `dist/`: not `.env`
@@ -62,7 +62,7 @@ only a Worker-safe part of `lousho`
 ([Cloudflare Workers](./cloudflare-workers.md#build-and-deploy) has the details):
 
 ```bash
-npx lousho build ./my-agent --target=cloudflare-worker
+npx @linuxdevil/lousho build ./my-agent --target=cloudflare-worker
 ```
 
 ## Agent modules
@@ -73,7 +73,7 @@ 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
+npx @linuxdevil/lousho build src/agent.ts --target=node-server
 node .lousho/build/node-server/dist/server.js
 ```
 
@@ -291,7 +291,7 @@ signal handler: stop accepting, let the requests in flight finish, then call
 
 ```ts
 import { createServer } from 'node:http';
-import { createAgent, mountChannels } from 'lousho';
+import { createAgent, mountChannels } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 const handler = mountChannels(agent, []);
diff --git a/docs/durable-execution.md b/docs/durable-execution.md
index 3fce903a6..626c206b3 100644
--- a/docs/durable-execution.md
+++ b/docs/durable-execution.md
@@ -10,8 +10,8 @@ and any `ApprovalStore` work the same way.
 See also: [Pause, restart, resume](./pause-and-resume.md), a short end-to-end tutorial.
 
 ```ts
-import { createAgent } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
+import { createAgent } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
 
 const agent = createAgent({ provider, store: new SqliteStore('./.lousho/jobs.db') });
 
@@ -104,7 +104,7 @@ session (the session already has its system prompt). To end a session and
 start over under the same id, call `store.checkpoints.delete(sessionId)`.
 
 ```ts
-import { createAgent, memoryStore, SessionAwaitingApprovalError } from 'lousho';
+import { createAgent, memoryStore, SessionAwaitingApprovalError } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider, store: memoryStore() });
 
@@ -136,7 +136,7 @@ underneath):
 3. calls the model once every call of the turn has exactly one result.
 
 ```ts
-import { createAgent, memoryStore } from 'lousho';
+import { createAgent, memoryStore } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider, store: memoryStore() });
 
@@ -160,7 +160,7 @@ finishes it. `agent.pending()` lists those runs across every session and
 `send(msg, { sessionId })` id, so a restarted process can find them:
 
 ```ts
-import { createAgent, fileStore } from 'lousho';
+import { createAgent, fileStore } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider, store: fileStore('./.lousho') });
 
@@ -225,8 +225,8 @@ without durable writes) is listed as `'in-progress'` with `lastError.code`
 to the code that serves traffic:
 
 ```ts
-import { createAgent, defineTool, memoryStore, PropagatingToolError } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool, memoryStore, PropagatingToolError } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 let charges = 0;
@@ -436,7 +436,7 @@ model calls). To run a job once, derive the `sessionId` from the delivery id
 and look at the checkpoint before sending:
 
 ```ts
-import { createAgent, memoryStore } from 'lousho';
+import { createAgent, memoryStore } from '@linuxdevil/lousho';
 
 const store = memoryStore();
 const agent = createAgent({ provider, store });
@@ -474,7 +474,7 @@ same call is re-run on resume) is passed to `execute`, so it works as an
 idempotency key against a re-run of one call:
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 declare const payments: { charge(amount: number, opts: { idempotencyKey: string }): Promise<{ id: string }> };
@@ -510,7 +510,7 @@ one invoice) needs an idempotency key from your own data, such as the claim id
 in the arguments, checked or passed on to the system you write to:
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 declare const claims: { file(claim: { claimId: string }, opts: { idempotencyKey: string }): Promise<{ id: string }> };
@@ -540,14 +540,14 @@ Which stores keep one:
 | `SqliteStore` | yes (`checkpoint_history` table) | `new SqliteStore(path, { historyLimit })` |
 | `LocalStorageCheckpointStore` | yes | `new LocalStorageCheckpointStore(storage, { historyLimit })` |
 | `fileStore(dir)` (JSON files) | yes (`checkpoint-history/<id>.json`) | `fileStore(dir, { historyLimit })` |
-| `KVCheckpointStore` / `KVStore` (Cloudflare Workers KV, from `lousho/kv`) | yes (see below) | `new KVStore(kv, { historyLimit })` |
+| `KVCheckpointStore` / `KVStore` (Cloudflare Workers KV, from `@linuxdevil/lousho/kv`) | yes (see below) | `new KVStore(kv, { historyLimit })` |
 | Agent Forge's `FileCheckpointStore` | yes | `new FileCheckpointStore(dir, { historyLimit })` |
 | a custom `CheckpointStore` | only if it implements `history()` | - |
 
 For example, with the in-memory store:
 
 ```ts
-import { getCheckpointHistory, memoryStore } from 'lousho';
+import { getCheckpointHistory, memoryStore } from '@linuxdevil/lousho';
 
 const { checkpoints } = memoryStore({ historyLimit: 20 }); // default 50, 0 keeps none
 // new SqliteStore(path, { historyLimit }), new LocalStorageCheckpointStore(storage, { historyLimit })
@@ -602,7 +602,7 @@ saves the result as the `'in-progress'` checkpoint of the new session over
 fork like any unfinished run with `agent.resume(fork.sessionId)`:
 
 ```ts
-import { createAgent, compareTrajectories, memoryStore } from 'lousho';
+import { createAgent, compareTrajectories, memoryStore } from '@linuxdevil/lousho';
 
 const store = memoryStore();
 const assistant = createAgent({ provider, store });
@@ -683,8 +683,8 @@ it and it has no result yet, or the human approved it) always rejects with
 whatever the option.
 
 ```ts
-import { createAgent, memoryStore } from 'lousho';
-import type { LLMProvider } from 'lousho';
+import { createAgent, memoryStore } from '@linuxdevil/lousho';
+import type { LLMProvider } from '@linuxdevil/lousho';
 
 declare const provider: LLMProvider;
 
@@ -725,8 +725,8 @@ call it corresponds to.
 `agent.send(message, { sessionId })`:
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { LocalStorageCheckpointStore } from 'lousho/utils';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { LocalStorageCheckpointStore } from '@linuxdevil/lousho/utils';
 
 const checkpoints = new LocalStorageCheckpointStore(storage);
 
@@ -740,8 +740,8 @@ await AgentExecutor.execute({ agent, input: 'Make it 3 people', provider, sessio
 It throws `SessionAwaitingApprovalError` on a paused session, as `send()` does:
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { SessionAwaitingApprovalError, memoryStore } from 'lousho';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { SessionAwaitingApprovalError, memoryStore } from '@linuxdevil/lousho';
 
 const { checkpoints } = memoryStore();
 
@@ -758,7 +758,7 @@ The exported `resumeAfterApproval()` function is what
 `agent.approvals.resolve()` calls:
 
 ```ts
-import { AgentExecutor, resumeAfterApproval } from 'lousho/executor';
+import { AgentExecutor, resumeAfterApproval } from '@linuxdevil/lousho/executor';
 
 const paused = await AgentExecutor.execute({
   agent, input, provider, toolRegistry, approvalStore, sessionId: 'chat-42', checkpointStore,
@@ -782,8 +782,8 @@ if (paused.finishReason === 'awaiting-approval') {
 fork's `sessionId` is `agent.resume(fork.sessionId)`:
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { compareTrajectories, memoryStore } from 'lousho';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { compareTrajectories, memoryStore } from '@linuxdevil/lousho';
 
 const { checkpoints } = memoryStore();
 await AgentExecutor.execute({ agent, provider, toolRegistry, input: 'Plan my trip', sessionId: 'trip', checkpointStore: checkpoints });
diff --git a/docs/errors.md b/docs/errors.md
index 0b868ff87..9d019cfcd 100644
--- a/docs/errors.md
+++ b/docs/errors.md
@@ -31,7 +31,7 @@ serialising the error is unchanged). It is absent when the run failed before
 it started.
 
 ```ts
-import { createAgent, type RunUsage } from 'lousho';
+import { createAgent, type RunUsage } from '@linuxdevil/lousho';
 
 try {
   await createAgent({ provider }).send('Go');
@@ -52,7 +52,7 @@ on purpose: `PropagatingToolError` and its subclasses (a tool throws one to
 stop the run), `WorkspaceError` (a workspace operation refused or failed -
 the model sees it as a tool error), `McpToolError` (a loaded MCP tool whose
 server reports `isError`; also a tool error), `AuthError` (an
-`lousho/auth` entry rejects the request with its 401 or 403),
+`@linuxdevil/lousho/auth` entry rejects the request with its 401 or 403),
 `CronExpressionError` (`parseCronExpression()`, which
 `defineSchedule()` wraps as `LOUSHO_SCHEDULE_INVALID`) and
 `DecryptionError` (`EncryptionUtils`, `DTOEncryptionFilter`).
@@ -63,7 +63,7 @@ server reports `isError`; also a tool error), `AuthError` (an
 and `.cassette` / `.callNumber` fields.
 
 ```ts
-import { createAgent, SDKError } from 'lousho';
+import { createAgent, SDKError } from '@linuxdevil/lousho';
 
 try {
   await createAgent({ provider, instructions: 'Be brief.' }).send('hi');
@@ -400,7 +400,7 @@ where the agent is being built.
 agent spec has no field for.
 
 **Fix:** build the agent with `createAgent()` and pass the configured tool, e.g.
-`createGitHubTools(config)` from `lousho/integrations`.
+`createGitHubTools(config)` from `@linuxdevil/lousho/integrations`.
 
 **Example:** `tools: [github]` in a spec.
 
@@ -1257,7 +1257,7 @@ dataset and add examples to it (`POST /api/v1/datasets`, `POST
 **Means:** a record/replay cassette is missing, is not valid JSON or does not
 match the recorded request. The message names the file. A mismatch inside a
 run reaches `send()` as the `CassetteMismatchError` itself (from
-`lousho/testing`, with `.cassette` and `.callNumber`) - it is
+`@linuxdevil/lousho/testing`, with `.cassette` and `.callNumber`) - it is
 a test-fixture failure, so it is never compacted into a
 `CompactedLLMProviderError`.
 
@@ -1560,7 +1560,7 @@ keep reaching the run that holds the id.
 
 ### LOUSHO_AUTH_CONFIG_INVALID
 
-**Means:** a route auth helper from `lousho/auth` (`jwt()`,
+**Means:** a route auth helper from `@linuxdevil/lousho/auth` (`jwt()`,
 `oidc()`, `basic()`, `apiToken()`) got options it cannot verify with, and
 refused them when it was created, not at the first request. The message names
 the option: no key source or two of them, an HMAC `secret` shorter than 32
diff --git a/docs/evals.md b/docs/evals.md
index d6da59702..a1f9b8c8c 100644
--- a/docs/evals.md
+++ b/docs/evals.md
@@ -14,7 +14,7 @@ prints a summary and writes JUnit and JSON reports.
 
 ```bash
 npm install --save-dev vitest
-npx lousho eval
+npx @linuxdevil/lousho eval
 ```
 
 ## Writing a trajectory eval
@@ -28,8 +28,8 @@ for the [judge evals](#judge-evals) below.
 ```ts no-run
 // refund.eval.ts
 import { z } from 'zod';
-import { createAgent, defineEval, defineTool, includes } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineEval, defineTool, includes } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const lookupOrder = defineTool({
   name: 'lookup_order',
@@ -111,7 +111,7 @@ it. Pass `{ subagent: 'researcher' }` to look at one sub-agent (and the
 sub-agents under it) only:
 
 ```ts
-import { createAgent, defineEval } from 'lousho';
+import { createAgent, defineEval } from '@linuxdevil/lousho';
 
 const researcher = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You research.', description: 'Finds sources' });
 const agent = createAgent({ model: 'openai/gpt-4o-mini', subagents: { researcher } });
@@ -141,7 +141,7 @@ case `n` times; the case passes when all `n` runs pass, or when at least
 `passAt: k` of them do:
 
 ```ts
-import { createAgent, defineEval } from 'lousho';
+import { createAgent, defineEval } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You handle refunds.' });
 
@@ -167,8 +167,8 @@ any object; its `label` (or `name`, or its `input`) names it.
 
 ```ts no-run
 import { z } from 'zod';
-import { createAgent, defineEval, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineEval, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const lookupOrder = defineTool({
   name: 'lookup_order',
@@ -220,7 +220,7 @@ curl -X POST "$LOUSHO_OBSERVE/api/v1/datasets/refunds/examples" -H 'content-type
 ```
 
 ```ts no-run
-import { createAgent, defineEval, includes } from 'lousho';
+import { createAgent, defineEval, includes } from '@linuxdevil/lousho';
 
 defineEval({
   name: 'refunds',
@@ -258,8 +258,8 @@ it.
 
 ```ts no-run
 // tone.judge.eval.ts: run with `lousho eval --judge`
-import { createAgent, defineEval, atLeast } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineEval, atLeast } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 defineEval({
   name: 'tone',
@@ -338,7 +338,7 @@ model. `--timeout ms` sets the limit for every case (`0` turns it off). With
 One eval can set its own limit, which wins over both:
 
 ```ts
-import { createAgent, defineEval } from 'lousho';
+import { createAgent, defineEval } from '@linuxdevil/lousho';
 
 defineEval({
   name: 'research report',
@@ -379,7 +379,7 @@ jobs:
       - uses: actions/setup-node@v4
         with: { node-version: 22 }
       - run: npm ci
-      - run: npx lousho eval --junit reports/evals.xml --json reports/evals.json
+      - run: npx @linuxdevil/lousho eval --junit reports/evals.xml --json reports/evals.json
       - uses: actions/upload-artifact@v4
         if: always()
         with:
@@ -420,9 +420,9 @@ between: it records each case once against the real provider through
 Your eval files do not change.
 
 ```bash
-npx lousho eval --record        # real provider: writes the cassettes, commit them
-npx lousho eval --replay        # every case from its cassette, no network, no key
-npx lousho eval --drift         # re-record and diff each case's trajectory
+npx @linuxdevil/lousho eval --record        # real provider: writes the cassettes, commit them
+npx @linuxdevil/lousho eval --replay        # every case from its cassette, no network, no key
+npx @linuxdevil/lousho eval --drift         # re-record and diff each case's trajectory
 ```
 
 - **`--record`** runs every case with its agent's real provider and writes one
@@ -475,7 +475,7 @@ a real judge only in `*.judge.eval.ts` files.
 How it works: the run loop sends every model call (`generate` or `stream`, from
 a plain run, a streamed run, a sub-agent or an approval resume) through one
 provider-interception seam, `setProviderInterceptor()` (exported from
-`lousho/testing`; `src/providers/interception.ts` in the
+`@linuxdevil/lousho/testing`; `src/providers/interception.ts` in the
 source). Nothing is installed by default, so the seam is
 free. While a case runs under one of these modes, `lousho eval` answers it with
 the provider wrapped by `recordReplay()` for that case's cassette. You can use
@@ -493,7 +493,7 @@ The same eval file that gates CI in-process can smoke-test a deployed agent (the
 URL and every case runs against the deployment instead of the in-process agent:
 
 ```bash
-npx lousho eval --url https://agent.example.com --token "$DEPLOY_TOKEN"   # or LOUSHO_EVAL_TOKEN
+npx @linuxdevil/lousho eval --url https://agent.example.com --token "$DEPLOY_TOKEN"   # or LOUSHO_EVAL_TOKEN
 ```
 
 Each case gets its own remote session (`POST /chat { sessionId, input }`, one
@@ -519,7 +519,7 @@ and tools the behaviour you want to check.
 In code, pass a `target` (this overrides `agent`; `--url` overrides both):
 
 ```ts
-import { defineEval, remoteTarget } from 'lousho';
+import { defineEval, remoteTarget } from '@linuxdevil/lousho';
 
 defineEval({
   name: 'deployed refund flow',
diff --git a/docs/executor-api.md b/docs/executor-api.md
index 5958368e0..5463e4d9f 100644
--- a/docs/executor-api.md
+++ b/docs/executor-api.md
@@ -15,8 +15,8 @@ take: `temperature` and `maxTokens` (`exporter`, `captureContent` and
 import {
   AgentBuilder,
   AgentExecutor,
-} from 'lousho/executor';
-import { createMockProvider } from 'lousho';
+} from '@linuxdevil/lousho/executor';
+import { createMockProvider } from '@linuxdevil/lousho';
 
 const agent = AgentBuilder.create()
   .setName('Customer Support Agent')
diff --git a/docs/flows.md b/docs/flows.md
index ced5f1eea..6843b11b7 100644
--- a/docs/flows.md
+++ b/docs/flows.md
@@ -6,8 +6,8 @@ Describe the graph with `FlowBuilder` and run it with the static
 `FlowExecutor.execute(flow, context, onEvent?)`.
 
 ```ts
-import { FlowBuilder, FlowExecutor, type EditorStep } from 'lousho/flows';
-import { resolveProvider, type AgentConfig } from 'lousho';
+import { FlowBuilder, FlowExecutor, type EditorStep } from '@linuxdevil/lousho/flows';
+import { resolveProvider, type AgentConfig } from '@linuxdevil/lousho';
 
 // A flow calls an LLMProvider directly (reads OPENAI_API_KEY).
 const provider = resolveProvider('openai/gpt-4o-mini');
@@ -109,7 +109,7 @@ its tool runs:
   never run unapproved.
 
 ```ts
-import { FlowExecutor, type AgentFlow } from 'lousho/flows';
+import { FlowExecutor, type AgentFlow } from '@linuxdevil/lousho/flows';
 
 declare const flow: AgentFlow;
 
@@ -134,7 +134,7 @@ set stays as before: `'{{missing}}'` is `''`, and `'$USD'` (no variable
 named `USD`) is the literal string `'$USD'`.
 
 ```ts
-import type { EditorStep } from 'lousho/flows';
+import type { EditorStep } from '@linuxdevil/lousho/flows';
 
 // With variables { count: 5, tags: ['a', 'b'] }, the tool gets { count: 5, tags: ['a', 'b'], note: 'count: 5' }.
 const step: EditorStep = {
@@ -156,7 +156,7 @@ once it is aborted, no further step starts and the flow fails with the signal's
 to the model request, and a `toolCall` hands it to the tool as `ctx.abortSignal`.
 
 ```ts
-import { FlowExecutor, type AgentFlow } from 'lousho/flows';
+import { FlowExecutor, type AgentFlow } from '@linuxdevil/lousho/flows';
 
 declare const flow: AgentFlow;
 
@@ -214,7 +214,7 @@ Invalid values (`maxAttempts` < 1 or not an integer, a negative `backoffMs`,
 a `timeoutMs` <= 0) fail the step with `LOUSHO_FLOW_INVALID`.
 
 ```ts
-import type { EditorStep } from 'lousho/flows';
+import type { EditorStep } from '@linuxdevil/lousho/flows';
 
 const fetchInvoice: EditorStep = {
   type: 'toolCall',
@@ -248,8 +248,8 @@ from the saved variables. `result.usage` and `result.steps` include the
 earlier attempts.
 
 ```ts
-import { FlowExecutor, type AgentFlow } from 'lousho/flows';
-import { memoryStore } from 'lousho';
+import { FlowExecutor, type AgentFlow } from '@linuxdevil/lousho/flows';
+import { memoryStore } from '@linuxdevil/lousho';
 
 declare const flow: AgentFlow;
 const checkpointStore = memoryStore().checkpoints;
@@ -318,8 +318,8 @@ are cancelled. Steps they completed are kept, and the rest run again on resume.
 To continue, pass the decision to `resume()`:
 
 ```ts
-import { FlowExecutor, type AgentFlow } from 'lousho/flows';
-import { memoryStore } from 'lousho';
+import { FlowExecutor, type AgentFlow } from '@linuxdevil/lousho/flows';
+import { memoryStore } from '@linuxdevil/lousho';
 
 declare const flow: AgentFlow;
 const checkpointStore = memoryStore().checkpoints;
@@ -366,7 +366,7 @@ asked, and the context's `approve` callback decides, exactly as for a
 node's `id`, or its place in the flow).
 
 ```ts
-import type { EditorStep } from 'lousho/flows';
+import type { EditorStep } from '@linuxdevil/lousho/flows';
 
 const steps: EditorStep = {
   type: 'sequence',
@@ -387,7 +387,7 @@ const steps: EditorStep = {
   the decision:
 
 ```ts no-run
-import { FlowExecutor, type AgentFlow } from 'lousho/flows';
+import { FlowExecutor, type AgentFlow } from '@linuxdevil/lousho/flows';
 
 declare const flow: AgentFlow;
 
@@ -411,8 +411,8 @@ An `agent` step calls a `createAgent()` agent registered in the context's
 guardrails and approvals — and the step stores its reply text:
 
 ```ts
-import { createAgent } from 'lousho';
-import { FlowExecutor, type AgentFlow } from 'lousho/flows';
+import { createAgent } from '@linuxdevil/lousho';
+import { FlowExecutor, type AgentFlow } from '@linuxdevil/lousho/flows';
 
 const writer = createAgent({ name: 'writer', model: 'openai/gpt-4o-mini', instructions: 'Draft a reply.' });
 
@@ -457,9 +457,9 @@ typed value rather than text:
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
-import { FlowExecutor, type AgentFlow } from 'lousho/flows';
-import { ToolRegistry } from 'lousho/tools';
+import { createAgent } from '@linuxdevil/lousho';
+import { FlowExecutor, type AgentFlow } from '@linuxdevil/lousho/flows';
+import { ToolRegistry } from '@linuxdevil/lousho/tools';
 
 const researcher = createAgent({ name: 'researcher', model: 'openai/gpt-4o-mini', instructions: 'Answer with three facts.' });
 
diff --git a/docs/guardrails.md b/docs/guardrails.md
index 9397f66bb..afc75c6e1 100644
--- a/docs/guardrails.md
+++ b/docs/guardrails.md
@@ -47,7 +47,7 @@ OpenRouter use `openrouter/<vendor>/<model>` (e.g.
 `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent, moderationGuardrail, piiGuardrail } from 'lousho';
+import { createAgent, moderationGuardrail, piiGuardrail } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   provider,
@@ -87,7 +87,7 @@ import {
   maxLengthGuardrail,
   regexGuardrail,
   type IoGuardrail,
-} from 'lousho';
+} from '@linuxdevil/lousho';
 
 const noProdWrites: IoGuardrail = {
   name: 'no-prod-writes',
@@ -133,7 +133,7 @@ try {
 The last four are a starter set for checks most production agents need:
 
 ```ts
-import { createAgent, piiGuardrail, promptInjectionGuardrail, secretsGuardrail } from 'lousho';
+import { createAgent, piiGuardrail, promptInjectionGuardrail, secretsGuardrail } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   provider,
@@ -181,7 +181,7 @@ proposed patch and rolls the results up into one verdict. The
 agent's patch before a pull request is opened:
 
 ```ts
-import { runPatchChecks, secretScanCheck, createDiffSizeCheck, createCommandCheck } from 'lousho';
+import { runPatchChecks, secretScanCheck, createDiffSizeCheck, createCommandCheck } from '@linuxdevil/lousho';
 
 const verdict = await runPatchChecks(
   { diff: patch },
@@ -221,8 +221,8 @@ function. The executor then calls `sandboxExecute` with the run's
 #### Advanced: the executor API
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { SubprocessSandbox } from 'lousho';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { SubprocessSandbox } from '@linuxdevil/lousho';
 
 // Route a flagged tool (requiresSandbox + sandboxExecute) through a real,
 // Docker-backed sandbox instead of the in-process NoopSandbox default
diff --git a/docs/handoffs.md b/docs/handoffs.md
index 2300c921a..3cf7b724b 100644
--- a/docs/handoffs.md
+++ b/docs/handoffs.md
@@ -19,7 +19,7 @@ description to decide when to hand off), then pass them to the triage agent as
 use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const lookupCharges = defineTool({
@@ -70,7 +70,7 @@ name with one of the agent's tools.
 Wrap a target in `handoff()` to configure it:
 
 ```ts
-import { createAgent, handoff, handoffFilters } from 'lousho';
+import { createAgent, handoff, handoffFilters } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const refunds = createAgent({ name: 'refunds', description: 'Issues refunds', model: 'openai/gpt-4o-mini' });
@@ -122,7 +122,7 @@ the middle of a conversation. Two filters are built in:
 - `handoffFilters.lastUserMessage`: keeps only the last user message.
 
 ```ts
-import { handoffFilters, type HandoffInputData } from 'lousho';
+import { handoffFilters, type HandoffInputData } from '@linuxdevil/lousho';
 
 // The last four messages, without tool traffic.
 const recent = (data: HandoffInputData) => handoffFilters.removeToolCalls(data).slice(-4);
@@ -169,7 +169,7 @@ In a session the active agent is the one the transcript last handed off to
 `session.send()` / `session.stream()` runs that agent:
 
 ```ts no-run
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const billing = createAgent({ name: 'billing', description: 'Handles charges and refunds', model: 'openai/gpt-4o-mini' });
 const triage = createAgent({ name: 'triage', model: 'openai/gpt-4o-mini', handoffs: [billing] });
@@ -187,7 +187,7 @@ its targets, give the target an array and add the lead to it afterwards (the
 array is read at every run):
 
 ```ts
-import { createAgent, handoff, type Handoff } from 'lousho';
+import { createAgent, handoff, type Handoff } from '@linuxdevil/lousho';
 
 const billingHandoffs: Handoff[] = [];
 const billing = createAgent({
@@ -237,7 +237,7 @@ A handoff is reported between the handoff call's `tool.start` / `tool.done`
 and the target's first `step.start`:
 
 ```ts no-run
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const billing = createAgent({ name: 'billing', description: 'Handles charges and refunds', model: 'openai/gpt-4o-mini' });
 const triage = createAgent({ name: 'triage', model: 'openai/gpt-4o-mini', handoffs: [billing] });
diff --git a/docs/hooks.md b/docs/hooks.md
index 814eb1196..039b070b2 100644
--- a/docs/hooks.md
+++ b/docs/hooks.md
@@ -9,8 +9,8 @@ Hooks are code you write, not policy and not a human decision: for rules that al
 Pass hooks to `createAgent({ hooks })`. This one logs every tool call and what it returned:
 
 ```ts
-import { createAgent, defineTool, type AgentHook } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool, type AgentHook } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const auditHook: AgentHook = {
@@ -81,8 +81,8 @@ that throws still rejects the run, as before. Sub-agents inherit the lead
 agent's hooks and their outcomes.
 
 ```ts
-import { createAgent, type AgentHook } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, type AgentHook } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const provider = mockModel(['Done.']);
 
@@ -124,8 +124,8 @@ getting anywhere. It's off unless you add it:
   `LOUSHO_RUN_NO_PROGRESS`, which `agent.recover()` won't retry.
 
 ```ts
-import { createAgent, createProgressGuard, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createProgressGuard, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const lookup = defineTool({
@@ -163,8 +163,8 @@ sees it as `outputCheckFailed` on the result and can fix the output. The check
 is your code, so make it independent of what the model wrote.
 
 ```ts
-import { createAgent, createOutputCheck, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createOutputCheck, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const files = new Map<string, string>();
@@ -194,8 +194,8 @@ await agent.send('Write the report');
 ### Deny a tool by name
 
 ```ts
-import { createAgent, defineTool, type AgentHook } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool, type AgentHook } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const shell = defineTool({
@@ -227,8 +227,8 @@ console.log(result.text);
 Return `{ input }` to run the tool with different arguments. They are validated against the tool's schema again.
 
 ```ts
-import { createAgent, defineTool, type AgentHook } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool, type AgentHook } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const search = defineTool({
@@ -261,8 +261,8 @@ await agent.send('Search for hooks');
 `postToolCall` receives the settled result and may return `{ result }` to replace what the model sees. The tool itself ran unchanged.
 
 ```ts
-import { createAgent, defineTool, type AgentHook } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool, type AgentHook } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const readLog = defineTool({
@@ -296,8 +296,8 @@ console.log(toolMessage?.role); // 'tool': its content is the redacted text
 `preGenerate` sees the live `ctx.messages` and `ctx.request`. Push a message to add context, or change a request field.
 
 ```ts
-import { createAgent, type AgentHook } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, type AgentHook } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const addDate: AgentHook = {
   name: 'add-date',
@@ -335,7 +335,7 @@ refused with a tool error instead of running. See [Approvals](./approvals.md) fo
 `createAgent({ hooks })` takes a plain array. Code that uses the executor API ([The executor API](./executor-api.md)) passes a `HookRegistry`: an ordered collection with `register`, `registerMany`, `get`, `has`, `list`, `unregister`, `clear` and `size()` — `size` is a method (`hooks.size()`), not a `Map`-style property. Registering a second hook with the same `name` replaces the first and logs a warning.
 
 ```ts
-import { HookRegistry, type AgentHook } from 'lousho/hooks';
+import { HookRegistry, type AgentHook } from '@linuxdevil/lousho/hooks';
 
 const redactPii: AgentHook = {
   name: 'redact-pii',
@@ -349,4 +349,4 @@ hooks.register(redactPii);
 console.log(hooks.list().map((hook) => hook.name)); // [ 'redact-pii' ]
 ```
 
-`HookRegistry`, `AgentHook` and the context types are available from the package root and from the `lousho/hooks` subpath. Hooks authored in the Agent Forge canvas editor are compiled into a `HookRegistry` and run sandboxed rather than in the host process: see [Agent Forge](./agent-forge.md#hooks).
+`HookRegistry`, `AgentHook` and the context types are available from the package root and from the `@linuxdevil/lousho/hooks` subpath. Hooks authored in the Agent Forge canvas editor are compiled into a `HookRegistry` and run sandboxed rather than in the host process: see [Agent Forge](./agent-forge.md#hooks).
diff --git a/docs/hosted-tools.md b/docs/hosted-tools.md
index 94ab004ec..8bd0d70af 100644
--- a/docs/hosted-tools.md
+++ b/docs/hosted-tools.md
@@ -6,7 +6,7 @@ web search, code interpreter and file search are the common ones. Put them in
 each call in its events, keeps it on the transcript and counts it in usage.
 
 ```ts
-import { createAgent, webSearch, defineTool } from 'lousho';
+import { createAgent, webSearch, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const saveNote = defineTool({
@@ -109,7 +109,7 @@ providers and with any AI SDK model wrapped by
 [`fromAiSdk()`](./providers.md#any-ai-sdk-model-fromaisdk):
 
 ```ts no-verify
-import { createAgent, fromAiSdk, hostedTool } from 'lousho';
+import { createAgent, fromAiSdk, hostedTool } from '@linuxdevil/lousho';
 import { openai } from '@ai-sdk/openai';
 
 const agent = createAgent({
@@ -126,7 +126,7 @@ A hosted call is reported like a tool call, with `executedBy: 'provider'` on
 `tool.start`, `tool.done` and `tool.error`:
 
 ```ts
-import { createAgent, webSearch } from 'lousho';
+import { createAgent, webSearch } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', tools: [webSearch()] });
 
@@ -180,7 +180,7 @@ without a human, leave the tool out of `tools`, or choose tools per run with a
 function:
 
 ```ts
-import { createAgent, webSearch } from 'lousho';
+import { createAgent, webSearch } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -217,8 +217,8 @@ hosted tools; a resuming agent with a different set reports
 request, so an agent with hosted tools runs offline:
 
 ```ts
-import { createAgent, webSearch } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, webSearch } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const model = mockModel([
   {
diff --git a/docs/improve.md b/docs/improve.md
index 895cc1ac4..47a19d24e 100644
--- a/docs/improve.md
+++ b/docs/improve.md
@@ -32,9 +32,9 @@ It's experimental: its results so far come from a small benchmark.
 For how this fits with recovering failed runs while the agent serves traffic, see [Self-healing and self-improvement](./self-healing.md).
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { formatImproveResult, improveAgent, renderTranscript, type Harness } from 'lousho/improve';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { formatImproveResult, improveAgent, renderTranscript, type Harness } from '@linuxdevil/lousho/improve';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const search = defineTool({
@@ -218,7 +218,7 @@ files.
 your own function, keep its `cached` field so the run is counted as cached.
 
 ```ts
-import { cachedProbe, improveAgent, type Harness, type ImproveOptions } from 'lousho/improve';
+import { cachedProbe, improveAgent, type Harness, type ImproveOptions } from '@linuxdevil/lousho/improve';
 
 declare const harness: Harness;
 declare const probe: ImproveOptions['probe'];
@@ -301,7 +301,7 @@ gate changes: it judges the harness, not the reasons.
 A `CaseCheck` returns `true`, `false`, `null` when it can't score the answer, or `{ passed, failure }`. Return `failure` on a failed answer to name the check it missed, as a custom `probe` does: each editor reads it in that run's record, after `Result: failed`, on one line with forged untrusted markers removed. A check must be synchronous; any other return value throws a `ConfigurationError`. Without it, a failed run whose answer looks right gives the editors nothing to fix. Name the real check; a wrong name is worse than none. A `failure` on a passed answer is dropped.
 
 ```ts
-import type { CaseCheck } from 'lousho/improve';
+import type { CaseCheck } from '@linuxdevil/lousho/improve';
 
 declare function failedTests(input: string, answer: string): string[];
 
@@ -316,7 +316,7 @@ const check: CaseCheck = (input, answer) => {
 With `retryWithDiagnosis`, [`agent.recover()`](./self-healing.md#recover-a-run-now) forks a run that kept failing into a `<id>.heal` session told why it failed. When that fork passes, you hold a pair on the same input: the failed run and a retry that passed. `casesFromRecoveries(db, filter)` finds those pairs in your local database and returns the failed runs as cases, each with a `recovery`: the retry's transcript, rendered with `renderTranscript`, the diagnosis it was given, and its final answer. A fork counts only when it carries the diagnosis and finished with no recorded error, no answer cut short and no low score. That isn't your check, so score each `recovery.answer` with your `CaseCheck` and keep only the ones that pass, then pass them on as `recoveries`:
 
 ```ts
-import { casesFromRecoveries, improveAgent, type CaseCheck, type Harness, type ImproveOptions, type SqlDatabase } from 'lousho/improve';
+import { casesFromRecoveries, improveAgent, type CaseCheck, type Harness, type ImproveOptions, type SqlDatabase } from '@linuxdevil/lousho/improve';
 
 declare const db: SqlDatabase;
 declare const harness: Harness;
@@ -351,7 +351,7 @@ A library keeps lessons from earlier attempts, so later editors can read them. E
 `libraryFiles(dir, domain)` returns up to 20 active lessons as files under `context/library/`, highest-voted first, then newest. Each file is labelled as data with the lesson between untrusted markers, and you pass them to `improveAgent` as `library`. Entries are checked again when read, so an entry file edited by hand that no longer passes is skipped. `voteEntry(dir, id, 'helped' | 'hurt')` counts an outcome, and retires a lesson for good once its hurt votes outnumber its helped votes by two. Votes are appended to `votes.jsonl` next to the entries, so votes cast at once aren't lost. `improveAgent` accepts only files shaped like `libraryFiles` output, named `context/library/<name>.md`.
 
 ```ts
-import { improveAgent, libraryFiles, libraryHome, type Harness, type ImproveOptions } from 'lousho/improve';
+import { improveAgent, libraryFiles, libraryHome, type Harness, type ImproveOptions } from '@linuxdevil/lousho/improve';
 
 declare const harness: Harness;
 declare const probe: ImproveOptions['probe'];
@@ -367,7 +367,7 @@ const result = await improveAgent({ harness, cases: ['stuck'], probe, editor: {
 Once a cycle is decided, `reflect` turns it into at most one lesson. A cycle is decided when its edit was kept, rejected, or applied and then rolled back. A rejected or rolled-back edit teaches as much as a kept one. The reflection session reads four files and nothing else: the review card, the diff, the case verdicts and the outcome. It never sees a raw transcript, and the text that models wrote reaches it between untrusted markers. It replies with an `<experience>` block (cue, lesson, evidence, confidence) or `NO_ENTRY`, and the lesson goes through `addEntry` with the cycle's failed checks, so a refused lesson is reported and never stored. `reflect` never throws. A failure comes back as `error` for you to record, and `tokens` is what it spent, to count toward the cycle's budget, which `maxTokens` caps.
 
 ```ts
-import { libraryHome, reflect, voteOnOutcome, type ImproveResult } from 'lousho/improve';
+import { libraryHome, reflect, voteOnOutcome, type ImproveResult } from '@linuxdevil/lousho/improve';
 
 declare const result: ImproveResult;
 
@@ -391,7 +391,7 @@ The session never sees a held-out case's id: each held-out case appears as `held
 `settleCanary` reads the trial; call it yourself on a timer when you don't use the watcher. After `sessions` candidate sessions it promotes when the share of flagged sessions is 0 or at least 0.05 below the base's rate over its last 20 runs, and no failure class appeared that the base didn't have. It retires early once a promotion is ruled out, and when the directory changed, the loop is paused, the opt-in is removed or `monitor.giveUpDays` pass. A promote goes through `applyProposal`, which checks the proposal again. A canary started in auto mode is queued for a person instead when `improve.json` has since switched to manual. In manual mode, `startCanary` refuses without `approvedBy`, and a canary without an approver serves no one.
 
 ```ts
-import { loadImproveSettings, settleCanary, startCanary, type Harness, type ImproveResult, type SqlDatabase } from 'lousho/improve';
+import { loadImproveSettings, settleCanary, startCanary, type Harness, type ImproveResult, type SqlDatabase } from '@linuxdevil/lousho/improve';
 
 declare const db: SqlDatabase;
 declare const result: ImproveResult;
@@ -474,7 +474,7 @@ See [The monitor](#the-monitor).
 under a harness; `lousho improve` builds it for you.
 
 ```ts
-import { healOnce, loadImproveSettings, type CaseCheck, type HealOptions, type SqlDatabase } from 'lousho/improve';
+import { healOnce, loadImproveSettings, type CaseCheck, type HealOptions, type SqlDatabase } from '@linuxdevil/lousho/improve';
 
 declare const db: SqlDatabase;
 declare const check: CaseCheck;
@@ -596,7 +596,7 @@ tick as a [schedule](./schedules.md) for an agent that already uses
 `schedules/`:
 
 ```ts
-import { improveSchedule, loadImproveSettings, watchAgent, type CaseCheck, type HealOptions, type SqlDatabase } from 'lousho/improve';
+import { improveSchedule, loadImproveSettings, watchAgent, type CaseCheck, type HealOptions, type SqlDatabase } from '@linuxdevil/lousho/improve';
 
 declare const db: SqlDatabase;
 declare const check: CaseCheck;
diff --git a/docs/installation.md b/docs/installation.md
index 086b87533..1f99d3109 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -9,11 +9,11 @@
 ## Install the package
 
 ```bash
-npm install lousho ai zod
+npm install @linuxdevil/lousho ai zod
 # or
-pnpm add lousho ai zod
+pnpm add @linuxdevil/lousho ai zod
 # or
-yarn add lousho ai zod
+yarn add @linuxdevil/lousho ai zod
 ```
 
 `ai` (the Vercel AI SDK: `^4.3.19`, `^6.0.0` or `^7.0.0`) and `zod`
@@ -42,7 +42,7 @@ that pairs with your `ai` major. Install the pair from one row:
 For example, on the current `ai` major:
 
 ```bash
-npm install lousho ai@^7.0.0 zod @ai-sdk/openai@^4.0.0
+npm install @linuxdevil/lousho ai@^7.0.0 zod @ai-sdk/openai@^4.0.0
 ```
 
 **Ollama on `ai` 6/7 needs zod 4.** `ollama-ai-provider-v2` (the Ollama package
@@ -60,7 +60,7 @@ with zod 4, and `ai` 7 with zod 3 and with zod 4. The two zod 4 entries on
 `ai` 6 and 7 also install `ollama-ai-provider-v2` (3.x and 4.x) and run the
 Ollama provider against it, so Ollama on `ai` 6/7 is tested, not assumed.
 
-Peers are loaded on demand: importing `lousho` (or any of
+Peers are loaded on demand: importing `@linuxdevil/lousho` (or any of
 its sub-entries) never loads a provider package, so you only need to install
 the ones you use. Each provider package is loaded the first time that
 provider makes a call; if it is missing, that call fails with a
@@ -74,7 +74,7 @@ npm install @ai-sdk/openai@^0.0.42
 ```
 
 ```ts no-run
-import { MissingPeerDependencyError, resolveProvider } from 'lousho';
+import { MissingPeerDependencyError, resolveProvider } from '@linuxdevil/lousho';
 
 const provider = resolveProvider('openai/gpt-4o-mini'); // needs OPENAI_API_KEY; does not load the peer
 try {
@@ -96,9 +96,9 @@ the `lousho init` questions or code mode installs none of them:
 | --------------------------- | --------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------ |
 | `dockerode`                 | `^5.0.1`  | Docker sandboxing: `SubprocessSandbox` (and `lousho doctor`'s Docker ping)                    | `npm install dockerode@^5.0.1`                   |
 | `@modelcontextprotocol/sdk` | `^1.31.0` | MCP: `createAgent({ mcpServers })` / `connectMcp()`, `serveMcp()` and `lousho mcp`            | `npm install @modelcontextprotocol/sdk@^1.31.0`  |
-| `@opentelemetry/api`        | `^1.9.1`  | OpenTelemetry tracing: `createOtelTraceExporter()` from `lousho/otel`         | `npm install @opentelemetry/api@^1.9.1`          |
-| `react`                     | `^18`, `^19` | The React bindings (`lousho/react`)                                      | `npm install react`                              |
-| `vue`                       | `^3`      | The Vue bindings (`lousho/vue`)                                               | `npm install vue@^3`                             |
+| `@opentelemetry/api`        | `^1.9.1`  | OpenTelemetry tracing: `createOtelTraceExporter()` from `@linuxdevil/lousho/otel`         | `npm install @opentelemetry/api@^1.9.1`          |
+| `react`                     | `^18`, `^19` | The React bindings (`@linuxdevil/lousho/react`)                                      | `npm install react`                              |
+| `vue`                       | `^3`      | The Vue bindings (`@linuxdevil/lousho/vue`)                                               | `npm install vue@^3`                             |
 | `tsup`                      | `^8.0.0`  | `lousho build`, which bundles the agent for each target                                       | `npm install --save-dev tsup@^8.0.0`             |
 | `prompts`                   | `^2.4.2`  | The interactive questions of `lousho init` (`lousho init --yes` and flags need nothing)       | `npm install prompts@^2.4.2`                     |
 | `quickjs-emscripten`        | `^0.32.0` | [Code mode](./code-mode.md): `createAgent({ codeMode })` runs `run_code` scripts in its QuickJS isolate | `npm install quickjs-emscripten@^0.32.0` |
@@ -111,7 +111,7 @@ that names the feature and the exact command, for example:
 The optional package 'dockerode' is not installed, but Docker sandboxing (SubprocessSandbox) needs it. Run: npm install dockerode@^5.0.1
 ```
 
-`npm create lousho` installs `prompts` itself, so scaffolding with it
+`npm create @linuxdevil/lousho` installs `prompts` itself, so scaffolding with it
 needs nothing extra. `lousho doctor` lists every optional peer, what it
 enables and whether it is installed (a missing `dockerode` is an error only
 when the agent spec uses a sandboxed tool).
@@ -129,8 +129,7 @@ The tarball is about 4 MB packed (15 MB unpacked). That is a stated trade-off,
 not an accident: `src/` ships because `lousho build` bundles
 `src/deploy/runtime.worker.ts` and `src/index.ts` from the installed package
 and the `dist/` source maps point at it (the maps carry no embedded source;
-embedding it instead and dropping `src/` measured larger, 5.2 MB packed), and
-`apps/agent-forge/` is the prebuilt dashboard that `lousho studio` serves. The
+embedding it instead and dropping `src/` measured larger, 5.2 MB packed). The
 1 MB `llms-full.txt` is in the repo, not the package.
 
 ## Entry points share code (ESM and CJS)
@@ -151,25 +150,25 @@ The entries `exports` declares, and what each one holds:
 
 | Import specifier | What it holds |
 | ---------------- | ------------- |
-| `lousho` | The root: `createAgent()`, `defineTool()`, `defineChannel()`, agents' public types, events, stores (`memoryStore()`, `fileStore()`), hooks, guardrails, sessions, skills, memory, sub-agents, evals, spec files, deployment types |
-| `lousho/executor` | The executor API (advanced - prefer `createAgent()`): `AgentExecutor`, `AgentBuilder`, `resumeAfterApproval()`, `streamResumeAfterApproval()`, `resumeRequest()`, `ToolRegistry`, `globalToolRegistry` |
-| `lousho/tools` | The tools surface: `defineTool()`, `ToolRegistry`, the built-in tools, MCP/OpenAPI helpers |
-| `lousho/flows` | `FlowBuilder`, `FlowExecutor`, `validateFlow()` and every flow type (`AgentFlow`, `EditorStep`, `FlowExecutionEvent`, ...) |
-| `lousho/integrations` | The credentialed third-party tools: `createJiraTools()`, `createGitHubTools()`, `createSlackTool()` / `slackTool`, `postSlackAlert()`, `createEmailTool()` and their types |
-| `lousho/utils` | `EncryptionUtils`, `sha256()`, `generatePassword()`, `StorageService`, `StorageServiceApprovalStore`, `LocalStorageCheckpointStore` and the validators (`validateWithSchema`, `isValidEmail`, ...) |
-| `lousho/mcp` | MCP client and server helpers: `connectMcp()`, `loadMcpTools()`, `serveMcp()` |
-| `lousho/types` | The public types without the runtime |
-| `lousho/testing` | `mockModel()`, `recordReplay()` and the offline-test helpers |
-| `lousho/otel` | `createOtelTraceExporter()` (needs the optional `@opentelemetry/api` peer) |
-| `lousho/hooks` | The hooks surface: `HookRegistry`, hook types |
-| `lousho/sqlite` | `SqliteStore` (sessions, checkpoints, approvals and tokens in one SQLite file; needs Node's `node:sqlite`) |
-| `lousho/auth` | Route auth: `routeAuth()`, `jwt()`, `oidc()`, `basic()`, `apiToken()`, `anonymous()` |
-| `lousho/kv` | `KVStore`, `KVCheckpointStore` for a hand-written Cloudflare Worker |
-| `lousho/traces` | `fileTraceExporter()`, `listTraces()`, `readTrace()` (what `lousho traces` reads) |
-| `lousho/triggers` | `TriggerAdapter`, `TriggerRegistry`, `verifySlackSignature`, `parseCronExpression` |
-| `lousho/react` | `useLoushoAgent()` and the React helpers (needs `react`) |
-| `lousho/vue` | `useLoushoAgent()` as a Vue composable (needs `vue`) |
-| `lousho/svelte` | `loushoAgent()` as a Svelte store |
+| `@linuxdevil/lousho` | The root: `createAgent()`, `defineTool()`, `defineChannel()`, agents' public types, events, stores (`memoryStore()`, `fileStore()`), hooks, guardrails, sessions, skills, memory, sub-agents, evals, spec files, deployment types |
+| `@linuxdevil/lousho/executor` | The executor API (advanced - prefer `createAgent()`): `AgentExecutor`, `AgentBuilder`, `resumeAfterApproval()`, `streamResumeAfterApproval()`, `resumeRequest()`, `ToolRegistry`, `globalToolRegistry` |
+| `@linuxdevil/lousho/tools` | The tools surface: `defineTool()`, `ToolRegistry`, the built-in tools, MCP/OpenAPI helpers |
+| `@linuxdevil/lousho/flows` | `FlowBuilder`, `FlowExecutor`, `validateFlow()` and every flow type (`AgentFlow`, `EditorStep`, `FlowExecutionEvent`, ...) |
+| `@linuxdevil/lousho/integrations` | The credentialed third-party tools: `createJiraTools()`, `createGitHubTools()`, `createSlackTool()` / `slackTool`, `postSlackAlert()`, `createEmailTool()` and their types |
+| `@linuxdevil/lousho/utils` | `EncryptionUtils`, `sha256()`, `generatePassword()`, `StorageService`, `StorageServiceApprovalStore`, `LocalStorageCheckpointStore` and the validators (`validateWithSchema`, `isValidEmail`, ...) |
+| `@linuxdevil/lousho/mcp` | MCP client and server helpers: `connectMcp()`, `loadMcpTools()`, `serveMcp()` |
+| `@linuxdevil/lousho/types` | The public types without the runtime |
+| `@linuxdevil/lousho/testing` | `mockModel()`, `recordReplay()` and the offline-test helpers |
+| `@linuxdevil/lousho/otel` | `createOtelTraceExporter()` (needs the optional `@opentelemetry/api` peer) |
+| `@linuxdevil/lousho/hooks` | The hooks surface: `HookRegistry`, hook types |
+| `@linuxdevil/lousho/sqlite` | `SqliteStore` (sessions, checkpoints, approvals and tokens in one SQLite file; needs Node's `node:sqlite`) |
+| `@linuxdevil/lousho/auth` | Route auth: `routeAuth()`, `jwt()`, `oidc()`, `basic()`, `apiToken()`, `anonymous()` |
+| `@linuxdevil/lousho/kv` | `KVStore`, `KVCheckpointStore` for a hand-written Cloudflare Worker |
+| `@linuxdevil/lousho/traces` | `fileTraceExporter()`, `listTraces()`, `readTrace()` (what `lousho traces` reads) |
+| `@linuxdevil/lousho/triggers` | `TriggerAdapter`, `TriggerRegistry`, `verifySlackSignature`, `parseCronExpression` |
+| `@linuxdevil/lousho/react` | `useLoushoAgent()` and the React helpers (needs `react`) |
+| `@linuxdevil/lousho/vue` | `useLoushoAgent()` as a Vue composable (needs `vue`) |
+| `@linuxdevil/lousho/svelte` | `loushoAgent()` as a Svelte store |
 
 ### TypeScript settings
 
@@ -239,8 +238,8 @@ one-line `CLAUDE.md` importing it) telling coding agents the project's files,
 scripts and conventions. It then installs the dependencies and runs `git init`.
 
 ```bash
-npm create lousho my-agent   # or: npx lousho init my-agent
-npx lousho init my-agent --yes --provider anthropic --template tools --no-install
+npm create @linuxdevil/lousho my-agent   # or: npx @linuxdevil/lousho init my-agent
+npx @linuxdevil/lousho init my-agent --yes --provider anthropic --template tools --no-install
 ```
 
 | Flag | Meaning |
@@ -256,16 +255,26 @@ npx lousho init my-agent --yes --provider anthropic --template tools --no-instal
 `create-lousho` (`packages/create-lousho`) is a thin wrapper that
 runs `lousho init` with the same arguments.
 
-## The `lousho` CLI
+## The `@linuxdevil/lousho` CLI
 
-Installing the package also installs the `lousho` command: `init`, `doctor`,
-`dev`, `chat`, `acp`, `add`, `mcp`, `eval`, `traces`, `build` and `studio`. See
+Installing the package also installs the `@linuxdevil/lousho` command: `init`, `doctor`,
+`dev`, `chat`, `acp`, `add`, `mcp`, `eval`, `traces`, `build`, `studio`,
+`observe`, `bridge` and more. See
 [CLI](./cli.md) for what each one does and its flags. Building needs `tsup`,
 an optional peer (see the table above): `npm install --save-dev tsup`.
 
+### Studio (optional)
+
+The visual dashboard, Lousho Studio, is a separate package,
+`@linuxdevil/studio` - it is not part of this tarball. Install it with
+`npm i -g @linuxdevil/studio` (or run `npx @linuxdevil/studio`), or just run
+`lousho studio` inside a project that has the SDK: the launcher finds an
+installed Studio and opens the folder as a workspace. See
+[Lousho Studio](./agent-forge.md).
+
 ## Troubleshooting: lousho doctor
 
-Run `npx lousho doctor` right after installing. It prints one line per check
+Run `npx @linuxdevil/lousho doctor` right after installing. It prints one line per check
 with a status (`ok`, `warn`, `FAIL`), what it found, and, for anything that is
 not ok, the command to run or the setting to change:
 
diff --git a/docs/mcp.md b/docs/mcp.md
index 583746af5..fcf8ea785 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -2,7 +2,7 @@
 
 MCP works in two directions. Your agent can call the tools of MCP servers, or
 your agent can be an MCP server that Claude Code, Cursor and other MCP clients
-call. Both live in the `lousho/mcp` subpath, and
+call. Both live in the `@linuxdevil/lousho/mcp` subpath, and
 `@modelcontextprotocol/sdk` is an optional peer: install it to use either
 direction.
 
@@ -11,7 +11,7 @@ npm install @modelcontextprotocol/sdk
 ```
 
 `connectMcp`, `loadMcpTools` and `serveMcp` are exported from
-`lousho/mcp`; the package root and `lousho/tools`
+`@linuxdevil/lousho/mcp`; the package root and `@linuxdevil/lousho/tools`
 export them too. `createAgent({ mcpServers })` needs no import from the subpath.
 
 ## Use MCP servers in an agent
@@ -26,7 +26,7 @@ or `ready()`, reconnects. Without `mcpServers`, `ready()` and `close()` do nothi
 `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts no-run
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -122,8 +122,8 @@ own tools and MCP tools can sit in one list. (Spreading into one record,
 `tools: { ...mcp.tools, my_tool: myTool }`, works too.)
 
 ```ts no-run
-import { createAgent } from 'lousho';
-import { connectMcp } from 'lousho/mcp';
+import { createAgent } from '@linuxdevil/lousho';
+import { connectMcp } from '@linuxdevil/lousho/mcp';
 
 const mcp = await connectMcp(
   { files: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '.'] } },
@@ -200,7 +200,7 @@ in `loadMcpTools(client, name, { approval })`:
 `allow`, `deny` or `ask`.
 
 ```ts no-run
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -224,15 +224,15 @@ its tools with `loadMcpTools()`, then pass the result to `createAgent()` (or
 register it on a `ToolRegistry`):
 
 ```ts
-import { createAgent } from 'lousho';
-import { loadMcpTools } from 'lousho/mcp';
+import { createAgent } from '@linuxdevil/lousho';
+import { loadMcpTools } from '@linuxdevil/lousho/mcp';
 
 const tools = await loadMcpTools(mcpClient, 'my-server');
 const agent = createAgent({ instructions: '...', provider, tools });
 ```
 
 `loadMcpTools` is also available from the package root and from
-`lousho/tools`.
+`@linuxdevil/lousho/tools`.
 
 ## Serve an agent over MCP
 
@@ -241,8 +241,8 @@ optionally, some of its tools) as an MCP server, so Claude Code, Cursor and
 other MCP clients can call it.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { serveMcp } from 'lousho/mcp';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { serveMcp } from '@linuxdevil/lousho/mcp';
 import { z } from 'zod';
 
 const searchDocs = defineTool({
@@ -307,7 +307,7 @@ needs approval is never advertised read-only. The built-in `read_file`, `list_di
 `glob`, `grep`, `todo_read`, `current_date` and `day_name` tools are read-only.
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const lookupOrder = defineTool({
@@ -324,8 +324,8 @@ const lookupOrder = defineTool({
 `lousho mcp` serves an agent spec file (stdio by default):
 
 ```sh
-npx lousho mcp agent.yaml
-npx lousho mcp agent.yaml --http --port 3920 --host 127.0.0.1
+npx @linuxdevil/lousho mcp agent.yaml
+npx @linuxdevil/lousho mcp agent.yaml --http --port 3920 --host 127.0.0.1
 ```
 
 To use it from an MCP client, add it to the client's MCP config (for example
diff --git a/docs/memory.md b/docs/memory.md
index 70cf97379..89276b3c5 100644
--- a/docs/memory.md
+++ b/docs/memory.md
@@ -36,7 +36,7 @@ The `vendor/` model prefix chooses the provider; with OpenRouter use
 `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts no-run
-import { createAgent, defineMemory, fileMemory } from 'lousho';
+import { createAgent, defineMemory, fileMemory } from '@linuxdevil/lousho';
 
 const preferences = defineMemory({
   name: 'preferences',
@@ -84,8 +84,8 @@ A scope function sees the run's `sessionId` and the `metadata` passed to
 sessions:
 
 ```ts
-import { createAgent, defineMemory, inMemoryMemory } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineMemory, inMemoryMemory } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const userFacts = defineMemory({
   name: 'user_facts',
@@ -128,7 +128,7 @@ every start: `add()` dedupes on text, so nothing is copied twice. Each copy
 keeps `text` and `metadata` and gets a new `id` and `createdAt`.
 
 ```ts
-import { defineMemory, fileMemory, migrateMemoryKeys } from 'lousho';
+import { defineMemory, fileMemory, migrateMemoryKeys } from '@linuxdevil/lousho';
 
 const provider = fileMemory({ dir: './.lousho/memory' });
 const notes = defineMemory({ name: 'notes', scope: 'global', provider });
@@ -166,7 +166,7 @@ the count.
 
 ```ts
 import { z } from 'zod';
-import { defineMemory, inMemoryMemory } from 'lousho';
+import { defineMemory, inMemoryMemory } from '@linuxdevil/lousho';
 
 const relationship = defineMemory({
   name: 'relationship',
@@ -197,7 +197,7 @@ adding a second version. The item keeps its id, becomes the newest, and
 
 ```ts
 import { z } from 'zod';
-import { defineMemory, inMemoryMemory } from 'lousho';
+import { defineMemory, inMemoryMemory } from '@linuxdevil/lousho';
 
 const settings = defineMemory({
   name: 'settings',
@@ -283,8 +283,8 @@ by meaning instead of by keyword, use `sqliteVectorMemory()`: see
 [Semantic recall](#semantic-recall).
 
 ```ts no-run
-import { createAgent, defineMemory } from 'lousho';
-import { SqliteStore, sqliteMemory } from 'lousho/sqlite';
+import { createAgent, defineMemory } from '@linuxdevil/lousho';
+import { SqliteStore, sqliteMemory } from '@linuxdevil/lousho/sqlite';
 
 const store = new SqliteStore('./.lousho/agent.db');
 const notes = defineMemory({ name: 'notes', scope: 'global', provider: sqliteMemory(store) });
@@ -294,7 +294,7 @@ const agent = createAgent({ model: 'openai/gpt-4o-mini', store, memory: [notes]
 For a hosted store or your own ranking, implement `MemoryProvider`:
 
 ```ts
-import type { MemoryItem, MemoryProvider } from 'lousho';
+import type { MemoryItem, MemoryProvider } from '@linuxdevil/lousho';
 
 const items = new Map<string, MemoryItem[]>();
 const myProvider: MemoryProvider = {
@@ -323,8 +323,8 @@ With [`mockModel`](./testing.md), assert on the system prompt of the first
 request and drive the tools with scripted tool calls:
 
 ```ts
-import { createAgent, defineMemory, inMemoryMemory, memoryKey } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineMemory, inMemoryMemory, memoryKey } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const store = inMemoryMemory();
 const notes = defineMemory({ name: 'notes', scope: 'global', provider: store });
@@ -366,7 +366,7 @@ package that pairs with your `ai` major, as for language models). It adds no
 dependency: `ai` is already a peer, and the provider package is yours.
 
 ```ts no-run
-import { createAgent, defineMemory, aiSdkEmbedder, inMemoryVectorMemory } from 'lousho';
+import { createAgent, defineMemory, aiSdkEmbedder, inMemoryVectorMemory } from '@linuxdevil/lousho';
 import { createOpenAI } from '@ai-sdk/openai';
 
 const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
@@ -388,7 +388,7 @@ Two providers rank by meaning, with the same options:
 - `inMemoryVectorMemory({ embedder, maxItems?, minScore? })` keeps items in this
   process.
 - `sqliteVectorMemory(store, { embedder, maxItems?, minScore? })` (from
-  `lousho/sqlite`) keeps them in the agent's SQLite file, in a
+  `@linuxdevil/lousho/sqlite`) keeps them in the agent's SQLite file, in a
   `memory_vectors` table that an existing file gains when it is opened. Vectors
   survive restarts.
 
@@ -412,14 +412,14 @@ re-embeds them in batches and returns how many it changed.
 `reindex(providerKey)` does one key only — for a slot's key, pass
 `memoryKey(slot, ctx)`.
 
-`hashEmbedder()` from `lousho/testing` is a deterministic
+`hashEmbedder()` from `@linuxdevil/lousho/testing` is a deterministic
 offline embedder for tests: a hashed bag of word stems, so texts that share
 words are close. It is not a semantic model and does not know that "vegetarian"
 and "eat" are related.
 
 ```ts
-import { inMemoryVectorMemory } from 'lousho';
-import { hashEmbedder } from 'lousho/testing';
+import { inMemoryVectorMemory } from '@linuxdevil/lousho';
+import { hashEmbedder } from '@linuxdevil/lousho/testing';
 
 const memory = inMemoryVectorMemory({ embedder: hashEmbedder() });
 await memory.add('global', { text: 'Sam is vegetarian' });
diff --git a/docs/migrating-from-ai-sdk.md b/docs/migrating-from-ai-sdk.md
index 2469ef74b..ced133f23 100644
--- a/docs/migrating-from-ai-sdk.md
+++ b/docs/migrating-from-ai-sdk.md
@@ -41,7 +41,7 @@ you already configured (keys, base URL, provider options) works as it is:
 
 ```ts no-run
 import { createOpenAI } from '@ai-sdk/openai';
-import { createAgent, fromAiSdk } from 'lousho';
+import { createAgent, fromAiSdk } from '@linuxdevil/lousho';
 
 const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
 const agent = createAgent({ provider: fromAiSdk(openai.chat('gpt-4o-mini')), instructions: 'You are helpful.' });
@@ -59,7 +59,7 @@ See [Providers](./providers.md#any-ai-sdk-model-fromaisdk) for the options and w
 ```ts no-verify
 import { tool } from 'ai';
 import { z } from 'zod';
-import { createAgent, fromAiSdk, fromAiSdkTools } from 'lousho';
+import { createAgent, fromAiSdk, fromAiSdkTools } from '@linuxdevil/lousho';
 
 const weather = tool({
   description: 'Get the weather in a city',
@@ -85,8 +85,8 @@ and a plain object works too. This one runs offline:
 
 ```ts
 import { z } from 'zod';
-import { createAgent, fromAiSdkTools } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, fromAiSdkTools } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const tools = fromAiSdkTools({
   weather: {
@@ -128,7 +128,7 @@ A `useChat` front end keeps working: the route returns the agent's run as a UI m
 stream.
 
 ```ts no-run
-import { createAgent, fromUIMessages, memoryStore, toUIMessageStreamResponse, type UIMessageLike } from 'lousho';
+import { createAgent, fromUIMessages, memoryStore, toUIMessageStreamResponse, type UIMessageLike } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You are helpful.', store: memoryStore() });
 
diff --git a/docs/migrating-to-create-agent.md b/docs/migrating-to-create-agent.md
index 732917fe3..ff8a511d0 100644
--- a/docs/migrating-to-create-agent.md
+++ b/docs/migrating-to-create-agent.md
@@ -2,7 +2,7 @@
 
 This page is for code that uses `AgentBuilder`, `AgentExecutor`, `ToolRegistry` and
 `resumeAfterApproval()`: the lower-level API the SDK started with. Those exports now
-live at `lousho/executor` and are not going away; if you stay on
+live at `@linuxdevil/lousho/executor` and are not going away; if you stay on
 them, see [The executor API](./executor-api.md). The reason to move is that one
 `createAgent()` call wires tools, stores, approvals, sessions, retries and
 compaction, where the executor makes you assemble each of them and pass them to every
@@ -24,9 +24,9 @@ import {
   AgentExecutor,
   ToolRegistry,
   resumeAfterApproval,
-} from 'lousho/executor';
-import { InMemoryApprovalStore, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+} from '@linuxdevil/lousho/executor';
+import { InMemoryApprovalStore, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
@@ -68,8 +68,8 @@ console.log(result.text); // 'Sent the report to Sam.'
 ```
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
diff --git a/docs/models-and-cost.md b/docs/models-and-cost.md
index 4aa6d6f65..fd876357f 100644
--- a/docs/models-and-cost.md
+++ b/docs/models-and-cost.md
@@ -6,7 +6,7 @@
 Dependency-free helpers for budgeting and context decisions.
 
 ```ts
-import { estimateTokens, estimateCost, getModelInfo, registerModel } from 'lousho';
+import { estimateTokens, estimateCost, getModelInfo, registerModel } from '@linuxdevil/lousho';
 
 // A custom or self-hosted model: add it (or override a built-in) before use.
 registerModel({
@@ -36,7 +36,7 @@ The built-in context windows and prices are a dated snapshot (see the retrieval
 Every `ExecutionResult` (and `agent.send()` result) carries `usage`, the running total of the whole run:
 
 ```ts
-import { createAgent, formatUsage } from 'lousho';
+import { createAgent, formatUsage } from '@linuxdevil/lousho';
 
 const result = await createAgent({ provider, instructions: 'You compare cities.' }).send('Compare 3 cities');
 
@@ -61,7 +61,7 @@ console.log(formatUsage(result.usage)); // 1,234 in / 567 out tokens · $0.0042
 Prices come from the model registry above, so to get a cost for a custom or fine-tuned model, register it under the id you pass as the model:
 
 ```ts
-import { registerModel } from 'lousho';
+import { registerModel } from '@linuxdevil/lousho';
 
 registerModel({
   id: 'ft:gpt-4o-mini:acme',
@@ -82,7 +82,7 @@ Anthropic caches a request prefix only up to a `cache_control` breakpoint that t
 
 ```ts
 import { readFileSync } from 'node:fs';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const longPolicy = readFileSync('./policy.md', 'utf8'); // a long, stable system prompt
 const agent = createAgent({ model: 'openrouter/anthropic/claude-haiku-4.5', instructions: longPolicy }); // promptCaching: 'auto'
diff --git a/docs/nextjs.md b/docs/nextjs.md
index 1d71e66db..352291df7 100644
--- a/docs/nextjs.md
+++ b/docs/nextjs.md
@@ -13,7 +13,7 @@ prefix chooses the provider; with OpenRouter use `openrouter/<vendor>/<model>`
 
 ```ts
 // app/api/agent/[[...path]]/route.ts
-import { createAgent, createRouteHandler, memoryStore } from 'lousho';
+import { createAgent, createRouteHandler, memoryStore } from '@linuxdevil/lousho';
 
 // `store` is what lets a session survive across requests: without one every
 // `agent.session({ id })` the handler opens gets a fresh in-memory transcript,
@@ -36,7 +36,7 @@ and spend your model budget. Pass a bearer token, or a function that checks your
 own session or cookie:
 
 ```ts
-import { createAgent, createRouteHandler } from 'lousho';
+import { createAgent, createRouteHandler } from '@linuxdevil/lousho';
 
 declare function isSignedIn(request: Request): Promise<boolean>;
 
@@ -89,8 +89,8 @@ customer's session (`GET /chat/:id`, to show what they are approving) and to
 decide in it; by default the session belongs to the customer alone:
 
 ```ts
-import { createAgent, createRouteHandler, memoryStore } from 'lousho';
-import { jwt } from 'lousho/auth';
+import { createAgent, createRouteHandler, memoryStore } from '@linuxdevil/lousho';
+import { jwt } from '@linuxdevil/lousho/auth';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', store: memoryStore() });
 const isSupervisor = (principal?: { claims?: Readonly<Record<string, unknown>> }) => principal?.claims?.role === 'supervisor';
@@ -131,7 +131,7 @@ see [Route auth and principals](./auth.md).
 
 ```tsx no-verify
 'use client';
-import { useLoushoAgent } from 'lousho/react';
+import { useLoushoAgent } from '@linuxdevil/lousho/react';
 
 export function Chat() {
   const agent = useLoushoAgent({ url: '/api/agent', headers: { Authorization: `Bearer ${token}` } }, { approvalsUrl: '/api/agent/approvals' });
@@ -158,7 +158,7 @@ const { messages, sendMessage } = useChat({ transport: new DefaultChatTransport(
 The same handler, mounted where the framework wants it:
 
 ```ts
-import { createAgent, createRouteHandler } from 'lousho';
+import { createAgent, createRouteHandler } from '@linuxdevil/lousho';
 
 const { handler } = createRouteHandler(createAgent({ model: 'openai/gpt-4o-mini' }), { basePath: '/agent', auth: 'secret' });
 
diff --git a/docs/oauth.md b/docs/oauth.md
index eb5c96d2c..99ddaaf6f 100644
--- a/docs/oauth.md
+++ b/docs/oauth.md
@@ -38,7 +38,7 @@ token, an operator who knows which authenticator the old tokens belong to moves
 them once:
 
 ```ts
-import { fileStore } from 'lousho';
+import { fileStore } from '@linuxdevil/lousho';
 
 const store = fileStore('./.lousho', { tokenKey: process.env.LOUSHO_TOKEN_KEY });
 const legacy = { owner: 'user', principalId: 'U04ABCDEF' } as const;
@@ -60,7 +60,7 @@ key unambiguous: a principal id containing `|` cannot collide with another
 owner.
 
 ```ts
-import { tokenStoreKey } from 'lousho';
+import { tokenStoreKey } from '@linuxdevil/lousho';
 
 tokenStoreKey('github', { owner: 'app' }); // 'github|app'
 tokenStoreKey('github', { owner: 'user', principalId: 'a|b', issuer: 'https://id.example.com' });
@@ -72,7 +72,7 @@ tokenStoreKey('github', { owner: 'user', principalId: 'a|b', issuer: 'https://id
 `AgentStore.tokens` is an `OAuthTokenStore`:
 
 ```ts
-import { memoryStore } from 'lousho';
+import { memoryStore } from '@linuxdevil/lousho';
 
 const { tokens } = memoryStore();
 const alice = { owner: 'user', principalId: 'alice', issuer: 'https://id.example.com' } as const;
@@ -115,7 +115,7 @@ node -e "console.log(Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toS
 ```
 
 ```ts
-import { createAgent, fileStore, generateTokenKey } from 'lousho';
+import { createAgent, fileStore, generateTokenKey } from '@linuxdevil/lousho';
 
 console.log(generateTokenKey()); // store it as a secret, e.g. LOUSHO_TOKEN_KEY
 
@@ -171,7 +171,7 @@ Define the provider once, at module level next to the tools that use it, with
 `defineOAuthProvider()`. A tool asks for a token with `ctx.getToken(provider)`:
 
 ```ts
-import { createAgent, defineOAuthProvider, defineTool, memoryStore } from 'lousho';
+import { createAgent, defineOAuthProvider, defineTool, memoryStore } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 export const github = defineOAuthProvider({
@@ -236,7 +236,7 @@ the agent's credential for every user: without the token the call fails with
 The operator signs the app in once with `agent.oauth.signInUrl(provider)`:
 
 ```ts
-import { createAgent, defineOAuthProvider, fileStore } from 'lousho';
+import { createAgent, defineOAuthProvider, fileStore } from '@linuxdevil/lousho';
 
 const slackBot = defineOAuthProvider({
   name: 'slack_bot',
@@ -319,7 +319,7 @@ link continues the run by approving the pause. Serving your own route, do the
 same:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider });
 
@@ -393,8 +393,8 @@ token store (encrypted by the persistent stores) under the provider name
 one.
 
 ```ts
-import { createAgent } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
+import { createAgent } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
 
 const agent = createAgent({
   provider,
diff --git a/docs/observability.md b/docs/observability.md
index 43b785168..dbb44e5dc 100644
--- a/docs/observability.md
+++ b/docs/observability.md
@@ -19,14 +19,14 @@ mapping.
 Pass an `exporter` to `createAgent()`; every run of the agent (`send()`,
 `stream()`, session turns, `resume()` and runs continued by
 `agent.approvals.resolve()`) is traced, sub-agents included. To keep traces
-on disk and browse them with `npx lousho traces`, use `fileTraceExporter()`
+on disk and browse them with `npx @linuxdevil/lousho traces`, use `fileTraceExporter()`
 (see [Local traces](#local-traces)). The `vendor/` model prefix chooses the
 provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g.
 `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent } from 'lousho';
-import { fileTraceExporter } from 'lousho/traces';
+import { createAgent } from '@linuxdevil/lousho';
+import { fileTraceExporter } from '@linuxdevil/lousho/traces';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -44,8 +44,8 @@ reported once per exporter with `console.warn` and otherwise ignored.
 With the executor, pass the exporter to `AgentExecutor.execute()`:
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { type TraceExporter } from 'lousho';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { type TraceExporter } from '@linuxdevil/lousho';
 
 const exporter: TraceExporter = {
   onSpanStart: (span) => console.log('[start]', span.kind, span.name),
@@ -56,7 +56,7 @@ await AgentExecutor.execute({ agent, input, provider, toolRegistry, exporter });
 ```
 
 For real OpenTelemetry spans, import `createOtelTraceExporter()` from
-`lousho/otel` (needs the optional peer dependency
+`@linuxdevil/lousho/otel` (needs the optional peer dependency
 `@opentelemetry/api` and a registered `TracerProvider`). It carries span kind
 and error status over to OpenTelemetry. See `examples/tracing`
 (`npm run example:tracing:console`, `npm run example:tracing:otel`, which also prints metrics).
@@ -84,7 +84,7 @@ To put several runs in one trace, pass a span id of yours as `parentSpanId`;
 the run's `invoke_agent` span becomes its child, and its cost rolls up into it:
 
 ```ts
-import { withSpan, type SimpleAgent, type TraceExporter } from 'lousho';
+import { withSpan, type SimpleAgent, type TraceExporter } from '@linuxdevil/lousho';
 
 declare const exporter: TraceExporter;
 declare const planner: SimpleAgent;
@@ -251,7 +251,7 @@ duration metric, only the model and tool calls inside them.
 ```ts
 import { metrics } from '@opentelemetry/api';
 import { ConsoleMetricExporter, MeterProvider, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
-import { createOtelTraceExporter } from 'lousho/otel';
+import { createOtelTraceExporter } from '@linuxdevil/lousho/otel';
 
 // Swap ConsoleMetricExporter for an OTLP exporter to reach any backend.
 metrics.setGlobalMeterProvider(
@@ -321,7 +321,7 @@ piece of plain text (before JSON encoding) and returns what to record; if it
 throws, that text is recorded as `[redacted]` and the run carries on:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 createAgent({
   model: 'openai/gpt-4o-mini',
@@ -337,8 +337,8 @@ createAgent({
 With the executor, opt in per run:
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { type TraceExporter } from 'lousho';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { type TraceExporter } from '@linuxdevil/lousho';
 
 declare const exporter: TraceExporter;
 
@@ -394,13 +394,13 @@ governs only the `gen_ai.*` content attributes.
 
 ## Local traces
 
-`fileTraceExporter()` from `lousho/traces` writes each run to a
+`fileTraceExporter()` from `@linuxdevil/lousho/traces` writes each run to a
 file, and `lousho traces` shows the files in the terminal. No OpenTelemetry
 backend, no extra package.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { fileTraceExporter } from 'lousho/traces';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { fileTraceExporter } from '@linuxdevil/lousho/traces';
 import { z } from 'zod';
 
 const getWeather = defineTool({
@@ -420,10 +420,10 @@ const agent = createAgent({
 Then, from the project directory:
 
 ```bash
-npx lousho traces                 # the 20 most recent runs, newest first
-npx lousho traces --limit 50 --json
-npx lousho traces 3f2a            # one run as a tree; a unique id prefix is enough
-npx lousho traces 3f2a --content  # also the captured messages and tool arguments
+npx @linuxdevil/lousho traces                 # the 20 most recent runs, newest first
+npx @linuxdevil/lousho traces --limit 50 --json
+npx @linuxdevil/lousho traces 3f2a            # one run as a tree; a unique id prefix is enough
+npx @linuxdevil/lousho traces 3f2a --content  # also the captured messages and tool arguments
 ```
 
 ```
@@ -487,6 +487,15 @@ is printed per process and reporting stays off. `LOUSHO_OBSERVE_PROJECT` labels
 the rows; `LOUSHO_OBSERVE_TOKEN` sends a bearer token for daemons bound
 beyond loopback (`--require-token` plus `lousho observe token create`).
 
+`LOUSHO_OBSERVE_PROJECT` also decides where an agent lands in
+[Lousho Studio](./agent-forge.md): set it to a workspace id (shown in Studio's
+**Settings → Workspaces**) and the agent's observed card appears under that
+workspace; unset, the project name is the package name and the agent appears
+under **Elsewhere**. Studio reads the same collector - it attaches to a
+running daemon or starts one itself on loopback (see
+[The collector](./agent-forge.md#the-collector)) - so a deployed agent that
+reports to Studio's collector shows up with no Studio-specific code.
+
 **Security.** Because the loopback daemon takes no token, it refuses requests
 a web page in your browser could forge. On every `/api/*` route:
 
@@ -506,7 +515,7 @@ check comes first.
 
 One SQLite file (default `~/.lousho/observe.db`, WAL mode) holds the fleet's
 observations, sessions, eval scores, prompt versions and shared context.
-`npx lousho studio` renders it (see [Agent Forge](./agent-forge.md#screens)):
+`npx @linuxdevil/studio` renders it (see [Lousho Studio](./agent-forge.md#screens)):
 Traces and Trace (trace trees with latency waterfalls), Threads, Monitoring
 (a live fleet monitor with heartbeat-derived status — a crashed agent's open
 sessions flip to `interrupted` — over per-agent charts of runs, p95 latency,
diff --git a/docs/openapi-tools.md b/docs/openapi-tools.md
index cb8f545be..21c2f3ce4 100644
--- a/docs/openapi-tools.md
+++ b/docs/openapi-tools.md
@@ -6,15 +6,15 @@ the API without a hand-written `defineTool()` per endpoint and without the raw
 [`http` tool](./tools.md#built-in-tools). Operations that change data ask for
 [approval](./approvals.md) by default.
 
-`openApiTools` is exported from `lousho` and
-`lousho/tools`. It needs no extra package. The `vendor/` model
+`openApiTools` is exported from `@linuxdevil/lousho` and
+`@linuxdevil/lousho/tools`. It needs no extra package. The `vendor/` model
 prefix chooses the provider; with OpenRouter use `openrouter/<vendor>/<model>`
 (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ## Quick start
 
 ```ts no-run
-import { createAgent, openApiTools } from 'lousho';
+import { createAgent, openApiTools } from '@linuxdevil/lousho';
 
 const tools = await openApiTools('https://api.example.com/openapi.json', {
   include: ['getOrder', 'refundOrder'],
@@ -75,7 +75,7 @@ destructiveHint: false` on GET, HEAD and OPTIONS; `readOnlyHint: false` on the
 rest, with `destructiveHint: true` for DELETE. Anything that reads annotations treats these tools the way it treats MCP tools.
 
 ```ts no-run
-import { openApiTools } from 'lousho';
+import { openApiTools } from '@linuxdevil/lousho';
 
 declare const spec: object;
 
@@ -93,7 +93,7 @@ never sees it) and added to the request. The value can be a function, called per
 request with the operation and the tool call id.
 
 ```ts no-run
-import { openApiTools } from 'lousho';
+import { openApiTools } from '@linuxdevil/lousho';
 
 declare const spec: object;
 declare const currentTenant: () => string;
@@ -164,7 +164,7 @@ An API with hundreds of operations is hundreds of tools. Give the agent the ones
 it needs with `include` or `exclude`, or with a predicate on `op.tags`:
 
 ```ts no-run
-import { openApiTools } from 'lousho';
+import { openApiTools } from '@linuxdevil/lousho';
 
 declare const spec: object;
 
diff --git a/docs/pause-and-resume.md b/docs/pause-and-resume.md
index e40149621..3e13344b5 100644
--- a/docs/pause-and-resume.md
+++ b/docs/pause-and-resume.md
@@ -13,7 +13,7 @@ section links to the page that has the full detail.
 Set `needsApproval` on the tool. The run pauses before the tool executes:
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 export const refund = defineTool({
@@ -41,9 +41,9 @@ shared by several processes on one host) or `fileStore(dir)` (plain JSON files).
 `finishReason: 'awaiting-approval'` and the id to decide:
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const refund = defineTool({
@@ -78,9 +78,9 @@ run left in the store. `agent.approvals.resolve()` runs the call (or rejects it)
 continues the run, and resolves with the result:
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const refund = defineTool({
@@ -135,8 +135,8 @@ This snippet stands in for the crash with a tool that throws
 step), then recovers:
 
 ```ts
-import { createAgent, defineTool, memoryStore, PropagatingToolError } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool, memoryStore, PropagatingToolError } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 let charges = 0;
diff --git a/docs/permission-modes.md b/docs/permission-modes.md
index 26209dbec..cad1801fa 100644
--- a/docs/permission-modes.md
+++ b/docs/permission-modes.md
@@ -6,8 +6,8 @@ pause (`dontAsk`). Switch it in the middle of a session, the way you would work
 with a coding agent: plan first, then let it edit.
 
 ```ts
-import { createAgent, createFsTools, MemoryWorkspace } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createFsTools, MemoryWorkspace } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const workspace = new MemoryWorkspace({ files: { 'notes.md': '# Notes\n' } });
 const agent = createAgent({
@@ -73,7 +73,7 @@ says nothing is treated as one with side effects and is refused.
 Declare a custom read-only tool like this:
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const lookUpOrder = defineTool({
@@ -95,7 +95,7 @@ The hint is a promise you make about your tool: plan mode trusts it.
 alone, so a tool of your own named `write_file` is not approved silently.
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const appendLine = defineTool({
@@ -140,7 +140,7 @@ Switching is always an explicit call to `setPermissionMode()`. Each switch is
 reported to `onPermissionModeChange` with `{ sessionId, from, to, at }`:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   provider,
diff --git a/docs/prompting-techniques.md b/docs/prompting-techniques.md
index 9a2b1145a..87427ede1 100644
--- a/docs/prompting-techniques.md
+++ b/docs/prompting-techniques.md
@@ -62,8 +62,8 @@ The four operations, and where each lives in the SDK:
 | **Isolate** | Run work in a clean context so detail doesn't flood the lead | Sub-agents (`task` calls see only their prompt), code mode (`run_code` returns one value), the `inputFilter` boundary |
 
 ```ts no-run
-import { createAgent, loadSkills } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, loadSkills } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const provider = mockModel([{ text: 'done' }]);
 const researchAgent = createAgent({ provider, instructions: 'You research one slice.' });
diff --git a/docs/providers.md b/docs/providers.md
index 309baac9f..5e0219785 100644
--- a/docs/providers.md
+++ b/docs/providers.md
@@ -9,7 +9,7 @@ OpenRouter use `openrouter/<vendor>/<model>` (e.g.
 `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { resolveProvider, LLMProviderRegistry } from 'lousho';
+import { resolveProvider, LLMProviderRegistry } from '@linuxdevil/lousho';
 
 // The convenient way — reads the credential from the environment
 const openai = resolveProvider('openai/gpt-4o-mini');       // OPENAI_API_KEY
@@ -39,7 +39,7 @@ the vendor's package (`^1.0.0` with `ai` 4, `^3.0.0` with `ai` 6, `^4.0.0` with
 (`MISTRAL_API_KEY`, `GROQ_API_KEY`, the AWS chain for Bedrock, and so on).
 
 ```ts no-run
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 createAgent({ model: 'mistral/mistral-large-latest' });   // @ai-sdk/mistral
 createAgent({ model: 'bedrock/anthropic.claude-sonnet' }); // @ai-sdk/amazon-bedrock
@@ -89,7 +89,7 @@ it anyway:
    present. With none set it throws an error listing the fixes.
 
 ```ts no-run
-import { createAgent, createMockProvider, resolveProvider } from 'lousho';
+import { createAgent, createMockProvider, resolveProvider } from '@linuxdevil/lousho';
 
 const fromString = createAgent({ model: 'anthropic/claude-sonnet-5-5' });
 const fromInstance = createAgent({ provider: resolveProvider('openai/gpt-4o-mini'), model: 'gpt-4o' });
@@ -107,7 +107,7 @@ error, 5xx) twice by default, and with `fallbackModels` moves on to the next
 model when the call still fails:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -150,7 +150,7 @@ Parts sent through `createAgent()`:
 
 ```ts
 import { readFileSync } from 'node:fs';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'Describe images briefly.', model: 'openai/gpt-4o-mini' });
 
@@ -166,7 +166,7 @@ console.log(answer.text);
 A `Message[]` is passed through as it is; `textOf()` returns the text parts of a message:
 
 ```ts
-import { createAgent, textOf, type Message } from 'lousho';
+import { createAgent, textOf, type Message } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'Describe images briefly.', model: 'openai/gpt-4o-mini' });
 const messages: Message[] = [
@@ -225,8 +225,8 @@ console.log(textOf(messages[0]), '->', result.text);
 `AgentExecutor.execute()` takes the same messages as its `input` (see [the executor API](./executor-api.md)):
 
 ```ts
-import { AgentBuilder, AgentExecutor } from 'lousho/executor';
-import { resolveProvider, type Message } from 'lousho';
+import { AgentBuilder, AgentExecutor } from '@linuxdevil/lousho/executor';
+import { resolveProvider, type Message } from '@linuxdevil/lousho';
 
 const agent = AgentBuilder.create().setName('vision').setPrompt('Describe images briefly.').build();
 const input: Message[] = [
@@ -288,7 +288,7 @@ text is not retried, so it fails after one `timeout`. To fail sooner, lower
 `timeout` or `retry.maxRetries`.
 
 ```ts
-import { OpenAIProvider } from 'lousho';
+import { OpenAIProvider } from '@linuxdevil/lousho';
 
 const provider = new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY!, timeout: 60_000 });
 ```
@@ -302,7 +302,7 @@ Pass `store: true` to have OpenAI store them (for its dashboard logs or
 evals). `store` is ignored with `api: 'chat'`.
 
 ```ts
-import { OpenAIProvider } from 'lousho';
+import { OpenAIProvider } from '@linuxdevil/lousho';
 
 const provider = new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY!, store: true });
 ```
@@ -319,7 +319,7 @@ instead. Install `undici` and pass its `Agent` as the dispatcher:
 
 ```ts
 import { Agent } from 'undici';
-import { createAgent, OpenAIProvider } from 'lousho';
+import { createAgent, OpenAIProvider } from '@linuxdevil/lousho';
 
 // Wait up to 15 minutes for the response headers and between body chunks.
 const dispatcher = new Agent({ headersTimeout: 15 * 60_000, bodyTimeout: 15 * 60_000 });
@@ -347,7 +347,7 @@ your function, so a failure you return from it is classified as it would be
 from the real network:
 
 ```ts
-import { OpenRouterProvider } from 'lousho';
+import { OpenRouterProvider } from '@linuxdevil/lousho';
 
 let failures = 1;
 const provider = new OpenRouterProvider({
@@ -365,7 +365,7 @@ into an `LLMProvider`, so you do not write an adapter:
 
 ```ts
 import { createOpenAI } from '@ai-sdk/openai';
-import { createAgent, fromAiSdk } from 'lousho';
+import { createAgent, fromAiSdk } from '@linuxdevil/lousho';
 
 const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
 const agent = createAgent({
@@ -416,7 +416,7 @@ npm install @earendil-works/pi-ai@^1.0.3
 ```
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 // OpenRouter's `openai/gpt-4o-mini`, through pi's openrouter adapter:
 const agent = createAgent({ model: 'pi/openrouter/openai/gpt-4o-mini' });
@@ -462,7 +462,7 @@ wire format. Point `OpenAIProvider` at the server's `/v1` URL and pick the API
 it implements with `api`:
 
 ```ts no-run
-import { createAgent, OpenAIProvider } from 'lousho';
+import { createAgent, OpenAIProvider } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   provider: new OpenAIProvider({
@@ -515,14 +515,14 @@ Ollama's `/v1` need).
 
 ```ts no-run
 import { createOpenAI } from '@ai-sdk/openai';
-import { createAgent, fromAiSdk } from 'lousho';
+import { createAgent, fromAiSdk } from '@linuxdevil/lousho';
 
 const local = createOpenAI({ baseURL: 'http://localhost:8080/v1', apiKey: 'any' });
 const agent = createAgent({ provider: fromAiSdk(local.chat('qwen3-8b')), instructions: 'You are a helpful assistant.' });
 ```
 
-`npx lousho doctor` shows `OPENAI_BASE_URL` when it is set, and
-`npx lousho doctor --ping` calls `GET <base>/models` on each configured
+`npx @linuxdevil/lousho doctor` shows `OPENAI_BASE_URL` when it is set, and
+`npx @linuxdevil/lousho doctor --ping` calls `GET <base>/models` on each configured
 provider to check that the server answers.
 
 ## Vercel AI SDK versions
diff --git a/docs/queue-and-steer.md b/docs/queue-and-steer.md
index 3624f5756..02c7ce196 100644
--- a/docs/queue-and-steer.md
+++ b/docs/queue-and-steer.md
@@ -15,7 +15,7 @@ reply gets one more step, so the model answers it in the same run. The
 `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 const run = agent.stream('Plan a weekend in Rome.');
@@ -62,8 +62,8 @@ Without a stream, pass an `InputQueue` to `AgentExecutor.execute()` (see
 [the executor API](./executor-api.md)):
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { InputQueue } from 'lousho';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { InputQueue } from '@linuxdevil/lousho';
 
 const inputQueue = new InputQueue();
 const pending = AgentExecutor.execute({ agent, provider, input: 'Plan my trip.', inputQueue });
@@ -90,7 +90,7 @@ the user changes their mind while the agent is still thinking:
 - `applied` is `false` once the run has finished: send the input as a new turn.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 const run = agent.stream('Plan a weekend in Rome.');
diff --git a/docs/quick-start.md b/docs/quick-start.md
index 424d30df9..93e5b37cb 100644
--- a/docs/quick-start.md
+++ b/docs/quick-start.md
@@ -20,19 +20,19 @@ npm test                 # offline tests: no API key needed
 
 To try a locally packed `create-lousho` (`npm pack`), pass the tarball's absolute path with `--package`: `npx --package=/abs/path/create-lousho-x.y.z.tgz create-lousho my-agent`. A bare `npx ../x.tgz` fails on Windows.
 
-`npx lousho init my-agent` is equivalent (pass `--provider`
+`npx @linuxdevil/lousho init my-agent` is equivalent (pass `--provider`
 and `--template`, since it runs without the interactive prompts). Inside a
-project that already has the SDK installed, `npx lousho init` works too: the
-`lousho` command comes from the SDK package, so a bare `npx lousho` outside such
+project that already has the SDK installed, `npx @linuxdevil/lousho init` works too: the
+`lousho` command comes from the SDK package, so a bare `npx @linuxdevil/lousho` outside such
 a project finds nothing to run. Without arguments, `init` asks for the
-directory, provider and template; `npx lousho init --help`
+directory, provider and template; `npx @linuxdevil/lousho init --help`
 lists every flag.
 
 Prefer to add the SDK to an existing project? Install it by hand (see
 [Installation](./installation.md)):
 
 ```bash
-npm install lousho ai@^7.0.0 zod
+npm install @linuxdevil/lousho ai@^7.0.0 zod
 npm install @ai-sdk/openai@^4.0.0 @ai-sdk/anthropic@^4.0.0
 ```
 
@@ -49,7 +49,7 @@ providers). The `vendor/` model prefix chooses the provider; with OpenRouter
 use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4.1-mini`).
 
 ```ts no-run
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4.1-mini', instructions: 'You are a helpful assistant.' });
 const { text } = await agent.send('Hello!');
@@ -72,7 +72,7 @@ whenever the user message mentions a tool's name, so this snippet exercises a
 real tool round trip without an LLM.
 
 ```ts
-import { createAgent, createMockProvider, defineTool } from 'lousho';
+import { createAgent, createMockProvider, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const currentDate = defineTool({
@@ -105,7 +105,7 @@ it for typed events (model text as it arrives, tool calls, step boundaries),
 and `await run.result` for the same result `send()` returns.
 
 ```ts
-import { createAgent, createMockProvider } from 'lousho';
+import { createAgent, createMockProvider } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   instructions: 'You are a helpful assistant.',
@@ -131,7 +131,7 @@ sending the events to a browser.
 keeps the transcript and passes it to the model on each `send()`.
 
 ```ts
-import { createAgent, createMockProvider } from 'lousho';
+import { createAgent, createMockProvider } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   instructions: 'You are a helpful assistant.',
@@ -153,12 +153,12 @@ Pass a store to keep sessions across restarts; see [Sessions](./sessions.md).
 Flag a tool `needsApproval` and the run pauses before calling it. `send()`
 resolves with `finishReason: 'awaiting-approval'` and an `approvalId`; your code
 (or a human) then approves or rejects the call and the run continues. Here
-`mockModel` from `lousho/testing` scripts the model's turns
+`mockModel` from `@linuxdevil/lousho/testing` scripts the model's turns
 exactly, so the tool call is certain.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
@@ -196,8 +196,8 @@ request the agent made, so you can assert on what the model was sent as well as
 on the result. No network, no key.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 let sent: string | undefined;
@@ -244,7 +244,7 @@ the mock provider otherwise - the same pattern the runnable
 [examples](../examples/README.md) use.
 
 ```ts
-import { createAgent, createMockProvider, resolveProvider } from 'lousho';
+import { createAgent, createMockProvider, resolveProvider } from '@linuxdevil/lousho';
 
 const provider = process.env.OPENAI_API_KEY
   ? resolveProvider('openai/gpt-4.1-mini')
@@ -267,7 +267,7 @@ into a live agent with `specToAgent()`. The same shape can be written as a
 YAML or JSON file and loaded with `loadSpec()`.
 
 ```ts
-import { specToAgent, agentSpecSchema } from 'lousho';
+import { specToAgent, agentSpecSchema } from '@linuxdevil/lousho';
 
 const spec = agentSpecSchema.parse({
   name: 'support-bot',
@@ -297,8 +297,8 @@ the same spec runs in the local dev server (chat UI at `/`, `POST /chat`,
 hot reload on save) and builds into a deployable server:
 
 ```bash
-npx lousho dev agent.yaml
-npx lousho build --target=node-server --agent=agent.yaml
+npx @linuxdevil/lousho dev agent.yaml
+npx @linuxdevil/lousho build --target=node-server --agent=agent.yaml
 ```
 
 ## Advanced: the executor API
diff --git a/docs/react.md b/docs/react.md
index ca6ba16e9..33888534d 100644
--- a/docs/react.md
+++ b/docs/react.md
@@ -5,11 +5,11 @@
 render-ready state: messages with their text and tool calls, a `status` for
 the composer, and the tool call waiting for approval, if any.
 
-It lives in the `lousho/react` subpath. `react` (18 or 19) is
+It lives in the `@linuxdevil/lousho/react` subpath. `react` (18 or 19) is
 an optional peer dependency: install it in the app that uses the hook.
 
 ```tsx
-import { useLoushoAgent } from 'lousho/react';
+import { useLoushoAgent } from '@linuxdevil/lousho/react';
 
 export function Chat() {
   const agent = useLoushoAgent({ url: '/api/agent' });
@@ -120,8 +120,8 @@ model prefix chooses the provider; with OpenRouter use
 
 ```ts
 import { createServer, type IncomingMessage } from 'node:http';
-import { createAgent } from 'lousho';
-import type { ApprovalOutcome } from 'lousho/react';
+import { createAgent } from '@linuxdevil/lousho';
+import type { ApprovalOutcome } from '@linuxdevil/lousho/react';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 
@@ -170,8 +170,8 @@ gets a fresh in-memory transcript and the next turn forgets the first (see
 The hook takes the agent itself, too. Called from a custom hook:
 
 ```ts
-import { createAgent } from 'lousho';
-import { useLoushoAgent } from 'lousho/react';
+import { createAgent } from '@linuxdevil/lousho';
+import { useLoushoAgent } from '@linuxdevil/lousho/react';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 
@@ -191,7 +191,7 @@ event)`, a pure reducer over `AgentEvent`s and a few local actions
 exported from the same subpath, for a custom binding or a non-React client:
 
 ```ts
-import { initialAgentUIState, parseEventStream, reduceAgentEvents } from 'lousho/react';
+import { initialAgentUIState, parseEventStream, reduceAgentEvents } from '@linuxdevil/lousho/react';
 
 let state = reduceAgentEvents(initialAgentUIState, { type: 'ui.send', input: 'Weather in Paris?' });
 const response = await fetch('http://localhost:3000/api/agent', {
@@ -219,7 +219,7 @@ chat and the plan. The list carries across turns and is cleared by nothing but a
 new hook (it is not restored when the page reconnects to an existing session).
 
 ```tsx
-import { useLoushoAgent, useTodos } from 'lousho/react';
+import { useLoushoAgent, useTodos } from '@linuxdevil/lousho/react';
 
 export function Plan() {
   const agent = useLoushoAgent({ url: '/api/agent' });
diff --git a/docs/reasoning.md b/docs/reasoning.md
index 514ff3462..24685f44f 100644
--- a/docs/reasoning.md
+++ b/docs/reasoning.md
@@ -7,7 +7,7 @@ as `reasoning.*` events in `agent.stream()`, and as `result.reasoning`. The
 `openrouter/<vendor>/<model>` (e.g. `openrouter/anthropic/claude-sonnet-4.5`).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'anthropic/claude-sonnet-4-5',
diff --git a/docs/registry.md b/docs/registry.md
index ea179c49b..025f7b32d 100644
--- a/docs/registry.md
+++ b/docs/registry.md
@@ -88,7 +88,7 @@ Each item document is:
   "files": [
     {
       "path": "tools/web-search.ts",
-      "content": "import { defineTool } from 'lousho';\nimport { z } from 'zod';\n\nexport default defineTool({\n  name: 'web-search',\n  description: 'Search the web',\n  input: z.object({ query: z.string() }),\n  needsApproval: true,\n  execute: async ({ query }) => {\n    const response = await fetch(`https://api.example.com/search?q=${encodeURIComponent(query)}`, {\n      headers: { authorization: `Bearer ${process.env.SEARCH_KEY}` },\n    });\n    return response.json();\n  },\n});\n"
+      "content": "import { defineTool } from '@linuxdevil/lousho';\nimport { z } from 'zod';\n\nexport default defineTool({\n  name: 'web-search',\n  description: 'Search the web',\n  input: z.object({ query: z.string() }),\n  needsApproval: true,\n  execute: async ({ query }) => {\n    const response = await fetch(`https://api.example.com/search?q=${encodeURIComponent(query)}`, {\n      headers: { authorization: `Bearer ${process.env.SEARCH_KEY}` },\n    });\n    return response.json();\n  },\n});\n"
     }
   ],
   "permissions": {
diff --git a/docs/runs.md b/docs/runs.md
index 0b080977a..a45c12bd8 100644
--- a/docs/runs.md
+++ b/docs/runs.md
@@ -25,7 +25,7 @@ same reason is on `run.done` in [streaming](streaming.md) (and on `finish`,
 the deprecated `onEvent` counterpart).
 
 ```ts
-import { createAgent, createMockProvider } from 'lousho';
+import { createAgent, createMockProvider } from '@linuxdevil/lousho';
 const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider(), maxSteps: 3 });
 const result = await agent.send('Research this thoroughly');
 if (result.finishReason === 'max-steps') console.warn(`Gave up after ${result.steps} steps`);
@@ -38,7 +38,7 @@ Pass an `AbortSignal` to stop a run: `agent.send(input, { signal })`,
 `resumeAfterApproval(..., { signal })`.
 
 ```ts
-import { createAgent, createMockProvider } from 'lousho';
+import { createAgent, createMockProvider } from '@linuxdevil/lousho';
 const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider() });
 const controller = new AbortController();
 setTimeout(() => controller.abort(), 5_000); // e.g. from a Stop button
@@ -49,7 +49,7 @@ console.log(result.finishReason); // 'aborted' if it was cancelled, else 'stop'
 For a time limit, use `AbortSignal.timeout(ms)`:
 
 ```ts
-import { createAgent, createMockProvider } from 'lousho';
+import { createAgent, createMockProvider } from '@linuxdevil/lousho';
 const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider() });
 const result = await agent.send('Summarize this', { signal: AbortSignal.timeout(30_000) });
 ```
@@ -101,7 +101,7 @@ for strictly sequential execution, e.g. when your tools share state that is
 not safe to touch concurrently.
 
 ```ts
-import { createAgent, createMockProvider, defineTool } from 'lousho';
+import { createAgent, createMockProvider, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const getWeather = defineTool({
diff --git a/docs/schedules.md b/docs/schedules.md
index f6869a1cc..562b27415 100644
--- a/docs/schedules.md
+++ b/docs/schedules.md
@@ -12,7 +12,7 @@ Give a cron expression and exactly one of `prompt` (text sent to the agent as a
 new turn) or `run` (your own function).
 
 ```ts
-import { createAgent, createMockProvider, defineSchedule, startSchedules } from 'lousho';
+import { createAgent, createMockProvider, defineSchedule, startSchedules } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You write reports.', provider: createMockProvider() });
 
@@ -58,7 +58,7 @@ server or a test exits normally. A script that does nothing but run schedules
 would therefore exit straight away; pass `keepAlive: true` for that:
 
 ```ts no-run
-import { createAgent, createMockProvider, defineSchedule, startSchedules } from 'lousho';
+import { createAgent, createMockProvider, defineSchedule, startSchedules } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You write reports.', provider: createMockProvider() });
 const running = startSchedules(agent, [defineSchedule({ cron: '@hourly', prompt: 'Check the queue.' })], { keepAlive: true });
@@ -84,7 +84,7 @@ claim is best effort across edge locations (see
 [Durable execution](./durable-execution.md#run-leases)).
 
 ```ts
-import { createAgent, createMockProvider, defineSchedule, fireSchedule } from 'lousho';
+import { createAgent, createMockProvider, defineSchedule, fireSchedule } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You write reports.', provider: createMockProvider() });
 const report = defineSchedule({ name: 'report', cron: '0 9 * * *', prompt: 'Run the daily report.' });
@@ -105,7 +105,7 @@ they show an empty transcript for a schedule id. Read a fire's report from the
 checkpoint store instead, or continue it with `agent.fork(id)`:
 
 ```ts
-import { createAgent, createMockProvider, defineSchedule, fireSchedule, memoryStore } from 'lousho';
+import { createAgent, createMockProvider, defineSchedule, fireSchedule, memoryStore } from '@linuxdevil/lousho';
 
 const store = memoryStore();
 const agent = createAgent({ instructions: 'You write reports.', provider: createMockProvider(), store });
@@ -131,7 +131,7 @@ my-agent/
 `schedules/` loads exactly as before.
 
 ```ts
-import { createAgent, resolveAgentDir, startSchedules } from 'lousho';
+import { createAgent, resolveAgentDir, startSchedules } from '@linuxdevil/lousho';
 
 const { config, schedules } = await resolveAgentDir('./my-agent');
 const agent = createAgent(config);
diff --git a/docs/self-healing.md b/docs/self-healing.md
index c1b9481a6..891905f52 100644
--- a/docs/self-healing.md
+++ b/docs/self-healing.md
@@ -26,8 +26,8 @@ each interrupted run from its last checkpoint, so completed steps don't run
 again.
 
 ```ts
-import { createAgent, createProgressGuard } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
+import { createAgent, createProgressGuard } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
 
 const agent = createAgent({
   provider,
@@ -91,7 +91,7 @@ recorded as not retryable, so `agent.recover()` won't resume the run.
 Each hint, denial and stop is streamed as a `heal.action` event:
 
 ```ts
-import { createAgent, createProgressGuard } from 'lousho';
+import { createAgent, createProgressGuard } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider, hooks: [createProgressGuard()] });
 
@@ -173,8 +173,8 @@ better instructions and skills using failing cases you give it, and returns a
 proposal without writing anything.
 
 ```ts
-import { createAgent } from 'lousho';
-import { formatImproveResult, improveAgent, renderTranscript } from 'lousho/improve';
+import { createAgent } from '@linuxdevil/lousho';
+import { formatImproveResult, improveAgent, renderTranscript } from '@linuxdevil/lousho/improve';
 
 const result = await improveAgent({
   harness: { instructions: 'You answer from the docs.', skills: {} },
diff --git a/docs/sessions.md b/docs/sessions.md
index 9e438f78b..eaf9d5ff9 100644
--- a/docs/sessions.md
+++ b/docs/sessions.md
@@ -9,7 +9,7 @@ See also: [Pause, restart, resume](./pause-and-resume.md), a short end-to-end tu
 > Snippets on this page leave some names to you: `provider` is any `LLMProvider` (offline: `createMockProvider()`).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const chat = createAgent({ instructions: 'Be brief.', provider });
 
@@ -71,7 +71,7 @@ The `vendor/` model prefix chooses the provider; with OpenRouter use
 `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 const session = agent.session({ id: 'user-42', turnPolicy: 'queue' });
@@ -123,7 +123,7 @@ returns the same `AgentRun` (typed events plus a `result` promise, see
 it.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const chat = createAgent({ instructions: 'Be brief.', provider });
 const session = chat.session();
@@ -192,8 +192,8 @@ crash, a failed checkpoint write or a `PropagatingToolError` can then be
 finished later, in another process:
 
 ```ts
-import { createAgent } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
+import { createAgent } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
 
 const agent = createAgent({ provider, store: new SqliteStore('./.lousho/agent.db') });
 
@@ -286,7 +286,7 @@ console.log(finished?.text, await agent.session({ id: 'user-42' }).pending()); /
 A `SessionStore` keeps transcripts between calls:
 
 ```ts
-import type { Message } from 'lousho';
+import type { Message } from '@linuxdevil/lousho';
 
 interface SessionStore {
   load(id: string): Promise<Message[] | undefined>;
@@ -317,7 +317,7 @@ writer in another process can still slip between, losing one turn.
   files on Windows and macOS too.
 
 ```ts
-import { createAgent, FileSessionStore } from 'lousho';
+import { createAgent, FileSessionStore } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider });
 const store = new FileSessionStore('./.lousho/sessions');
@@ -350,7 +350,7 @@ implementation by where the process runs:
 | In memory (`memoryStore()`) | `MemorySessionStore` | in memory | `InMemoryApprovalStore` | Tests, scripts, one process that never restarts |
 | Files (`fileStore(dir)`) | `<dir>/sessions/<id>.json` | `<dir>/checkpoints/`, `<dir>/checkpoint-history/` | `<dir>/approvals/<id>.json` | One machine, you want plain inspectable files |
 | SQLite | `store.sessions` | `store.checkpoints` | `store.approvals` | A Node server: one durable, transactional file, shared by several processes on one host (see [Sharing a SQLite file](#sharing-a-sqlite-file)) |
-| Cloudflare KV (`KVStore` from `lousho/kv`) | `store.sessions` | `store.checkpoints` | `store.approvals` | Workers deployments (see [Deployment](deployment.md)) |
+| Cloudflare KV (`KVStore` from `@linuxdevil/lousho/kv`) | `store.sessions` | `store.checkpoints` | `store.approvals` | Workers deployments (see [Deployment](deployment.md)) |
 
 Each one is an `AgentStore` part: pass them together as
 `createAgent({ store: { sessions, checkpoints, approvals } })`. `memoryStore()`,
@@ -364,7 +364,7 @@ another writer or reader has open fails for a moment with `EPERM`, `EACCES` or
 file still end with one of them (the last rename wins):
 
 ```ts
-import { createAgent, fileStore } from 'lousho';
+import { createAgent, fileStore } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider, store: fileStore('./.lousho') });
 // ./.lousho/sessions/user-42.json, ./.lousho/checkpoints/..., ./.lousho/approvals/...
@@ -401,7 +401,7 @@ session's transcript), and so are pending approvals and OAuth tokens. It
 resolves with the counts, `{ sessions, checkpoints, checkpointHistory, oauthPending }`:
 
 ```ts
-import { fileStore } from 'lousho';
+import { fileStore } from '@linuxdevil/lousho';
 
 const store = fileStore('./.lousho');
 await store.prune({ olderThanMs: 30 * 24 * 60 * 60 * 1000 }); // a month
@@ -416,8 +416,8 @@ generated Worker uses `KVCheckpointStore`, see [Deployment](deployment.md)).
 re-exported from the root entry, so importing the SDK never loads it):
 
 ```ts
-import { createAgent } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
+import { createAgent } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
 
 const store = new SqliteStore('./.lousho/agent.db'); // or ':memory:'
 const agent = createAgent({ provider, store }); // transcripts, per-step checkpoints and approvals
@@ -482,8 +482,8 @@ starts a new session from any of them, so you can try another direction
 without losing the original conversation:
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const searchFlights = defineTool({
diff --git a/docs/skills.md b/docs/skills.md
index e0f4f98db..2bbdaf478 100644
--- a/docs/skills.md
+++ b/docs/skills.md
@@ -22,7 +22,7 @@ can correct itself.
 ## Skills in code
 
 ```ts
-import { createAgent, defineSkill } from 'lousho';
+import { createAgent, defineSkill } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   instructions: 'You are a release engineer.',
@@ -91,7 +91,7 @@ Use the imperative mood and link the PR.
   (both paths are listed).
 
 ```ts
-import { createAgent, loadSkills } from 'lousho';
+import { createAgent, loadSkills } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   instructions: 'You are a release engineer.',
diff --git a/docs/stream-events.md b/docs/stream-events.md
index e323f5e99..24496089c 100644
--- a/docs/stream-events.md
+++ b/docs/stream-events.md
@@ -123,7 +123,7 @@ payload. Each event type is exported too (`TextDeltaEvent`, `ToolDoneEvent`,
 `RunDoneEvent`, ...), and `AgentEventOf<'tool.done'>` picks one by name.
 
 ```ts
-import { isAgentEvent, isToolEvent, type AgentEvent } from 'lousho';
+import { isAgentEvent, isToolEvent, type AgentEvent } from '@linuxdevil/lousho';
 
 function render(event: AgentEvent): string {
   switch (event.type) {
diff --git a/docs/streaming.md b/docs/streaming.md
index bdc23e4f0..3f9de9cbf 100644
--- a/docs/streaming.md
+++ b/docs/streaming.md
@@ -11,7 +11,7 @@ provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g.
 > Snippets on this page leave some names to you: `provider` is any `LLMProvider` (offline: `createMockProvider()`); `agent` is a `createAgent()` result; `input` is the user's text, a `string`; `approvalStore` is an `ApprovalStore`; `toolRegistry` is a `ToolRegistry`.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 
@@ -72,7 +72,7 @@ interface AgentRun extends AsyncIterable<AgentEvent> {
   throw synchronously from `stream()`.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 
@@ -99,7 +99,7 @@ Output guardrails still check only the final reply of a `send()`, as without
 a listener. Sub-agents' events arrive tagged with `subagent`.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -150,7 +150,7 @@ save, so the transcript is complete when the loop ends. An aborted or failed
 run, or one you stop reading early, is not saved.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 const session = agent.session({ id: 'user-42' });
@@ -178,7 +178,7 @@ process, since everything is read from the approval store. A model chosen per
 run (`model` as a function) is the one the paused run used.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider /* , a tool with needsApproval */ });
 const paused = await agent.send('Delete the old reports.');
@@ -197,7 +197,7 @@ of `resumeAfterApproval()` (see [the executor API](./executor-api.md)) and
 returns the same `AgentRun`.
 
 ```ts
-import { AgentExecutor, streamResumeAfterApproval } from 'lousho/executor';
+import { AgentExecutor, streamResumeAfterApproval } from '@linuxdevil/lousho/executor';
 
 const paused = await AgentExecutor.execute({ agent, input, provider, toolRegistry, approvalStore });
 const run = streamResumeAfterApproval({ id: paused.approvalId!, approved: true }, approvalStore, toolRegistry, provider);
@@ -231,7 +231,7 @@ for approval is reported once, by the top-level `approval.requested` (which
 carries the sub-agent's call).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const researcher = createAgent({ provider, instructions: 'You research.', description: 'Finds sources' });
 const lead = createAgent({ provider, instructions: 'You coordinate.', subagents: { researcher } });
@@ -272,7 +272,7 @@ step was running) and `run.done` (`'aborted'`), and `result` resolves with
 `finishReason: 'aborted'`.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 const run = agent.stream('Write a long story');
@@ -290,7 +290,7 @@ To add input to a run that is still going, or to redirect it, see [Queued input
 ## Example: terminal
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const getWeather = defineTool({
@@ -329,7 +329,7 @@ saved even when the client leaves (see [Next.js](./nextjs.md#routes)).
 
 ```ts
 import { createServer } from 'node:http';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 
@@ -372,7 +372,7 @@ with `{ sessionId, input }` streams `agent.session({ id }).stream(input)` as
 needs approval ends the stream with `approval.requested`:
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
 
 const run = AgentExecutor.stream({ agent, input, provider, toolRegistry, approvalStore });
 for await (const event of run) {
diff --git a/docs/structured-output.md b/docs/structured-output.md
index b4877ba02..2916dc857 100644
--- a/docs/structured-output.md
+++ b/docs/structured-output.md
@@ -8,7 +8,7 @@ the provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g.
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -36,7 +36,7 @@ itself) or any other Standard Schema that can produce JSON Schema:
 
 ```ts
 import { z } from 'zod/v4';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', output: z.object({ city: z.string() }) });
 const { object } = await agent.send('Where is the Eiffel Tower?');
@@ -54,7 +54,7 @@ the tool take the data and keep `output` for a summary or status.
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 declare function postComment(comment: { file: string; body: string }): Promise<void>;
 
@@ -77,7 +77,7 @@ from the data (a claim id), because a rerun of the whole flow extracts again:
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 declare function askReviewer(claim: { claimId: string; amountCents: number }): Promise<boolean>;
 declare const claims: { file(claim: { claimId: string; amountCents: number }, opts: { idempotencyKey: string }): Promise<void> };
@@ -106,7 +106,7 @@ turn. There is no per-call `output` override: the schema is the agent's.
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', output: z.object({ city: z.string(), tempC: z.number() }) });
 const session = agent.session();
@@ -136,7 +136,7 @@ read from the `object` of the remote stream's `run.done` event.
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const reporter = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -161,7 +161,7 @@ and `result.object` has no key for it. A field that accepts `null` itself
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openrouter/openai/gpt-4o-mini',
@@ -241,7 +241,7 @@ here; set `'final'` to keep it off those calls):
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o',
@@ -278,7 +278,7 @@ where a failure is yours to report:
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const Invoice = z.object({ subtotal: z.number(), tax: z.number(), total: z.number() });
 const agent = createAgent({ model: 'openai/gpt-4o-mini', output: Invoice });
@@ -330,7 +330,7 @@ progress, and `result.object` for the answer. The UI bindings keep it as
 `partialObject`.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const planner = createAgent({ model: 'openai/gpt-4o-mini', output: z.object({ days: z.array(z.string()) }) });
@@ -347,8 +347,8 @@ schema, or use `createAgent()` for the inferred type.
 
 ```ts
 import { z } from 'zod';
-import { AgentBuilder, AgentExecutor } from 'lousho/executor';
-import { createMockProvider } from 'lousho';
+import { AgentBuilder, AgentExecutor } from '@linuxdevil/lousho/executor';
+import { createMockProvider } from '@linuxdevil/lousho';
 
 const Ticket = z.object({ title: z.string(), priority: z.enum(['low', 'high']) });
 const agent = AgentBuilder.create().setName('triage').setPrompt('You triage bug reports.').build();
@@ -362,8 +362,8 @@ With `mockModel`, script the JSON text the model would write:
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const agent = createAgent({ provider: mockModel(['{"city":"Paris","tempC":21}']), output: z.object({ city: z.string(), tempC: z.number() }) });
 const { object } = await agent.send('Weather in Paris?');
diff --git a/docs/sub-agents.md b/docs/sub-agents.md
index 936b7d476..feda9a74a 100644
--- a/docs/sub-agents.md
+++ b/docs/sub-agents.md
@@ -21,7 +21,7 @@ Give each sub-agent a `description` (the lead model reads it to choose), then
 pass them to the lead as `subagents`:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const researcher = createAgent({
   provider,
@@ -109,8 +109,8 @@ needs no code. A lead that keeps its work across turns or restarts needs a
 store and a session:
 
 ```ts
-import { createAgent } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
+import { createAgent } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
 
 const store = new SqliteStore('./.lousho/agent.db');
 const researcher = createAgent({ provider, instructions: 'You research.', description: 'Finds and summarizes sources' });
@@ -158,7 +158,7 @@ sometimes pass one sub-agent's `taskId` to another and waste a turn on the
 error; this removes the option.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const analyst = createAgent({ provider, instructions: 'You analyze.', description: 'Analyzes data' });
 const lead = createAgent({ provider, subagents: { analyst }, subagentOptions: { continuation: false } });
@@ -194,7 +194,7 @@ At most `maxConcurrent` background sub-agents of one lead run run at once
 as slots free. Set it with `subagentOptions` on `createAgent()`:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const researcher = createAgent({ provider, instructions: 'You research.', description: 'Finds and summarizes sources' });
 
@@ -235,7 +235,7 @@ events arrive before the lead's `run.done`.
 The result lists every background task of the run with its final status:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const researcher = createAgent({ provider, instructions: 'You research.', description: 'Finds and summarizes sources' });
 const lead = createAgent({ provider, instructions: 'You coordinate research.', subagents: { researcher } });
@@ -287,7 +287,7 @@ Limits:
   cannot be resumed: the model chose not to wait for it.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const shell = defineTool({
@@ -318,7 +318,7 @@ the set can change between runs; `resolve()` is called when the lead picks a
 name (return `undefined` for an unknown one).
 
 ```ts
-import { createAgent, type SubagentCatalog } from 'lousho';
+import { createAgent, type SubagentCatalog } from '@linuxdevil/lousho';
 
 const experts = new Map([
   ['researcher', createAgent({ provider, instructions: 'You research.' })],
@@ -340,7 +340,7 @@ next to local ones, and the lead delegates to it with the same `task` tool,
 including `background: true`.
 
 ```ts
-import { createAgent, remoteAgent } from 'lousho';
+import { createAgent, remoteAgent } from '@linuxdevil/lousho';
 
 const lead = createAgent({
   provider,
@@ -404,7 +404,7 @@ final answer becomes the `task` result; a continuation that pauses again pauses
 the lead again.
 
 ```ts
-import type { SimpleAgent } from 'lousho';
+import type { SimpleAgent } from '@linuxdevil/lousho';
 declare const lead: SimpleAgent; // the lead agent above
 
 const paused = await lead.send('Deploy the docs site');
@@ -438,7 +438,7 @@ use the ready-made Pi adapter.
 Pi's tools (`read`, `bash`, `edit`, `write`, ...) work on a local directory.
 
 ```ts
-import { createAgent, piAgent, ask, allow } from 'lousho';
+import { createAgent, piAgent, ask, allow } from '@linuxdevil/lousho';
 import { ModelRuntime } from '@earendil-works/pi-coding-agent';
 
 const runtime = await ModelRuntime.create(); // reads ~/.pi/agent auth, env keys
@@ -529,7 +529,7 @@ the enclosing sub-agent as `parent` when nested deeper. A hook that should only
 see the top-level run returns early:
 
 ```ts
-import { HookRegistry } from 'lousho';
+import { HookRegistry } from '@linuxdevil/lousho';
 
 const hooks = new HookRegistry();
 hooks.register({
@@ -565,7 +565,7 @@ sub-agents it runs inside (e.g. `['researcher']`). Approve or reject it with
 is needed):
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const lead = createAgent({
   provider,
@@ -622,8 +622,8 @@ Resume with `resumeAfterApproval()`, passing the same `subagents` option as the
 paused run:
 
 ```ts
-import { AgentExecutor, resumeAfterApproval, ToolRegistry } from 'lousho/executor';
-import { createAgent } from 'lousho';
+import { AgentExecutor, resumeAfterApproval, ToolRegistry } from '@linuxdevil/lousho/executor';
+import { createAgent } from '@linuxdevil/lousho';
 
 const subagents = { researcher: createAgent({ provider, instructions: 'You research.', description: 'Researches' }) };
 
diff --git a/docs/svelte.md b/docs/svelte.md
index 641613adc..002369681 100644
--- a/docs/svelte.md
+++ b/docs/svelte.md
@@ -6,13 +6,13 @@ sources, the same state and the same actions, over the same
 field means, the two kinds of source, how approvals work and the server side;
 this page covers what differs.
 
-It lives in the `lousho/svelte` subpath. The store implements
+It lives in the `@linuxdevil/lousho/svelte` subpath. The store implements
 Svelte's store contract (`subscribe(run) => unsubscribe`) by hand, so it works
 with `$agent` in Svelte 4 and 5 and needs no `svelte` import: there is no peer
 dependency to install.
 
 ```ts
-import { loushoAgent } from 'lousho/svelte';
+import { loushoAgent } from '@linuxdevil/lousho/svelte';
 
 // In a component's <script lang="ts">, or a module that several components share:
 export const agent = loushoAgent({ url: '/api/agent' }, { approvalsUrl: '/api/approvals' });
@@ -71,7 +71,7 @@ snippets here):
 
 The reducer and the stream parser are exported from this subpath too
 (`reduceAgentEvents`, `initialAgentUIState`, `parseEventStream`), the same
-ones as in `lousho/react`.
+ones as in `@linuxdevil/lousho/react`.
 
 ## Todos
 
@@ -83,7 +83,7 @@ the same stream as the chat, and notifies only when the list changes (see
 [React](./react.md#todos)).
 
 ```ts
-import { loushoAgent, loushoTodos } from 'lousho/svelte';
+import { loushoAgent, loushoTodos } from '@linuxdevil/lousho/svelte';
 
 export const agent = loushoAgent({ url: '/api/agent' });
 export const plan = loushoTodos(agent);
diff --git a/docs/testing.md b/docs/testing.md
index 338a30b82..81cba1084 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -1,6 +1,6 @@
 # Testing agents
 
-`lousho/testing` ships `mockModel`: a scripted, deterministic
+`@linuxdevil/lousho/testing` ships `mockModel`: a scripted, deterministic
 `LLMProvider` for unit tests. You write down what the model should say on each
 turn, run your agent, and then assert on exactly what the agent sent to the
 model. No network, no API keys, no flakiness.
@@ -14,8 +14,8 @@ npm install --save-dev vitest
 A bare string is shorthand for `{ text }`.
 
 ```ts
-import { createAgent } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const model = mockModel(['Hello! How can I help?']);
 const agent = createAgent({ instructions: 'You are friendly.', provider: model });
@@ -37,8 +37,8 @@ ids are generated deterministically (`call_1`, `call_2`, ...) unless you pass
 ```ts no-run
 import { describe, it, expect, vi } from 'vitest';
 import { z } from 'zod';
-import { createAgent, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 describe('weather agent', () => {
   it('calls get_weather and reports the result', async () => {
@@ -77,8 +77,8 @@ when the provider fails.
 
 ```ts no-verify
 import { it, expect } from 'vitest';
-import { createAgent } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 it('surfaces a provider failure', async () => {
   const model = mockModel([{ error: new Error('upstream 503') }]);
@@ -109,7 +109,7 @@ Pass a function to compute a turn from the request. It may be async and may
 return a string or any turn object.
 
 ```ts
-import { mockModel } from 'lousho/testing';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const model = mockModel([(req) => `You said: ${req.messages.at(-1)?.content}`]);
 const result = await model.generate({ messages: [{ role: 'user', content: 'ping' }] });
@@ -136,7 +136,7 @@ request and tells you to add a turn. To replay the final turn forever (handy for
 loop and step-limit tests), pass `{ onExhausted: 'repeat-last' }`:
 
 ```ts
-import { mockModel } from 'lousho/testing';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const looping = mockModel([{ toolCalls: [{ name: 'again' }] }], { onExhausted: 'repeat-last' });
 ```
@@ -161,8 +161,8 @@ OpenRouter use `openrouter/<vendor>/<model>` (e.g.
 `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent, resolveProvider } from 'lousho';
-import { recordReplay } from 'lousho/testing';
+import { createAgent, resolveProvider } from '@linuxdevil/lousho';
+import { recordReplay } from '@linuxdevil/lousho/testing';
 
 const provider = recordReplay(() => resolveProvider('openai/gpt-4o-mini'), {
   cassette: './__cassettes__/refund-flow.json',
@@ -210,7 +210,7 @@ If the change is intentional, re-record the cassette (run with LOUSHO_RECORD=1,
 
 That hint assumes you wired `mode` to `LOUSHO_RECORD` as above. If you record
 some other way, pass `rerecordHint` with the command your project uses; under
-`lousho eval` the hint names `npx lousho eval --record` instead.
+`lousho eval` the hint names `npx @linuxdevil/lousho eval --record` instead.
 
 For parallel or unordered calls pass `match: 'request'`: each call finds the
 first unused entry with an identical request, in any order. Running out of
@@ -227,7 +227,7 @@ changing the schema itself still fails the match. For anything else, pass
 `normalize`:
 
 ```ts
-import { mockModel, recordReplay } from 'lousho/testing';
+import { mockModel, recordReplay } from '@linuxdevil/lousho/testing';
 
 const provider = recordReplay(mockModel(['ok']), {
   cassette: './__cassettes__/users.json',
@@ -277,7 +277,7 @@ the file. Pass `redact` to scrub them (it runs on every recorded string, in both
 requests and responses, and replay applies it when matching):
 
 ```ts
-import { mockModel, recordReplay } from 'lousho/testing';
+import { mockModel, recordReplay } from '@linuxdevil/lousho/testing';
 
 const provider = recordReplay(mockModel(['ok']), {
   cassette: './__cassettes__/support.json',
diff --git a/docs/tool-search.md b/docs/tool-search.md
index 334612797..c471a216d 100644
--- a/docs/tool-search.md
+++ b/docs/tool-search.md
@@ -26,7 +26,7 @@ model prefix chooses the provider; with OpenRouter use
 `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const convertCurrency = defineTool({
@@ -56,7 +56,7 @@ const agent = createAgent({
 Or mark a whole MCP server: every tool it lists is deferred.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -126,7 +126,7 @@ the search. Deferral itself is turned on by marking tools or servers
 | `search(query, tools)` | keyword ranking | Your own ranking (for example embeddings): return tool names, best first. Unknown names and duplicates are dropped. If it throws, the call is a tool error and loads nothing. |
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
diff --git a/docs/tools.md b/docs/tools.md
index bee4082b4..0011c9546 100644
--- a/docs/tools.md
+++ b/docs/tools.md
@@ -9,7 +9,7 @@ accepted (`createAgent({ tools: [...] })`, `ToolRegistry.register(tool)`,
 > Snippets on this page leave some names to you: `provider` is any `LLMProvider` (offline: `createMockProvider()`).
 
 ```ts
-import { defineTool, createAgent, type ToolInput, type ToolOutput } from 'lousho';
+import { defineTool, createAgent, type ToolInput, type ToolOutput } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const weather = defineTool({
@@ -158,7 +158,7 @@ The transcript message carries `isError: true`; `tool-result` events, `onToolRes
 `toolErrorMessage` to `createAgent` to replace the text of `execution` errors:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   instructions: 'You answer questions about orders.',
@@ -218,7 +218,7 @@ its next model call with `finishReason: 'budget-exceeded'` and
 under `onExceeded: 'throw'`, see [Budgets](./configuration.md#budgets)).
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const stats = defineTool({ name: 'stats', description: 'Weekly stats', input: z.object({}), execute: async () => (await fetch('https://stats.example.com/week')).json() });
@@ -238,7 +238,7 @@ if (result.toolErrors) console.warn(`${result.toolErrors} tool call(s) failed; t
 | `createTodoTools()` | `todo_write` / `todo_read` so an agent can plan multi-step work; see [Todo tools](#todo-tools). |
 | `askQuestionTool()`, `createAgent({ askQuestion: true })` | `ask_question`: the agent asks the user something and the run pauses until `agent.approvals.answer()`; see [Asking the user a question](./approvals.md#asking-the-user-a-question). |
 | `createFsTools()`, `createShellTool()` | File system and shell tools for coding agents; see [Workspace tools](./workspace-tools.md). |
-| `createEmailTool()`, `createSlackTool()`, `createGitHubTools()`, `createJiraTools()` (from `lousho/integrations`) | Integrations that need credentials, so they are built with options. `createSlackTool()` reads the webhook URL from `SLACK_WEBHOOK_URL` unless you pass `webhookUrl`; `createJiraTools()` takes `baseUrl`, `email` and `apiToken` explicitly (conventionally from `JIRA_BASE_URL`, `JIRA_EMAIL` and `JIRA_API_TOKEN`). |
+| `createEmailTool()`, `createSlackTool()`, `createGitHubTools()`, `createJiraTools()` (from `@linuxdevil/lousho/integrations`) | Integrations that need credentials, so they are built with options. `createSlackTool()` reads the webhook URL from `SLACK_WEBHOOK_URL` unless you pass `webhookUrl`; `createJiraTools()` takes `baseUrl`, `email` and `apiToken` explicitly (conventionally from `JIRA_BASE_URL`, `JIRA_EMAIL` and `JIRA_API_TOKEN`). |
 | `createAgent({ mcpServers })`, `connectMcp(servers)` | Every tool of MCP servers given as config (stdio `command` or HTTP `url`), named `<server>__<tool>`; see [Use MCP servers in an agent](./mcp.md#use-mcp-servers-in-an-agent). |
 | `openApiTools(document, options)` | One tool per operation of an OpenAPI 3.0 / 3.1 document; mutating operations ask for approval. See [OpenAPI tools](./openapi-tools.md). |
 | `loadMcpTools(client, name)` | Every tool of a connected MCP server; see [MCP tools](./mcp.md#tools-from-a-client-you-connected-yourself). |
@@ -276,7 +276,7 @@ the provider; with OpenRouter use `openrouter/<vendor>/<model>`, e.g.
 `openrouter/openai/gpt-4o-mini`):
 
 ```ts
-import { createAgent, createWebFetchTool } from 'lousho';
+import { createAgent, createWebFetchTool } from '@linuxdevil/lousho';
 
 const webFetch = createWebFetchTool({
   timeoutMs: 30_000, // whole request: redirects and body included
@@ -315,7 +315,7 @@ emits a `todo.updated` stream event with the new list and its counts (see
 `useTodos()` / `loushoTodos()`, so a UI shows the plan live without `onChange`.
 
 ```ts
-import { createAgent, createTodoTools, type TodoStore } from 'lousho';
+import { createAgent, createTodoTools, type TodoStore } from '@linuxdevil/lousho';
 
 const todos = createTodoTools({ onChange: (list) => console.log(list.length, 'todos') });
 const planner = createAgent({ instructions: 'Plan multi-step work, then do it.', provider, tools: todos.tools });
@@ -338,8 +338,8 @@ raw `ToolDescriptor` (a built-in tool, an MCP tool, or an existing `tool()` from
 the `ai` SDK), and `registerMany()` for a record of descriptors or an array of defined tools.
 
 ```ts
-import { ToolRegistry } from 'lousho/tools';
-import { currentDateTool, defineTool } from 'lousho';
+import { ToolRegistry } from '@linuxdevil/lousho/tools';
+import { currentDateTool, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const lookupOrder = defineTool({
@@ -371,7 +371,7 @@ the result `null`, as does any tool that returns `undefined`: the transcript, th
 model and `tool.done` all see `null`.
 
 ```ts
-import { createAgent, defineTool, type ToolOutput } from 'lousho';
+import { createAgent, defineTool, type ToolOutput } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const buildReport = defineTool({
diff --git a/docs/triggers.md b/docs/triggers.md
index aa82b2629..9b611c473 100644
--- a/docs/triggers.md
+++ b/docs/triggers.md
@@ -1,6 +1,6 @@
 # Triggers
 
-A trigger adapter turns one wake-up mechanism into an agent run. The `lousho/triggers` subpath is the extension point for your own mechanism (`TriggerAdapter`, `TriggerRegistry`) plus a few helpers shared with channels and schedules: the `WebhookAuth` shapes, `verifySlackSignature()` and `parseCronExpression()`. The built-in webhook, Slack and cron adapters were removed; see [Migrating from triggers](./upgrading.md#migrating-from-triggers).
+A trigger adapter turns one wake-up mechanism into an agent run. The `@linuxdevil/lousho/triggers` subpath is the extension point for your own mechanism (`TriggerAdapter`, `TriggerRegistry`) plus a few helpers shared with channels and schedules: the `WebhookAuth` shapes, `verifySlackSignature()` and `parseCronExpression()`. The built-in webhook, Slack and cron adapters were removed; see [Migrating from triggers](./upgrading.md#migrating-from-triggers).
 
 ## Choosing between triggers, channels and schedules
 
@@ -30,8 +30,8 @@ Reply semantics differ per adapter. An adapter whose reply is the open request (
 Write your own adapter by returning a handle from `listen`:
 
 ```ts
-import { createAgent, createMockProvider } from 'lousho';
-import type { TriggerAdapter } from 'lousho/triggers';
+import { createAgent, createMockProvider } from '@linuxdevil/lousho';
+import type { TriggerAdapter } from '@linuxdevil/lousho/triggers';
 
 const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider() });
 
@@ -54,7 +54,7 @@ handle.stop();
 The `WebhookAuth` shapes are the reference for `webhookChannel({ auth })` (see [Channels](./channels.md)). `checkWebhookAuth()` and `assertValidWebhookAuth()` are exported for your own handler.
 
 ```ts no-run
-import { createAgent, createMockProvider, mountChannels, webhookChannel } from 'lousho';
+import { createAgent, createMockProvider, mountChannels, webhookChannel } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider() });
 
@@ -99,7 +99,7 @@ sent in clear text.
 `slackChannel()` verifies every request for you (see [Slack in Channels](./channels.md#slack)). For your own handler (slash commands, interactivity), verify the RAW body with `verifySlackSignature()`: HMAC-SHA256 over `v0:{X-Slack-Request-Timestamp}:{raw body}`, compared in constant time with `X-Slack-Signature` (`v0=<hex>`). Requests more than five minutes old, or more than a minute ahead of local time, are rejected (the timestamp is in seconds, as Slack sends it). See [Slack's documentation](https://docs.slack.dev/authentication/verifying-requests-from-slack).
 
 ```ts no-run
-import { verifySlackSignature } from 'lousho/triggers';
+import { verifySlackSignature } from '@linuxdevil/lousho/triggers';
 
 const authentic = verifySlackSignature({
   signingSecret: process.env.SLACK_SIGNING_SECRET ?? '',
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index cceda626c..055fbf909 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -1,7 +1,7 @@
 # Troubleshooting
 
 This page starts from what you see and points to the cause, the fix and the page
-that explains it. First run `npx lousho doctor` ([what it checks](./installation.md#troubleshooting-lousho-doctor)),
+that explains it. First run `npx @linuxdevil/lousho doctor` ([what it checks](./installation.md#troubleshooting-lousho-doctor)),
 then, if you have an error code (`LOUSHO_...`), look it up in [Errors](./errors.md).
 
 ## Setup
@@ -16,7 +16,7 @@ environment (`LOUSHO_CONFIG_MISSING_PROVIDER`).
 ### "The API key is not set"
 
 - **Cause:** the provider's key variable (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`) is not in the environment of the process that runs the agent (`LOUSHO_PROVIDER_MISSING_API_KEY`).
-- **Fix:** set it, or pass a configured provider instance. `npx lousho doctor` prints `set` or `not set` for each key, never the value. The `vendor/` model prefix chooses the provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`) — `model: 'openai/gpt-4o-mini'` needs `OPENAI_API_KEY` even when only `OPENROUTER_API_KEY` is set.
+- **Fix:** set it, or pass a configured provider instance. `npx @linuxdevil/lousho doctor` prints `set` or `not set` for each key, never the value. The `vendor/` model prefix chooses the provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`) — `model: 'openai/gpt-4o-mini'` needs `OPENAI_API_KEY` even when only `OPENROUTER_API_KEY` is set.
 - **More:** [the error](./errors.md#lousho_provider_missing_api_key).
 
 ### "Cannot find package `@ai-sdk/openai`" or "install the optional peer"
@@ -40,7 +40,7 @@ environment (`LOUSHO_CONFIG_MISSING_PROVIDER`).
 ### The Node version is too old
 
 - **Cause:** the SDK needs Node.js 22.19 or newer (`engines.node`).
-- **Fix:** upgrade Node. `npx lousho doctor` compares your version with the requirement.
+- **Fix:** upgrade Node. `npx @linuxdevil/lousho doctor` compares your version with the requirement.
 - **More:** [Requirements](./installation.md#requirements).
 
 ### Ollama and zod versions disagree
@@ -139,7 +139,7 @@ environment (`LOUSHO_CONFIG_MISSING_PROVIDER`).
 
 Open an issue at <https://github.com/LinuxDevil/lousho/issues>. Include:
 
-- the output of `npx lousho doctor --json`,
+- the output of `npx @linuxdevil/lousho doctor --json`,
 - the error code (`LOUSHO_...`) and the full message,
 - the SDK version (`npm ls lousho`) and your `ai` version.
 
diff --git a/docs/upgrading.md b/docs/upgrading.md
index 2ef8e90c4..ef1eab177 100644
--- a/docs/upgrading.md
+++ b/docs/upgrading.md
@@ -16,7 +16,7 @@ Already on `1.0.0-alpha.19`? Skip to
 since.
 
 ```bash
-npm install lousho@^1.0.0-alpha.19
+npm install @linuxdevil/lousho@^1.0.0-alpha.19
 ```
 
 ## Import paths that moved
@@ -27,23 +27,23 @@ are unchanged apart from where they live.
 
 | Name(s) | Old import | New import |
 | ------- | ---------- | ---------- |
-| `AgentExecutor`, `AgentBuilder`, `ExecuteOptions`, `ResumeExecuteOptions`, `ResumeRequest`, `resumeAfterApproval()`, `streamResumeAfterApproval()`, `resumeRequest()` | `lousho` or `lousho/core` | `lousho/executor` |
-| `ToolRegistry`, `globalToolRegistry` | `lousho` or `lousho/core` | `lousho/executor` (also still in `lousho/tools`) |
-| `ExecutionResult`, `ExecutionFinishReason` (the executor's types) | `lousho/core` | `lousho/executor` (`ExecutionResult` is also still in the root, where `createAgent()`'s result type lives) |
-| `FlowBuilder`, `FlowExecutor`, `validateFlow` and every flow type (`AgentFlow`, `EditorStep`, `FlowExecutionEvent`, ...) | `lousho` or `lousho/types` | `lousho/flows` |
-| `createJiraTools`, `createGitHubTools`, `createSlackTool`, `slackTool`, `postSlackAlert`, `createEmailTool` and their types | `lousho` or `lousho/tools` | `lousho/integrations` |
-| `EncryptionUtils`, `DTOEncryptionFilter`, `DecryptionError`, `sha256`, `generatePassword` | `lousho` | `lousho/utils` |
-| `StorageService`, `StorageServiceApprovalStore`, `LocalStorageCheckpointStore` | `lousho` | `lousho/utils` (with `createAgent()` stores, prefer `fileStore(dir)` from the root) |
-| `validateWithSchema`, `safeValidate`, `isValidEmail` and the other validators | `lousho` | `lousho/utils` |
-
-The `lousho/core` subpath no longer exists; everything it
+| `AgentExecutor`, `AgentBuilder`, `ExecuteOptions`, `ResumeExecuteOptions`, `ResumeRequest`, `resumeAfterApproval()`, `streamResumeAfterApproval()`, `resumeRequest()` | `lousho` or `@linuxdevil/lousho/core` | `@linuxdevil/lousho/executor` |
+| `ToolRegistry`, `globalToolRegistry` | `lousho` or `@linuxdevil/lousho/core` | `@linuxdevil/lousho/executor` (also still in `@linuxdevil/lousho/tools`) |
+| `ExecutionResult`, `ExecutionFinishReason` (the executor's types) | `@linuxdevil/lousho/core` | `@linuxdevil/lousho/executor` (`ExecutionResult` is also still in the root, where `createAgent()`'s result type lives) |
+| `FlowBuilder`, `FlowExecutor`, `validateFlow` and every flow type (`AgentFlow`, `EditorStep`, `FlowExecutionEvent`, ...) | `lousho` or `@linuxdevil/lousho/types` | `@linuxdevil/lousho/flows` |
+| `createJiraTools`, `createGitHubTools`, `createSlackTool`, `slackTool`, `postSlackAlert`, `createEmailTool` and their types | `lousho` or `@linuxdevil/lousho/tools` | `@linuxdevil/lousho/integrations` |
+| `EncryptionUtils`, `DTOEncryptionFilter`, `DecryptionError`, `sha256`, `generatePassword` | `lousho` | `@linuxdevil/lousho/utils` |
+| `StorageService`, `StorageServiceApprovalStore`, `LocalStorageCheckpointStore` | `lousho` | `@linuxdevil/lousho/utils` (with `createAgent()` stores, prefer `fileStore(dir)` from the root) |
+| `validateWithSchema`, `safeValidate`, `isValidEmail` and the other validators | `lousho` | `@linuxdevil/lousho/utils` |
+
+The `@linuxdevil/lousho/core` subpath no longer exists; everything it
 exported is under `/executor`.
 
 ```ts
-import { AgentExecutor, AgentBuilder, ToolRegistry } from 'lousho/executor';
-import { FlowBuilder, validateFlow } from 'lousho/flows';
-import { createSlackTool } from 'lousho/integrations';
-import { EncryptionUtils, validateWithSchema } from 'lousho/utils';
+import { AgentExecutor, AgentBuilder, ToolRegistry } from '@linuxdevil/lousho/executor';
+import { FlowBuilder, validateFlow } from '@linuxdevil/lousho/flows';
+import { createSlackTool } from '@linuxdevil/lousho/integrations';
+import { EncryptionUtils, validateWithSchema } from '@linuxdevil/lousho/utils';
 ```
 
 ## Removed APIs and their replacements
@@ -75,13 +75,13 @@ import { EncryptionUtils, validateWithSchema } from 'lousho/utils';
 
 ```ts no-verify
 // Before (alpha):
-import { createDelegateTool } from 'lousho';
+import { createDelegateTool } from '@linuxdevil/lousho';
 const delegate = createDelegateTool({ agent: billing, name: 'billing' });
 ```
 
 ```ts
 // After (1.0): the lead gets a `task` tool per sub-agent.
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const billing = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You answer billing questions.' });
 const lead = createAgent({
@@ -114,7 +114,7 @@ results and behavior are unchanged; `SECRET_PATTERNS` keeps its name. See
 
 ## Migrating from triggers
 
-`WebhookTriggerAdapter`, `SlackTriggerAdapter`, `CronTriggerAdapter` and their option/handle types were removed from `lousho/triggers`. `TriggerAdapter`, `TriggerRegistry`, the `WebhookAuth` helpers, `verifySlackSignature()` and `parseCronExpression()` stay. See [Triggers](./triggers.md).
+`WebhookTriggerAdapter`, `SlackTriggerAdapter`, `CronTriggerAdapter` and their option/handle types were removed from `@linuxdevil/lousho/triggers`. `TriggerAdapter`, `TriggerRegistry`, the `WebhookAuth` helpers, `verifySlackSignature()` and `parseCronExpression()` stay. See [Triggers](./triggers.md).
 
 | Removed | Replacement |
 | ------- | ----------- |
@@ -286,7 +286,7 @@ there is one. A change marked "no opt-out" closed a security or data-loss bug.
 | `agent.stream()` rethrows the run's error after the `error` and `run.done` events. See [Streaming](./streaming.md). | `stream(input, { throwOnError: false })` |
 | `send([])` throws `LOUSHO_CONFIG_INVALID`. | no opt-out |
 
-### CLI, evals and Agent Forge
+### CLI, evals and Studio
 
 | Change | Opt-out |
 | ------ | ------- |
@@ -301,7 +301,30 @@ there is one. A change marked "no opt-out" closed a security or data-loss bug.
 | The observe daemon prunes old data by default: on its first sweep and then once a day it deletes every trace whose observations all finished more than 30 days ago, with that trace's scores and prompt-use links, and sessions that are no longer `active`, ended before the window and no longer referenced. A trace with a run still open, active sessions, the Insights rollups, prompts, hub entries, the agent registry, tokens, datasets, evaluator rules and annotation queues are never pruned. See [Retention](./observability.md#retention). | `lousho observe start --retention-days 0` keeps everything (or `N` for another window) |
 | `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` (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`) |
+| 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 @linuxdevil/lousho`) |
+| The npm package no longer ships Studio (`apps/agent-forge`); `lousho studio` is now a launcher that finds an installed `@linuxdevil/studio`. | `npm i -g @linuxdevil/studio` (or `npx @linuxdevil/studio`); see below |
+
+### Studio moved to its own package
+
+Lousho Studio is published separately as `@linuxdevil/studio` and is no longer
+part of the `@linuxdevil/lousho` tarball. What to do:
+
+- Install it once: `npm i -g @linuxdevil/studio`, then run `lousho-studio`.
+  Or run `npx @linuxdevil/studio`. `lousho studio` inside a project keeps
+  working - it finds the installed Studio and opens that folder as a
+  workspace; with none installed it prints
+  `Studio is a separate install: npx @linuxdevil/studio`.
+- Studio-wide settings and secrets moved from a project's `.lousho/` to
+  `~/.lousho/studio/`. On first launch Studio offers **Import settings and
+  keys from <workspace>** once and copies them; the originals stay put.
+- `lousho studio --prod`/`--dev` now only apply inside the SDK's own
+  repository checkout; an installed Studio is always the production build.
+- A workspace's agents run on the project's own `@linuxdevil/lousho` through
+  `lousho bridge` when the installed SDK is new enough; older SDKs make the
+  workspace read-only until updated (the banner names the minimum). Studio
+  and the SDK update independently.
+
+See [Lousho Studio](./agent-forge.md) for the full picture.
 
 ## What 1.0 promises
 
diff --git a/docs/utilities.md b/docs/utilities.md
index dea7838b5..58e4772e7 100644
--- a/docs/utilities.md
+++ b/docs/utilities.md
@@ -1,13 +1,13 @@
 # Utilities
 
-Supporting helpers exported from the `lousho/utils` subpath:
+Supporting helpers exported from the `@linuxdevil/lousho/utils` subpath:
 encryption and hashing, and file storage for attachments. None of them is
 needed to build an agent; they are here for the apps around one.
 
 ## Encryption and hashing
 
 ```ts
-import { EncryptionUtils, sha256 } from 'lousho/utils';
+import { EncryptionUtils, sha256 } from '@linuxdevil/lousho/utils';
 
 const encryption = new EncryptionUtils('your-secret-key');
 const encrypted = await encryption.encrypt('sensitive data'); // fresh random salt every call
@@ -28,7 +28,7 @@ as-is. It is also what `StorageServiceApprovalStore` and
 `LocalStorageCheckpointStore` write through.
 
 ```ts
-import { StorageService } from 'lousho/utils';
+import { StorageService } from '@linuxdevil/lousho/utils';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
diff --git a/docs/vue.md b/docs/vue.md
index e064c46f7..74cc98fff 100644
--- a/docs/vue.md
+++ b/docs/vue.md
@@ -6,11 +6,11 @@ the same sources, the same state and the same actions, over the same
 field means, the two kinds of source, how approvals work and the server side;
 this page covers what differs.
 
-It lives in the `lousho/vue` subpath. `vue` (3.x) is an
+It lives in the `@linuxdevil/lousho/vue` subpath. `vue` (3.x) is an
 optional peer dependency: install it in the app that uses the composable.
 
 ```ts
-import { useLoushoAgent } from 'lousho/vue';
+import { useLoushoAgent } from '@linuxdevil/lousho/vue';
 
 // In <script setup>:
 const { messages, status, pendingApproval, send, stop, approve, reject, reset } = useLoushoAgent(
@@ -59,7 +59,7 @@ and in the template:
 
 The reducer and the stream parser are exported from this subpath too
 (`reduceAgentEvents`, `initialAgentUIState`, `parseEventStream`), the same
-ones as in `lousho/react`.
+ones as in `@linuxdevil/lousho/react`.
 
 ## Todos
 
@@ -70,7 +70,7 @@ shows the plan of an agent with the [todo tools](./tools.md#todo-tools) live, fr
 the same stream as the chat (see [React](./react.md#todos)).
 
 ```ts
-import { useLoushoAgent, useTodos } from 'lousho/vue';
+import { useLoushoAgent, useTodos } from '@linuxdevil/lousho/vue';
 
 // In <script setup>:
 const agent = useLoushoAgent({ url: '/api/agent' });
diff --git a/docs/workspace-tools.md b/docs/workspace-tools.md
index f0561d856..ca3e8fb99 100644
--- a/docs/workspace-tools.md
+++ b/docs/workspace-tools.md
@@ -9,7 +9,7 @@ sandbox such as E2B, Daytona or Cloudflare.
 For a walkthrough, see [Build a coding agent](./build-a-coding-agent.md).
 
 ```ts
-import { createAgent, NodeWorkspace, createFsTools, createShellTool } from 'lousho';
+import { createAgent, NodeWorkspace, createFsTools, createShellTool } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({ root: './project' }); // every path is confined to this directory
 const agent = createAgent({
@@ -33,7 +33,7 @@ if (paused.finishReason === 'awaiting-approval') {
 predicate that returns `false` for the commands you trust.
 
 ```ts
-import { createAgent, NodeWorkspace, createFsTools, createShellTool } from 'lousho';
+import { createAgent, NodeWorkspace, createFsTools, createShellTool } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({ root: './project' });
 const agent = createAgent({
@@ -61,8 +61,8 @@ the same, and `resumeAfterApproval(...)` is what `agent.approvals.resolve()`
 calls once a human approves:
 
 ```ts
-import { AgentExecutor, ToolRegistry } from 'lousho/executor';
-import { NodeWorkspace, createFsTools, createShellTool } from 'lousho';
+import { AgentExecutor, ToolRegistry } from '@linuxdevil/lousho/executor';
+import { NodeWorkspace, createFsTools, createShellTool } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({ root: '.' }); // every path is confined to this directory
 const registry = new ToolRegistry();
@@ -116,7 +116,7 @@ has `timedOut: true` or `aborted: true` and a `note` saying why.
 | `name`             | `'shell'` | Tool name. |
 
 ```ts
-import { createShellTool, NodeWorkspace } from 'lousho';
+import { createShellTool, NodeWorkspace } from '@linuxdevil/lousho';
 
 const shell = createShellTool(new NodeWorkspace({ root: '.' }), {
   needsApproval: (command) => !/^(ls|cat|git (status|diff|log))\b/.test(command), // read-only commands run without asking
@@ -143,8 +143,8 @@ agent created is deleted, one it edited or overwrote gets its content back.
 With `dryRun: true` it changes nothing and returns the same report.
 
 ```ts
-import { createAgent, createFsTools, MemoryWorkspace, WorkspaceCheckpoints } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createFsTools, MemoryWorkspace, WorkspaceCheckpoints } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const workspace = new MemoryWorkspace({ files: { 'notes.md': '# Notes\n' } });
 const checkpoints = new WorkspaceCheckpoints(workspace); // backups in memory; FileWorkspaceCheckpointStore keeps them on disk
@@ -281,7 +281,7 @@ A `deny` you pass **replaces** the defaults, it does not extend them: list
 'secrets']` (entry names, not paths), or pass `deny: []` to turn the check off.
 
 ```ts
-import { createFsTools, NodeWorkspace } from 'lousho';
+import { createFsTools, NodeWorkspace } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({ root: '.' });
 const tools = createFsTools(workspace, { readOnly: true, deny: ['.git', '.env', '.env.*'] });
@@ -329,7 +329,7 @@ Node's process launcher also adds the session variables every process needs
 them is a secret.
 
 ```ts
-import { NodeWorkspace } from 'lousho';
+import { NodeWorkspace } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({
   root: './project',
@@ -368,7 +368,7 @@ refused command is never offered for approval:
   returns `true` for the rest of the line (`''` when there is none):
 
   ```ts
-  import { createShellTool, NodeWorkspace } from 'lousho';
+  import { createShellTool, NodeWorkspace } from '@linuxdevil/lousho';
 
   const workspace = new NodeWorkspace({ root: '.' });
   createShellTool(workspace, {
@@ -431,7 +431,7 @@ you pass, nothing from the host. File tools can keep using `NodeWorkspace`
 on the same directory:
 
 ```ts
-import { createFsTools, createShellTool, NodeWorkspace, SandboxShell, SubprocessSandbox } from 'lousho';
+import { createFsTools, createShellTool, NodeWorkspace, SandboxShell, SubprocessSandbox } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({ root: './project' });
 const shell = new SandboxShell(new SubprocessSandbox({ image: 'node:20-alpine' }), { cwd: workspace.root });
@@ -487,7 +487,7 @@ list is only enforced when a proxy is the container's only way out.
    before; the network stays for the sandbox's next run until `close()`.
 
 ```ts
-import { createCredentialBroker, createShellTool, SandboxShell, SubprocessSandbox } from 'lousho';
+import { createCredentialBroker, createShellTool, SandboxShell, SubprocessSandbox } from '@linuxdevil/lousho';
 
 const token = 'ghp_example'; // read from your secret store; it never enters the container
 const broker = await createCredentialBroker({ rules: { 'api.github.com': { authorization: () => `Bearer ${token}` } } });
@@ -543,7 +543,7 @@ the SDK's tests exercise the wiring against a fake Docker client, not a live
 daemon.
 
 ```ts
-import { createShellTool, SandboxShell, SubprocessSandbox } from 'lousho';
+import { createShellTool, SandboxShell, SubprocessSandbox } from '@linuxdevil/lousho';
 
 const sandbox = new SubprocessSandbox({ image: 'node:20-alpine', network: 'none' });
 const shell = new SandboxShell(sandbox, {
@@ -574,7 +574,7 @@ local HTTP proxy that adds the auth headers to requests for the hosts you
 name, so the command only ever sees the proxy's address.
 
 ```ts
-import { createCredentialBroker, NodeWorkspace } from 'lousho';
+import { createCredentialBroker, NodeWorkspace } from '@linuxdevil/lousho';
 
 const token = 'ghp_example'; // read from your secret store; never passed to the command
 const broker = await createCredentialBroker({
@@ -635,7 +635,7 @@ custom tool could call it directly. Throw `WorkspaceError` with a readable
 message on failure.
 
 ```ts
-import { normalizeWorkspacePath, WorkspaceError, type FsProvider, type ShellProvider } from 'lousho';
+import { normalizeWorkspacePath, WorkspaceError, type FsProvider, type ShellProvider } from '@linuxdevil/lousho';
 
 // A stand-in for your remote sandbox SDK (E2B, Daytona, Cloudflare, ...).
 declare const remote: {
@@ -691,8 +691,8 @@ way. Its `exec` is a stub you program, and every command it receives is
 recorded. Combine it with `mockModel` for deterministic tests:
 
 ```ts
-import { createAgent, createFsTools, createShellTool, MemoryWorkspace } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createFsTools, createShellTool, MemoryWorkspace } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const workspace = new MemoryWorkspace({
   files: { 'src/math.ts': 'export const add = (a: number, b: number) => a - b;\n' },
diff --git a/docs/workspaces.md b/docs/workspaces.md
index 75e291c3b..01b0674b2 100644
--- a/docs/workspaces.md
+++ b/docs/workspaces.md
@@ -319,7 +319,7 @@ A criterion's `check` names a check in the host's check registry, and the runtim
 The result, `EffectiveHarness`, holds `sources`, the composed `instructions`, the merged fields, `provenance` (for each field path, the sources its value came from) and `hash`. The hash is the sha256 of the canonical JSON of the sources, prose and fields, with keys sorted. It does not depend on key order and is stable across runs, so a revision or a span can name the exact harness it ran with. Provenance is not part of the hash.
 
 ```ts
-import { composeHarness, type HarnessLayer } from 'lousho/workspaces';
+import { composeHarness, type HarnessLayer } from '@linuxdevil/lousho/workspaces';
 
 const base: HarnessLayer = {
   source: 'workspace base',
@@ -363,7 +363,7 @@ Agent refs and harness profile refs have different grammars. Do not read one as
 Agent names are kebab-case. A `workspace:` or `local:` agent ref takes no range. A prefix is required. `parseAgentRef` returns `{ ok: true, ref }` or `{ ok: false, error }` and never throws:
 
 ```ts
-import { parseAgentRef } from 'lousho/workspaces';
+import { parseAgentRef } from '@linuxdevil/lousho/workspaces';
 
 const parsed = parseAgentRef('global:fact-checker@^1.0.0');
 if (parsed.ok && parsed.ref.kind === 'global') console.log(parsed.ref.name, parsed.ref.range);
@@ -420,7 +420,7 @@ Shared files sit under fixed patterns: `shared/instructions/<name>.md`, `shared/
 | `sandbox.required` | OR of the two. A workspace can turn it on but never off. Absent means `false` |
 
 ```ts
-import { narrowPolicy, type WorkspacePolicy } from 'lousho/workspaces';
+import { narrowPolicy, type WorkspacePolicy } from '@linuxdevil/lousho/workspaces';
 
 const ceiling: WorkspacePolicy = {
   permissions: [],
@@ -461,8 +461,8 @@ A workspace agent is read from its files and nothing in it is run, so settings i
 `agentPolicyOptions(policy, { attachment, agent }, registry)` returns the `createAgent` `tools` and `permissions` for one attachment, or for the main agent when `attachment` is left out. It also returns a `toolRegistry` for a workflow's `toolCall` steps, which pass `flowToolGate`, plus `secrets` by tool, `network`, `sandbox` and `warnings`. It is the only code path under `src/workspaces/runtime` that builds a toolset. `attachmentAgent()` is the only place the page runtime builds a page agent, and `createMainAgent()` the only place it builds the main agent: it takes those options, passes every tool through the host's `bindTool(descriptor, scope)` with the tool's `secrets`, `network.allowHosts` and `sandbox.required`, and the host enforces them. Under `createWorkspaceRuntime` a host without `bindTool` can run only tools whose scope grants no secrets, no hosts and no sandbox; any other tool fails the run with `LOUSHO_WORKSPACE_HOST_INVALID`, so nothing the policy narrows ever runs unenforced (see [The workspace runtime and its host](#the-workspace-runtime-and-its-host)).
 
 ```ts
-import { narrowPolicy, pagePolicy, type HostToolRegistry } from 'lousho/workspaces';
-import { defineTool } from 'lousho';
+import { narrowPolicy, pagePolicy, type HostToolRegistry } from '@linuxdevil/lousho/workspaces';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const registry: HostToolRegistry = {
@@ -493,7 +493,7 @@ console.log(Object.keys(page.attachments.video.tools), page.warnings);
 Every engine implements one interface, so the main agent, the wire contract and the page UI do not care which type a page runs under. These are plain JSON types.
 
 ```ts
-import type { PageEngine, PageInput, PageResult, PageRunContext } from 'lousho/workspaces';
+import type { PageEngine, PageInput, PageResult, PageRunContext } from '@linuxdevil/lousho/workspaces';
 
 async function runEngine(engine: PageEngine, input: PageInput, ctx: PageRunContext): Promise<PageResult> {
   ctx.emit({ type: 'progress', message: `running ${input.pageId} as ${engine.type}` });
@@ -616,7 +616,7 @@ Text is plain: `label`, `title`, `placeholder` and option labels are 1 to 500 ch
 `validateWorkspace` reports each of these as PRD012 and resolves a schema path against the page folder first.
 
 ```ts
-import { pageUiSchema, validateUiBindings } from 'lousho/workspaces';
+import { pageUiSchema, validateUiBindings } from '@linuxdevil/lousho/workspaces';
 
 const ui = pageUiSchema.parse({
   schema: 'lousho.ui/1',
@@ -656,7 +656,7 @@ The operations are: `create_workspace`, `set_workspace_field`, `create_page`, `r
 `set_profile` writes a workspace harness profile (`harness-profiles/<path>/harness.json` and its prose) from a `workspace:<path>` ref. `delete_profile` removes the profile's folder. `set_resource` and `delete_resource` write and remove a text resource (`.md` or `.txt`) of a page or of the base harness; list it in the harness's `context.resources` with `set_harness_field`. `set_main_model` sets the main agent's model. Check scripts, tools, workspace workflows, brand files and the policy have no operation: a criterion's `check` may name a host-registry check by name.
 
 ```ts
-import { applyOps, validateWorkspace } from 'lousho/workspaces';
+import { applyOps, validateWorkspace } from '@linuxdevil/lousho/workspaces';
 
 const result = applyOps(
   {},
@@ -678,7 +678,7 @@ This batch is refused: the page names the alias `writer` that `agents.json` does
 `validateWorkspace(tree, options?)` checks a whole tree across files. It never throws for invalid input and never touches the file system. It returns problems `{ severity, code, file, path, message }` in a stable order. Only `error` makes a workspace invalid; `warning` and `info` do not. `options.resolveGlobal(ref)` answers `global:` refs with that folder's files, and `options.mode: "strict"` adds only an `info` note in v1.
 
 ```ts
-import { validateWorkspace } from 'lousho/workspaces';
+import { validateWorkspace } from '@linuxdevil/lousho/workspaces';
 
 const problems = validateWorkspace({
   'workspace.json': JSON.stringify({
diff --git a/examples/README.md b/examples/README.md
index b863b9ca6..363010f61 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -6,7 +6,7 @@ is runnable directly (see its own README for exact instructions); most use
 to try.
 
 The examples import the SDK by its package name and public subpaths
-(`lousho`, `lousho/testing`, ...), exactly as
+(`lousho`, `@linuxdevil/lousho/testing`, ...), exactly as
 your app would, so you can copy a file out as it is. Inside this repo the
 `paths` in `tsconfig.json` (and a resolver in `vitest.config.ts`) point those
 imports at `src/`, so nothing needs building first.
diff --git a/examples/agent-dir/index.test.ts b/examples/agent-dir/index.test.ts
index 3a7fbab7e..dad7ed3f7 100644
--- a/examples/agent-dir/index.test.ts
+++ b/examples/agent-dir/index.test.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
-import { loadAgentDir } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { loadAgentDir } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 describe('examples/agent-dir', () => {
   it('loads from disk and its tool and skill are callable offline', async () => {
diff --git a/examples/agent-dir/index.ts b/examples/agent-dir/index.ts
index ec76e0fa2..f9f463648 100644
--- a/examples/agent-dir/index.ts
+++ b/examples/agent-dir/index.ts
@@ -9,8 +9,8 @@
  * you trust. Run with: npx tsx examples/agent-dir/index.ts
  */
 import path from 'node:path';
-import { loadAgentDir } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { loadAgentDir } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const provider = mockModel([
   {
diff --git a/examples/agent-dir/tools/word_count.ts b/examples/agent-dir/tools/word_count.ts
index 0e248a996..6d55f11c1 100644
--- a/examples/agent-dir/tools/word_count.ts
+++ b/examples/agent-dir/tools/word_count.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 
 export default defineTool({
   name: 'word_count',
diff --git a/examples/coding-agent-workflows/index.test.ts b/examples/coding-agent-workflows/index.test.ts
index 9a3216637..13fcb50fc 100644
--- a/examples/coding-agent-workflows/index.test.ts
+++ b/examples/coding-agent-workflows/index.test.ts
@@ -1,8 +1,8 @@
 import { z } from 'zod';
 import { describe, expect, it } from 'vitest';
-import { mockModel } from 'lousho/testing';
-import { defineTool } from 'lousho';
-import { ToolRegistry } from 'lousho/executor';
+import { mockModel } from '@linuxdevil/lousho/testing';
+import { defineTool } from '@linuxdevil/lousho';
+import { ToolRegistry } from '@linuxdevil/lousho/executor';
 import { codingTools, memoryWorkspace, runCodingAgent, triage } from './index';
 
 const decision = (route: string, confidence: number) =>
diff --git a/examples/coding-agent-workflows/index.ts b/examples/coding-agent-workflows/index.ts
index f34a56469..22e16a08e 100644
--- a/examples/coding-agent-workflows/index.ts
+++ b/examples/coding-agent-workflows/index.ts
@@ -29,10 +29,10 @@
 import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
-import { createAgent, defineTool, resolveProvider, type LLMProvider, type SimpleAgent } from 'lousho';
-import { ToolRegistry } from 'lousho/executor';
-import { FlowBuilder, FlowExecutor, type EditorStep, type FlowExecutionResult } from 'lousho/flows';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool, resolveProvider, type LLMProvider, type SimpleAgent } from '@linuxdevil/lousho';
+import { ToolRegistry } from '@linuxdevil/lousho/executor';
+import { FlowBuilder, FlowExecutor, type EditorStep, type FlowExecutionResult } from '@linuxdevil/lousho/flows';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 export const LIVE_MODEL = 'openrouter/openai/gpt-4o-mini';
 
diff --git a/examples/coding-harness/index.test.ts b/examples/coding-harness/index.test.ts
index 84bf8d846..b9e4c4d74 100644
--- a/examples/coding-harness/index.test.ts
+++ b/examples/coding-harness/index.test.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
-import { MemoryWorkspace } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { MemoryWorkspace } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { createCodingHarness, fakeExec, FIXTURE, instructionsFor, scriptedExplorer, scriptedLead } from './index';
 
 function memoryWorkspace(): MemoryWorkspace {
diff --git a/examples/coding-harness/index.ts b/examples/coding-harness/index.ts
index dc983d02a..0f84702af 100644
--- a/examples/coding-harness/index.ts
+++ b/examples/coding-harness/index.ts
@@ -32,8 +32,8 @@ import {
   type AgentHook,
   type LLMProvider,
   type Message,
-} from 'lousho';
-import { mockModel } from 'lousho/testing';
+} from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 /** The project the harness works on: `add()` subtracts, so its test fails. */
 export const FIXTURE: Record<string, string> = {
diff --git a/examples/coding-harness/kit-pi.test.ts b/examples/coding-harness/kit-pi.test.ts
index 42673feca..148e2cd45 100644
--- a/examples/coding-harness/kit-pi.test.ts
+++ b/examples/coding-harness/kit-pi.test.ts
@@ -12,7 +12,7 @@
  * delegating to a real Pi coding agent over OpenRouter.
  *
  * Like kit.test.ts this needs `npm run build` to have run (the kit's files
- * import `lousho` by name and the loader goes through dist).
+ * import `@linuxdevil/lousho` by name and the loader goes through dist).
  */
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { execFileSync } from 'node:child_process';
@@ -22,8 +22,8 @@ import * as path from 'node:path';
 import { PassThrough, Writable } from 'node:stream';
 import { fauxAssistantMessage, fauxProvider, fauxToolCall, type FauxResponseStep } from '@earendil-works/pi-ai';
 import { ModelRuntime } from '@earendil-works/pi-coding-agent';
-import { loadAgentDir } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { loadAgentDir } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { runAdd } from '../../src/cli/add';
 import { FIXTURE } from './index';
 
@@ -140,7 +140,7 @@ describe('lousho add coding-pi', () => {
 
 describe('the installed kit, loaded', () => {
   it('puts the pi coder in the subagents map and keeps the explorer a delegate tool', async () => {
-    const { resolveAgentDir } = await import('lousho');
+    const { resolveAgentDir } = await import('@linuxdevil/lousho');
     const { config, manifest } = await resolveAgentDir(root, { provider: mockModel(['x']) });
 
     expect(manifest.subagents).toEqual(['coder', 'explorer']);
diff --git a/examples/coding-harness/kit.test.ts b/examples/coding-harness/kit.test.ts
index e3d33dc3c..35c7bdbf1 100644
--- a/examples/coding-harness/kit.test.ts
+++ b/examples/coding-harness/kit.test.ts
@@ -23,8 +23,8 @@ import * as path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { PassThrough, Writable } from 'node:stream';
 import { spawn } from 'node:child_process';
-import { loadAgentDir } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { loadAgentDir } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { NodeServerAdapter } from '../../src/deploy/adapters/node-server';
 import { withBuildLock } from '../../src/deploy/buildLock.testkit';
 import { runAdd } from '../../src/cli/add';
@@ -57,7 +57,7 @@ async function add(args: string[]) {
 
 async function kitModule() {
   return (await import(pathToFileURL(path.join(root, 'tools', 'fs.ts')).href)) as {
-    checkpoints: import('lousho').WorkspaceCheckpoints;
+    checkpoints: import('@linuxdevil/lousho').WorkspaceCheckpoints;
   };
 }
 
@@ -67,7 +67,7 @@ async function kitModule() {
  * approver by passing it in code.
  */
 async function kitApprove() {
-  return ((await import(pathToFileURL(path.join(root, 'approve.ts')).href)) as { default: import('lousho').ApproveToolCall }).default;
+  return ((await import(pathToFileURL(path.join(root, 'approve.ts')).href)) as { default: import('@linuxdevil/lousho').ApproveToolCall }).default;
 }
 
 /** A provider that plays the lead's script and the explorer's, in call order. */
@@ -292,7 +292,7 @@ describe('lousho build --target=node-server', () => {
     fs.rmSync(path.join(root, 'agent.json'));
     fs.writeFileSync(
       path.join(root, 'agent.ts'),
-      `import { createMockProvider } from 'lousho';
+      `import { createMockProvider } from '@linuxdevil/lousho';
 export default {
   provider: createMockProvider({ name: 'mock', responses: ['Fixed add() in math.js; node --test now passes.'] }),
   maxSteps: 20,
diff --git a/examples/connectors/index.test.ts b/examples/connectors/index.test.ts
index c0b4fadff..60dfc704c 100644
--- a/examples/connectors/index.test.ts
+++ b/examples/connectors/index.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
-import { createAgent } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { connectorSpecs } from './index';
 
 // The test spawns the real mock-connectors stdio server - the honest check
diff --git a/examples/connectors/index.ts b/examples/connectors/index.ts
index a5a3155e7..e8ea935fc 100644
--- a/examples/connectors/index.ts
+++ b/examples/connectors/index.ts
@@ -23,9 +23,9 @@
  */
 import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { createAgent, resolveProvider, type LLMProvider } from 'lousho';
-import { mockModel } from 'lousho/testing';
-import { type McpServerSpec } from 'lousho';
+import { createAgent, resolveProvider, type LLMProvider } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
+import { type McpServerSpec } from '@linuxdevil/lousho';
 
 export const LIVE_MODEL = 'openrouter/openai/gpt-4o-mini';
 
diff --git a/examples/connectors/mock-connectors-server.ts b/examples/connectors/mock-connectors-server.ts
index b05d2e092..01bda7e00 100644
--- a/examples/connectors/mock-connectors-server.ts
+++ b/examples/connectors/mock-connectors-server.ts
@@ -12,9 +12,9 @@
  * required `agent` option; the connector tools ride in `tools`.
  */
 import { z } from 'zod';
-import { createAgent, defineTool } from 'lousho';
-import { serveMcp } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { serveMcp } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const DOCS = new Map<string, string>([
   ['doc-1', '# Launch plan\n\nShip the connector example on Friday.'],
diff --git a/examples/data-analyst/index.test.ts b/examples/data-analyst/index.test.ts
index d95bf38dc..7e8f1de5c 100644
--- a/examples/data-analyst/index.test.ts
+++ b/examples/data-analyst/index.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { mockModel, testToolContext } from 'lousho/testing';
+import { mockModel, testToolContext } from '@linuxdevil/lousho/testing';
 import {
   createAnalystTools,
   createDataAnalyst,
diff --git a/examples/data-analyst/index.ts b/examples/data-analyst/index.ts
index 762227f67..350f87cba 100644
--- a/examples/data-analyst/index.ts
+++ b/examples/data-analyst/index.ts
@@ -40,8 +40,8 @@
 import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
-import { allow, createAgent, defineTool, type AgentHook, type LLMProvider } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { allow, createAgent, defineTool, type AgentHook, type LLMProvider } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 export const LIVE_MODEL = 'openrouter/openai/gpt-4o-mini';
 
diff --git a/examples/deep-research/index.test.ts b/examples/deep-research/index.test.ts
index edc03d795..196e6edca 100644
--- a/examples/deep-research/index.test.ts
+++ b/examples/deep-research/index.test.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
-import { toolResultText } from 'lousho';
-import { testToolContext } from 'lousho/testing';
+import { toolResultText } from '@linuxdevil/lousho';
+import { testToolContext } from '@linuxdevil/lousho/testing';
 import {
   CORPUS,
   createDeepResearch,
diff --git a/examples/deep-research/index.ts b/examples/deep-research/index.ts
index 9d0904d4f..2b35f0a21 100644
--- a/examples/deep-research/index.ts
+++ b/examples/deep-research/index.ts
@@ -24,8 +24,8 @@
 import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
-import { createAgent, defineTool, textOf, toolResultText, type LLMProvider } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool, textOf, toolResultText, type LLMProvider } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 export const LIVE_MODEL = 'openrouter/openai/gpt-4o-mini';
 export const DEFAULT_QUESTION =
diff --git a/examples/doc-qa/index.ts b/examples/doc-qa/index.ts
index 6fb4340ca..81bb09543 100644
--- a/examples/doc-qa/index.ts
+++ b/examples/doc-qa/index.ts
@@ -8,9 +8,9 @@
  *
  * Run with: tsx examples/doc-qa/index.ts
  */
-import { createAgent } from 'lousho';
-import { createMockProvider } from 'lousho';
-import { resolveProvider } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
+import { createMockProvider } from '@linuxdevil/lousho';
+import { resolveProvider } from '@linuxdevil/lousho';
 
 const DOCUMENT = `
 Lousho Refund Policy: Refunds are available within 30 days of purchase.
diff --git a/examples/evaluator-loop/index.test.ts b/examples/evaluator-loop/index.test.ts
index 10f2c1d44..a892db95e 100644
--- a/examples/evaluator-loop/index.test.ts
+++ b/examples/evaluator-loop/index.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
-import { createAgent, textOf } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, textOf } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { RUBRIC, runEvaluatorLoop } from './index';
 
 const PROMPT = 'Write a 3-sentence product description for HydraTrack.';
diff --git a/examples/evaluator-loop/index.ts b/examples/evaluator-loop/index.ts
index 186dbfeb9..a0182a5fb 100644
--- a/examples/evaluator-loop/index.ts
+++ b/examples/evaluator-loop/index.ts
@@ -28,8 +28,8 @@ import {
   resolveProvider,
   type LLMJudgeConfig,
   type SimpleAgent,
-} from 'lousho';
-import { mockModel } from 'lousho/testing';
+} from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 export const LIVE_MODEL = 'openrouter/openai/gpt-4o-mini';
 /** Bare model id, as `judge.provider.generate({ model })` expects it. */
diff --git a/examples/harnesses.live.test.ts b/examples/harnesses.live.test.ts
index bcf485a28..db95df5be 100644
--- a/examples/harnesses.live.test.ts
+++ b/examples/harnesses.live.test.ts
@@ -19,7 +19,7 @@
  */
 import { describe, expect, it } from 'vitest';
 import { z } from 'zod';
-import { createAgent, defineTool, resolveProvider } from 'lousho';
+import { createAgent, defineTool, resolveProvider } from '@linuxdevil/lousho';
 import { createDeepResearch } from './deep-research';
 import { createSupportDesk } from './support-desk';
 import { runEvaluatorLoop } from './evaluator-loop';
diff --git a/examples/heal-benchmark/agents.ts b/examples/heal-benchmark/agents.ts
index c337eaec9..cf15ff850 100644
--- a/examples/heal-benchmark/agents.ts
+++ b/examples/heal-benchmark/agents.ts
@@ -1,4 +1,4 @@
-import { defineTool, type DefinedTool } from 'lousho';
+import { defineTool, type DefinedTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 import { codingAgent } from './codingAgent';
 
diff --git a/examples/heal-benchmark/armSummary.test.ts b/examples/heal-benchmark/armSummary.test.ts
index e61f76fb9..dce7e2d07 100644
--- a/examples/heal-benchmark/armSummary.test.ts
+++ b/examples/heal-benchmark/armSummary.test.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import { bars, renderReport, trueFixAttempts } from './armSummary';
 import type { Arm, ArmRow } from './gates';
-import { emptyLedger } from 'lousho/improve';
+import { emptyLedger } from '@linuxdevil/lousho/improve';
 
 const row = (arm: Arm, attempt: number, accepted: boolean, passK: ArmRow['passK'] = {}): ArmRow => ({ attempt, arm, accepted, reason: 'r', model: 'm', date: 'd', passK });
 const many = (arm: Arm, accepted: readonly boolean[]) => accepted.map((value, attempt) => row(arm, attempt, value));
diff --git a/examples/heal-benchmark/armSummary.ts b/examples/heal-benchmark/armSummary.ts
index daa25fd7f..7450c2039 100644
--- a/examples/heal-benchmark/armSummary.ts
+++ b/examples/heal-benchmark/armSummary.ts
@@ -1,5 +1,5 @@
 import type { Arm, ArmRow } from './gates';
-import type { ImproveLedger } from 'lousho/improve';
+import type { ImproveLedger } from '@linuxdevil/lousho/improve';
 import type { ReplayLine } from './replayRows';
 
 export interface Confirmation {
diff --git a/examples/heal-benchmark/codingAgent.test.ts b/examples/heal-benchmark/codingAgent.test.ts
index 37b014f8d..e2f026d07 100644
--- a/examples/heal-benchmark/codingAgent.test.ts
+++ b/examples/heal-benchmark/codingAgent.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { mockModel } from 'lousho/testing';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { codingAgent, FIXES, runProjectTests } from './codingAgent';
 import { runBenchmark } from './run';
 
diff --git a/examples/heal-benchmark/codingAgent.ts b/examples/heal-benchmark/codingAgent.ts
index 8741dfde2..317c8a80b 100644
--- a/examples/heal-benchmark/codingAgent.ts
+++ b/examples/heal-benchmark/codingAgent.ts
@@ -2,7 +2,7 @@ import { spawnSync } from 'node:child_process';
 import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
-import { createFsTools, defineTool, MemoryWorkspace } from 'lousho';
+import { createFsTools, defineTool, MemoryWorkspace } from '@linuxdevil/lousho';
 import { z } from 'zod';
 import type { BenchmarkAgent } from './agents';
 
diff --git a/examples/heal-benchmark/experiment.ts b/examples/heal-benchmark/experiment.ts
index f2d040213..ad47950c4 100644
--- a/examples/heal-benchmark/experiment.ts
+++ b/examples/heal-benchmark/experiment.ts
@@ -1,6 +1,6 @@
 import { appendFileSync, readFileSync, writeFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
-import { cachedProbe, emptyLedger, improveAgent, type Harness, type ImproveLedger, type ImproveResult } from 'lousho/improve';
+import { cachedProbe, emptyLedger, improveAgent, type Harness, type ImproveLedger, type ImproveResult } from '@linuxdevil/lousho/improve';
 import { renderReport, trueFixAttempts, type Confirmation } from './armSummary';
 import { admitHoldout, armRow, armsFromResult, loggedProbe, noOpHarness, plantedHarness, scriptedEditor, type Arm, type ArmContext, type ArmRow, type LoggedRun } from './gates';
 import { benchmarkProbe, buildAgent } from './probe';
diff --git a/examples/heal-benchmark/gates.test.ts b/examples/heal-benchmark/gates.test.ts
index 8fa52b7b7..6c7ad084c 100644
--- a/examples/heal-benchmark/gates.test.ts
+++ b/examples/heal-benchmark/gates.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { improveAgent, type Harness, type ImproveOptions, type ImproveResult, type ProbeRun, type ProbeSummary } from 'lousho/improve';
+import { improveAgent, type Harness, type ImproveOptions, type ImproveResult, type ProbeRun, type ProbeSummary } from '@linuxdevil/lousho/improve';
 import { codingAgent, FIXES } from './codingAgent';
 import { admitHoldout, armsFromResult, gateV1, harnessKey, loggedProbe, noOpHarness, passK, PLANTED_REGRESSION, plantedHarness, scriptedEditor, type LoggedRun } from './gates';
 
diff --git a/examples/heal-benchmark/gates.ts b/examples/heal-benchmark/gates.ts
index 70af5fb89..00d12750c 100644
--- a/examples/heal-benchmark/gates.ts
+++ b/examples/heal-benchmark/gates.ts
@@ -1,5 +1,5 @@
-import type { CaseCount, Harness, ImproveOptions, ImproveResult, ProbeRun, ProbeSummary } from 'lousho/improve';
-import { mockModel, type MockTurn } from 'lousho/testing';
+import type { CaseCount, Harness, ImproveOptions, ImproveResult, ProbeRun, ProbeSummary } from '@linuxdevil/lousho/improve';
+import { mockModel, type MockTurn } from '@linuxdevil/lousho/testing';
 
 export const PLANTED_REGRESSION = 'Never edit src/pages.js: it is generated, so leave it exactly as it is.';
 export const noOpHarness = (base: Harness): Harness => ({ ...base, instructions: `${base.instructions}\n` });
diff --git a/examples/heal-benchmark/improve-cli/agent.ts b/examples/heal-benchmark/improve-cli/agent.ts
index 687e37bb7..ee1ebe3f3 100644
--- a/examples/heal-benchmark/improve-cli/agent.ts
+++ b/examples/heal-benchmark/improve-cli/agent.ts
@@ -1,4 +1,4 @@
-import type { CreateAgentConfig } from 'lousho';
+import type { CreateAgentConfig } from '@linuxdevil/lousho';
 import { DEFAULT_MODEL, refuseUnsharedModels } from './modelRule.ts';
 import { codingInstructions, freshProjectHook, projectTools } from './projectRuns.ts';
 
diff --git a/examples/heal-benchmark/improve-cli/check.ts b/examples/heal-benchmark/improve-cli/check.ts
index fb126fe53..e3e327207 100644
--- a/examples/heal-benchmark/improve-cli/check.ts
+++ b/examples/heal-benchmark/improve-cli/check.ts
@@ -1,4 +1,4 @@
-import type { CaseCheck } from 'lousho/improve';
+import type { CaseCheck } from '@linuxdevil/lousho/improve';
 import { latestProjectRun } from './projectRuns.ts';
 
 const check: CaseCheck = (input) => {
diff --git a/examples/heal-benchmark/improve-cli/improveCli.test.ts b/examples/heal-benchmark/improve-cli/improveCli.test.ts
index cccfa88db..bb2bc4ebb 100644
--- a/examples/heal-benchmark/improve-cli/improveCli.test.ts
+++ b/examples/heal-benchmark/improve-cli/improveCli.test.ts
@@ -6,9 +6,9 @@ import * as path from 'node:path';
 import { Writable } from 'node:stream';
 import { fileURLToPath } from 'node:url';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { createAgent } from 'lousho';
-import { casesFromFailures, createShadowHook } from 'lousho/improve';
-import { mockModel, type MockRequest, type MockStaticTurn } from 'lousho/testing';
+import { createAgent } from '@linuxdevil/lousho';
+import { casesFromFailures, createShadowHook } from '@linuxdevil/lousho/improve';
+import { mockModel, type MockRequest, type MockStaticTurn } from '@linuxdevil/lousho/testing';
 import { runImprove } from '../../../src/cli/improve';
 import { startObserveDaemon } from '../../../src/observe/daemon';
 import { openDb } from '../../../src/observe/store';
diff --git a/examples/heal-benchmark/improve-cli/projectRuns.ts b/examples/heal-benchmark/improve-cli/projectRuns.ts
index f9732e626..16c6e0413 100644
--- a/examples/heal-benchmark/improve-cli/projectRuns.ts
+++ b/examples/heal-benchmark/improve-cli/projectRuns.ts
@@ -1,4 +1,4 @@
-import { defineTool, type AgentHook, type DefinedTool, type Message } from 'lousho';
+import { defineTool, type AgentHook, type DefinedTool, type Message } from '@linuxdevil/lousho';
 import { codingAgent } from '../codingAgent.ts';
 
 type CodingProject = ReturnType<typeof codingAgent>;
diff --git a/examples/heal-benchmark/improve-cli/record.ts b/examples/heal-benchmark/improve-cli/record.ts
index 104c43323..8ad19b4ea 100644
--- a/examples/heal-benchmark/improve-cli/record.ts
+++ b/examples/heal-benchmark/improve-cli/record.ts
@@ -4,8 +4,8 @@ import { createServer } from 'node:net';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
-import { createAgent, type AgentHook, type LLMProvider } from 'lousho';
-import { observeExporter, type ObserveReporter, type TraceExporter } from 'lousho/traces';
+import { createAgent, type AgentHook, type LLMProvider } from '@linuxdevil/lousho';
+import { observeExporter, type ObserveReporter, type TraceExporter } from '@linuxdevil/lousho/traces';
 import agent from './agent.ts';
 import check from './check.ts';
 import { DEFAULT_MODEL, refuseUnsharedModel } from './modelRule.ts';
diff --git a/examples/heal-benchmark/improve.ts b/examples/heal-benchmark/improve.ts
index 329a0b8bd..b68eb473e 100644
--- a/examples/heal-benchmark/improve.ts
+++ b/examples/heal-benchmark/improve.ts
@@ -1,7 +1,7 @@
 import { appendFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
-import { cachedProbe, emptyLedger, improveAgent, type Harness, type ImproveOptions } from 'lousho/improve';
-import { mockModel } from 'lousho/testing';
+import { cachedProbe, emptyLedger, improveAgent, type Harness, type ImproveOptions } from '@linuxdevil/lousho/improve';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { benchmarkProbe, buildAgent, checkFailureNames, nameFailures, parseFailureNames, throttleHook, type FailureNames } from './probe';
 import { confirmHarness, replayRow, type RecordedRow, type ReplayLine } from './replayRows';
 
diff --git a/examples/heal-benchmark/index.test.ts b/examples/heal-benchmark/index.test.ts
index 5a6d627c2..38d184d89 100644
--- a/examples/heal-benchmark/index.test.ts
+++ b/examples/heal-benchmark/index.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { mockModel } from 'lousho/testing';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { AGENTS } from './agents';
 import { harnessVersion, runBenchmark, type BenchmarkRun } from './run';
 import { formatSummary, summarize } from './score';
diff --git a/examples/heal-benchmark/index.ts b/examples/heal-benchmark/index.ts
index d173a9360..5b6dd6dc1 100644
--- a/examples/heal-benchmark/index.ts
+++ b/examples/heal-benchmark/index.ts
@@ -1,7 +1,7 @@
 import { appendFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
-import { createProgressGuard, type AgentHook } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createProgressGuard, type AgentHook } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { AGENTS } from './agents';
 import { runBenchmark } from './run';
 import { formatSummary, summarize } from './score';
diff --git a/examples/heal-benchmark/loop.test.ts b/examples/heal-benchmark/loop.test.ts
index 93ff9f3f2..0a4a7e41f 100644
--- a/examples/heal-benchmark/loop.test.ts
+++ b/examples/heal-benchmark/loop.test.ts
@@ -4,7 +4,7 @@ import path from 'node:path';
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 import { startObserveDaemon } from '../../src/observe/daemon';
 import { ingestBatch, openDb } from '../../src/observe/store';
-import type { SqlDatabase } from 'lousho/improve';
+import type { SqlDatabase } from '@linuxdevil/lousho/improve';
 import { AGENT_MODEL, assertSynthetic, EDITOR_MODEL, LOOP_PREFIX, openKit, syntheticOnly, type LoopEnv } from './loopRuntime';
 import { runAttempt, SCENARIOS, type LoopRow, type ScenarioId } from './loopScenarios';
 
diff --git a/examples/heal-benchmark/loop.ts b/examples/heal-benchmark/loop.ts
index d7af24e51..5d3542692 100644
--- a/examples/heal-benchmark/loop.ts
+++ b/examples/heal-benchmark/loop.ts
@@ -3,7 +3,7 @@ import { appendFileSync, existsSync, readFileSync, realpathSync } from 'node:fs'
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
-import type { SqlDatabase } from 'lousho/improve';
+import type { SqlDatabase } from '@linuxdevil/lousho/improve';
 import { renderLoopReport, type LoopRowLike } from './armSummary';
 import { spawnCollector, type Collector } from './improve-cli/record';
 import { AGENT_MODEL, assertSynthetic, EDITOR_MODEL, LOOP_PREFIX, syntheticOnly, type LoopEnv } from './loopRuntime';
diff --git a/examples/heal-benchmark/loopRuntime.ts b/examples/heal-benchmark/loopRuntime.ts
index 7f42eb3d4..86ddf0862 100644
--- a/examples/heal-benchmark/loopRuntime.ts
+++ b/examples/heal-benchmark/loopRuntime.ts
@@ -1,10 +1,10 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
-import { createAgent, defineSkill, memoryStore, resolveProvider, type AgentHook, type HarnessArm, type LLMProvider, type Skill } from 'lousho';
-import { loadImproveSettings, readAgentHarness, readCanary, renderTranscript, routesToCandidate, watchAgent, type CaseCheck, type Harness, type HealOptions, type ImproveOptions, type SqlDatabase, type WatchOptions, type WatchTick } from 'lousho/improve';
-import { mockModel, type MockRequest, type MockStaticTurn } from 'lousho/testing';
-import { observeExporter, type ObserveReporter, type TraceExporter } from 'lousho/traces';
+import { createAgent, defineSkill, memoryStore, resolveProvider, type AgentHook, type HarnessArm, type LLMProvider, type Skill } from '@linuxdevil/lousho';
+import { loadImproveSettings, readAgentHarness, readCanary, renderTranscript, routesToCandidate, watchAgent, type CaseCheck, type Harness, type HealOptions, type ImproveOptions, type SqlDatabase, type WatchOptions, type WatchTick } from '@linuxdevil/lousho/improve';
+import { mockModel, type MockRequest, type MockStaticTurn } from '@linuxdevil/lousho/testing';
+import { observeExporter, type ObserveReporter, type TraceExporter } from '@linuxdevil/lousho/traces';
 import { codingAgent, FIXES } from './codingAgent';
 import { rootTracking } from './improve-cli/record';
 import { harnessKey, passK } from './gates';
diff --git a/examples/heal-benchmark/loopScenarios.ts b/examples/heal-benchmark/loopScenarios.ts
index 878ced9ae..d8798d3fd 100644
--- a/examples/heal-benchmark/loopScenarios.ts
+++ b/examples/heal-benchmark/loopScenarios.ts
@@ -24,7 +24,7 @@ import {
   type Harness,
   type ImproveResult,
   type WatchTick,
-} from 'lousho/improve';
+} from '@linuxdevil/lousho/improve';
 import { codingAgent } from './codingAgent';
 import { noOpHarness, PLANTED_REGRESSION, plantedHarness } from './gates';
 import { FIX_RULE, harnessBytesHash, INJECTED, INJECTION, MIX, NEW_CLASS_RULE, openKit, passedTrace, passKOf, traffic, watchTicks, type Kit, type KitSetup, type LoopEnv } from './loopRuntime';
diff --git a/examples/heal-benchmark/probe.ts b/examples/heal-benchmark/probe.ts
index 57d94f1b8..8d48311c6 100644
--- a/examples/heal-benchmark/probe.ts
+++ b/examples/heal-benchmark/probe.ts
@@ -1,6 +1,6 @@
-import { createAgent, defineSkill, type AgentHook } from 'lousho';
-import { renderTranscript, type Harness, type ProbeRun } from 'lousho/improve';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineSkill, type AgentHook } from '@linuxdevil/lousho';
+import { renderTranscript, type Harness, type ProbeRun } from '@linuxdevil/lousho/improve';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { AGENTS, type BenchmarkAgent } from './agents';
 
 export type FailureNames = 'real' | 'none' | 'shuffled';
diff --git a/examples/heal-benchmark/replay.test.ts b/examples/heal-benchmark/replay.test.ts
index e04311484..5b8b14720 100644
--- a/examples/heal-benchmark/replay.test.ts
+++ b/examples/heal-benchmark/replay.test.ts
@@ -2,8 +2,8 @@ import { mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'n
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { cachedProbe, emptyLedger, improveAgent, probeCacheKey, type Harness, type ImproveOptions, type ProbeRun } from 'lousho/improve';
-import { mockModel, type MockTurn } from 'lousho/testing';
+import { cachedProbe, emptyLedger, improveAgent, probeCacheKey, type Harness, type ImproveOptions, type ProbeRun } from '@linuxdevil/lousho/improve';
+import { mockModel, type MockTurn } from '@linuxdevil/lousho/testing';
 import { assertRowModel, replayRow, type RecordedRow } from './replayRows';
 
 const BASE: Harness = { instructions: 'Fix the bug.', skills: {} };
diff --git a/examples/heal-benchmark/replay.ts b/examples/heal-benchmark/replay.ts
index 6620af157..f574a8cc7 100644
--- a/examples/heal-benchmark/replay.ts
+++ b/examples/heal-benchmark/replay.ts
@@ -1,7 +1,7 @@
 import { appendFileSync, readFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
 import { benchmarkProbe } from './probe';
-import { cachedProbe, emptyLedger, type ImproveLedger } from 'lousho/improve';
+import { cachedProbe, emptyLedger, type ImproveLedger } from '@linuxdevil/lousho/improve';
 import { assertRowModel, LABELS, replayRow, type RecordedRow, type ReplayLine } from './replayRows';
 
 const { values } = parseArgs({
diff --git a/examples/heal-benchmark/replayRows.ts b/examples/heal-benchmark/replayRows.ts
index 8b2a2203d..dc5ab7c93 100644
--- a/examples/heal-benchmark/replayRows.ts
+++ b/examples/heal-benchmark/replayRows.ts
@@ -1,4 +1,4 @@
-import type { Harness, ImproveOptions } from 'lousho/improve';
+import type { Harness, ImproveOptions } from '@linuxdevil/lousho/improve';
 
 export interface RecordedRow {
   attempt: number;
diff --git a/examples/heal-benchmark/run.ts b/examples/heal-benchmark/run.ts
index 543b80386..90677dd2c 100644
--- a/examples/heal-benchmark/run.ts
+++ b/examples/heal-benchmark/run.ts
@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { createAgent, type AgentHook, type LLMProvider } from 'lousho';
+import { createAgent, type AgentHook, type LLMProvider } from '@linuxdevil/lousho';
 import type { BenchmarkAgent, BenchmarkTask } from './agents';
 
 export type RunOutcome = 'passed' | 'failed' | 'unknown';
diff --git a/examples/heal-benchmark/simulate.ts b/examples/heal-benchmark/simulate.ts
index 9a1535689..bc3a311ed 100644
--- a/examples/heal-benchmark/simulate.ts
+++ b/examples/heal-benchmark/simulate.ts
@@ -1,5 +1,5 @@
 import { parseArgs } from 'node:util';
-import { improveAgent, type Harness, type ImproveOptions } from 'lousho/improve';
+import { improveAgent, type Harness, type ImproveOptions } from '@linuxdevil/lousho/improve';
 import { armsFromResult, harnessKey, noOpHarness, plantedHarness, scriptedEditor, type Arm } from './gates';
 
 const { values } = parseArgs({
diff --git a/examples/hostinger-deploy/agent/tools/host.test.ts b/examples/hostinger-deploy/agent/tools/host.test.ts
index 843cbed6a..b427bb06b 100644
--- a/examples/hostinger-deploy/agent/tools/host.test.ts
+++ b/examples/hostinger-deploy/agent/tools/host.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { hostStatus, listNotes, readNote, writeNote } from './host';
-import { testToolContext } from 'lousho/testing';
+import { testToolContext } from '@linuxdevil/lousho/testing';
 
 const ctx = testToolContext();
 
diff --git a/examples/hostinger-deploy/agent/tools/host.ts b/examples/hostinger-deploy/agent/tools/host.ts
index 893c13dbd..36a21af7d 100644
--- a/examples/hostinger-deploy/agent/tools/host.ts
+++ b/examples/hostinger-deploy/agent/tools/host.ts
@@ -1,4 +1,4 @@
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 import os from 'node:os';
 import { mkdir, readFile, writeFile, readdir } from 'node:fs/promises';
diff --git a/examples/imports.test.ts b/examples/imports.test.ts
index e970c4b37..681da5d9d 100644
--- a/examples/imports.test.ts
+++ b/examples/imports.test.ts
@@ -35,7 +35,7 @@ describe('example imports', () => {
 
   it('tsconfig.json maps exactly the package exports to their sources', () => {
     const { config } = ts.readConfigFile(path.join(REPO_ROOT, 'tsconfig.json'), ts.sys.readFile);
-    // dist/<name> -> src/<name> derivation does not hold for `lousho/spec`:
+    // dist/<name> -> src/<name> derivation does not hold for `@linuxdevil/lousho/spec`:
     // src/spec/index.ts is already the v1 spec barrel, so the browser-safe
     // entry lives at src/spec/v2/index.ts while still building dist/spec/.
     const SOURCE_OVERRIDES: Record<string, string[]> = { [`${pkg.name}/spec`]: ['./src/spec/v2/index.ts'] };
diff --git a/examples/openrouter/index.ts b/examples/openrouter/index.ts
index a20468381..d19b37827 100644
--- a/examples/openrouter/index.ts
+++ b/examples/openrouter/index.ts
@@ -8,8 +8,8 @@
  *   snippets: basic, streaming, compare, tools, agent-builder, models,
  *             cost, errors, conversation, capabilities
  */
-import { LLMProviderRegistry, Message } from 'lousho';
-import { AgentBuilder } from 'lousho/executor';
+import { LLMProviderRegistry, Message } from '@linuxdevil/lousho';
+import { AgentBuilder } from '@linuxdevil/lousho/executor';
 
 const apiKey = process.env.OPENROUTER_API_KEY || '';
 
diff --git a/examples/ops-pipeline/demoProvider.ts b/examples/ops-pipeline/demoProvider.ts
index cf9b2c99a..c07fb6a01 100644
--- a/examples/ops-pipeline/demoProvider.ts
+++ b/examples/ops-pipeline/demoProvider.ts
@@ -13,8 +13,8 @@
  *    registry): returns a fenced ```diff block diagnosing the demo's
  *    synthetic NullPointerException.
  */
-import { GenerateOptions, GenerateResult, LLMProvider, StreamResult } from 'lousho';
-import { textOf } from 'lousho';
+import { GenerateOptions, GenerateResult, LLMProvider, StreamResult } from '@linuxdevil/lousho';
+import { textOf } from '@linuxdevil/lousho';
 
 const DEMO_FIXER_DIFF_RESPONSE = [
   'Root cause: `order` is not null-checked before `charge()` is called.',
diff --git a/examples/ops-pipeline/fixer.test.ts b/examples/ops-pipeline/fixer.test.ts
index 1cc221c18..dfdfbaf84 100644
--- a/examples/ops-pipeline/fixer.test.ts
+++ b/examples/ops-pipeline/fixer.test.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect, vi } from 'vitest';
 import { runFixer, extractDiffBlock, EmptyPatchError, FixRequest, createFixerTool } from './fixer';
-import { LLMProvider, GenerateResult } from 'lousho';
+import { LLMProvider, GenerateResult } from '@linuxdevil/lousho';
 
 function makeScriptedProvider(text: string): LLMProvider {
   const result: GenerateResult = {
diff --git a/examples/ops-pipeline/fixer.ts b/examples/ops-pipeline/fixer.ts
index cb220a73d..87fc1232e 100644
--- a/examples/ops-pipeline/fixer.ts
+++ b/examples/ops-pipeline/fixer.ts
@@ -14,11 +14,11 @@
  * rather than being fixer-core itself.
  */
 import { z } from 'zod';
-import { AgentExecutor, ExecuteOptions } from 'lousho/executor';
-import { ExecutionResult } from 'lousho';
-import { AgentConfig, ToolDescriptor } from 'lousho';
-import { defineTool } from 'lousho';
-import { LLMProvider } from 'lousho';
+import { AgentExecutor, ExecuteOptions } from '@linuxdevil/lousho/executor';
+import { ExecutionResult } from '@linuxdevil/lousho';
+import { AgentConfig, ToolDescriptor } from '@linuxdevil/lousho';
+import { defineTool } from '@linuxdevil/lousho';
+import { LLMProvider } from '@linuxdevil/lousho';
 
 /**
  * A request to diagnose-and-fix an error, built from an ErrorSignal
diff --git a/examples/ops-pipeline/guardedPr.test.ts b/examples/ops-pipeline/guardedPr.test.ts
index 791a110dd..040b39ac1 100644
--- a/examples/ops-pipeline/guardedPr.test.ts
+++ b/examples/ops-pipeline/guardedPr.test.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect, vi } from 'vitest';
 import { handleFixerPatch } from './guardedPr';
-import { ToolDescriptor } from 'lousho';
+import { ToolDescriptor } from '@linuxdevil/lousho';
 
 describe('handleFixerPatch', () => {
   const CLEAN_PATCH = '--- a/foo.txt\n+++ b/foo.txt\n@@ -1 +1 @@\n-old\n+new\n';
diff --git a/examples/ops-pipeline/guardedPr.ts b/examples/ops-pipeline/guardedPr.ts
index 9fac2e6fb..dfaf2162e 100644
--- a/examples/ops-pipeline/guardedPr.ts
+++ b/examples/ops-pipeline/guardedPr.ts
@@ -25,8 +25,8 @@ import {
   createDiffSizeCheck,
   runPatchChecks,
   secretScanCheck,
-} from 'lousho';
-import { ToolDescriptor } from 'lousho';
+} from '@linuxdevil/lousho';
+import { ToolDescriptor } from '@linuxdevil/lousho';
 
 export interface FixerPatchContext {
   /** The REAL hardened GitHub tool's PR-creation ToolDescriptor. */
diff --git a/examples/ops-pipeline/index.ts b/examples/ops-pipeline/index.ts
index f226ba35a..c305a82db 100644
--- a/examples/ops-pipeline/index.ts
+++ b/examples/ops-pipeline/index.ts
@@ -28,10 +28,10 @@
 import * as http from 'node:http';
 import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { ToolDescriptor } from 'lousho';
-import { ToolRegistry } from 'lousho/executor';
-import { verifySlackSignature } from 'lousho/triggers';
-import { LLMProvider } from 'lousho';
+import { ToolDescriptor } from '@linuxdevil/lousho';
+import { ToolRegistry } from '@linuxdevil/lousho/executor';
+import { verifySlackSignature } from '@linuxdevil/lousho/triggers';
+import { LLMProvider } from '@linuxdevil/lousho';
 import { startMonitorServer, MonitorServerHandle, StartMonitorServerOptions } from './monitor';
 import { createFixerTool, buildFixerAgent } from './fixer';
 import { handleFixerPatch } from './guardedPr';
@@ -43,13 +43,13 @@ import {
   readBody,
 } from './slackInteractions';
 import { closeServer, listenOn, sendJson, sendNotFound } from './httpHelpers';
-import { ApprovalStore } from 'lousho';
-import { ExecutionResult } from 'lousho';
-import { PatchCheck } from 'lousho';
+import { ApprovalStore } from '@linuxdevil/lousho';
+import { ExecutionResult } from '@linuxdevil/lousho';
+import { PatchCheck } from '@linuxdevil/lousho';
 import { createDemoProvider } from './demoProvider';
 import { createMockGithubTool } from './mocks/mockGithubTool';
 import { createMockSlackTool } from './mocks/mockSlackTool';
-import { textOf } from 'lousho';
+import { textOf } from '@linuxdevil/lousho';
 
 const DELEGATE_TOOL_NAME = 'delegate_to_fixer';
 const DEFAULT_CHANNEL = '#incidents';
diff --git a/examples/ops-pipeline/mocks/mockGithubTool.ts b/examples/ops-pipeline/mocks/mockGithubTool.ts
index 2407efb56..87fa69ea2 100644
--- a/examples/ops-pipeline/mocks/mockGithubTool.ts
+++ b/examples/ops-pipeline/mocks/mockGithubTool.ts
@@ -5,7 +5,7 @@
  * Never makes a real network call, so the ops-pipeline demo runs with zero
  * external network access.
  */
-import { ToolDescriptor } from 'lousho';
+import { ToolDescriptor } from '@linuxdevil/lousho';
 
 export interface MockCreatedPullRequest {
   title: string;
diff --git a/examples/ops-pipeline/mocks/mockSlackTool.ts b/examples/ops-pipeline/mocks/mockSlackTool.ts
index 36c12cfb6..4aa7c2d06 100644
--- a/examples/ops-pipeline/mocks/mockSlackTool.ts
+++ b/examples/ops-pipeline/mocks/mockSlackTool.ts
@@ -6,8 +6,8 @@
  * POSTing to a real webhook - so the ops-pipeline demo runs with zero
  * external network access.
  */
-import { ToolDescriptor } from 'lousho';
-import { buildSlackAlertPayload, SlackAlertPayload } from 'lousho/integrations';
+import { ToolDescriptor } from '@linuxdevil/lousho';
+import { buildSlackAlertPayload, SlackAlertPayload } from '@linuxdevil/lousho/integrations';
 
 export interface MockSlackPost {
   channel: string;
diff --git a/examples/ops-pipeline/monitor.test.ts b/examples/ops-pipeline/monitor.test.ts
index bb2534e05..759ee33dc 100644
--- a/examples/ops-pipeline/monitor.test.ts
+++ b/examples/ops-pipeline/monitor.test.ts
@@ -1,7 +1,7 @@
 import { describe, it, expect, vi } from 'vitest';
 import { handleErrorSignal, buildMonitorPrompt, ErrorSignal, startMonitorServer } from './monitor';
-import { AgentExecutor } from 'lousho/executor';
-import { createMockProvider } from 'lousho';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { createMockProvider } from '@linuxdevil/lousho';
 
 function makeSignal(overrides: Partial<ErrorSignal> = {}): ErrorSignal {
   return {
diff --git a/examples/ops-pipeline/monitor.ts b/examples/ops-pipeline/monitor.ts
index 77efde879..e1784c927 100644
--- a/examples/ops-pipeline/monitor.ts
+++ b/examples/ops-pipeline/monitor.ts
@@ -15,8 +15,8 @@
  */
 import * as http from 'node:http';
 import { closeServer, listenOn, sendJson, sendNotFound } from './httpHelpers';
-import { AgentExecutor, ExecuteOptions } from 'lousho/executor';
-import { ExecutionResult } from 'lousho';
+import { AgentExecutor, ExecuteOptions } from '@linuxdevil/lousho/executor';
+import { ExecutionResult } from '@linuxdevil/lousho';
 
 /**
  * A single error/incident signal from a monitoring source.
diff --git a/examples/ops-pipeline/pipeline.eval.ts b/examples/ops-pipeline/pipeline.eval.ts
index 5b16b616b..0fc8a8c84 100644
--- a/examples/ops-pipeline/pipeline.eval.ts
+++ b/examples/ops-pipeline/pipeline.eval.ts
@@ -26,10 +26,10 @@
  *    ran, in what order, without inventing a fake single-result shape.
  */
 import { describe, it, expect } from 'vitest';
-import { defineEval } from 'lousho';
-import { toolCallOrder } from 'lousho';
-import { ToolRegistry } from 'lousho/executor';
-import { secretScanCheck, createDiffSizeCheck } from 'lousho';
+import { defineEval } from '@linuxdevil/lousho';
+import { toolCallOrder } from '@linuxdevil/lousho';
+import { ToolRegistry } from '@linuxdevil/lousho/executor';
+import { secretScanCheck, createDiffSizeCheck } from '@linuxdevil/lousho';
 import { startOpsPipeline } from './index';
 import { createDemoProvider } from './demoProvider';
 import { createFixerTool, buildFixerAgent } from './fixer';
diff --git a/examples/ops-pipeline/slackInteractions.test.ts b/examples/ops-pipeline/slackInteractions.test.ts
index ae79c9a9a..a2609c6e9 100644
--- a/examples/ops-pipeline/slackInteractions.test.ts
+++ b/examples/ops-pipeline/slackInteractions.test.ts
@@ -6,9 +6,9 @@ import {
   createInMemoryApprovalStore,
   SlackInteractionPayload,
 } from './slackInteractions';
-import { ApprovalStore, ExecutionSnapshot, PendingApproval } from 'lousho';
-import { ToolRegistry } from 'lousho/executor';
-import { createMockProvider } from 'lousho';
+import { ApprovalStore, ExecutionSnapshot, PendingApproval } from '@linuxdevil/lousho';
+import { ToolRegistry } from '@linuxdevil/lousho/executor';
+import { createMockProvider } from '@linuxdevil/lousho';
 
 describe('extractApprovalIdFromInteraction', () => {
   it('extracts the approvalId from a fix_it block_actions click', () => {
diff --git a/examples/ops-pipeline/slackInteractions.ts b/examples/ops-pipeline/slackInteractions.ts
index 4679dca65..365d8aac1 100644
--- a/examples/ops-pipeline/slackInteractions.ts
+++ b/examples/ops-pipeline/slackInteractions.ts
@@ -10,11 +10,11 @@
  * ApprovalGate, not a bypass or a reimplementation of it.
  */
 import * as http from 'node:http';
-import { resumeAfterApproval, ResumeExecuteOptions } from 'lousho/executor';
-import { ApprovalStore, ExecutionSnapshot, PendingApproval } from 'lousho';
-import { ExecutionResult } from 'lousho';
-import { LLMProvider } from 'lousho';
-import { ToolRegistry } from 'lousho/executor';
+import { resumeAfterApproval, ResumeExecuteOptions } from '@linuxdevil/lousho/executor';
+import { ApprovalStore, ExecutionSnapshot, PendingApproval } from '@linuxdevil/lousho';
+import { ExecutionResult } from '@linuxdevil/lousho';
+import { LLMProvider } from '@linuxdevil/lousho';
+import { ToolRegistry } from '@linuxdevil/lousho/executor';
 
 /** The subset of Slack's real block_actions interaction callback payload this route reads. */
 export interface SlackInteractionPayload {
diff --git a/examples/phase-pipeline/index.test.ts b/examples/phase-pipeline/index.test.ts
index 25bad127c..990f66403 100644
--- a/examples/phase-pipeline/index.test.ts
+++ b/examples/phase-pipeline/index.test.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest';
-import { defineTool } from 'lousho';
-import { ToolRegistry } from 'lousho/executor';
-import { mockModel } from 'lousho/testing';
+import { defineTool } from '@linuxdevil/lousho';
+import { ToolRegistry } from '@linuxdevil/lousho/executor';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 import { buildPhaseFlow, runPhasePipeline, scriptedPhases } from './index';
 
diff --git a/examples/phase-pipeline/index.ts b/examples/phase-pipeline/index.ts
index b63378487..c0f9cd8af 100644
--- a/examples/phase-pipeline/index.ts
+++ b/examples/phase-pipeline/index.ts
@@ -24,16 +24,16 @@ import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { execFile } from 'node:child_process';
 import { z } from 'zod';
-import { defineTool, resolveProvider, type LLMProvider } from 'lousho';
+import { defineTool, resolveProvider, type LLMProvider } from '@linuxdevil/lousho';
 import {
   FlowBuilder,
   FlowExecutor,
   type AgentFlow,
   type EditorStep,
   type FlowExecutionResult,
-} from 'lousho/flows';
-import { ToolRegistry } from 'lousho/executor';
-import { mockModel } from 'lousho/testing';
+} from '@linuxdevil/lousho/flows';
+import { ToolRegistry } from '@linuxdevil/lousho/executor';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 export const LIVE_MODEL = 'openrouter/openai/gpt-4o-mini';
 
diff --git a/examples/plan-mode/index.ts b/examples/plan-mode/index.ts
index f5befa92c..319b2a46a 100644
--- a/examples/plan-mode/index.ts
+++ b/examples/plan-mode/index.ts
@@ -11,10 +11,10 @@
  *
  * Run with: npx tsx examples/plan-mode/index.ts
  */
-import { createAgent } from 'lousho';
-import { createFsTools } from 'lousho';
-import { MemoryWorkspace } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent } from '@linuxdevil/lousho';
+import { createFsTools } from '@linuxdevil/lousho';
+import { MemoryWorkspace } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const workspace = new MemoryWorkspace({
   files: { 'greet.ts': "export function greet(name: string) {\n  return 'Hello ' + name;\n}\n" },
diff --git a/examples/research-assistant/index.ts b/examples/research-assistant/index.ts
index 2cd44fc0e..6a47b3275 100644
--- a/examples/research-assistant/index.ts
+++ b/examples/research-assistant/index.ts
@@ -9,10 +9,10 @@
  *
  * Run with: tsx examples/research-assistant/index.ts
  */
-import { createAgent } from 'lousho';
-import { createMockProvider } from 'lousho';
-import { resolveProvider } from 'lousho';
-import { httpTool } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
+import { createMockProvider } from '@linuxdevil/lousho';
+import { resolveProvider } from '@linuxdevil/lousho';
+import { httpTool } from '@linuxdevil/lousho';
 
 const provider = process.env.ANTHROPIC_API_KEY
   ? resolveProvider('anthropic/claude-3-5-sonnet-latest')
diff --git a/examples/slack-notifier/index.ts b/examples/slack-notifier/index.ts
index 967a887e6..29c82966c 100644
--- a/examples/slack-notifier/index.ts
+++ b/examples/slack-notifier/index.ts
@@ -7,9 +7,9 @@
  *
  * Run with: tsx examples/slack-notifier/index.ts
  */
-import { createAgent } from 'lousho';
-import { createMockProvider } from 'lousho';
-import { resolveProvider } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
+import { createMockProvider } from '@linuxdevil/lousho';
+import { resolveProvider } from '@linuxdevil/lousho';
 
 const provider = process.env.OPENAI_API_KEY
   ? resolveProvider('openai/gpt-4o-mini')
diff --git a/examples/support-bot/index.ts b/examples/support-bot/index.ts
index 574c3c7c7..fc81e4ded 100644
--- a/examples/support-bot/index.ts
+++ b/examples/support-bot/index.ts
@@ -6,9 +6,9 @@
  *
  * Run with: tsx examples/support-bot/index.ts
  */
-import { createAgent } from 'lousho';
-import { createMockProvider } from 'lousho';
-import { resolveProvider } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
+import { createMockProvider } from '@linuxdevil/lousho';
+import { resolveProvider } from '@linuxdevil/lousho';
 
 const provider = process.env.OPENAI_API_KEY
   ? resolveProvider('openai/gpt-4o-mini')
diff --git a/examples/support-desk/index.test.ts b/examples/support-desk/index.test.ts
index 6785631b9..cd1c92255 100644
--- a/examples/support-desk/index.test.ts
+++ b/examples/support-desk/index.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
-import { mockModel, type MockModel } from 'lousho/testing';
+import { mockModel, type MockModel } from '@linuxdevil/lousho/testing';
 import { createSupportDesk, demoState, scriptedBilling, scriptedTriage } from './index';
 
 const toolNames = (model: MockModel, call: number) => (model.calls[call]?.tools ?? []).map((tool) => tool.function.name);
diff --git a/examples/support-desk/index.ts b/examples/support-desk/index.ts
index 01d9953b4..c77274b44 100644
--- a/examples/support-desk/index.ts
+++ b/examples/support-desk/index.ts
@@ -65,8 +65,8 @@ import {
   type HandoffInputData,
   type LLMProvider,
   type SimpleAgent,
-} from 'lousho';
-import { mockModel } from 'lousho/testing';
+} from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 export const LIVE_MODEL = 'openrouter/openai/gpt-4o-mini';
 
diff --git a/examples/tracing/console-exporter.ts b/examples/tracing/console-exporter.ts
index 7a5366fdc..7a1549f58 100644
--- a/examples/tracing/console-exporter.ts
+++ b/examples/tracing/console-exporter.ts
@@ -9,7 +9,7 @@
  * createOtelTraceExporter() for a bundled OpenTelemetry bridge).
  */
 
-import { Span, TraceExporter } from 'lousho';
+import { Span, TraceExporter } from '@linuxdevil/lousho';
 
 export function createConsoleExporter(): TraceExporter {
   // Tracks depth so nested spans (chat/execute_tool under invoke_agent)
diff --git a/examples/tracing/run-otel.ts b/examples/tracing/run-otel.ts
index f516708ec..d86fac841 100644
--- a/examples/tracing/run-otel.ts
+++ b/examples/tracing/run-otel.ts
@@ -29,7 +29,7 @@ import {
   ConsoleSpanExporter,
   SimpleSpanProcessor,
 } from '@opentelemetry/sdk-trace-node';
-import { createOtelTraceExporter } from 'lousho/otel';
+import { createOtelTraceExporter } from '@linuxdevil/lousho/otel';
 import { runWeatherScenario } from './weather-scenario';
 
 async function main() {
diff --git a/examples/tracing/weather-scenario.ts b/examples/tracing/weather-scenario.ts
index 0b218016f..c010a91cb 100644
--- a/examples/tracing/weather-scenario.ts
+++ b/examples/tracing/weather-scenario.ts
@@ -7,11 +7,11 @@
 
 import { tool } from 'ai';
 import { z } from 'zod';
-import { AgentExecutor } from 'lousho/executor';
-import { AgentBuilder } from 'lousho/executor';
-import { ToolRegistry } from 'lousho/executor';
-import { LLMProvider, GenerateOptions, GenerateResult } from 'lousho';
-import type { TraceExporter } from 'lousho';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { AgentBuilder } from '@linuxdevil/lousho/executor';
+import { ToolRegistry } from '@linuxdevil/lousho/executor';
+import { LLMProvider, GenerateOptions, GenerateResult } from '@linuxdevil/lousho';
+import type { TraceExporter } from '@linuxdevil/lousho';
 
 /** A tiny mock provider: one tool call, then a final answer. */
 class MockProvider implements LLMProvider {
diff --git a/examples/waves/index.test.ts b/examples/waves/index.test.ts
index a9574b3c9..952c1921c 100644
--- a/examples/waves/index.test.ts
+++ b/examples/waves/index.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
-import { createAgent } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { runWaves } from './index';
 
 /** A worker factory handing each new agent the next scripted line. */
diff --git a/examples/waves/index.ts b/examples/waves/index.ts
index 67f79a052..30738370f 100644
--- a/examples/waves/index.ts
+++ b/examples/waves/index.ts
@@ -23,8 +23,8 @@
 import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
-import { createAgent, resolveProvider, type LLMProvider, type SimpleAgent } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, resolveProvider, type LLMProvider, type SimpleAgent } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 export const LIVE_MODEL = 'openrouter/openai/gpt-4o-mini';
 
diff --git a/examples/workflow-router/index.ts b/examples/workflow-router/index.ts
index ebb672c1d..0c96b8703 100644
--- a/examples/workflow-router/index.ts
+++ b/examples/workflow-router/index.ts
@@ -7,9 +7,9 @@
  *
  * Run with: tsx examples/workflow-router/index.ts
  */
-import { createAgent } from 'lousho';
-import { createMockProvider } from 'lousho';
-import { resolveProvider } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
+import { createMockProvider } from '@linuxdevil/lousho';
+import { resolveProvider } from '@linuxdevil/lousho';
 
 const provider = process.env.OPENAI_API_KEY
   ? resolveProvider('openai/gpt-4o-mini')
diff --git a/examples/workspace-marketing/host.ts b/examples/workspace-marketing/host.ts
index c64f6bebc..5095e5b50 100644
--- a/examples/workspace-marketing/host.ts
+++ b/examples/workspace-marketing/host.ts
@@ -3,8 +3,8 @@ import { mkdirSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
-import { defineTool, type LLMProvider, type ToolDescriptor } from 'lousho';
-import { mockModel, type MockModel, type MockRequest } from 'lousho/testing';
+import { defineTool, type LLMProvider, type ToolDescriptor } from '@linuxdevil/lousho';
+import { mockModel, type MockModel, type MockRequest } from '@linuxdevil/lousho/testing';
 import {
   checkRegistry,
   createWorkspaceStores,
@@ -17,7 +17,7 @@ import {
   type PageToolScope,
   type WorkspaceHost,
   type WorkspaceCheckRegistry,
-} from 'lousho/workspaces';
+} from '@linuxdevil/lousho/workspaces';
 
 const WORKSPACE_DIR = fileURLToPath(new URL('./workspace', import.meta.url));
 
diff --git a/examples/workspace-marketing/index.test.ts b/examples/workspace-marketing/index.test.ts
index 12d68734a..d2ca19f95 100644
--- a/examples/workspace-marketing/index.test.ts
+++ b/examples/workspace-marketing/index.test.ts
@@ -2,10 +2,10 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
-import { createWorkspaceRuntime, memorySource, resolveCheck, type PageResult, type WorkspaceRuntime } from 'lousho/workspaces';
+import { createWorkspaceRuntime, memorySource, resolveCheck, type PageResult, type WorkspaceRuntime } from '@linuxdevil/lousho/workspaces';
 import { marketingChecks, marketingHost, PAGES, readWorkspaceFiles, scriptedMarketingModel, WORKSPACE_ID } from './host';
 import { runMarketing } from './run';
-import { jsonSchemaToStandardSchema } from 'lousho/spec';
+import { jsonSchemaToStandardSchema } from '@linuxdevil/lousho/spec';
 
 const dirs: string[] = [];
 const runtimes: WorkspaceRuntime[] = [];
diff --git a/examples/workspace-marketing/run.ts b/examples/workspace-marketing/run.ts
index 5fe4c7811..63cb5db57 100644
--- a/examples/workspace-marketing/run.ts
+++ b/examples/workspace-marketing/run.ts
@@ -3,8 +3,8 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { parseArgs } from 'node:util';
 import { fileURLToPath } from 'node:url';
-import { resolveProvider } from 'lousho';
-import { createWorkspaceRuntime, memorySource, type PageResult } from 'lousho/workspaces';
+import { resolveProvider } from '@linuxdevil/lousho';
+import { createWorkspaceRuntime, memorySource, type PageResult } from '@linuxdevil/lousho/workspaces';
 import { marketingHost, PAGES, readWorkspaceFiles, type PageId } from './host';
 
 const TOPIC = 'why the sky is blue';
diff --git a/llms-full.txt b/llms-full.txt
index 918b7bd78..2bd7667d6 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -19,11 +19,11 @@ TypeScript AI agents you can test in CI, pause for approval, and resume after a
   <a href="https://lousho.com/agent-forge">
     <picture>
       <source media="(prefers-color-scheme: dark)" srcset="docs/images/studio-trace-dark.png">
-      <img alt="Agent Forge, the local studio, showing one agent run as a trace" src="docs/images/studio-trace.png" width="560">
+      <img alt="Lousho Studio, the local studio, showing one agent run as a trace" src="docs/images/studio-trace.png" width="560">
     </picture>
   </a>
   <br>
-  <sub>Agent Forge, the local studio. Open it with <code>npx lousho studio</code>.</sub>
+  <sub>Lousho Studio, the local studio. Open it with <code>npx @linuxdevil/studio</code> (a separate install).</sub>
 </div>
 
 ## Why Lousho
@@ -31,7 +31,7 @@ TypeScript AI agents you can test in CI, pause for approval, and resume after a
 - **Test agents in CI without an API key.** `lousho eval` records a real run once, replays it with no network, and reports when the tool-call trajectory drifts. [Evals](https://lousho.com/evals)
 - **Resume after a crash.** Give the agent a store and `agent.resume()` finishes an interrupted run. Tool calls that already have a result do not run again. [Durable execution](https://lousho.com/durable-execution)
 - **Pause for a human.** A tool marked `needsApproval` pauses the run. Another request, or with a durable store another process, can approve it later, and the run continues where it stopped. [Approvals](https://lousho.com/approvals)
-- **Runs in your own Node process.** There is no hosted runtime. `lousho build` targets a Node server, Docker or Cloudflare Workers, and `lousho studio` runs on your machine. [Deployment](https://lousho.com/deployment)
+- **Runs in your own Node process.** There is no hosted runtime. `lousho build` targets a Node server, Docker or Cloudflare Workers, and Lousho Studio (`@linuxdevil/studio`, a separate install) runs on your machine. [Deployment](https://lousho.com/deployment)
 - **Works with the Vercel AI SDK.** `fromAiSdk()` and `fromAiSdkTools()` wrap AI SDK models and tools, so you can move over one piece at a time. [Migrating from the AI SDK](https://lousho.com/migrating-from-ai-sdk)
 
 ## Try it in 60 seconds, no API key
@@ -49,8 +49,8 @@ npm test
 Now add an eval. Save this as `src/weather.eval.ts`:
 
 ```ts no-run
-import { createAgent, defineEval, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineEval, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const getWeather = defineTool({
@@ -83,7 +83,7 @@ defineEval({
 Then run it:
 
 ```bash
-npx lousho eval
+npx @linuxdevil/lousho eval
 ```
 
 ```text
@@ -96,9 +96,9 @@ weather advice  -     PASS    -       14ms
 To test against a real model, use `model: 'openai/gpt-4.1-mini'` in place of `provider`, set your key and record once. This step needs the key. Commit the cassettes it writes. CI then replays them with no network and no key:
 
 ```bash
-npx lousho eval --record
-npx lousho eval --replay
-npx lousho eval --drift
+npx @linuxdevil/lousho eval --record
+npx @linuxdevil/lousho eval --replay
+npx @linuxdevil/lousho eval --drift
 ```
 
 `--drift` re-records each case and shows where the tool calls, arguments or step count changed. See [Record, replay and drift](https://lousho.com/evals#record-replay-and-drift).
@@ -122,17 +122,17 @@ Requires Node.js 22.19 or newer. To start a new project, see [Try it](#try-it-in
 To add Lousho to an existing project:
 
 ```bash
-npm install lousho ai@^7.0.0 zod @ai-sdk/openai@^4.0.0
+npm install @linuxdevil/lousho ai@^7.0.0 zod @ai-sdk/openai@^4.0.0
 ```
 
-See [Installation](https://lousho.com/installation#provider-packages) for other providers. `npx lousho doctor` checks your setup and prints a fix for anything missing.
+See [Installation](https://lousho.com/installation#provider-packages) for other providers. `npx @linuxdevil/lousho doctor` checks your setup and prints a fix for anything missing.
 
 ## Quickstart
 
 This file uses top-level `await`, so it must be an ES module (`.mts`, or `"type": "module"` in `package.json`). Set `OPENAI_API_KEY` to run it.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const getWeather = defineTool({
@@ -154,7 +154,7 @@ console.log(text);
 
 ### Agent folders
 
-An agent can also be a folder, which you run with `npx lousho dev ./my-agent`:
+An agent can also be a folder, which you run with `npx @linuxdevil/lousho dev ./my-agent`:
 
 ```text
 my-agent/
@@ -172,9 +172,9 @@ Loading a folder runs its code, so only load ones you trust. See [Agent director
 - **Multi-agent**: [sub-agents](https://lousho.com/sub-agents) that run in parallel, and [handoffs](https://lousho.com/handoffs) to specialists.
 - **UI**: bindings for [React](https://lousho.com/react), [Vue](https://lousho.com/vue) and [Svelte](https://lousho.com/svelte), plus [AI SDK `useChat`](https://lousho.com/ai-sdk-ui) and [Next.js routes](https://lousho.com/nextjs).
 - **Tracing**: OpenTelemetry GenAI spans and a local trace viewer. [Observability](https://lousho.com/observability)
-- **Agent Forge**: `lousho studio` opens a local visual canvas, run debugger and chat. [Agent Forge](https://lousho.com/agent-forge)
+- **Lousho Studio**: a separate install (`npx @linuxdevil/studio`) opens a local visual canvas, run debugger and chat across all your projects. [Lousho Studio](https://lousho.com/agent-forge)
 - **Self-healing (experimental)**: `lousho improve` turns an agent's failed runs into tested edits to its instructions and skills, applies one that passes (or queues it for a person), and rolls it back on a regression. [Self-healing](https://github.com/LinuxDevil/lousho/blob/main/docs/self-healing.md)
-- **Workspaces (experimental)**: `lousho/workspaces` holds the contracts for a workspace of pages, harnesses and shared policy: schemas, validation, harness composition and typed authoring operations. [Workspaces](https://github.com/LinuxDevil/lousho/blob/main/docs/workspaces.md)
+- **Workspaces (experimental)**: `@linuxdevil/lousho/workspaces` holds the contracts for a workspace of pages, harnesses and shared policy: schemas, validation, harness composition and typed authoring operations. [Workspaces](https://github.com/LinuxDevil/lousho/blob/main/docs/workspaces.md)
 - **Coding agents**: workspace tools, permission rules and starter kits from `lousho add`. [Build a coding agent](https://lousho.com/build-a-coding-agent)
 
 ## Documentation
@@ -223,11 +223,11 @@ Source: docs/installation.md
 ## Install the package
 
 ```bash
-npm install lousho ai zod
+npm install @linuxdevil/lousho ai zod
 # or
-pnpm add lousho ai zod
+pnpm add @linuxdevil/lousho ai zod
 # or
-yarn add lousho ai zod
+yarn add @linuxdevil/lousho ai zod
 ```
 
 `ai` (the Vercel AI SDK: `^4.3.19`, `^6.0.0` or `^7.0.0`) and `zod`
@@ -256,7 +256,7 @@ that pairs with your `ai` major. Install the pair from one row:
 For example, on the current `ai` major:
 
 ```bash
-npm install lousho ai@^7.0.0 zod @ai-sdk/openai@^4.0.0
+npm install @linuxdevil/lousho ai@^7.0.0 zod @ai-sdk/openai@^4.0.0
 ```
 
 **Ollama on `ai` 6/7 needs zod 4.** `ollama-ai-provider-v2` (the Ollama package
@@ -274,7 +274,7 @@ with zod 4, and `ai` 7 with zod 3 and with zod 4. The two zod 4 entries on
 `ai` 6 and 7 also install `ollama-ai-provider-v2` (3.x and 4.x) and run the
 Ollama provider against it, so Ollama on `ai` 6/7 is tested, not assumed.
 
-Peers are loaded on demand: importing `lousho` (or any of
+Peers are loaded on demand: importing `@linuxdevil/lousho` (or any of
 its sub-entries) never loads a provider package, so you only need to install
 the ones you use. Each provider package is loaded the first time that
 provider makes a call; if it is missing, that call fails with a
@@ -288,7 +288,7 @@ npm install @ai-sdk/openai@^0.0.42
 ```
 
 ```ts no-run
-import { MissingPeerDependencyError, resolveProvider } from 'lousho';
+import { MissingPeerDependencyError, resolveProvider } from '@linuxdevil/lousho';
 
 const provider = resolveProvider('openai/gpt-4o-mini'); // needs OPENAI_API_KEY; does not load the peer
 try {
@@ -310,9 +310,9 @@ the `lousho init` questions or code mode installs none of them:
 | --------------------------- | --------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------ |
 | `dockerode`                 | `^5.0.1`  | Docker sandboxing: `SubprocessSandbox` (and `lousho doctor`'s Docker ping)                    | `npm install dockerode@^5.0.1`                   |
 | `@modelcontextprotocol/sdk` | `^1.31.0` | MCP: `createAgent({ mcpServers })` / `connectMcp()`, `serveMcp()` and `lousho mcp`            | `npm install @modelcontextprotocol/sdk@^1.31.0`  |
-| `@opentelemetry/api`        | `^1.9.1`  | OpenTelemetry tracing: `createOtelTraceExporter()` from `lousho/otel`         | `npm install @opentelemetry/api@^1.9.1`          |
-| `react`                     | `^18`, `^19` | The React bindings (`lousho/react`)                                      | `npm install react`                              |
-| `vue`                       | `^3`      | The Vue bindings (`lousho/vue`)                                               | `npm install vue@^3`                             |
+| `@opentelemetry/api`        | `^1.9.1`  | OpenTelemetry tracing: `createOtelTraceExporter()` from `@linuxdevil/lousho/otel`         | `npm install @opentelemetry/api@^1.9.1`          |
+| `react`                     | `^18`, `^19` | The React bindings (`@linuxdevil/lousho/react`)                                      | `npm install react`                              |
+| `vue`                       | `^3`      | The Vue bindings (`@linuxdevil/lousho/vue`)                                               | `npm install vue@^3`                             |
 | `tsup`                      | `^8.0.0`  | `lousho build`, which bundles the agent for each target                                       | `npm install --save-dev tsup@^8.0.0`             |
 | `prompts`                   | `^2.4.2`  | The interactive questions of `lousho init` (`lousho init --yes` and flags need nothing)       | `npm install prompts@^2.4.2`                     |
 | `quickjs-emscripten`        | `^0.32.0` | [Code mode](https://github.com/LinuxDevil/lousho/blob/main/docs/code-mode.md): `createAgent({ codeMode })` runs `run_code` scripts in its QuickJS isolate | `npm install quickjs-emscripten@^0.32.0` |
@@ -325,7 +325,7 @@ that names the feature and the exact command, for example:
 The optional package 'dockerode' is not installed, but Docker sandboxing (SubprocessSandbox) needs it. Run: npm install dockerode@^5.0.1
 ```
 
-`npm create lousho` installs `prompts` itself, so scaffolding with it
+`npm create @linuxdevil/lousho` installs `prompts` itself, so scaffolding with it
 needs nothing extra. `lousho doctor` lists every optional peer, what it
 enables and whether it is installed (a missing `dockerode` is an error only
 when the agent spec uses a sandboxed tool).
@@ -343,8 +343,7 @@ The tarball is about 4 MB packed (15 MB unpacked). That is a stated trade-off,
 not an accident: `src/` ships because `lousho build` bundles
 `src/deploy/runtime.worker.ts` and `src/index.ts` from the installed package
 and the `dist/` source maps point at it (the maps carry no embedded source;
-embedding it instead and dropping `src/` measured larger, 5.2 MB packed), and
-`apps/agent-forge/` is the prebuilt dashboard that `lousho studio` serves. The
+embedding it instead and dropping `src/` measured larger, 5.2 MB packed). The
 1 MB `llms-full.txt` is in the repo, not the package.
 
 ## Entry points share code (ESM and CJS)
@@ -365,25 +364,25 @@ The entries `exports` declares, and what each one holds:
 
 | Import specifier | What it holds |
 | ---------------- | ------------- |
-| `lousho` | The root: `createAgent()`, `defineTool()`, `defineChannel()`, agents' public types, events, stores (`memoryStore()`, `fileStore()`), hooks, guardrails, sessions, skills, memory, sub-agents, evals, spec files, deployment types |
-| `lousho/executor` | The executor API (advanced - prefer `createAgent()`): `AgentExecutor`, `AgentBuilder`, `resumeAfterApproval()`, `streamResumeAfterApproval()`, `resumeRequest()`, `ToolRegistry`, `globalToolRegistry` |
-| `lousho/tools` | The tools surface: `defineTool()`, `ToolRegistry`, the built-in tools, MCP/OpenAPI helpers |
-| `lousho/flows` | `FlowBuilder`, `FlowExecutor`, `validateFlow()` and every flow type (`AgentFlow`, `EditorStep`, `FlowExecutionEvent`, ...) |
-| `lousho/integrations` | The credentialed third-party tools: `createJiraTools()`, `createGitHubTools()`, `createSlackTool()` / `slackTool`, `postSlackAlert()`, `createEmailTool()` and their types |
-| `lousho/utils` | `EncryptionUtils`, `sha256()`, `generatePassword()`, `StorageService`, `StorageServiceApprovalStore`, `LocalStorageCheckpointStore` and the validators (`validateWithSchema`, `isValidEmail`, ...) |
-| `lousho/mcp` | MCP client and server helpers: `connectMcp()`, `loadMcpTools()`, `serveMcp()` |
-| `lousho/types` | The public types without the runtime |
-| `lousho/testing` | `mockModel()`, `recordReplay()` and the offline-test helpers |
-| `lousho/otel` | `createOtelTraceExporter()` (needs the optional `@opentelemetry/api` peer) |
-| `lousho/hooks` | The hooks surface: `HookRegistry`, hook types |
-| `lousho/sqlite` | `SqliteStore` (sessions, checkpoints, approvals and tokens in one SQLite file; needs Node's `node:sqlite`) |
-| `lousho/auth` | Route auth: `routeAuth()`, `jwt()`, `oidc()`, `basic()`, `apiToken()`, `anonymous()` |
-| `lousho/kv` | `KVStore`, `KVCheckpointStore` for a hand-written Cloudflare Worker |
-| `lousho/traces` | `fileTraceExporter()`, `listTraces()`, `readTrace()` (what `lousho traces` reads) |
-| `lousho/triggers` | `TriggerAdapter`, `TriggerRegistry`, `verifySlackSignature`, `parseCronExpression` |
-| `lousho/react` | `useLoushoAgent()` and the React helpers (needs `react`) |
-| `lousho/vue` | `useLoushoAgent()` as a Vue composable (needs `vue`) |
-| `lousho/svelte` | `loushoAgent()` as a Svelte store |
+| `@linuxdevil/lousho` | The root: `createAgent()`, `defineTool()`, `defineChannel()`, agents' public types, events, stores (`memoryStore()`, `fileStore()`), hooks, guardrails, sessions, skills, memory, sub-agents, evals, spec files, deployment types |
+| `@linuxdevil/lousho/executor` | The executor API (advanced - prefer `createAgent()`): `AgentExecutor`, `AgentBuilder`, `resumeAfterApproval()`, `streamResumeAfterApproval()`, `resumeRequest()`, `ToolRegistry`, `globalToolRegistry` |
+| `@linuxdevil/lousho/tools` | The tools surface: `defineTool()`, `ToolRegistry`, the built-in tools, MCP/OpenAPI helpers |
+| `@linuxdevil/lousho/flows` | `FlowBuilder`, `FlowExecutor`, `validateFlow()` and every flow type (`AgentFlow`, `EditorStep`, `FlowExecutionEvent`, ...) |
+| `@linuxdevil/lousho/integrations` | The credentialed third-party tools: `createJiraTools()`, `createGitHubTools()`, `createSlackTool()` / `slackTool`, `postSlackAlert()`, `createEmailTool()` and their types |
+| `@linuxdevil/lousho/utils` | `EncryptionUtils`, `sha256()`, `generatePassword()`, `StorageService`, `StorageServiceApprovalStore`, `LocalStorageCheckpointStore` and the validators (`validateWithSchema`, `isValidEmail`, ...) |
+| `@linuxdevil/lousho/mcp` | MCP client and server helpers: `connectMcp()`, `loadMcpTools()`, `serveMcp()` |
+| `@linuxdevil/lousho/types` | The public types without the runtime |
+| `@linuxdevil/lousho/testing` | `mockModel()`, `recordReplay()` and the offline-test helpers |
+| `@linuxdevil/lousho/otel` | `createOtelTraceExporter()` (needs the optional `@opentelemetry/api` peer) |
+| `@linuxdevil/lousho/hooks` | The hooks surface: `HookRegistry`, hook types |
+| `@linuxdevil/lousho/sqlite` | `SqliteStore` (sessions, checkpoints, approvals and tokens in one SQLite file; needs Node's `node:sqlite`) |
+| `@linuxdevil/lousho/auth` | Route auth: `routeAuth()`, `jwt()`, `oidc()`, `basic()`, `apiToken()`, `anonymous()` |
+| `@linuxdevil/lousho/kv` | `KVStore`, `KVCheckpointStore` for a hand-written Cloudflare Worker |
+| `@linuxdevil/lousho/traces` | `fileTraceExporter()`, `listTraces()`, `readTrace()` (what `lousho traces` reads) |
+| `@linuxdevil/lousho/triggers` | `TriggerAdapter`, `TriggerRegistry`, `verifySlackSignature`, `parseCronExpression` |
+| `@linuxdevil/lousho/react` | `useLoushoAgent()` and the React helpers (needs `react`) |
+| `@linuxdevil/lousho/vue` | `useLoushoAgent()` as a Vue composable (needs `vue`) |
+| `@linuxdevil/lousho/svelte` | `loushoAgent()` as a Svelte store |
 
 ### TypeScript settings
 
@@ -453,8 +452,8 @@ one-line `CLAUDE.md` importing it) telling coding agents the project's files,
 scripts and conventions. It then installs the dependencies and runs `git init`.
 
 ```bash
-npm create lousho my-agent   # or: npx lousho init my-agent
-npx lousho init my-agent --yes --provider anthropic --template tools --no-install
+npm create @linuxdevil/lousho my-agent   # or: npx @linuxdevil/lousho init my-agent
+npx @linuxdevil/lousho init my-agent --yes --provider anthropic --template tools --no-install
 ```
 
 | Flag | Meaning |
@@ -470,16 +469,26 @@ npx lousho init my-agent --yes --provider anthropic --template tools --no-instal
 `create-lousho` (`packages/create-lousho`) is a thin wrapper that
 runs `lousho init` with the same arguments.
 
-## The `lousho` CLI
+## The `@linuxdevil/lousho` CLI
 
-Installing the package also installs the `lousho` command: `init`, `doctor`,
-`dev`, `chat`, `acp`, `add`, `mcp`, `eval`, `traces`, `build` and `studio`. See
+Installing the package also installs the `@linuxdevil/lousho` command: `init`, `doctor`,
+`dev`, `chat`, `acp`, `add`, `mcp`, `eval`, `traces`, `build`, `studio`,
+`observe`, `bridge` and more. See
 [CLI](https://github.com/LinuxDevil/lousho/blob/main/docs/cli.md) for what each one does and its flags. Building needs `tsup`,
 an optional peer (see the table above): `npm install --save-dev tsup`.
 
+### Studio (optional)
+
+The visual dashboard, Lousho Studio, is a separate package,
+`@linuxdevil/studio` - it is not part of this tarball. Install it with
+`npm i -g @linuxdevil/studio` (or run `npx @linuxdevil/studio`), or just run
+`lousho studio` inside a project that has the SDK: the launcher finds an
+installed Studio and opens the folder as a workspace. See
+[Lousho Studio](https://github.com/LinuxDevil/lousho/blob/main/docs/agent-forge.md).
+
 ## Troubleshooting: lousho doctor
 
-Run `npx lousho doctor` right after installing. It prints one line per check
+Run `npx @linuxdevil/lousho doctor` right after installing. It prints one line per check
 with a status (`ok`, `warn`, `FAIL`), what it found, and, for anything that is
 not ok, the command to run or the setting to change:
 
@@ -574,19 +583,19 @@ npm test                 # offline tests: no API key needed
 
 To try a locally packed `create-lousho` (`npm pack`), pass the tarball's absolute path with `--package`: `npx --package=/abs/path/create-lousho-x.y.z.tgz create-lousho my-agent`. A bare `npx ../x.tgz` fails on Windows.
 
-`npx lousho init my-agent` is equivalent (pass `--provider`
+`npx @linuxdevil/lousho init my-agent` is equivalent (pass `--provider`
 and `--template`, since it runs without the interactive prompts). Inside a
-project that already has the SDK installed, `npx lousho init` works too: the
-`lousho` command comes from the SDK package, so a bare `npx lousho` outside such
+project that already has the SDK installed, `npx @linuxdevil/lousho init` works too: the
+`lousho` command comes from the SDK package, so a bare `npx @linuxdevil/lousho` outside such
 a project finds nothing to run. Without arguments, `init` asks for the
-directory, provider and template; `npx lousho init --help`
+directory, provider and template; `npx @linuxdevil/lousho init --help`
 lists every flag.
 
 Prefer to add the SDK to an existing project? Install it by hand (see
 [Installation](https://github.com/LinuxDevil/lousho/blob/main/docs/installation.md)):
 
 ```bash
-npm install lousho ai@^7.0.0 zod
+npm install @linuxdevil/lousho ai@^7.0.0 zod
 npm install @ai-sdk/openai@^4.0.0 @ai-sdk/anthropic@^4.0.0
 ```
 
@@ -603,7 +612,7 @@ providers). The `vendor/` model prefix chooses the provider; with OpenRouter
 use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4.1-mini`).
 
 ```ts no-run
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4.1-mini', instructions: 'You are a helpful assistant.' });
 const { text } = await agent.send('Hello!');
@@ -626,7 +635,7 @@ whenever the user message mentions a tool's name, so this snippet exercises a
 real tool round trip without an LLM.
 
 ```ts
-import { createAgent, createMockProvider, defineTool } from 'lousho';
+import { createAgent, createMockProvider, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const currentDate = defineTool({
@@ -659,7 +668,7 @@ it for typed events (model text as it arrives, tool calls, step boundaries),
 and `await run.result` for the same result `send()` returns.
 
 ```ts
-import { createAgent, createMockProvider } from 'lousho';
+import { createAgent, createMockProvider } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   instructions: 'You are a helpful assistant.',
@@ -685,7 +694,7 @@ sending the events to a browser.
 keeps the transcript and passes it to the model on each `send()`.
 
 ```ts
-import { createAgent, createMockProvider } from 'lousho';
+import { createAgent, createMockProvider } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   instructions: 'You are a helpful assistant.',
@@ -707,12 +716,12 @@ Pass a store to keep sessions across restarts; see [Sessions](https://github.com
 Flag a tool `needsApproval` and the run pauses before calling it. `send()`
 resolves with `finishReason: 'awaiting-approval'` and an `approvalId`; your code
 (or a human) then approves or rejects the call and the run continues. Here
-`mockModel` from `lousho/testing` scripts the model's turns
+`mockModel` from `@linuxdevil/lousho/testing` scripts the model's turns
 exactly, so the tool call is certain.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
@@ -750,8 +759,8 @@ request the agent made, so you can assert on what the model was sent as well as
 on the result. No network, no key.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 let sent: string | undefined;
@@ -798,7 +807,7 @@ the mock provider otherwise - the same pattern the runnable
 [examples](https://github.com/LinuxDevil/lousho/blob/main/examples/README.md) use.
 
 ```ts
-import { createAgent, createMockProvider, resolveProvider } from 'lousho';
+import { createAgent, createMockProvider, resolveProvider } from '@linuxdevil/lousho';
 
 const provider = process.env.OPENAI_API_KEY
   ? resolveProvider('openai/gpt-4.1-mini')
@@ -821,7 +830,7 @@ into a live agent with `specToAgent()`. The same shape can be written as a
 YAML or JSON file and loaded with `loadSpec()`.
 
 ```ts
-import { specToAgent, agentSpecSchema } from 'lousho';
+import { specToAgent, agentSpecSchema } from '@linuxdevil/lousho';
 
 const spec = agentSpecSchema.parse({
   name: 'support-bot',
@@ -851,8 +860,8 @@ the same spec runs in the local dev server (chat UI at `/`, `POST /chat`,
 hot reload on save) and builds into a deployable server:
 
 ```bash
-npx lousho dev agent.yaml
-npx lousho build --target=node-server --agent=agent.yaml
+npx @linuxdevil/lousho dev agent.yaml
+npx @linuxdevil/lousho build --target=node-server --agent=agent.yaml
 ```
 
 ## Advanced: the executor API
@@ -917,9 +926,9 @@ How the pieces fit:
 | Export                        | Description                                                                 |
 | ----------------------------- | --------------------------------------------------------------------------- |
 | `createAgent(config)`         | Zero-config `{ send(message) }` agent from a `model` string or provider (+ instructions, tools). |
-| `AgentBuilder` (from `lousho/executor`) | Fluent builder for an `AgentConfig` (`AgentBuilder.create().setName(...)...build()`). Advanced: see [the executor API](https://github.com/LinuxDevil/lousho/blob/main/docs/executor-api.md). |
-| `AgentExecutor.execute(opts)` (from `lousho/executor`) | Static executor: runs an agent (LLM + tool-calling loop) and resolves to an `ExecutionResult`. Advanced: see [the executor API](https://github.com/LinuxDevil/lousho/blob/main/docs/executor-api.md). |
-| `resumeAfterApproval()` (from `lousho/executor`) | Resume an execution paused for human approval. Advanced: see [the executor API](https://github.com/LinuxDevil/lousho/blob/main/docs/executor-api.md). |
+| `AgentBuilder` (from `@linuxdevil/lousho/executor`) | Fluent builder for an `AgentConfig` (`AgentBuilder.create().setName(...)...build()`). Advanced: see [the executor API](https://github.com/LinuxDevil/lousho/blob/main/docs/executor-api.md). |
+| `AgentExecutor.execute(opts)` (from `@linuxdevil/lousho/executor`) | Static executor: runs an agent (LLM + tool-calling loop) and resolves to an `ExecutionResult`. Advanced: see [the executor API](https://github.com/LinuxDevil/lousho/blob/main/docs/executor-api.md). |
+| `resumeAfterApproval()` (from `@linuxdevil/lousho/executor`) | Resume an execution paused for human approval. Advanced: see [the executor API](https://github.com/LinuxDevil/lousho/blob/main/docs/executor-api.md). |
 | `InMemoryApprovalStore`       | Process-local `ApprovalStore`; the default store of `createAgent()` agents. |
 | `StorageServiceApprovalStore`, `LocalStorageCheckpointStore` (from `/utils`) | File-backed approval and checkpoint stores over a `StorageService` (see [Approvals](https://github.com/LinuxDevil/lousho/blob/main/docs/approvals.md), [Durable execution](https://github.com/LinuxDevil/lousho/blob/main/docs/durable-execution.md)). |
 | `SqliteStore` (from `/sqlite`) | Sessions, checkpoints and approvals in one SQLite file (see [Sessions](https://github.com/LinuxDevil/lousho/blob/main/docs/sessions.md#choosing-a-store)). |
@@ -947,8 +956,8 @@ resolves with the task prompt as `input` and the lead run's `sessionId`,
 `metadata` and `principal`.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const refund = defineTool({ name: 'refund', description: 'Refunds an order', input: z.object({ orderId: z.string() }), execute: async () => 'ok' });
@@ -977,14 +986,14 @@ when it is created.
 
 ### UI bindings
 
-`lousho/react` exports `useLoushoAgent(source, options?)`, a
+`@linuxdevil/lousho/react` exports `useLoushoAgent(source, options?)`, a
 React hook that runs an agent in process (`{ agent, sessionId? }`) or over HTTP
 (`{ url }`) and returns `messages`, `status`, `pendingApproval`,
 `send()`, `stop()`, `approve()` and `reject()`. Its framework-neutral parts,
 `reduceAgentEvents()` and `parseEventStream()`, are exported too. See
-[React](https://github.com/LinuxDevil/lousho/blob/main/docs/react.md). `lousho/vue` exports the same
+[React](https://github.com/LinuxDevil/lousho/blob/main/docs/react.md). `@linuxdevil/lousho/vue` exports the same
 `useLoushoAgent()` as a Vue 3 composable, with the state as refs. See
-[Vue](https://github.com/LinuxDevil/lousho/blob/main/docs/vue.md). `lousho/svelte` exports `loushoAgent()`, the
+[Vue](https://github.com/LinuxDevil/lousho/blob/main/docs/vue.md). `@linuxdevil/lousho/svelte` exports `loushoAgent()`, the
 same state and actions as a Svelte store (`$agent`). See [Svelte](https://github.com/LinuxDevil/lousho/blob/main/docs/svelte.md).
 
 ### Sub-agents
@@ -1082,7 +1091,7 @@ See [Providers](https://github.com/LinuxDevil/lousho/blob/main/docs/providers.md
 
 ## Testing
 
-Exported from `lousho/testing` (see [Testing agents](https://github.com/LinuxDevil/lousho/blob/main/docs/testing.md)).
+Exported from `@linuxdevil/lousho/testing` (see [Testing agents](https://github.com/LinuxDevil/lousho/blob/main/docs/testing.md)).
 
 | Export                | Description                                                                              |
 | --------------------- | ---------------------------------------------------------------------------------------- |
@@ -1095,18 +1104,18 @@ Exported from `lousho/testing` (see [Testing agents](https://github.com/LinuxDev
 | -------------------------------------------- | --------------------------------------------- |
 | `defineTool({ name, description, input, execute, ... })` | Define a tool; `execute`/`needsApproval` args are inferred from the zod `input`. Accepted by `createAgent({ tools: [...] })`, `ToolRegistry.register(tool)` and `AgentBuilder.addTool(tool)`. |
 | `ToolInput<typeof t>`, `ToolOutput<typeof t>` | Argument and result types of a defined tool. |
-| `ToolRegistry` (from `lousho/tools` or `lousho/executor`) | Holds the tools an agent config refers to (advanced: `register(tool)` or `register(name, descriptor)`). |
+| `ToolRegistry` (from `@linuxdevil/lousho/tools` or `@linuxdevil/lousho/executor`) | Holds the tools an agent config refers to (advanced: `register(tool)` or `register(name, descriptor)`). |
 | `httpTool`, `currentDateTool`, `dayNameTool` | Built-in tools.                               |
 | `createFsTools(fs, options?)`, `createShellTool(shell, options?)` | Workspace tools (`read_file`, `write_file`, `edit_file`, `list_dir`, `glob`, `grep`, `shell`) over an `FsProvider` / `ShellProvider`. See [Workspace tools](https://github.com/LinuxDevil/lousho/blob/main/docs/workspace-tools.md). |
 | `NodeWorkspace`, `MemoryWorkspace`, `SandboxShell` | Workspace providers: a real directory (paths confined to `root`, minimal shell env), an in-memory tree with a scripted `exec` for tests, and a `ShellProvider` over a `SandboxAdapter` (Docker). |
 | `createTodoTools({ store?, onChange? })`     | `todo_write` / `todo_read` tools (plus `getTodos()`) so agents can plan and track multi-step work; see [Todo tools](https://github.com/LinuxDevil/lousho/blob/main/docs/tools.md#todo-tools). |
 | `connectMcp(servers, options?)`             | Connect MCP servers from config (stdio or HTTP) and load their tools; see [Share servers with `connectMcp()`](https://github.com/LinuxDevil/lousho/blob/main/docs/mcp.md#share-servers-with-connectmcp). |
-| `loadMcpTools(client, connectionName)`       | Load a connected MCP server's tools as `ToolDescriptor`s. Available from the package root, `lousho/tools`, and `lousho/mcp`. |
+| `loadMcpTools(client, connectionName)`       | Load a connected MCP server's tools as `ToolDescriptor`s. Available from the package root, `@linuxdevil/lousho/tools`, and `@linuxdevil/lousho/mcp`. |
 
 See [Tools](https://github.com/LinuxDevil/lousho/blob/main/docs/tools.md) for a guide to defining and registering tools.
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
@@ -1132,7 +1141,7 @@ execute }`) is legacy, still built for compatibility, and used only for
 descriptors that do not set `inputSchema` / `execute`.
 
 ```ts
-import { loadMcpTools } from 'lousho/mcp';
+import { loadMcpTools } from '@linuxdevil/lousho/mcp';
 
 const tools = await loadMcpTools(mcpClient, 'my-server');
 ```
@@ -1159,7 +1168,7 @@ warning naming the server, the tool and the reason, and `onSkip` to collect
 what was left out:
 
 ```ts
-import { loadMcpTools, type SkippedMcpTool } from 'lousho/mcp';
+import { loadMcpTools, type SkippedMcpTool } from '@linuxdevil/lousho/mcp';
 
 const skipped: SkippedMcpTool[] = [];
 const tools = await loadMcpTools(mcpClient, 'my-server', {
@@ -1188,13 +1197,13 @@ Token estimates, the model price table, and the usage and cost of a run: see [Mo
 
 ## Flows, evals, observability and security
 
-- `FlowBuilder` / `FlowExecutor` (`lousho/flows`) - multi-step
+- `FlowBuilder` / `FlowExecutor` (`@linuxdevil/lousho/flows`) - multi-step
   workflow graphs; see [Flows](https://github.com/LinuxDevil/lousho/blob/main/docs/flows.md).
-- `TriggerAdapter` and `TriggerRegistry` (`lousho/triggers`) -
+- `TriggerAdapter` and `TriggerRegistry` (`@linuxdevil/lousho/triggers`) -
   the extension point for your own wake-up mechanism, plus `verifySlackSignature()`,
   `parseCronExpression()` and the `WebhookAuth` helpers; see [Triggers](https://github.com/LinuxDevil/lousho/blob/main/docs/triggers.md).
 - `jwt()`, `oidc()`, `basic()`, `apiToken()`, `anonymous()` and `routeAuth()`
-  (`lousho/auth`) - route auth as an ordered list; the caller
+  (`@linuxdevil/lousho/auth`) - route auth as an ordered list; the caller
   it accepts reaches the run as `principal`; see [Route auth and principals](https://github.com/LinuxDevil/lousho/blob/main/docs/auth.md).
 - `defineEval()`, scorers such as `exactMatch`, `toolCallOrder` and `budget`, checks such
   as `includes` and `atLeast`, and `llmJudge()` - agent evals run under vitest
@@ -1202,7 +1211,7 @@ Token estimates, the model price table, and the usage and cost of a run: see [Mo
 - `withSpan()` and `TraceExporter` - tracing for `AgentExecutor.execute()`.
   `TraceExporter` is a bring-your-own-exporter interface (no exporter
   ships by default); for real OpenTelemetry spans, import
-  `createOtelTraceExporter()` from the `lousho/otel`
+  `createOtelTraceExporter()` from the `@linuxdevil/lousho/otel`
   subpath (requires the optional peer dependency `@opentelemetry/api`)
   instead of hand-rolling the OTel bridge - see
   `examples/tracing/run-otel.ts`. Spans follow the OpenTelemetry GenAI
@@ -1216,7 +1225,7 @@ Token estimates, the model price table, and the usage and cost of a run: see [Mo
   `GenerateHookContext` - hooks that observe, deny, rewrite or redact tool calls
   and model calls. See [Hooks](https://github.com/LinuxDevil/lousho/blob/main/docs/hooks.md).
 - `EncryptionUtils`, `sha256`, `StorageService`
-  (`lousho/utils`) - supporting utilities; see
+  (`@linuxdevil/lousho/utils`) - supporting utilities; see
   [Utilities](https://github.com/LinuxDevil/lousho/blob/main/docs/utilities.md).
 
 ## Deployment
@@ -1238,9 +1247,9 @@ it, watch its tool calls and approve them from the editor's agent panel.
 ## The command
 
 ```bash
-npx lousho acp agent.yaml                          # a spec file
-npx lousho acp ./my-agent --model openai/gpt-4o    # an agent directory, on another model
-npx lousho acp src/agent.ts                        # a .ts/.js module (createAgent() options or an agent)
+npx @linuxdevil/lousho acp agent.yaml                          # a spec file
+npx @linuxdevil/lousho acp ./my-agent --model openai/gpt-4o    # an agent directory, on another model
+npx @linuxdevil/lousho acp src/agent.ts                        # a .ts/.js module (createAgent() options or an agent)
 ```
 
 ```text
@@ -1346,7 +1355,7 @@ It resolves once `input` ends, after aborting any running turn.
 
 ```ts
 import * as readline from 'node:readline';
-import { createAgent, serveAcp } from 'lousho';
+import { createAgent, serveAcp } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You are a coding assistant.' });
 
@@ -1374,7 +1383,7 @@ code at any time without a rewrite.
 > implied; the files run with your process's full permissions.
 
 ```ts
-import { loadAgentDir } from 'lousho';
+import { loadAgentDir } from '@linuxdevil/lousho';
 
 const agent = await loadAgentDir('./my-agent');
 const { text } = await agent.send('Hello!');
@@ -1471,7 +1480,7 @@ rule decides.
 
 ```ts
 // hooks.ts — the default export is a hook or a list of them
-import type { AgentHook } from 'lousho';
+import type { AgentHook } from '@linuxdevil/lousho';
 const audit: AgentHook = {
   name: 'audit',
   postToolCall(ctx) {
@@ -1483,7 +1492,7 @@ export default audit;
 
 ```ts
 // approve.ts — the default export decides every `ask`ed call
-import type { ApproveToolCall } from 'lousho';
+import type { ApproveToolCall } from '@linuxdevil/lousho';
 const approve: ApproveToolCall = ({ args }) => !String(args.path ?? '').endsWith('.test.js');
 export default approve;
 ```
@@ -1508,7 +1517,7 @@ that exports no tool at all is an error, as are two tools with the same name
 ```ts no-verify
 // tools/send_email.ts
 import { z } from 'zod';
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 
 export default defineTool({
   name: 'send_email',
@@ -1599,7 +1608,7 @@ internal helper of the generated bundle); with your own server, use
 
 ```ts
 import { createServer } from 'node:http';
-import { createAgent, mountChannels, resolveAgentDir } from 'lousho';
+import { createAgent, mountChannels, resolveAgentDir } from '@linuxdevil/lousho';
 
 // channels/support.ts: export default webhookChannel({ secret: process.env.HOOK_SECRET ?? '' })
 const { config, channels } = await resolveAgentDir('./my-agent');
@@ -1622,7 +1631,7 @@ naming the file. A `memory` override passed to `loadAgentDir(dir, { overrides })
 is merged with the directory's slots by name: the override wins a name clash.
 
 ```ts
-import { defineMemory, fileMemory, resolveAgentDir } from 'lousho';
+import { defineMemory, fileMemory, resolveAgentDir } from '@linuxdevil/lousho';
 
 // memory/notes.ts: export default { scope: 'global', provider: fileMemory({ dir: './.lousho/memory' }) }
 const { manifest } = await resolveAgentDir('./my-agent', {
@@ -1636,7 +1645,7 @@ A relative `dir` in a `memory/*.ts` file resolves against the process working di
 ```ts
 // memory/notes.ts
 import { fileURLToPath } from 'node:url';
-import { fileMemory } from 'lousho';
+import { fileMemory } from '@linuxdevil/lousho';
 
 export default {
   scope: 'global',
@@ -1660,7 +1669,7 @@ The path follows the module: a copied or bundled build keeps its memory next to
 handy for tests and tooling:
 
 ```ts
-import { resolveAgentDir, createAgent } from 'lousho';
+import { resolveAgentDir, createAgent } from '@linuxdevil/lousho';
 
 const { config, manifest } = await resolveAgentDir('./my-agent');
 console.log(manifest.tools, manifest.skills, manifest.subagents);
@@ -1680,8 +1689,8 @@ declares (`guardrails`, `onEvent`, `retry`, `reasoning`, `redactContent`,
 `output`, ...). Use it to swap the model in tests:
 
 ```ts no-run
-import { loadAgentDir } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { loadAgentDir } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const agent = await loadAgentDir('./my-agent', { provider: mockModel(['Hi there.']) });
 ```
@@ -1712,7 +1721,7 @@ says so. Compile the directory first, or use `.js`/`.mjs` tools with an
 ## Run it with `lousho dev`
 
 ```bash
-npx lousho dev ./my-agent
+npx @linuxdevil/lousho dev ./my-agent
 ```
 
 Serves the chat UI and `POST /chat` for the directory and reloads it when
@@ -1731,7 +1740,7 @@ dev](https://github.com/LinuxDevil/lousho/blob/main/docs/schedules.md#in-lousho-
 ## Deploy it with `lousho build`
 
 ```bash
-npx lousho build ./my-agent --target=node-server    # or docker
+npx @linuxdevil/lousho build ./my-agent --target=node-server    # or docker
 ```
 
 The agent directory is the unit of deployment: the built server loads it with
@@ -1754,70 +1763,80 @@ The Cloudflare Worker target builds a directory too, embedding every folder: `su
 `lousho mcp` takes an agent directory as well as a spec file ([Configuration](https://github.com/LinuxDevil/lousho/blob/main/docs/configuration.md)):
 `lousho mcp ./my-agent` serves it as an MCP server ([MCP](https://github.com/LinuxDevil/lousho/blob/main/docs/mcp.md#serve-an-agent-over-mcp)).
 
-# Agent Forge
+# Lousho Studio
 
 Source: docs/agent-forge.md
 
-Agent Forge (`apps/agent-forge`, also called the Studio) is this SDK's
-companion dashboard: one app with a left navigation to build and run agents,
-try prompts, and read what your agents did from the observe daemon. Build an
-agent's graph on a canvas, run it, chat with it and author sandboxed
-pre/post hooks (all reading and writing the same `AgentSpec` YAML that
-`lousho dev` and `lousho build` use), try prompts in a playground, and read
-the [observe daemon](https://github.com/LinuxDevil/lousho/blob/main/docs/observability.md#the-observe-daemon)'s traces,
-threads, fleet monitoring, eval scores, datasets, annotation queues, prompt
-registry and context hub. It's launched with one command,
-`lousho studio`, and ships as part of this SDK's npm package.
-
-This doc covers: installation, the `lousho studio` quickstart, the
-[navigation and screens](#navigation), a first-agent walkthrough, hook
-authoring, time travel (replaying a run from a past step), the playground
-endpoint, and how settings/secrets/deploy wiring works.
-
-Three features have their own pages: [the visual
-builder](https://github.com/LinuxDevil/lousho/blob/main/docs/forge-builder.md) — the canvas, Inspector, Configure tab,
-in-place testing and Code tab — [the Agent
-Author](https://github.com/LinuxDevil/lousho/blob/main/docs/forge-author.md) — the chat that drafts agents as proposals you
-review before anything is saved — and [versions, triggers and
-publishing](https://github.com/LinuxDevil/lousho/blob/main/docs/forge-lifecycle.md) — the working copy, drafts, the inbox,
-the eval gate, Serve and Deploy.
+Lousho Studio is a local web app for building, testing and watching every agent across your projects.
 
-## Installation
+It is a separate npm package, `@linuxdevil/studio` — the SDK (`@linuxdevil/lousho`)
+does not contain it. One Studio server shows every agent you have: the spec-v2
+graph agents saved in your project folders, code agents Studio finds by scanning
+a workspace, and agents running anywhere that report to the observe collector.
+
+This page covers installing and starting Studio, workspaces, which SDK runs a
+workspace's agents (and what each banner means), the collector, and how agents
+deployed on other machines show up here. [Using Studio](#using-studio) covers
+the builder, the playground, traces and the rest of the app; the builder,
+Author and lifecycle screens have their own pages: [the visual
+builder](https://github.com/LinuxDevil/lousho/blob/main/docs/forge-builder.md), [the Agent
+Author](https://github.com/LinuxDevil/lousho/blob/main/docs/forge-author.md) and [versions, triggers and
+publishing](https://github.com/LinuxDevil/lousho/blob/main/docs/forge-lifecycle.md).
 
-Agent Forge ships inside `lousho` itself - there's no
-separate package to install:
+## Install and start
+
+Any of these works:
 
 ```bash
-npm install lousho
+npx @linuxdevil/studio
 ```
 
-That's it. `lousho studio` (below) runs a pre-built copy of the app; you
-don't need `apps/agent-forge`'s own source or its devDependencies (Vite,
-`tsx`, etc.) to use it.
-
-If you're working inside this SDK's own monorepo instead (contributing to
-Agent Forge itself), see [Dev mode](#dev-mode) below.
+```bash
+npm i -g @linuxdevil/studio
+lousho-studio
+```
 
-## Quickstart
+Or, inside a project that already has `@linuxdevil/lousho` installed, the SDK's
+launcher finds the installed Studio and opens this folder as a workspace:
 
 ```bash
-npx lousho studio
-```
-
-This starts one local server and prints its URL (default
-`http://127.0.0.1:4750/?token=<random>`). Open that exact URL in a browser.
-It lands on the Agents list (`#/agents`): your saved agents as cards, plus
-a **New agent** menu. Opening or creating one takes you to its Canvas tab
-(`#/agents/<id>/canvas`) — the builder: the build toolbar (the agent's name
-and run status, the model badge, then Debug, Stop, Run, Import, Export and
-Save), the agent rail (your saved agents plus a node/hook palette), the
-canvas, the Inspector (right), and a bottom drawer with Test, Problems,
-Logs, Trace, Output, History and Settings tabs. An agent opens with
-nothing selected and the whole graph fitted in view; the Inspector stays
-folded away until you select a node, or press the **Inspector** button at
-the canvas's top-right (its accessible name is "Show inspector"), which is
-remembered. The other screens are one click away in the navigation; see
-[Navigation](#navigation).
+lousho studio
+```
+
+When no Studio is installed the launcher says so instead of bundling one:
+
+```
+Studio is a separate install: npx @linuxdevil/studio
+```
+
+`lousho studio` accepts `--port` and `--host` and passes them through; run
+`lousho studio --help` for its options. `--prod` and `--dev` only apply inside
+the SDK's own repository checkout (see [Dev mode](#dev-mode)).
+
+`lousho-studio` (and `npx @linuxdevil/studio`) take the same flags:
+
+| Flag | Default | Meaning |
+| --- | --- | --- |
+| `--workspace <dir>` | the current folder | A project folder to open; it is added to your workspaces. |
+| `--port N` | `4750` | The port to listen on. |
+| `--host H` | `127.0.0.1` | The interface to bind to. |
+
+The server prints its URL, `http://127.0.0.1:4750/?token=<random>`. The
+`?token=` is a per-launch access token: the page keeps it for that tab and
+sends it on every API call, so open the printed URL, not the bare host (see
+[Access token](#access-token)).
+
+Opening Studio lands on the Agents list (`#/agents`): your saved agents as
+cards, plus a **New agent** menu. Opening or creating one takes you to its
+Canvas tab — the builder: the build toolbar (the agent's name and run
+status, the model badge, then Debug, Stop, Run, Import, Export and Save),
+the agent rail (your saved agents plus a node/hook palette), the canvas, the
+Inspector (right), and a bottom drawer with Test, Problems, Logs, Trace,
+Output, History and Settings tabs. An agent opens with nothing selected and
+the whole graph fitted in view; the Inspector stays folded away until you
+select a node, or press the **Inspector** button at the canvas's top-right
+(its accessible name is "Show inspector"), which is remembered. The other
+screens are one click away in the navigation; see [Navigation](#navigation).
 
 Below 860px wide the navigation becomes a drawer opened from the
 **Navigation** (menu) button at the top; picking a screen, the scrim or Esc
@@ -1826,15 +1845,145 @@ slide-over panels you open from the top bar; Run (or Stop) and Save stay in
 the bar, and Debug, Import, Export and the model badge move into its **More
 actions** (`⋯`) menu.
 
-Useful flags:
+## Workspaces
+
+A workspace is a project folder on disk. The folder you launch Studio from is
+added automatically; add more with **Add workspace → folder path** (or the
+**Add workspace…** entry in the switcher).
+
+The switcher at the top of the nav lists **All workspaces**, each workspace,
+and **Add workspace…**. `#/agents` is the all-workspaces list; an agent route
+is `#/w/<workspace>/agents/<id>/<tab>`.
+
+Things live in three places:
+
+| Where | What |
+| --- | --- |
+| `~/.lousho/studio/` | Studio-wide state: the workspace registry, settings, secrets, assistant sessions, pass spend, inbox alerts. Shared across workspaces. |
+| `<workspace>/.lousho/agents/` | The project's agents: spec, metadata, layout, working copy, versions, drafts, suggestions, traces, chats, approvals, checkpoints. Travels with the project. |
+| `~/.lousho/observe.db` | The observe collector's database (traces, scores, sessions). |
+
+On first launch after the split, if a workspace still has a project-level
+`.lousho/settings.json` or `.lousho/secrets.json`, Studio offers **Import
+settings and keys from <workspace>** once, copies them into
+`~/.lousho/studio/`, and leaves the originals alone.
+
+## Three kinds of agent
+
+The all-workspaces agent list mixes three kinds:
+
+| Kind | Source | What you can do |
+| --- | --- | --- |
+| Workspace agent | `<workspace>/.lousho/agents/<id>.yaml` (Agent spec v2) | Everything: canvas, Author, versions, test, publish. |
+| Code agent | An agent directory or `agent.ts` found by scanning a workspace | Read-only canvas, traces, runs. |
+| Observed agent | Any agent reporting to the observe collector (`GET /api/v1/agents`): deployed workers, CI, other machines | Read-only card: name, project, instances, last seen, traces, scores, evals. |
+
+Observed agents whose collector `project` matches a workspace id appear under
+that workspace (see [See agents running elsewhere](#see-agents-running-elsewhere)).
+The rest are grouped under **Elsewhere**.
+
+## Which SDK runs your agents
+
+For each workspace Studio picks how agent processes run:
+
+- **Bridge** — the normal case. Studio spawns `lousho bridge` from the SDK
+  installed in that project (`@linuxdevil/lousho`), so runs use the project's
+  own SDK version. This matters because a project's `{ file }` tools and
+  skills import that project's dependencies, which only resolve inside the
+  project.
+- **In-process** — Studio's own built-in SDK, used when the project has no
+  SDK installed or its checkout is not built.
+- **Read-only** — the project's SDK is too old or speaks a protocol this
+  Studio does not know, so edits are refused until it is fixed.
+
+Each non-default state shows a banner at the top of the workspace's pages:
+
+| Banner | What to do |
+| --- | --- |
+| `This project has no @linuxdevil/lousho installed. Runs use Studio's built-in SDK <version>.` | Runs still work on Studio's SDK. Install `@linuxdevil/lousho` in the project to run its own version. |
+| `This SDK checkout is not built, so runs use Studio's built-in SDK <version>. Run npm run build to use it.` | Inside the SDK repository: run `npm run build` in the checkout. |
+| `Update @linuxdevil/lousho in this project to <minimum> or later to edit agents here.` | The project's SDK is older than this Studio understands. The workspace is read-only: update `@linuxdevil/lousho` in the project to edit. |
+| `This project's @linuxdevil/lousho <version> is newer than this Studio understands. Update Studio to edit agents here.` | The project has a newer SDK than this Studio was built for. Update Studio (`npm i -g @linuxdevil/studio@latest`) to edit. |
+| `This project's agent process keeps stopping. Check the Studio terminal for its output, then restart it.` | The bridge process crashed repeatedly. Its output is in the terminal that started Studio; use **Restart** on the banner to try again. |
+
+While a workspace is read-only, writes under its agents (saves, drafts, runs,
+deploys) are refused; reads still work.
+
+A few features still need Studio's built-in SDK and are unavailable on
+bridge workspaces:
+
+- Flow runs: `Flow runs need Studio's built-in SDK for now. Remove the project's SDK from this workspace or run the flow from code.`
+- Breakpoints: `Breakpoints need Studio's built-in SDK for now.`
+- Time travel: `Time travel is not available yet for projects that run their own SDK.`
+
+## The collector
+
+Everything under Observe, Evaluate and Assets — and run reporting — reads the
+observe collector. On boot Studio probes the configured URL (default
+`http://127.0.0.1:7777`):
+
+- **Attached** — a `lousho observe` daemon is already running there; Studio
+  uses it.
+- **Started** — none answered on loopback, so Studio started its own and
+  stops it on exit. It never stops a daemon it did not start.
+- **Remote** — a non-loopback URL (team or hosted collector); Studio probes
+  it but does not start or stop anything there.
+- **Down** — nothing answers; daemon screens show the start command instead
+  of data and recover on their own.
+
+The collector card at the bottom of the nav shows the mode (`Attached to
+<url>`, `Started by Studio on <url>`, `Remote collector at <url>`, `Not
+reachable: <error>`). **Settings → Collector** sets a remote URL and bearer
+token; create a token with `lousho observe token create --project <name>`.
+`LOUSHO_OBSERVE_URL` and `LOUSHO_OBSERVE_TOKEN` in Studio's own environment
+override the stored setting, and `LOUSHO_STUDIO_COLLECTOR=0` stops Studio
+from auto-starting a local daemon.
+
+## See agents running elsewhere
+
+An agent deployed on another machine — a server, CI, a teammate's laptop —
+shows up in Studio once it reports to a collector Studio can read. Reporting
+is pure SDK configuration; nothing in the agent is Studio-specific:
+
+```ts no-run
+import { createAgent } from '@linuxdevil/lousho';
+
+// LOUSHO_OBSERVE, LOUSHO_OBSERVE_TOKEN and LOUSHO_OBSERVE_PROJECT are read
+// from the environment - no Studio-specific code.
+export const agent = createAgent({ model: 'openai/gpt-4.1-mini' });
+```
+
+Set these in the deployed environment:
+
+| Variable | Meaning |
+| --- | --- |
+| `LOUSHO_OBSERVE` | The collector URL, e.g. `http://127.0.0.1:7777` or a tunnel/remote URL. `1`/`true` uses the default. |
+| `LOUSHO_OBSERVE_TOKEN` | Bearer token, when the collector requires one (`lousho observe token create`). |
+| `LOUSHO_OBSERVE_PROJECT` | The workspace id to group the agent under — shown in **Settings → Workspaces**. Without it the project name is the package name and the agent appears under **Elsewhere**. |
+
+Point Studio at the same collector under **Settings → Collector** (or with
+`LOUSHO_OBSERVE_URL`/`LOUSHO_OBSERVE_TOKEN` in Studio's environment), and the
+deployed agent's traces, scores and sessions appear in Studio's Observe
+screens.
+
+## Updating
+
+Studio (`@linuxdevil/studio`) and the SDK (`@linuxdevil/lousho`) are separate
+packages and update independently:
 
 ```bash
-npx lousho studio --port 5000       # pick a different port
-npx lousho studio --host 0.0.0.0    # bind to all interfaces
-npx lousho studio --prod            # force production mode (see below)
-npx lousho studio --dev             # force dev mode (monorepo only)
+npm i -g @linuxdevil/studio@latest   # Studio itself
+npm i @linuxdevil/lousho@latest      # inside each project, its SDK
 ```
 
+A workspace's agents edit only when the project's SDK is at least
+`MIN_BRIDGE_SDK_VERSION` — the SDK version this Studio was built against. Older
+SDKs get the read-only banner above; newer ones get the "update Studio" banner.
+Bridge workspaces also need `lousho bridge` in the project's SDK, which speaks
+bridge protocol `1`.
+
+## Using Studio
+
 ### Access token
 
 The studio can store provider keys, start runs and execute hook code, so its
@@ -1866,40 +2015,38 @@ without the CLI:
 
 ### Where agents live
 
-Agent specs and run state are stored under `.lousho/` in the directory you
-ran `lousho studio` from (agent YAML files under `.lousho/agents/`,
-checkpoints and approvals alongside them) - the same `.lousho/` layout
-`lousho dev`/`lousho build` use. Those YAML files are
-[Agent spec v2](https://github.com/LinuxDevil/lousho/blob/main/docs/agent-spec.md) documents, which that page explains field
-by field.
-
-The agents list and the builder's agent rail show exactly the agents in that `.lousho/agents/`: a YAML
-file you add there shows up, and an agent you create in the studio is
-written there at once (autosave and **Save** both write the file), so it
-can be chatted with straight away. Another project, opened in its own
-`lousho studio`, shows only its own agents. The browser keeps nothing but a
-draft of an edit that could not reach the server (it is pushed on the next
-load), stored per workspace directory. A file in `.lousho/agents/` that no
-longer parses is skipped with a warning in the server log.
+Each workspace's agent specs and run state live under `.lousho/` in that
+project folder (agent YAML files under `.lousho/agents/`, checkpoints and
+approvals alongside them) - the same `.lousho/` layout `lousho dev`/`lousho
+build` use, so the files travel with the project and stay diffable.
+Studio-wide state (settings, secrets, the workspace registry) lives in
+`~/.lousho/studio/` instead; see [Workspaces](#workspaces). Those YAML files
+are [Agent spec v2](https://github.com/LinuxDevil/lousho/blob/main/docs/agent-spec.md) documents, which that page explains
+field by field.
+
+The Agents screen's agent rail lists exactly the agents in that workspace's
+`.lousho/agents/`: a YAML file you add there shows up, and an agent you
+create in the studio is written there at once (autosave and **Save** both
+write the file), so it can be chatted with straight away. Another workspace
+shows only its own agents. The browser keeps nothing but a draft of an edit
+that could not reach the server (it is pushed on the next load), stored per
+workspace directory. A file in `.lousho/agents/` that no longer parses is
+skipped with a warning in the server log.
 
 ### Production vs. dev mode
 
-`lousho studio` has two modes, and picks the right one automatically:
-
-- **Production** (the default once Agent Forge has been built): a single
-  Express server serves both the REST/WebSocket API *and* the pre-built
-  client (React app) as static files, on one port. This is what runs when
-  you `npm install` the published package - there's no separate Vite dev
-  server and no TypeScript loader involved.
-- **Dev** (falls back to this if the build hasn't been run yet, i.e. inside
-  a source checkout of this monorepo): the API server runs straight off
-  its TypeScript source via `tsx`, alongside a real Vite dev server (with
-  hot-module reload) that proxies API requests to it. Two processes, two
-  ports internally, one command.
+An installed Studio (`lousho-studio`, `npx @linuxdevil/studio`, or
+`lousho studio` finding it) is always production mode: a single Express
+server serves both the REST/WebSocket API *and* the pre-built client (React
+app) as static files, on one port. There is no separate Vite dev server and
+no TypeScript loader involved.
 
-`--prod`/`--dev` force one or the other; run without either flag and
-`lousho studio` auto-detects based on whether `apps/agent-forge/dist-server`
-exists.
+Dev mode - the API server running from TypeScript via `tsx` next to a Vite
+dev server with hot-module reload - exists only inside the SDK's own
+repository checkout, for people contributing to Studio itself. There
+`lousho studio --dev` (or `--prod` to force the built bundle) picks the mode;
+run without either flag it auto-detects based on whether
+`apps/agent-forge/dist-server` exists. See [Dev mode](#dev-mode).
 
 ## Navigation
 
@@ -2002,30 +2149,27 @@ Every status in the Studio is the same pill:
 
 ### The collector (observe daemon)
 
-Everything under Observe, Evaluate and Assets reads the observe daemon
-(`lousho observe start`) through the Studio server's `/observe` proxy. The
-proxy reads only `LOUSHO_OBSERVE_URL` (default `http://127.0.0.1:7777`);
-`LOUSHO_OBSERVE` does not change where the screens read (it only picks where
-builder runs report, see the [walkthrough](#first-agent-walkthrough)). When
-`LOUSHO_OBSERVE_TOKEN` is set, the proxy sends it to the daemon as the bearer
-token on every read and write (as run reporting and the judge evaluators do),
-so the screens also work against a daemon started with `--require-token`.
-Without it, such a daemon answers `401` to every `/api/` read and the screens
-show that error instead of data (`/health` still answers, so the collector
-card says running). The browser's own credentials (the Studio token, cookies,
-`Authorization`) are never passed on. The proxy only forwards reads plus the
-writes the screens make (feedback scores, new prompt versions from the
-Playground, prompt label moves, hub entry edits, dataset and example writes,
-annotation queue writes, evaluator rule writes); every other write, ingest
-above all, is refused with `405`. It always calls the daemon at
-`LOUSHO_OBSERVE_URL`, whatever host the request line names.
-
-The collector card at the bottom of the nav says whether the daemon answers:
-**Checking collector…** until the first probe, then **Collector running**
-or **Collector unreachable**, with the daemon URL underneath. The probe keeps polling. While the daemon is down, each
-daemon screen shows the command to start it instead of an error, keeps its
-URL, and swaps the data back in by itself once the daemon answers. Builder
-and Playground runs do not need the daemon.
+Everything under Observe, Evaluate and Assets reads the observe collector
+through the Studio server's `/observe` proxy, which calls whatever URL the
+collector manager resolved (see [The collector](#the-collector)). The proxy
+forwards reads plus the writes the screens make (feedback scores, new prompt
+versions from the Playground, prompt label moves, hub entry edits, dataset
+and example writes, annotation queue writes, evaluator rule writes); every
+other write, ingest above all, is refused with `405`. When a bearer token is
+configured the proxy sends it to the collector on every read and write (as
+run reporting and the judge evaluators do), so the screens also work against
+a collector started with `--require-token`. Without it, such a collector
+answers `401` to every `/api/` read and the screens show that error instead
+of data (`/health` still answers, so the collector card says running). The
+browser's own credentials (the Studio token, cookies, `Authorization`) are
+never passed on.
+
+The collector card at the bottom of the nav shows the resolved mode —
+**Attached to \<url\>**, **Started by Studio on \<url\>**, **Remote collector
+at \<url\>** or **Not reachable: \<error\>** — and keeps polling. While the
+collector is down, each daemon screen shows the command to start it instead
+of an error, keeps its URL, and swaps the data back in by itself once it
+answers. The Agents screen and Playground runs do not need the collector.
 
 ## Screens
 
@@ -2220,7 +2364,7 @@ filter (agent, status `ok` or `error`, name contains), and the kind:
   the provider's environment variable where the Studio runs (the stored key
   wins); the provider list offers the providers that have either, plus
   `ollama` and `mock`. With no key at all the judge option is disabled, with
-  a link to Settings. Judges run only while `lousho studio` is running; until
+  a link to Settings. Judges run only while Studio is running; until
   then their jobs wait in the daemon (see
   [Judge rules](https://github.com/LinuxDevil/lousho/blob/main/docs/observability.md#judge-rules-through-agent-forge)). Set
   `LOUSHO_STUDIO_JUDGE=0` on the Studio server to turn its judge loop off.
@@ -2316,10 +2460,10 @@ and deploy cards; see [Settings, secrets and deploy wiring](#settings-secrets-an
    `awaiting approval`), and once the run's trace id is known an **Open
    trace** link next to it opens the run at `#/traces/<traceId>` (in the
    narrow layout it is in the **More** menu). Builder runs report to the
-   observe daemon as agent `<agent id>`, the same way the Playground does:
-   when `LOUSHO_OBSERVE` is set its reporter is used (nothing is reported
-   twice), a daemon that is down only drops events and never fails the run,
-   and message content is sent only to a loopback daemon (never to the
+   observe collector as agent `<agent id>`, the same way the Playground
+   does (see [The collector](#the-collector)): a collector that is down
+   only drops events and never fails the run, and message content is sent
+   only to a loopback collector (never to the
    trace files or the live Trace tab). Run sends a fixed
    prompt, which the Test tab's chat shows
    as a **Run input** bubble instead of a message from you. If the studio
@@ -2350,9 +2494,9 @@ and deploy cards; see [Settings, secrets and deploy wiring](#settings-secrets-an
    live. Selecting a step highlights its node on the canvas. The list
    refreshes when a run ends. The files are the ones `lousho traces` reads, in
    `.lousho/agents/<agent id>/traces/<day>/<trace id>.jsonl` under the
-   directory `lousho studio` was started in (see
+   workspace folder (see
    [Local traces](https://github.com/LinuxDevil/lousho/blob/main/docs/observability.md#local-traces)):
-   `npx lousho traces --dir .lousho/agents/<agent id>/traces` shows the same
+   `npx @linuxdevil/lousho traces --dir .lousho/agents/<agent id>/traces` shows the same
    runs in the terminal, and deleting the agent's folder deletes its traces.
    The tab shows what the spans hold: model and tool names, token counts,
    cost, durations and error messages, and in the inspector's Input,
@@ -2535,36 +2679,36 @@ Every stream ends with exactly one `done` or `error`, even a run that stops
 without a result. `usage` has the `run.done` event's usage shape
 (`AgentEventUsage`).
 
-Closing the connection aborts the run. Every run reports to the observe
-daemon the Studio reads (`LOUSHO_OBSERVE_URL`, default
-`http://127.0.0.1:7777`, or `LOUSHO_OBSERVE` when set) as agent
+Closing the connection aborts the run. Every run reports to the collector
+the Studio reads (see [The collector](#the-collector)) as agent
 `playground`, with `lousho.prompt.ref` on the run's root span when
-`promptRef` is given. `LOUSHO_OBSERVE_TOKEN` is sent as the bearer token, for a
-daemon bound beyond loopback. A daemon that is down does not slow or fail the run.
+`promptRef` is given. A bearer token is sent when one is configured, for a
+collector bound beyond loopback. A collector that is down does not slow or
+fail the run.
 
 ## Settings, secrets and deploy wiring
 
 The Settings screen (`#/settings`, the last screen in the nav) and the builder
 drawer's **Settings** tab share three parts: provider API keys
-(OpenAI and Anthropic, stored encrypted under `.lousho/` and never shown
+(OpenAI and Anthropic, stored encrypted under `~/.lousho/studio/` and never shown
 again; each key shows **Set** with its masked last characters, **From
 environment** when only `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` is set, or
 **Not set**), named settings profiles (provider, deploy adapter, hook timeout,
-OpenTelemetry toggle; kept in `.lousho/settings.json`, which holds no
+OpenTelemetry toggle; kept in `~/.lousho/studio/settings.json`, which holds no
 secrets), and a **Deploy** section that picks an adapter (`node-server`,
 `docker` or `cloudflare-worker`) and runs `lousho build` for the selected
 agent. Other providers still read their environment variables, the same way
 `lousho dev`/`lousho build` do (see [Configuration](https://github.com/LinuxDevil/lousho/blob/main/docs/configuration.md)), and
 the `mock` provider needs no credentials.
 
-Stored keys are encrypted with AES-256-GCM in `.lousho/secrets.json`. The
-encryption key is generated on first use and kept next to it in
-`.lousho/secrets.key` (both `0600` on POSIX). This keeps keys out of
+Stored keys are encrypted with AES-256-GCM in `~/.lousho/studio/secrets.json`.
+The encryption key is generated on first use and kept next to it in
+`~/.lousho/studio/secrets.key` (both `0600` on POSIX). This keeps keys out of
 anything that copies the ciphertext alone - a backup, a zip of the project,
 a shared agent YAML - but anyone who can read both files as your user can
-decrypt them. It is not an OS keychain. Keep `.lousho/` out of version
-control and out of shared archives, and prefer environment variables on
-shared machines.
+decrypt them. It is not an OS keychain. Keep `~/.lousho/studio/` out of
+version control and out of shared archives, and prefer environment variables
+on shared machines.
 
 An agent whose provider has no key (no stored key and no environment
 variable) does not run. **Run** and **Chat** fail with
@@ -2576,16 +2720,18 @@ mock agent carries a **MOCK** badge.
 
 ## Dev mode
 
-If you're working inside this SDK's own monorepo (contributing to Agent
-Forge itself, not just using it), `lousho studio` falls back to dev mode
-automatically as long as `apps/agent-forge/dist-server` hasn't been built
-yet:
+Dev mode exists only for people contributing to Studio inside the SDK's own
+monorepo - an installed Studio is always the production bundle (see
+[Production vs. dev mode](#production-vs-dev-mode)). From a checkout of this
+repository, `lousho studio` detects the Studio source and falls back to dev
+mode automatically as long as `apps/agent-forge/dist-server` hasn't been
+built yet:
 
 ```bash
 git clone https://github.com/LinuxDevil/lousho.git
 cd agent-sdk
 npm install
-npx lousho studio --dev   # or just `npx lousho studio` before building
+node bin/lousho.js studio --dev   # or just `node bin/lousho.js studio` before building
 ```
 
 This runs the API server straight from TypeScript (`tsx`) and a real Vite
@@ -2597,7 +2743,7 @@ is pinned to port 5173 and the API server accepts that origin. To build the prod
 ```bash
 npm run build:studio   # builds apps/agent-forge/dist (client) and
                         # apps/agent-forge/dist-server (bundled server)
-npx lousho studio       # now runs in production mode
+node bin/lousho.js studio       # now runs in production mode
 ```
 
 `npm run build:studio` also runs automatically as part of the root
@@ -2741,8 +2887,8 @@ A minimal spec is four fields. This snippet parses one and runs it on the
 built-in `mock` provider, so it works offline with no API key:
 
 ```ts
-import { createMockProvider, LLMProviderRegistry, specV2ToAgent } from 'lousho';
-import { parseAgentSpecV2 } from 'lousho/spec';
+import { createMockProvider, LLMProviderRegistry, specV2ToAgent } from '@linuxdevil/lousho';
+import { parseAgentSpecV2 } from '@linuxdevil/lousho/spec';
 
 // 'mock' is a registered provider name; scripting its reply keeps the output deterministic.
 LLMProviderRegistry.register('mock', () => createMockProvider({ responses: ['Hello!'] }));
@@ -2941,8 +3087,8 @@ for when you want to build the agent yourself. v1's `specToAgent()` stays
 separate: it is synchronous and takes a v1 spec, not v2 data.
 
 ```ts
-import { compileSpec, specV2ToAgent, type SpecHost } from 'lousho';
-import { parseAgentSpecV2 } from 'lousho/spec';
+import { compileSpec, specV2ToAgent, type SpecHost } from '@linuxdevil/lousho';
+import { parseAgentSpecV2 } from '@linuxdevil/lousho/spec';
 
 const host: SpecHost = { baseDir: process.cwd() };
 const spec = parseAgentSpecV2({ version: 2, name: 'Greeter', model: 'mock/greeter', instructions: 'Say hello.' });
@@ -2970,14 +3116,14 @@ and v1's `agentSpecSchema`. Node-only helpers (`specV2ToAgent`,
 stay on the package root.
 
 ```ts
-import { agentSpecV2JsonSchema } from 'lousho/spec';
+import { agentSpecV2JsonSchema } from '@linuxdevil/lousho/spec';
 
 const schema = agentSpecV2JsonSchema(); // the draft-07 JSON Schema of a spec, for forms and editors
 console.log(schema.title); // 'AgentSpec v2'
 ```
 
 ```ts
-import { parseAgentSpecV2, specToCode } from 'lousho/spec';
+import { parseAgentSpecV2, specToCode } from '@linuxdevil/lousho/spec';
 
 const spec = parseAgentSpecV2({ version: 2, name: 'Greeter', model: 'mock/greeter', instructions: 'Say hello.' });
 console.log(specToCode(spec)); // the same spec as a readable createAgent({...}) module
@@ -2992,7 +3138,7 @@ is not re-validated - run it through `parseAgentSpecV2()` or use
 version and always returns a validated `AgentSpecV2`.
 
 ```ts
-import { loadSpecV2, upgradeSpec } from 'lousho';
+import { loadSpecV2, upgradeSpec } from '@linuxdevil/lousho';
 
 const v1 = {
   name: 'support-bot',
@@ -3073,7 +3219,7 @@ The `vendor/` model prefix chooses the provider; with OpenRouter use
 `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent, fromUIMessages, memoryStore, toUIMessageStreamResponse, type UIMessageLike } from 'lousho';
+import { createAgent, fromUIMessages, memoryStore, toUIMessageStreamResponse, type UIMessageLike } from '@linuxdevil/lousho';
 
 // The store must outlive the request: without one, every `agent.session({ id })`
 // gets a fresh in-memory transcript and the next turn would start empty.
@@ -3210,7 +3356,7 @@ kept: a `system` message (or any other role, or an entry that is not a message)
 is dropped, so a caller cannot add instructions to the agent's prompt. Set
 instructions on the agent (`createAgent({ instructions })`), not in the request.
 
-A dedicated `lousho/ai-sdk-ui` subpath may follow; for now the
+A dedicated `@linuxdevil/lousho/ai-sdk-ui` subpath may follow; for now the
 functions come from the package root.
 
 # Approvals
@@ -3227,7 +3373,7 @@ See also: [Pause, restart, resume](https://github.com/LinuxDevil/lousho/blob/mai
 > Snippets on this page leave some names to you: `provider` is any `LLMProvider` (offline: `createMockProvider()`); `agent` is a `createAgent()` result; `input` is the user's text, a `string`; `emailTool` is a tool built with `defineTool()`; `storage` is a `StorageService`; `toolRegistry` is a `ToolRegistry`.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
@@ -3253,7 +3399,7 @@ if (paused.finishReason === 'awaiting-approval') {
 arguments, typed from the tool's zod `input`:
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
@@ -3306,7 +3452,7 @@ error. `allow(tools)`, `deny(tools, reason?)` and `ask(tools)` build the
 common rules.
 
 ```ts
-import { allow, ask, createAgent, defineTool, deny, type PermissionRule } from 'lousho';
+import { allow, ask, createAgent, defineTool, deny, type PermissionRule } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const shell = defineTool({
@@ -3385,7 +3531,7 @@ session, each `send()` is its own transcript. Compacting away that message
 makes the tool ask again.
 
 ```ts
-import { createAgent, defineTool, once } from 'lousho';
+import { createAgent, defineTool, once } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const askOnce = once();
@@ -3451,8 +3597,8 @@ restart, give the agent a durable store, such as the SQLite one (see
 [Choosing a store](https://github.com/LinuxDevil/lousho/blob/main/docs/sessions.md#choosing-a-store)):
 
 ```ts
-import { createAgent } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
+import { createAgent } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
 
 const store = new SqliteStore('./.lousho/agent.db');
 const agent = createAgent({ provider, tools: [emailTool], store }); // or approvalStore: store.approvals
@@ -3486,7 +3632,7 @@ The step's calls that need no approval do not wait: they run when the step
 does, before the pause.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' /* , tools: [payInvoice, archiveThread] */ });
 const paused = await agent.send('Pay the invoice and archive the thread');
@@ -3528,7 +3674,7 @@ decided.
   `approved: false`.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', tools: [emailTool] });
 const support = agent.session({ id: 'support-42' });
@@ -3555,7 +3701,7 @@ approval. There is no option on `resolve()` that ends the run. To stop that:
   model gets the reason and answers:
 
 ```ts
-import { createAgent, type AgentHook } from 'lousho';
+import { createAgent, type AgentHook } from '@linuxdevil/lousho';
 
 const noRefile: AgentHook = {
   name: 'no-refile',
@@ -3586,7 +3732,7 @@ is only on the audit entry (`onPermissionDecision`). An expired pause resolved
 with `approved: true` does not run the tool.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
@@ -3653,7 +3799,7 @@ Its argument's `principal` is whose call it is, and
 tool's `ctx.approval.by` (see [auth](https://github.com/LinuxDevil/lousho/blob/main/docs/auth.md#who-approved)).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const trusted = createAgent({
   provider,
@@ -3671,10 +3817,10 @@ score, a timeout, a model error, arguments too long to judge — defers to a
 human exactly like `'defer'`. It never denies a call on its own.
 
 ```ts
-import { ask, createAgent, createAutoApprove, modelAutoApprover } from 'lousho';
+import { ask, createAgent, createAutoApprove, modelAutoApprover } from '@linuxdevil/lousho';
 
 declare const issueTool: any;
-declare const cheapProvider: import('lousho').LLMProvider;
+declare const cheapProvider: import('@linuxdevil/lousho').LLMProvider;
 
 const agent = createAgent({
   provider,
@@ -3709,11 +3855,11 @@ permissions:
 ```
 
 ```ts
-import { modelAutoApprover, specV2ToAgent } from 'lousho';
+import { modelAutoApprover, specV2ToAgent } from '@linuxdevil/lousho';
 
-declare const spec: import('lousho').AgentSpecV2;
+declare const spec: import('@linuxdevil/lousho').AgentSpecV2;
 declare const baseDir: string;
-declare const cheapProvider: import('lousho').LLMProvider;
+declare const cheapProvider: import('@linuxdevil/lousho').LLMProvider;
 
 const agent = await specV2ToAgent(spec, {
   baseDir,
@@ -3740,7 +3886,7 @@ is what `resolve()` resolves with. A continuation that pauses again ends with
 continues in that session, and `run.done` comes once the transcript is saved.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider, tools: [emailTool] });
 const paused = await agent.send('Email Sam the report');
@@ -3777,7 +3923,7 @@ approval: in sessions, in durable stores and across a restart.
   in tests and scripted agents.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'Plan the trip with the user.', provider, askQuestion: true });
 
@@ -3814,8 +3960,8 @@ tool. Resume later, after a real restart if you like, with
 `resumeAfterApproval()`:
 
 ```ts
-import { AgentExecutor, resumeAfterApproval } from 'lousho/executor';
-import { StorageServiceApprovalStore } from 'lousho/utils';
+import { AgentExecutor, resumeAfterApproval } from '@linuxdevil/lousho/executor';
+import { StorageServiceApprovalStore } from '@linuxdevil/lousho/utils';
 
 const approvalStore = new StorageServiceApprovalStore(storage);
 
@@ -3874,7 +4020,7 @@ only when its namespace binding has `list`, as a real one does).
 Source: docs/auth.md
 
 An agent served over HTTP needs to know two things about each request: may it
-call at all, and who is it. `lousho/auth` answers both. You
+call at all, and who is it. `@linuxdevil/lousho/auth` answers both. You
 give a route an ordered list of auth entries (`jwt()`, `oidc()`, `basic()`,
 `apiToken()`, `anonymous()` or your own function); the first entry that
 accepts the request returns a **principal**, and that principal goes into the
@@ -3882,9 +4028,9 @@ run, where your `model` / `instructions` / `tools` functions and memory scopes
 can read it.
 
 ```ts no-run
-import { createAgent, createRouteHandler } from 'lousho';
-import { apiToken, jwt } from 'lousho/auth';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createRouteHandler } from '@linuxdevil/lousho';
+import { apiToken, jwt } from '@linuxdevil/lousho/auth';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const agent = createAgent({
   provider: mockModel(['Hello!']),
@@ -3956,7 +4102,7 @@ exactly one key source:
 | `jwksUrl` | a JWKS endpoint (https, or http on localhost) | `RS256`, `ES256` by default; RSA and EC keys only |
 
 ```ts
-import { jwt } from 'lousho/auth';
+import { jwt } from '@linuxdevil/lousho/auth';
 
 const fromOurAuthServer = jwt({
   jwksUrl: 'https://auth.example.com/.well-known/jwks.json',
@@ -3996,7 +4142,7 @@ or http on `localhost` / `127.0.0.1` / `[::1]` — the same rule as `jwt()`'s
 `jwksUrl`). Algorithms default to `RS256` and `ES256`; HMAC is not allowed.
 
 ```ts
-import { oidc } from 'lousho/auth';
+import { oidc } from '@linuxdevil/lousho/auth';
 
 const google = oidc({ issuer: 'https://accounts.google.com', audience: process.env.GOOGLE_CLIENT_ID ?? 'client-id' });
 ```
@@ -4012,7 +4158,7 @@ carries `WWW-Authenticate: Basic realm="<realm>", charset="UTF-8"` so browsers
 show their login prompt.
 
 ```ts
-import { basic } from 'lousho/auth';
+import { basic } from '@linuxdevil/lousho/auth';
 
 const operators = basic({ users: { ops: process.env.OPS_PASSWORD! }, realm: 'agent' });
 // Or check against your own store (compare in constant time there):
@@ -4041,7 +4187,7 @@ Any function of the `Request` is an entry. Declare the challenges it answers a
 `401` with, or it advertises `Bearer`:
 
 ```ts
-import { AuthError, type AuthFn } from 'lousho/auth';
+import { AuthError, type AuthFn } from '@linuxdevil/lousho/auth';
 
 const tenantKey: AuthFn = async (request) => {
   const key = request.headers.get('x-tenant-key');
@@ -4101,7 +4247,7 @@ In an [agent directory](https://github.com/LinuxDevil/lousho/blob/main/docs/agen
 
 ```ts no-verify
 // my-agent/auth.ts
-import { apiToken, oidc } from 'lousho/auth';
+import { apiToken, oidc } from '@linuxdevil/lousho/auth';
 
 export default [
   oidc({ issuer: 'https://login.example.com', audience: 'agent-api' }),
@@ -4131,8 +4277,8 @@ The principal is on the run context next to `sessionId` and `metadata`. The
 `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent, defineMemory, inMemoryMemory, type Principal } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineMemory, inMemoryMemory, type Principal } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const notes = defineMemory({
   name: 'notes',
@@ -4216,7 +4362,7 @@ none in any of these places.
 ### In a tool
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 export const myOrders = defineTool({
@@ -4237,8 +4383,8 @@ from the request body or the model, and a tool cannot change it.
 ### Approval policies and permission rules
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const deploy = defineTool({
@@ -4266,8 +4412,8 @@ A decision can name who made it. The approved tool sees the decider as
 `ctx.approval.by`, next to `ctx.approval.note`:
 
 ```ts
-import { createAgent, defineTool, type Principal } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool, type Principal } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
@@ -4337,8 +4483,8 @@ see the example under [Who may decide an approval](#who-may-decide-an-approval))
 caller keeps the check stateless:
 
 ```ts
-import { createAgent, createRouteHandler, memoryStore } from 'lousho';
-import { jwt } from 'lousho/auth';
+import { createAgent, createRouteHandler, memoryStore } from '@linuxdevil/lousho';
+import { jwt } from '@linuxdevil/lousho/auth';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', store: memoryStore() });
 // The user id a session id starts with: everything before its last `-`. A prefix match would let
@@ -4394,7 +4540,7 @@ Behind a reverse proxy:
   rewrites `Host`, list the upstream name the proxy sends, not the public one.
 
 ```ts
-import { createAgent, createRouteHandler } from 'lousho';
+import { createAgent, createRouteHandler } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 
@@ -4424,8 +4570,8 @@ customer can no longer approve their own refund, and a supervisor can read any
 session (to see what they are approving) and decide in it:
 
 ```ts
-import { createAgent, createRouteHandler, memoryStore } from 'lousho';
-import { jwt } from 'lousho/auth';
+import { createAgent, createRouteHandler, memoryStore } from '@linuxdevil/lousho';
+import { jwt } from '@linuxdevil/lousho/auth';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', store: memoryStore() });
 const isSupervisor = (principal?: { claims?: Readonly<Record<string, unknown>> }) => principal?.claims?.role === 'supervisor';
@@ -4447,8 +4593,8 @@ claims, a manager decides them, and nobody approves their own:
 
 ```ts no-verify
 // my-agent/auth.ts
-import { apiToken } from 'lousho/auth';
-import type { ApprovalAccessRequest, SessionAccessRequest } from 'lousho';
+import { apiToken } from '@linuxdevil/lousho/auth';
+import type { ApprovalAccessRequest, SessionAccessRequest } from '@linuxdevil/lousho';
 
 export default [
   apiToken(process.env.ALICE_TOKEN!, { id: 'alice' }),
@@ -4535,7 +4681,7 @@ file system and a shell for it, and `createFsTools()` and `createShellTool()`
 turn it into tools.
 
 ```ts
-import { NodeWorkspace, createFsTools, createShellTool } from 'lousho';
+import { NodeWorkspace, createFsTools, createShellTool } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({ root: process.cwd() });
 const tools = [...createFsTools(workspace), createShellTool(workspace)];
@@ -4560,7 +4706,7 @@ per-tool map. For the shell, pass a predicate over the command string and gate
 only the commands you consider risky.
 
 ```ts
-import { NodeWorkspace, createFsTools, createShellTool } from 'lousho';
+import { NodeWorkspace, createFsTools, createShellTool } from '@linuxdevil/lousho';
 
 const DESTRUCTIVE = /\b(rm|mv|chmod|chown|git\s+(push|reset|clean|checkout))\b|>/;
 
@@ -4592,7 +4738,7 @@ written and `tool.start` announces each tool call (see
 [Streaming](https://github.com/LinuxDevil/lousho/blob/main/docs/streaming.md)).
 
 ```ts
-import { NodeWorkspace, createAgent, createFsTools, createShellTool } from 'lousho';
+import { NodeWorkspace, createAgent, createFsTools, createShellTool } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({ root: process.cwd() });
 const agent = createAgent({
@@ -4629,7 +4775,7 @@ the rest of the work. That run can pause again, so loop until there is no
 
 ```ts
 import { createInterface } from 'node:readline/promises';
-import { createAgent, type AgentRun } from 'lousho';
+import { createAgent, type AgentRun } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You are a coding agent.' });
 const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -4684,7 +4830,7 @@ same pause handling.
 // coding.ts
 // Run: OPENAI_API_KEY=... npx tsx coding.ts "Fix the failing test"
 import { createInterface } from 'node:readline/promises';
-import { NodeWorkspace, createAgent, createFsTools, createShellTool, type AgentRun } from 'lousho';
+import { NodeWorkspace, createAgent, createFsTools, createShellTool, type AgentRun } from '@linuxdevil/lousho';
 
 const DESTRUCTIVE = /\b(rm|mv|chmod|chown|git\s+(push|reset|clean|checkout))\b|>/;
 
@@ -4768,8 +4914,8 @@ memory and takes a scripted `exec` for the shell, and `mockModel` plays the
 model. Assert on `workspace.snapshot()` and `workspace.commands`.
 
 ```ts
-import { createAgent, createFsTools, createShellTool, MemoryWorkspace } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createFsTools, createShellTool, MemoryWorkspace } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const workspace = new MemoryWorkspace({
   files: { 'math.js': 'exports.add = (a, b) => a - b;\n' },
@@ -4796,8 +4942,8 @@ To test the approval path, gate `write_file` the way the real agent does.
 runs the write and finishes the turn.
 
 ```ts
-import { createAgent, createFsTools, MemoryWorkspace } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createFsTools, MemoryWorkspace } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const workspace = new MemoryWorkspace({ files: { 'notes.txt': 'old\n' } });
 const agent = createAgent({
@@ -4876,7 +5022,7 @@ const channels = mountFetchChannels(agent, [slack], { waitUntil: (turn) => void
 
 ```ts no-run
 import * as http from 'node:http';
-import { createAgent, createMockProvider, httpChannel, mountChannels } from 'lousho';
+import { createAgent, createMockProvider, httpChannel, mountChannels } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider() });
 const channels = mountChannels(agent, [
@@ -4951,7 +5097,7 @@ Discord, Telegram, Teams, GitHub) keeps its own answer and tells the user the
 request failed in the conversation.
 
 ```ts
-import { createAgent, defineChannel, mountChannels } from 'lousho';
+import { createAgent, defineChannel, mountChannels } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You answer text messages.', provider });
 
@@ -5035,7 +5181,7 @@ dropped silently once the surface was acknowledged. `resolveApproval()`
 throws `LOUSHO_APPROVAL_CONFLICT` for an approval another request is deciding.
 
 ```ts
-import { createAgent, defineChannel, mountChannels } from 'lousho';
+import { createAgent, defineChannel, mountChannels } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You are helpful.', provider, askQuestion: true });
 
@@ -5080,7 +5226,7 @@ the verified request (the alerting system that sent the hook, an integration
 user); `body` is the parsed JSON body, `undefined` when it is not JSON.
 
 ```ts
-import { createAgent, httpChannel, mountChannels, webhookChannel } from 'lousho';
+import { createAgent, httpChannel, mountChannels, webhookChannel } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You are helpful.', provider });
 
@@ -5173,7 +5319,7 @@ Set up the app at [api.slack.com/apps](https://api.slack.com/apps):
 
 ```ts
 import * as http from 'node:http';
-import { createAgent, mountChannels, slackChannel } from 'lousho';
+import { createAgent, mountChannels, slackChannel } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You are a helpful Slack bot.', provider });
 
@@ -5248,7 +5394,7 @@ curl -X POST "https://discord.com/api/v10/applications/$APP_ID/guilds/$GUILD_ID/
 
 ```ts
 import * as http from 'node:http';
-import { createAgent, discordChannel, mountChannels } from 'lousho';
+import { createAgent, discordChannel, mountChannels } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You are a helpful Discord bot.', provider });
 
@@ -5332,7 +5478,7 @@ curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" -H "Co
 
 ```ts
 import * as http from 'node:http';
-import { createAgent, mountChannels, telegramChannel } from 'lousho';
+import { createAgent, mountChannels, telegramChannel } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You are a helpful Telegram bot.', provider });
 
@@ -5384,7 +5530,7 @@ so it also runs on Workers.
   them somewhere shared and durable, e.g. Redis `SET NX EX`:
 
   ```ts
-  import { githubChannel, type DeliveryStore } from 'lousho';
+  import { githubChannel, type DeliveryStore } from '@linuxdevil/lousho';
 
   const seenIds = new Set<string>(); // stands in for Redis or a database table
   const deliveries: DeliveryStore = { seen: (id) => seenIds.has(id) || (seenIds.add(id), false) };
@@ -5485,7 +5631,7 @@ agent from answering its own comments.
 
 ```ts
 import * as http from 'node:http';
-import { createAgent, githubChannel, mountChannels } from 'lousho';
+import { createAgent, githubChannel, mountChannels } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You answer questions about this repository.', provider });
 
@@ -5581,7 +5727,7 @@ Set up the bot:
 
 ```ts
 import * as http from 'node:http';
-import { createAgent, mountChannels, teamsChannel } from 'lousho';
+import { createAgent, mountChannels, teamsChannel } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You help the team with questions.', provider });
 
@@ -5617,8 +5763,8 @@ into `createAgent()`, so the same directory drives both harnesses. Nothing is
 copied or renamed; Lousho reads the files where they already are.
 
 ```ts no-run
-import { createAgent, claudeProject } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, claudeProject } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const provider = mockModel([{ text: 'ok' }]);
 
@@ -5675,8 +5821,8 @@ task-shaped notes, hooks can pause on `scratchpad` writes like any tool.
 ## Options
 
 ```ts no-run
-import { claudeProject } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { claudeProject } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const provider = mockModel([{ text: 'ok' }]);
 
@@ -5709,10 +5855,10 @@ touching `.claude/`. See the option in [Configuration](https://github.com/LinuxD
 
 Source: docs/cli.md
 
-Installing the package also installs the `lousho` command. It scaffolds
+Installing the package also installs the `@linuxdevil/lousho` command. It scaffolds
 projects, checks your setup, runs an agent locally, serves it over MCP, runs
-evals, shows saved traces, builds a deployable artifact and launches the Agent Forge dashboard.
-Run it with `npx lousho <command>` inside a project that has the SDK installed.
+evals, shows saved traces, builds a deployable artifact and opens Lousho Studio.
+Run it with `npx @linuxdevil/lousho <command>` inside a project that has the SDK installed.
 
 | Command | What it does | Details |
 | ------- | ------------ | ------- |
@@ -5726,7 +5872,10 @@ Run it with `npx lousho <command>` inside a project that has the SDK installed.
 | `lousho eval [globs...]` | Run `*.eval.ts` files under vitest; print a summary and write JUnit/JSON reports. | [Evals](https://github.com/LinuxDevil/lousho/blob/main/docs/evals.md#lousho-eval) |
 | `lousho traces [id]` | List the recent runs saved by `fileTraceExporter()` (duration, model and tool calls, tokens, cost), or print one run as a span tree. | [Observability](https://github.com/LinuxDevil/lousho/blob/main/docs/observability.md#local-traces) |
 | `lousho build --target=<t> --agent=<spec>` | Build a deployable Node server, Docker image or Cloudflare Worker. | [Deployment](https://github.com/LinuxDevil/lousho/blob/main/docs/deployment.md) |
-| `lousho studio` | Launch Agent Forge, the visual dashboard, on one local port. | [Agent Forge](https://github.com/LinuxDevil/lousho/blob/main/docs/agent-forge.md) |
+| `lousho studio` | Open Lousho Studio (the separate `@linuxdevil/studio` package) on this project. | [Lousho Studio](https://github.com/LinuxDevil/lousho/blob/main/docs/agent-forge.md) |
+| `lousho bridge` | Speak Studio's bridge protocol on stdio; started by Studio, not run by hand. | [Below](#lousho-bridge) |
+| `lousho workspace <init\|ls\|show\|validate\|run>` | Create, inspect, validate and run a workspace from a folder or a running service. | [Workspaces](https://github.com/LinuxDevil/lousho/blob/main/docs/workspaces.md) |
+| `lousho observe <sub>` | Run the local collector every agent reports to when `LOUSHO_OBSERVE` is set: `start`, `status`, `stop`, `rebuild-rollups`, `prune`, `export`, `failures`, `score`, `token`. | [Below](#lousho-observe) |
 | `lousho improve <path> --check <module>` | Experimental. Run one self-healing cycle on an agent directory: propose edits to its instructions and skills from failed runs in your local observe database, gate them, replay them on fresh runs, and apply (auto mode, the default) or queue (manual mode) one that passes. `--watch` keeps it running; `pause`, `status`, `rollback`, `approve` and the other subcommands manage it. `--dry-run` prints the review card and applies nothing. | [Below](#lousho-improve) |
 
 Every command that takes a `<spec>` reads an agent spec file (`.yaml`,
@@ -5741,7 +5890,9 @@ lousho chat <spec.yaml|spec.json|agent-dir|agent.ts> [--model provider/model] [-
 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|agent.ts> --target=<node-server|cloudflare-worker|docker> [--out=<dir>]    (or --agent=<path>)
-lousho studio [--port N] [--host H] [--prod|--dev]
+lousho studio [--port N] [--host H]
+lousho bridge
+lousho workspace <init|ls|show|validate|run> [args] [--source <dir> | --service <url>]
 lousho mcp <agent.yaml|json|agent-dir|agent.ts> [--http --port N --host H]
 lousho doctor [agent.yaml|json|agent-dir|agent.ts] [--json] [--ping]
 lousho eval [globs...] [--tag t] [--junit path] [--json path] [--strict] [--judge] [--record | --replay | --drift [--drift-usage]] [--url <base> [--token <bearer>]] [--config vitest.config.ts] [--timeout <ms>]
@@ -5785,18 +5936,18 @@ not the shared `LOUSHO_CONFIG_INVALID` path. The only short flags besides
 instead of the generated one; globs then narrow that config's files as vitest
 filters.
 
-`npm create lousho my-agent` runs `lousho init` with the same arguments.
+`npm create @linuxdevil/lousho my-agent` runs `lousho init` with the same arguments.
 To scaffold against an unreleased build of the SDK, pass `--sdk-path` (see
 [Installing from a local build](https://github.com/LinuxDevil/lousho/blob/main/docs/installation.md#installing-from-a-local-build)).
 
 ## `lousho dev`
 
 ```bash
-npx lousho dev agent.yaml                  # a spec file
-npx lousho dev ./my-agent                  # an agent directory
-npx lousho dev src/agent.ts                # a TypeScript (or JavaScript) module
-npx lousho dev agent.yaml --port 4000 --host 0.0.0.0
-npx lousho dev ./my-agent --no-schedules   # do not fire cron schedules or a spec's cron triggers
+npx @linuxdevil/lousho dev agent.yaml                  # a spec file
+npx @linuxdevil/lousho dev ./my-agent                  # an agent directory
+npx @linuxdevil/lousho dev src/agent.ts                # a TypeScript (or JavaScript) module
+npx @linuxdevil/lousho dev agent.yaml --port 4000 --host 0.0.0.0
+npx @linuxdevil/lousho dev ./my-agent --no-schedules   # do not fire cron schedules or a spec's cron triggers
 ```
 
 For an agent directory, `channels/` are mounted under `/channels` and
@@ -5835,7 +5986,7 @@ plus a free-text field. The same endpoints work from `curl` or your own page:
 
 `--traces` (or `--traces=<dir>`) writes every run to local trace files with
 `fileTraceExporter()`, in `.lousho/traces` unless you name a directory, so
-`npx lousho traces` shows what the agent did. It is off by default because the
+`npx @linuxdevil/lousho traces` shows what the agent did. It is off by default because the
 files hold prompt, tool argument and tool result content, and the flag prints
 the directory it writes to. It applies to spec files, agent directories and
 modules alike (a module's own `exporter` is replaced while the flag is set).
@@ -5898,9 +6049,9 @@ Directories and modules are your code and run with your permissions; only run
 ## `lousho chat`
 
 ```bash
-npx lousho chat agent.yaml                          # a spec file
-npx lousho chat ./my-agent --model openai/gpt-4o    # an agent directory, on another model
-npx lousho chat src/agent.ts --store sqlite:.lousho/chat.db --session support
+npx @linuxdevil/lousho chat agent.yaml                          # a spec file
+npx @linuxdevil/lousho chat ./my-agent --model openai/gpt-4o    # an agent directory, on another model
+npx @linuxdevil/lousho chat src/agent.ts --store sqlite:.lousho/chat.db --session support
 ```
 
 A terminal REPL: each line you type is one turn of a session. `<path>` is
@@ -5959,9 +6110,9 @@ scripted lines and a `mockModel` agent and no terminal.
 ## `lousho build`
 
 ```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)
+npx @linuxdevil/lousho build --target=node-server --agent=agent.yaml        # or docker / cloudflare-worker
+npx @linuxdevil/lousho build ./my-agent --target=node-server                # an agent directory (node-server, docker)
+npx @linuxdevil/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
@@ -5972,31 +6123,45 @@ Workers limits are in [Deployment](https://github.com/LinuxDevil/lousho/blob/mai
 ## `lousho studio`
 
 ```bash
-npx lousho studio            # prints http://127.0.0.1:4750/?token=<per-launch token>
-npx lousho studio --port 5000
+npx @linuxdevil/lousho studio            # prints http://127.0.0.1:4750/?token=<per-launch token>
+npx @linuxdevil/lousho studio --port 5000
 ```
 
-Starts one local server for the Agent Forge API and UI. Agents and run state
-are stored under `.lousho/` in the current directory. The app has a left
-navigation: Agents (the builder) and Playground, then Traces, Threads and
-Monitoring, Evaluations (Scores, Datasets, Evaluators, Annotation queues),
-Prompts, Context Hub and Settings; everything past the Playground reads the
-`lousho observe` daemon. See [Agent Forge](https://github.com/LinuxDevil/lousho/blob/main/docs/agent-forge.md) for the screens
+Opens Lousho Studio on this project. Studio is a separate package
+(`@linuxdevil/studio`): install it with `npm i -g @linuxdevil/studio` (or run
+`npx @linuxdevil/studio`); this command finds it and opens the current folder
+as a workspace. When no Studio is installed it prints
+`Studio is a separate install: npx @linuxdevil/studio` and exits.
+
+Options: `--port N` and `--host H` pass through to Studio (defaults 4750 and
+`127.0.0.1`). `--prod` and `--dev` only apply inside the SDK's own repository
+checkout. See [Lousho Studio](https://github.com/LinuxDevil/lousho/blob/main/docs/agent-forge.md) for workspaces, the screens
 and the walkthrough.
 
+## `lousho bridge`
+
+```bash
+lousho bridge
+```
+
+Speaks Studio's bridge protocol (NDJSON) on stdin/stdout so Studio can build
+and run agents with this project's own SDK. Studio starts it for each
+workspace that has `@linuxdevil/lousho` installed; you do not run it
+yourself.
+
 ## `lousho observe`
 
 ```bash
-npx lousho observe start                        # collector on http://127.0.0.1:7777
-npx lousho observe status                       # health + fleet counts
-npx lousho observe stop                         # <db>.pid + SIGTERM (checks the daemon serves --db)
-npx lousho observe rebuild-rollups              # recompute insight aggregates
-npx lousho observe prune --older-than 30d       # delete finished runs older than 30 days, then VACUUM
-npx lousho observe export --since 7d --out runs.jsonl # traces as JSONL, one per line
-npx lousho observe failures --since 7d          # recurring tool and model failures, by agent
-npx lousho observe failures --traces .lousho/traces --json # the same from trace files, no database
-npx lousho observe score --agent support        # continuous score, pass rate and trajectory gate state
-npx lousho observe token create --project myapp # bearer key for non-loopback auth
+npx @linuxdevil/lousho observe start                        # collector on http://127.0.0.1:7777
+npx @linuxdevil/lousho observe status                       # health + fleet counts
+npx @linuxdevil/lousho observe stop                         # <db>.pid + SIGTERM (checks the daemon serves --db)
+npx @linuxdevil/lousho observe rebuild-rollups              # recompute insight aggregates
+npx @linuxdevil/lousho observe prune --older-than 30d       # delete finished runs older than 30 days, then VACUUM
+npx @linuxdevil/lousho observe export --since 7d --out runs.jsonl # traces as JSONL, one per line
+npx @linuxdevil/lousho observe failures --since 7d          # recurring tool and model failures, by agent
+npx @linuxdevil/lousho observe failures --traces .lousho/traces --json # the same from trace files, no database
+npx @linuxdevil/lousho observe score --agent support        # continuous score, pass rate and trajectory gate state
+npx @linuxdevil/lousho observe token create --project myapp # bearer key for non-loopback auth
 ```
 
 Runs the local collector every agent reports to when `LOUSHO_OBSERVE` is
@@ -6047,11 +6212,11 @@ no daemon needs to be running. See [Export](https://github.com/LinuxDevil/lousho
 ## `lousho prompt`
 
 ```bash
-npx lousho prompt push prompt.md --name mira    # publishes a new version
-npx lousho prompt list
-npx lousho prompt get mira@latest
-npx lousho prompt label mira prod 3             # mira@prod -> 3 (was 2)
-npx lousho prompt get mira@prod
+npx @linuxdevil/lousho prompt push prompt.md --name mira    # publishes a new version
+npx @linuxdevil/lousho prompt list
+npx @linuxdevil/lousho prompt get mira@latest
+npx @linuxdevil/lousho prompt label mira prod 3             # mira@prod -> 3 (was 2)
+npx @linuxdevil/lousho prompt get mira@prod
 ```
 
 Publishes and reads prompt versions in the observe daemon's registry. Agents
@@ -6075,7 +6240,7 @@ resolve them with `createAgent({ prompt: 'mira@latest' })` (or a label,
 Experimental, like the [`improveAgent()`](https://github.com/LinuxDevil/lousho/blob/main/docs/improve.md) it runs.
 
 ```bash
-npx lousho improve ./my-agent --check ./check.mjs --since 7d --out proposal.md
+npx @linuxdevil/lousho improve ./my-agent --check ./check.mjs --since 7d --out proposal.md
 ```
 
 ```js
@@ -6174,9 +6339,9 @@ under `.lousho/revisions/` and recorded in the hash-chained
 `.lousho/audit.jsonl`. Three subcommands read and undo that history:
 
 ```bash
-npx lousho improve revisions ./my-agent
-npx lousho improve rollback ./my-agent --by ali --reason "answers got worse"
-npx lousho improve audit ./my-agent --verify
+npx @linuxdevil/lousho improve revisions ./my-agent
+npx @linuxdevil/lousho improve rollback ./my-agent --by ali --reason "answers got worse"
+npx @linuxdevil/lousho improve audit ./my-agent --verify
 ```
 
 - `revisions <dir> [--json]` lists the saved revisions, newest first, with their
@@ -6206,9 +6371,9 @@ In manual mode a proposal that passed the gate waits in
 `.lousho/proposals/<id>.json` until a person decides:
 
 ```bash
-npx lousho improve pending ./my-agent
-npx lousho improve approve ./my-agent 3f9c0a1b2d4e --by ali --check ./check.mjs
-npx lousho improve reject ./my-agent 3f9c0a1b2d4e --by ali --reason "too broad"
+npx @linuxdevil/lousho improve pending ./my-agent
+npx @linuxdevil/lousho improve approve ./my-agent 3f9c0a1b2d4e --by ali --check ./check.mjs
+npx @linuxdevil/lousho improve reject ./my-agent 3f9c0a1b2d4e --by ali --reason "too broad"
 ```
 
 - `pending <dir> [--show <id>] [--json]` lists the queue, newest first, marking
@@ -6245,9 +6410,9 @@ npx lousho improve reject ./my-agent 3f9c0a1b2d4e --by ali --reason "too broad"
 `--watch` keeps the loop running on an agent directory:
 
 ```bash
-npx lousho improve ./my-agent --check ./check.mjs --watch --interval 15m
-npx lousho improve pause ./my-agent --reason "release freeze" --by ali
-npx lousho improve resume ./my-agent --by ali
+npx @linuxdevil/lousho improve ./my-agent --check ./check.mjs --watch --interval 15m
+npx @linuxdevil/lousho improve pause ./my-agent --reason "release freeze" --by ali
+npx @linuxdevil/lousho improve resume ./my-agent --by ali
 ```
 
 Each tick checks the kill switch (`.lousho/improve.stop`, `LOUSHO_IMPROVE=off`
@@ -6309,7 +6474,7 @@ to real sessions, instead of being written.
 
 Source: docs/cloudflare-workers.md
 
-`npx lousho build --target=cloudflare-worker --agent=agent.yaml` generates a module Worker (`worker.ts`), a `wrangler.toml` and a bundle, `dist/worker.js`, that the build checks for `node:` imports. It needs `tsup` and `wrangler` installed, and it takes an [agent spec file](https://github.com/LinuxDevil/lousho/blob/main/docs/configuration.md) or an [agent directory](https://github.com/LinuxDevil/lousho/blob/main/docs/agent-directories.md) (`npx lousho build ./my-agent --target=cloudflare-worker`). The Worker serves the same [HTTP API](https://github.com/LinuxDevil/lousho/blob/main/docs/deployment.md#http-api) as the other targets. This target has the tightest limits of the three, so they come first.
+`npx @linuxdevil/lousho build --target=cloudflare-worker --agent=agent.yaml` generates a module Worker (`worker.ts`), a `wrangler.toml` and a bundle, `dist/worker.js`, that the build checks for `node:` imports. It needs `tsup` and `wrangler` installed, and it takes an [agent spec file](https://github.com/LinuxDevil/lousho/blob/main/docs/configuration.md) or an [agent directory](https://github.com/LinuxDevil/lousho/blob/main/docs/agent-directories.md) (`npx @linuxdevil/lousho build ./my-agent --target=cloudflare-worker`). The Worker serves the same [HTTP API](https://github.com/LinuxDevil/lousho/blob/main/docs/deployment.md#http-api) as the other targets. This target has the tightest limits of the three, so they come first.
 
 ## What works and what does not
 
@@ -6319,7 +6484,7 @@ Source: docs/cloudflare-workers.md
 | [Agent directories](https://github.com/LinuxDevil/lousho/blob/main/docs/agent-directories.md) | yes: config, `instructions.md`, `tools/`, `skills/`, `subagents/`, `schedules/` (Worker cron rules), `channels/` (mounted under `/channels`), `memory/` (`kvMemory()`, or `inMemoryMemory()` per isolate) and `projectInstructions` (embedded at build time) | yes, all of it |
 | Providers | `mock`, `openai`, `anthropic`, `openrouter` | `mock`, `openai`, `anthropic`, `ollama`, `openrouter` |
 | Built-in tools | `current-date`, `day-name`, `http` (listed host names only, from the `LOUSHO_HTTP_ALLOW` binding) | all, including `http` and `web-fetch` |
-| Tools written in TypeScript | yes, in an agent directory: no Node builtins, and from `lousho` only the names listed under [Agent directories on a Worker](#build-and-deploy) | yes, in an agent directory |
+| Tools written in TypeScript | yes, in an agent directory: no Node builtins, and from `@linuxdevil/lousho` only the names listed under [Agent directories on a Worker](#build-and-deploy) | yes, in an agent directory |
 | Sandboxed tool execution | no (the build swaps the sandbox for a shim that fails when used) | yes |
 | MCP servers over stdio | no (the child process cannot start; the shim fails when used) | yes |
 | [Code mode](https://github.com/LinuxDevil/lousho/blob/main/docs/code-mode.md) (`codeMode`) | no (the build swaps QuickJS for a shim that fails the run at its start) | yes |
@@ -6412,7 +6577,7 @@ Worker builds the agent with the same rules as `resolveAgentDir()` (config
 keys, tool exports, duplicate tool names):
 
 ```bash
-npx lousho build ./my-agent --target=cloudflare-worker
+npx @linuxdevil/lousho build ./my-agent --target=cloudflare-worker
 cd .lousho/build/cloudflare-worker && npx wrangler deploy
 ```
 
@@ -6518,8 +6683,8 @@ binding typed as `KVBinding` (the `get`/`put`/`delete` part of Cloudflare's
 from the `/worker` subpath - see [Writing your own Worker](#writing-your-own-worker):
 
 ```ts
-import { createAgent } from 'lousho/worker';
-import { KVStore, type KVBinding } from 'lousho/kv';
+import { createAgent } from '@linuxdevil/lousho/worker';
+import { KVStore, type KVBinding } from '@linuxdevil/lousho/kv';
 
 interface Env {
   AGENT_KV: KVBinding;
@@ -6582,7 +6747,7 @@ new call, which gets a new approval id, so a tool that must act once per
 invoice also needs a key from its own arguments (the invoice number here):
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 // `payments` stands in for your payment client.
@@ -6624,7 +6789,7 @@ day-of-week (`LOUSHO_SCHEDULE_INVALID`).
 
 In a Worker you write yourself, wire an agent defined in code with
 `handleScheduled(agent, schedules, controller, ctx)` (exported from
-`lousho/worker` — the `lousho/deploy-runtime-worker`
+`@linuxdevil/lousho/worker` — the `@linuxdevil/lousho/deploy-runtime-worker`
 specifier in the generated code is a virtual one that only `lousho build`'s
 bundler resolves; do not import it yourself). It runs the schedules whose
 `cron` equals `controller.cron` inside `ctx.waitUntil()` and never throws; list
@@ -6633,9 +6798,9 @@ the same expressions under `[triggers] crons` yourself. Give the agent a store
 isolate's memory and is gone when it is recycled:
 
 ```ts
-import { createAgent, createMockProvider, defineSchedule, handleScheduled } from 'lousho/worker';
-import type { ScheduledContext, ScheduledController } from 'lousho/worker';
-import { KVStore, type KVBinding } from 'lousho/kv';
+import { createAgent, createMockProvider, defineSchedule, handleScheduled } from '@linuxdevil/lousho/worker';
+import type { ScheduledContext, ScheduledController } from '@linuxdevil/lousho/worker';
+import { KVStore, type KVBinding } from '@linuxdevil/lousho/kv';
 
 interface Env {
   AGENT_CHECKPOINTS: KVBinding;
@@ -6657,7 +6822,7 @@ export default {
 
 ## Writing your own Worker
 
-Import from `lousho/worker`, not the package root. The root entry
+Import from `@linuxdevil/lousho/worker`, not the package root. The root entry
 also exports file stores, the agent-directory loader, MCP over stdio, sandboxes
 and other Node-only modules, so bundling it for `platform: 'browser'` fails with
 `Could not resolve "async_hooks"` and friends. `/worker` is `createAgent` plus the
@@ -6669,8 +6834,8 @@ import {
   createAgent, createMockProvider, defineSchedule, defineTool, handleScheduled,
   memoryStore, serveFetch, OpenAIProvider, AnthropicProvider, OpenRouterProvider,
   LLMProviderRegistry, SDKError, /* ... */
-} from 'lousho/worker';
-import { KVStore } from 'lousho/kv'; // also re-exported from /worker
+} from '@linuxdevil/lousho/worker';
+import { KVStore } from '@linuxdevil/lousho/kv'; // also re-exported from /worker
 ```
 
 The exports: `createAgent` (and its config types), `memoryStore`, the KV stores
@@ -6743,8 +6908,8 @@ read-modify-write is not atomic.
 ## Bundle size and Node builtins
 
 The KV-backed stores (`KVStore`, `KVCheckpointStore` and `CHECKPOINT_KV_BINDING`,
-exported from `lousho/kv`) have no `node:*` references anywhere
-in their dependency graph, and neither does the `lousho/worker`
+exported from `@linuxdevil/lousho/kv`) have no `node:*` references anywhere
+in their dependency graph, and neither does the `@linuxdevil/lousho/worker`
 entry a hand-written Worker bundles (its build is checked the same way; see
 [Writing your own Worker](#writing-your-own-worker)). The Worker runs the spec as a `createAgent()` agent, whose
 Node-only imports (project instructions, the file session store, guardrail
@@ -6800,7 +6965,7 @@ npm install quickjs-emscripten@^0.32.0
 ```
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const prices: Record<string, number> = { apple: 1.2, pear: 0.8, plum: 2 };
@@ -7006,7 +7171,7 @@ OpenRouter use `openrouter/<vendor>/<model>` (e.g.
 `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const simple = createAgent({ model: 'openai/gpt-4o', compaction: true });
 
@@ -7072,7 +7237,7 @@ listeners (`createAgent({ onEvent })`, `onAgentEvent`) or is streamed.
 a cheap summarizer model:
 
 ```ts
-import { createAgent, createCompactionHook, twoPhaseStrategy } from 'lousho';
+import { createAgent, createCompactionHook, twoPhaseStrategy } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   provider,
@@ -7145,7 +7310,7 @@ model's loaded context length (`loaded_context_length` from
 prints the model's default).
 
 ```ts
-import { createAgent, registerModel } from 'lousho';
+import { createAgent, registerModel } from '@linuxdevil/lousho';
 
 // Either on the agent...
 const agent = createAgent({
@@ -7171,8 +7336,8 @@ Registering the hook in a `HookRegistry` is for code that calls the executor
 directly (see [the executor API](https://github.com/LinuxDevil/lousho/blob/main/docs/executor-api.md)):
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { HookRegistry, createCompactionHook, twoPhaseStrategy } from 'lousho';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { HookRegistry, createCompactionHook, twoPhaseStrategy } from '@linuxdevil/lousho';
 
 const hooks = new HookRegistry();
 hooks.register(
@@ -7258,7 +7423,7 @@ message; a pinned tool result keeps its whole assistant turn. Pin what the
 agent must always see in full, such as the task statement or a key document:
 
 ```ts
-import { pinMessage, isPinned, type Message } from 'lousho';
+import { pinMessage, isPinned, type Message } from '@linuxdevil/lousho';
 
 const messages: Message[] = [
   { role: 'system', content: 'You are a research assistant.' },
@@ -7276,7 +7441,7 @@ of the conversation, and resolves to a new array (its input is not modified).
 Use it to shrink a stored transcript before you continue it:
 
 ```ts
-import { compactMessages, summarizeStrategy, type Message } from 'lousho';
+import { compactMessages, summarizeStrategy, type Message } from '@linuxdevil/lousho';
 
 declare const history: Message[];
 
@@ -7310,8 +7475,8 @@ durable turn is unfinished. Listeners added with `session.on()` get
 checkpoint and checkpoint history, and emits `context.cleared`.
 
 ```ts
-import { createAgent, twoPhaseStrategy } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, twoPhaseStrategy } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const agent = createAgent({ provider: mockModel(['ok']) });
 const session = agent.session({ compaction: { strategy: twoPhaseStrategy({ model: 'openai/gpt-4o-mini' }) } });
@@ -7336,7 +7501,7 @@ unchanged when there is nothing to do: the hook then leaves the run alone and
 does not call `onCompaction`.
 
 ```ts
-import { createCompactionHook, isPinned, type CompactionStrategy } from 'lousho';
+import { createCompactionHook, isPinned, type CompactionStrategy } from '@linuxdevil/lousho';
 
 // Keep the system prompt, pinned messages and the last 20 messages.
 const keepRecent: CompactionStrategy = {
@@ -7589,7 +7754,7 @@ mcpServers:
 ```
 
 ```ts
-import { agentSpecSchema, specToAgent, type McpServerSpec } from 'lousho';
+import { agentSpecSchema, specToAgent, type McpServerSpec } from '@linuxdevil/lousho';
 
 const filesystem: McpServerSpec = { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem'] };
 const spec = agentSpecSchema.parse({
@@ -7632,7 +7797,7 @@ other models. The `vendor/` model prefix chooses the provider; with OpenRouter
 use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -7674,7 +7839,7 @@ To build the same thing by hand, or for providers you construct yourself,
 anywhere a provider is accepted:
 
 ```ts
-import { createAgent, resolveProvider, withFallback, withRetry } from 'lousho';
+import { createAgent, resolveProvider, withFallback, withRetry } from '@linuxdevil/lousho';
 
 const provider = withFallback(
   [
@@ -7745,7 +7910,7 @@ flow waves and eval suites cannot burst unbounded model calls. Every limit is
 optional:
 
 ```ts
-import { withRateLimit, resolveProvider } from 'lousho';
+import { withRateLimit, resolveProvider } from '@linuxdevil/lousho';
 
 const provider = withRateLimit(resolveProvider('openai/gpt-4o-mini'), {
   requestsPerMinute: 60, // calls started per rolling minute
@@ -7775,7 +7940,7 @@ its own provider is queued too). Give several agents the same
 `createRateLimiter()` to share it across them.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const researcher = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You research.', description: 'Finds sources' });
 createAgent({ model: 'openai/gpt-4o-mini', subagents: { researcher }, rateLimit: { maxConcurrent: 2 } });
@@ -7854,7 +8019,7 @@ A `send()` or `stream()` call can pass its own, which win key by key over the
 agent's:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -7889,7 +8054,7 @@ Besides `modelSettings`, a `send()` or `stream()` call can set its own
 instructions for that run:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You triage support tickets.' });
 await agent.send('Summarize the ticket.', { maxSteps: 2, instructions: 'Answer in French.' });
@@ -7907,7 +8072,7 @@ keeps `model` / `provider` and `instructions` / `prompt` mutually exclusive,
 so TypeScript rejects spreading it next to a literal that sets one of them.
 
 ```ts
-import { createAgent, type CreateAgentBase } from 'lousho';
+import { createAgent, type CreateAgentBase } from '@linuxdevil/lousho';
 
 const shared: CreateAgentBase = { maxSteps: 8, modelSettings: { temperature: 0 } };
 
@@ -7966,7 +8131,7 @@ with a checkpoint store it is checkpointed as finished, like `'max-steps'`.
 (`LOUSHO_BUDGET_EXCEEDED`, with the same `budget`) instead.
 
 ```ts
-import { BudgetExceededError, createAgent } from 'lousho';
+import { BudgetExceededError, createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   provider,
@@ -7995,7 +8160,7 @@ continued from its store keeps its budget. Both apply together; the first limit
 reached stops the turn. A turn that was aborted is not counted.
 
 ```ts
-import { createAgent, memoryStore } from 'lousho';
+import { createAgent, memoryStore } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider, store: memoryStore(), limits: { maxTokens: 20_000 } });
 const session = agent.session({ id: 'user-42', limits: { maxCostUsd: 1 } });
@@ -8009,7 +8174,7 @@ Many repositories keep guidance for coding agents in an `AGENTS.md` (or
 `CLAUDE.md`) file. `createAgent` can append it to the agent's instructions:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   instructions: 'You review pull requests.',
@@ -8051,7 +8216,7 @@ connector is an **MCP server**: add it to `mcpServers` and its tools join the
 agent's registry namespaced as `<server>__<tool>`.
 
 ```ts no-run
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openrouter/openai/gpt-4o-mini',
@@ -8092,8 +8257,8 @@ into the SDK's approval gate: a `slack.post_message` pauses the run until
 approved, `docs.get_document` does not. Tune it per server:
 
 ```ts no-run
-import { createAgent } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const provider = mockModel([{ text: 'ok' }]);
 
@@ -8135,7 +8300,7 @@ Source: docs/decisions.md
 Public beta: `gpt-6-luna` is the only model the endpoint serves, and the surface may still change. The endpoint is not part of chat completions, so it does not go through `createAgent()` providers or OpenRouter — it needs `OPENAI_API_KEY` (or `apiKey`/`baseURL` for a compatible endpoint).
 
 ```ts
-import { decide } from 'lousho';
+import { decide } from '@linuxdevil/lousho';
 
 const { answers } = await decide({
   input: 'I was charged twice for my order.',
@@ -8162,7 +8327,7 @@ if (route.type === 'choice' && route.confidence >= 0.7) {
 ## Question types
 
 ```ts no-run
-import { decide, type DecisionQuestion } from 'lousho';
+import { decide, type DecisionQuestion } from '@linuxdevil/lousho';
 
 const questions: DecisionQuestion[] = [
   // predicate: probability 0-1 that a condition holds
@@ -8199,7 +8364,7 @@ const questions: DecisionQuestion[] = [
 Independent questions share one `input` and one request:
 
 ```ts no-run
-import { decide, type DecisionQuestion } from 'lousho';
+import { decide, type DecisionQuestion } from '@linuxdevil/lousho';
 
 const questions: DecisionQuestion[] = [
   { type: 'predicate', name: 'is_spam', instructions: 'Is this spam?' },
@@ -8221,7 +8386,7 @@ const byName = Object.fromEntries(answers.map((a) => [a.name, a]));
 ## Options
 
 ```ts no-run
-import { decide } from 'lousho';
+import { decide } from '@linuxdevil/lousho';
 
 const result = await decide({
   input: '...',
@@ -8251,7 +8416,7 @@ Source: docs/deployment.md
 into a deployable artifact for one target platform:
 
 ```bash
-npx lousho build --target=<target> --agent=agent.yaml [--out=<dir>]
+npx @linuxdevil/lousho build --target=<target> --agent=agent.yaml [--out=<dir>]
 ```
 
 It runs the target's adapter through three steps - **scaffold** (write the
@@ -8277,7 +8442,7 @@ All three targets also take an [agent directory](https://github.com/LinuxDevil/l
 in place of a spec file (the path may be positional or `--agent`):
 
 ```bash
-npx lousho build ./my-agent --target=node-server
+npx @linuxdevil/lousho build ./my-agent --target=node-server
 node .lousho/build/node-server/dist/server.js
 ```
 
@@ -8288,7 +8453,7 @@ directory's [schedules](https://github.com/LinuxDevil/lousho/blob/main/docs/sche
 routes keep the bearer token), and logs `schedules: ...; channels: ...`.
 The directory's code files are pre-bundled with the build's tsup step into
 `dist/agent/**.js` (one ESM build sharing one copy of the SDK, so a `from
-'lousho'` import in a tool is the SDK the server runs), and
+'@linuxdevil/lousho'` import in a tool is the SDK the server runs), and
 only the files the server reads as data are copied: `instructions.md`,
 `instructions/`, `skills/`, a JSON/YAML config, and the same in each
 `subagents/<name>/`. Nothing else in the directory reaches `dist/`: not `.env`
@@ -8309,7 +8474,7 @@ only a Worker-safe part of `lousho`
 ([Cloudflare Workers](https://github.com/LinuxDevil/lousho/blob/main/docs/cloudflare-workers.md#build-and-deploy) has the details):
 
 ```bash
-npx lousho build ./my-agent --target=cloudflare-worker
+npx @linuxdevil/lousho build ./my-agent --target=cloudflare-worker
 ```
 
 ## Agent modules
@@ -8320,7 +8485,7 @@ 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
+npx @linuxdevil/lousho build src/agent.ts --target=node-server
 node .lousho/build/node-server/dist/server.js
 ```
 
@@ -8538,7 +8703,7 @@ signal handler: stop accepting, let the requests in flight finish, then call
 
 ```ts
 import { createServer } from 'node:http';
-import { createAgent, mountChannels } from 'lousho';
+import { createAgent, mountChannels } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 const handler = mountChannels(agent, []);
@@ -8642,8 +8807,8 @@ and any `ApprovalStore` work the same way.
 See also: [Pause, restart, resume](https://github.com/LinuxDevil/lousho/blob/main/docs/pause-and-resume.md), a short end-to-end tutorial.
 
 ```ts
-import { createAgent } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
+import { createAgent } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
 
 const agent = createAgent({ provider, store: new SqliteStore('./.lousho/jobs.db') });
 
@@ -8736,7 +8901,7 @@ session (the session already has its system prompt). To end a session and
 start over under the same id, call `store.checkpoints.delete(sessionId)`.
 
 ```ts
-import { createAgent, memoryStore, SessionAwaitingApprovalError } from 'lousho';
+import { createAgent, memoryStore, SessionAwaitingApprovalError } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider, store: memoryStore() });
 
@@ -8768,7 +8933,7 @@ underneath):
 3. calls the model once every call of the turn has exactly one result.
 
 ```ts
-import { createAgent, memoryStore } from 'lousho';
+import { createAgent, memoryStore } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider, store: memoryStore() });
 
@@ -8792,7 +8957,7 @@ finishes it. `agent.pending()` lists those runs across every session and
 `send(msg, { sessionId })` id, so a restarted process can find them:
 
 ```ts
-import { createAgent, fileStore } from 'lousho';
+import { createAgent, fileStore } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider, store: fileStore('./.lousho') });
 
@@ -8857,8 +9022,8 @@ without durable writes) is listed as `'in-progress'` with `lastError.code`
 to the code that serves traffic:
 
 ```ts
-import { createAgent, defineTool, memoryStore, PropagatingToolError } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool, memoryStore, PropagatingToolError } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 let charges = 0;
@@ -9068,7 +9233,7 @@ model calls). To run a job once, derive the `sessionId` from the delivery id
 and look at the checkpoint before sending:
 
 ```ts
-import { createAgent, memoryStore } from 'lousho';
+import { createAgent, memoryStore } from '@linuxdevil/lousho';
 
 const store = memoryStore();
 const agent = createAgent({ provider, store });
@@ -9106,7 +9271,7 @@ same call is re-run on resume) is passed to `execute`, so it works as an
 idempotency key against a re-run of one call:
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 declare const payments: { charge(amount: number, opts: { idempotencyKey: string }): Promise<{ id: string }> };
@@ -9142,7 +9307,7 @@ one invoice) needs an idempotency key from your own data, such as the claim id
 in the arguments, checked or passed on to the system you write to:
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 declare const claims: { file(claim: { claimId: string }, opts: { idempotencyKey: string }): Promise<{ id: string }> };
@@ -9172,14 +9337,14 @@ Which stores keep one:
 | `SqliteStore` | yes (`checkpoint_history` table) | `new SqliteStore(path, { historyLimit })` |
 | `LocalStorageCheckpointStore` | yes | `new LocalStorageCheckpointStore(storage, { historyLimit })` |
 | `fileStore(dir)` (JSON files) | yes (`checkpoint-history/<id>.json`) | `fileStore(dir, { historyLimit })` |
-| `KVCheckpointStore` / `KVStore` (Cloudflare Workers KV, from `lousho/kv`) | yes (see below) | `new KVStore(kv, { historyLimit })` |
+| `KVCheckpointStore` / `KVStore` (Cloudflare Workers KV, from `@linuxdevil/lousho/kv`) | yes (see below) | `new KVStore(kv, { historyLimit })` |
 | Agent Forge's `FileCheckpointStore` | yes | `new FileCheckpointStore(dir, { historyLimit })` |
 | a custom `CheckpointStore` | only if it implements `history()` | - |
 
 For example, with the in-memory store:
 
 ```ts
-import { getCheckpointHistory, memoryStore } from 'lousho';
+import { getCheckpointHistory, memoryStore } from '@linuxdevil/lousho';
 
 const { checkpoints } = memoryStore({ historyLimit: 20 }); // default 50, 0 keeps none
 // new SqliteStore(path, { historyLimit }), new LocalStorageCheckpointStore(storage, { historyLimit })
@@ -9234,7 +9399,7 @@ saves the result as the `'in-progress'` checkpoint of the new session over
 fork like any unfinished run with `agent.resume(fork.sessionId)`:
 
 ```ts
-import { createAgent, compareTrajectories, memoryStore } from 'lousho';
+import { createAgent, compareTrajectories, memoryStore } from '@linuxdevil/lousho';
 
 const store = memoryStore();
 const assistant = createAgent({ provider, store });
@@ -9315,8 +9480,8 @@ it and it has no result yet, or the human approved it) always rejects with
 whatever the option.
 
 ```ts
-import { createAgent, memoryStore } from 'lousho';
-import type { LLMProvider } from 'lousho';
+import { createAgent, memoryStore } from '@linuxdevil/lousho';
+import type { LLMProvider } from '@linuxdevil/lousho';
 
 declare const provider: LLMProvider;
 
@@ -9357,8 +9522,8 @@ call it corresponds to.
 `agent.send(message, { sessionId })`:
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { LocalStorageCheckpointStore } from 'lousho/utils';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { LocalStorageCheckpointStore } from '@linuxdevil/lousho/utils';
 
 const checkpoints = new LocalStorageCheckpointStore(storage);
 
@@ -9372,8 +9537,8 @@ await AgentExecutor.execute({ agent, input: 'Make it 3 people', provider, sessio
 It throws `SessionAwaitingApprovalError` on a paused session, as `send()` does:
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { SessionAwaitingApprovalError, memoryStore } from 'lousho';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { SessionAwaitingApprovalError, memoryStore } from '@linuxdevil/lousho';
 
 const { checkpoints } = memoryStore();
 
@@ -9390,7 +9555,7 @@ The exported `resumeAfterApproval()` function is what
 `agent.approvals.resolve()` calls:
 
 ```ts
-import { AgentExecutor, resumeAfterApproval } from 'lousho/executor';
+import { AgentExecutor, resumeAfterApproval } from '@linuxdevil/lousho/executor';
 
 const paused = await AgentExecutor.execute({
   agent, input, provider, toolRegistry, approvalStore, sessionId: 'chat-42', checkpointStore,
@@ -9414,8 +9579,8 @@ if (paused.finishReason === 'awaiting-approval') {
 fork's `sessionId` is `agent.resume(fork.sessionId)`:
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { compareTrajectories, memoryStore } from 'lousho';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { compareTrajectories, memoryStore } from '@linuxdevil/lousho';
 
 const { checkpoints } = memoryStore();
 await AgentExecutor.execute({ agent, provider, toolRegistry, input: 'Plan my trip', sessionId: 'trip', checkpointStore: checkpoints });
@@ -9510,7 +9675,7 @@ serialising the error is unchanged). It is absent when the run failed before
 it started.
 
 ```ts
-import { createAgent, type RunUsage } from 'lousho';
+import { createAgent, type RunUsage } from '@linuxdevil/lousho';
 
 try {
   await createAgent({ provider }).send('Go');
@@ -9531,7 +9696,7 @@ on purpose: `PropagatingToolError` and its subclasses (a tool throws one to
 stop the run), `WorkspaceError` (a workspace operation refused or failed -
 the model sees it as a tool error), `McpToolError` (a loaded MCP tool whose
 server reports `isError`; also a tool error), `AuthError` (an
-`lousho/auth` entry rejects the request with its 401 or 403),
+`@linuxdevil/lousho/auth` entry rejects the request with its 401 or 403),
 `CronExpressionError` (`parseCronExpression()`, which
 `defineSchedule()` wraps as `LOUSHO_SCHEDULE_INVALID`) and
 `DecryptionError` (`EncryptionUtils`, `DTOEncryptionFilter`).
@@ -9542,7 +9707,7 @@ server reports `isError`; also a tool error), `AuthError` (an
 and `.cassette` / `.callNumber` fields.
 
 ```ts
-import { createAgent, SDKError } from 'lousho';
+import { createAgent, SDKError } from '@linuxdevil/lousho';
 
 try {
   await createAgent({ provider, instructions: 'Be brief.' }).send('hi');
@@ -9879,7 +10044,7 @@ where the agent is being built.
 agent spec has no field for.
 
 **Fix:** build the agent with `createAgent()` and pass the configured tool, e.g.
-`createGitHubTools(config)` from `lousho/integrations`.
+`createGitHubTools(config)` from `@linuxdevil/lousho/integrations`.
 
 **Example:** `tools: [github]` in a spec.
 
@@ -10736,7 +10901,7 @@ dataset and add examples to it (`POST /api/v1/datasets`, `POST
 **Means:** a record/replay cassette is missing, is not valid JSON or does not
 match the recorded request. The message names the file. A mismatch inside a
 run reaches `send()` as the `CassetteMismatchError` itself (from
-`lousho/testing`, with `.cassette` and `.callNumber`) - it is
+`@linuxdevil/lousho/testing`, with `.cassette` and `.callNumber`) - it is
 a test-fixture failure, so it is never compacted into a
 `CompactedLLMProviderError`.
 
@@ -11039,7 +11204,7 @@ keep reaching the run that holds the id.
 
 ### LOUSHO_AUTH_CONFIG_INVALID
 
-**Means:** a route auth helper from `lousho/auth` (`jwt()`,
+**Means:** a route auth helper from `@linuxdevil/lousho/auth` (`jwt()`,
 `oidc()`, `basic()`, `apiToken()`) got options it cannot verify with, and
 refused them when it was created, not at the first request. The message names
 the option: no key source or two of them, an HMAC `secret` shorter than 32
@@ -11206,7 +11371,7 @@ prints a summary and writes JUnit and JSON reports.
 
 ```bash
 npm install --save-dev vitest
-npx lousho eval
+npx @linuxdevil/lousho eval
 ```
 
 ## Writing a trajectory eval
@@ -11220,8 +11385,8 @@ for the [judge evals](#judge-evals) below.
 ```ts no-run
 // refund.eval.ts
 import { z } from 'zod';
-import { createAgent, defineEval, defineTool, includes } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineEval, defineTool, includes } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const lookupOrder = defineTool({
   name: 'lookup_order',
@@ -11303,7 +11468,7 @@ it. Pass `{ subagent: 'researcher' }` to look at one sub-agent (and the
 sub-agents under it) only:
 
 ```ts
-import { createAgent, defineEval } from 'lousho';
+import { createAgent, defineEval } from '@linuxdevil/lousho';
 
 const researcher = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You research.', description: 'Finds sources' });
 const agent = createAgent({ model: 'openai/gpt-4o-mini', subagents: { researcher } });
@@ -11333,7 +11498,7 @@ case `n` times; the case passes when all `n` runs pass, or when at least
 `passAt: k` of them do:
 
 ```ts
-import { createAgent, defineEval } from 'lousho';
+import { createAgent, defineEval } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You handle refunds.' });
 
@@ -11359,8 +11524,8 @@ any object; its `label` (or `name`, or its `input`) names it.
 
 ```ts no-run
 import { z } from 'zod';
-import { createAgent, defineEval, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineEval, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const lookupOrder = defineTool({
   name: 'lookup_order',
@@ -11412,7 +11577,7 @@ curl -X POST "$LOUSHO_OBSERVE/api/v1/datasets/refunds/examples" -H 'content-type
 ```
 
 ```ts no-run
-import { createAgent, defineEval, includes } from 'lousho';
+import { createAgent, defineEval, includes } from '@linuxdevil/lousho';
 
 defineEval({
   name: 'refunds',
@@ -11450,8 +11615,8 @@ it.
 
 ```ts no-run
 // tone.judge.eval.ts: run with `lousho eval --judge`
-import { createAgent, defineEval, atLeast } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineEval, atLeast } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 defineEval({
   name: 'tone',
@@ -11530,7 +11695,7 @@ model. `--timeout ms` sets the limit for every case (`0` turns it off). With
 One eval can set its own limit, which wins over both:
 
 ```ts
-import { createAgent, defineEval } from 'lousho';
+import { createAgent, defineEval } from '@linuxdevil/lousho';
 
 defineEval({
   name: 'research report',
@@ -11571,7 +11736,7 @@ jobs:
       - uses: actions/setup-node@v4
         with: { node-version: 22 }
       - run: npm ci
-      - run: npx lousho eval --junit reports/evals.xml --json reports/evals.json
+      - run: npx @linuxdevil/lousho eval --junit reports/evals.xml --json reports/evals.json
       - uses: actions/upload-artifact@v4
         if: always()
         with:
@@ -11612,9 +11777,9 @@ between: it records each case once against the real provider through
 Your eval files do not change.
 
 ```bash
-npx lousho eval --record        # real provider: writes the cassettes, commit them
-npx lousho eval --replay        # every case from its cassette, no network, no key
-npx lousho eval --drift         # re-record and diff each case's trajectory
+npx @linuxdevil/lousho eval --record        # real provider: writes the cassettes, commit them
+npx @linuxdevil/lousho eval --replay        # every case from its cassette, no network, no key
+npx @linuxdevil/lousho eval --drift         # re-record and diff each case's trajectory
 ```
 
 - **`--record`** runs every case with its agent's real provider and writes one
@@ -11667,7 +11832,7 @@ a real judge only in `*.judge.eval.ts` files.
 How it works: the run loop sends every model call (`generate` or `stream`, from
 a plain run, a streamed run, a sub-agent or an approval resume) through one
 provider-interception seam, `setProviderInterceptor()` (exported from
-`lousho/testing`; `src/providers/interception.ts` in the
+`@linuxdevil/lousho/testing`; `src/providers/interception.ts` in the
 source). Nothing is installed by default, so the seam is
 free. While a case runs under one of these modes, `lousho eval` answers it with
 the provider wrapped by `recordReplay()` for that case's cassette. You can use
@@ -11685,7 +11850,7 @@ The same eval file that gates CI in-process can smoke-test a deployed agent (the
 URL and every case runs against the deployment instead of the in-process agent:
 
 ```bash
-npx lousho eval --url https://agent.example.com --token "$DEPLOY_TOKEN"   # or LOUSHO_EVAL_TOKEN
+npx @linuxdevil/lousho eval --url https://agent.example.com --token "$DEPLOY_TOKEN"   # or LOUSHO_EVAL_TOKEN
 ```
 
 Each case gets its own remote session (`POST /chat { sessionId, input }`, one
@@ -11711,7 +11876,7 @@ and tools the behaviour you want to check.
 In code, pass a `target` (this overrides `agent`; `--url` overrides both):
 
 ```ts
-import { defineEval, remoteTarget } from 'lousho';
+import { defineEval, remoteTarget } from '@linuxdevil/lousho';
 
 defineEval({
   name: 'deployed refund flow',
@@ -11746,8 +11911,8 @@ take: `temperature` and `maxTokens` (`exporter`, `captureContent` and
 import {
   AgentBuilder,
   AgentExecutor,
-} from 'lousho/executor';
-import { createMockProvider } from 'lousho';
+} from '@linuxdevil/lousho/executor';
+import { createMockProvider } from '@linuxdevil/lousho';
 
 const agent = AgentBuilder.create()
   .setName('Customer Support Agent')
@@ -11813,8 +11978,8 @@ Describe the graph with `FlowBuilder` and run it with the static
 `FlowExecutor.execute(flow, context, onEvent?)`.
 
 ```ts
-import { FlowBuilder, FlowExecutor, type EditorStep } from 'lousho/flows';
-import { resolveProvider, type AgentConfig } from 'lousho';
+import { FlowBuilder, FlowExecutor, type EditorStep } from '@linuxdevil/lousho/flows';
+import { resolveProvider, type AgentConfig } from '@linuxdevil/lousho';
 
 // A flow calls an LLMProvider directly (reads OPENAI_API_KEY).
 const provider = resolveProvider('openai/gpt-4o-mini');
@@ -11916,7 +12081,7 @@ its tool runs:
   never run unapproved.
 
 ```ts
-import { FlowExecutor, type AgentFlow } from 'lousho/flows';
+import { FlowExecutor, type AgentFlow } from '@linuxdevil/lousho/flows';
 
 declare const flow: AgentFlow;
 
@@ -11941,7 +12106,7 @@ set stays as before: `'{{missing}}'` is `''`, and `'$USD'` (no variable
 named `USD`) is the literal string `'$USD'`.
 
 ```ts
-import type { EditorStep } from 'lousho/flows';
+import type { EditorStep } from '@linuxdevil/lousho/flows';
 
 // With variables { count: 5, tags: ['a', 'b'] }, the tool gets { count: 5, tags: ['a', 'b'], note: 'count: 5' }.
 const step: EditorStep = {
@@ -11963,7 +12128,7 @@ once it is aborted, no further step starts and the flow fails with the signal's
 to the model request, and a `toolCall` hands it to the tool as `ctx.abortSignal`.
 
 ```ts
-import { FlowExecutor, type AgentFlow } from 'lousho/flows';
+import { FlowExecutor, type AgentFlow } from '@linuxdevil/lousho/flows';
 
 declare const flow: AgentFlow;
 
@@ -12021,7 +12186,7 @@ Invalid values (`maxAttempts` < 1 or not an integer, a negative `backoffMs`,
 a `timeoutMs` <= 0) fail the step with `LOUSHO_FLOW_INVALID`.
 
 ```ts
-import type { EditorStep } from 'lousho/flows';
+import type { EditorStep } from '@linuxdevil/lousho/flows';
 
 const fetchInvoice: EditorStep = {
   type: 'toolCall',
@@ -12055,8 +12220,8 @@ from the saved variables. `result.usage` and `result.steps` include the
 earlier attempts.
 
 ```ts
-import { FlowExecutor, type AgentFlow } from 'lousho/flows';
-import { memoryStore } from 'lousho';
+import { FlowExecutor, type AgentFlow } from '@linuxdevil/lousho/flows';
+import { memoryStore } from '@linuxdevil/lousho';
 
 declare const flow: AgentFlow;
 const checkpointStore = memoryStore().checkpoints;
@@ -12125,8 +12290,8 @@ are cancelled. Steps they completed are kept, and the rest run again on resume.
 To continue, pass the decision to `resume()`:
 
 ```ts
-import { FlowExecutor, type AgentFlow } from 'lousho/flows';
-import { memoryStore } from 'lousho';
+import { FlowExecutor, type AgentFlow } from '@linuxdevil/lousho/flows';
+import { memoryStore } from '@linuxdevil/lousho';
 
 declare const flow: AgentFlow;
 const checkpointStore = memoryStore().checkpoints;
@@ -12173,7 +12338,7 @@ asked, and the context's `approve` callback decides, exactly as for a
 node's `id`, or its place in the flow).
 
 ```ts
-import type { EditorStep } from 'lousho/flows';
+import type { EditorStep } from '@linuxdevil/lousho/flows';
 
 const steps: EditorStep = {
   type: 'sequence',
@@ -12194,7 +12359,7 @@ const steps: EditorStep = {
   the decision:
 
 ```ts no-run
-import { FlowExecutor, type AgentFlow } from 'lousho/flows';
+import { FlowExecutor, type AgentFlow } from '@linuxdevil/lousho/flows';
 
 declare const flow: AgentFlow;
 
@@ -12218,8 +12383,8 @@ An `agent` step calls a `createAgent()` agent registered in the context's
 guardrails and approvals — and the step stores its reply text:
 
 ```ts
-import { createAgent } from 'lousho';
-import { FlowExecutor, type AgentFlow } from 'lousho/flows';
+import { createAgent } from '@linuxdevil/lousho';
+import { FlowExecutor, type AgentFlow } from '@linuxdevil/lousho/flows';
 
 const writer = createAgent({ name: 'writer', model: 'openai/gpt-4o-mini', instructions: 'Draft a reply.' });
 
@@ -12264,9 +12429,9 @@ typed value rather than text:
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
-import { FlowExecutor, type AgentFlow } from 'lousho/flows';
-import { ToolRegistry } from 'lousho/tools';
+import { createAgent } from '@linuxdevil/lousho';
+import { FlowExecutor, type AgentFlow } from '@linuxdevil/lousho/flows';
+import { ToolRegistry } from '@linuxdevil/lousho/tools';
 
 const researcher = createAgent({ name: 'researcher', model: 'openai/gpt-4o-mini', instructions: 'Answer with three facts.' });
 
@@ -13165,7 +13330,7 @@ OpenRouter use `openrouter/<vendor>/<model>` (e.g.
 `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent, moderationGuardrail, piiGuardrail } from 'lousho';
+import { createAgent, moderationGuardrail, piiGuardrail } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   provider,
@@ -13205,7 +13370,7 @@ import {
   maxLengthGuardrail,
   regexGuardrail,
   type IoGuardrail,
-} from 'lousho';
+} from '@linuxdevil/lousho';
 
 const noProdWrites: IoGuardrail = {
   name: 'no-prod-writes',
@@ -13251,7 +13416,7 @@ try {
 The last four are a starter set for checks most production agents need:
 
 ```ts
-import { createAgent, piiGuardrail, promptInjectionGuardrail, secretsGuardrail } from 'lousho';
+import { createAgent, piiGuardrail, promptInjectionGuardrail, secretsGuardrail } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   provider,
@@ -13299,7 +13464,7 @@ proposed patch and rolls the results up into one verdict. The
 agent's patch before a pull request is opened:
 
 ```ts
-import { runPatchChecks, secretScanCheck, createDiffSizeCheck, createCommandCheck } from 'lousho';
+import { runPatchChecks, secretScanCheck, createDiffSizeCheck, createCommandCheck } from '@linuxdevil/lousho';
 
 const verdict = await runPatchChecks(
   { diff: patch },
@@ -13339,8 +13504,8 @@ function. The executor then calls `sandboxExecute` with the run's
 #### Advanced: the executor API
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { SubprocessSandbox } from 'lousho';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { SubprocessSandbox } from '@linuxdevil/lousho';
 
 // Route a flagged tool (requiresSandbox + sandboxExecute) through a real,
 // Docker-backed sandbox instead of the in-process NoopSandbox default
@@ -13390,7 +13555,7 @@ description to decide when to hand off), then pass them to the triage agent as
 use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const lookupCharges = defineTool({
@@ -13441,7 +13606,7 @@ name with one of the agent's tools.
 Wrap a target in `handoff()` to configure it:
 
 ```ts
-import { createAgent, handoff, handoffFilters } from 'lousho';
+import { createAgent, handoff, handoffFilters } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const refunds = createAgent({ name: 'refunds', description: 'Issues refunds', model: 'openai/gpt-4o-mini' });
@@ -13493,7 +13658,7 @@ the middle of a conversation. Two filters are built in:
 - `handoffFilters.lastUserMessage`: keeps only the last user message.
 
 ```ts
-import { handoffFilters, type HandoffInputData } from 'lousho';
+import { handoffFilters, type HandoffInputData } from '@linuxdevil/lousho';
 
 // The last four messages, without tool traffic.
 const recent = (data: HandoffInputData) => handoffFilters.removeToolCalls(data).slice(-4);
@@ -13540,7 +13705,7 @@ In a session the active agent is the one the transcript last handed off to
 `session.send()` / `session.stream()` runs that agent:
 
 ```ts no-run
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const billing = createAgent({ name: 'billing', description: 'Handles charges and refunds', model: 'openai/gpt-4o-mini' });
 const triage = createAgent({ name: 'triage', model: 'openai/gpt-4o-mini', handoffs: [billing] });
@@ -13558,7 +13723,7 @@ its targets, give the target an array and add the lead to it afterwards (the
 array is read at every run):
 
 ```ts
-import { createAgent, handoff, type Handoff } from 'lousho';
+import { createAgent, handoff, type Handoff } from '@linuxdevil/lousho';
 
 const billingHandoffs: Handoff[] = [];
 const billing = createAgent({
@@ -13608,7 +13773,7 @@ A handoff is reported between the handoff call's `tool.start` / `tool.done`
 and the target's first `step.start`:
 
 ```ts no-run
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const billing = createAgent({ name: 'billing', description: 'Handles charges and refunds', model: 'openai/gpt-4o-mini' });
 const triage = createAgent({ name: 'triage', model: 'openai/gpt-4o-mini', handoffs: [billing] });
@@ -13656,8 +13821,8 @@ Hooks are code you write, not policy and not a human decision: for rules that al
 Pass hooks to `createAgent({ hooks })`. This one logs every tool call and what it returned:
 
 ```ts
-import { createAgent, defineTool, type AgentHook } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool, type AgentHook } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const auditHook: AgentHook = {
@@ -13728,8 +13893,8 @@ that throws still rejects the run, as before. Sub-agents inherit the lead
 agent's hooks and their outcomes.
 
 ```ts
-import { createAgent, type AgentHook } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, type AgentHook } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const provider = mockModel(['Done.']);
 
@@ -13771,8 +13936,8 @@ getting anywhere. It's off unless you add it:
   `LOUSHO_RUN_NO_PROGRESS`, which `agent.recover()` won't retry.
 
 ```ts
-import { createAgent, createProgressGuard, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createProgressGuard, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const lookup = defineTool({
@@ -13810,8 +13975,8 @@ sees it as `outputCheckFailed` on the result and can fix the output. The check
 is your code, so make it independent of what the model wrote.
 
 ```ts
-import { createAgent, createOutputCheck, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createOutputCheck, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const files = new Map<string, string>();
@@ -13841,8 +14006,8 @@ await agent.send('Write the report');
 ### Deny a tool by name
 
 ```ts
-import { createAgent, defineTool, type AgentHook } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool, type AgentHook } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const shell = defineTool({
@@ -13874,8 +14039,8 @@ console.log(result.text);
 Return `{ input }` to run the tool with different arguments. They are validated against the tool's schema again.
 
 ```ts
-import { createAgent, defineTool, type AgentHook } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool, type AgentHook } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const search = defineTool({
@@ -13908,8 +14073,8 @@ await agent.send('Search for hooks');
 `postToolCall` receives the settled result and may return `{ result }` to replace what the model sees. The tool itself ran unchanged.
 
 ```ts
-import { createAgent, defineTool, type AgentHook } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool, type AgentHook } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const readLog = defineTool({
@@ -13943,8 +14108,8 @@ console.log(toolMessage?.role); // 'tool': its content is the redacted text
 `preGenerate` sees the live `ctx.messages` and `ctx.request`. Push a message to add context, or change a request field.
 
 ```ts
-import { createAgent, type AgentHook } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, type AgentHook } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const addDate: AgentHook = {
   name: 'add-date',
@@ -13982,7 +14147,7 @@ refused with a tool error instead of running. See [Approvals](https://github.com
 `createAgent({ hooks })` takes a plain array. Code that uses the executor API ([The executor API](https://github.com/LinuxDevil/lousho/blob/main/docs/executor-api.md)) passes a `HookRegistry`: an ordered collection with `register`, `registerMany`, `get`, `has`, `list`, `unregister`, `clear` and `size()` — `size` is a method (`hooks.size()`), not a `Map`-style property. Registering a second hook with the same `name` replaces the first and logs a warning.
 
 ```ts
-import { HookRegistry, type AgentHook } from 'lousho/hooks';
+import { HookRegistry, type AgentHook } from '@linuxdevil/lousho/hooks';
 
 const redactPii: AgentHook = {
   name: 'redact-pii',
@@ -13996,7 +14161,7 @@ hooks.register(redactPii);
 console.log(hooks.list().map((hook) => hook.name)); // [ 'redact-pii' ]
 ```
 
-`HookRegistry`, `AgentHook` and the context types are available from the package root and from the `lousho/hooks` subpath. Hooks authored in the Agent Forge canvas editor are compiled into a `HookRegistry` and run sandboxed rather than in the host process: see [Agent Forge](https://github.com/LinuxDevil/lousho/blob/main/docs/agent-forge.md#hooks).
+`HookRegistry`, `AgentHook` and the context types are available from the package root and from the `@linuxdevil/lousho/hooks` subpath. Hooks authored in the Agent Forge canvas editor are compiled into a `HookRegistry` and run sandboxed rather than in the host process: see [Agent Forge](https://github.com/LinuxDevil/lousho/blob/main/docs/agent-forge.md#hooks).
 
 # Hosted provider tools
 
@@ -14008,7 +14173,7 @@ web search, code interpreter and file search are the common ones. Put them in
 each call in its events, keeps it on the transcript and counts it in usage.
 
 ```ts
-import { createAgent, webSearch, defineTool } from 'lousho';
+import { createAgent, webSearch, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const saveNote = defineTool({
@@ -14111,7 +14276,7 @@ providers and with any AI SDK model wrapped by
 [`fromAiSdk()`](https://github.com/LinuxDevil/lousho/blob/main/docs/providers.md#any-ai-sdk-model-fromaisdk):
 
 ```ts no-verify
-import { createAgent, fromAiSdk, hostedTool } from 'lousho';
+import { createAgent, fromAiSdk, hostedTool } from '@linuxdevil/lousho';
 import { openai } from '@ai-sdk/openai';
 
 const agent = createAgent({
@@ -14128,7 +14293,7 @@ A hosted call is reported like a tool call, with `executedBy: 'provider'` on
 `tool.start`, `tool.done` and `tool.error`:
 
 ```ts
-import { createAgent, webSearch } from 'lousho';
+import { createAgent, webSearch } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', tools: [webSearch()] });
 
@@ -14182,7 +14347,7 @@ without a human, leave the tool out of `tools`, or choose tools per run with a
 function:
 
 ```ts
-import { createAgent, webSearch } from 'lousho';
+import { createAgent, webSearch } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -14219,8 +14384,8 @@ hosted tools; a resuming agent with a different set reports
 request, so an agent with hosted tools runs offline:
 
 ```ts
-import { createAgent, webSearch } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, webSearch } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const model = mockModel([
   {
@@ -14320,9 +14485,9 @@ It's experimental: its results so far come from a small benchmark.
 For how this fits with recovering failed runs while the agent serves traffic, see [Self-healing and self-improvement](https://github.com/LinuxDevil/lousho/blob/main/docs/self-healing.md).
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { formatImproveResult, improveAgent, renderTranscript, type Harness } from 'lousho/improve';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { formatImproveResult, improveAgent, renderTranscript, type Harness } from '@linuxdevil/lousho/improve';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const search = defineTool({
@@ -14506,7 +14671,7 @@ files.
 your own function, keep its `cached` field so the run is counted as cached.
 
 ```ts
-import { cachedProbe, improveAgent, type Harness, type ImproveOptions } from 'lousho/improve';
+import { cachedProbe, improveAgent, type Harness, type ImproveOptions } from '@linuxdevil/lousho/improve';
 
 declare const harness: Harness;
 declare const probe: ImproveOptions['probe'];
@@ -14589,7 +14754,7 @@ gate changes: it judges the harness, not the reasons.
 A `CaseCheck` returns `true`, `false`, `null` when it can't score the answer, or `{ passed, failure }`. Return `failure` on a failed answer to name the check it missed, as a custom `probe` does: each editor reads it in that run's record, after `Result: failed`, on one line with forged untrusted markers removed. A check must be synchronous; any other return value throws a `ConfigurationError`. Without it, a failed run whose answer looks right gives the editors nothing to fix. Name the real check; a wrong name is worse than none. A `failure` on a passed answer is dropped.
 
 ```ts
-import type { CaseCheck } from 'lousho/improve';
+import type { CaseCheck } from '@linuxdevil/lousho/improve';
 
 declare function failedTests(input: string, answer: string): string[];
 
@@ -14604,7 +14769,7 @@ const check: CaseCheck = (input, answer) => {
 With `retryWithDiagnosis`, [`agent.recover()`](https://github.com/LinuxDevil/lousho/blob/main/docs/self-healing.md#recover-a-run-now) forks a run that kept failing into a `<id>.heal` session told why it failed. When that fork passes, you hold a pair on the same input: the failed run and a retry that passed. `casesFromRecoveries(db, filter)` finds those pairs in your local database and returns the failed runs as cases, each with a `recovery`: the retry's transcript, rendered with `renderTranscript`, the diagnosis it was given, and its final answer. A fork counts only when it carries the diagnosis and finished with no recorded error, no answer cut short and no low score. That isn't your check, so score each `recovery.answer` with your `CaseCheck` and keep only the ones that pass, then pass them on as `recoveries`:
 
 ```ts
-import { casesFromRecoveries, improveAgent, type CaseCheck, type Harness, type ImproveOptions, type SqlDatabase } from 'lousho/improve';
+import { casesFromRecoveries, improveAgent, type CaseCheck, type Harness, type ImproveOptions, type SqlDatabase } from '@linuxdevil/lousho/improve';
 
 declare const db: SqlDatabase;
 declare const harness: Harness;
@@ -14639,7 +14804,7 @@ A library keeps lessons from earlier attempts, so later editors can read them. E
 `libraryFiles(dir, domain)` returns up to 20 active lessons as files under `context/library/`, highest-voted first, then newest. Each file is labelled as data with the lesson between untrusted markers, and you pass them to `improveAgent` as `library`. Entries are checked again when read, so an entry file edited by hand that no longer passes is skipped. `voteEntry(dir, id, 'helped' | 'hurt')` counts an outcome, and retires a lesson for good once its hurt votes outnumber its helped votes by two. Votes are appended to `votes.jsonl` next to the entries, so votes cast at once aren't lost. `improveAgent` accepts only files shaped like `libraryFiles` output, named `context/library/<name>.md`.
 
 ```ts
-import { improveAgent, libraryFiles, libraryHome, type Harness, type ImproveOptions } from 'lousho/improve';
+import { improveAgent, libraryFiles, libraryHome, type Harness, type ImproveOptions } from '@linuxdevil/lousho/improve';
 
 declare const harness: Harness;
 declare const probe: ImproveOptions['probe'];
@@ -14655,7 +14820,7 @@ const result = await improveAgent({ harness, cases: ['stuck'], probe, editor: {
 Once a cycle is decided, `reflect` turns it into at most one lesson. A cycle is decided when its edit was kept, rejected, or applied and then rolled back. A rejected or rolled-back edit teaches as much as a kept one. The reflection session reads four files and nothing else: the review card, the diff, the case verdicts and the outcome. It never sees a raw transcript, and the text that models wrote reaches it between untrusted markers. It replies with an `<experience>` block (cue, lesson, evidence, confidence) or `NO_ENTRY`, and the lesson goes through `addEntry` with the cycle's failed checks, so a refused lesson is reported and never stored. `reflect` never throws. A failure comes back as `error` for you to record, and `tokens` is what it spent, to count toward the cycle's budget, which `maxTokens` caps.
 
 ```ts
-import { libraryHome, reflect, voteOnOutcome, type ImproveResult } from 'lousho/improve';
+import { libraryHome, reflect, voteOnOutcome, type ImproveResult } from '@linuxdevil/lousho/improve';
 
 declare const result: ImproveResult;
 
@@ -14679,7 +14844,7 @@ The session never sees a held-out case's id: each held-out case appears as `held
 `settleCanary` reads the trial; call it yourself on a timer when you don't use the watcher. After `sessions` candidate sessions it promotes when the share of flagged sessions is 0 or at least 0.05 below the base's rate over its last 20 runs, and no failure class appeared that the base didn't have. It retires early once a promotion is ruled out, and when the directory changed, the loop is paused, the opt-in is removed or `monitor.giveUpDays` pass. A promote goes through `applyProposal`, which checks the proposal again. A canary started in auto mode is queued for a person instead when `improve.json` has since switched to manual. In manual mode, `startCanary` refuses without `approvedBy`, and a canary without an approver serves no one.
 
 ```ts
-import { loadImproveSettings, settleCanary, startCanary, type Harness, type ImproveResult, type SqlDatabase } from 'lousho/improve';
+import { loadImproveSettings, settleCanary, startCanary, type Harness, type ImproveResult, type SqlDatabase } from '@linuxdevil/lousho/improve';
 
 declare const db: SqlDatabase;
 declare const result: ImproveResult;
@@ -14762,7 +14927,7 @@ See [The monitor](#the-monitor).
 under a harness; `lousho improve` builds it for you.
 
 ```ts
-import { healOnce, loadImproveSettings, type CaseCheck, type HealOptions, type SqlDatabase } from 'lousho/improve';
+import { healOnce, loadImproveSettings, type CaseCheck, type HealOptions, type SqlDatabase } from '@linuxdevil/lousho/improve';
 
 declare const db: SqlDatabase;
 declare const check: CaseCheck;
@@ -14884,7 +15049,7 @@ tick as a [schedule](https://github.com/LinuxDevil/lousho/blob/main/docs/schedul
 `schedules/`:
 
 ```ts
-import { improveSchedule, loadImproveSettings, watchAgent, type CaseCheck, type HealOptions, type SqlDatabase } from 'lousho/improve';
+import { improveSchedule, loadImproveSettings, watchAgent, type CaseCheck, type HealOptions, type SqlDatabase } from '@linuxdevil/lousho/improve';
 
 declare const db: SqlDatabase;
 declare const check: CaseCheck;
@@ -15199,7 +15364,7 @@ Source: docs/mcp.md
 
 MCP works in two directions. Your agent can call the tools of MCP servers, or
 your agent can be an MCP server that Claude Code, Cursor and other MCP clients
-call. Both live in the `lousho/mcp` subpath, and
+call. Both live in the `@linuxdevil/lousho/mcp` subpath, and
 `@modelcontextprotocol/sdk` is an optional peer: install it to use either
 direction.
 
@@ -15208,7 +15373,7 @@ npm install @modelcontextprotocol/sdk
 ```
 
 `connectMcp`, `loadMcpTools` and `serveMcp` are exported from
-`lousho/mcp`; the package root and `lousho/tools`
+`@linuxdevil/lousho/mcp`; the package root and `@linuxdevil/lousho/tools`
 export them too. `createAgent({ mcpServers })` needs no import from the subpath.
 
 ## Use MCP servers in an agent
@@ -15223,7 +15388,7 @@ or `ready()`, reconnects. Without `mcpServers`, `ready()` and `close()` do nothi
 `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts no-run
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -15319,8 +15484,8 @@ own tools and MCP tools can sit in one list. (Spreading into one record,
 `tools: { ...mcp.tools, my_tool: myTool }`, works too.)
 
 ```ts no-run
-import { createAgent } from 'lousho';
-import { connectMcp } from 'lousho/mcp';
+import { createAgent } from '@linuxdevil/lousho';
+import { connectMcp } from '@linuxdevil/lousho/mcp';
 
 const mcp = await connectMcp(
   { files: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '.'] } },
@@ -15397,7 +15562,7 @@ in `loadMcpTools(client, name, { approval })`:
 `allow`, `deny` or `ask`.
 
 ```ts no-run
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -15421,15 +15586,15 @@ its tools with `loadMcpTools()`, then pass the result to `createAgent()` (or
 register it on a `ToolRegistry`):
 
 ```ts
-import { createAgent } from 'lousho';
-import { loadMcpTools } from 'lousho/mcp';
+import { createAgent } from '@linuxdevil/lousho';
+import { loadMcpTools } from '@linuxdevil/lousho/mcp';
 
 const tools = await loadMcpTools(mcpClient, 'my-server');
 const agent = createAgent({ instructions: '...', provider, tools });
 ```
 
 `loadMcpTools` is also available from the package root and from
-`lousho/tools`.
+`@linuxdevil/lousho/tools`.
 
 ## Serve an agent over MCP
 
@@ -15438,8 +15603,8 @@ optionally, some of its tools) as an MCP server, so Claude Code, Cursor and
 other MCP clients can call it.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { serveMcp } from 'lousho/mcp';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { serveMcp } from '@linuxdevil/lousho/mcp';
 import { z } from 'zod';
 
 const searchDocs = defineTool({
@@ -15504,7 +15669,7 @@ needs approval is never advertised read-only. The built-in `read_file`, `list_di
 `glob`, `grep`, `todo_read`, `current_date` and `day_name` tools are read-only.
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const lookupOrder = defineTool({
@@ -15521,8 +15686,8 @@ const lookupOrder = defineTool({
 `lousho mcp` serves an agent spec file (stdio by default):
 
 ```sh
-npx lousho mcp agent.yaml
-npx lousho mcp agent.yaml --http --port 3920 --host 127.0.0.1
+npx @linuxdevil/lousho mcp agent.yaml
+npx @linuxdevil/lousho mcp agent.yaml --http --port 3920 --host 127.0.0.1
 ```
 
 To use it from an MCP client, add it to the client's MCP config (for example
@@ -15582,7 +15747,7 @@ The `vendor/` model prefix chooses the provider; with OpenRouter use
 `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts no-run
-import { createAgent, defineMemory, fileMemory } from 'lousho';
+import { createAgent, defineMemory, fileMemory } from '@linuxdevil/lousho';
 
 const preferences = defineMemory({
   name: 'preferences',
@@ -15630,8 +15795,8 @@ A scope function sees the run's `sessionId` and the `metadata` passed to
 sessions:
 
 ```ts
-import { createAgent, defineMemory, inMemoryMemory } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineMemory, inMemoryMemory } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const userFacts = defineMemory({
   name: 'user_facts',
@@ -15674,7 +15839,7 @@ every start: `add()` dedupes on text, so nothing is copied twice. Each copy
 keeps `text` and `metadata` and gets a new `id` and `createdAt`.
 
 ```ts
-import { defineMemory, fileMemory, migrateMemoryKeys } from 'lousho';
+import { defineMemory, fileMemory, migrateMemoryKeys } from '@linuxdevil/lousho';
 
 const provider = fileMemory({ dir: './.lousho/memory' });
 const notes = defineMemory({ name: 'notes', scope: 'global', provider });
@@ -15712,7 +15877,7 @@ the count.
 
 ```ts
 import { z } from 'zod';
-import { defineMemory, inMemoryMemory } from 'lousho';
+import { defineMemory, inMemoryMemory } from '@linuxdevil/lousho';
 
 const relationship = defineMemory({
   name: 'relationship',
@@ -15743,7 +15908,7 @@ adding a second version. The item keeps its id, becomes the newest, and
 
 ```ts
 import { z } from 'zod';
-import { defineMemory, inMemoryMemory } from 'lousho';
+import { defineMemory, inMemoryMemory } from '@linuxdevil/lousho';
 
 const settings = defineMemory({
   name: 'settings',
@@ -15829,8 +15994,8 @@ by meaning instead of by keyword, use `sqliteVectorMemory()`: see
 [Semantic recall](#semantic-recall).
 
 ```ts no-run
-import { createAgent, defineMemory } from 'lousho';
-import { SqliteStore, sqliteMemory } from 'lousho/sqlite';
+import { createAgent, defineMemory } from '@linuxdevil/lousho';
+import { SqliteStore, sqliteMemory } from '@linuxdevil/lousho/sqlite';
 
 const store = new SqliteStore('./.lousho/agent.db');
 const notes = defineMemory({ name: 'notes', scope: 'global', provider: sqliteMemory(store) });
@@ -15840,7 +16005,7 @@ const agent = createAgent({ model: 'openai/gpt-4o-mini', store, memory: [notes]
 For a hosted store or your own ranking, implement `MemoryProvider`:
 
 ```ts
-import type { MemoryItem, MemoryProvider } from 'lousho';
+import type { MemoryItem, MemoryProvider } from '@linuxdevil/lousho';
 
 const items = new Map<string, MemoryItem[]>();
 const myProvider: MemoryProvider = {
@@ -15869,8 +16034,8 @@ With [`mockModel`](https://github.com/LinuxDevil/lousho/blob/main/docs/testing.m
 request and drive the tools with scripted tool calls:
 
 ```ts
-import { createAgent, defineMemory, inMemoryMemory, memoryKey } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineMemory, inMemoryMemory, memoryKey } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const store = inMemoryMemory();
 const notes = defineMemory({ name: 'notes', scope: 'global', provider: store });
@@ -15912,7 +16077,7 @@ package that pairs with your `ai` major, as for language models). It adds no
 dependency: `ai` is already a peer, and the provider package is yours.
 
 ```ts no-run
-import { createAgent, defineMemory, aiSdkEmbedder, inMemoryVectorMemory } from 'lousho';
+import { createAgent, defineMemory, aiSdkEmbedder, inMemoryVectorMemory } from '@linuxdevil/lousho';
 import { createOpenAI } from '@ai-sdk/openai';
 
 const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
@@ -15934,7 +16099,7 @@ Two providers rank by meaning, with the same options:
 - `inMemoryVectorMemory({ embedder, maxItems?, minScore? })` keeps items in this
   process.
 - `sqliteVectorMemory(store, { embedder, maxItems?, minScore? })` (from
-  `lousho/sqlite`) keeps them in the agent's SQLite file, in a
+  `@linuxdevil/lousho/sqlite`) keeps them in the agent's SQLite file, in a
   `memory_vectors` table that an existing file gains when it is opened. Vectors
   survive restarts.
 
@@ -15958,14 +16123,14 @@ re-embeds them in batches and returns how many it changed.
 `reindex(providerKey)` does one key only — for a slot's key, pass
 `memoryKey(slot, ctx)`.
 
-`hashEmbedder()` from `lousho/testing` is a deterministic
+`hashEmbedder()` from `@linuxdevil/lousho/testing` is a deterministic
 offline embedder for tests: a hashed bag of word stems, so texts that share
 words are close. It is not a semantic model and does not know that "vegetarian"
 and "eat" are related.
 
 ```ts
-import { inMemoryVectorMemory } from 'lousho';
-import { hashEmbedder } from 'lousho/testing';
+import { inMemoryVectorMemory } from '@linuxdevil/lousho';
+import { hashEmbedder } from '@linuxdevil/lousho/testing';
 
 const memory = inMemoryVectorMemory({ embedder: hashEmbedder() });
 await memory.add('global', { text: 'Sam is vegetarian' });
@@ -16031,7 +16196,7 @@ you already configured (keys, base URL, provider options) works as it is:
 
 ```ts no-run
 import { createOpenAI } from '@ai-sdk/openai';
-import { createAgent, fromAiSdk } from 'lousho';
+import { createAgent, fromAiSdk } from '@linuxdevil/lousho';
 
 const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
 const agent = createAgent({ provider: fromAiSdk(openai.chat('gpt-4o-mini')), instructions: 'You are helpful.' });
@@ -16049,7 +16214,7 @@ See [Providers](https://github.com/LinuxDevil/lousho/blob/main/docs/providers.md
 ```ts no-verify
 import { tool } from 'ai';
 import { z } from 'zod';
-import { createAgent, fromAiSdk, fromAiSdkTools } from 'lousho';
+import { createAgent, fromAiSdk, fromAiSdkTools } from '@linuxdevil/lousho';
 
 const weather = tool({
   description: 'Get the weather in a city',
@@ -16075,8 +16240,8 @@ and a plain object works too. This one runs offline:
 
 ```ts
 import { z } from 'zod';
-import { createAgent, fromAiSdkTools } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, fromAiSdkTools } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const tools = fromAiSdkTools({
   weather: {
@@ -16118,7 +16283,7 @@ A `useChat` front end keeps working: the route returns the agent's run as a UI m
 stream.
 
 ```ts no-run
-import { createAgent, fromUIMessages, memoryStore, toUIMessageStreamResponse, type UIMessageLike } from 'lousho';
+import { createAgent, fromUIMessages, memoryStore, toUIMessageStreamResponse, type UIMessageLike } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You are helpful.', store: memoryStore() });
 
@@ -16142,7 +16307,7 @@ Source: docs/migrating-to-create-agent.md
 
 This page is for code that uses `AgentBuilder`, `AgentExecutor`, `ToolRegistry` and
 `resumeAfterApproval()`: the lower-level API the SDK started with. Those exports now
-live at `lousho/executor` and are not going away; if you stay on
+live at `@linuxdevil/lousho/executor` and are not going away; if you stay on
 them, see [The executor API](https://github.com/LinuxDevil/lousho/blob/main/docs/executor-api.md). The reason to move is that one
 `createAgent()` call wires tools, stores, approvals, sessions, retries and
 compaction, where the executor makes you assemble each of them and pass them to every
@@ -16164,9 +16329,9 @@ import {
   AgentExecutor,
   ToolRegistry,
   resumeAfterApproval,
-} from 'lousho/executor';
-import { InMemoryApprovalStore, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+} from '@linuxdevil/lousho/executor';
+import { InMemoryApprovalStore, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
@@ -16208,8 +16373,8 @@ console.log(result.text); // 'Sent the report to Sam.'
 ```
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
@@ -16322,7 +16487,7 @@ Source: docs/models-and-cost.md
 Dependency-free helpers for budgeting and context decisions.
 
 ```ts
-import { estimateTokens, estimateCost, getModelInfo, registerModel } from 'lousho';
+import { estimateTokens, estimateCost, getModelInfo, registerModel } from '@linuxdevil/lousho';
 
 // A custom or self-hosted model: add it (or override a built-in) before use.
 registerModel({
@@ -16352,7 +16517,7 @@ The built-in context windows and prices are a dated snapshot (see the retrieval
 Every `ExecutionResult` (and `agent.send()` result) carries `usage`, the running total of the whole run:
 
 ```ts
-import { createAgent, formatUsage } from 'lousho';
+import { createAgent, formatUsage } from '@linuxdevil/lousho';
 
 const result = await createAgent({ provider, instructions: 'You compare cities.' }).send('Compare 3 cities');
 
@@ -16377,7 +16542,7 @@ console.log(formatUsage(result.usage)); // 1,234 in / 567 out tokens · $0.0042
 Prices come from the model registry above, so to get a cost for a custom or fine-tuned model, register it under the id you pass as the model:
 
 ```ts
-import { registerModel } from 'lousho';
+import { registerModel } from '@linuxdevil/lousho';
 
 registerModel({
   id: 'ft:gpt-4o-mini:acme',
@@ -16398,7 +16563,7 @@ Anthropic caches a request prefix only up to a `cache_control` breakpoint that t
 
 ```ts
 import { readFileSync } from 'node:fs';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const longPolicy = readFileSync('./policy.md', 'utf8'); // a long, stable system prompt
 const agent = createAgent({ model: 'openrouter/anthropic/claude-haiku-4.5', instructions: longPolicy }); // promptCaching: 'auto'
@@ -16434,7 +16599,7 @@ prefix chooses the provider; with OpenRouter use `openrouter/<vendor>/<model>`
 
 ```ts
 // app/api/agent/[[...path]]/route.ts
-import { createAgent, createRouteHandler, memoryStore } from 'lousho';
+import { createAgent, createRouteHandler, memoryStore } from '@linuxdevil/lousho';
 
 // `store` is what lets a session survive across requests: without one every
 // `agent.session({ id })` the handler opens gets a fresh in-memory transcript,
@@ -16457,7 +16622,7 @@ and spend your model budget. Pass a bearer token, or a function that checks your
 own session or cookie:
 
 ```ts
-import { createAgent, createRouteHandler } from 'lousho';
+import { createAgent, createRouteHandler } from '@linuxdevil/lousho';
 
 declare function isSignedIn(request: Request): Promise<boolean>;
 
@@ -16510,8 +16675,8 @@ customer's session (`GET /chat/:id`, to show what they are approving) and to
 decide in it; by default the session belongs to the customer alone:
 
 ```ts
-import { createAgent, createRouteHandler, memoryStore } from 'lousho';
-import { jwt } from 'lousho/auth';
+import { createAgent, createRouteHandler, memoryStore } from '@linuxdevil/lousho';
+import { jwt } from '@linuxdevil/lousho/auth';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', store: memoryStore() });
 const isSupervisor = (principal?: { claims?: Readonly<Record<string, unknown>> }) => principal?.claims?.role === 'supervisor';
@@ -16552,7 +16717,7 @@ see [Route auth and principals](https://github.com/LinuxDevil/lousho/blob/main/d
 
 ```tsx no-verify
 'use client';
-import { useLoushoAgent } from 'lousho/react';
+import { useLoushoAgent } from '@linuxdevil/lousho/react';
 
 export function Chat() {
   const agent = useLoushoAgent({ url: '/api/agent', headers: { Authorization: `Bearer ${token}` } }, { approvalsUrl: '/api/agent/approvals' });
@@ -16579,7 +16744,7 @@ const { messages, sendMessage } = useChat({ transport: new DefaultChatTransport(
 The same handler, mounted where the framework wants it:
 
 ```ts
-import { createAgent, createRouteHandler } from 'lousho';
+import { createAgent, createRouteHandler } from '@linuxdevil/lousho';
 
 const { handler } = createRouteHandler(createAgent({ model: 'openai/gpt-4o-mini' }), { basePath: '/agent', auth: 'secret' });
 
@@ -16633,7 +16798,7 @@ token, an operator who knows which authenticator the old tokens belong to moves
 them once:
 
 ```ts
-import { fileStore } from 'lousho';
+import { fileStore } from '@linuxdevil/lousho';
 
 const store = fileStore('./.lousho', { tokenKey: process.env.LOUSHO_TOKEN_KEY });
 const legacy = { owner: 'user', principalId: 'U04ABCDEF' } as const;
@@ -16655,7 +16820,7 @@ key unambiguous: a principal id containing `|` cannot collide with another
 owner.
 
 ```ts
-import { tokenStoreKey } from 'lousho';
+import { tokenStoreKey } from '@linuxdevil/lousho';
 
 tokenStoreKey('github', { owner: 'app' }); // 'github|app'
 tokenStoreKey('github', { owner: 'user', principalId: 'a|b', issuer: 'https://id.example.com' });
@@ -16667,7 +16832,7 @@ tokenStoreKey('github', { owner: 'user', principalId: 'a|b', issuer: 'https://id
 `AgentStore.tokens` is an `OAuthTokenStore`:
 
 ```ts
-import { memoryStore } from 'lousho';
+import { memoryStore } from '@linuxdevil/lousho';
 
 const { tokens } = memoryStore();
 const alice = { owner: 'user', principalId: 'alice', issuer: 'https://id.example.com' } as const;
@@ -16710,7 +16875,7 @@ node -e "console.log(Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toS
 ```
 
 ```ts
-import { createAgent, fileStore, generateTokenKey } from 'lousho';
+import { createAgent, fileStore, generateTokenKey } from '@linuxdevil/lousho';
 
 console.log(generateTokenKey()); // store it as a secret, e.g. LOUSHO_TOKEN_KEY
 
@@ -16766,7 +16931,7 @@ Define the provider once, at module level next to the tools that use it, with
 `defineOAuthProvider()`. A tool asks for a token with `ctx.getToken(provider)`:
 
 ```ts
-import { createAgent, defineOAuthProvider, defineTool, memoryStore } from 'lousho';
+import { createAgent, defineOAuthProvider, defineTool, memoryStore } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 export const github = defineOAuthProvider({
@@ -16831,7 +16996,7 @@ the agent's credential for every user: without the token the call fails with
 The operator signs the app in once with `agent.oauth.signInUrl(provider)`:
 
 ```ts
-import { createAgent, defineOAuthProvider, fileStore } from 'lousho';
+import { createAgent, defineOAuthProvider, fileStore } from '@linuxdevil/lousho';
 
 const slackBot = defineOAuthProvider({
   name: 'slack_bot',
@@ -16914,7 +17079,7 @@ link continues the run by approving the pause. Serving your own route, do the
 same:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider });
 
@@ -16988,8 +17153,8 @@ token store (encrypted by the persistent stores) under the provider name
 one.
 
 ```ts
-import { createAgent } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
+import { createAgent } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
 
 const agent = createAgent({
   provider,
@@ -17086,14 +17251,14 @@ mapping.
 Pass an `exporter` to `createAgent()`; every run of the agent (`send()`,
 `stream()`, session turns, `resume()` and runs continued by
 `agent.approvals.resolve()`) is traced, sub-agents included. To keep traces
-on disk and browse them with `npx lousho traces`, use `fileTraceExporter()`
+on disk and browse them with `npx @linuxdevil/lousho traces`, use `fileTraceExporter()`
 (see [Local traces](#local-traces)). The `vendor/` model prefix chooses the
 provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g.
 `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent } from 'lousho';
-import { fileTraceExporter } from 'lousho/traces';
+import { createAgent } from '@linuxdevil/lousho';
+import { fileTraceExporter } from '@linuxdevil/lousho/traces';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -17111,8 +17276,8 @@ reported once per exporter with `console.warn` and otherwise ignored.
 With the executor, pass the exporter to `AgentExecutor.execute()`:
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { type TraceExporter } from 'lousho';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { type TraceExporter } from '@linuxdevil/lousho';
 
 const exporter: TraceExporter = {
   onSpanStart: (span) => console.log('[start]', span.kind, span.name),
@@ -17123,7 +17288,7 @@ await AgentExecutor.execute({ agent, input, provider, toolRegistry, exporter });
 ```
 
 For real OpenTelemetry spans, import `createOtelTraceExporter()` from
-`lousho/otel` (needs the optional peer dependency
+`@linuxdevil/lousho/otel` (needs the optional peer dependency
 `@opentelemetry/api` and a registered `TracerProvider`). It carries span kind
 and error status over to OpenTelemetry. See `examples/tracing`
 (`npm run example:tracing:console`, `npm run example:tracing:otel`, which also prints metrics).
@@ -17151,7 +17316,7 @@ To put several runs in one trace, pass a span id of yours as `parentSpanId`;
 the run's `invoke_agent` span becomes its child, and its cost rolls up into it:
 
 ```ts
-import { withSpan, type SimpleAgent, type TraceExporter } from 'lousho';
+import { withSpan, type SimpleAgent, type TraceExporter } from '@linuxdevil/lousho';
 
 declare const exporter: TraceExporter;
 declare const planner: SimpleAgent;
@@ -17318,7 +17483,7 @@ duration metric, only the model and tool calls inside them.
 ```ts
 import { metrics } from '@opentelemetry/api';
 import { ConsoleMetricExporter, MeterProvider, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
-import { createOtelTraceExporter } from 'lousho/otel';
+import { createOtelTraceExporter } from '@linuxdevil/lousho/otel';
 
 // Swap ConsoleMetricExporter for an OTLP exporter to reach any backend.
 metrics.setGlobalMeterProvider(
@@ -17388,7 +17553,7 @@ piece of plain text (before JSON encoding) and returns what to record; if it
 throws, that text is recorded as `[redacted]` and the run carries on:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 createAgent({
   model: 'openai/gpt-4o-mini',
@@ -17404,8 +17569,8 @@ createAgent({
 With the executor, opt in per run:
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { type TraceExporter } from 'lousho';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { type TraceExporter } from '@linuxdevil/lousho';
 
 declare const exporter: TraceExporter;
 
@@ -17461,13 +17626,13 @@ governs only the `gen_ai.*` content attributes.
 
 ## Local traces
 
-`fileTraceExporter()` from `lousho/traces` writes each run to a
+`fileTraceExporter()` from `@linuxdevil/lousho/traces` writes each run to a
 file, and `lousho traces` shows the files in the terminal. No OpenTelemetry
 backend, no extra package.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { fileTraceExporter } from 'lousho/traces';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { fileTraceExporter } from '@linuxdevil/lousho/traces';
 import { z } from 'zod';
 
 const getWeather = defineTool({
@@ -17487,10 +17652,10 @@ const agent = createAgent({
 Then, from the project directory:
 
 ```bash
-npx lousho traces                 # the 20 most recent runs, newest first
-npx lousho traces --limit 50 --json
-npx lousho traces 3f2a            # one run as a tree; a unique id prefix is enough
-npx lousho traces 3f2a --content  # also the captured messages and tool arguments
+npx @linuxdevil/lousho traces                 # the 20 most recent runs, newest first
+npx @linuxdevil/lousho traces --limit 50 --json
+npx @linuxdevil/lousho traces 3f2a            # one run as a tree; a unique id prefix is enough
+npx @linuxdevil/lousho traces 3f2a --content  # also the captured messages and tool arguments
 ```
 
 ```
@@ -17554,6 +17719,15 @@ is printed per process and reporting stays off. `LOUSHO_OBSERVE_PROJECT` labels
 the rows; `LOUSHO_OBSERVE_TOKEN` sends a bearer token for daemons bound
 beyond loopback (`--require-token` plus `lousho observe token create`).
 
+`LOUSHO_OBSERVE_PROJECT` also decides where an agent lands in
+[Lousho Studio](https://github.com/LinuxDevil/lousho/blob/main/docs/agent-forge.md): set it to a workspace id (shown in Studio's
+**Settings → Workspaces**) and the agent's observed card appears under that
+workspace; unset, the project name is the package name and the agent appears
+under **Elsewhere**. Studio reads the same collector - it attaches to a
+running daemon or starts one itself on loopback (see
+[The collector](https://github.com/LinuxDevil/lousho/blob/main/docs/agent-forge.md#the-collector)) - so a deployed agent that
+reports to Studio's collector shows up with no Studio-specific code.
+
 **Security.** Because the loopback daemon takes no token, it refuses requests
 a web page in your browser could forge. On every `/api/*` route:
 
@@ -17573,7 +17747,7 @@ check comes first.
 
 One SQLite file (default `~/.lousho/observe.db`, WAL mode) holds the fleet's
 observations, sessions, eval scores, prompt versions and shared context.
-`npx lousho studio` renders it (see [Agent Forge](https://github.com/LinuxDevil/lousho/blob/main/docs/agent-forge.md#screens)):
+`npx @linuxdevil/studio` renders it (see [Lousho Studio](https://github.com/LinuxDevil/lousho/blob/main/docs/agent-forge.md#screens)):
 Traces and Trace (trace trees with latency waterfalls), Threads, Monitoring
 (a live fleet monitor with heartbeat-derived status — a crashed agent's open
 sessions flip to `interrupted` — over per-agent charts of runs, p95 latency,
@@ -18178,15 +18352,15 @@ the API without a hand-written `defineTool()` per endpoint and without the raw
 [`http` tool](https://github.com/LinuxDevil/lousho/blob/main/docs/tools.md#built-in-tools). Operations that change data ask for
 [approval](https://github.com/LinuxDevil/lousho/blob/main/docs/approvals.md) by default.
 
-`openApiTools` is exported from `lousho` and
-`lousho/tools`. It needs no extra package. The `vendor/` model
+`openApiTools` is exported from `@linuxdevil/lousho` and
+`@linuxdevil/lousho/tools`. It needs no extra package. The `vendor/` model
 prefix chooses the provider; with OpenRouter use `openrouter/<vendor>/<model>`
 (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ## Quick start
 
 ```ts no-run
-import { createAgent, openApiTools } from 'lousho';
+import { createAgent, openApiTools } from '@linuxdevil/lousho';
 
 const tools = await openApiTools('https://api.example.com/openapi.json', {
   include: ['getOrder', 'refundOrder'],
@@ -18247,7 +18421,7 @@ destructiveHint: false` on GET, HEAD and OPTIONS; `readOnlyHint: false` on the
 rest, with `destructiveHint: true` for DELETE. Anything that reads annotations treats these tools the way it treats MCP tools.
 
 ```ts no-run
-import { openApiTools } from 'lousho';
+import { openApiTools } from '@linuxdevil/lousho';
 
 declare const spec: object;
 
@@ -18265,7 +18439,7 @@ never sees it) and added to the request. The value can be a function, called per
 request with the operation and the tool call id.
 
 ```ts no-run
-import { openApiTools } from 'lousho';
+import { openApiTools } from '@linuxdevil/lousho';
 
 declare const spec: object;
 declare const currentTenant: () => string;
@@ -18336,7 +18510,7 @@ An API with hundreds of operations is hundreds of tools. Give the agent the ones
 it needs with `include` or `exclude`, or with a predicate on `op.tags`:
 
 ```ts no-run
-import { openApiTools } from 'lousho';
+import { openApiTools } from '@linuxdevil/lousho';
 
 declare const spec: object;
 
@@ -18375,7 +18549,7 @@ section links to the page that has the full detail.
 Set `needsApproval` on the tool. The run pauses before the tool executes:
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 export const refund = defineTool({
@@ -18403,9 +18577,9 @@ shared by several processes on one host) or `fileStore(dir)` (plain JSON files).
 `finishReason: 'awaiting-approval'` and the id to decide:
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const refund = defineTool({
@@ -18440,9 +18614,9 @@ run left in the store. `agent.approvals.resolve()` runs the call (or rejects it)
 continues the run, and resolves with the result:
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const refund = defineTool({
@@ -18497,8 +18671,8 @@ This snippet stands in for the crash with a tool that throws
 step), then recovers:
 
 ```ts
-import { createAgent, defineTool, memoryStore, PropagatingToolError } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool, memoryStore, PropagatingToolError } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 let charges = 0;
@@ -18576,8 +18750,8 @@ pause (`dontAsk`). Switch it in the middle of a session, the way you would work
 with a coding agent: plan first, then let it edit.
 
 ```ts
-import { createAgent, createFsTools, MemoryWorkspace } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createFsTools, MemoryWorkspace } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const workspace = new MemoryWorkspace({ files: { 'notes.md': '# Notes\n' } });
 const agent = createAgent({
@@ -18643,7 +18817,7 @@ says nothing is treated as one with side effects and is refused.
 Declare a custom read-only tool like this:
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const lookUpOrder = defineTool({
@@ -18665,7 +18839,7 @@ The hint is a promise you make about your tool: plan mode trusts it.
 alone, so a tool of your own named `write_file` is not approved silently.
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const appendLine = defineTool({
@@ -18710,7 +18884,7 @@ Switching is always an explicit call to `setPermissionMode()`. Each switch is
 reported to `onPermissionModeChange` with `{ sessionId, from, to, at }`:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   provider,
@@ -18832,8 +19006,8 @@ The four operations, and where each lives in the SDK:
 | **Isolate** | Run work in a clean context so detail doesn't flood the lead | Sub-agents (`task` calls see only their prompt), code mode (`run_code` returns one value), the `inputFilter` boundary |
 
 ```ts no-run
-import { createAgent, loadSkills } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, loadSkills } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const provider = mockModel([{ text: 'done' }]);
 const researchAgent = createAgent({ provider, instructions: 'You research one slice.' });
@@ -18928,7 +19102,7 @@ OpenRouter use `openrouter/<vendor>/<model>` (e.g.
 `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { resolveProvider, LLMProviderRegistry } from 'lousho';
+import { resolveProvider, LLMProviderRegistry } from '@linuxdevil/lousho';
 
 // The convenient way — reads the credential from the environment
 const openai = resolveProvider('openai/gpt-4o-mini');       // OPENAI_API_KEY
@@ -18958,7 +19132,7 @@ the vendor's package (`^1.0.0` with `ai` 4, `^3.0.0` with `ai` 6, `^4.0.0` with
 (`MISTRAL_API_KEY`, `GROQ_API_KEY`, the AWS chain for Bedrock, and so on).
 
 ```ts no-run
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 createAgent({ model: 'mistral/mistral-large-latest' });   // @ai-sdk/mistral
 createAgent({ model: 'bedrock/anthropic.claude-sonnet' }); // @ai-sdk/amazon-bedrock
@@ -19008,7 +19182,7 @@ it anyway:
    present. With none set it throws an error listing the fixes.
 
 ```ts no-run
-import { createAgent, createMockProvider, resolveProvider } from 'lousho';
+import { createAgent, createMockProvider, resolveProvider } from '@linuxdevil/lousho';
 
 const fromString = createAgent({ model: 'anthropic/claude-sonnet-5-5' });
 const fromInstance = createAgent({ provider: resolveProvider('openai/gpt-4o-mini'), model: 'gpt-4o' });
@@ -19026,7 +19200,7 @@ error, 5xx) twice by default, and with `fallbackModels` moves on to the next
 model when the call still fails:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -19069,7 +19243,7 @@ Parts sent through `createAgent()`:
 
 ```ts
 import { readFileSync } from 'node:fs';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'Describe images briefly.', model: 'openai/gpt-4o-mini' });
 
@@ -19085,7 +19259,7 @@ console.log(answer.text);
 A `Message[]` is passed through as it is; `textOf()` returns the text parts of a message:
 
 ```ts
-import { createAgent, textOf, type Message } from 'lousho';
+import { createAgent, textOf, type Message } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'Describe images briefly.', model: 'openai/gpt-4o-mini' });
 const messages: Message[] = [
@@ -19144,8 +19318,8 @@ console.log(textOf(messages[0]), '->', result.text);
 `AgentExecutor.execute()` takes the same messages as its `input` (see [the executor API](https://github.com/LinuxDevil/lousho/blob/main/docs/executor-api.md)):
 
 ```ts
-import { AgentBuilder, AgentExecutor } from 'lousho/executor';
-import { resolveProvider, type Message } from 'lousho';
+import { AgentBuilder, AgentExecutor } from '@linuxdevil/lousho/executor';
+import { resolveProvider, type Message } from '@linuxdevil/lousho';
 
 const agent = AgentBuilder.create().setName('vision').setPrompt('Describe images briefly.').build();
 const input: Message[] = [
@@ -19207,7 +19381,7 @@ text is not retried, so it fails after one `timeout`. To fail sooner, lower
 `timeout` or `retry.maxRetries`.
 
 ```ts
-import { OpenAIProvider } from 'lousho';
+import { OpenAIProvider } from '@linuxdevil/lousho';
 
 const provider = new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY!, timeout: 60_000 });
 ```
@@ -19221,7 +19395,7 @@ Pass `store: true` to have OpenAI store them (for its dashboard logs or
 evals). `store` is ignored with `api: 'chat'`.
 
 ```ts
-import { OpenAIProvider } from 'lousho';
+import { OpenAIProvider } from '@linuxdevil/lousho';
 
 const provider = new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY!, store: true });
 ```
@@ -19238,7 +19412,7 @@ instead. Install `undici` and pass its `Agent` as the dispatcher:
 
 ```ts
 import { Agent } from 'undici';
-import { createAgent, OpenAIProvider } from 'lousho';
+import { createAgent, OpenAIProvider } from '@linuxdevil/lousho';
 
 // Wait up to 15 minutes for the response headers and between body chunks.
 const dispatcher = new Agent({ headersTimeout: 15 * 60_000, bodyTimeout: 15 * 60_000 });
@@ -19266,7 +19440,7 @@ your function, so a failure you return from it is classified as it would be
 from the real network:
 
 ```ts
-import { OpenRouterProvider } from 'lousho';
+import { OpenRouterProvider } from '@linuxdevil/lousho';
 
 let failures = 1;
 const provider = new OpenRouterProvider({
@@ -19284,7 +19458,7 @@ into an `LLMProvider`, so you do not write an adapter:
 
 ```ts
 import { createOpenAI } from '@ai-sdk/openai';
-import { createAgent, fromAiSdk } from 'lousho';
+import { createAgent, fromAiSdk } from '@linuxdevil/lousho';
 
 const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
 const agent = createAgent({
@@ -19335,7 +19509,7 @@ npm install @earendil-works/pi-ai@^1.0.3
 ```
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 // OpenRouter's `openai/gpt-4o-mini`, through pi's openrouter adapter:
 const agent = createAgent({ model: 'pi/openrouter/openai/gpt-4o-mini' });
@@ -19381,7 +19555,7 @@ wire format. Point `OpenAIProvider` at the server's `/v1` URL and pick the API
 it implements with `api`:
 
 ```ts no-run
-import { createAgent, OpenAIProvider } from 'lousho';
+import { createAgent, OpenAIProvider } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   provider: new OpenAIProvider({
@@ -19434,14 +19608,14 @@ Ollama's `/v1` need).
 
 ```ts no-run
 import { createOpenAI } from '@ai-sdk/openai';
-import { createAgent, fromAiSdk } from 'lousho';
+import { createAgent, fromAiSdk } from '@linuxdevil/lousho';
 
 const local = createOpenAI({ baseURL: 'http://localhost:8080/v1', apiKey: 'any' });
 const agent = createAgent({ provider: fromAiSdk(local.chat('qwen3-8b')), instructions: 'You are a helpful assistant.' });
 ```
 
-`npx lousho doctor` shows `OPENAI_BASE_URL` when it is set, and
-`npx lousho doctor --ping` calls `GET <base>/models` on each configured
+`npx @linuxdevil/lousho doctor` shows `OPENAI_BASE_URL` when it is set, and
+`npx @linuxdevil/lousho doctor --ping` calls `GET <base>/models` on each configured
 provider to check that the server answers.
 
 ## Vercel AI SDK versions
@@ -19550,7 +19724,7 @@ reply gets one more step, so the model answers it in the same run. The
 `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 const run = agent.stream('Plan a weekend in Rome.');
@@ -19597,8 +19771,8 @@ Without a stream, pass an `InputQueue` to `AgentExecutor.execute()` (see
 [the executor API](https://github.com/LinuxDevil/lousho/blob/main/docs/executor-api.md)):
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { InputQueue } from 'lousho';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { InputQueue } from '@linuxdevil/lousho';
 
 const inputQueue = new InputQueue();
 const pending = AgentExecutor.execute({ agent, provider, input: 'Plan my trip.', inputQueue });
@@ -19625,7 +19799,7 @@ the user changes their mind while the agent is still thinking:
 - `applied` is `false` once the run has finished: send the input as a new turn.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 const run = agent.stream('Plan a weekend in Rome.');
@@ -19658,11 +19832,11 @@ Source: docs/react.md
 render-ready state: messages with their text and tool calls, a `status` for
 the composer, and the tool call waiting for approval, if any.
 
-It lives in the `lousho/react` subpath. `react` (18 or 19) is
+It lives in the `@linuxdevil/lousho/react` subpath. `react` (18 or 19) is
 an optional peer dependency: install it in the app that uses the hook.
 
 ```tsx
-import { useLoushoAgent } from 'lousho/react';
+import { useLoushoAgent } from '@linuxdevil/lousho/react';
 
 export function Chat() {
   const agent = useLoushoAgent({ url: '/api/agent' });
@@ -19773,8 +19947,8 @@ model prefix chooses the provider; with OpenRouter use
 
 ```ts
 import { createServer, type IncomingMessage } from 'node:http';
-import { createAgent } from 'lousho';
-import type { ApprovalOutcome } from 'lousho/react';
+import { createAgent } from '@linuxdevil/lousho';
+import type { ApprovalOutcome } from '@linuxdevil/lousho/react';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 
@@ -19823,8 +19997,8 @@ gets a fresh in-memory transcript and the next turn forgets the first (see
 The hook takes the agent itself, too. Called from a custom hook:
 
 ```ts
-import { createAgent } from 'lousho';
-import { useLoushoAgent } from 'lousho/react';
+import { createAgent } from '@linuxdevil/lousho';
+import { useLoushoAgent } from '@linuxdevil/lousho/react';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 
@@ -19844,7 +20018,7 @@ event)`, a pure reducer over `AgentEvent`s and a few local actions
 exported from the same subpath, for a custom binding or a non-React client:
 
 ```ts
-import { initialAgentUIState, parseEventStream, reduceAgentEvents } from 'lousho/react';
+import { initialAgentUIState, parseEventStream, reduceAgentEvents } from '@linuxdevil/lousho/react';
 
 let state = reduceAgentEvents(initialAgentUIState, { type: 'ui.send', input: 'Weather in Paris?' });
 const response = await fetch('http://localhost:3000/api/agent', {
@@ -19872,7 +20046,7 @@ chat and the plan. The list carries across turns and is cleared by nothing but a
 new hook (it is not restored when the page reconnects to an existing session).
 
 ```tsx
-import { useLoushoAgent, useTodos } from 'lousho/react';
+import { useLoushoAgent, useTodos } from '@linuxdevil/lousho/react';
 
 export function Plan() {
   const agent = useLoushoAgent({ url: '/api/agent' });
@@ -19913,7 +20087,7 @@ as `reasoning.*` events in `agent.stream()`, and as `result.reasoning`. The
 `openrouter/<vendor>/<model>` (e.g. `openrouter/anthropic/claude-sonnet-4.5`).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'anthropic/claude-sonnet-4-5',
@@ -20109,7 +20283,7 @@ Each item document is:
   "files": [
     {
       "path": "tools/web-search.ts",
-      "content": "import { defineTool } from 'lousho';\nimport { z } from 'zod';\n\nexport default defineTool({\n  name: 'web-search',\n  description: 'Search the web',\n  input: z.object({ query: z.string() }),\n  needsApproval: true,\n  execute: async ({ query }) => {\n    const response = await fetch(`https://api.example.com/search?q=${encodeURIComponent(query)}`, {\n      headers: { authorization: `Bearer ${process.env.SEARCH_KEY}` },\n    });\n    return response.json();\n  },\n});\n"
+      "content": "import { defineTool } from '@linuxdevil/lousho';\nimport { z } from 'zod';\n\nexport default defineTool({\n  name: 'web-search',\n  description: 'Search the web',\n  input: z.object({ query: z.string() }),\n  needsApproval: true,\n  execute: async ({ query }) => {\n    const response = await fetch(`https://api.example.com/search?q=${encodeURIComponent(query)}`, {\n      headers: { authorization: `Bearer ${process.env.SEARCH_KEY}` },\n    });\n    return response.json();\n  },\n});\n"
     }
   ],
   "permissions": {
@@ -20315,7 +20489,7 @@ same reason is on `run.done` in [streaming](https://github.com/LinuxDevil/lousho
 the deprecated `onEvent` counterpart).
 
 ```ts
-import { createAgent, createMockProvider } from 'lousho';
+import { createAgent, createMockProvider } from '@linuxdevil/lousho';
 const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider(), maxSteps: 3 });
 const result = await agent.send('Research this thoroughly');
 if (result.finishReason === 'max-steps') console.warn(`Gave up after ${result.steps} steps`);
@@ -20328,7 +20502,7 @@ Pass an `AbortSignal` to stop a run: `agent.send(input, { signal })`,
 `resumeAfterApproval(..., { signal })`.
 
 ```ts
-import { createAgent, createMockProvider } from 'lousho';
+import { createAgent, createMockProvider } from '@linuxdevil/lousho';
 const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider() });
 const controller = new AbortController();
 setTimeout(() => controller.abort(), 5_000); // e.g. from a Stop button
@@ -20339,7 +20513,7 @@ console.log(result.finishReason); // 'aborted' if it was cancelled, else 'stop'
 For a time limit, use `AbortSignal.timeout(ms)`:
 
 ```ts
-import { createAgent, createMockProvider } from 'lousho';
+import { createAgent, createMockProvider } from '@linuxdevil/lousho';
 const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider() });
 const result = await agent.send('Summarize this', { signal: AbortSignal.timeout(30_000) });
 ```
@@ -20391,7 +20565,7 @@ for strictly sequential execution, e.g. when your tools share state that is
 not safe to touch concurrently.
 
 ```ts
-import { createAgent, createMockProvider, defineTool } from 'lousho';
+import { createAgent, createMockProvider, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const getWeather = defineTool({
@@ -20458,7 +20632,7 @@ Give a cron expression and exactly one of `prompt` (text sent to the agent as a
 new turn) or `run` (your own function).
 
 ```ts
-import { createAgent, createMockProvider, defineSchedule, startSchedules } from 'lousho';
+import { createAgent, createMockProvider, defineSchedule, startSchedules } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You write reports.', provider: createMockProvider() });
 
@@ -20504,7 +20678,7 @@ server or a test exits normally. A script that does nothing but run schedules
 would therefore exit straight away; pass `keepAlive: true` for that:
 
 ```ts no-run
-import { createAgent, createMockProvider, defineSchedule, startSchedules } from 'lousho';
+import { createAgent, createMockProvider, defineSchedule, startSchedules } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You write reports.', provider: createMockProvider() });
 const running = startSchedules(agent, [defineSchedule({ cron: '@hourly', prompt: 'Check the queue.' })], { keepAlive: true });
@@ -20530,7 +20704,7 @@ claim is best effort across edge locations (see
 [Durable execution](https://github.com/LinuxDevil/lousho/blob/main/docs/durable-execution.md#run-leases)).
 
 ```ts
-import { createAgent, createMockProvider, defineSchedule, fireSchedule } from 'lousho';
+import { createAgent, createMockProvider, defineSchedule, fireSchedule } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You write reports.', provider: createMockProvider() });
 const report = defineSchedule({ name: 'report', cron: '0 9 * * *', prompt: 'Run the daily report.' });
@@ -20551,7 +20725,7 @@ they show an empty transcript for a schedule id. Read a fire's report from the
 checkpoint store instead, or continue it with `agent.fork(id)`:
 
 ```ts
-import { createAgent, createMockProvider, defineSchedule, fireSchedule, memoryStore } from 'lousho';
+import { createAgent, createMockProvider, defineSchedule, fireSchedule, memoryStore } from '@linuxdevil/lousho';
 
 const store = memoryStore();
 const agent = createAgent({ instructions: 'You write reports.', provider: createMockProvider(), store });
@@ -20577,7 +20751,7 @@ my-agent/
 `schedules/` loads exactly as before.
 
 ```ts
-import { createAgent, resolveAgentDir, startSchedules } from 'lousho';
+import { createAgent, resolveAgentDir, startSchedules } from '@linuxdevil/lousho';
 
 const { config, schedules } = await resolveAgentDir('./my-agent');
 const agent = createAgent(config);
@@ -20693,8 +20867,8 @@ each interrupted run from its last checkpoint, so completed steps don't run
 again.
 
 ```ts
-import { createAgent, createProgressGuard } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
+import { createAgent, createProgressGuard } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
 
 const agent = createAgent({
   provider,
@@ -20758,7 +20932,7 @@ recorded as not retryable, so `agent.recover()` won't resume the run.
 Each hint, denial and stop is streamed as a `heal.action` event:
 
 ```ts
-import { createAgent, createProgressGuard } from 'lousho';
+import { createAgent, createProgressGuard } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider, hooks: [createProgressGuard()] });
 
@@ -20840,8 +21014,8 @@ better instructions and skills using failing cases you give it, and returns a
 proposal without writing anything.
 
 ```ts
-import { createAgent } from 'lousho';
-import { formatImproveResult, improveAgent, renderTranscript } from 'lousho/improve';
+import { createAgent } from '@linuxdevil/lousho';
+import { formatImproveResult, improveAgent, renderTranscript } from '@linuxdevil/lousho/improve';
 
 const result = await improveAgent({
   harness: { instructions: 'You answer from the docs.', skills: {} },
@@ -20906,7 +21080,7 @@ See also: [Pause, restart, resume](https://github.com/LinuxDevil/lousho/blob/mai
 > Snippets on this page leave some names to you: `provider` is any `LLMProvider` (offline: `createMockProvider()`).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const chat = createAgent({ instructions: 'Be brief.', provider });
 
@@ -20968,7 +21142,7 @@ The `vendor/` model prefix chooses the provider; with OpenRouter use
 `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 const session = agent.session({ id: 'user-42', turnPolicy: 'queue' });
@@ -21020,7 +21194,7 @@ returns the same `AgentRun` (typed events plus a `result` promise, see
 it.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const chat = createAgent({ instructions: 'Be brief.', provider });
 const session = chat.session();
@@ -21089,8 +21263,8 @@ crash, a failed checkpoint write or a `PropagatingToolError` can then be
 finished later, in another process:
 
 ```ts
-import { createAgent } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
+import { createAgent } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
 
 const agent = createAgent({ provider, store: new SqliteStore('./.lousho/agent.db') });
 
@@ -21183,7 +21357,7 @@ console.log(finished?.text, await agent.session({ id: 'user-42' }).pending()); /
 A `SessionStore` keeps transcripts between calls:
 
 ```ts
-import type { Message } from 'lousho';
+import type { Message } from '@linuxdevil/lousho';
 
 interface SessionStore {
   load(id: string): Promise<Message[] | undefined>;
@@ -21214,7 +21388,7 @@ writer in another process can still slip between, losing one turn.
   files on Windows and macOS too.
 
 ```ts
-import { createAgent, FileSessionStore } from 'lousho';
+import { createAgent, FileSessionStore } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider });
 const store = new FileSessionStore('./.lousho/sessions');
@@ -21247,7 +21421,7 @@ implementation by where the process runs:
 | In memory (`memoryStore()`) | `MemorySessionStore` | in memory | `InMemoryApprovalStore` | Tests, scripts, one process that never restarts |
 | Files (`fileStore(dir)`) | `<dir>/sessions/<id>.json` | `<dir>/checkpoints/`, `<dir>/checkpoint-history/` | `<dir>/approvals/<id>.json` | One machine, you want plain inspectable files |
 | SQLite | `store.sessions` | `store.checkpoints` | `store.approvals` | A Node server: one durable, transactional file, shared by several processes on one host (see [Sharing a SQLite file](#sharing-a-sqlite-file)) |
-| Cloudflare KV (`KVStore` from `lousho/kv`) | `store.sessions` | `store.checkpoints` | `store.approvals` | Workers deployments (see [Deployment](https://github.com/LinuxDevil/lousho/blob/main/docs/deployment.md)) |
+| Cloudflare KV (`KVStore` from `@linuxdevil/lousho/kv`) | `store.sessions` | `store.checkpoints` | `store.approvals` | Workers deployments (see [Deployment](https://github.com/LinuxDevil/lousho/blob/main/docs/deployment.md)) |
 
 Each one is an `AgentStore` part: pass them together as
 `createAgent({ store: { sessions, checkpoints, approvals } })`. `memoryStore()`,
@@ -21261,7 +21435,7 @@ another writer or reader has open fails for a moment with `EPERM`, `EACCES` or
 file still end with one of them (the last rename wins):
 
 ```ts
-import { createAgent, fileStore } from 'lousho';
+import { createAgent, fileStore } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider, store: fileStore('./.lousho') });
 // ./.lousho/sessions/user-42.json, ./.lousho/checkpoints/..., ./.lousho/approvals/...
@@ -21298,7 +21472,7 @@ session's transcript), and so are pending approvals and OAuth tokens. It
 resolves with the counts, `{ sessions, checkpoints, checkpointHistory, oauthPending }`:
 
 ```ts
-import { fileStore } from 'lousho';
+import { fileStore } from '@linuxdevil/lousho';
 
 const store = fileStore('./.lousho');
 await store.prune({ olderThanMs: 30 * 24 * 60 * 60 * 1000 }); // a month
@@ -21313,8 +21487,8 @@ generated Worker uses `KVCheckpointStore`, see [Deployment](https://github.com/L
 re-exported from the root entry, so importing the SDK never loads it):
 
 ```ts
-import { createAgent } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
+import { createAgent } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
 
 const store = new SqliteStore('./.lousho/agent.db'); // or ':memory:'
 const agent = createAgent({ provider, store }); // transcripts, per-step checkpoints and approvals
@@ -21379,8 +21553,8 @@ starts a new session from any of them, so you can try another direction
 without losing the original conversation:
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const searchFlights = defineTool({
@@ -21491,7 +21665,7 @@ can correct itself.
 ## Skills in code
 
 ```ts
-import { createAgent, defineSkill } from 'lousho';
+import { createAgent, defineSkill } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   instructions: 'You are a release engineer.',
@@ -21560,7 +21734,7 @@ Use the imperative mood and link the PR.
   (both paths are listed).
 
 ```ts
-import { createAgent, loadSkills } from 'lousho';
+import { createAgent, loadSkills } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   instructions: 'You are a release engineer.',
@@ -21702,7 +21876,7 @@ payload. Each event type is exported too (`TextDeltaEvent`, `ToolDoneEvent`,
 `RunDoneEvent`, ...), and `AgentEventOf<'tool.done'>` picks one by name.
 
 ```ts
-import { isAgentEvent, isToolEvent, type AgentEvent } from 'lousho';
+import { isAgentEvent, isToolEvent, type AgentEvent } from '@linuxdevil/lousho';
 
 function render(event: AgentEvent): string {
   switch (event.type) {
@@ -21748,7 +21922,7 @@ provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g.
 > Snippets on this page leave some names to you: `provider` is any `LLMProvider` (offline: `createMockProvider()`); `agent` is a `createAgent()` result; `input` is the user's text, a `string`; `approvalStore` is an `ApprovalStore`; `toolRegistry` is a `ToolRegistry`.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 
@@ -21809,7 +21983,7 @@ interface AgentRun extends AsyncIterable<AgentEvent> {
   throw synchronously from `stream()`.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 
@@ -21836,7 +22010,7 @@ Output guardrails still check only the final reply of a `send()`, as without
 a listener. Sub-agents' events arrive tagged with `subagent`.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -21887,7 +22061,7 @@ save, so the transcript is complete when the loop ends. An aborted or failed
 run, or one you stop reading early, is not saved.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 const session = agent.session({ id: 'user-42' });
@@ -21915,7 +22089,7 @@ process, since everything is read from the approval store. A model chosen per
 run (`model` as a function) is the one the paused run used.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider /* , a tool with needsApproval */ });
 const paused = await agent.send('Delete the old reports.');
@@ -21934,7 +22108,7 @@ of `resumeAfterApproval()` (see [the executor API](https://github.com/LinuxDevil
 returns the same `AgentRun`.
 
 ```ts
-import { AgentExecutor, streamResumeAfterApproval } from 'lousho/executor';
+import { AgentExecutor, streamResumeAfterApproval } from '@linuxdevil/lousho/executor';
 
 const paused = await AgentExecutor.execute({ agent, input, provider, toolRegistry, approvalStore });
 const run = streamResumeAfterApproval({ id: paused.approvalId!, approved: true }, approvalStore, toolRegistry, provider);
@@ -21968,7 +22142,7 @@ for approval is reported once, by the top-level `approval.requested` (which
 carries the sub-agent's call).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const researcher = createAgent({ provider, instructions: 'You research.', description: 'Finds sources' });
 const lead = createAgent({ provider, instructions: 'You coordinate.', subagents: { researcher } });
@@ -22009,7 +22183,7 @@ step was running) and `run.done` (`'aborted'`), and `result` resolves with
 `finishReason: 'aborted'`.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 const run = agent.stream('Write a long story');
@@ -22027,7 +22201,7 @@ To add input to a run that is still going, or to redirect it, see [Queued input
 ## Example: terminal
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const getWeather = defineTool({
@@ -22066,7 +22240,7 @@ saved even when the client leaves (see [Next.js](https://github.com/LinuxDevil/l
 
 ```ts
 import { createServer } from 'node:http';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 
@@ -22109,7 +22283,7 @@ with `{ sessionId, input }` streams `agent.session({ id }).stream(input)` as
 needs approval ends the stream with `approval.requested`:
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
 
 const run = AgentExecutor.stream({ agent, input, provider, toolRegistry, approvalStore });
 for await (const event of run) {
@@ -22132,7 +22306,7 @@ the provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g.
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -22160,7 +22334,7 @@ itself) or any other Standard Schema that can produce JSON Schema:
 
 ```ts
 import { z } from 'zod/v4';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', output: z.object({ city: z.string() }) });
 const { object } = await agent.send('Where is the Eiffel Tower?');
@@ -22178,7 +22352,7 @@ the tool take the data and keep `output` for a summary or status.
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 declare function postComment(comment: { file: string; body: string }): Promise<void>;
 
@@ -22201,7 +22375,7 @@ from the data (a claim id), because a rerun of the whole flow extracts again:
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 declare function askReviewer(claim: { claimId: string; amountCents: number }): Promise<boolean>;
 declare const claims: { file(claim: { claimId: string; amountCents: number }, opts: { idempotencyKey: string }): Promise<void> };
@@ -22230,7 +22404,7 @@ turn. There is no per-call `output` override: the schema is the agent's.
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', output: z.object({ city: z.string(), tempC: z.number() }) });
 const session = agent.session();
@@ -22260,7 +22434,7 @@ read from the `object` of the remote stream's `run.done` event.
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const reporter = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -22285,7 +22459,7 @@ and `result.object` has no key for it. A field that accepts `null` itself
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openrouter/openai/gpt-4o-mini',
@@ -22365,7 +22539,7 @@ here; set `'final'` to keep it off those calls):
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o',
@@ -22402,7 +22576,7 @@ where a failure is yours to report:
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const Invoice = z.object({ subtotal: z.number(), tax: z.number(), total: z.number() });
 const agent = createAgent({ model: 'openai/gpt-4o-mini', output: Invoice });
@@ -22454,7 +22628,7 @@ progress, and `result.object` for the answer. The UI bindings keep it as
 `partialObject`.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const planner = createAgent({ model: 'openai/gpt-4o-mini', output: z.object({ days: z.array(z.string()) }) });
@@ -22471,8 +22645,8 @@ schema, or use `createAgent()` for the inferred type.
 
 ```ts
 import { z } from 'zod';
-import { AgentBuilder, AgentExecutor } from 'lousho/executor';
-import { createMockProvider } from 'lousho';
+import { AgentBuilder, AgentExecutor } from '@linuxdevil/lousho/executor';
+import { createMockProvider } from '@linuxdevil/lousho';
 
 const Ticket = z.object({ title: z.string(), priority: z.enum(['low', 'high']) });
 const agent = AgentBuilder.create().setName('triage').setPrompt('You triage bug reports.').build();
@@ -22486,8 +22660,8 @@ With `mockModel`, script the JSON text the model would write:
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const agent = createAgent({ provider: mockModel(['{"city":"Paris","tempC":21}']), output: z.object({ city: z.string(), tempC: z.number() }) });
 const { object } = await agent.send('Weather in Paris?');
@@ -22523,7 +22697,7 @@ Give each sub-agent a `description` (the lead model reads it to choose), then
 pass them to the lead as `subagents`:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const researcher = createAgent({
   provider,
@@ -22611,8 +22785,8 @@ needs no code. A lead that keeps its work across turns or restarts needs a
 store and a session:
 
 ```ts
-import { createAgent } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
+import { createAgent } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
 
 const store = new SqliteStore('./.lousho/agent.db');
 const researcher = createAgent({ provider, instructions: 'You research.', description: 'Finds and summarizes sources' });
@@ -22660,7 +22834,7 @@ sometimes pass one sub-agent's `taskId` to another and waste a turn on the
 error; this removes the option.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const analyst = createAgent({ provider, instructions: 'You analyze.', description: 'Analyzes data' });
 const lead = createAgent({ provider, subagents: { analyst }, subagentOptions: { continuation: false } });
@@ -22696,7 +22870,7 @@ At most `maxConcurrent` background sub-agents of one lead run run at once
 as slots free. Set it with `subagentOptions` on `createAgent()`:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const researcher = createAgent({ provider, instructions: 'You research.', description: 'Finds and summarizes sources' });
 
@@ -22737,7 +22911,7 @@ events arrive before the lead's `run.done`.
 The result lists every background task of the run with its final status:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const researcher = createAgent({ provider, instructions: 'You research.', description: 'Finds and summarizes sources' });
 const lead = createAgent({ provider, instructions: 'You coordinate research.', subagents: { researcher } });
@@ -22789,7 +22963,7 @@ Limits:
   cannot be resumed: the model chose not to wait for it.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const shell = defineTool({
@@ -22820,7 +22994,7 @@ the set can change between runs; `resolve()` is called when the lead picks a
 name (return `undefined` for an unknown one).
 
 ```ts
-import { createAgent, type SubagentCatalog } from 'lousho';
+import { createAgent, type SubagentCatalog } from '@linuxdevil/lousho';
 
 const experts = new Map([
   ['researcher', createAgent({ provider, instructions: 'You research.' })],
@@ -22842,7 +23016,7 @@ next to local ones, and the lead delegates to it with the same `task` tool,
 including `background: true`.
 
 ```ts
-import { createAgent, remoteAgent } from 'lousho';
+import { createAgent, remoteAgent } from '@linuxdevil/lousho';
 
 const lead = createAgent({
   provider,
@@ -22906,7 +23080,7 @@ final answer becomes the `task` result; a continuation that pauses again pauses
 the lead again.
 
 ```ts
-import type { SimpleAgent } from 'lousho';
+import type { SimpleAgent } from '@linuxdevil/lousho';
 declare const lead: SimpleAgent; // the lead agent above
 
 const paused = await lead.send('Deploy the docs site');
@@ -22940,7 +23114,7 @@ use the ready-made Pi adapter.
 Pi's tools (`read`, `bash`, `edit`, `write`, ...) work on a local directory.
 
 ```ts
-import { createAgent, piAgent, ask, allow } from 'lousho';
+import { createAgent, piAgent, ask, allow } from '@linuxdevil/lousho';
 import { ModelRuntime } from '@earendil-works/pi-coding-agent';
 
 const runtime = await ModelRuntime.create(); // reads ~/.pi/agent auth, env keys
@@ -23031,7 +23205,7 @@ the enclosing sub-agent as `parent` when nested deeper. A hook that should only
 see the top-level run returns early:
 
 ```ts
-import { HookRegistry } from 'lousho';
+import { HookRegistry } from '@linuxdevil/lousho';
 
 const hooks = new HookRegistry();
 hooks.register({
@@ -23067,7 +23241,7 @@ sub-agents it runs inside (e.g. `['researcher']`). Approve or reject it with
 is needed):
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const lead = createAgent({
   provider,
@@ -23124,8 +23298,8 @@ Resume with `resumeAfterApproval()`, passing the same `subagents` option as the
 paused run:
 
 ```ts
-import { AgentExecutor, resumeAfterApproval, ToolRegistry } from 'lousho/executor';
-import { createAgent } from 'lousho';
+import { AgentExecutor, resumeAfterApproval, ToolRegistry } from '@linuxdevil/lousho/executor';
+import { createAgent } from '@linuxdevil/lousho';
 
 const subagents = { researcher: createAgent({ provider, instructions: 'You research.', description: 'Researches' }) };
 
@@ -23152,13 +23326,13 @@ sources, the same state and the same actions, over the same
 field means, the two kinds of source, how approvals work and the server side;
 this page covers what differs.
 
-It lives in the `lousho/svelte` subpath. The store implements
+It lives in the `@linuxdevil/lousho/svelte` subpath. The store implements
 Svelte's store contract (`subscribe(run) => unsubscribe`) by hand, so it works
 with `$agent` in Svelte 4 and 5 and needs no `svelte` import: there is no peer
 dependency to install.
 
 ```ts
-import { loushoAgent } from 'lousho/svelte';
+import { loushoAgent } from '@linuxdevil/lousho/svelte';
 
 // In a component's <script lang="ts">, or a module that several components share:
 export const agent = loushoAgent({ url: '/api/agent' }, { approvalsUrl: '/api/approvals' });
@@ -23217,7 +23391,7 @@ snippets here):
 
 The reducer and the stream parser are exported from this subpath too
 (`reduceAgentEvents`, `initialAgentUIState`, `parseEventStream`), the same
-ones as in `lousho/react`.
+ones as in `@linuxdevil/lousho/react`.
 
 ## Todos
 
@@ -23229,7 +23403,7 @@ the same stream as the chat, and notifies only when the list changes (see
 [React](https://github.com/LinuxDevil/lousho/blob/main/docs/react.md#todos)).
 
 ```ts
-import { loushoAgent, loushoTodos } from 'lousho/svelte';
+import { loushoAgent, loushoTodos } from '@linuxdevil/lousho/svelte';
 
 export const agent = loushoAgent({ url: '/api/agent' });
 export const plan = loushoTodos(agent);
@@ -23247,7 +23421,7 @@ export const plan = loushoTodos(agent);
 
 Source: docs/testing.md
 
-`lousho/testing` ships `mockModel`: a scripted, deterministic
+`@linuxdevil/lousho/testing` ships `mockModel`: a scripted, deterministic
 `LLMProvider` for unit tests. You write down what the model should say on each
 turn, run your agent, and then assert on exactly what the agent sent to the
 model. No network, no API keys, no flakiness.
@@ -23261,8 +23435,8 @@ npm install --save-dev vitest
 A bare string is shorthand for `{ text }`.
 
 ```ts
-import { createAgent } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const model = mockModel(['Hello! How can I help?']);
 const agent = createAgent({ instructions: 'You are friendly.', provider: model });
@@ -23284,8 +23458,8 @@ ids are generated deterministically (`call_1`, `call_2`, ...) unless you pass
 ```ts no-run
 import { describe, it, expect, vi } from 'vitest';
 import { z } from 'zod';
-import { createAgent, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 describe('weather agent', () => {
   it('calls get_weather and reports the result', async () => {
@@ -23324,8 +23498,8 @@ when the provider fails.
 
 ```ts no-verify
 import { it, expect } from 'vitest';
-import { createAgent } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 it('surfaces a provider failure', async () => {
   const model = mockModel([{ error: new Error('upstream 503') }]);
@@ -23356,7 +23530,7 @@ Pass a function to compute a turn from the request. It may be async and may
 return a string or any turn object.
 
 ```ts
-import { mockModel } from 'lousho/testing';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const model = mockModel([(req) => `You said: ${req.messages.at(-1)?.content}`]);
 const result = await model.generate({ messages: [{ role: 'user', content: 'ping' }] });
@@ -23383,7 +23557,7 @@ request and tells you to add a turn. To replay the final turn forever (handy for
 loop and step-limit tests), pass `{ onExhausted: 'repeat-last' }`:
 
 ```ts
-import { mockModel } from 'lousho/testing';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const looping = mockModel([{ toolCalls: [{ name: 'again' }] }], { onExhausted: 'repeat-last' });
 ```
@@ -23408,8 +23582,8 @@ OpenRouter use `openrouter/<vendor>/<model>` (e.g.
 `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent, resolveProvider } from 'lousho';
-import { recordReplay } from 'lousho/testing';
+import { createAgent, resolveProvider } from '@linuxdevil/lousho';
+import { recordReplay } from '@linuxdevil/lousho/testing';
 
 const provider = recordReplay(() => resolveProvider('openai/gpt-4o-mini'), {
   cassette: './__cassettes__/refund-flow.json',
@@ -23457,7 +23631,7 @@ If the change is intentional, re-record the cassette (run with LOUSHO_RECORD=1,
 
 That hint assumes you wired `mode` to `LOUSHO_RECORD` as above. If you record
 some other way, pass `rerecordHint` with the command your project uses; under
-`lousho eval` the hint names `npx lousho eval --record` instead.
+`lousho eval` the hint names `npx @linuxdevil/lousho eval --record` instead.
 
 For parallel or unordered calls pass `match: 'request'`: each call finds the
 first unused entry with an identical request, in any order. Running out of
@@ -23474,7 +23648,7 @@ changing the schema itself still fails the match. For anything else, pass
 `normalize`:
 
 ```ts
-import { mockModel, recordReplay } from 'lousho/testing';
+import { mockModel, recordReplay } from '@linuxdevil/lousho/testing';
 
 const provider = recordReplay(mockModel(['ok']), {
   cassette: './__cassettes__/users.json',
@@ -23524,7 +23698,7 @@ the file. Pass `redact` to scrub them (it runs on every recorded string, in both
 requests and responses, and replay applies it when matching):
 
 ```ts
-import { mockModel, recordReplay } from 'lousho/testing';
+import { mockModel, recordReplay } from '@linuxdevil/lousho/testing';
 
 const provider = recordReplay(mockModel(['ok']), {
   cassette: './__cassettes__/support.json',
@@ -23571,7 +23745,7 @@ model prefix chooses the provider; with OpenRouter use
 `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const convertCurrency = defineTool({
@@ -23601,7 +23775,7 @@ const agent = createAgent({
 Or mark a whole MCP server: every tool it lists is deferred.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -23671,7 +23845,7 @@ the search. Deferral itself is turned on by marking tools or servers
 | `search(query, tools)` | keyword ranking | Your own ranking (for example embeddings): return tool names, best first. Unknown names and duplicates are dropped. If it throws, the call is a tool error and loads nothing. |
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -23748,7 +23922,7 @@ accepted (`createAgent({ tools: [...] })`, `ToolRegistry.register(tool)`,
 > Snippets on this page leave some names to you: `provider` is any `LLMProvider` (offline: `createMockProvider()`).
 
 ```ts
-import { defineTool, createAgent, type ToolInput, type ToolOutput } from 'lousho';
+import { defineTool, createAgent, type ToolInput, type ToolOutput } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const weather = defineTool({
@@ -23897,7 +24071,7 @@ The transcript message carries `isError: true`; `tool-result` events, `onToolRes
 `toolErrorMessage` to `createAgent` to replace the text of `execution` errors:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   instructions: 'You answer questions about orders.',
@@ -23957,7 +24131,7 @@ its next model call with `finishReason: 'budget-exceeded'` and
 under `onExceeded: 'throw'`, see [Budgets](https://github.com/LinuxDevil/lousho/blob/main/docs/configuration.md#budgets)).
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const stats = defineTool({ name: 'stats', description: 'Weekly stats', input: z.object({}), execute: async () => (await fetch('https://stats.example.com/week')).json() });
@@ -23977,7 +24151,7 @@ if (result.toolErrors) console.warn(`${result.toolErrors} tool call(s) failed; t
 | `createTodoTools()` | `todo_write` / `todo_read` so an agent can plan multi-step work; see [Todo tools](#todo-tools). |
 | `askQuestionTool()`, `createAgent({ askQuestion: true })` | `ask_question`: the agent asks the user something and the run pauses until `agent.approvals.answer()`; see [Asking the user a question](https://github.com/LinuxDevil/lousho/blob/main/docs/approvals.md#asking-the-user-a-question). |
 | `createFsTools()`, `createShellTool()` | File system and shell tools for coding agents; see [Workspace tools](https://github.com/LinuxDevil/lousho/blob/main/docs/workspace-tools.md). |
-| `createEmailTool()`, `createSlackTool()`, `createGitHubTools()`, `createJiraTools()` (from `lousho/integrations`) | Integrations that need credentials, so they are built with options. `createSlackTool()` reads the webhook URL from `SLACK_WEBHOOK_URL` unless you pass `webhookUrl`; `createJiraTools()` takes `baseUrl`, `email` and `apiToken` explicitly (conventionally from `JIRA_BASE_URL`, `JIRA_EMAIL` and `JIRA_API_TOKEN`). |
+| `createEmailTool()`, `createSlackTool()`, `createGitHubTools()`, `createJiraTools()` (from `@linuxdevil/lousho/integrations`) | Integrations that need credentials, so they are built with options. `createSlackTool()` reads the webhook URL from `SLACK_WEBHOOK_URL` unless you pass `webhookUrl`; `createJiraTools()` takes `baseUrl`, `email` and `apiToken` explicitly (conventionally from `JIRA_BASE_URL`, `JIRA_EMAIL` and `JIRA_API_TOKEN`). |
 | `createAgent({ mcpServers })`, `connectMcp(servers)` | Every tool of MCP servers given as config (stdio `command` or HTTP `url`), named `<server>__<tool>`; see [Use MCP servers in an agent](https://github.com/LinuxDevil/lousho/blob/main/docs/mcp.md#use-mcp-servers-in-an-agent). |
 | `openApiTools(document, options)` | One tool per operation of an OpenAPI 3.0 / 3.1 document; mutating operations ask for approval. See [OpenAPI tools](https://github.com/LinuxDevil/lousho/blob/main/docs/openapi-tools.md). |
 | `loadMcpTools(client, name)` | Every tool of a connected MCP server; see [MCP tools](https://github.com/LinuxDevil/lousho/blob/main/docs/mcp.md#tools-from-a-client-you-connected-yourself). |
@@ -24015,7 +24189,7 @@ the provider; with OpenRouter use `openrouter/<vendor>/<model>`, e.g.
 `openrouter/openai/gpt-4o-mini`):
 
 ```ts
-import { createAgent, createWebFetchTool } from 'lousho';
+import { createAgent, createWebFetchTool } from '@linuxdevil/lousho';
 
 const webFetch = createWebFetchTool({
   timeoutMs: 30_000, // whole request: redirects and body included
@@ -24054,7 +24228,7 @@ emits a `todo.updated` stream event with the new list and its counts (see
 `useTodos()` / `loushoTodos()`, so a UI shows the plan live without `onChange`.
 
 ```ts
-import { createAgent, createTodoTools, type TodoStore } from 'lousho';
+import { createAgent, createTodoTools, type TodoStore } from '@linuxdevil/lousho';
 
 const todos = createTodoTools({ onChange: (list) => console.log(list.length, 'todos') });
 const planner = createAgent({ instructions: 'Plan multi-step work, then do it.', provider, tools: todos.tools });
@@ -24077,8 +24251,8 @@ raw `ToolDescriptor` (a built-in tool, an MCP tool, or an existing `tool()` from
 the `ai` SDK), and `registerMany()` for a record of descriptors or an array of defined tools.
 
 ```ts
-import { ToolRegistry } from 'lousho/tools';
-import { currentDateTool, defineTool } from 'lousho';
+import { ToolRegistry } from '@linuxdevil/lousho/tools';
+import { currentDateTool, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const lookupOrder = defineTool({
@@ -24110,7 +24284,7 @@ the result `null`, as does any tool that returns `undefined`: the transcript, th
 model and `tool.done` all see `null`.
 
 ```ts
-import { createAgent, defineTool, type ToolOutput } from 'lousho';
+import { createAgent, defineTool, type ToolOutput } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const buildReport = defineTool({
@@ -24173,7 +24347,7 @@ What to know:
 
 Source: docs/triggers.md
 
-A trigger adapter turns one wake-up mechanism into an agent run. The `lousho/triggers` subpath is the extension point for your own mechanism (`TriggerAdapter`, `TriggerRegistry`) plus a few helpers shared with channels and schedules: the `WebhookAuth` shapes, `verifySlackSignature()` and `parseCronExpression()`. The built-in webhook, Slack and cron adapters were removed; see [Migrating from triggers](https://github.com/LinuxDevil/lousho/blob/main/docs/upgrading.md#migrating-from-triggers).
+A trigger adapter turns one wake-up mechanism into an agent run. The `@linuxdevil/lousho/triggers` subpath is the extension point for your own mechanism (`TriggerAdapter`, `TriggerRegistry`) plus a few helpers shared with channels and schedules: the `WebhookAuth` shapes, `verifySlackSignature()` and `parseCronExpression()`. The built-in webhook, Slack and cron adapters were removed; see [Migrating from triggers](https://github.com/LinuxDevil/lousho/blob/main/docs/upgrading.md#migrating-from-triggers).
 
 ## Choosing between triggers, channels and schedules
 
@@ -24203,8 +24377,8 @@ Reply semantics differ per adapter. An adapter whose reply is the open request (
 Write your own adapter by returning a handle from `listen`:
 
 ```ts
-import { createAgent, createMockProvider } from 'lousho';
-import type { TriggerAdapter } from 'lousho/triggers';
+import { createAgent, createMockProvider } from '@linuxdevil/lousho';
+import type { TriggerAdapter } from '@linuxdevil/lousho/triggers';
 
 const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider() });
 
@@ -24227,7 +24401,7 @@ handle.stop();
 The `WebhookAuth` shapes are the reference for `webhookChannel({ auth })` (see [Channels](https://github.com/LinuxDevil/lousho/blob/main/docs/channels.md)). `checkWebhookAuth()` and `assertValidWebhookAuth()` are exported for your own handler.
 
 ```ts no-run
-import { createAgent, createMockProvider, mountChannels, webhookChannel } from 'lousho';
+import { createAgent, createMockProvider, mountChannels, webhookChannel } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider() });
 
@@ -24272,7 +24446,7 @@ sent in clear text.
 `slackChannel()` verifies every request for you (see [Slack in Channels](https://github.com/LinuxDevil/lousho/blob/main/docs/channels.md#slack)). For your own handler (slash commands, interactivity), verify the RAW body with `verifySlackSignature()`: HMAC-SHA256 over `v0:{X-Slack-Request-Timestamp}:{raw body}`, compared in constant time with `X-Slack-Signature` (`v0=<hex>`). Requests more than five minutes old, or more than a minute ahead of local time, are rejected (the timestamp is in seconds, as Slack sends it). See [Slack's documentation](https://docs.slack.dev/authentication/verifying-requests-from-slack).
 
 ```ts no-run
-import { verifySlackSignature } from 'lousho/triggers';
+import { verifySlackSignature } from '@linuxdevil/lousho/triggers';
 
 const authentic = verifySlackSignature({
   signingSecret: process.env.SLACK_SIGNING_SECRET ?? '',
@@ -24334,7 +24508,7 @@ response lists the cancelled run keys under `cancelled`.
 Source: docs/troubleshooting.md
 
 This page starts from what you see and points to the cause, the fix and the page
-that explains it. First run `npx lousho doctor` ([what it checks](https://github.com/LinuxDevil/lousho/blob/main/docs/installation.md#troubleshooting-lousho-doctor)),
+that explains it. First run `npx @linuxdevil/lousho doctor` ([what it checks](https://github.com/LinuxDevil/lousho/blob/main/docs/installation.md#troubleshooting-lousho-doctor)),
 then, if you have an error code (`LOUSHO_...`), look it up in [Errors](https://github.com/LinuxDevil/lousho/blob/main/docs/errors.md).
 
 ## Setup
@@ -24349,7 +24523,7 @@ environment (`LOUSHO_CONFIG_MISSING_PROVIDER`).
 ### "The API key is not set"
 
 - **Cause:** the provider's key variable (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`) is not in the environment of the process that runs the agent (`LOUSHO_PROVIDER_MISSING_API_KEY`).
-- **Fix:** set it, or pass a configured provider instance. `npx lousho doctor` prints `set` or `not set` for each key, never the value. The `vendor/` model prefix chooses the provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`) — `model: 'openai/gpt-4o-mini'` needs `OPENAI_API_KEY` even when only `OPENROUTER_API_KEY` is set.
+- **Fix:** set it, or pass a configured provider instance. `npx @linuxdevil/lousho doctor` prints `set` or `not set` for each key, never the value. The `vendor/` model prefix chooses the provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`) — `model: 'openai/gpt-4o-mini'` needs `OPENAI_API_KEY` even when only `OPENROUTER_API_KEY` is set.
 - **More:** [the error](https://github.com/LinuxDevil/lousho/blob/main/docs/errors.md#lousho_provider_missing_api_key).
 
 ### "Cannot find package `@ai-sdk/openai`" or "install the optional peer"
@@ -24373,7 +24547,7 @@ environment (`LOUSHO_CONFIG_MISSING_PROVIDER`).
 ### The Node version is too old
 
 - **Cause:** the SDK needs Node.js 22.19 or newer (`engines.node`).
-- **Fix:** upgrade Node. `npx lousho doctor` compares your version with the requirement.
+- **Fix:** upgrade Node. `npx @linuxdevil/lousho doctor` compares your version with the requirement.
 - **More:** [Requirements](https://github.com/LinuxDevil/lousho/blob/main/docs/installation.md#requirements).
 
 ### Ollama and zod versions disagree
@@ -24472,7 +24646,7 @@ environment (`LOUSHO_CONFIG_MISSING_PROVIDER`).
 
 Open an issue at <https://github.com/LinuxDevil/lousho/issues>. Include:
 
-- the output of `npx lousho doctor --json`,
+- the output of `npx @linuxdevil/lousho doctor --json`,
 - the error code (`LOUSHO_...`) and the full message,
 - the SDK version (`npm ls lousho`) and your `ai` version.
 
@@ -24498,7 +24672,7 @@ Already on `1.0.0-alpha.19`? Skip to
 since.
 
 ```bash
-npm install lousho@^1.0.0-alpha.19
+npm install @linuxdevil/lousho@^1.0.0-alpha.19
 ```
 
 ## Import paths that moved
@@ -24509,23 +24683,23 @@ are unchanged apart from where they live.
 
 | Name(s) | Old import | New import |
 | ------- | ---------- | ---------- |
-| `AgentExecutor`, `AgentBuilder`, `ExecuteOptions`, `ResumeExecuteOptions`, `ResumeRequest`, `resumeAfterApproval()`, `streamResumeAfterApproval()`, `resumeRequest()` | `lousho` or `lousho/core` | `lousho/executor` |
-| `ToolRegistry`, `globalToolRegistry` | `lousho` or `lousho/core` | `lousho/executor` (also still in `lousho/tools`) |
-| `ExecutionResult`, `ExecutionFinishReason` (the executor's types) | `lousho/core` | `lousho/executor` (`ExecutionResult` is also still in the root, where `createAgent()`'s result type lives) |
-| `FlowBuilder`, `FlowExecutor`, `validateFlow` and every flow type (`AgentFlow`, `EditorStep`, `FlowExecutionEvent`, ...) | `lousho` or `lousho/types` | `lousho/flows` |
-| `createJiraTools`, `createGitHubTools`, `createSlackTool`, `slackTool`, `postSlackAlert`, `createEmailTool` and their types | `lousho` or `lousho/tools` | `lousho/integrations` |
-| `EncryptionUtils`, `DTOEncryptionFilter`, `DecryptionError`, `sha256`, `generatePassword` | `lousho` | `lousho/utils` |
-| `StorageService`, `StorageServiceApprovalStore`, `LocalStorageCheckpointStore` | `lousho` | `lousho/utils` (with `createAgent()` stores, prefer `fileStore(dir)` from the root) |
-| `validateWithSchema`, `safeValidate`, `isValidEmail` and the other validators | `lousho` | `lousho/utils` |
-
-The `lousho/core` subpath no longer exists; everything it
+| `AgentExecutor`, `AgentBuilder`, `ExecuteOptions`, `ResumeExecuteOptions`, `ResumeRequest`, `resumeAfterApproval()`, `streamResumeAfterApproval()`, `resumeRequest()` | `lousho` or `@linuxdevil/lousho/core` | `@linuxdevil/lousho/executor` |
+| `ToolRegistry`, `globalToolRegistry` | `lousho` or `@linuxdevil/lousho/core` | `@linuxdevil/lousho/executor` (also still in `@linuxdevil/lousho/tools`) |
+| `ExecutionResult`, `ExecutionFinishReason` (the executor's types) | `@linuxdevil/lousho/core` | `@linuxdevil/lousho/executor` (`ExecutionResult` is also still in the root, where `createAgent()`'s result type lives) |
+| `FlowBuilder`, `FlowExecutor`, `validateFlow` and every flow type (`AgentFlow`, `EditorStep`, `FlowExecutionEvent`, ...) | `lousho` or `@linuxdevil/lousho/types` | `@linuxdevil/lousho/flows` |
+| `createJiraTools`, `createGitHubTools`, `createSlackTool`, `slackTool`, `postSlackAlert`, `createEmailTool` and their types | `lousho` or `@linuxdevil/lousho/tools` | `@linuxdevil/lousho/integrations` |
+| `EncryptionUtils`, `DTOEncryptionFilter`, `DecryptionError`, `sha256`, `generatePassword` | `lousho` | `@linuxdevil/lousho/utils` |
+| `StorageService`, `StorageServiceApprovalStore`, `LocalStorageCheckpointStore` | `lousho` | `@linuxdevil/lousho/utils` (with `createAgent()` stores, prefer `fileStore(dir)` from the root) |
+| `validateWithSchema`, `safeValidate`, `isValidEmail` and the other validators | `lousho` | `@linuxdevil/lousho/utils` |
+
+The `@linuxdevil/lousho/core` subpath no longer exists; everything it
 exported is under `/executor`.
 
 ```ts
-import { AgentExecutor, AgentBuilder, ToolRegistry } from 'lousho/executor';
-import { FlowBuilder, validateFlow } from 'lousho/flows';
-import { createSlackTool } from 'lousho/integrations';
-import { EncryptionUtils, validateWithSchema } from 'lousho/utils';
+import { AgentExecutor, AgentBuilder, ToolRegistry } from '@linuxdevil/lousho/executor';
+import { FlowBuilder, validateFlow } from '@linuxdevil/lousho/flows';
+import { createSlackTool } from '@linuxdevil/lousho/integrations';
+import { EncryptionUtils, validateWithSchema } from '@linuxdevil/lousho/utils';
 ```
 
 ## Removed APIs and their replacements
@@ -24557,13 +24731,13 @@ import { EncryptionUtils, validateWithSchema } from 'lousho/utils';
 
 ```ts no-verify
 // Before (alpha):
-import { createDelegateTool } from 'lousho';
+import { createDelegateTool } from '@linuxdevil/lousho';
 const delegate = createDelegateTool({ agent: billing, name: 'billing' });
 ```
 
 ```ts
 // After (1.0): the lead gets a `task` tool per sub-agent.
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const billing = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You answer billing questions.' });
 const lead = createAgent({
@@ -24596,7 +24770,7 @@ results and behavior are unchanged; `SECRET_PATTERNS` keeps its name. See
 
 ## Migrating from triggers
 
-`WebhookTriggerAdapter`, `SlackTriggerAdapter`, `CronTriggerAdapter` and their option/handle types were removed from `lousho/triggers`. `TriggerAdapter`, `TriggerRegistry`, the `WebhookAuth` helpers, `verifySlackSignature()` and `parseCronExpression()` stay. See [Triggers](https://github.com/LinuxDevil/lousho/blob/main/docs/triggers.md).
+`WebhookTriggerAdapter`, `SlackTriggerAdapter`, `CronTriggerAdapter` and their option/handle types were removed from `@linuxdevil/lousho/triggers`. `TriggerAdapter`, `TriggerRegistry`, the `WebhookAuth` helpers, `verifySlackSignature()` and `parseCronExpression()` stay. See [Triggers](https://github.com/LinuxDevil/lousho/blob/main/docs/triggers.md).
 
 | Removed | Replacement |
 | ------- | ----------- |
@@ -24768,7 +24942,7 @@ there is one. A change marked "no opt-out" closed a security or data-loss bug.
 | `agent.stream()` rethrows the run's error after the `error` and `run.done` events. See [Streaming](https://github.com/LinuxDevil/lousho/blob/main/docs/streaming.md). | `stream(input, { throwOnError: false })` |
 | `send([])` throws `LOUSHO_CONFIG_INVALID`. | no opt-out |
 
-### CLI, evals and Agent Forge
+### CLI, evals and Studio
 
 | Change | Opt-out |
 | ------ | ------- |
@@ -24783,7 +24957,30 @@ there is one. A change marked "no opt-out" closed a security or data-loss bug.
 | The observe daemon prunes old data by default: on its first sweep and then once a day it deletes every trace whose observations all finished more than 30 days ago, with that trace's scores and prompt-use links, and sessions that are no longer `active`, ended before the window and no longer referenced. A trace with a run still open, active sessions, the Insights rollups, prompts, hub entries, the agent registry, tokens, datasets, evaluator rules and annotation queues are never pruned. See [Retention](https://github.com/LinuxDevil/lousho/blob/main/docs/observability.md#retention). | `lousho observe start --retention-days 0` keeps everything (or `N` for another window) |
 | `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` (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`) |
+| 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 @linuxdevil/lousho`) |
+| The npm package no longer ships Studio (`apps/agent-forge`); `lousho studio` is now a launcher that finds an installed `@linuxdevil/studio`. | `npm i -g @linuxdevil/studio` (or `npx @linuxdevil/studio`); see below |
+
+### Studio moved to its own package
+
+Lousho Studio is published separately as `@linuxdevil/studio` and is no longer
+part of the `@linuxdevil/lousho` tarball. What to do:
+
+- Install it once: `npm i -g @linuxdevil/studio`, then run `lousho-studio`.
+  Or run `npx @linuxdevil/studio`. `lousho studio` inside a project keeps
+  working - it finds the installed Studio and opens that folder as a
+  workspace; with none installed it prints
+  `Studio is a separate install: npx @linuxdevil/studio`.
+- Studio-wide settings and secrets moved from a project's `.lousho/` to
+  `~/.lousho/studio/`. On first launch Studio offers **Import settings and
+  keys from <workspace>** once and copies them; the originals stay put.
+- `lousho studio --prod`/`--dev` now only apply inside the SDK's own
+  repository checkout; an installed Studio is always the production build.
+- A workspace's agents run on the project's own `@linuxdevil/lousho` through
+  `lousho bridge` when the installed SDK is new enough; older SDKs make the
+  workspace read-only until updated (the banner names the minimum). Studio
+  and the SDK update independently.
+
+See [Lousho Studio](https://github.com/LinuxDevil/lousho/blob/main/docs/agent-forge.md) for the full picture.
 
 ## What 1.0 promises
 
@@ -24810,14 +25007,14 @@ surface is always a deliberate, reviewed diff.
 
 Source: docs/utilities.md
 
-Supporting helpers exported from the `lousho/utils` subpath:
+Supporting helpers exported from the `@linuxdevil/lousho/utils` subpath:
 encryption and hashing, and file storage for attachments. None of them is
 needed to build an agent; they are here for the apps around one.
 
 ## Encryption and hashing
 
 ```ts
-import { EncryptionUtils, sha256 } from 'lousho/utils';
+import { EncryptionUtils, sha256 } from '@linuxdevil/lousho/utils';
 
 const encryption = new EncryptionUtils('your-secret-key');
 const encrypted = await encryption.encrypt('sensitive data'); // fresh random salt every call
@@ -24838,7 +25035,7 @@ as-is. It is also what `StorageServiceApprovalStore` and
 `LocalStorageCheckpointStore` write through.
 
 ```ts
-import { StorageService } from 'lousho/utils';
+import { StorageService } from '@linuxdevil/lousho/utils';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
@@ -24863,11 +25060,11 @@ the same sources, the same state and the same actions, over the same
 field means, the two kinds of source, how approvals work and the server side;
 this page covers what differs.
 
-It lives in the `lousho/vue` subpath. `vue` (3.x) is an
+It lives in the `@linuxdevil/lousho/vue` subpath. `vue` (3.x) is an
 optional peer dependency: install it in the app that uses the composable.
 
 ```ts
-import { useLoushoAgent } from 'lousho/vue';
+import { useLoushoAgent } from '@linuxdevil/lousho/vue';
 
 // In <script setup>:
 const { messages, status, pendingApproval, send, stop, approve, reject, reset } = useLoushoAgent(
@@ -24916,7 +25113,7 @@ and in the template:
 
 The reducer and the stream parser are exported from this subpath too
 (`reduceAgentEvents`, `initialAgentUIState`, `parseEventStream`), the same
-ones as in `lousho/react`.
+ones as in `@linuxdevil/lousho/react`.
 
 ## Todos
 
@@ -24927,7 +25124,7 @@ shows the plan of an agent with the [todo tools](https://github.com/LinuxDevil/l
 the same stream as the chat (see [React](https://github.com/LinuxDevil/lousho/blob/main/docs/react.md#todos)).
 
 ```ts
-import { useLoushoAgent, useTodos } from 'lousho/vue';
+import { useLoushoAgent, useTodos } from '@linuxdevil/lousho/vue';
 
 // In <script setup>:
 const agent = useLoushoAgent({ url: '/api/agent' });
@@ -24957,7 +25154,7 @@ sandbox such as E2B, Daytona or Cloudflare.
 For a walkthrough, see [Build a coding agent](https://github.com/LinuxDevil/lousho/blob/main/docs/build-a-coding-agent.md).
 
 ```ts
-import { createAgent, NodeWorkspace, createFsTools, createShellTool } from 'lousho';
+import { createAgent, NodeWorkspace, createFsTools, createShellTool } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({ root: './project' }); // every path is confined to this directory
 const agent = createAgent({
@@ -24981,7 +25178,7 @@ if (paused.finishReason === 'awaiting-approval') {
 predicate that returns `false` for the commands you trust.
 
 ```ts
-import { createAgent, NodeWorkspace, createFsTools, createShellTool } from 'lousho';
+import { createAgent, NodeWorkspace, createFsTools, createShellTool } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({ root: './project' });
 const agent = createAgent({
@@ -25009,8 +25206,8 @@ the same, and `resumeAfterApproval(...)` is what `agent.approvals.resolve()`
 calls once a human approves:
 
 ```ts
-import { AgentExecutor, ToolRegistry } from 'lousho/executor';
-import { NodeWorkspace, createFsTools, createShellTool } from 'lousho';
+import { AgentExecutor, ToolRegistry } from '@linuxdevil/lousho/executor';
+import { NodeWorkspace, createFsTools, createShellTool } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({ root: '.' }); // every path is confined to this directory
 const registry = new ToolRegistry();
@@ -25064,7 +25261,7 @@ has `timedOut: true` or `aborted: true` and a `note` saying why.
 | `name`             | `'shell'` | Tool name. |
 
 ```ts
-import { createShellTool, NodeWorkspace } from 'lousho';
+import { createShellTool, NodeWorkspace } from '@linuxdevil/lousho';
 
 const shell = createShellTool(new NodeWorkspace({ root: '.' }), {
   needsApproval: (command) => !/^(ls|cat|git (status|diff|log))\b/.test(command), // read-only commands run without asking
@@ -25091,8 +25288,8 @@ agent created is deleted, one it edited or overwrote gets its content back.
 With `dryRun: true` it changes nothing and returns the same report.
 
 ```ts
-import { createAgent, createFsTools, MemoryWorkspace, WorkspaceCheckpoints } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createFsTools, MemoryWorkspace, WorkspaceCheckpoints } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const workspace = new MemoryWorkspace({ files: { 'notes.md': '# Notes\n' } });
 const checkpoints = new WorkspaceCheckpoints(workspace); // backups in memory; FileWorkspaceCheckpointStore keeps them on disk
@@ -25229,7 +25426,7 @@ A `deny` you pass **replaces** the defaults, it does not extend them: list
 'secrets']` (entry names, not paths), or pass `deny: []` to turn the check off.
 
 ```ts
-import { createFsTools, NodeWorkspace } from 'lousho';
+import { createFsTools, NodeWorkspace } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({ root: '.' });
 const tools = createFsTools(workspace, { readOnly: true, deny: ['.git', '.env', '.env.*'] });
@@ -25277,7 +25474,7 @@ Node's process launcher also adds the session variables every process needs
 them is a secret.
 
 ```ts
-import { NodeWorkspace } from 'lousho';
+import { NodeWorkspace } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({
   root: './project',
@@ -25316,7 +25513,7 @@ refused command is never offered for approval:
   returns `true` for the rest of the line (`''` when there is none):
 
   ```ts
-  import { createShellTool, NodeWorkspace } from 'lousho';
+  import { createShellTool, NodeWorkspace } from '@linuxdevil/lousho';
 
   const workspace = new NodeWorkspace({ root: '.' });
   createShellTool(workspace, {
@@ -25379,7 +25576,7 @@ you pass, nothing from the host. File tools can keep using `NodeWorkspace`
 on the same directory:
 
 ```ts
-import { createFsTools, createShellTool, NodeWorkspace, SandboxShell, SubprocessSandbox } from 'lousho';
+import { createFsTools, createShellTool, NodeWorkspace, SandboxShell, SubprocessSandbox } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({ root: './project' });
 const shell = new SandboxShell(new SubprocessSandbox({ image: 'node:20-alpine' }), { cwd: workspace.root });
@@ -25435,7 +25632,7 @@ list is only enforced when a proxy is the container's only way out.
    before; the network stays for the sandbox's next run until `close()`.
 
 ```ts
-import { createCredentialBroker, createShellTool, SandboxShell, SubprocessSandbox } from 'lousho';
+import { createCredentialBroker, createShellTool, SandboxShell, SubprocessSandbox } from '@linuxdevil/lousho';
 
 const token = 'ghp_example'; // read from your secret store; it never enters the container
 const broker = await createCredentialBroker({ rules: { 'api.github.com': { authorization: () => `Bearer ${token}` } } });
@@ -25491,7 +25688,7 @@ the SDK's tests exercise the wiring against a fake Docker client, not a live
 daemon.
 
 ```ts
-import { createShellTool, SandboxShell, SubprocessSandbox } from 'lousho';
+import { createShellTool, SandboxShell, SubprocessSandbox } from '@linuxdevil/lousho';
 
 const sandbox = new SubprocessSandbox({ image: 'node:20-alpine', network: 'none' });
 const shell = new SandboxShell(sandbox, {
@@ -25522,7 +25719,7 @@ local HTTP proxy that adds the auth headers to requests for the hosts you
 name, so the command only ever sees the proxy's address.
 
 ```ts
-import { createCredentialBroker, NodeWorkspace } from 'lousho';
+import { createCredentialBroker, NodeWorkspace } from '@linuxdevil/lousho';
 
 const token = 'ghp_example'; // read from your secret store; never passed to the command
 const broker = await createCredentialBroker({
@@ -25583,7 +25780,7 @@ custom tool could call it directly. Throw `WorkspaceError` with a readable
 message on failure.
 
 ```ts
-import { normalizeWorkspacePath, WorkspaceError, type FsProvider, type ShellProvider } from 'lousho';
+import { normalizeWorkspacePath, WorkspaceError, type FsProvider, type ShellProvider } from '@linuxdevil/lousho';
 
 // A stand-in for your remote sandbox SDK (E2B, Daytona, Cloudflare, ...).
 declare const remote: {
@@ -25639,8 +25836,8 @@ way. Its `exec` is a stub you program, and every command it receives is
 recorded. Combine it with `mockModel` for deterministic tests:
 
 ```ts
-import { createAgent, createFsTools, createShellTool, MemoryWorkspace } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createFsTools, createShellTool, MemoryWorkspace } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const workspace = new MemoryWorkspace({
   files: { 'src/math.ts': 'export const add = (a: number, b: number) => a - b;\n' },
@@ -25980,7 +26177,7 @@ A criterion's `check` names a check in the host's check registry, and the runtim
 The result, `EffectiveHarness`, holds `sources`, the composed `instructions`, the merged fields, `provenance` (for each field path, the sources its value came from) and `hash`. The hash is the sha256 of the canonical JSON of the sources, prose and fields, with keys sorted. It does not depend on key order and is stable across runs, so a revision or a span can name the exact harness it ran with. Provenance is not part of the hash.
 
 ```ts
-import { composeHarness, type HarnessLayer } from 'lousho/workspaces';
+import { composeHarness, type HarnessLayer } from '@linuxdevil/lousho/workspaces';
 
 const base: HarnessLayer = {
   source: 'workspace base',
@@ -26024,7 +26221,7 @@ Agent refs and harness profile refs have different grammars. Do not read one as
 Agent names are kebab-case. A `workspace:` or `local:` agent ref takes no range. A prefix is required. `parseAgentRef` returns `{ ok: true, ref }` or `{ ok: false, error }` and never throws:
 
 ```ts
-import { parseAgentRef } from 'lousho/workspaces';
+import { parseAgentRef } from '@linuxdevil/lousho/workspaces';
 
 const parsed = parseAgentRef('global:fact-checker@^1.0.0');
 if (parsed.ok && parsed.ref.kind === 'global') console.log(parsed.ref.name, parsed.ref.range);
@@ -26081,7 +26278,7 @@ Shared files sit under fixed patterns: `shared/instructions/<name>.md`, `shared/
 | `sandbox.required` | OR of the two. A workspace can turn it on but never off. Absent means `false` |
 
 ```ts
-import { narrowPolicy, type WorkspacePolicy } from 'lousho/workspaces';
+import { narrowPolicy, type WorkspacePolicy } from '@linuxdevil/lousho/workspaces';
 
 const ceiling: WorkspacePolicy = {
   permissions: [],
@@ -26122,8 +26319,8 @@ A workspace agent is read from its files and nothing in it is run, so settings i
 `agentPolicyOptions(policy, { attachment, agent }, registry)` returns the `createAgent` `tools` and `permissions` for one attachment, or for the main agent when `attachment` is left out. It also returns a `toolRegistry` for a workflow's `toolCall` steps, which pass `flowToolGate`, plus `secrets` by tool, `network`, `sandbox` and `warnings`. It is the only code path under `src/workspaces/runtime` that builds a toolset. `attachmentAgent()` is the only place the page runtime builds a page agent, and `createMainAgent()` the only place it builds the main agent: it takes those options, passes every tool through the host's `bindTool(descriptor, scope)` with the tool's `secrets`, `network.allowHosts` and `sandbox.required`, and the host enforces them. Under `createWorkspaceRuntime` a host without `bindTool` can run only tools whose scope grants no secrets, no hosts and no sandbox; any other tool fails the run with `LOUSHO_WORKSPACE_HOST_INVALID`, so nothing the policy narrows ever runs unenforced (see [The workspace runtime and its host](#the-workspace-runtime-and-its-host)).
 
 ```ts
-import { narrowPolicy, pagePolicy, type HostToolRegistry } from 'lousho/workspaces';
-import { defineTool } from 'lousho';
+import { narrowPolicy, pagePolicy, type HostToolRegistry } from '@linuxdevil/lousho/workspaces';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const registry: HostToolRegistry = {
@@ -26154,7 +26351,7 @@ console.log(Object.keys(page.attachments.video.tools), page.warnings);
 Every engine implements one interface, so the main agent, the wire contract and the page UI do not care which type a page runs under. These are plain JSON types.
 
 ```ts
-import type { PageEngine, PageInput, PageResult, PageRunContext } from 'lousho/workspaces';
+import type { PageEngine, PageInput, PageResult, PageRunContext } from '@linuxdevil/lousho/workspaces';
 
 async function runEngine(engine: PageEngine, input: PageInput, ctx: PageRunContext): Promise<PageResult> {
   ctx.emit({ type: 'progress', message: `running ${input.pageId} as ${engine.type}` });
@@ -26277,7 +26474,7 @@ Text is plain: `label`, `title`, `placeholder` and option labels are 1 to 500 ch
 `validateWorkspace` reports each of these as PRD012 and resolves a schema path against the page folder first.
 
 ```ts
-import { pageUiSchema, validateUiBindings } from 'lousho/workspaces';
+import { pageUiSchema, validateUiBindings } from '@linuxdevil/lousho/workspaces';
 
 const ui = pageUiSchema.parse({
   schema: 'lousho.ui/1',
@@ -26317,7 +26514,7 @@ The operations are: `create_workspace`, `set_workspace_field`, `create_page`, `r
 `set_profile` writes a workspace harness profile (`harness-profiles/<path>/harness.json` and its prose) from a `workspace:<path>` ref. `delete_profile` removes the profile's folder. `set_resource` and `delete_resource` write and remove a text resource (`.md` or `.txt`) of a page or of the base harness; list it in the harness's `context.resources` with `set_harness_field`. `set_main_model` sets the main agent's model. Check scripts, tools, workspace workflows, brand files and the policy have no operation: a criterion's `check` may name a host-registry check by name.
 
 ```ts
-import { applyOps, validateWorkspace } from 'lousho/workspaces';
+import { applyOps, validateWorkspace } from '@linuxdevil/lousho/workspaces';
 
 const result = applyOps(
   {},
@@ -26339,7 +26536,7 @@ This batch is refused: the page names the alias `writer` that `agents.json` does
 `validateWorkspace(tree, options?)` checks a whole tree across files. It never throws for invalid input and never touches the file system. It returns problems `{ severity, code, file, path, message }` in a stable order. Only `error` makes a workspace invalid; `warning` and `info` do not. `options.resolveGlobal(ref)` answers `global:` refs with that folder's files, and `options.mode: "strict"` adds only an `info` note in v1.
 
 ```ts
-import { validateWorkspace } from 'lousho/workspaces';
+import { validateWorkspace } from '@linuxdevil/lousho/workspaces';
 
 const problems = validateWorkspace({
   'workspace.json': JSON.stringify({
diff --git a/llms.txt b/llms.txt
index c8441f422..47d6ad3bc 100644
--- a/llms.txt
+++ b/llms.txt
@@ -1,4 +1,4 @@
-# lousho
+# @linuxdevil/lousho
 
 > TypeScript AI agents you can test in CI, pause for approval, and resume after a crash. Runs in your own Node process.
 
@@ -10,16 +10,16 @@
 - [API Overview](https://github.com/LinuxDevil/lousho/blob/main/docs/api-overview.md): The package root (`lousho`) exports everything below. For the complete, generated API reference (every export, signature and doc comment), build the TypeDoc site
 - [Agent Client Protocol (ACP)](https://github.com/LinuxDevil/lousho/blob/main/docs/acp.md): The Agent Client Protocol lets an editor drive a coding agent that runs as a subprocess: the editor writes JSON-RPC 2.0 requests to the agent's stdin, one JSON message per line, and reads the agent's replies and streamed updates from its stdout. Zed and other editors speak it.
 - [Agent directories](https://github.com/LinuxDevil/lousho/blob/main/docs/agent-directories.md): An agent can be defined as a directory. `loadAgentDir()` reads it and calls `createAgent()` with the options the files describe, so it returns exactly what `createAgent()` returns. The typed code API stays the source of truth: a directory is a different way to write the same options, and you can switch to code at any time without a rewrite.
-- [Agent Forge](https://github.com/LinuxDevil/lousho/blob/main/docs/agent-forge.md): Agent Forge (`apps/agent-forge`, also called the Studio) is this SDK's companion dashboard: one app with a left navigation to build and run agents, try prompts, and read what your agents did from the observe daemon.
+- [Lousho Studio](https://github.com/LinuxDevil/lousho/blob/main/docs/agent-forge.md): Lousho Studio is a local web app for building, testing and watching every agent across your projects.
 - [Agent spec v2](https://github.com/LinuxDevil/lousho/blob/main/docs/agent-spec.md): An agent spec v2 is a YAML or JSON file that describes a whole agent as plain data: model, instructions, tools, MCP servers, skills, memory, sub-agents, handoffs, guardrails, permission rules, hooks, structured output, triggers and an optional flow. Agent Forge, the Agent Author and `lousho dev` all read and write this format.
 - [AI SDK UI (`useChat`)](https://github.com/LinuxDevil/lousho/blob/main/docs/ai-sdk-ui.md): If your front end already uses the Vercel AI SDK's UI hooks (`useChat` from `@ai-sdk/react`, and the Vue, Svelte and Angular equivalents), you can keep them and run a Lousho agent behind the route. Three functions, exported from the package root, do the translation. They import nothing from `ai`, use no `node:*` module, and work on Node, Workers and any Fetch-based runtime.
 - [Approvals](https://github.com/LinuxDevil/lousho/blob/main/docs/approvals.md): Flag a tool `needsApproval` and the run pauses before calling it, until a human (or your code) approves or rejects the call. The pause is saved in an `ApprovalStore`, so the decision can come minutes or days later, from another request or another process, and the run then continues where it stopped.
-- [Route auth and principals](https://github.com/LinuxDevil/lousho/blob/main/docs/auth.md): An agent served over HTTP needs to know two things about each request: may it call at all, and who is it. `lousho/auth` answers both.
+- [Route auth and principals](https://github.com/LinuxDevil/lousho/blob/main/docs/auth.md): An agent served over HTTP needs to know two things about each request: may it call at all, and who is it. `@linuxdevil/lousho/auth` answers both.
 - [Build a coding agent](https://github.com/LinuxDevil/lousho/blob/main/docs/build-a-coding-agent.md): This page builds a terminal coding agent in the style of Claude Code: it reads and edits files in your project, runs commands, asks you before it writes a file or runs something risky, and keeps the conversation going for follow-up questions.
 - [Channels](https://github.com/LinuxDevil/lousho/blob/main/docs/channels.md): A channel connects an agent to one surface: a JSON API, a webhook, a chat app. It says how an inbound request is authenticated, which conversation it belongs to, and how the agent's reply (or an approval it pauses on) goes back to the surface. `mountChannels()` serves your channels behind one `(req, res)` handler and runs every request the same way
 - [Claude Code projects](https://github.com/LinuxDevil/lousho/blob/main/docs/claude-projects.md): A repository that already carries Claude Code's conventional files — `CLAUDE.md`, `.claude/skills/`, `.claude/agents/`, `.claude/rules/`, `.claude/scratchpad/` — loads them with `claudeProject()`: the result spreads into `createAgent()`, so the same directory drives both harnesses. Nothing is copied or renamed; Lousho reads the files where they already are.
-- [CLI](https://github.com/LinuxDevil/lousho/blob/main/docs/cli.md): Installing the package also installs the `lousho` command. It scaffolds projects, checks your setup, runs an agent locally, serves it over MCP, runs evals, shows saved traces, builds a deployable artifact and launches the Agent Forge dashboard. Run it with `npx lousho <command>` inside a project that has the SDK installed.
-- [Cloudflare Workers](https://github.com/LinuxDevil/lousho/blob/main/docs/cloudflare-workers.md): `npx lousho build --target=cloudflare-worker --agent=agent.yaml` generates a module Worker (`worker.ts`), a `wrangler.toml` and a bundle, `dist/worker.js`, that the build checks for `node:` imports. It needs `tsup` and `wrangler` installed, and it takes an agent spec file or an agent directory (`npx lousho build ./my-agent --target=cloudflare-worker`).
+- [CLI](https://github.com/LinuxDevil/lousho/blob/main/docs/cli.md): Installing the package also installs the `@linuxdevil/lousho` command. It scaffolds projects, checks your setup, runs an agent locally, serves it over MCP, runs evals, shows saved traces, builds a deployable artifact and opens Lousho Studio. Run it with `npx @linuxdevil/lousho <command>` inside a project that has the SDK installed.
+- [Cloudflare Workers](https://github.com/LinuxDevil/lousho/blob/main/docs/cloudflare-workers.md): `npx @linuxdevil/lousho build --target=cloudflare-worker --agent=agent.yaml` generates a module Worker (`worker.ts`), a `wrangler.toml` and a bundle, `dist/worker.js`, that the build checks for `node:` imports. It needs `tsup` and `wrangler` installed, and it takes an agent spec file or an agent directory (`npx @linuxdevil/lousho build ./my-agent --target=cloudflare-worker`).
 - [Code mode](https://github.com/LinuxDevil/lousho/blob/main/docs/code-mode.md): With code mode the model gets one more tool, `run_code`. Instead of calling tools one at a time, with a model round trip after each, it writes a short JavaScript program that calls the agent's tools as async functions, loops, filters and combines their results, and returns one value.
 - [Context compaction](https://github.com/LinuxDevil/lousho/blob/main/docs/compaction.md): A long agent run fills its context window mostly with tool results: file contents, search hits, API responses the model read once and no longer needs in full. Compaction keeps such a run under the model's limit in two phases: first it replaces old tool results with a short marker, and if that is not enough it replaces the oldest turns with a summary written by a (cheaper) model.
 - [How Lousho compares](https://github.com/LinuxDevil/lousho/blob/main/docs/comparison.md): This page compares Lousho with four other TypeScript agent libraries: the Vercel AI SDK (`ToolLoopAgent`), the OpenAI Agents SDK for JavaScript, Mastra and LangGraph.js. Each competitor cell comes from that project's official docs.
@@ -41,7 +41,7 @@
 - [Hosted provider tools](https://github.com/LinuxDevil/lousho/blob/main/docs/hosted-tools.md): Some model providers run tools themselves, inside the model request: OpenAI's web search, code interpreter and file search are the common ones. Put them in `tools` next to your own tools; the provider runs them, and the run reports each call in its events, keeps it on the transcript and counts it in usage.
 - [Deploying to a Hostinger VPS](https://github.com/LinuxDevil/lousho/blob/main/docs/hostinger-vps.md): The `docker` deployment target is a plain Dockerfile + bundled server, so it runs on any Docker host — including a Hostinger VPS. The hostinger-deploy example ships a complete, tested recipe: `deploy.mjs` verifies the VM through the Hostinger API, builds locally, ships the context over SSH, and runs the container — then proves the deploy with `/health` and one real `/chat` turn.
 - [Improving an agent](https://github.com/LinuxDevil/lousho/blob/main/docs/improve.md): improveAgent proposes tested edits to an agent's instructions and skills; the self-healing loop (healOnce, lousho improve) gates them, replays them, applies or queues them, and rolls them back on a regression.
-- [MCP (Model Context Protocol)](https://github.com/LinuxDevil/lousho/blob/main/docs/mcp.md): MCP works in two directions. Your agent can call the tools of MCP servers, or your agent can be an MCP server that Claude Code, Cursor and other MCP clients call. Both live in the `lousho/mcp` subpath, and `@modelcontextprotocol/sdk` is an optional peer: install it to use either direction.
+- [MCP (Model Context Protocol)](https://github.com/LinuxDevil/lousho/blob/main/docs/mcp.md): MCP works in two directions. Your agent can call the tools of MCP servers, or your agent can be an MCP server that Claude Code, Cursor and other MCP clients call. Both live in the `@linuxdevil/lousho/mcp` subpath, and `@modelcontextprotocol/sdk` is an optional peer: install it to use either direction.
 - [Memory](https://github.com/LinuxDevil/lousho/blob/main/docs/memory.md): A session remembers one conversation. Memory is what an agent keeps across conversations: a user's preferences, facts it was told, decisions made last week. You give an agent one or more named memory slots; each slot stores short text items through a provider and is keyed by a scope (one memory for everybody, one per session, or one per user).
 - [Migrating from the Vercel AI SDK](https://github.com/LinuxDevil/lousho/blob/main/docs/migrating-from-ai-sdk.md): This page is for code built on the Vercel AI SDK's agent loop: `generateText({ tools })` or `streamText({ tools })` with a step limit, or `new ToolLoopAgent({ ... })`. You can keep your models, your tools and your `useChat` front end. Three adapters bring them over without a rewrite
 - [Models, tokens and cost](https://github.com/LinuxDevil/lousho/blob/main/docs/models-and-cost.md): Dependency-free helpers for budgeting and context decisions.
@@ -66,13 +66,13 @@
 - [Structured output](https://github.com/LinuxDevil/lousho/blob/main/docs/structured-output.md): Give an agent a zod schema as `output` and its final reply becomes a typed, validated object: `result.object`. The agent can still call tools first; only the final answer has to match the schema. The `vendor/` model prefix chooses the provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 - [Sub-agents](https://github.com/LinuxDevil/lousho/blob/main/docs/sub-agents.md): A sub-agent is a separate agent - its own instructions, model, tools and skills - that a lead agent hands a self-contained task to. The sub-agent starts with a clean context (it sees only the task prompt, never the lead's conversation), works through as many steps as it needs, and its final answer comes back to the lead as one tool result.
 - [Svelte](https://github.com/LinuxDevil/lousho/blob/main/docs/svelte.md): `loushoAgent()` for Svelte is the React hook as a store: the same sources, the same state and the same actions, over the same typed event stream. Read React for what each field means, the two kinds of source, how approvals work and the server side; this page covers what differs.
-- [Testing agents](https://github.com/LinuxDevil/lousho/blob/main/docs/testing.md): `lousho/testing` ships `mockModel`: a scripted, deterministic `LLMProvider` for unit tests. You write down what the model should say on each turn, run your agent, and then assert on exactly what the agent sent to the model. No network, no API keys, no flakiness.
+- [Testing agents](https://github.com/LinuxDevil/lousho/blob/main/docs/testing.md): `@linuxdevil/lousho/testing` ships `mockModel`: a scripted, deterministic `LLMProvider` for unit tests. You write down what the model should say on each turn, run your agent, and then assert on exactly what the agent sent to the model. No network, no API keys, no flakiness.
 - [Tool search](https://github.com/LinuxDevil/lousho/blob/main/docs/tool-search.md): An agent with many tools (several MCP servers, a large internal toolkit) sends every tool definition on every model call. That costs input tokens and, past about 30 tools, makes the model worse at picking the right one. With tool search, tools marked `deferLoading` are left out of the request.
 - [Tools](https://github.com/LinuxDevil/lousho/blob/main/docs/tools.md): A tool is a typed function the model can call. Define one with `defineTool()`: the argument and result types are inferred from its zod `input`, the arguments are validated before `execute` runs, and the result drops in anywhere tools are accepted (`createAgent({ tools: [...] })`, `ToolRegistry.register(tool)`, `AgentBuilder.addTool(tool)`).
-- [Triggers](https://github.com/LinuxDevil/lousho/blob/main/docs/triggers.md): A trigger adapter turns one wake-up mechanism into an agent run. The `lousho/triggers` subpath is the extension point for your own mechanism (`TriggerAdapter`, `TriggerRegistry`) plus a few helpers shared with channels and schedules: the `WebhookAuth` shapes, `verifySlackSignature()` and `parseCronExpression()`.
-- [Troubleshooting](https://github.com/LinuxDevil/lousho/blob/main/docs/troubleshooting.md): This page starts from what you see and points to the cause, the fix and the page that explains it. First run `npx lousho doctor` (what it checks), then, if you have an error code (`LOUSHO_...`), look it up in Errors.
+- [Triggers](https://github.com/LinuxDevil/lousho/blob/main/docs/triggers.md): A trigger adapter turns one wake-up mechanism into an agent run. The `@linuxdevil/lousho/triggers` subpath is the extension point for your own mechanism (`TriggerAdapter`, `TriggerRegistry`) plus a few helpers shared with channels and schedules: the `WebhookAuth` shapes, `verifySlackSignature()` and `parseCronExpression()`.
+- [Troubleshooting](https://github.com/LinuxDevil/lousho/blob/main/docs/troubleshooting.md): This page starts from what you see and points to the cause, the fix and the page that explains it. First run `npx @linuxdevil/lousho doctor` (what it checks), then, if you have an error code (`LOUSHO_...`), look it up in Errors.
 - [Upgrading to 1.0](https://github.com/LinuxDevil/lousho/blob/main/docs/upgrading.md): Anyone with code written against `1.0.0-alpha.8` or an earlier `1.0.0-alpha.*` release. Between those alphas and the 1.0 line (the changes listed under `1.0.0-alpha.19` in the changelog, first published in `1.0.0-alpha.15`) the package's public surface was reorganized: imports moved to subpaths, dead or superseded APIs were removed, and the patch guardrails were renamed patch checks.
-- [Utilities](https://github.com/LinuxDevil/lousho/blob/main/docs/utilities.md): Supporting helpers exported from the `lousho/utils` subpath: encryption and hashing, and file storage for attachments. None of them is needed to build an agent; they are here for the apps around one.
+- [Utilities](https://github.com/LinuxDevil/lousho/blob/main/docs/utilities.md): Supporting helpers exported from the `@linuxdevil/lousho/utils` subpath: encryption and hashing, and file storage for attachments. None of them is needed to build an agent; they are here for the apps around one.
 - [Vue](https://github.com/LinuxDevil/lousho/blob/main/docs/vue.md): `useLoushoAgent()` for Vue 3 is the React hook as a composable: the same sources, the same state and the same actions, over the same typed event stream. Read React for what each field means, the two kinds of source, how approvals work and the server side; this page covers what differs.
 - [Workspace tools](https://github.com/LinuxDevil/lousho/blob/main/docs/workspace-tools.md): Workspace tools give an agent a file system and a shell, so you can build coding agents in the style of Claude Code. The tools never use `node:fs` or `node:child_process` themselves.
 - [Workspaces: architecture and contracts (v0)](https://github.com/LinuxDevil/lousho/blob/main/docs/workspaces.md): Architecture and contracts v0 for Lousho workspaces. A workspace is a folder of pages, harnesses, agent references, a shared policy and a declarative UI, with the files, fields, defaults, path rules, composition rules, error codes and JSON Schemas that exist today in lousho/workspaces.
@@ -103,5 +103,5 @@
 
 ## Optional
 
-- [Migrating to createAgent()](https://github.com/LinuxDevil/lousho/blob/main/docs/migrating-to-create-agent.md): This page is for code that uses `AgentBuilder`, `AgentExecutor`, `ToolRegistry` and `resumeAfterApproval()`: the lower-level API the SDK started with. Those exports now live at `lousho/executor` and are not going away; if you stay on them, see The executor API.
+- [Migrating to createAgent()](https://github.com/LinuxDevil/lousho/blob/main/docs/migrating-to-create-agent.md): This page is for code that uses `AgentBuilder`, `AgentExecutor`, `ToolRegistry` and `resumeAfterApproval()`: the lower-level API the SDK started with. Those exports now live at `@linuxdevil/lousho/executor` and are not going away; if you stay on them, see The executor API.
 - [Prompting and context techniques](https://github.com/LinuxDevil/lousho/blob/main/docs/prompting-techniques.md): Agent quality comes from three layers, and it is worth knowing which layer a technique lives at, because the fix for a misbehaving agent is different at each one
diff --git a/package-lock.json b/package-lock.json
index c4a6ec1f2..16c772b08 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,11 +1,11 @@
 {
-  "name": "lousho",
+  "name": "@linuxdevil/lousho",
   "version": "1.0.0-alpha.117",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "lousho",
+      "name": "@linuxdevil/lousho",
       "version": "1.0.0-alpha.117",
       "license": "MIT",
       "workspaces": [
@@ -140,25 +140,31 @@
       }
     },
     "apps/agent-forge": {
-      "name": "@lousho/agent-forge",
-      "version": "0.0.1",
+      "name": "@linuxdevil/studio",
+      "version": "0.1.0-alpha.0",
+      "license": "MIT",
       "dependencies": {
+        "@ai-sdk/anthropic": "^4.0.0",
+        "@ai-sdk/openai": "^4.0.0",
         "@codemirror/lang-javascript": "^6.2.5",
+        "@linuxdevil/lousho": "file:../..",
         "@uiw/react-codemirror": "^4.25.12",
         "@xyflow/react": "^12.12.0",
+        "ai": "^7.0.0",
         "elkjs": "^0.9.3",
         "express": "^5.2.1",
-        "lousho": "file:../..",
         "react": "^18.3.1",
         "react-dom": "^18.3.1",
         "ws": "^8.18.3",
         "yaml": "^2.9.1",
         "zod": "^3.25.76"
       },
+      "bin": {
+        "lousho-studio": "dist-server/cli.cjs"
+      },
       "devDependencies": {
-        "@ai-sdk/anthropic": "^0.0.42",
-        "@ai-sdk/openai": "^0.0.42",
         "@axe-core/playwright": "4.13.0",
+        "@codemirror/lang-javascript": "^6.2.5",
         "@fontsource-variable/inter": "^5.3.0",
         "@playwright/test": "^1.63.0",
         "@types/express": "^5.0.5",
@@ -166,18 +172,159 @@
         "@types/react-dom": "^18.3.1",
         "@types/supertest": "^6.0.3",
         "@types/ws": "^8.18.1",
+        "@uiw/react-codemirror": "^4.25.12",
         "@vitejs/plugin-react": "^4.3.4",
+        "@xyflow/react": "^12.12.0",
         "diff": "^8.0.4",
+        "express": "^5.2.1",
         "jsdom": "^25.0.1",
         "lucide-react": "^1.63.0",
         "ollama-ai-provider": "^1.2.0",
+        "react": "^18.3.1",
+        "react-dom": "^18.3.1",
         "supertest": "^7.3.0",
         "tsup": "^8.0.0",
         "tsx": "^4.23.15",
         "typescript": "^5.9.3",
         "typescript-eslint": "^8.71.0",
         "vite": "^5.4.11",
-        "vitest": "^1.0.0"
+        "vitest": "^1.0.0",
+        "ws": "^8.18.3"
+      },
+      "engines": {
+        "node": ">=22.19.0"
+      }
+    },
+    "apps/agent-forge/node_modules/@ai-sdk/anthropic": {
+      "version": "4.0.105",
+      "resolved": "https://registry.npmjs.org/@ai-sdk/anthropic/-/anthropic-4.0.105.tgz",
+      "integrity": "sha512-i6kmv6y+FGTBxOPtLRrb5I+92WcFFGubhd33CD0JeaSyFOnLJ8my4a9olkAgyR9fACHMzxFBmoEHd0uO4i72bA==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@ai-sdk/provider": "4.0.38",
+        "@ai-sdk/provider-utils": "5.0.81"
+      },
+      "engines": {
+        "node": ">=22"
+      },
+      "peerDependencies": {
+        "zod": "^3.25.76 || ^4.1.8"
+      }
+    },
+    "apps/agent-forge/node_modules/@ai-sdk/anthropic/node_modules/@ai-sdk/provider-utils": {
+      "version": "5.0.81",
+      "resolved": "https://registry.npmjs.org/@ai-sdk/provider-utils/-/provider-utils-5.0.81.tgz",
+      "integrity": "sha512-pfvvdQ3d1WxdBuug/mnGEP6E48cPokwD8dMBnsFeeAUp0/rb/H2aj0f3mwOiY62gu/Cu5GO44e+SE5nDHyBWMA==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@ai-sdk/provider": "4.0.38",
+        "@standard-schema/spec": "^1.1.0",
+        "@workflow/serde": "4.1.0",
+        "eventsource-parser": "^3.0.8"
+      },
+      "engines": {
+        "node": ">=22"
+      },
+      "peerDependencies": {
+        "zod": "^3.25.76 || ^4.1.8"
+      }
+    },
+    "apps/agent-forge/node_modules/@ai-sdk/openai": {
+      "version": "4.0.118",
+      "resolved": "https://registry.npmjs.org/@ai-sdk/openai/-/openai-4.0.118.tgz",
+      "integrity": "sha512-pBsFeB+IudrX96P0ic9AO/1NPnfB6IyoS2B2pnhBJ/Ovt4bsvAmBOPeUxwEfYbQyfetJdVFep9sfYX42uVX3SQ==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@ai-sdk/provider": "4.0.38",
+        "@ai-sdk/provider-utils": "5.0.81"
+      },
+      "engines": {
+        "node": ">=22"
+      },
+      "peerDependencies": {
+        "zod": "^3.25.76 || ^4.1.8"
+      }
+    },
+    "apps/agent-forge/node_modules/@ai-sdk/openai/node_modules/@ai-sdk/provider-utils": {
+      "version": "5.0.81",
+      "resolved": "https://registry.npmjs.org/@ai-sdk/provider-utils/-/provider-utils-5.0.81.tgz",
+      "integrity": "sha512-pfvvdQ3d1WxdBuug/mnGEP6E48cPokwD8dMBnsFeeAUp0/rb/H2aj0f3mwOiY62gu/Cu5GO44e+SE5nDHyBWMA==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@ai-sdk/provider": "4.0.38",
+        "@standard-schema/spec": "^1.1.0",
+        "@workflow/serde": "4.1.0",
+        "eventsource-parser": "^3.0.8"
+      },
+      "engines": {
+        "node": ">=22"
+      },
+      "peerDependencies": {
+        "zod": "^3.25.76 || ^4.1.8"
+      }
+    },
+    "apps/agent-forge/node_modules/@ai-sdk/provider": {
+      "version": "4.0.38",
+      "resolved": "https://registry.npmjs.org/@ai-sdk/provider/-/provider-4.0.38.tgz",
+      "integrity": "sha512-GElz70UUCuDFFyD6m6aQJFgRY0HEABQzB5otzgkrisYaF5mnss7o0upAmbBTSD6KWiM9h7lZm1ls2c7xzHR8CA==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "json-schema": "^0.4.0"
+      },
+      "engines": {
+        "node": ">=22"
+      }
+    },
+    "apps/agent-forge/node_modules/ai": {
+      "version": "7.0.173",
+      "resolved": "https://registry.npmjs.org/ai/-/ai-7.0.173.tgz",
+      "integrity": "sha512-dLea37zT1h7cjkUsBprU4Rq35HJqhtHHaq1jTAXjHQoyfpeswpgCrhjZJWdWc10gjEAxmz114py7iLGQ3xIMxw==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@ai-sdk/gateway": "4.0.146",
+        "@ai-sdk/provider": "4.0.38",
+        "@ai-sdk/provider-utils": "5.0.81"
+      },
+      "engines": {
+        "node": ">=22"
+      },
+      "peerDependencies": {
+        "zod": "^3.25.76 || ^4.1.8"
+      }
+    },
+    "apps/agent-forge/node_modules/ai/node_modules/@ai-sdk/gateway": {
+      "version": "4.0.146",
+      "resolved": "https://registry.npmjs.org/@ai-sdk/gateway/-/gateway-4.0.146.tgz",
+      "integrity": "sha512-rJ5NQSyjnpo6HSBEYc9Ff6k1EROUuB7KeAfHYVbVDsk68ynY0Eb8JeWflZKXlT6NhYgqyCiBDxE5blXWACXMKQ==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@ai-sdk/provider": "4.0.38",
+        "@ai-sdk/provider-utils": "5.0.81",
+        "@vercel/oidc": "3.2.0"
+      },
+      "engines": {
+        "node": ">=22"
+      },
+      "peerDependencies": {
+        "zod": "^3.25.76 || ^4.1.8"
+      }
+    },
+    "apps/agent-forge/node_modules/ai/node_modules/@ai-sdk/provider-utils": {
+      "version": "5.0.81",
+      "resolved": "https://registry.npmjs.org/@ai-sdk/provider-utils/-/provider-utils-5.0.81.tgz",
+      "integrity": "sha512-pfvvdQ3d1WxdBuug/mnGEP6E48cPokwD8dMBnsFeeAUp0/rb/H2aj0f3mwOiY62gu/Cu5GO44e+SE5nDHyBWMA==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@ai-sdk/provider": "4.0.38",
+        "@standard-schema/spec": "^1.1.0",
+        "@workflow/serde": "4.1.0",
+        "eventsource-parser": "^3.0.8"
+      },
+      "engines": {
+        "node": ">=22"
+      },
+      "peerDependencies": {
+        "zod": "^3.25.76 || ^4.1.8"
       }
     },
     "node_modules/@ai-sdk/anthropic": {
@@ -943,7 +1090,6 @@
       "integrity": "sha512-RgHBCvtjbOK2gXSNBNIkNoEc9qoVEtau3hj8gEqKQuL3HZAibKarWFEI3Lfm6EYKkLalOh8eSrj9b+ch9H/VBA==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@babel/code-frame": "^7.29.7",
         "@babel/generator": "^7.29.7",
@@ -1181,6 +1327,7 @@
       "version": "7.29.7",
       "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.29.7.tgz",
       "integrity": "sha512-Nq8OhGWiZIZGV6hLHoyAKLLcJihP/xFeBMGJoUrxTX2psI8dCifzLhZISFb+VWS3wFMRDmCGw5R+dOySCqPLhw==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=6.9.0"
@@ -1387,6 +1534,7 @@
       "version": "6.20.3",
       "resolved": "https://registry.npmjs.org/@codemirror/autocomplete/-/autocomplete-6.20.3.tgz",
       "integrity": "sha512-tlosUqb+3BbxCxZdu4tKeRghPFC+QM7q4X5YhKV2eCmPG+1r2F3f4AaSz5sCrFqUtX4Jh20VFTKecl16MgiV9g==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@codemirror/language": "^6.0.0",
@@ -1399,6 +1547,7 @@
       "version": "6.11.1",
       "resolved": "https://registry.npmjs.org/@codemirror/commands/-/commands-6.11.1.tgz",
       "integrity": "sha512-O/4hG3SC1YwcmQ0d2UVNDs+AsaNWd1iHVxbTeEBuqH+6bExAiPK3iS/BvpY6rZGURALv4ZD3sIgcCmRvw3ehBg==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@codemirror/language": "^6.0.0",
@@ -1411,6 +1560,7 @@
       "version": "6.2.5",
       "resolved": "https://registry.npmjs.org/@codemirror/lang-javascript/-/lang-javascript-6.2.5.tgz",
       "integrity": "sha512-zD4e5mS+50htS7F+TYjBPsiIFGanfVqg4HyUz6WNFikgOPf2BgKlx+TQedI1w6n/IqRBVBbBWmGFdLB/7uxO4A==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@codemirror/autocomplete": "^6.0.0",
@@ -1426,6 +1576,7 @@
       "version": "6.12.4",
       "resolved": "https://registry.npmjs.org/@codemirror/language/-/language-6.12.4.tgz",
       "integrity": "sha512-1q4PaT+o6PbgpkJt4Q8Fv5XJxTy4FUZ4MWETtyiDw3J0Pyr9E2vqcKL+k9wcvjNTIsauxvE7OfmWj3FRPHQ76A==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@codemirror/state": "^6.0.0",
@@ -1440,6 +1591,7 @@
       "version": "6.9.7",
       "resolved": "https://registry.npmjs.org/@codemirror/lint/-/lint-6.9.7.tgz",
       "integrity": "sha512-28/+iWLYxKxsvGYhSYL7zaCZqLz5+FFFDq9tVsvGv9kv8RY4fFAchJ5WX9M3YrrRlTIsECjsXPqeNgnSmNP2dg==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@codemirror/state": "^6.0.0",
@@ -1451,6 +1603,7 @@
       "version": "6.7.2",
       "resolved": "https://registry.npmjs.org/@codemirror/search/-/search-6.7.2.tgz",
       "integrity": "sha512-gUYkYhT2+n/+VGZ+8EzE5WFkYZUZYm1VOKDudIsNqh42uRVQJ0a6Yss9sdKT3MeOYfuL1N6AZA57oza0Oyr0LA==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@codemirror/state": "^6.0.0",
@@ -1462,6 +1615,7 @@
       "version": "6.7.6",
       "resolved": "https://registry.npmjs.org/@codemirror/state/-/state-6.7.6.tgz",
       "integrity": "sha512-kAz+AncRtKuIknedxT1bq4XwXv4UowhbkHU1myPrtVb/jZtImWuV5BXzv5vK6i3kYACsdiZiQKFQQ5Mq7elW8w==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@marijn/find-cluster-break": "^1.0.0"
@@ -1471,6 +1625,7 @@
       "version": "6.1.3",
       "resolved": "https://registry.npmjs.org/@codemirror/theme-one-dark/-/theme-one-dark-6.1.3.tgz",
       "integrity": "sha512-NzBdIvEJmx6fjeremiGp3t/okrLPYT0d9orIc7AFun8oZcRk58aejkqhv6spnz4MLAevrKNPMQYXEWMg4s+sKA==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@codemirror/language": "^6.0.0",
@@ -1483,8 +1638,8 @@
       "version": "6.43.13",
       "resolved": "https://registry.npmjs.org/@codemirror/view/-/view-6.43.13.tgz",
       "integrity": "sha512-sihaFrUzAsYBQsL9J2t69y8nfMQGwcYmggAZsk+kjPbjYZMyuf2hU8tUNTZ+P+isb6XRr8JE22TZlJxBoVdH1A==",
+      "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@codemirror/state": "^6.7.0",
         "crelt": "^1.0.6",
@@ -1604,7 +1759,6 @@
         }
       ],
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=18"
       },
@@ -1628,7 +1782,6 @@
         }
       ],
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -3974,12 +4127,14 @@
       "version": "1.5.3",
       "resolved": "https://registry.npmjs.org/@lezer/common/-/common-1.5.3.tgz",
       "integrity": "sha512-H0iErY4e43LpXbYDyBci5W4v/RwTgGV3YzYOlJPiGZ8RY8w51kVE+xLn1tg3Z6UmSfyETvtsUK3r7YsgDQEI7Q==",
+      "dev": true,
       "license": "MIT"
     },
     "node_modules/@lezer/highlight": {
       "version": "1.2.5",
       "resolved": "https://registry.npmjs.org/@lezer/highlight/-/highlight-1.2.5.tgz",
       "integrity": "sha512-O1GMVKgtf5YspFaRzpmqkVgMtIk2HG9uMAbH6wdAIdNh3TVzCsch/+cRi+6l2//UGDKe6NB9BW3cvuR5ezMQ0w==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@lezer/common": "^1.3.0"
@@ -3989,6 +4144,7 @@
       "version": "1.5.5",
       "resolved": "https://registry.npmjs.org/@lezer/javascript/-/javascript-1.5.5.tgz",
       "integrity": "sha512-sWg4yX1J6XW67AaAynVt0iwF0M5c+np36TEu+P2ifAJ8haRYvHnWDV28r1jdwnJehWCwXECutAUy56K4RBZIyg==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@lezer/common": "^1.2.0",
@@ -4000,12 +4156,17 @@
       "version": "1.4.10",
       "resolved": "https://registry.npmjs.org/@lezer/lr/-/lr-1.4.10.tgz",
       "integrity": "sha512-rnCpTIBafOx4mRp43xOxDJbFipJm/c0cia/V5TiGlhmMa+wsSdoGmUN3w5Bqrks/09Q/D4tNAmWaT8p6NRi77A==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@lezer/common": "^1.0.0"
       }
     },
-    "node_modules/@lousho/agent-forge": {
+    "node_modules/@linuxdevil/lousho": {
+      "resolved": "",
+      "link": true
+    },
+    "node_modules/@linuxdevil/studio": {
       "resolved": "apps/agent-forge",
       "link": true
     },
@@ -4017,6 +4178,7 @@
       "version": "1.0.4",
       "resolved": "https://registry.npmjs.org/@marijn/find-cluster-break/-/find-cluster-break-1.0.4.tgz",
       "integrity": "sha512-Wy0V7+SGUjnF9/TkiM1hKVDPj7jKXduPNboMVtHTA8dySMURWqfg/JZ9E2Sq8JgSJmkl7k7Qe9FLeMSrSraWmQ==",
+      "dev": true,
       "license": "MIT"
     },
     "node_modules/@microsoft/api-extractor": {
@@ -4252,7 +4414,6 @@
       "integrity": "sha512-gLyJlPHPZYdAk1JENA9LeHejZe1Ti77/pTeFm/nMXmQH/HFZlcS/O2XJB+L8fkbrNSqhdtlvjBVjxwUYanNH5Q==",
       "dev": true,
       "license": "Apache-2.0",
-      "peer": true,
       "engines": {
         "node": ">=8.0.0"
       }
@@ -5078,7 +5239,6 @@
       "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "fast-deep-equal": "^3.1.3",
         "fast-uri": "^3.0.1",
@@ -5397,7 +5557,6 @@
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/@standard-schema/spec/-/spec-1.1.0.tgz",
       "integrity": "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/argparse": {
@@ -5484,12 +5643,14 @@
       "version": "3.1.3",
       "resolved": "https://registry.npmjs.org/@types/d3-color/-/d3-color-3.1.3.tgz",
       "integrity": "sha512-iO90scth9WAbmgv7ogoq57O9YpKmFBbmoEoCHDB2xMBY0+/KVrqAaCDyCE16dUspeOvIxFFRI+0sEtqDqy2b4A==",
+      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/d3-drag": {
       "version": "3.0.7",
       "resolved": "https://registry.npmjs.org/@types/d3-drag/-/d3-drag-3.0.7.tgz",
       "integrity": "sha512-HE3jVKlzU9AaMazNufooRJ5ZpWmLIoc90A37WU2JMmeq28w1FQqCZswHZ3xR+SuxYftzHq6WU6KJHvqxKzTxxQ==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@types/d3-selection": "*"
@@ -5499,6 +5660,7 @@
       "version": "3.0.4",
       "resolved": "https://registry.npmjs.org/@types/d3-interpolate/-/d3-interpolate-3.0.4.tgz",
       "integrity": "sha512-mgLPETlrpVV1YRJIglr4Ez47g7Yxjl1lj7YKsiMCb27VJH9W8NVM6Bb9d8kkpG/uAQS5AmbA48q2IAolKKo1MA==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@types/d3-color": "*"
@@ -5508,12 +5670,14 @@
       "version": "3.0.12",
       "resolved": "https://registry.npmjs.org/@types/d3-selection/-/d3-selection-3.0.12.tgz",
       "integrity": "sha512-Qe/KWYhEiIIxGs7HrAAjMfShxKldx19SJtr5zu53f3afPsdZNz7HHtdTLXo/kqeiWNXVycI24kSnfzBYkTzpgw==",
+      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/d3-transition": {
       "version": "3.0.9",
       "resolved": "https://registry.npmjs.org/@types/d3-transition/-/d3-transition-3.0.9.tgz",
       "integrity": "sha512-uZS5shfxzO3rGlu0cC3bjmMFKsXv+SmZZcgp0KD22ts4uGXp5EVYGzu/0YdwZeKmddhcAccYtREJKkPfXkZuCg==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@types/d3-selection": "*"
@@ -5523,6 +5687,7 @@
       "version": "3.0.9",
       "resolved": "https://registry.npmjs.org/@types/d3-zoom/-/d3-zoom-3.0.9.tgz",
       "integrity": "sha512-0sE1406XBYJGiqD3AusTl9ZqC//2mIXix51tbom25gDCA8ri4xnSZg28CaSE8Srl6FClqABUKfsn0qghgdepMA==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@types/d3-interpolate": "*",
@@ -5676,7 +5841,7 @@
       "version": "15.7.15",
       "resolved": "https://registry.npmjs.org/@types/prop-types/-/prop-types-15.7.15.tgz",
       "integrity": "sha512-F6bEyamV9jKGAFBEmlQnesRPGOQqS2+Uwi0Em15xenOxHaf2hv6L8YCVn3rPdPJOiJfPiCnLIRyvwVaqMY3MIw==",
-      "devOptional": true,
+      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/qs": {
@@ -5697,9 +5862,8 @@
       "version": "18.3.31",
       "resolved": "https://registry.npmjs.org/@types/react/-/react-18.3.31.tgz",
       "integrity": "sha512-vfEqpXTvwT91yhmwdfouStN2hSKwTvyRs8qpLfADyrq/kxDw0hZM7Wk9Ug1FELj8hIby+S/+kQCSRFF32nv2Qw==",
-      "devOptional": true,
+      "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@types/prop-types": "*",
         "csstype": "^3.2.2"
@@ -5709,9 +5873,8 @@
       "version": "18.3.7",
       "resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-18.3.7.tgz",
       "integrity": "sha512-MEe3UeoENYVFXzoXEWsvcpg6ZvlrFNlOQ7EOsvhI3CfAXwzPfO8Qwuxd40nepsYKqyyVQnTdEfv68q91yLcKrQ==",
-      "devOptional": true,
+      "dev": true,
       "license": "MIT",
-      "peer": true,
       "peerDependencies": {
         "@types/react": "^18.0.0"
       }
@@ -5857,7 +6020,6 @@
       "integrity": "sha512-CG4nPk1f2zc8yw4pALqHsFYH2hdo+h1T9daSp21+Hnxi9LOE3GT9hAfTKJCBXVNM2GmYs1eMEP615wPoeOgk3A==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@typescript-eslint/scope-manager": "8.71.0",
         "@typescript-eslint/types": "8.71.0",
@@ -6439,6 +6601,7 @@
       "version": "4.25.12",
       "resolved": "https://registry.npmjs.org/@uiw/codemirror-extensions-basic-setup/-/codemirror-extensions-basic-setup-4.25.12.tgz",
       "integrity": "sha512-wR5lz7jbVcBGyiiLEObAmDikcc39KNqrrd4bdUhav85WZu48ttgnSf1YV+grHuMsj5l/WCw6u+r9ZuSfURJgiA==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@codemirror/autocomplete": "^6.0.0",
@@ -6466,6 +6629,7 @@
       "version": "4.25.12",
       "resolved": "https://registry.npmjs.org/@uiw/react-codemirror/-/react-codemirror-4.25.12.tgz",
       "integrity": "sha512-RE0Gj/QesD7/JWPnJREG8Kq8brGv2NAH17iUECcBrLkqXzzEAgsj/4Qqvz/OlK8XWKmzlsenLRkObT9H+gYQ0w==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@babel/runtime": "^7.18.6",
@@ -6492,7 +6656,6 @@
       "version": "3.2.0",
       "resolved": "https://registry.npmjs.org/@vercel/oidc/-/oidc-3.2.0.tgz",
       "integrity": "sha512-UycprH3T6n3jH0k44NHMa7pnFHGu/N05MjojYr+Mc6I7obkoLIJujSWwin1pCvdy/eOxrI/l3uDLQsmcrOb4ug==",
-      "dev": true,
       "license": "Apache-2.0",
       "engines": {
         "node": ">= 20"
@@ -6773,13 +6936,13 @@
       "version": "4.1.0",
       "resolved": "https://registry.npmjs.org/@workflow/serde/-/serde-4.1.0.tgz",
       "integrity": "sha512-pav4F2BoirECWR7Nf1TKt+2eETcBj7jj4cBefQ8VXQCA6NPkaKeLfj/zMgi+3zYV5ZIBT4GuUiphsj0/b9hPQQ==",
-      "dev": true,
       "license": "Apache-2.0"
     },
     "node_modules/@xyflow/react": {
       "version": "12.12.0",
       "resolved": "https://registry.npmjs.org/@xyflow/react/-/react-12.12.0.tgz",
       "integrity": "sha512-74oXI0Rgm1Eu33cHQAd74J6oVgCH9mbFyTVQbsGgp2kmWwh0HdtBr2VP04z8mbPD+M/xO69nqG5dDEt7/EN2rQ==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@xyflow/system": "0.0.83",
@@ -6805,6 +6968,7 @@
       "version": "0.0.83",
       "resolved": "https://registry.npmjs.org/@xyflow/system/-/system-0.0.83.tgz",
       "integrity": "sha512-a//eDjez3WZF47aaPTfVUDD0OINOq+WVwBZCRTqG+m0a5euX8EwlJ4jMY1Wxz0Ocj4xOeekJ70V22Pq0ll8RJw==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@types/d3-drag": "^3.0.7",
@@ -6822,6 +6986,7 @@
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/accepts/-/accepts-2.0.0.tgz",
       "integrity": "sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "mime-types": "^3.0.0",
@@ -6837,7 +7002,6 @@
       "integrity": "sha512-lGq+9yr1/GuAWaVYIHRjvvySG5/4VfKIvC8EWxStPdcDh/Ka7FG3twP6v4d5BkravUilhIAsG4Qj83t02LWUPQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -7299,6 +7463,7 @@
       "version": "2.3.0",
       "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.3.0.tgz",
       "integrity": "sha512-2cGmJupaNgg+QUwVLAucDuWuoMZ6EX9iHDRswZ5lsNYEmwPaRknMPCLZz07yTzVq/83p4o/wzbDZbBrTvGGTIw==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "bytes": "^3.1.2",
@@ -7323,6 +7488,7 @@
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/content-type/-/content-type-2.1.0.tgz",
       "integrity": "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=18"
@@ -7370,7 +7536,6 @@
         }
       ],
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "baseline-browser-mapping": "^2.11.26",
         "caniuse-lite": "^1.0.30001812",
@@ -7447,6 +7612,7 @@
       "version": "3.1.2",
       "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz",
       "integrity": "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.8"
@@ -7490,6 +7656,7 @@
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/call-bind-apply-helpers/-/call-bind-apply-helpers-1.0.2.tgz",
       "integrity": "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "es-errors": "^1.3.0",
@@ -7503,6 +7670,7 @@
       "version": "1.0.4",
       "resolved": "https://registry.npmjs.org/call-bound/-/call-bound-1.0.4.tgz",
       "integrity": "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "call-bind-apply-helpers": "^1.0.2",
@@ -7608,6 +7776,7 @@
       "version": "5.0.5",
       "resolved": "https://registry.npmjs.org/classcat/-/classcat-5.0.5.tgz",
       "integrity": "sha512-JhZUT7JFcQy/EzW605k/ktHtncoo9vnyW/2GspNYwFlN1C/WmjuV/xtS04e9SOkL2sTdw0VAZ2UGCcQ9lR6p6w==",
+      "dev": true,
       "license": "MIT"
     },
     "node_modules/cliui": {
@@ -7708,6 +7877,7 @@
       "version": "6.0.2",
       "resolved": "https://registry.npmjs.org/codemirror/-/codemirror-6.0.2.tgz",
       "integrity": "sha512-VhydHotNW5w1UGK0Qj96BwSk/Zqbp9WbnyK2W/eVMv4QyF41INRGpjUhFJY7/uDNuudSc33a/PKr4iDqRduvHw==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@codemirror/autocomplete": "^6.0.0",
@@ -7800,6 +7970,7 @@
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-1.1.0.tgz",
       "integrity": "sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=18"
@@ -7813,6 +7984,7 @@
       "version": "1.0.5",
       "resolved": "https://registry.npmjs.org/content-type/-/content-type-1.0.5.tgz",
       "integrity": "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.6"
@@ -7829,6 +8001,7 @@
       "version": "0.7.2",
       "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.7.2.tgz",
       "integrity": "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.6"
@@ -7838,6 +8011,7 @@
       "version": "1.2.2",
       "resolved": "https://registry.npmjs.org/cookie-signature/-/cookie-signature-1.2.2.tgz",
       "integrity": "sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=6.6.0"
@@ -7891,6 +8065,7 @@
       "version": "1.0.7",
       "resolved": "https://registry.npmjs.org/crelt/-/crelt-1.0.7.tgz",
       "integrity": "sha512-aK6BbWfhf4U/wCcLHKPJl/xa6VkVstRaPywWtMKGwuOLc/wZTyQYuoxgvZnNsBvv7Kg3YTBQYYBCggcviQczuA==",
+      "dev": true,
       "license": "MIT"
     },
     "node_modules/cross-spawn": {
@@ -7933,13 +8108,14 @@
       "version": "3.2.3",
       "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz",
       "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==",
-      "devOptional": true,
+      "dev": true,
       "license": "MIT"
     },
     "node_modules/d3-color": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/d3-color/-/d3-color-3.1.0.tgz",
       "integrity": "sha512-zg/chbXyeBtMQ1LbD/WSoW2DpC3I0mpmPdW+ynRTj/x2DAWYrIY7qeZIHidozwV24m4iavr15lNwIwLxRmOxhA==",
+      "dev": true,
       "license": "ISC",
       "engines": {
         "node": ">=12"
@@ -7949,6 +8125,7 @@
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/d3-dispatch/-/d3-dispatch-3.0.1.tgz",
       "integrity": "sha512-rzUyPU/S7rwUflMyLc1ETDeBj0NRuHKKAcvukozwhshr6g6c5d8zh4c2gQjY2bZ0dXeGLWc1PF174P2tVvKhfg==",
+      "dev": true,
       "license": "ISC",
       "engines": {
         "node": ">=12"
@@ -7958,6 +8135,7 @@
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/d3-drag/-/d3-drag-3.0.0.tgz",
       "integrity": "sha512-pWbUJLdETVA8lQNJecMxoXfH6x+mO2UQo8rSmZ+QqxcbyA3hfeprFgIT//HW2nlHChWeIIMwS2Fq+gEARkhTkg==",
+      "dev": true,
       "license": "ISC",
       "dependencies": {
         "d3-dispatch": "1 - 3",
@@ -7971,6 +8149,7 @@
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/d3-ease/-/d3-ease-3.0.1.tgz",
       "integrity": "sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w==",
+      "dev": true,
       "license": "BSD-3-Clause",
       "engines": {
         "node": ">=12"
@@ -7980,6 +8159,7 @@
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/d3-interpolate/-/d3-interpolate-3.0.1.tgz",
       "integrity": "sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g==",
+      "dev": true,
       "license": "ISC",
       "dependencies": {
         "d3-color": "1 - 3"
@@ -7992,8 +8172,8 @@
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/d3-selection/-/d3-selection-3.0.0.tgz",
       "integrity": "sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==",
+      "dev": true,
       "license": "ISC",
-      "peer": true,
       "engines": {
         "node": ">=12"
       }
@@ -8002,6 +8182,7 @@
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/d3-timer/-/d3-timer-3.0.1.tgz",
       "integrity": "sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==",
+      "dev": true,
       "license": "ISC",
       "engines": {
         "node": ">=12"
@@ -8011,6 +8192,7 @@
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/d3-transition/-/d3-transition-3.0.1.tgz",
       "integrity": "sha512-ApKvfjsSR6tg06xrL434C0WydLr7JewBB3V+/39RMHsaXTOG0zmt/OAXeng5M5LBm0ojmxJrpomQVZ1aPvBL4w==",
+      "dev": true,
       "license": "ISC",
       "dependencies": {
         "d3-color": "1 - 3",
@@ -8030,6 +8212,7 @@
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/d3-zoom/-/d3-zoom-3.0.0.tgz",
       "integrity": "sha512-b8AmV3kfQaqWAuacbPuNbL6vahnOJflOhexLzMMNLga62+/nh0JzvJ0aO/5a5MVgUFGS7Hu1P9P03o3fJkDCyw==",
+      "dev": true,
       "license": "ISC",
       "dependencies": {
         "d3-dispatch": "1 - 3",
@@ -8107,6 +8290,7 @@
       "version": "4.4.3",
       "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
       "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "ms": "^2.1.3"
@@ -8161,6 +8345,7 @@
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz",
       "integrity": "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.8"
@@ -8262,6 +8447,7 @@
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",
       "integrity": "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "call-bind-apply-helpers": "^1.0.1",
@@ -8293,6 +8479,7 @@
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/ee-first/-/ee-first-1.1.1.tgz",
       "integrity": "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==",
+      "dev": true,
       "license": "MIT"
     },
     "node_modules/electron-to-chromium": {
@@ -8319,6 +8506,7 @@
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/encodeurl/-/encodeurl-2.0.0.tgz",
       "integrity": "sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.8"
@@ -8361,6 +8549,7 @@
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
       "integrity": "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.4"
@@ -8370,6 +8559,7 @@
       "version": "1.3.0",
       "resolved": "https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz",
       "integrity": "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.4"
@@ -8379,6 +8569,7 @@
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.2.tgz",
       "integrity": "sha512-HWcBoN6NileqtSydK2FqHbS/LoDd2pqrnQHLyJzBj4kOp/ky2MWMN694xOfkK8/SnUsW2DH7EfyVlydKCsm1Zw==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "es-errors": "^1.3.0"
@@ -8410,7 +8601,6 @@
       "dev": true,
       "hasInstallScript": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "esbuild": "bin/esbuild"
       },
@@ -8460,6 +8650,7 @@
       "version": "1.0.3",
       "resolved": "https://registry.npmjs.org/escape-html/-/escape-html-1.0.3.tgz",
       "integrity": "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==",
+      "dev": true,
       "license": "MIT"
     },
     "node_modules/escape-string-regexp": {
@@ -8481,7 +8672,6 @@
       "integrity": "sha512-P7a6UEEqb9G95MYAtqkmsTbVXIYyzIfl6NGOIJk162PaahFxFyeGcrlXYFSiagECg4sEm8IseJdZBKR3rx6MsQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "workspaces": [
         "packages/*"
       ],
@@ -8720,6 +8910,7 @@
       "version": "1.8.1",
       "resolved": "https://registry.npmjs.org/etag/-/etag-1.8.1.tgz",
       "integrity": "sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.6"
@@ -8742,7 +8933,6 @@
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/eventsource-parser/-/eventsource-parser-3.1.1.tgz",
       "integrity": "sha512-EKN1vKAMcZ8MlYMpaNuxN6R9yakzH6uajHcHVTqWJzvu5pWw9DyhbP35HH8MVBQ+dZjAfDxk+A8NiR9KWaXiyQ==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=18.0.0"
@@ -8776,8 +8966,8 @@
       "version": "5.2.1",
       "resolved": "https://registry.npmjs.org/express/-/express-5.2.1.tgz",
       "integrity": "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==",
+      "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "accepts": "^2.0.0",
         "body-parser": "^2.2.1",
@@ -9036,6 +9226,7 @@
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-2.1.1.tgz",
       "integrity": "sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "debug": "^4.4.0",
@@ -9193,6 +9384,7 @@
       "version": "0.2.0",
       "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz",
       "integrity": "sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.6"
@@ -9202,6 +9394,7 @@
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/fresh/-/fresh-2.0.0.tgz",
       "integrity": "sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.8"
@@ -9255,6 +9448,7 @@
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz",
       "integrity": "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==",
+      "dev": true,
       "license": "MIT",
       "funding": {
         "url": "https://github.com/sponsors/ljharb"
@@ -9337,6 +9531,7 @@
       "version": "1.3.0",
       "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz",
       "integrity": "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "call-bind-apply-helpers": "^1.0.2",
@@ -9361,6 +9556,7 @@
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/get-proto/-/get-proto-1.0.1.tgz",
       "integrity": "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "dunder-proto": "^1.0.1",
@@ -9450,6 +9646,7 @@
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz",
       "integrity": "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.4"
@@ -9489,6 +9686,7 @@
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz",
       "integrity": "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.4"
@@ -9530,6 +9728,7 @@
       "version": "2.0.4",
       "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.4.tgz",
       "integrity": "sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "function-bind": "^1.1.2"
@@ -9554,7 +9753,6 @@
       "integrity": "sha512-dQuLsa5oO+47QVMVMaaD9cIv8ctmVtK1iRvwWngkfloFJMeFeuoUFDswIqZGxmGX3hrRzREgEArjkK9OgsQEhA==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=16.9.0"
       }
@@ -9613,6 +9811,7 @@
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz",
       "integrity": "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "depd": "~2.0.0",
@@ -9687,6 +9886,7 @@
       "version": "0.7.3",
       "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.3.tgz",
       "integrity": "sha512-IKXpvIzjnC9XTAUbVBcMfGS0EPaIXtW6v+zr+RRp+hqULEpo0owZax6wyRwPOJbWbzjYspQwusTsfVr0ifh4uQ==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "safer-buffer": ">= 2.1.2 < 3.0.0"
@@ -9766,6 +9966,7 @@
       "version": "2.0.4",
       "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
       "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
+      "dev": true,
       "license": "ISC"
     },
     "node_modules/ip-address": {
@@ -9782,6 +9983,7 @@
       "version": "1.9.1",
       "resolved": "https://registry.npmjs.org/ipaddr.js/-/ipaddr.js-1.9.1.tgz",
       "integrity": "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.10"
@@ -9847,6 +10049,7 @@
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/is-promise/-/is-promise-4.0.0.tgz",
       "integrity": "sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==",
+      "dev": true,
       "license": "MIT"
     },
     "node_modules/is-stream": {
@@ -10088,7 +10291,6 @@
       "version": "0.4.0",
       "resolved": "https://registry.npmjs.org/json-schema/-/json-schema-0.4.0.tgz",
       "integrity": "sha512-es94M3nTIfsEPisRafak+HDLfHXnKBhV3vU5eqPcS3flIWqcxJWgXHXiey3YrpaNsanY5ei1VoYEbOzijuq9BA==",
-      "devOptional": true,
       "license": "(AFL-2.1 OR BSD-3-Clause)"
     },
     "node_modules/json-schema-to-ts": {
@@ -10199,7 +10401,6 @@
       "integrity": "sha512-CYDD3SOtsHtyXeEORYRx2qBtpDJFjRTGXUtmNEMGyzYOKj1TE3tycdlho7kA1Ufx9OYWZzg52QFBGALTirzDSw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@keyv/serialize": "^1.1.1"
       }
@@ -10336,6 +10537,7 @@
       "version": "1.4.0",
       "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz",
       "integrity": "sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "js-tokens": "^3.0.0 || ^4.0.0"
@@ -10348,6 +10550,7 @@
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
       "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==",
+      "dev": true,
       "license": "MIT"
     },
     "node_modules/loupe": {
@@ -10360,10 +10563,6 @@
         "get-func-name": "^2.0.1"
       }
     },
-    "node_modules/lousho": {
-      "resolved": "",
-      "link": true
-    },
     "node_modules/lru-cache": {
       "version": "10.4.3",
       "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-10.4.3.tgz",
@@ -10477,6 +10676,7 @@
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
       "integrity": "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.4"
@@ -10493,6 +10693,7 @@
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-1.1.1.tgz",
       "integrity": "sha512-yz3xRaG20c6/BOzvYoDaGtPmGscs7YivItZEEqe6GbwNfHuxu9YNmvnEkMzKldAGY4/80pRcQRZSEnhquk9XuQ==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.8"
@@ -10506,6 +10707,7 @@
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/merge-descriptors/-/merge-descriptors-2.0.0.tgz",
       "integrity": "sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=18"
@@ -10548,6 +10750,7 @@
       "version": "1.54.0",
       "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.54.0.tgz",
       "integrity": "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.6"
@@ -10557,6 +10760,7 @@
       "version": "3.0.2",
       "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-3.0.2.tgz",
       "integrity": "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "mime-db": "^1.54.0"
@@ -10657,6 +10861,7 @@
       "version": "2.1.3",
       "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
       "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
+      "dev": true,
       "license": "MIT"
     },
     "node_modules/mz": {
@@ -10709,6 +10914,7 @@
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/negotiator/-/negotiator-1.1.0.tgz",
       "integrity": "sha512-NMPBRMJgiQHjbd8phG3Vebdx4kZ1H121rbl5IkMqeOsahptB9BKo/d7oJ3zTXqTgagn2bWlNSXkh0QUGM31RYg==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "content-type": "^2.1.0"
@@ -10725,6 +10931,7 @@
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/content-type/-/content-type-2.1.0.tgz",
       "integrity": "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=18"
@@ -10834,6 +11041,7 @@
       "version": "1.13.4",
       "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz",
       "integrity": "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.4"
@@ -10869,6 +11077,7 @@
       "version": "2.4.1",
       "resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.1.tgz",
       "integrity": "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "ee-first": "1.1.1"
@@ -10881,6 +11090,7 @@
       "version": "1.4.0",
       "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
       "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==",
+      "dev": true,
       "license": "ISC",
       "dependencies": {
         "wrappy": "1"
@@ -11070,6 +11280,7 @@
       "version": "1.3.3",
       "resolved": "https://registry.npmjs.org/parseurl/-/parseurl-1.3.3.tgz",
       "integrity": "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.8"
@@ -11140,6 +11351,7 @@
       "version": "8.4.2",
       "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.4.2.tgz",
       "integrity": "sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA==",
+      "dev": true,
       "license": "MIT",
       "funding": {
         "type": "opencollective",
@@ -11169,7 +11381,6 @@
       "integrity": "sha512-aL96AHANtWjPLDOLqnhx+ngp9+UK7ETEU8VJrDCGvsSSi/mGLcWYsS6Herg7lmaBJe4uwrfqsa7gTEFaSizDoQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "pg-connection-string": "^2.14.1",
         "pg-pool": "^3.14.0",
@@ -11274,7 +11485,6 @@
       "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=12"
       },
@@ -11357,7 +11567,6 @@
       "integrity": "sha512-rYCsBF/M5HjUch52bbtVONEFjv6Xu8sm8h72dNlR5bzIE1fvC/bxgspzkjSfU+MweEMmPM8KJebG6nnyxo5mCg==",
       "dev": true,
       "license": "Apache-2.0",
-      "peer": true,
       "bin": {
         "playwright-core": "cli.js"
       },
@@ -11385,7 +11594,6 @@
         }
       ],
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "nanoid": "^3.3.18",
         "picocolors": "^1.1.1",
@@ -11585,6 +11793,7 @@
       "version": "2.0.8",
       "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.8.tgz",
       "integrity": "sha512-5nnx0yGyVUcY6t9RnWcARWtwT9F1D8O9rt08htPvnd49W1IgZtmLkhu9WfMzQj1cFxjHIO6connUNVW5k7AVyQ==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "forwarded": "0.2.0",
@@ -11691,6 +11900,7 @@
       "version": "6.16.0",
       "resolved": "https://registry.npmjs.org/qs/-/qs-6.16.0.tgz",
       "integrity": "sha512-h6fhOIaRrID2CbEY2fqs+7t+UXZo+MLAnU5gRIq85uFtdiUPCdsApMlHhXogKVM4HM2DVbIjGNTTYH2OcmP1vA==",
+      "dev": true,
       "license": "BSD-3-Clause",
       "dependencies": {
         "es-define-property": "^1.0.1",
@@ -11741,6 +11951,7 @@
       "version": "1.3.0",
       "resolved": "https://registry.npmjs.org/range-parser/-/range-parser-1.3.0.tgz",
       "integrity": "sha512-hek2mFQpPuI4E1BBKrSto+BU3e3x4xuarsbiwr3+lf7p44juvFMV0XFWQAP3xUyqXA4RrXLIoaSUGbSt056ZMw==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.6"
@@ -11754,6 +11965,7 @@
       "version": "3.0.2",
       "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-3.0.2.tgz",
       "integrity": "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "bytes": "~3.1.2",
@@ -11769,8 +11981,8 @@
       "version": "18.3.1",
       "resolved": "https://registry.npmjs.org/react/-/react-18.3.1.tgz",
       "integrity": "sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==",
+      "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "loose-envify": "^1.1.0"
       },
@@ -11782,8 +11994,8 @@
       "version": "18.3.1",
       "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-18.3.1.tgz",
       "integrity": "sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==",
+      "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "loose-envify": "^1.1.0",
         "scheduler": "^0.23.2"
@@ -11982,6 +12194,7 @@
       "version": "2.2.0",
       "resolved": "https://registry.npmjs.org/router/-/router-2.2.0.tgz",
       "integrity": "sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "debug": "^4.4.0",
@@ -12026,6 +12239,7 @@
       "version": "2.1.2",
       "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz",
       "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
+      "dev": true,
       "license": "MIT"
     },
     "node_modules/saxes": {
@@ -12045,6 +12259,7 @@
       "version": "0.23.2",
       "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.23.2.tgz",
       "integrity": "sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "loose-envify": "^1.1.0"
@@ -12088,6 +12303,7 @@
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/send/-/send-1.2.1.tgz",
       "integrity": "sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "debug": "^4.4.3",
@@ -12114,6 +12330,7 @@
       "version": "2.2.1",
       "resolved": "https://registry.npmjs.org/serve-static/-/serve-static-2.2.1.tgz",
       "integrity": "sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "encodeurl": "^2.0.0",
@@ -12133,6 +12350,7 @@
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/setprototypeof/-/setprototypeof-1.2.0.tgz",
       "integrity": "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==",
+      "dev": true,
       "license": "ISC"
     },
     "node_modules/sharp": {
@@ -12212,6 +12430,7 @@
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.1.tgz",
       "integrity": "sha512-6x6dK6zJdpTzF4sQeNYxwtvBzf6Eg4GtlesS94HOvTudUeyK2WXAaIfmDgsyslYrRBeFIlsi54AYsFGUuhmvrQ==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "es-errors": "^1.3.0",
@@ -12231,6 +12450,7 @@
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/side-channel-list/-/side-channel-list-1.0.1.tgz",
       "integrity": "sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "es-errors": "^1.3.0",
@@ -12247,6 +12467,7 @@
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/side-channel-map/-/side-channel-map-1.0.1.tgz",
       "integrity": "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "call-bound": "^1.0.2",
@@ -12265,6 +12486,7 @@
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/side-channel-weakmap/-/side-channel-weakmap-1.0.2.tgz",
       "integrity": "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "call-bound": "^1.0.2",
@@ -12394,6 +12616,7 @@
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.2.tgz",
       "integrity": "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.8"
@@ -12560,6 +12783,7 @@
       "version": "4.1.4",
       "resolved": "https://registry.npmjs.org/style-mod/-/style-mod-4.1.4.tgz",
       "integrity": "sha512-XXWIQt633/EpAFx8aZDOTjBzrCaGmhvEQlQo6MVPfa2OzO2cWo+4hV9h+6UkHYlXGfy+ODXKUdP7Pthmcu5ATw==",
+      "dev": true,
       "license": "MIT"
     },
     "node_modules/sucrase": {
@@ -12871,6 +13095,7 @@
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz",
       "integrity": "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=0.6"
@@ -13553,6 +13778,7 @@
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/type-is/-/type-is-2.1.0.tgz",
       "integrity": "sha512-faYHw0anBbc/kWF3zFTEnxSFOAGUX9GFbOBthvDdLsIlEoWOFOtS0zgCiQYwIskL9iGXZL3kAXD8OoZ4GmMATA==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "content-type": "^2.0.0",
@@ -13571,6 +13797,7 @@
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/content-type/-/content-type-2.1.0.tgz",
       "integrity": "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=18"
@@ -13655,7 +13882,6 @@
       "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
       "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
       "dev": true,
-      "peer": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"
@@ -13724,7 +13950,6 @@
       "integrity": "sha512-i7qRCmY42zmCwnYlh9H2SvLEypEFGye5iRmEMKjcGi7zk9UquigRjFtTLz0TYqr0ZGLZhaMHl/foy1bZR+Cwlw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "pathe": "^2.0.3"
       }
@@ -13743,6 +13968,7 @@
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/unpipe/-/unpipe-1.0.0.tgz",
       "integrity": "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.8"
@@ -13793,6 +14019,7 @@
       "version": "1.7.0",
       "resolved": "https://registry.npmjs.org/use-sync-external-store/-/use-sync-external-store-1.7.0.tgz",
       "integrity": "sha512-6L+EeigHMQhdaIPNIFUKwfWJSwWFQ8gJbJ2DLOs5sDIegTwR9fRxvnM3uciHKjIZhFz+KAv2emhWMRvDmMcY8A==",
+      "dev": true,
       "license": "MIT",
       "peerDependencies": {
         "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
@@ -13809,6 +14036,7 @@
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz",
       "integrity": "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.8"
@@ -13820,7 +14048,6 @@
       "integrity": "sha512-j3lYzGC3P+B5Yfy/pfKNgVEg4+UtcIJcVRt2cDjIOmhLourAqPqf8P7acgxeiSgUB7E3p2P8/3gNIgDLpwzs4g==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "esbuild": "^0.21.3",
         "postcss": "^8.4.43",
@@ -14341,7 +14568,6 @@
       "integrity": "sha512-Ljb1cnSJSivGN0LqXd/zmDbWEM0RNNg2t1QW/XUhYl/qPqyu7CsqeWtqQXHVaJsecLPuDoak2oJcZN2QoRIOag==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@vitest/expect": "1.6.1",
         "@vitest/runner": "1.6.1",
@@ -14435,6 +14661,7 @@
       "version": "2.2.8",
       "resolved": "https://registry.npmjs.org/w3c-keyname/-/w3c-keyname-2.2.8.tgz",
       "integrity": "sha512-dpojBhNsCNN7T82Tm7k26A6G9ML3NkhDsnw9n/eoxSRlVBB4CEtIQ/KTCLI2Fwf3ataSXRhYFkQi3SlnFwPvPQ==",
+      "dev": true,
       "license": "MIT"
     },
     "node_modules/w3c-xmlserializer": {
@@ -14566,7 +14793,6 @@
       "dev": true,
       "hasInstallScript": true,
       "license": "Apache-2.0",
-      "peer": true,
       "bin": {
         "workerd": "bin/workerd"
       },
@@ -15223,12 +15449,14 @@
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
       "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
+      "dev": true,
       "license": "ISC"
     },
     "node_modules/ws": {
       "version": "8.21.0",
       "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.0.tgz",
       "integrity": "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=10.0.0"
@@ -15436,7 +15664,6 @@
       "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz",
       "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==",
       "license": "MIT",
-      "peer": true,
       "funding": {
         "url": "https://github.com/sponsors/colinhacks"
       }
@@ -15455,6 +15682,7 @@
       "version": "4.5.7",
       "resolved": "https://registry.npmjs.org/zustand/-/zustand-4.5.7.tgz",
       "integrity": "sha512-CHOUy7mu3lbD6o6LJLfllpjkzhHXSBlX8B9+qPddUsIfeF5S/UZ5q0kmCsnRqT1UHFQZchNFDDzMbQsuesHWlw==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "use-sync-external-store": "^1.2.2"
@@ -15483,7 +15711,7 @@
       "version": "0.1.2-alpha.96",
       "license": "MIT",
       "dependencies": {
-        "lousho": "^1.0.0-alpha.117",
+        "@linuxdevil/lousho": "^1.0.0-alpha.117",
         "prompts": "^2.4.2"
       },
       "bin": {
@@ -15536,7 +15764,7 @@
         "vitest": "^1.0.0"
       },
       "peerDependencies": {
-        "lousho": ">=1.0.0-alpha.117",
+        "@linuxdevil/lousho": ">=1.0.0-alpha.117",
         "react": ">=18",
         "react-dom": ">=18"
       }
diff --git a/package.json b/package.json
index 54de65f34..4bf2ca7ea 100644
--- a/package.json
+++ b/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "lousho",
+  "name": "@linuxdevil/lousho",
   "version": "1.0.0-alpha.117",
   "description": "TypeScript AI agent SDK with tools, MCP, durable sessions, human approvals, and OpenTelemetry. Runs in your own Node process.",
   "workspaces": [
@@ -357,10 +357,6 @@
     "bin",
     "registry/dist",
     "templates",
-    "apps/agent-forge/package.json",
-    "apps/agent-forge/dist",
-    "apps/agent-forge/dist-server",
-    "!apps/agent-forge/dist-server/*.map",
     "README.md",
     "llms.txt",
     "docs/*.md",
@@ -418,7 +414,7 @@
     "pipeline:demo:trigger": "tsx examples/ops-pipeline/mocks/sendSyntheticError.ts",
     "build:studio": "npm run build:studio --workspace apps/agent-forge",
     "test:e2e:studio": "npm run test:e2e:studio --workspace apps/agent-forge",
-    "prepublishOnly": "npm run build && npm run build:studio",
+    "prepublishOnly": "npm run build",
     "prepack": "node scripts/prepack-check.mjs",
     "docs:build": "typedoc",
     "docs:ratchet": "tsx scripts/typedoc-ratchet.ts",
@@ -434,6 +430,7 @@
     "example:openrouter": "tsx examples/openrouter/index.ts",
     "size-check": "tsx scripts/size-check.ts",
     "pack-smoke": "tsx scripts/pack-smoke.ts",
+    "pack-smoke:studio": "tsx scripts/pack-smoke-studio.ts",
     "registry:build": "tsx scripts/build-registry.ts",
     "registry:check": "tsx scripts/build-registry.ts --check",
     "workspaces:schema": "tsx scripts/workspaces-schema.ts",
diff --git a/packages/create-lousho/README.md b/packages/create-lousho/README.md
index 4fdcf8e15..5ea0b000e 100644
--- a/packages/create-lousho/README.md
+++ b/packages/create-lousho/README.md
@@ -34,7 +34,7 @@ npm create lousho my-agent -- --yes --provider anthropic --template tools
 
 Running a packed `.tgz` of this package on Windows: `npx C:\abs\path\create-lousho-<version>.tgz` silently does nothing (an npm quirk with absolute drive-letter paths). Use a relative path (`npx ./create-lousho-<version>.tgz my-agent`) or a `file:` spec (`npx file:C:/abs/path/create-lousho-<version>.tgz my-agent`).
 
-This package is a thin wrapper: it runs `lousho init` from the SDK, so `npx lousho init --help` lists every option.
+This package is a thin wrapper: it runs `lousho init` from the SDK, so `npx @linuxdevil/lousho init --help` lists every option.
 
 ## Links
 
diff --git a/packages/create-lousho/package.json b/packages/create-lousho/package.json
index 2d1309b4e..c4ae6c125 100644
--- a/packages/create-lousho/package.json
+++ b/packages/create-lousho/package.json
@@ -33,7 +33,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "lousho": "^1.0.0-alpha.117",
+    "@linuxdevil/lousho": "^1.0.0-alpha.117",
     "prompts": "^2.4.2"
   },
   "devDependencies": {
diff --git a/packages/create-lousho/src/index.test.ts b/packages/create-lousho/src/index.test.ts
index d25c8b49e..6cb058381 100644
--- a/packages/create-lousho/src/index.test.ts
+++ b/packages/create-lousho/src/index.test.ts
@@ -44,7 +44,7 @@ describe('create-lousho wraps lousho init', () => {
 
     expect(output).toContain('Next steps:');
     expect(fs.readFileSync(path.join(dir, '.env.example'), 'utf8')).toContain('ANTHROPIC_API_KEY=');
-    expect(JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')).dependencies['lousho']).toBe(
+    expect(JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')).dependencies['@linuxdevil/lousho']).toBe(
       'file:./sdk-0.0.0.tgz'
     );
   });
diff --git a/packages/create-lousho/src/index.ts b/packages/create-lousho/src/index.ts
index d4040b701..0cf9c77c3 100644
--- a/packages/create-lousho/src/index.ts
+++ b/packages/create-lousho/src/index.ts
@@ -13,7 +13,7 @@ import path from 'node:path';
 export function loushoBin(): string {
   // The package's "exports" map hides package.json, but the "." entry
   // (<root>/dist/index.js) is resolvable and bin/ is its sibling of dist/.
-  const entry = require.resolve('lousho');
+  const entry = require.resolve('@linuxdevil/lousho');
   return path.join(path.dirname(entry), '..', 'bin', 'lousho.js');
 }
 
diff --git a/packages/create-lousho/src/template.e2e.test.ts b/packages/create-lousho/src/template.e2e.test.ts
index 0e3ad5992..6ac156c7c 100644
--- a/packages/create-lousho/src/template.e2e.test.ts
+++ b/packages/create-lousho/src/template.e2e.test.ts
@@ -92,8 +92,8 @@ describe('end-to-end scaffold + install + typecheck + test', () => {
       );
 
       const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
-      expect(pkg.dependencies['lousho']).toMatch(/^file:\.\/.*\.tgz$/);
-      expect(fs.existsSync(path.join(dir, 'node_modules', 'lousho'))).toBe(true);
+      expect(pkg.dependencies['@linuxdevil/lousho']).toMatch(/^file:\.\/.*\.tgz$/);
+      expect(fs.existsSync(path.join(dir, 'node_modules', '@linuxdevil', 'lousho'))).toBe(true);
 
       npm(['run', 'typecheck'], dir);
       const testOutput = npm(['test'], dir);
@@ -101,7 +101,7 @@ describe('end-to-end scaffold + install + typecheck + test', () => {
 
       const sdkPkg = JSON.parse(fs.readFileSync(path.join(SDK_ROOT, 'package.json'), 'utf8'));
       const installed = JSON.parse(
-        fs.readFileSync(path.join(dir, 'node_modules', 'lousho', 'package.json'), 'utf8')
+        fs.readFileSync(path.join(dir, 'node_modules', '@linuxdevil', 'lousho', 'package.json'), 'utf8')
       );
       expect(installed.version).toBe(sdkPkg.version);
 
diff --git a/packages/workspaces-react/README.md b/packages/workspaces-react/README.md
index 9b3b136ea..23a3b8ceb 100644
--- a/packages/workspaces-react/README.md
+++ b/packages/workspaces-react/README.md
@@ -7,7 +7,7 @@ Renders a Lousho page UI (`lousho.ui/1`) in any React 18 or later app. `<PageApp
 ## Use
 
 ```tsx
-import { createFetchClient } from 'lousho/workspaces/client';
+import { createFetchClient } from '@linuxdevil/lousho/workspaces/client';
 import { PageApp } from '@lousho/workspaces-react';
 import '@lousho/workspaces-react/styles.css';
 
diff --git a/packages/workspaces-react/package.json b/packages/workspaces-react/package.json
index 15bc43d22..19372c581 100644
--- a/packages/workspaces-react/package.json
+++ b/packages/workspaces-react/package.json
@@ -24,7 +24,7 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "peerDependencies": {
-    "lousho": ">=1.0.0-alpha.117",
+    "@linuxdevil/lousho": ">=1.0.0-alpha.117",
     "react": ">=18",
     "react-dom": ">=18"
   },
diff --git a/packages/workspaces-react/src/PageApp.test.tsx b/packages/workspaces-react/src/PageApp.test.tsx
index 41938b676..cc5fa0c93 100644
--- a/packages/workspaces-react/src/PageApp.test.tsx
+++ b/packages/workspaces-react/src/PageApp.test.tsx
@@ -1,7 +1,7 @@
 import axe from 'axe-core';
 import { act } from 'react';
 import { describe, expect, it, vi } from 'vitest';
-import { UI_COMPONENTS, type UiComponent } from 'lousho/workspaces';
+import { UI_COMPONENTS, type UiComponent } from '@linuxdevil/lousho/workspaces';
 import { PageApp } from './PageApp';
 import { runWith, withAudience, withUi } from './__tests__/clients';
 import { choose, flush, labelled, render } from './__tests__/render';
diff --git a/packages/workspaces-react/src/PageApp.tsx b/packages/workspaces-react/src/PageApp.tsx
index b92969fde..c2c36ab7b 100644
--- a/packages/workspaces-react/src/PageApp.tsx
+++ b/packages/workspaces-react/src/PageApp.tsx
@@ -1,5 +1,5 @@
 import { useEffect, useMemo, useState, type Key, type ReactElement } from 'react';
-import type { ApiClient, PageUiView, UiComponent } from 'lousho/workspaces/client';
+import type { ApiClient, PageUiView, UiComponent } from '@linuxdevil/lousho/workspaces/client';
 import { IDLE_RUN, type RenderContext, type RunHandle } from './context';
 import { useFormState, type FormCheck } from './form';
 import { renderComponent } from './render';
diff --git a/packages/workspaces-react/src/__tests__/clients.ts b/packages/workspaces-react/src/__tests__/clients.ts
index d02c45112..b35cd84d6 100644
--- a/packages/workspaces-react/src/__tests__/clients.ts
+++ b/packages/workspaces-react/src/__tests__/clients.ts
@@ -1,4 +1,4 @@
-import { fixtureClient, type ApiClient, type HarnessView, type PageRunView, type PageUiView, type UiComponent, type UiContainer } from 'lousho/workspaces/client';
+import { fixtureClient, type ApiClient, type HarnessView, type PageRunView, type PageUiView, type UiComponent, type UiContainer } from '@linuxdevil/lousho/workspaces/client';
 import type { RunHandle } from '../context';
 
 type Call = (name: string, input: unknown) => Promise<unknown>;
diff --git a/packages/workspaces-react/src/components/actions.tsx b/packages/workspaces-react/src/components/actions.tsx
index 2e8d26735..85b76cb12 100644
--- a/packages/workspaces-react/src/components/actions.tsx
+++ b/packages/workspaces-react/src/components/actions.tsx
@@ -1,5 +1,5 @@
 import type { ReactElement } from 'react';
-import type { UiRunWidget } from 'lousho/workspaces/client';
+import type { UiRunWidget } from '@linuxdevil/lousho/workspaces/client';
 import type { RenderContext, RunPhase } from '../context';
 
 const BUSY: ReadonlySet<RunPhase> = new Set<RunPhase>(['starting', 'queued', 'running', 'needs-approval']);
diff --git a/packages/workspaces-react/src/components/inputs.tsx b/packages/workspaces-react/src/components/inputs.tsx
index 5aeafe9c8..2b467cf00 100644
--- a/packages/workspaces-react/src/components/inputs.tsx
+++ b/packages/workspaces-react/src/components/inputs.tsx
@@ -1,5 +1,5 @@
 import type { ReactElement } from 'react';
-import type { UiChoiceField, UiFileField, UiInputField, UiNumberField, UiOption, UiText } from 'lousho/workspaces/client';
+import type { UiChoiceField, UiFileField, UiInputField, UiNumberField, UiOption, UiText } from '@linuxdevil/lousho/workspaces/client';
 import type { RenderContext } from '../context';
 import { enumValues, fieldSchema } from '../schema';
 import { Field, FieldError, fieldLabel, useControl } from './field';
diff --git a/packages/workspaces-react/src/components/layout.tsx b/packages/workspaces-react/src/components/layout.tsx
index 5ffc484ab..90cd606f9 100644
--- a/packages/workspaces-react/src/components/layout.tsx
+++ b/packages/workspaces-react/src/components/layout.tsx
@@ -1,5 +1,5 @@
 import { useId, useRef, useState, type KeyboardEvent, type ReactElement } from 'react';
-import type { UiContainer, UiTabs } from 'lousho/workspaces/client';
+import type { UiContainer, UiTabs } from '@linuxdevil/lousho/workspaces/client';
 import type { RenderContext } from '../context';
 
 const CONTAINER_CLASS = { stack: 'lwr-stack', row: 'lwr-row', section: 'lwr-section', card: 'lwr-card' } as const;
diff --git a/packages/workspaces-react/src/components/outputs.tsx b/packages/workspaces-react/src/components/outputs.tsx
index 60684a1e6..b1419bb50 100644
--- a/packages/workspaces-react/src/components/outputs.tsx
+++ b/packages/workspaces-react/src/components/outputs.tsx
@@ -1,5 +1,5 @@
 import type { ReactElement, ReactNode } from 'react';
-import type { UiArtifactView, UiOutputField, UiRunWidget, UiText } from 'lousho/workspaces/client';
+import type { UiArtifactView, UiOutputField, UiRunWidget, UiText } from '@linuxdevil/lousho/workspaces/client';
 import type { RenderContext } from '../context';
 import { getAt } from '../paths';
 import { isRecord } from '../schema';
diff --git a/packages/workspaces-react/src/components/status.tsx b/packages/workspaces-react/src/components/status.tsx
index d99675d31..7def6c3aa 100644
--- a/packages/workspaces-react/src/components/status.tsx
+++ b/packages/workspaces-react/src/components/status.tsx
@@ -1,5 +1,5 @@
 import type { ReactElement } from 'react';
-import type { UiRunWidget } from 'lousho/workspaces/client';
+import type { UiRunWidget } from '@linuxdevil/lousho/workspaces/client';
 import type { RenderContext, RunPhase } from '../context';
 
 const STATUS_WORDS: Readonly<Record<RunPhase, string>> = {
diff --git a/packages/workspaces-react/src/context.ts b/packages/workspaces-react/src/context.ts
index aaf4ff591..04e0e20fe 100644
--- a/packages/workspaces-react/src/context.ts
+++ b/packages/workspaces-react/src/context.ts
@@ -1,5 +1,5 @@
 import type { Key, ReactElement } from 'react';
-import type { ApiClient, ArtifactRef, PageApprovalEvent, PageProgressEvent, PageRunView, PageUi, RunViewStatus, UiComponent } from 'lousho/workspaces/client';
+import type { ApiClient, ArtifactRef, PageApprovalEvent, PageProgressEvent, PageRunView, PageUi, RunViewStatus, UiComponent } from '@linuxdevil/lousho/workspaces/client';
 
 /** Where a run started from the page UI stands: `idle` before the first run, `starting` until the service answers, then the service's status. */
 export type RunPhase = 'idle' | 'starting' | RunViewStatus;
diff --git a/packages/workspaces-react/src/render.tsx b/packages/workspaces-react/src/render.tsx
index 7b6a3ba3f..e30481e61 100644
--- a/packages/workspaces-react/src/render.tsx
+++ b/packages/workspaces-react/src/render.tsx
@@ -1,5 +1,5 @@
 import { useEffect, type Key, type ReactElement } from 'react';
-import type { UiComponent, UiComponentType, UiText } from 'lousho/workspaces/client';
+import type { UiComponent, UiComponentType, UiText } from '@linuxdevil/lousho/workspaces/client';
 import type { RenderContext } from './context';
 import { CancelButton, ReviseBox, RunButton } from './components/actions';
 import { ChoiceRadio, ChoiceSelect, FileInput, NumberInput, SchemaFormField, TextArea, TextInput, Toggle } from './components/inputs';
diff --git a/packages/workspaces-react/src/visible.ts b/packages/workspaces-react/src/visible.ts
index 4dbab8041..de5bc80cb 100644
--- a/packages/workspaces-react/src/visible.ts
+++ b/packages/workspaces-react/src/visible.ts
@@ -1,4 +1,4 @@
-import { evaluateSafeExpression } from 'lousho/workspaces/client';
+import { evaluateSafeExpression } from '@linuxdevil/lousho/workspaces/client';
 
 export interface VisibleScope {
   inputs: unknown;
diff --git a/packages/workspaces-react/tsconfig.build.json b/packages/workspaces-react/tsconfig.build.json
index bf9c2f488..7ee689348 100644
--- a/packages/workspaces-react/tsconfig.build.json
+++ b/packages/workspaces-react/tsconfig.build.json
@@ -2,8 +2,8 @@
   "extends": "./tsconfig.json",
   "compilerOptions": {
     "paths": {
-      "lousho/workspaces/client": ["../../dist/workspaces/client/index.d.mts"],
-      "lousho/workspaces": ["../../dist/workspaces/index.d.mts"]
+      "@linuxdevil/lousho/workspaces/client": ["../../dist/workspaces/client/index.d.mts"],
+      "@linuxdevil/lousho/workspaces": ["../../dist/workspaces/index.d.mts"]
     },
     "types": []
   },
diff --git a/packages/workspaces-react/tsconfig.json b/packages/workspaces-react/tsconfig.json
index 094142341..d9b458c19 100644
--- a/packages/workspaces-react/tsconfig.json
+++ b/packages/workspaces-react/tsconfig.json
@@ -17,8 +17,8 @@
     "noEmit": true,
     "types": ["node"],
     "paths": {
-      "lousho/workspaces": ["../../src/workspaces/index.ts"],
-      "lousho/workspaces/client": ["../../src/workspaces/client/index.ts"]
+      "@linuxdevil/lousho/workspaces": ["../../src/workspaces/index.ts"],
+      "@linuxdevil/lousho/workspaces/client": ["../../src/workspaces/client/index.ts"]
     }
   },
   "include": ["src/**/*", "../../typings/**/*.d.ts"],
diff --git a/packages/workspaces-react/tsup.config.ts b/packages/workspaces-react/tsup.config.ts
index 2d8d6ce57..5b2245a91 100644
--- a/packages/workspaces-react/tsup.config.ts
+++ b/packages/workspaces-react/tsup.config.ts
@@ -10,5 +10,5 @@ export default defineConfig({
   clean: true,
   treeshake: true,
   platform: 'browser',
-  external: ['react', 'react-dom', 'react/jsx-runtime', 'lousho', 'lousho/workspaces/client'],
+  external: ['react', 'react-dom', 'react/jsx-runtime', '@linuxdevil/lousho', '@linuxdevil/lousho/workspaces/client'],
 });
diff --git a/registry/coding-kit/approve.ts b/registry/coding-kit/approve.ts
index daa376ae5..b749de7cb 100644
--- a/registry/coding-kit/approve.ts
+++ b/registry/coding-kit/approve.ts
@@ -1,4 +1,4 @@
-import type { ApproveToolCall } from 'lousho';
+import type { ApproveToolCall } from '@linuxdevil/lousho';
 
 /**
  * The kit's approver (pointed at by `agent.json`'s `approve`): the agent asks
diff --git a/registry/coding-kit/hooks.ts b/registry/coding-kit/hooks.ts
index f2983ddaa..b80fe173e 100644
--- a/registry/coding-kit/hooks.ts
+++ b/registry/coding-kit/hooks.ts
@@ -1,4 +1,4 @@
-import type { AgentHook, Message } from 'lousho';
+import type { AgentHook, Message } from '@linuxdevil/lousho';
 
 /**
  * The kit's hooks (pointed at by `agent.json`'s `hooks`): a loop guard that
diff --git a/registry/coding-kit/item.json b/registry/coding-kit/item.json
index e85e9e9a0..a8af20295 100644
--- a/registry/coding-kit/item.json
+++ b/registry/coding-kit/item.json
@@ -6,5 +6,5 @@
     "exec": true,
     "filesystem": "write"
   },
-  "dependencies": ["lousho"]
+  "dependencies": ["@linuxdevil/lousho"]
 }
diff --git a/registry/coding-kit/subagents/explorer/tools/read-only.ts b/registry/coding-kit/subagents/explorer/tools/read-only.ts
index bf1a5f673..a8a8ef41d 100644
--- a/registry/coding-kit/subagents/explorer/tools/read-only.ts
+++ b/registry/coding-kit/subagents/explorer/tools/read-only.ts
@@ -6,7 +6,7 @@
  */
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { createFsTools, NodeWorkspace } from 'lousho';
+import { createFsTools, NodeWorkspace } from '@linuxdevil/lousho';
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
 const workspace = new NodeWorkspace({ root });
diff --git a/registry/coding-kit/tools/fs.ts b/registry/coding-kit/tools/fs.ts
index da2059aa3..c85f0620e 100644
--- a/registry/coding-kit/tools/fs.ts
+++ b/registry/coding-kit/tools/fs.ts
@@ -26,7 +26,7 @@ import {
   WorkspaceCheckpoints,
   WorkspaceError,
   type FsProvider,
-} from 'lousho';
+} from '@linuxdevil/lousho';
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
diff --git a/registry/coding-pi/approve.ts b/registry/coding-pi/approve.ts
index daa376ae5..b749de7cb 100644
--- a/registry/coding-pi/approve.ts
+++ b/registry/coding-pi/approve.ts
@@ -1,4 +1,4 @@
-import type { ApproveToolCall } from 'lousho';
+import type { ApproveToolCall } from '@linuxdevil/lousho';
 
 /**
  * The kit's approver (pointed at by `agent.json`'s `approve`): the agent asks
diff --git a/registry/coding-pi/hooks.ts b/registry/coding-pi/hooks.ts
index f2983ddaa..b80fe173e 100644
--- a/registry/coding-pi/hooks.ts
+++ b/registry/coding-pi/hooks.ts
@@ -1,4 +1,4 @@
-import type { AgentHook, Message } from 'lousho';
+import type { AgentHook, Message } from '@linuxdevil/lousho';
 
 /**
  * The kit's hooks (pointed at by `agent.json`'s `hooks`): a loop guard that
diff --git a/registry/coding-pi/item.json b/registry/coding-pi/item.json
index d9cf993da..701b77ea6 100644
--- a/registry/coding-pi/item.json
+++ b/registry/coding-pi/item.json
@@ -8,5 +8,5 @@
     "network": ["api.openrouter.ai"],
     "env": ["OPENROUTER_API_KEY"]
   },
-  "dependencies": ["lousho", "@earendil-works/pi-ai", "@earendil-works/pi-coding-agent"]
+  "dependencies": ["@linuxdevil/lousho", "@earendil-works/pi-ai", "@earendil-works/pi-coding-agent"]
 }
diff --git a/registry/coding-pi/subagents/explorer/tools/read-only.ts b/registry/coding-pi/subagents/explorer/tools/read-only.ts
index bf1a5f673..a8a8ef41d 100644
--- a/registry/coding-pi/subagents/explorer/tools/read-only.ts
+++ b/registry/coding-pi/subagents/explorer/tools/read-only.ts
@@ -6,7 +6,7 @@
  */
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { createFsTools, NodeWorkspace } from 'lousho';
+import { createFsTools, NodeWorkspace } from '@linuxdevil/lousho';
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
 const workspace = new NodeWorkspace({ root });
diff --git a/registry/coding-pi/tools/fs.ts b/registry/coding-pi/tools/fs.ts
index da2059aa3..c85f0620e 100644
--- a/registry/coding-pi/tools/fs.ts
+++ b/registry/coding-pi/tools/fs.ts
@@ -26,7 +26,7 @@ import {
   WorkspaceCheckpoints,
   WorkspaceError,
   type FsProvider,
-} from 'lousho';
+} from '@linuxdevil/lousho';
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
diff --git a/registry/dist/items/coding-kit.json b/registry/dist/items/coding-kit.json
index 37a7c79f4..c1bf640d6 100644
--- a/registry/dist/items/coding-kit.json
+++ b/registry/dist/items/coding-kit.json
@@ -9,11 +9,11 @@
     },
     {
       "path": "approve.ts",
-      "content": "import type { ApproveToolCall } from 'lousho';\n\n/**\n * The kit's approver (pointed at by `agent.json`'s `approve`): the agent asks\n * before every `write_file` / `edit_file`; the approver allows them all except\n * test files, so the model can fix the code but never the tests that judge it.\n */\nconst approve: ApproveToolCall = ({ args }) => !String(args.path ?? '').endsWith('.test.js');\n\nexport default approve;\n"
+      "content": "import type { ApproveToolCall } from '@linuxdevil/lousho';\n\n/**\n * The kit's approver (pointed at by `agent.json`'s `approve`): the agent asks\n * before every `write_file` / `edit_file`; the approver allows them all except\n * test files, so the model can fix the code but never the tests that judge it.\n */\nconst approve: ApproveToolCall = ({ args }) => !String(args.path ?? '').endsWith('.test.js');\n\nexport default approve;\n"
     },
     {
       "path": "hooks.ts",
-      "content": "import type { AgentHook, Message } from 'lousho';\n\n/**\n * The kit's hooks (pointed at by `agent.json`'s `hooks`): a loop guard that\n * denies a tool call the model already made twice with the same arguments,\n * then an output cap that keeps long tool results from flooding the context.\n * Ported from examples/coding-harness/index.ts.\n */\n\n/** Test runs are expected to repeat (before and after every change), so the loop guard lets them through. */\nconst TEST_COMMAND = /^\\s*node --test\\b/;\n\nfunction canonical(value: unknown): string {\n  const record = (value ?? {}) as Record<string, unknown>;\n  return JSON.stringify(Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b))));\n}\n\n/** How many earlier calls in the current turn (since the last user message) match this one. */\nfunction earlierCalls(messages: readonly Message[], toolCallId: string, toolName: string, args: unknown): number {\n  const key = canonical(args);\n  let count = 0;\n  for (let i = messages.length - 1; i >= 0 && messages[i].role !== 'user'; i--) {\n    for (const call of messages[i].toolCalls ?? []) {\n      if (call.id === toolCallId || call.function.name !== toolName) continue;\n      try {\n        if (canonical(JSON.parse(call.function.arguments || '{}')) === key) count++;\n      } catch {\n        // unparseable arguments never match\n      }\n    }\n  }\n  return count;\n}\n\n/**\n * Deny a tool call the model already made `maxRepeats` times with the same\n * arguments in the current turn. The count is read from the conversation\n * itself, so separate runs and separately loaded agents never share it and a\n * pause for approval does not reset it; test commands and the post-approval\n * re-fire of a paused call are let through.\n */\nexport function loopGuard(maxRepeats = 2): AgentHook {\n  return {\n    name: 'loop-guard',\n    preToolCall(ctx) {\n      if (ctx.resumedAfterApproval) return undefined;\n      if (ctx.toolName === 'shell' && TEST_COMMAND.test(String(ctx.args.command ?? ''))) return undefined;\n      if (earlierCalls(ctx.messages, ctx.toolCallId, ctx.toolName, ctx.args) >= 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\nexport default [loopGuard(), outputCap()];\n"
+      "content": "import type { AgentHook, Message } from '@linuxdevil/lousho';\n\n/**\n * The kit's hooks (pointed at by `agent.json`'s `hooks`): a loop guard that\n * denies a tool call the model already made twice with the same arguments,\n * then an output cap that keeps long tool results from flooding the context.\n * Ported from examples/coding-harness/index.ts.\n */\n\n/** Test runs are expected to repeat (before and after every change), so the loop guard lets them through. */\nconst TEST_COMMAND = /^\\s*node --test\\b/;\n\nfunction canonical(value: unknown): string {\n  const record = (value ?? {}) as Record<string, unknown>;\n  return JSON.stringify(Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b))));\n}\n\n/** How many earlier calls in the current turn (since the last user message) match this one. */\nfunction earlierCalls(messages: readonly Message[], toolCallId: string, toolName: string, args: unknown): number {\n  const key = canonical(args);\n  let count = 0;\n  for (let i = messages.length - 1; i >= 0 && messages[i].role !== 'user'; i--) {\n    for (const call of messages[i].toolCalls ?? []) {\n      if (call.id === toolCallId || call.function.name !== toolName) continue;\n      try {\n        if (canonical(JSON.parse(call.function.arguments || '{}')) === key) count++;\n      } catch {\n        // unparseable arguments never match\n      }\n    }\n  }\n  return count;\n}\n\n/**\n * Deny a tool call the model already made `maxRepeats` times with the same\n * arguments in the current turn. The count is read from the conversation\n * itself, so separate runs and separately loaded agents never share it and a\n * pause for approval does not reset it; test commands and the post-approval\n * re-fire of a paused call are let through.\n */\nexport function loopGuard(maxRepeats = 2): AgentHook {\n  return {\n    name: 'loop-guard',\n    preToolCall(ctx) {\n      if (ctx.resumedAfterApproval) return undefined;\n      if (ctx.toolName === 'shell' && TEST_COMMAND.test(String(ctx.args.command ?? ''))) return undefined;\n      if (earlierCalls(ctx.messages, ctx.toolCallId, ctx.toolName, ctx.args) >= 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\nexport default [loopGuard(), outputCap()];\n"
     },
     {
       "path": "instructions.md",
@@ -41,11 +41,11 @@
     },
     {
       "path": "subagents/explorer/tools/read-only.ts",
-      "content": "/**\n * The explorer's read-only file tools, bound to the same workspace as the\n * lead's (the agent directory, three levels up from this file): `read_file`,\n * `list_dir`, `glob` and `grep`, with no `write_file` / `edit_file`, so a\n * delegated reading task cannot change anything.\n */\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport { createFsTools, NodeWorkspace } from 'lousho';\n\nconst root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');\nconst workspace = new NodeWorkspace({ root });\nconst readOnly = createFsTools(workspace).filter((tool) => ['read_file', 'list_dir', 'glob', 'grep'].includes(tool.name));\n\nexport default readOnly;\n"
+      "content": "/**\n * The explorer's read-only file tools, bound to the same workspace as the\n * lead's (the agent directory, three levels up from this file): `read_file`,\n * `list_dir`, `glob` and `grep`, with no `write_file` / `edit_file`, so a\n * delegated reading task cannot change anything.\n */\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport { createFsTools, NodeWorkspace } from '@linuxdevil/lousho';\n\nconst root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');\nconst workspace = new NodeWorkspace({ root });\nconst readOnly = createFsTools(workspace).filter((tool) => ['read_file', 'list_dir', 'glob', 'grep'].includes(tool.name));\n\nexport default readOnly;\n"
     },
     {
       "path": "tools/fs.ts",
-      "content": "/**\n * The kit's workspace tools: every file tool and a shell limited to an allow\n * list. The workspace is the agent directory itself - the kit works on the\n * project it is installed into, and `lousho build` bundles this file next to\n * the agent so the built server's workspace is the bundled directory.\n *\n * Because the agent's own files share that directory, the file tools refuse\n * to change them: `agent.*`, `approve.*`, `hooks.*`, `instructions*`,\n * `lousho-registry.json`, and everything under `.lousho/`, `tools/`,\n * `skills/`, `subagents/`, `.git/` and `node_modules/`. Without this the\n * model could rewrite its own approver or permissions.\n *\n * `checkpoints` backs up every write and edit (to `.lousho/checkpoints/` in\n * the workspace, so a rewind still works after a restart); `workspace`,\n * `checkpoints` and `fs` are also exported for code that wants the same\n * objects (a test, or another tool file).\n */\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport {\n  createFsTools,\n  createShellTool,\n  FileWorkspaceCheckpointStore,\n  NodeWorkspace,\n  normalizeWorkspacePath,\n  WorkspaceCheckpoints,\n  WorkspaceError,\n  type FsProvider,\n} from 'lousho';\n\nconst root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');\n\nexport const workspace = new NodeWorkspace({ root });\nexport const checkpoints = new WorkspaceCheckpoints(workspace, {\n  store: new FileWorkspaceCheckpointStore(path.join(root, '.lousho', 'checkpoints')),\n});\n\nconst PROTECTED_DIRS = new Set(['.lousho', 'tools', 'skills', 'subagents', 'instructions', '.git', 'node_modules']);\nconst PROTECTED_ROOT_FILE = /^(agent|approve|hooks)(\\..*)?$|^instructions|^lousho-registry\\.json$/;\n\n/** True when `p` names one of the agent's own files (case-insensitive; Windows aliases included). */\nexport function isAgentFile(p: string): boolean {\n  // Windows drops trailing dots and spaces, and `APPROV~1.TS` may alias `approve.ts`.\n  const segments = normalizeWorkspacePath(p)\n    .split('/')\n    .map((s) => s.replace(/[. ]+$/, '').toLowerCase());\n  if (segments.some((s) => /~\\d/.test(s))) return true;\n  if (PROTECTED_DIRS.has(segments[0])) return true;\n  return segments.length === 1 && PROTECTED_ROOT_FILE.test(segments[0]);\n}\n\nfunction guard(p: string): void {\n  if (isAgentFile(p)) {\n    throw new WorkspaceError(`${p} is part of the agent's own configuration and cannot be changed. Change the project's code instead.`);\n  }\n}\n\n/** The workspace as the file tools see it: reads pass through, writes to the agent's own files are refused. */\nconst projectFiles: FsProvider = {\n  readFile: (p) => workspace.readFile(p),\n  stat: (p) => workspace.stat(p),\n  readdir: (p) => workspace.readdir(p),\n  getMode: (p) => workspace.getMode(p),\n  async writeFile(p, content) {\n    guard(p);\n    return workspace.writeFile(p, content);\n  },\n  async mkdir(p) {\n    guard(p);\n    return workspace.mkdir(p);\n  },\n  async rm(p, options) {\n    guard(p);\n    return workspace.rm(p, options);\n  },\n  async chmod(p, mode) {\n    guard(p);\n    return workspace.chmod(p, mode);\n  },\n};\n\nexport const fs = createFsTools(projectFiles, { checkpoints });\n\n/**\n * A shell that only runs the commands a coding harness needs. `node --test`\n * takes test file paths but no flags (a flag such as\n * `--test-reporter-destination=../x` writes outside the project); `git diff`\n * is left out because `git diff --output=<file>` writes anywhere.\n */\nexport const shell = createShellTool(workspace, {\n  needsApproval: false,\n  allow: [/^node --test( (?!-)(?![^ ]*\\.\\.)[\\w./-]+)*$/, /^git status( (-s|--short|--porcelain))?$/],\n});\n\nexport default fs;\n"
+      "content": "/**\n * The kit's workspace tools: every file tool and a shell limited to an allow\n * list. The workspace is the agent directory itself - the kit works on the\n * project it is installed into, and `lousho build` bundles this file next to\n * the agent so the built server's workspace is the bundled directory.\n *\n * Because the agent's own files share that directory, the file tools refuse\n * to change them: `agent.*`, `approve.*`, `hooks.*`, `instructions*`,\n * `lousho-registry.json`, and everything under `.lousho/`, `tools/`,\n * `skills/`, `subagents/`, `.git/` and `node_modules/`. Without this the\n * model could rewrite its own approver or permissions.\n *\n * `checkpoints` backs up every write and edit (to `.lousho/checkpoints/` in\n * the workspace, so a rewind still works after a restart); `workspace`,\n * `checkpoints` and `fs` are also exported for code that wants the same\n * objects (a test, or another tool file).\n */\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport {\n  createFsTools,\n  createShellTool,\n  FileWorkspaceCheckpointStore,\n  NodeWorkspace,\n  normalizeWorkspacePath,\n  WorkspaceCheckpoints,\n  WorkspaceError,\n  type FsProvider,\n} from '@linuxdevil/lousho';\n\nconst root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');\n\nexport const workspace = new NodeWorkspace({ root });\nexport const checkpoints = new WorkspaceCheckpoints(workspace, {\n  store: new FileWorkspaceCheckpointStore(path.join(root, '.lousho', 'checkpoints')),\n});\n\nconst PROTECTED_DIRS = new Set(['.lousho', 'tools', 'skills', 'subagents', 'instructions', '.git', 'node_modules']);\nconst PROTECTED_ROOT_FILE = /^(agent|approve|hooks)(\\..*)?$|^instructions|^lousho-registry\\.json$/;\n\n/** True when `p` names one of the agent's own files (case-insensitive; Windows aliases included). */\nexport function isAgentFile(p: string): boolean {\n  // Windows drops trailing dots and spaces, and `APPROV~1.TS` may alias `approve.ts`.\n  const segments = normalizeWorkspacePath(p)\n    .split('/')\n    .map((s) => s.replace(/[. ]+$/, '').toLowerCase());\n  if (segments.some((s) => /~\\d/.test(s))) return true;\n  if (PROTECTED_DIRS.has(segments[0])) return true;\n  return segments.length === 1 && PROTECTED_ROOT_FILE.test(segments[0]);\n}\n\nfunction guard(p: string): void {\n  if (isAgentFile(p)) {\n    throw new WorkspaceError(`${p} is part of the agent's own configuration and cannot be changed. Change the project's code instead.`);\n  }\n}\n\n/** The workspace as the file tools see it: reads pass through, writes to the agent's own files are refused. */\nconst projectFiles: FsProvider = {\n  readFile: (p) => workspace.readFile(p),\n  stat: (p) => workspace.stat(p),\n  readdir: (p) => workspace.readdir(p),\n  getMode: (p) => workspace.getMode(p),\n  async writeFile(p, content) {\n    guard(p);\n    return workspace.writeFile(p, content);\n  },\n  async mkdir(p) {\n    guard(p);\n    return workspace.mkdir(p);\n  },\n  async rm(p, options) {\n    guard(p);\n    return workspace.rm(p, options);\n  },\n  async chmod(p, mode) {\n    guard(p);\n    return workspace.chmod(p, mode);\n  },\n};\n\nexport const fs = createFsTools(projectFiles, { checkpoints });\n\n/**\n * A shell that only runs the commands a coding harness needs. `node --test`\n * takes test file paths but no flags (a flag such as\n * `--test-reporter-destination=../x` writes outside the project); `git diff`\n * is left out because `git diff --output=<file>` writes anywhere.\n */\nexport const shell = createShellTool(workspace, {\n  needsApproval: false,\n  allow: [/^node --test( (?!-)(?![^ ]*\\.\\.)[\\w./-]+)*$/, /^git status( (-s|--short|--porcelain))?$/],\n});\n\nexport default fs;\n"
     }
   ],
   "permissions": {
@@ -53,6 +53,6 @@
     "exec": true
   },
   "dependencies": [
-    "lousho"
+    "@linuxdevil/lousho"
   ]
 }
diff --git a/registry/dist/items/coding-pi.json b/registry/dist/items/coding-pi.json
index bda774da9..b89405169 100644
--- a/registry/dist/items/coding-pi.json
+++ b/registry/dist/items/coding-pi.json
@@ -9,11 +9,11 @@
     },
     {
       "path": "approve.ts",
-      "content": "import type { ApproveToolCall } from 'lousho';\n\n/**\n * The kit's approver (pointed at by `agent.json`'s `approve`): the agent asks\n * before every `write_file` / `edit_file`; the approver allows them all except\n * test files, so the model can fix the code but never the tests that judge it.\n */\nconst approve: ApproveToolCall = ({ args }) => !String(args.path ?? '').endsWith('.test.js');\n\nexport default approve;\n"
+      "content": "import type { ApproveToolCall } from '@linuxdevil/lousho';\n\n/**\n * The kit's approver (pointed at by `agent.json`'s `approve`): the agent asks\n * before every `write_file` / `edit_file`; the approver allows them all except\n * test files, so the model can fix the code but never the tests that judge it.\n */\nconst approve: ApproveToolCall = ({ args }) => !String(args.path ?? '').endsWith('.test.js');\n\nexport default approve;\n"
     },
     {
       "path": "hooks.ts",
-      "content": "import type { AgentHook, Message } from 'lousho';\n\n/**\n * The kit's hooks (pointed at by `agent.json`'s `hooks`): a loop guard that\n * denies a tool call the model already made twice with the same arguments,\n * then an output cap that keeps long tool results from flooding the context.\n * Ported from examples/coding-harness/index.ts.\n */\n\n/** Test runs are expected to repeat (before and after every change), so the loop guard lets them through. */\nconst TEST_COMMAND = /^\\s*node --test\\b/;\n\nfunction canonical(value: unknown): string {\n  const record = (value ?? {}) as Record<string, unknown>;\n  return JSON.stringify(Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b))));\n}\n\n/** How many earlier calls in the current turn (since the last user message) match this one. */\nfunction earlierCalls(messages: readonly Message[], toolCallId: string, toolName: string, args: unknown): number {\n  const key = canonical(args);\n  let count = 0;\n  for (let i = messages.length - 1; i >= 0 && messages[i].role !== 'user'; i--) {\n    for (const call of messages[i].toolCalls ?? []) {\n      if (call.id === toolCallId || call.function.name !== toolName) continue;\n      try {\n        if (canonical(JSON.parse(call.function.arguments || '{}')) === key) count++;\n      } catch {\n        // unparseable arguments never match\n      }\n    }\n  }\n  return count;\n}\n\n/**\n * Deny a tool call the model already made `maxRepeats` times with the same\n * arguments in the current turn. The count is read from the conversation\n * itself, so separate runs and separately loaded agents never share it and a\n * pause for approval does not reset it; test commands and the post-approval\n * re-fire of a paused call are let through.\n */\nexport function loopGuard(maxRepeats = 2): AgentHook {\n  return {\n    name: 'loop-guard',\n    preToolCall(ctx) {\n      if (ctx.resumedAfterApproval) return undefined;\n      if (ctx.toolName === 'shell' && TEST_COMMAND.test(String(ctx.args.command ?? ''))) return undefined;\n      if (earlierCalls(ctx.messages, ctx.toolCallId, ctx.toolName, ctx.args) >= 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\nexport default [loopGuard(), outputCap()];\n"
+      "content": "import type { AgentHook, Message } from '@linuxdevil/lousho';\n\n/**\n * The kit's hooks (pointed at by `agent.json`'s `hooks`): a loop guard that\n * denies a tool call the model already made twice with the same arguments,\n * then an output cap that keeps long tool results from flooding the context.\n * Ported from examples/coding-harness/index.ts.\n */\n\n/** Test runs are expected to repeat (before and after every change), so the loop guard lets them through. */\nconst TEST_COMMAND = /^\\s*node --test\\b/;\n\nfunction canonical(value: unknown): string {\n  const record = (value ?? {}) as Record<string, unknown>;\n  return JSON.stringify(Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b))));\n}\n\n/** How many earlier calls in the current turn (since the last user message) match this one. */\nfunction earlierCalls(messages: readonly Message[], toolCallId: string, toolName: string, args: unknown): number {\n  const key = canonical(args);\n  let count = 0;\n  for (let i = messages.length - 1; i >= 0 && messages[i].role !== 'user'; i--) {\n    for (const call of messages[i].toolCalls ?? []) {\n      if (call.id === toolCallId || call.function.name !== toolName) continue;\n      try {\n        if (canonical(JSON.parse(call.function.arguments || '{}')) === key) count++;\n      } catch {\n        // unparseable arguments never match\n      }\n    }\n  }\n  return count;\n}\n\n/**\n * Deny a tool call the model already made `maxRepeats` times with the same\n * arguments in the current turn. The count is read from the conversation\n * itself, so separate runs and separately loaded agents never share it and a\n * pause for approval does not reset it; test commands and the post-approval\n * re-fire of a paused call are let through.\n */\nexport function loopGuard(maxRepeats = 2): AgentHook {\n  return {\n    name: 'loop-guard',\n    preToolCall(ctx) {\n      if (ctx.resumedAfterApproval) return undefined;\n      if (ctx.toolName === 'shell' && TEST_COMMAND.test(String(ctx.args.command ?? ''))) return undefined;\n      if (earlierCalls(ctx.messages, ctx.toolCallId, ctx.toolName, ctx.args) >= 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\nexport default [loopGuard(), outputCap()];\n"
     },
     {
       "path": "instructions.md",
@@ -45,11 +45,11 @@
     },
     {
       "path": "subagents/explorer/tools/read-only.ts",
-      "content": "/**\n * The explorer's read-only file tools, bound to the same workspace as the\n * lead's (the agent directory, three levels up from this file): `read_file`,\n * `list_dir`, `glob` and `grep`, with no `write_file` / `edit_file`, so a\n * delegated reading task cannot change anything.\n */\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport { createFsTools, NodeWorkspace } from 'lousho';\n\nconst root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');\nconst workspace = new NodeWorkspace({ root });\nconst readOnly = createFsTools(workspace).filter((tool) => ['read_file', 'list_dir', 'glob', 'grep'].includes(tool.name));\n\nexport default readOnly;\n"
+      "content": "/**\n * The explorer's read-only file tools, bound to the same workspace as the\n * lead's (the agent directory, three levels up from this file): `read_file`,\n * `list_dir`, `glob` and `grep`, with no `write_file` / `edit_file`, so a\n * delegated reading task cannot change anything.\n */\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport { createFsTools, NodeWorkspace } from '@linuxdevil/lousho';\n\nconst root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');\nconst workspace = new NodeWorkspace({ root });\nconst readOnly = createFsTools(workspace).filter((tool) => ['read_file', 'list_dir', 'glob', 'grep'].includes(tool.name));\n\nexport default readOnly;\n"
     },
     {
       "path": "tools/fs.ts",
-      "content": "/**\n * The kit's workspace tools: every file tool and a shell limited to an allow\n * list. The workspace is the agent directory itself - the kit works on the\n * project it is installed into, and `lousho build` bundles this file next to\n * the agent so the built server's workspace is the bundled directory.\n *\n * Because the agent's own files share that directory, the file tools refuse\n * to change them: `agent.*`, `approve.*`, `hooks.*`, `instructions*`,\n * `lousho-registry.json`, and everything under `.lousho/`, `tools/`,\n * `skills/`, `subagents/`, `.git/` and `node_modules/`. Without this the\n * model could rewrite its own approver or permissions.\n *\n * `checkpoints` backs up every write and edit (to `.lousho/checkpoints/` in\n * the workspace, so a rewind still works after a restart); `workspace`,\n * `checkpoints` and `fs` are also exported for code that wants the same\n * objects (a test, or another tool file).\n */\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport {\n  createFsTools,\n  createShellTool,\n  FileWorkspaceCheckpointStore,\n  NodeWorkspace,\n  normalizeWorkspacePath,\n  WorkspaceCheckpoints,\n  WorkspaceError,\n  type FsProvider,\n} from 'lousho';\n\nconst root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');\n\nexport const workspace = new NodeWorkspace({ root });\nexport const checkpoints = new WorkspaceCheckpoints(workspace, {\n  store: new FileWorkspaceCheckpointStore(path.join(root, '.lousho', 'checkpoints')),\n});\n\nconst PROTECTED_DIRS = new Set(['.lousho', 'tools', 'skills', 'subagents', 'instructions', '.git', 'node_modules']);\nconst PROTECTED_ROOT_FILE = /^(agent|approve|hooks)(\\..*)?$|^instructions|^lousho-registry\\.json$/;\n\n/** True when `p` names one of the agent's own files (case-insensitive; Windows aliases included). */\nexport function isAgentFile(p: string): boolean {\n  // Windows drops trailing dots and spaces, and `APPROV~1.TS` may alias `approve.ts`.\n  const segments = normalizeWorkspacePath(p)\n    .split('/')\n    .map((s) => s.replace(/[. ]+$/, '').toLowerCase());\n  if (segments.some((s) => /~\\d/.test(s))) return true;\n  if (PROTECTED_DIRS.has(segments[0])) return true;\n  return segments.length === 1 && PROTECTED_ROOT_FILE.test(segments[0]);\n}\n\nfunction guard(p: string): void {\n  if (isAgentFile(p)) {\n    throw new WorkspaceError(`${p} is part of the agent's own configuration and cannot be changed. Change the project's code instead.`);\n  }\n}\n\n/** The workspace as the file tools see it: reads pass through, writes to the agent's own files are refused. */\nconst projectFiles: FsProvider = {\n  readFile: (p) => workspace.readFile(p),\n  stat: (p) => workspace.stat(p),\n  readdir: (p) => workspace.readdir(p),\n  getMode: (p) => workspace.getMode(p),\n  async writeFile(p, content) {\n    guard(p);\n    return workspace.writeFile(p, content);\n  },\n  async mkdir(p) {\n    guard(p);\n    return workspace.mkdir(p);\n  },\n  async rm(p, options) {\n    guard(p);\n    return workspace.rm(p, options);\n  },\n  async chmod(p, mode) {\n    guard(p);\n    return workspace.chmod(p, mode);\n  },\n};\n\nexport const fs = createFsTools(projectFiles, { checkpoints });\n\n/**\n * A shell that only runs the commands a coding harness needs. `node --test`\n * takes test file paths but no flags (a flag such as\n * `--test-reporter-destination=../x` writes outside the project); `git diff`\n * is left out because `git diff --output=<file>` writes anywhere.\n */\nexport const shell = createShellTool(workspace, {\n  needsApproval: false,\n  allow: [/^node --test( (?!-)(?![^ ]*\\.\\.)[\\w./-]+)*$/, /^git status( (-s|--short|--porcelain))?$/],\n});\n\nexport default fs;\n"
+      "content": "/**\n * The kit's workspace tools: every file tool and a shell limited to an allow\n * list. The workspace is the agent directory itself - the kit works on the\n * project it is installed into, and `lousho build` bundles this file next to\n * the agent so the built server's workspace is the bundled directory.\n *\n * Because the agent's own files share that directory, the file tools refuse\n * to change them: `agent.*`, `approve.*`, `hooks.*`, `instructions*`,\n * `lousho-registry.json`, and everything under `.lousho/`, `tools/`,\n * `skills/`, `subagents/`, `.git/` and `node_modules/`. Without this the\n * model could rewrite its own approver or permissions.\n *\n * `checkpoints` backs up every write and edit (to `.lousho/checkpoints/` in\n * the workspace, so a rewind still works after a restart); `workspace`,\n * `checkpoints` and `fs` are also exported for code that wants the same\n * objects (a test, or another tool file).\n */\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport {\n  createFsTools,\n  createShellTool,\n  FileWorkspaceCheckpointStore,\n  NodeWorkspace,\n  normalizeWorkspacePath,\n  WorkspaceCheckpoints,\n  WorkspaceError,\n  type FsProvider,\n} from '@linuxdevil/lousho';\n\nconst root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');\n\nexport const workspace = new NodeWorkspace({ root });\nexport const checkpoints = new WorkspaceCheckpoints(workspace, {\n  store: new FileWorkspaceCheckpointStore(path.join(root, '.lousho', 'checkpoints')),\n});\n\nconst PROTECTED_DIRS = new Set(['.lousho', 'tools', 'skills', 'subagents', 'instructions', '.git', 'node_modules']);\nconst PROTECTED_ROOT_FILE = /^(agent|approve|hooks)(\\..*)?$|^instructions|^lousho-registry\\.json$/;\n\n/** True when `p` names one of the agent's own files (case-insensitive; Windows aliases included). */\nexport function isAgentFile(p: string): boolean {\n  // Windows drops trailing dots and spaces, and `APPROV~1.TS` may alias `approve.ts`.\n  const segments = normalizeWorkspacePath(p)\n    .split('/')\n    .map((s) => s.replace(/[. ]+$/, '').toLowerCase());\n  if (segments.some((s) => /~\\d/.test(s))) return true;\n  if (PROTECTED_DIRS.has(segments[0])) return true;\n  return segments.length === 1 && PROTECTED_ROOT_FILE.test(segments[0]);\n}\n\nfunction guard(p: string): void {\n  if (isAgentFile(p)) {\n    throw new WorkspaceError(`${p} is part of the agent's own configuration and cannot be changed. Change the project's code instead.`);\n  }\n}\n\n/** The workspace as the file tools see it: reads pass through, writes to the agent's own files are refused. */\nconst projectFiles: FsProvider = {\n  readFile: (p) => workspace.readFile(p),\n  stat: (p) => workspace.stat(p),\n  readdir: (p) => workspace.readdir(p),\n  getMode: (p) => workspace.getMode(p),\n  async writeFile(p, content) {\n    guard(p);\n    return workspace.writeFile(p, content);\n  },\n  async mkdir(p) {\n    guard(p);\n    return workspace.mkdir(p);\n  },\n  async rm(p, options) {\n    guard(p);\n    return workspace.rm(p, options);\n  },\n  async chmod(p, mode) {\n    guard(p);\n    return workspace.chmod(p, mode);\n  },\n};\n\nexport const fs = createFsTools(projectFiles, { checkpoints });\n\n/**\n * A shell that only runs the commands a coding harness needs. `node --test`\n * takes test file paths but no flags (a flag such as\n * `--test-reporter-destination=../x` writes outside the project); `git diff`\n * is left out because `git diff --output=<file>` writes anywhere.\n */\nexport const shell = createShellTool(workspace, {\n  needsApproval: false,\n  allow: [/^node --test( (?!-)(?![^ ]*\\.\\.)[\\w./-]+)*$/, /^git status( (-s|--short|--porcelain))?$/],\n});\n\nexport default fs;\n"
     }
   ],
   "permissions": {
@@ -63,7 +63,7 @@
     "exec": true
   },
   "dependencies": [
-    "lousho",
+    "@linuxdevil/lousho",
     "@earendil-works/pi-ai",
     "@earendil-works/pi-coding-agent"
   ]
diff --git a/registry/dist/items/generic-webhook.json b/registry/dist/items/generic-webhook.json
index af0b311e5..644633d31 100644
--- a/registry/dist/items/generic-webhook.json
+++ b/registry/dist/items/generic-webhook.json
@@ -5,7 +5,7 @@
   "files": [
     {
       "path": "channels/generic-webhook.ts",
-      "content": "import { webhookChannel } from 'lousho';\n\n// Verifies `x-signature-256: sha256=<hmac of the raw body>` against WEBHOOK_SECRET\n// (the format GitHub webhooks use). The channel refuses to load when the secret\n// is not set, so a deployment can never run unauthenticated by accident.\nexport default webhookChannel({\n  name: 'generic-webhook',\n  secret: process.env.WEBHOOK_SECRET ?? '',\n});\n"
+      "content": "import { webhookChannel } from '@linuxdevil/lousho';\n\n// Verifies `x-signature-256: sha256=<hmac of the raw body>` against WEBHOOK_SECRET\n// (the format GitHub webhooks use). The channel refuses to load when the secret\n// is not set, so a deployment can never run unauthenticated by accident.\nexport default webhookChannel({\n  name: 'generic-webhook',\n  secret: process.env.WEBHOOK_SECRET ?? '',\n});\n"
     }
   ],
   "permissions": {
@@ -14,6 +14,6 @@
     ]
   },
   "dependencies": [
-    "lousho"
+    "@linuxdevil/lousho"
   ]
 }
diff --git a/registry/dist/items/github-issues.json b/registry/dist/items/github-issues.json
index 616ce297b..2172313f4 100644
--- a/registry/dist/items/github-issues.json
+++ b/registry/dist/items/github-issues.json
@@ -5,7 +5,7 @@
   "files": [
     {
       "path": "tools/github-issues.ts",
-      "content": "import { z } from 'zod';\nimport { defineTool } from 'lousho';\n\nfunction token(): string {\n  const value = process.env.GITHUB_TOKEN;\n  if (!value) throw new Error('GITHUB_TOKEN is not set; create a token with issues access and export it.');\n  return value;\n}\n\nasync function github(path: string, init?: RequestInit): Promise<unknown> {\n  const response = await fetch(`https://api.github.com${path}`, {\n    ...init,\n    headers: {\n      authorization: `Bearer ${token()}`,\n      accept: 'application/vnd.github+json',\n      'x-github-api-version': '2022-11-28',\n      ...init?.headers,\n    },\n  });\n  if (!response.ok) throw new Error(`GitHub API request failed: HTTP ${response.status}`);\n  return response.json();\n}\n\ninterface ListedIssue {\n  number: number;\n  title: string;\n  state: string;\n  html_url: string;\n  pull_request?: unknown;\n}\n\nconst repoArgs = {\n  owner: z.string().describe('The user or organisation that owns the repository'),\n  repo: z.string().describe('The repository name'),\n};\n\nconst list = defineTool({\n  name: 'github-issues-list',\n  description: 'List issues of a GitHub repository (pull requests are filtered out)',\n  input: z.object({\n    ...repoArgs,\n    state: z.enum(['open', 'closed', 'all']).default('open'),\n    limit: z.number().int().min(1).max(100).default(20),\n  }),\n  async execute({ owner, repo, state, limit }) {\n    const issues = (await github(`/repos/${owner}/${repo}/issues?state=${state}&per_page=${limit}`)) as ListedIssue[];\n    return issues\n      .filter((issue) => issue.pull_request === undefined)\n      .map((issue) => ({ number: issue.number, title: issue.title, state: issue.state, url: issue.html_url }));\n  },\n});\n\nconst create = defineTool({\n  name: 'github-issues-create',\n  description: 'Create an issue in a GitHub repository',\n  input: z.object({\n    ...repoArgs,\n    title: z.string(),\n    body: z.string().default(''),\n  }),\n  needsApproval: true,\n  async execute({ owner, repo, title, body }) {\n    const issue = (await github(`/repos/${owner}/${repo}/issues`, { method: 'POST', body: JSON.stringify({ title, body }) })) as {\n      number: number;\n      html_url: string;\n    };\n    return { number: issue.number, url: issue.html_url };\n  },\n});\n\nexport default [list, create];\n"
+      "content": "import { z } from 'zod';\nimport { defineTool } from '@linuxdevil/lousho';\n\nfunction token(): string {\n  const value = process.env.GITHUB_TOKEN;\n  if (!value) throw new Error('GITHUB_TOKEN is not set; create a token with issues access and export it.');\n  return value;\n}\n\nasync function github(path: string, init?: RequestInit): Promise<unknown> {\n  const response = await fetch(`https://api.github.com${path}`, {\n    ...init,\n    headers: {\n      authorization: `Bearer ${token()}`,\n      accept: 'application/vnd.github+json',\n      'x-github-api-version': '2022-11-28',\n      ...init?.headers,\n    },\n  });\n  if (!response.ok) throw new Error(`GitHub API request failed: HTTP ${response.status}`);\n  return response.json();\n}\n\ninterface ListedIssue {\n  number: number;\n  title: string;\n  state: string;\n  html_url: string;\n  pull_request?: unknown;\n}\n\nconst repoArgs = {\n  owner: z.string().describe('The user or organisation that owns the repository'),\n  repo: z.string().describe('The repository name'),\n};\n\nconst list = defineTool({\n  name: 'github-issues-list',\n  description: 'List issues of a GitHub repository (pull requests are filtered out)',\n  input: z.object({\n    ...repoArgs,\n    state: z.enum(['open', 'closed', 'all']).default('open'),\n    limit: z.number().int().min(1).max(100).default(20),\n  }),\n  async execute({ owner, repo, state, limit }) {\n    const issues = (await github(`/repos/${owner}/${repo}/issues?state=${state}&per_page=${limit}`)) as ListedIssue[];\n    return issues\n      .filter((issue) => issue.pull_request === undefined)\n      .map((issue) => ({ number: issue.number, title: issue.title, state: issue.state, url: issue.html_url }));\n  },\n});\n\nconst create = defineTool({\n  name: 'github-issues-create',\n  description: 'Create an issue in a GitHub repository',\n  input: z.object({\n    ...repoArgs,\n    title: z.string(),\n    body: z.string().default(''),\n  }),\n  needsApproval: true,\n  async execute({ owner, repo, title, body }) {\n    const issue = (await github(`/repos/${owner}/${repo}/issues`, { method: 'POST', body: JSON.stringify({ title, body }) })) as {\n      number: number;\n      html_url: string;\n    };\n    return { number: issue.number, url: issue.html_url };\n  },\n});\n\nexport default [list, create];\n"
     }
   ],
   "permissions": {
@@ -18,7 +18,7 @@
     "needsApproval": true
   },
   "dependencies": [
-    "lousho",
+    "@linuxdevil/lousho",
     "zod"
   ]
 }
diff --git a/registry/dist/items/inbox-triage.json b/registry/dist/items/inbox-triage.json
index 83d5d1203..666c03857 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';\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"
+      "content": "import type { ApproveToolCall } from '@linuxdevil/lousho';\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';\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"
+      "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 '@linuxdevil/lousho';\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';\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"
+      "content": "import type { AgentHook } from '@linuxdevil/lousho';\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",
@@ -33,7 +33,7 @@
     },
     {
       "path": "kit.test.ts",
-      "content": "/**\n * The inbox-triage kit, tested offline: `loadAgentDir()` reads the kit's own\n * directory and a scripted `mockModel` drives the triage loop - classify,\n * draft, pause on `send_reply`, deny (nothing leaves) and approve (the reply\n * lands in the outbox). The store is a temp dir via INBOX_TRIAGE_HOME so the\n * kit's seeded data/ stays untouched.\n *\n * The kit's files import `lousho` by name, which resolves to\n * the workspace self-link (dist/) inside this repo - like\n * examples/coding-harness/kit.test.ts this needs `npm run build` to have run.\n */\nimport { afterAll, beforeEach, describe, expect, it, vi } from 'vitest';\nimport * as fs from 'node:fs';\nimport * as os from 'node:os';\nimport * as path from 'node:path';\nimport { loadAgentDir, resolveAgentDir, startSchedules } from 'lousho';\nimport type { ChannelContext, ChannelInbound, ChannelRequest } from 'lousho';\nimport { mockModel, type MockModel } from 'lousho/testing';\n\nconst KIT = __dirname;\nconst home = fs.mkdtempSync(path.join(os.tmpdir(), 'inbox-triage-'));\nprocess.env.INBOX_TRIAGE_HOME = home;\n\nconst SEED = [\n  { id: 'm-budget', from: 'priya@acme.com', subject: 'Invoice #1042 question', body: 'Hi - the invoice lists 12 seats but we only have 10. Confirm before Friday?', receivedAt: '2026-01-05T09:12:00.000Z', status: 'new' },\n  { id: 'm-spam', from: 'winner@lottery-prizes.example', subject: 'You WON $5,000,000', body: 'Claim your prize now - reply with your bank details.', receivedAt: '2026-01-05T07:30:00.000Z', status: 'new' },\n];\n\nfunction resetHome() {\n  fs.rmSync(home, { recursive: true, force: true });\n  fs.mkdirSync(home, { recursive: true });\n  fs.writeFileSync(path.join(home, 'inbox.json'), `${JSON.stringify(SEED, null, 2)}\\n`, 'utf8');\n}\n\ninterface JsonRecord {\n  [key: string]: unknown;\n}\n\nfunction readJson(name: string): JsonRecord[] {\n  return JSON.parse(fs.readFileSync(path.join(home, name), 'utf8')) as JsonRecord[];\n}\n\nconst exists = (name: string): boolean => fs.existsSync(path.join(home, name));\n\nconst toolOutputs = (provider: MockModel): string =>\n  provider.calls[provider.calls.length - 1].messages\n    .filter((m) => m.role === 'tool')\n    .map((m) => String(m.content))\n    .join('\\n');\n\nconst systemOf = (call: { messages: readonly { role: string; content: unknown }[] }): string =>\n  String(call.messages.find((m) => m.role === 'system')?.content);\n\nbeforeEach(resetHome);\nafterAll(() => fs.rmSync(home, { recursive: true, force: true }));\n\ndescribe('the kit directory, resolved', () => {\n  it('discovers tools, the poll schedule, the inbound channel and the senders memory', async () => {\n    const { config, manifest, schedules, channels } = await resolveAgentDir(KIT, { provider: mockModel(['x']) });\n\n    expect(manifest.name).toBe('inbox-triage');\n    expect([...manifest.tools].sort()).toEqual(\n      ['classify_message', 'delete_message', 'draft_reply', 'list_drafts', 'list_messages', 'mark_processed', 'read_message', 'send_reply'].sort()\n    );\n    expect(manifest.schedules).toEqual(['poll-inbox']);\n    expect(manifest.channels).toEqual(['inbound']);\n    expect(manifest.memory).toEqual(['senders']);\n    expect(schedules[0].cron).toBe('*/15 * * * *');\n    expect(schedules[0].prompt).toContain('list_messages');\n    expect(channels[0].name).toBe('inbound');\n    expect(manifest.files.some((file) => file.endsWith('hooks.ts'))).toBe(true);\n  });\n\n  it('appends instructions/openai.md when the model id names the openai family', async () => {\n    const { config } = await resolveAgentDir(KIT, { provider: mockModel(['x']), model: 'openai/test-model' });\n    expect(String(config.instructions)).toContain('one tool call at a time');\n  });\n});\n\ndescribe('the loaded kit, offline', () => {\n  it('classifies, drafts, pauses send_reply for the human and sends only on approval', async () => {\n    const audit: string[] = [];\n    const provider = mockModel([\n      { toolCalls: [{ name: 'list_messages', args: { status: 'new' } }] },\n      { toolCalls: [{ name: 'classify_message', args: { id: 'm-budget', category: 'reply-needed', reason: 'customer billing question' } }] },\n      { toolCalls: [{ name: 'remember_senders', args: { text: 'priya@acme.com - billing contact at Acme, wants plain acknowledgements' } }] },\n      { toolCalls: [{ name: 'draft_reply', args: { messageId: 'm-budget', body: 'Hi Priya - you are right, it is 10 seats. A corrected invoice goes out Friday.' } }] },\n      { toolCalls: [{ name: 'send_reply', args: { messageId: 'm-budget', draftId: 'draft-m-budget-1' } }] },\n      // the run continues after the denial\n      { toolCalls: [{ name: 'mark_processed', args: { id: 'm-spam' } }] },\n      { text: 'Held the reply to Priya for review; processed the spam message.' },\n      // second run: the human approves\n      { toolCalls: [{ name: 'send_reply', args: { messageId: 'm-budget', draftId: 'draft-m-budget-1' } }] },\n      { text: 'Sent the corrected-invoice reply to Priya.' },\n      // third run: recall surfaces the sender fact in the system prompt\n      { text: 'Done.' },\n    ]);\n    const agent = await loadAgentDir(KIT, {\n      provider,\n      onPermissionDecision: (entry) => audit.push(`${entry.toolName}:${entry.decision}`),\n    });\n\n    const paused = await agent.send('Triage the inbox.');\n    expect(paused.finishReason).toBe('awaiting-approval');\n    expect(exists('outbox.json')).toBe(false); // nothing leaves before the human decides\n\n    const denied = await agent.approvals.resolve({ id: paused.approvalId!, approved: false, note: 'Not yet' });\n    expect(denied.finishReason).toBe('stop');\n    expect(exists('outbox.json')).toBe(false);\n\n    const drafts = readJson('drafts.json');\n    expect(drafts).toHaveLength(1);\n    expect(drafts[0]).toMatchObject({ id: 'draft-m-budget-1', messageId: 'm-budget', to: 'priya@acme.com', status: 'draft' });\n    const message = readJson('inbox.json').find((m) => m.id === 'm-budget');\n    expect(message).toMatchObject({ category: 'reply-needed', status: 'triaged' });\n    expect(readJson('inbox.json').find((m) => m.id === 'm-spam')).toMatchObject({ status: 'processed' });\n    expect(audit).toContain('send_reply:ask');\n\n    // memory was written: senders slot, shared scope (no sender principal in a bare send); keys are `<slot>#<scope>`\n    const memoryFile = path.join(home, 'memory', `${encodeURIComponent('senders#shared')}.json`);\n    expect(fs.existsSync(memoryFile)).toBe(true);\n    expect(fs.readFileSync(memoryFile, 'utf8')).toContain('priya@acme.com');\n\n    const pausedAgain = await agent.send('Send the pending reply.');\n    expect(pausedAgain.finishReason).toBe('awaiting-approval');\n    const done = await agent.approvals.resolve({ id: pausedAgain.approvalId!, approved: true });\n    expect(done.text).toContain('Sent');\n\n    const outbox = readJson('outbox.json');\n    expect(outbox).toHaveLength(1);\n    expect(outbox[0]).toMatchObject({ messageId: 'm-budget', draftId: 'draft-m-budget-1', to: 'priya@acme.com' });\n    expect(String(outbox[0].body)).toContain('10 seats');\n    expect(readJson('inbox.json').find((m) => m.id === 'm-budget')).toMatchObject({ status: 'replied' });\n    expect(readJson('drafts.json')[0]).toMatchObject({ status: 'sent' });\n\n    // the remembered sender fact is recalled into the next run's system prompt\n    await agent.send('Anything new?');\n    expect(systemOf(provider.calls[provider.calls.length - 1])).toContain('<memory name=\"senders\">');\n    expect(systemOf(provider.calls[provider.calls.length - 1])).toContain('priya@acme.com');\n  }, 30_000);\n\n  it('denies delete_message outright and refuses a send_reply with placeholders before the pause', async () => {\n    const provider = mockModel([\n      { toolCalls: [{ name: 'delete_message', args: { id: 'm-spam' } }] },\n      { toolCalls: [{ name: 'send_reply', args: { messageId: 'm-budget', body: 'Hi [NAME], thanks for writing in.' } }] },\n      { text: 'Deletion denied; the placeholder draft was refused too.' },\n    ]);\n    const agent = await loadAgentDir(KIT, { provider });\n\n    const result = await agent.send('Delete the spam and reply to the invoice mail.');\n\n    expect(result.finishReason).toBe('stop'); // no pause: deny rule + hook, not an approval\n    expect(readJson('inbox.json').find((m) => m.id === 'm-spam')).toMatchObject({ status: 'new' });\n    const outputs = toolOutputs(provider);\n    expect(outputs).toContain('Triage never deletes');\n    expect(outputs).toContain('[NAME]');\n    expect(exists('outbox.json')).toBe(false);\n  });\n});\n\ndescribe('intake', () => {\n  it('poll-inbox fires its sweep prompt on the cron tick', async () => {\n    const provider = mockModel([{ text: 'Nothing new.' }]);\n    const agent = await loadAgentDir(KIT, { provider });\n    const { schedules } = await resolveAgentDir(KIT, { provider });\n\n    let now = Date.parse('2026-01-05T12:00:00Z');\n    let fire: (() => void) | undefined;\n    const running = startSchedules(agent, schedules, {\n      now: () => now,\n      setTimer: (fn) => {\n        fire = fn;\n        return () => {};\n      },\n    });\n    try {\n      expect(fire).toBeDefined();\n      now += 15 * 60 * 1000; // past the next quarter-hour boundary\n      fire!();\n      await vi.waitFor(() => expect(provider.calls.length).toBe(1));\n      const prompt = String(provider.calls[0].messages.at(-1)?.content);\n      expect(prompt).toContain('list_messages');\n      expect(prompt).toContain('classify_message');\n    } finally {\n      running.stop();\n    }\n  });\n\n  it('the inbound channel files a posted message and hands the turn to the sender', async () => {\n    const { channels } = await resolveAgentDir(KIT, { provider: mockModel(['x']) });\n    const channel = channels[0];\n\n    const body = JSON.stringify({ from: 'bob@corp.example', subject: 'Pricing?', body: 'What does the team plan cost?' });\n    const req: ChannelRequest = { method: 'POST', url: '/channels/inbound', headers: {}, rawBody: new TextEncoder().encode(body), text: body };\n    const ctx: ChannelContext = {\n      approval: async () => undefined,\n      sessionId: (key) => `inbound:${key}`,\n      hasSession: async () => false,\n      pendingQuestion: async () => undefined,\n    };\n\n    expect(await channel.verify?.(req)).toBe(true); // INBOUND_TOKEN unset: open intake\n    const inbound = (await channel.parse(req, () => {}, ctx)) as ChannelInbound;\n    expect(inbound.sessionKey).toBe('bob@corp.example');\n    expect(inbound.metadata).toMatchObject({ sender: 'bob@corp.example' });\n    expect(inbound.principal).toMatchObject({ id: 'bob@corp.example' });\n    expect(String(inbound.input)).toContain('Pricing?');\n\n    const message = readJson('inbox.json').find((m) => m.from === 'bob@corp.example');\n    expect(message).toMatchObject({ subject: 'Pricing?', status: 'new' });\n\n    let responded: unknown;\n    await channel.reply({ inbound, sessionId: 's-1', text: 'triaged', respond: (_status, out) => (responded = out) });\n    expect(responded).toMatchObject({ ok: true, messageId: message?.id });\n  });\n});\n\ndescribe('live', () => {\n  it.skipIf(!process.env.OPENROUTER_API_KEY)('triages the seeded inbox on the real model', async () => {\n    const agent = await loadAgentDir(KIT);\n    const result = await agent.send('Triage the inbox: classify everything new, draft a reply where one is needed.');\n    // whatever it does, it must stop at a send for a human - or stop cleanly\n    if (result.finishReason === 'awaiting-approval') {\n      await agent.approvals.resolve({ id: result.approvalId!, approved: false, note: 'test: do not actually send' });\n    }\n    const inbox = readJson('inbox.json');\n    expect(inbox.every((message) => message.status !== 'new')).toBe(true);\n    expect(exists('outbox.json')).toBe(false);\n  }, 120_000);\n});\n"
+      "content": "/**\n * The inbox-triage kit, tested offline: `loadAgentDir()` reads the kit's own\n * directory and a scripted `mockModel` drives the triage loop - classify,\n * draft, pause on `send_reply`, deny (nothing leaves) and approve (the reply\n * lands in the outbox). The store is a temp dir via INBOX_TRIAGE_HOME so the\n * kit's seeded data/ stays untouched.\n *\n * The kit's files import `@linuxdevil/lousho` by name, which resolves to\n * the workspace self-link (dist/) inside this repo - like\n * examples/coding-harness/kit.test.ts this needs `npm run build` to have run.\n */\nimport { afterAll, beforeEach, describe, expect, it, vi } from 'vitest';\nimport * as fs from 'node:fs';\nimport * as os from 'node:os';\nimport * as path from 'node:path';\nimport { loadAgentDir, resolveAgentDir, startSchedules } from '@linuxdevil/lousho';\nimport type { ChannelContext, ChannelInbound, ChannelRequest } from '@linuxdevil/lousho';\nimport { mockModel, type MockModel } from '@linuxdevil/lousho/testing';\n\nconst KIT = __dirname;\nconst home = fs.mkdtempSync(path.join(os.tmpdir(), 'inbox-triage-'));\nprocess.env.INBOX_TRIAGE_HOME = home;\n\nconst SEED = [\n  { id: 'm-budget', from: 'priya@acme.com', subject: 'Invoice #1042 question', body: 'Hi - the invoice lists 12 seats but we only have 10. Confirm before Friday?', receivedAt: '2026-01-05T09:12:00.000Z', status: 'new' },\n  { id: 'm-spam', from: 'winner@lottery-prizes.example', subject: 'You WON $5,000,000', body: 'Claim your prize now - reply with your bank details.', receivedAt: '2026-01-05T07:30:00.000Z', status: 'new' },\n];\n\nfunction resetHome() {\n  fs.rmSync(home, { recursive: true, force: true });\n  fs.mkdirSync(home, { recursive: true });\n  fs.writeFileSync(path.join(home, 'inbox.json'), `${JSON.stringify(SEED, null, 2)}\\n`, 'utf8');\n}\n\ninterface JsonRecord {\n  [key: string]: unknown;\n}\n\nfunction readJson(name: string): JsonRecord[] {\n  return JSON.parse(fs.readFileSync(path.join(home, name), 'utf8')) as JsonRecord[];\n}\n\nconst exists = (name: string): boolean => fs.existsSync(path.join(home, name));\n\nconst toolOutputs = (provider: MockModel): string =>\n  provider.calls[provider.calls.length - 1].messages\n    .filter((m) => m.role === 'tool')\n    .map((m) => String(m.content))\n    .join('\\n');\n\nconst systemOf = (call: { messages: readonly { role: string; content: unknown }[] }): string =>\n  String(call.messages.find((m) => m.role === 'system')?.content);\n\nbeforeEach(resetHome);\nafterAll(() => fs.rmSync(home, { recursive: true, force: true }));\n\ndescribe('the kit directory, resolved', () => {\n  it('discovers tools, the poll schedule, the inbound channel and the senders memory', async () => {\n    const { config, manifest, schedules, channels } = await resolveAgentDir(KIT, { provider: mockModel(['x']) });\n\n    expect(manifest.name).toBe('inbox-triage');\n    expect([...manifest.tools].sort()).toEqual(\n      ['classify_message', 'delete_message', 'draft_reply', 'list_drafts', 'list_messages', 'mark_processed', 'read_message', 'send_reply'].sort()\n    );\n    expect(manifest.schedules).toEqual(['poll-inbox']);\n    expect(manifest.channels).toEqual(['inbound']);\n    expect(manifest.memory).toEqual(['senders']);\n    expect(schedules[0].cron).toBe('*/15 * * * *');\n    expect(schedules[0].prompt).toContain('list_messages');\n    expect(channels[0].name).toBe('inbound');\n    expect(manifest.files.some((file) => file.endsWith('hooks.ts'))).toBe(true);\n  });\n\n  it('appends instructions/openai.md when the model id names the openai family', async () => {\n    const { config } = await resolveAgentDir(KIT, { provider: mockModel(['x']), model: 'openai/test-model' });\n    expect(String(config.instructions)).toContain('one tool call at a time');\n  });\n});\n\ndescribe('the loaded kit, offline', () => {\n  it('classifies, drafts, pauses send_reply for the human and sends only on approval', async () => {\n    const audit: string[] = [];\n    const provider = mockModel([\n      { toolCalls: [{ name: 'list_messages', args: { status: 'new' } }] },\n      { toolCalls: [{ name: 'classify_message', args: { id: 'm-budget', category: 'reply-needed', reason: 'customer billing question' } }] },\n      { toolCalls: [{ name: 'remember_senders', args: { text: 'priya@acme.com - billing contact at Acme, wants plain acknowledgements' } }] },\n      { toolCalls: [{ name: 'draft_reply', args: { messageId: 'm-budget', body: 'Hi Priya - you are right, it is 10 seats. A corrected invoice goes out Friday.' } }] },\n      { toolCalls: [{ name: 'send_reply', args: { messageId: 'm-budget', draftId: 'draft-m-budget-1' } }] },\n      // the run continues after the denial\n      { toolCalls: [{ name: 'mark_processed', args: { id: 'm-spam' } }] },\n      { text: 'Held the reply to Priya for review; processed the spam message.' },\n      // second run: the human approves\n      { toolCalls: [{ name: 'send_reply', args: { messageId: 'm-budget', draftId: 'draft-m-budget-1' } }] },\n      { text: 'Sent the corrected-invoice reply to Priya.' },\n      // third run: recall surfaces the sender fact in the system prompt\n      { text: 'Done.' },\n    ]);\n    const agent = await loadAgentDir(KIT, {\n      provider,\n      onPermissionDecision: (entry) => audit.push(`${entry.toolName}:${entry.decision}`),\n    });\n\n    const paused = await agent.send('Triage the inbox.');\n    expect(paused.finishReason).toBe('awaiting-approval');\n    expect(exists('outbox.json')).toBe(false); // nothing leaves before the human decides\n\n    const denied = await agent.approvals.resolve({ id: paused.approvalId!, approved: false, note: 'Not yet' });\n    expect(denied.finishReason).toBe('stop');\n    expect(exists('outbox.json')).toBe(false);\n\n    const drafts = readJson('drafts.json');\n    expect(drafts).toHaveLength(1);\n    expect(drafts[0]).toMatchObject({ id: 'draft-m-budget-1', messageId: 'm-budget', to: 'priya@acme.com', status: 'draft' });\n    const message = readJson('inbox.json').find((m) => m.id === 'm-budget');\n    expect(message).toMatchObject({ category: 'reply-needed', status: 'triaged' });\n    expect(readJson('inbox.json').find((m) => m.id === 'm-spam')).toMatchObject({ status: 'processed' });\n    expect(audit).toContain('send_reply:ask');\n\n    // memory was written: senders slot, shared scope (no sender principal in a bare send); keys are `<slot>#<scope>`\n    const memoryFile = path.join(home, 'memory', `${encodeURIComponent('senders#shared')}.json`);\n    expect(fs.existsSync(memoryFile)).toBe(true);\n    expect(fs.readFileSync(memoryFile, 'utf8')).toContain('priya@acme.com');\n\n    const pausedAgain = await agent.send('Send the pending reply.');\n    expect(pausedAgain.finishReason).toBe('awaiting-approval');\n    const done = await agent.approvals.resolve({ id: pausedAgain.approvalId!, approved: true });\n    expect(done.text).toContain('Sent');\n\n    const outbox = readJson('outbox.json');\n    expect(outbox).toHaveLength(1);\n    expect(outbox[0]).toMatchObject({ messageId: 'm-budget', draftId: 'draft-m-budget-1', to: 'priya@acme.com' });\n    expect(String(outbox[0].body)).toContain('10 seats');\n    expect(readJson('inbox.json').find((m) => m.id === 'm-budget')).toMatchObject({ status: 'replied' });\n    expect(readJson('drafts.json')[0]).toMatchObject({ status: 'sent' });\n\n    // the remembered sender fact is recalled into the next run's system prompt\n    await agent.send('Anything new?');\n    expect(systemOf(provider.calls[provider.calls.length - 1])).toContain('<memory name=\"senders\">');\n    expect(systemOf(provider.calls[provider.calls.length - 1])).toContain('priya@acme.com');\n  }, 30_000);\n\n  it('denies delete_message outright and refuses a send_reply with placeholders before the pause', async () => {\n    const provider = mockModel([\n      { toolCalls: [{ name: 'delete_message', args: { id: 'm-spam' } }] },\n      { toolCalls: [{ name: 'send_reply', args: { messageId: 'm-budget', body: 'Hi [NAME], thanks for writing in.' } }] },\n      { text: 'Deletion denied; the placeholder draft was refused too.' },\n    ]);\n    const agent = await loadAgentDir(KIT, { provider });\n\n    const result = await agent.send('Delete the spam and reply to the invoice mail.');\n\n    expect(result.finishReason).toBe('stop'); // no pause: deny rule + hook, not an approval\n    expect(readJson('inbox.json').find((m) => m.id === 'm-spam')).toMatchObject({ status: 'new' });\n    const outputs = toolOutputs(provider);\n    expect(outputs).toContain('Triage never deletes');\n    expect(outputs).toContain('[NAME]');\n    expect(exists('outbox.json')).toBe(false);\n  });\n});\n\ndescribe('intake', () => {\n  it('poll-inbox fires its sweep prompt on the cron tick', async () => {\n    const provider = mockModel([{ text: 'Nothing new.' }]);\n    const agent = await loadAgentDir(KIT, { provider });\n    const { schedules } = await resolveAgentDir(KIT, { provider });\n\n    let now = Date.parse('2026-01-05T12:00:00Z');\n    let fire: (() => void) | undefined;\n    const running = startSchedules(agent, schedules, {\n      now: () => now,\n      setTimer: (fn) => {\n        fire = fn;\n        return () => {};\n      },\n    });\n    try {\n      expect(fire).toBeDefined();\n      now += 15 * 60 * 1000; // past the next quarter-hour boundary\n      fire!();\n      await vi.waitFor(() => expect(provider.calls.length).toBe(1));\n      const prompt = String(provider.calls[0].messages.at(-1)?.content);\n      expect(prompt).toContain('list_messages');\n      expect(prompt).toContain('classify_message');\n    } finally {\n      running.stop();\n    }\n  });\n\n  it('the inbound channel files a posted message and hands the turn to the sender', async () => {\n    const { channels } = await resolveAgentDir(KIT, { provider: mockModel(['x']) });\n    const channel = channels[0];\n\n    const body = JSON.stringify({ from: 'bob@corp.example', subject: 'Pricing?', body: 'What does the team plan cost?' });\n    const req: ChannelRequest = { method: 'POST', url: '/channels/inbound', headers: {}, rawBody: new TextEncoder().encode(body), text: body };\n    const ctx: ChannelContext = {\n      approval: async () => undefined,\n      sessionId: (key) => `inbound:${key}`,\n      hasSession: async () => false,\n      pendingQuestion: async () => undefined,\n    };\n\n    expect(await channel.verify?.(req)).toBe(true); // INBOUND_TOKEN unset: open intake\n    const inbound = (await channel.parse(req, () => {}, ctx)) as ChannelInbound;\n    expect(inbound.sessionKey).toBe('bob@corp.example');\n    expect(inbound.metadata).toMatchObject({ sender: 'bob@corp.example' });\n    expect(inbound.principal).toMatchObject({ id: 'bob@corp.example' });\n    expect(String(inbound.input)).toContain('Pricing?');\n\n    const message = readJson('inbox.json').find((m) => m.from === 'bob@corp.example');\n    expect(message).toMatchObject({ subject: 'Pricing?', status: 'new' });\n\n    let responded: unknown;\n    await channel.reply({ inbound, sessionId: 's-1', text: 'triaged', respond: (_status, out) => (responded = out) });\n    expect(responded).toMatchObject({ ok: true, messageId: message?.id });\n  });\n});\n\ndescribe('live', () => {\n  it.skipIf(!process.env.OPENROUTER_API_KEY)('triages the seeded inbox on the real model', async () => {\n    const agent = await loadAgentDir(KIT);\n    const result = await agent.send('Triage the inbox: classify everything new, draft a reply where one is needed.');\n    // whatever it does, it must stop at a send for a human - or stop cleanly\n    if (result.finishReason === 'awaiting-approval') {\n      await agent.approvals.resolve({ id: result.approvalId!, approved: false, note: 'test: do not actually send' });\n    }\n    const inbox = readJson('inbox.json');\n    expect(inbox.every((message) => message.status !== 'new')).toBe(true);\n    expect(exists('outbox.json')).toBe(false);\n  }, 120_000);\n});\n"
     },
     {
       "path": "lib/mailstore.ts",
@@ -41,19 +41,19 @@
     },
     {
       "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';\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"
+      "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 '@linuxdevil/lousho';\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",
-      "content": "import { defineSchedule } from 'lousho';\n\n/**\n * The kit's batch intake: every 15 minutes the agent sweeps the inbox for\n * anything that arrived out-of-band (the channel triages webhooks live; this\n * catches mail dropped into inbox.json by a sync job, an importer, a human).\n */\nexport default defineSchedule({\n  name: 'poll-inbox',\n  cron: '*/15 * * * *',\n  prompt: [\n    'Check the inbox for new messages with list_messages (status \"new\").',\n    'For each one: read_message, then classify_message as urgent / reply-needed / fyi / spam.',\n    'Before drafting for a sender, recall_senders for what you know about them.',\n    'For urgent and reply-needed messages, draft_reply in my voice, then call send_reply once - it pauses for my review.',\n    'For fyi and spam, just classify and mark_processed.',\n    'remember_senders anything durable you learned about a sender, then summarise what you did.',\n  ].join(' '),\n});\n"
+      "content": "import { defineSchedule } from '@linuxdevil/lousho';\n\n/**\n * The kit's batch intake: every 15 minutes the agent sweeps the inbox for\n * anything that arrived out-of-band (the channel triages webhooks live; this\n * catches mail dropped into inbox.json by a sync job, an importer, a human).\n */\nexport default defineSchedule({\n  name: 'poll-inbox',\n  cron: '*/15 * * * *',\n  prompt: [\n    'Check the inbox for new messages with list_messages (status \"new\").',\n    'For each one: read_message, then classify_message as urgent / reply-needed / fyi / spam.',\n    'Before drafting for a sender, recall_senders for what you know about them.',\n    'For urgent and reply-needed messages, draft_reply in my voice, then call send_reply once - it pauses for my review.',\n    'For fyi and spam, just classify and mark_processed.',\n    'remember_senders anything durable you learned about a sender, then summarise what you did.',\n  ].join(' '),\n});\n"
     },
     {
       "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';\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"
+      "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 '@linuxdevil/lousho';\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';\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"
+      "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 '@linuxdevil/lousho';\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": {
@@ -66,7 +66,7 @@
     "filesystem": "write"
   },
   "dependencies": [
-    "lousho",
+    "@linuxdevil/lousho",
     "zod"
   ]
 }
diff --git a/registry/dist/items/incident-response.json b/registry/dist/items/incident-response.json
index 8e5a4f448..22391ef95 100644
--- a/registry/dist/items/incident-response.json
+++ b/registry/dist/items/incident-response.json
@@ -9,15 +9,15 @@
     },
     {
       "path": "approve.ts",
-      "content": "import type { ApproveToolCall } from 'lousho';\n\n/**\n * The kit's approver (pointed at by `agent.json`'s `approve`): what reaches\n * this function is the 'ask' tier of the permission rules - production\n * remediation and anything the rules did not list.\n *\n *   tier 2 - reversible production remediation (restart, bounded scale):\n *            auto-approved, and the approval is annotated with its tier so the\n *            decision record carries why it was allowed through.\n *   tier 3 - anything hotter (scaling a service to zero, tools outside the\n *            remediation set): refused, so the call escalates to a human\n *            instead of running on the agent's own authority.\n */\nconst TIER_2 = new Set(['restart_service', 'scale_replicas']);\n\nconst approve: ApproveToolCall = ({ toolName, args }) => {\n  const environment = String(args.environment ?? 'production');\n  if (toolName === 'scale_replicas' && Number(args.replicas) === 0) {\n    return false; // scaling to zero is an outage, not a remediation - tier 3\n  }\n  if (!TIER_2.has(toolName)) {\n    return false; // outside the remediation set - tier 3, a human decides\n  }\n  return `approved at risk tier 2: '${toolName}' on ${environment} is reversible - verify within the incident window`;\n};\n\nexport default approve;\n"
+      "content": "import type { ApproveToolCall } from '@linuxdevil/lousho';\n\n/**\n * The kit's approver (pointed at by `agent.json`'s `approve`): what reaches\n * this function is the 'ask' tier of the permission rules - production\n * remediation and anything the rules did not list.\n *\n *   tier 2 - reversible production remediation (restart, bounded scale):\n *            auto-approved, and the approval is annotated with its tier so the\n *            decision record carries why it was allowed through.\n *   tier 3 - anything hotter (scaling a service to zero, tools outside the\n *            remediation set): refused, so the call escalates to a human\n *            instead of running on the agent's own authority.\n */\nconst TIER_2 = new Set(['restart_service', 'scale_replicas']);\n\nconst approve: ApproveToolCall = ({ toolName, args }) => {\n  const environment = String(args.environment ?? 'production');\n  if (toolName === 'scale_replicas' && Number(args.replicas) === 0) {\n    return false; // scaling to zero is an outage, not a remediation - tier 3\n  }\n  if (!TIER_2.has(toolName)) {\n    return false; // outside the remediation set - tier 3, a human decides\n  }\n  return `approved at risk tier 2: '${toolName}' on ${environment} is reversible - verify within the incident window`;\n};\n\nexport default approve;\n"
     },
     {
       "path": "channels/alerts.ts",
-      "content": "import { webhookChannel } from 'lousho';\n\n/**\n * Alert intake (PagerDuty-style): POSTs land on /channels/alerts; the JSON\n * body's `input` string - or the whole body - becomes the alert the agent\n * works on, and a `sessionKey` keeps one incident in one session.\n *\n * With INCIDENT_WEBHOOK_SECRET set, requests must carry a GitHub-style\n * 'x-signature-256: sha256=<hmac of the raw body>' header. Without it the\n * channel accepts unauthenticated requests - local development only; always\n * set the secret in a deployment.\n */\nexport default webhookChannel({\n  name: 'alerts',\n  ...(process.env.INCIDENT_WEBHOOK_SECRET ? { secret: process.env.INCIDENT_WEBHOOK_SECRET } : {}),\n});\n"
+      "content": "import { webhookChannel } from '@linuxdevil/lousho';\n\n/**\n * Alert intake (PagerDuty-style): POSTs land on /channels/alerts; the JSON\n * body's `input` string - or the whole body - becomes the alert the agent\n * works on, and a `sessionKey` keeps one incident in one session.\n *\n * With INCIDENT_WEBHOOK_SECRET set, requests must carry a GitHub-style\n * 'x-signature-256: sha256=<hmac of the raw body>' header. Without it the\n * channel accepts unauthenticated requests - local development only; always\n * set the secret in a deployment.\n */\nexport default webhookChannel({\n  name: 'alerts',\n  ...(process.env.INCIDENT_WEBHOOK_SECRET ? { secret: process.env.INCIDENT_WEBHOOK_SECRET } : {}),\n});\n"
     },
     {
       "path": "hooks.ts",
-      "content": "import { appendFileSync, mkdirSync } from 'node:fs';\nimport path from 'node:path';\nimport type { AgentHook } from 'lousho';\n\n/**\n * The kit's hooks (pointed at by `agent.json`'s `hooks`): the incident audit\n * trail. Every tool call and its outcome is appended to `timeline` (in-memory,\n * readable by anything that shares this module) and - when\n * `INCIDENT_TIMELINE_FILE` is set - to that file as JSON lines, so a deploy\n * keeps a durable record of what the agent did during an incident.\n */\n\nexport interface TimelineEntry {\n  at: string;\n  /** 'call' = invoked; 'approval' = paused for a human; 'result' / 'error' = settled. An approved call re-enters the pipeline, so it records 'call' twice. */\n  phase: 'call' | 'approval' | 'result' | 'error';\n  toolName: string;\n  toolCallId: string;\n  sessionId?: string;\n  args?: Record<string, unknown>;\n  detail?: string;\n}\n\n/** Every tool call the agent has made, in order - the in-memory incident timeline. */\nexport const timeline: TimelineEntry[] = [];\n\n/** Clear the in-memory timeline (tests). */\nexport function resetTimeline(): void {\n  timeline.length = 0;\n}\n\nfunction summarize(result: unknown, error?: string): string | undefined {\n  if (error !== undefined) return `error: ${error}`;\n  const text = typeof result === 'string' ? result : JSON.stringify(result ?? null);\n  return text.length > 300 ? `${text.slice(0, 300)}…` : text;\n}\n\nfunction record(entry: TimelineEntry): void {\n  timeline.push(entry);\n  const file = process.env.INCIDENT_TIMELINE_FILE;\n  if (file === undefined || file === '') return;\n  mkdirSync(path.dirname(file), { recursive: true });\n  appendFileSync(file, `${JSON.stringify(entry)}\\n`, 'utf8');\n}\n\n/** Append each tool call and its outcome to the incident timeline. */\nexport function incidentTimeline(): AgentHook {\n  return {\n    name: 'incident-timeline',\n    preToolCall(ctx) {\n      record({ at: new Date().toISOString(), phase: 'call', toolName: ctx.toolName, toolCallId: ctx.toolCallId, ...(ctx.sessionId && { sessionId: ctx.sessionId }), args: { ...ctx.args } });\n    },\n    postToolCall(ctx, result) {\n      record({\n        at: new Date().toISOString(),\n        phase: result.requiresApproval ? 'approval' : result.error ? 'error' : 'result',\n        toolName: ctx.toolName,\n        toolCallId: ctx.toolCallId,\n        ...(ctx.sessionId && { sessionId: ctx.sessionId }),\n        detail: result.requiresApproval ? 'paused for approval' : summarize(result.result, result.error),\n      });\n    },\n  };\n}\n\nexport default [incidentTimeline()];\n"
+      "content": "import { appendFileSync, mkdirSync } from 'node:fs';\nimport path from 'node:path';\nimport type { AgentHook } from '@linuxdevil/lousho';\n\n/**\n * The kit's hooks (pointed at by `agent.json`'s `hooks`): the incident audit\n * trail. Every tool call and its outcome is appended to `timeline` (in-memory,\n * readable by anything that shares this module) and - when\n * `INCIDENT_TIMELINE_FILE` is set - to that file as JSON lines, so a deploy\n * keeps a durable record of what the agent did during an incident.\n */\n\nexport interface TimelineEntry {\n  at: string;\n  /** 'call' = invoked; 'approval' = paused for a human; 'result' / 'error' = settled. An approved call re-enters the pipeline, so it records 'call' twice. */\n  phase: 'call' | 'approval' | 'result' | 'error';\n  toolName: string;\n  toolCallId: string;\n  sessionId?: string;\n  args?: Record<string, unknown>;\n  detail?: string;\n}\n\n/** Every tool call the agent has made, in order - the in-memory incident timeline. */\nexport const timeline: TimelineEntry[] = [];\n\n/** Clear the in-memory timeline (tests). */\nexport function resetTimeline(): void {\n  timeline.length = 0;\n}\n\nfunction summarize(result: unknown, error?: string): string | undefined {\n  if (error !== undefined) return `error: ${error}`;\n  const text = typeof result === 'string' ? result : JSON.stringify(result ?? null);\n  return text.length > 300 ? `${text.slice(0, 300)}…` : text;\n}\n\nfunction record(entry: TimelineEntry): void {\n  timeline.push(entry);\n  const file = process.env.INCIDENT_TIMELINE_FILE;\n  if (file === undefined || file === '') return;\n  mkdirSync(path.dirname(file), { recursive: true });\n  appendFileSync(file, `${JSON.stringify(entry)}\\n`, 'utf8');\n}\n\n/** Append each tool call and its outcome to the incident timeline. */\nexport function incidentTimeline(): AgentHook {\n  return {\n    name: 'incident-timeline',\n    preToolCall(ctx) {\n      record({ at: new Date().toISOString(), phase: 'call', toolName: ctx.toolName, toolCallId: ctx.toolCallId, ...(ctx.sessionId && { sessionId: ctx.sessionId }), args: { ...ctx.args } });\n    },\n    postToolCall(ctx, result) {\n      record({\n        at: new Date().toISOString(),\n        phase: result.requiresApproval ? 'approval' : result.error ? 'error' : 'result',\n        toolName: ctx.toolName,\n        toolCallId: ctx.toolCallId,\n        ...(ctx.sessionId && { sessionId: ctx.sessionId }),\n        detail: result.requiresApproval ? 'paused for approval' : summarize(result.result, result.error),\n      });\n    },\n  };\n}\n\nexport default [incidentTimeline()];\n"
     },
     {
       "path": "instructions.md",
@@ -25,7 +25,7 @@
     },
     {
       "path": "kit.test.ts",
-      "content": "/**\n * The incident-response kit, exercised offline: the directory is loaded in\n * place with `loadAgentDir()` / `resolveAgentDir()` (the kit's files import\n * `lousho` by name, resolved to this repo's dist through the\n * workspace self-link - like kit.test.ts in examples/coding-harness, this\n * needs `npm run build` to have run).\n *\n * The scripted mockModel plays the responder: an alert arrives (the same\n * JSON the `alerts` webhook channel would deliver), the agent diagnoses with\n * read-only tools, and its remediation goes through the risk-tiered gate -\n * staging auto-allowed, production asks (the kit's approver annotates the\n * tier), destructive calls denied - while the audit hook writes the\n * timeline.\n */\nimport { beforeEach, describe, expect, it } from 'vitest';\nimport * as crypto from 'node:crypto';\nimport * as fs from 'node:fs';\nimport * as os from 'node:os';\nimport * as path from 'node:path';\nimport { createAgent, loadAgentDir, resolveAgentDir } from 'lousho';\nimport { mockModel, type MockModel } from 'lousho/testing';\n// static imports share the module instances the loader's dynamic import gets\nimport { infra, resetInfra } from './tools/infra.js';\nimport { resetTimeline, timeline } from './hooks.js';\nimport approve from './approve.js';\n\nconst DIR = __dirname; // the kit directory itself\n\nconst ALERT = JSON.stringify({\n  alert: {\n    id: 'PD-4821',\n    service: 'payments-api',\n    environment: 'production',\n    severity: 'critical',\n    summary: 'error_rate 14% (baseline 0.4%)',\n  },\n});\n\nlet timelineFile: string;\nlet tmpRoot: string;\n\nbeforeEach(() => {\n  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'incident-response-'));\n  timelineFile = path.join(tmpRoot, 'timeline.jsonl');\n  process.env.INCIDENT_TIMELINE_FILE = timelineFile;\n  // set before any resolveAgentDir call so the channel file binds the HMAC secret at load\n  process.env.INCIDENT_WEBHOOK_SECRET = 'test-secret';\n  resetInfra();\n  resetTimeline();\n});\n\n/** The tool-result messages of the provider's most recent request, joined - what the model saw. */\nconst toolOutputs = (provider: MockModel): string =>\n  provider.calls[provider.calls.length - 1].messages\n    .filter((m) => m.role === 'tool')\n    .map((m) => String(m.content))\n    .join('\\n');\n\nconst auditLog = (): { audit: string[]; onPermissionDecision: (entry: { toolName: string; decision: string; rule?: { reason?: string } }) => void } => {\n  const audit: string[] = [];\n  return {\n    audit,\n    onPermissionDecision: (entry) => audit.push(`${entry.toolName}: ${entry.decision}${entry.rule?.reason ? ` (${entry.rule.reason})` : ''}`),\n  };\n};\n\ndescribe('the kit, loaded in place', () => {\n  it('discovers every tool, the skill and the alerts channel', async () => {\n    const { manifest, channels } = await resolveAgentDir(DIR, { provider: mockModel(['x']) });\n    expect(manifest.tools).toEqual([\n      'check_logs',\n      'query_metrics',\n      'get_runbook',\n      'check_status',\n      'restart_service',\n      'scale_replicas',\n      'post_update',\n      'drop_table',\n      'delete_data',\n    ]);\n    expect(manifest.skills).toEqual(['incident-runbook']);\n    expect(manifest.channels).toEqual(['alerts']);\n    expect(channels[0].name).toBe('alerts');\n  });\n});\n\ndescribe('the alerts webhook channel', () => {\n  /** A request whose signature is computed with `key` (omit for unsigned). */\n  const signedRequest = (body: string, key?: string) => {\n    const rawBody = new TextEncoder().encode(body);\n    const headers: Record<string, string> =\n      key === undefined ? {} : { 'x-signature-256': `sha256=${crypto.createHmac('sha256', key).update(rawBody).digest('hex')}` };\n    return { method: 'POST', url: '/channels/alerts', headers, rawBody, text: body };\n  };\n\n  it('requires the HMAC signature and turns an alert POST into agent input keyed on sessionKey', async () => {\n    const { channels } = await resolveAgentDir(DIR, { provider: mockModel(['x']) });\n    const channel = channels[0];\n    const ok = async (req: ReturnType<typeof signedRequest>) => {\n      const verdict = await channel.verify?.(req);\n      return typeof verdict === 'object' ? verdict.ok : verdict !== false;\n    };\n    const body = JSON.stringify({ input: 'Alert: payments-api error_rate 14%', sessionKey: 'inc-4821' });\n\n    expect(await ok(signedRequest(body))).toBe(false); // unsigned\n    expect(await ok(signedRequest(body, 'bad'))).toBe(false); // wrong key\n    expect(await ok(signedRequest(body, 'test-secret'))).toBe(true);\n\n    const inbound = await channel.parse(signedRequest(body, 'test-secret'), () => {}, undefined as never);\n    expect(inbound && 'input' in inbound && inbound.input).toBe('Alert: payments-api error_rate 14%');\n    expect(inbound && 'sessionKey' in inbound && inbound.sessionKey).toBe('inc-4821');\n  });\n});\n\ndescribe('an incident end to end', () => {\n  it('diagnoses, gets the production restart approved at tier 2, verifies and audits every call', async () => {\n    const provider = mockModel([\n      { toolCalls: [{ name: 'check_logs', args: { service: 'payments-api', severity: 'error' } }] },\n      { toolCalls: [{ name: 'query_metrics', args: { service: 'payments-api', metric: 'error_rate' } }] },\n      { toolCalls: [{ name: 'get_runbook', args: { topic: 'high-error-rate' } }] },\n      { toolCalls: [{ name: 'restart_service', args: { service: 'payments-api', environment: 'production', reason: 'pool exhausted' } }] },\n      { toolCalls: [{ name: 'check_status', args: { service: 'payments-api' } }] },\n      { toolCalls: [{ name: 'post_update', args: { message: 'payments-api restarted; error_rate recovering', severity: 'info' } }] },\n      { text: 'Mitigated: restarted payments-api in production (approved at tier 2); error_rate back to baseline.' },\n    ]);\n    const { audit, onPermissionDecision } = auditLog();\n    const agent = await loadAgentDir(DIR, { provider, onPermissionDecision });\n\n    const result = await agent.send(ALERT);\n\n    expect(result.finishReason).toBe('stop');\n    expect(result.text).toContain('Mitigated');\n    // diagnosis ran, the gate asked on the production restart, then it executed\n    expect(audit).toContain('check_logs: allow');\n    expect(audit).toContain('query_metrics: allow');\n    expect(audit).toContain('restart_service: ask');\n    expect(infra.services['payments-api'].status).toBe('healthy');\n    expect(infra.services['payments-api'].restarts).toBe(2);\n    // the update was posted and every call is on the timeline (memory + JSONL file)\n    expect(infra.updates.map((u) => u.message)).toContain('payments-api restarted; error_rate recovering');\n    // the approved call re-enters the pipeline after the pause, so its 'call' is recorded twice\n    const calls = timeline.filter((e) => e.phase === 'call').map((e) => e.toolName);\n    expect(calls).toEqual(['check_logs', 'query_metrics', 'get_runbook', 'restart_service', 'restart_service', 'check_status', 'post_update']);\n    const restartResult = timeline.find((e) => e.toolName === 'restart_service' && e.phase === 'result');\n    expect(restartResult?.detail).toContain('\"after\":\"healthy\"');\n    const lines = fs.readFileSync(timelineFile, 'utf8').trim().split('\\n').map((l) => JSON.parse(l) as { toolName: string; phase: string });\n    expect(lines.filter((l) => l.toolName === 'restart_service').map((l) => l.phase)).toEqual(['call', 'approval', 'call', 'result']);\n    // the model saw the canned diagnosis data\n    expect(toolOutputs(provider)).toContain('pool exhausted');\n  });\n\n  it('pauses for a human when no approver answers, and resumes on approval', async () => {\n    const provider = mockModel([\n      { toolCalls: [{ name: 'restart_service', args: { service: 'payments-api', environment: 'production' } }] },\n      { toolCalls: [{ name: 'check_status', args: { service: 'payments-api' } }] },\n      { text: 'Restarted after human approval; verified healthy.' },\n    ]);\n    const { config } = await resolveAgentDir(DIR, { provider });\n    const agent = createAgent({ ...config, approve: undefined });\n\n    const paused = await agent.send(ALERT);\n    expect(paused.finishReason).toBe('awaiting-approval');\n    const [pending] = await agent.approvals.list();\n    expect(pending.toolName).toBe('restart_service');\n    expect(infra.services['payments-api'].status).toBe('degraded'); // not executed while paused\n\n    const result = await agent.approvals.resolve({ id: paused.approvalId!, approved: true });\n    expect(result.finishReason).toBe('stop');\n    expect(infra.services['payments-api'].status).toBe('healthy');\n  });\n\n  it('refuses tier-3 asks: scaling to zero is rejected by the kit approver', async () => {\n    const provider = mockModel([\n      { toolCalls: [{ name: 'scale_replicas', args: { service: 'payments-api', environment: 'production', replicas: 0 } }] },\n      { text: 'Approval refused - escalating to the on-call human.' },\n    ]);\n    const { audit, onPermissionDecision } = auditLog();\n    const agent = await loadAgentDir(DIR, { provider, onPermissionDecision });\n\n    const result = await agent.send(ALERT);\n\n    expect(result.finishReason).toBe('stop');\n    expect(audit).toContain('scale_replicas: ask');\n    expect(infra.services['payments-api'].desiredReplicas).toBe(3);\n    expect(toolOutputs(provider)).toMatch(/reject|denied|refused/i);\n  });\n\n  it('auto-allows staging remediation without asking', async () => {\n    const provider = mockModel([\n      { toolCalls: [{ name: 'restart_service', args: { service: 'checkout-web', environment: 'staging' } }] },\n      { text: 'Staging restarted.' },\n    ]);\n    const { audit, onPermissionDecision } = auditLog();\n    const agent = await loadAgentDir(DIR, { provider, onPermissionDecision });\n\n    await agent.send('Alert: checkout-web staging deploy check');\n\n    expect(audit).toContain('restart_service: allow');\n    expect(audit).not.toContain('restart_service: ask');\n    expect(infra.services['checkout-web'].restarts).toBe(1);\n  });\n});\n\ndescribe('the safety rails', () => {\n  it('denies drop_table before the tool can run, leaving the data intact', async () => {\n    const provider = mockModel([\n      { toolCalls: [{ name: 'drop_table', args: { table: 'payments' } }] },\n      { text: 'The drop was denied by policy; escalating to the on-call human.' },\n    ]);\n    const { audit, onPermissionDecision } = auditLog();\n    const agent = await loadAgentDir(DIR, { provider, onPermissionDecision });\n\n    await agent.send(ALERT);\n\n    expect(audit).toContain(\"drop_table: deny (Destructive data operations are never within an incident responder's mandate)\");\n    expect(infra.databases.payments.rows).toBe(184_203);\n    expect(toolOutputs(provider)).toContain('denied');\n    expect(timeline.find((e) => e.toolName === 'drop_table')?.phase).toBe('call'); // the attempt is audited\n  });\n\n  it('denies delete_data too', async () => {\n    const provider = mockModel([\n      { toolCalls: [{ name: 'delete_data', args: { table: 'sessions' } }] },\n      { text: 'Denied.' },\n    ]);\n    const { audit, onPermissionDecision } = auditLog();\n    const agent = await loadAgentDir(DIR, { provider, onPermissionDecision });\n\n    await agent.send(ALERT);\n\n    expect(audit).toContain(\"delete_data: deny (Destructive data operations are never within an incident responder's mandate)\");\n    expect(infra.databases.sessions.rows).toBe(51_977);\n  });\n\n  it('catches a model that labels a production service as staging to dodge the ask tier', async () => {\n    const provider = mockModel([\n      // the \"allow staging\" rule matches the claimed argument, but the tool\n      // cross-checks the estate and refuses the mismatched call\n      { toolCalls: [{ name: 'restart_service', args: { service: 'payments-api', environment: 'staging' } }] },\n      { text: 'Environment mismatch caught - re-issuing as production with approval.' },\n    ]);\n    const { audit, onPermissionDecision } = auditLog();\n    const agent = await loadAgentDir(DIR, { provider, onPermissionDecision });\n\n    await agent.send(ALERT);\n\n    expect(audit).toContain('restart_service: allow'); // the rule trusted the claimed arg\n    expect(toolOutputs(provider)).toContain('environment mismatch'); // the tool did not\n    expect(infra.services['payments-api'].status).toBe('degraded');\n  });\n});\n\ndescribe('the kit approver', () => {\n  const pending = (toolName: string, args: Record<string, unknown>) => ({ id: 'ap-1', toolCallId: 'call_1', toolName, args, createdAt: new Date().toISOString() });\n\n  it('annotates tier-2 approvals and refuses everything hotter', () => {\n    expect(approve(pending('restart_service', { environment: 'production' }))).toContain('risk tier 2');\n    expect(approve(pending('scale_replicas', { environment: 'production', replicas: 4 }))).toContain('risk tier 2');\n    expect(approve(pending('scale_replicas', { environment: 'production', replicas: 0 }))).toBe(false);\n    expect(approve(pending('unknown_tool', {}))).toBe(false);\n  });\n});\n"
+      "content": "/**\n * The incident-response kit, exercised offline: the directory is loaded in\n * place with `loadAgentDir()` / `resolveAgentDir()` (the kit's files import\n * `lousho` by name, resolved to this repo's dist through the\n * workspace self-link - like kit.test.ts in examples/coding-harness, this\n * needs `npm run build` to have run).\n *\n * The scripted mockModel plays the responder: an alert arrives (the same\n * JSON the `alerts` webhook channel would deliver), the agent diagnoses with\n * read-only tools, and its remediation goes through the risk-tiered gate -\n * staging auto-allowed, production asks (the kit's approver annotates the\n * tier), destructive calls denied - while the audit hook writes the\n * timeline.\n */\nimport { beforeEach, describe, expect, it } from 'vitest';\nimport * as crypto from 'node:crypto';\nimport * as fs from 'node:fs';\nimport * as os from 'node:os';\nimport * as path from 'node:path';\nimport { createAgent, loadAgentDir, resolveAgentDir } from '@linuxdevil/lousho';\nimport { mockModel, type MockModel } from '@linuxdevil/lousho/testing';\n// static imports share the module instances the loader's dynamic import gets\nimport { infra, resetInfra } from './tools/infra.js';\nimport { resetTimeline, timeline } from './hooks.js';\nimport approve from './approve.js';\n\nconst DIR = __dirname; // the kit directory itself\n\nconst ALERT = JSON.stringify({\n  alert: {\n    id: 'PD-4821',\n    service: 'payments-api',\n    environment: 'production',\n    severity: 'critical',\n    summary: 'error_rate 14% (baseline 0.4%)',\n  },\n});\n\nlet timelineFile: string;\nlet tmpRoot: string;\n\nbeforeEach(() => {\n  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'incident-response-'));\n  timelineFile = path.join(tmpRoot, 'timeline.jsonl');\n  process.env.INCIDENT_TIMELINE_FILE = timelineFile;\n  // set before any resolveAgentDir call so the channel file binds the HMAC secret at load\n  process.env.INCIDENT_WEBHOOK_SECRET = 'test-secret';\n  resetInfra();\n  resetTimeline();\n});\n\n/** The tool-result messages of the provider's most recent request, joined - what the model saw. */\nconst toolOutputs = (provider: MockModel): string =>\n  provider.calls[provider.calls.length - 1].messages\n    .filter((m) => m.role === 'tool')\n    .map((m) => String(m.content))\n    .join('\\n');\n\nconst auditLog = (): { audit: string[]; onPermissionDecision: (entry: { toolName: string; decision: string; rule?: { reason?: string } }) => void } => {\n  const audit: string[] = [];\n  return {\n    audit,\n    onPermissionDecision: (entry) => audit.push(`${entry.toolName}: ${entry.decision}${entry.rule?.reason ? ` (${entry.rule.reason})` : ''}`),\n  };\n};\n\ndescribe('the kit, loaded in place', () => {\n  it('discovers every tool, the skill and the alerts channel', async () => {\n    const { manifest, channels } = await resolveAgentDir(DIR, { provider: mockModel(['x']) });\n    expect(manifest.tools).toEqual([\n      'check_logs',\n      'query_metrics',\n      'get_runbook',\n      'check_status',\n      'restart_service',\n      'scale_replicas',\n      'post_update',\n      'drop_table',\n      'delete_data',\n    ]);\n    expect(manifest.skills).toEqual(['incident-runbook']);\n    expect(manifest.channels).toEqual(['alerts']);\n    expect(channels[0].name).toBe('alerts');\n  });\n});\n\ndescribe('the alerts webhook channel', () => {\n  /** A request whose signature is computed with `key` (omit for unsigned). */\n  const signedRequest = (body: string, key?: string) => {\n    const rawBody = new TextEncoder().encode(body);\n    const headers: Record<string, string> =\n      key === undefined ? {} : { 'x-signature-256': `sha256=${crypto.createHmac('sha256', key).update(rawBody).digest('hex')}` };\n    return { method: 'POST', url: '/channels/alerts', headers, rawBody, text: body };\n  };\n\n  it('requires the HMAC signature and turns an alert POST into agent input keyed on sessionKey', async () => {\n    const { channels } = await resolveAgentDir(DIR, { provider: mockModel(['x']) });\n    const channel = channels[0];\n    const ok = async (req: ReturnType<typeof signedRequest>) => {\n      const verdict = await channel.verify?.(req);\n      return typeof verdict === 'object' ? verdict.ok : verdict !== false;\n    };\n    const body = JSON.stringify({ input: 'Alert: payments-api error_rate 14%', sessionKey: 'inc-4821' });\n\n    expect(await ok(signedRequest(body))).toBe(false); // unsigned\n    expect(await ok(signedRequest(body, 'bad'))).toBe(false); // wrong key\n    expect(await ok(signedRequest(body, 'test-secret'))).toBe(true);\n\n    const inbound = await channel.parse(signedRequest(body, 'test-secret'), () => {}, undefined as never);\n    expect(inbound && 'input' in inbound && inbound.input).toBe('Alert: payments-api error_rate 14%');\n    expect(inbound && 'sessionKey' in inbound && inbound.sessionKey).toBe('inc-4821');\n  });\n});\n\ndescribe('an incident end to end', () => {\n  it('diagnoses, gets the production restart approved at tier 2, verifies and audits every call', async () => {\n    const provider = mockModel([\n      { toolCalls: [{ name: 'check_logs', args: { service: 'payments-api', severity: 'error' } }] },\n      { toolCalls: [{ name: 'query_metrics', args: { service: 'payments-api', metric: 'error_rate' } }] },\n      { toolCalls: [{ name: 'get_runbook', args: { topic: 'high-error-rate' } }] },\n      { toolCalls: [{ name: 'restart_service', args: { service: 'payments-api', environment: 'production', reason: 'pool exhausted' } }] },\n      { toolCalls: [{ name: 'check_status', args: { service: 'payments-api' } }] },\n      { toolCalls: [{ name: 'post_update', args: { message: 'payments-api restarted; error_rate recovering', severity: 'info' } }] },\n      { text: 'Mitigated: restarted payments-api in production (approved at tier 2); error_rate back to baseline.' },\n    ]);\n    const { audit, onPermissionDecision } = auditLog();\n    const agent = await loadAgentDir(DIR, { provider, onPermissionDecision });\n\n    const result = await agent.send(ALERT);\n\n    expect(result.finishReason).toBe('stop');\n    expect(result.text).toContain('Mitigated');\n    // diagnosis ran, the gate asked on the production restart, then it executed\n    expect(audit).toContain('check_logs: allow');\n    expect(audit).toContain('query_metrics: allow');\n    expect(audit).toContain('restart_service: ask');\n    expect(infra.services['payments-api'].status).toBe('healthy');\n    expect(infra.services['payments-api'].restarts).toBe(2);\n    // the update was posted and every call is on the timeline (memory + JSONL file)\n    expect(infra.updates.map((u) => u.message)).toContain('payments-api restarted; error_rate recovering');\n    // the approved call re-enters the pipeline after the pause, so its 'call' is recorded twice\n    const calls = timeline.filter((e) => e.phase === 'call').map((e) => e.toolName);\n    expect(calls).toEqual(['check_logs', 'query_metrics', 'get_runbook', 'restart_service', 'restart_service', 'check_status', 'post_update']);\n    const restartResult = timeline.find((e) => e.toolName === 'restart_service' && e.phase === 'result');\n    expect(restartResult?.detail).toContain('\"after\":\"healthy\"');\n    const lines = fs.readFileSync(timelineFile, 'utf8').trim().split('\\n').map((l) => JSON.parse(l) as { toolName: string; phase: string });\n    expect(lines.filter((l) => l.toolName === 'restart_service').map((l) => l.phase)).toEqual(['call', 'approval', 'call', 'result']);\n    // the model saw the canned diagnosis data\n    expect(toolOutputs(provider)).toContain('pool exhausted');\n  });\n\n  it('pauses for a human when no approver answers, and resumes on approval', async () => {\n    const provider = mockModel([\n      { toolCalls: [{ name: 'restart_service', args: { service: 'payments-api', environment: 'production' } }] },\n      { toolCalls: [{ name: 'check_status', args: { service: 'payments-api' } }] },\n      { text: 'Restarted after human approval; verified healthy.' },\n    ]);\n    const { config } = await resolveAgentDir(DIR, { provider });\n    const agent = createAgent({ ...config, approve: undefined });\n\n    const paused = await agent.send(ALERT);\n    expect(paused.finishReason).toBe('awaiting-approval');\n    const [pending] = await agent.approvals.list();\n    expect(pending.toolName).toBe('restart_service');\n    expect(infra.services['payments-api'].status).toBe('degraded'); // not executed while paused\n\n    const result = await agent.approvals.resolve({ id: paused.approvalId!, approved: true });\n    expect(result.finishReason).toBe('stop');\n    expect(infra.services['payments-api'].status).toBe('healthy');\n  });\n\n  it('refuses tier-3 asks: scaling to zero is rejected by the kit approver', async () => {\n    const provider = mockModel([\n      { toolCalls: [{ name: 'scale_replicas', args: { service: 'payments-api', environment: 'production', replicas: 0 } }] },\n      { text: 'Approval refused - escalating to the on-call human.' },\n    ]);\n    const { audit, onPermissionDecision } = auditLog();\n    const agent = await loadAgentDir(DIR, { provider, onPermissionDecision });\n\n    const result = await agent.send(ALERT);\n\n    expect(result.finishReason).toBe('stop');\n    expect(audit).toContain('scale_replicas: ask');\n    expect(infra.services['payments-api'].desiredReplicas).toBe(3);\n    expect(toolOutputs(provider)).toMatch(/reject|denied|refused/i);\n  });\n\n  it('auto-allows staging remediation without asking', async () => {\n    const provider = mockModel([\n      { toolCalls: [{ name: 'restart_service', args: { service: 'checkout-web', environment: 'staging' } }] },\n      { text: 'Staging restarted.' },\n    ]);\n    const { audit, onPermissionDecision } = auditLog();\n    const agent = await loadAgentDir(DIR, { provider, onPermissionDecision });\n\n    await agent.send('Alert: checkout-web staging deploy check');\n\n    expect(audit).toContain('restart_service: allow');\n    expect(audit).not.toContain('restart_service: ask');\n    expect(infra.services['checkout-web'].restarts).toBe(1);\n  });\n});\n\ndescribe('the safety rails', () => {\n  it('denies drop_table before the tool can run, leaving the data intact', async () => {\n    const provider = mockModel([\n      { toolCalls: [{ name: 'drop_table', args: { table: 'payments' } }] },\n      { text: 'The drop was denied by policy; escalating to the on-call human.' },\n    ]);\n    const { audit, onPermissionDecision } = auditLog();\n    const agent = await loadAgentDir(DIR, { provider, onPermissionDecision });\n\n    await agent.send(ALERT);\n\n    expect(audit).toContain(\"drop_table: deny (Destructive data operations are never within an incident responder's mandate)\");\n    expect(infra.databases.payments.rows).toBe(184_203);\n    expect(toolOutputs(provider)).toContain('denied');\n    expect(timeline.find((e) => e.toolName === 'drop_table')?.phase).toBe('call'); // the attempt is audited\n  });\n\n  it('denies delete_data too', async () => {\n    const provider = mockModel([\n      { toolCalls: [{ name: 'delete_data', args: { table: 'sessions' } }] },\n      { text: 'Denied.' },\n    ]);\n    const { audit, onPermissionDecision } = auditLog();\n    const agent = await loadAgentDir(DIR, { provider, onPermissionDecision });\n\n    await agent.send(ALERT);\n\n    expect(audit).toContain(\"delete_data: deny (Destructive data operations are never within an incident responder's mandate)\");\n    expect(infra.databases.sessions.rows).toBe(51_977);\n  });\n\n  it('catches a model that labels a production service as staging to dodge the ask tier', async () => {\n    const provider = mockModel([\n      // the \"allow staging\" rule matches the claimed argument, but the tool\n      // cross-checks the estate and refuses the mismatched call\n      { toolCalls: [{ name: 'restart_service', args: { service: 'payments-api', environment: 'staging' } }] },\n      { text: 'Environment mismatch caught - re-issuing as production with approval.' },\n    ]);\n    const { audit, onPermissionDecision } = auditLog();\n    const agent = await loadAgentDir(DIR, { provider, onPermissionDecision });\n\n    await agent.send(ALERT);\n\n    expect(audit).toContain('restart_service: allow'); // the rule trusted the claimed arg\n    expect(toolOutputs(provider)).toContain('environment mismatch'); // the tool did not\n    expect(infra.services['payments-api'].status).toBe('degraded');\n  });\n});\n\ndescribe('the kit approver', () => {\n  const pending = (toolName: string, args: Record<string, unknown>) => ({ id: 'ap-1', toolCallId: 'call_1', toolName, args, createdAt: new Date().toISOString() });\n\n  it('annotates tier-2 approvals and refuses everything hotter', () => {\n    expect(approve(pending('restart_service', { environment: 'production' }))).toContain('risk tier 2');\n    expect(approve(pending('scale_replicas', { environment: 'production', replicas: 4 }))).toContain('risk tier 2');\n    expect(approve(pending('scale_replicas', { environment: 'production', replicas: 0 }))).toBe(false);\n    expect(approve(pending('unknown_tool', {}))).toBe(false);\n  });\n});\n"
     },
     {
       "path": "skills/incident-runbook/SKILL.md",
@@ -33,7 +33,7 @@
     },
     {
       "path": "tools/infra.ts",
-      "content": "/**\n * The kit's simulated infrastructure: a canned production/staging estate plus\n * the tools the responder calls against it. Everything runs offline - `infra`\n * is an in-memory fixture the tools read and mutate, so a restart or a scale\n * is visible to later calls (a test reloads this module and calls\n * `resetInfra()`).\n *\n * The remediation tools take an `environment` argument AND cross-check it\n * against the service's real environment: a permission rule that allows\n * \"staging\" trusts the argument the model wrote, so the tool refuses a call\n * that labels a production service as staging.\n */\nimport { z } from 'zod';\nimport { defineTool } from 'lousho';\n\nexport type Environment = 'staging' | 'production';\nexport type ServiceStatus = 'healthy' | 'degraded' | 'down' | 'restarting';\n\nexport interface ServiceState {\n  name: string;\n  environment: Environment;\n  status: ServiceStatus;\n  replicas: number;\n  desiredReplicas: number;\n  version: string;\n  restarts: number;\n}\n\nexport interface UpdateEntry {\n  at: string;\n  severity: 'info' | 'warning' | 'critical';\n  message: string;\n}\n\nexport interface InfraState {\n  services: Record<string, ServiceState>;\n  /** table -> rows still present; drop_table / delete_data eat into this. */\n  databases: Record<string, { rows: number }>;\n  /** Status-page updates the agent posted. */\n  updates: UpdateEntry[];\n  logs: Record<string, string[]>;\n  runbooks: Record<string, { title: string; steps: string[] }>;\n}\n\nconst seed = (): InfraState => ({\n  services: {\n    'payments-api': {\n      name: 'payments-api',\n      environment: 'production',\n      status: 'degraded',\n      replicas: 3,\n      desiredReplicas: 3,\n      version: 'v2.14.0',\n      restarts: 1,\n    },\n    'checkout-web': {\n      name: 'checkout-web',\n      environment: 'staging',\n      status: 'healthy',\n      replicas: 2,\n      desiredReplicas: 2,\n      version: 'v1.9.3',\n      restarts: 0,\n    },\n    'orders-db': {\n      name: 'orders-db',\n      environment: 'production',\n      status: 'healthy',\n      replicas: 1,\n      desiredReplicas: 1,\n      version: 'postgres-16.2',\n      restarts: 0,\n    },\n  },\n  databases: {\n    payments: { rows: 184_203 },\n    sessions: { rows: 51_977 },\n  },\n  updates: [],\n  logs: {\n    'payments-api': [\n      '2024-05-11T14:02:11Z ERROR pool: connection timeout after 5000ms (pool exhausted, 32/32 in use)',\n      '2024-05-11T14:02:14Z ERROR handler POST /charges failed: upstream timeout (payments-db)',\n      '2024-05-11T14:02:31Z WARN  heap: 87% of limit, GC pause 1.2s',\n      '2024-05-11T14:03:02Z ERROR pool: connection timeout after 5000ms (pool exhausted, 32/32 in use)',\n      '2024-05-11T14:03:19Z ERROR handler POST /charges failed: upstream timeout (payments-db)',\n    ],\n    'checkout-web': [\n      '2024-05-11T13:58:40Z INFO  GET /cart 200 in 41ms',\n      '2024-05-11T14:01:55Z INFO  GET /checkout 200 in 63ms',\n    ],\n    'orders-db': [\n      '2024-05-11T14:00:00Z INFO  checkpoint completed, wrote 812 buffers',\n      '2024-05-11T14:05:00Z INFO  automatic vacuum of \"orders\": index scans 0',\n    ],\n  },\n  runbooks: {\n    'high-error-rate': {\n      title: 'Elevated error rate on a service',\n      steps: [\n        'Correlate check_logs and query_metrics(error_rate, latency_p99) to find the failing dependency.',\n        'If logs show an exhausted resource (pool, heap), a rolling restart clears the leak - this is tier 2 in production.',\n        'If errors track a traffic spike, scale replicas instead - check the spike is real, not a retry storm.',\n        'Verify error_rate returns to baseline with query_metrics before calling the incident mitigated.',\n      ],\n    },\n    restart: {\n      title: 'Rolling restart of a service',\n      steps: [\n        'restart_service performs a rolling restart; replicas stay up one short during the roll.',\n        'Staging restarts are pre-approved. Production restarts need approval - state the blast radius in the request.',\n        'After the restart, check_status must report healthy and query_metrics(error_rate) must fall before you post \"mitigated\".',\n      ],\n    },\n    scale: {\n      title: 'Scaling a service',\n      steps: [\n        'scale_replicas changes desiredReplicas; the platform converges within ~60s.',\n        'Never scale to 0 during an incident - that is an outage, not a remediation. The approver refuses it.',\n        'Verify with check_status that replicas converged.',\n      ],\n    },\n  },\n});\n\n/** The live fixture the tools operate on. */\nexport const infra: InfraState = seed();\n\n/** Back to the seeded state (tests). Mutates in place so importers keep their reference. */\nexport function resetInfra(): InfraState {\n  const fresh = seed();\n  infra.services = fresh.services;\n  infra.databases = fresh.databases;\n  infra.updates = fresh.updates;\n  infra.logs = fresh.logs;\n  infra.runbooks = fresh.runbooks;\n  return infra;\n}\n\nconst serviceArg = z.string().describe('The service name, e.g. \"payments-api\"');\nconst environmentArg = z.enum(['staging', 'production']).describe('The environment the caller believes the service runs in - verified against the estate.');\n\n/** The service entry, or a model-facing error string. */\nfunction service(name: string): ServiceState | { error: string } {\n  const entry = infra.services[name];\n  return entry ?? { error: `unknown service '${name}'. Known services: ${Object.keys(infra.services).join(', ')}` };\n}\n\n/**\n * Guards the environment claim: a permission rule that allows \"staging\" sees\n * only the argument, so the tool itself refuses when the claim disagrees with\n * the estate.\n */\nfunction envGuard(entry: ServiceState, claimed: Environment): { error: string } | undefined {\n  if (entry.environment !== claimed) {\n    return {\n      error: `environment mismatch: '${entry.name}' runs in ${entry.environment}, not ${claimed}. Re-issue the call with the real environment so it passes through the right approval tier.`,\n    };\n  }\n  return undefined;\n}\n\nexport const check_logs = defineTool({\n  name: 'check_logs',\n  description: 'Read the most recent log lines of a service (read-only)',\n  input: z.object({\n    service: serviceArg,\n    severity: z.enum(['info', 'warn', 'error']).optional().describe('Only lines at or above this severity'),\n    limit: z.number().int().min(1).max(50).optional().describe('Maximum lines to return (default 20)'),\n  }),\n  annotations: { readOnlyHint: true },\n  execute({ service: name, severity, limit = 20 }) {\n    const entry = service(name);\n    if ('error' in entry) return entry;\n    const floor = severity === 'error' ? 'ERROR' : severity === 'warn' ? 'WARN' : '';\n    const lines = (infra.logs[name] ?? []).filter((line) => floor === '' || line.includes(floor)).slice(-limit);\n    return { service: name, environment: entry.environment, lines };\n  },\n});\n\n/** A plausible metric series: baseline wiggle, with a spike while the service is degraded. */\nfunction series(entry: ServiceState, metric: string): { t: string; v: number }[] {\n  const baseline: Record<string, number> = { error_rate: 0.4, latency_p99: 120, cpu: 34, memory: 58, restarts: entry.restarts };\n  const spiked: Record<string, number> = { error_rate: 14.2, latency_p99: 5100, cpu: 61, memory: 87, restarts: entry.restarts };\n  const hot = entry.status === 'degraded' || entry.status === 'down';\n  const now = Date.UTC(2024, 4, 11, 14, 0, 0);\n  return [0, 1, 2, 3, 4].map((i) => {\n    const base = baseline[metric] ?? 0;\n    const value = hot && i >= 3 ? (spiked[metric] ?? base) : base + i * 0.05;\n    return { t: new Date(now - (4 - i) * 60_000).toISOString(), v: Math.round(value * 100) / 100 };\n  });\n}\n\nexport const query_metrics = defineTool({\n  name: 'query_metrics',\n  description: 'Query a service metric over the last window (read-only): error_rate, latency_p99, cpu, memory or restarts',\n  input: z.object({\n    service: serviceArg,\n    metric: z.enum(['error_rate', 'latency_p99', 'cpu', 'memory', 'restarts']),\n    windowMinutes: z.number().int().min(1).max(120).optional().describe('Lookback window (default 5m)'),\n  }),\n  annotations: { readOnlyHint: true },\n  execute({ service: name, metric, windowMinutes = 5 }) {\n    const entry = service(name);\n    if ('error' in entry) return entry;\n    const points = series(entry, metric);\n    const latest = points.at(-1)!.v;\n    return {\n      service: name,\n      metric,\n      windowMinutes,\n      points,\n      summary: { current: latest, baseline: points[0].v, elevated: latest > points[0].v * 1.5 },\n    };\n  },\n});\n\nexport const get_runbook = defineTool({\n  name: 'get_runbook',\n  description: 'Fetch the runbook procedure for a topic (read-only): \"high-error-rate\", \"restart\", \"scale\"',\n  input: z.object({ topic: z.string().describe('Runbook topic, e.g. \"high-error-rate\"') }),\n  annotations: { readOnlyHint: true },\n  execute({ topic }) {\n    const runbook = infra.runbooks[topic];\n    if (!runbook) return { error: `no runbook for '${topic}'. Available: ${Object.keys(infra.runbooks).join(', ')}` };\n    return { topic, ...runbook };\n  },\n});\n\nexport const check_status = defineTool({\n  name: 'check_status',\n  description: 'Current status of a service: health, replica count vs desired, version, restart count (read-only)',\n  input: z.object({ service: serviceArg }),\n  annotations: { readOnlyHint: true },\n  execute({ service: name }) {\n    const entry = service(name);\n    if ('error' in entry) return entry;\n    return { ...entry, converged: entry.replicas === entry.desiredReplicas };\n  },\n});\n\nexport const restart_service = defineTool({\n  name: 'restart_service',\n  description: 'Perform a rolling restart of a service. Staging restarts are pre-approved; production restarts need human approval.',\n  input: z.object({\n    service: serviceArg,\n    environment: environmentArg,\n    reason: z.string().optional().describe('Why the restart is needed - recorded on the incident timeline'),\n  }),\n  execute({ service: name, environment, reason }) {\n    const entry = service(name);\n    if ('error' in entry) return entry;\n    const mismatch = envGuard(entry, environment);\n    if (mismatch) return mismatch;\n    const before = entry.status;\n    entry.status = 'healthy';\n    entry.restarts += 1;\n    return {\n      service: name,\n      environment: entry.environment,\n      before,\n      after: entry.status,\n      restarts: entry.restarts,\n      ...(reason !== undefined && { reason }),\n    };\n  },\n});\n\nexport const scale_replicas = defineTool({\n  name: 'scale_replicas',\n  description: 'Set the desired replica count of a service (1-20). Scaling to 0 during an incident is refused by policy.',\n  input: z.object({\n    service: serviceArg,\n    environment: environmentArg,\n    replicas: z.number().int().min(0).max(20).describe('Desired replica count'),\n  }),\n  execute({ service: name, environment, replicas }) {\n    const entry = service(name);\n    if ('error' in entry) return entry;\n    const mismatch = envGuard(entry, environment);\n    if (mismatch) return mismatch;\n    const before = entry.desiredReplicas;\n    entry.desiredReplicas = replicas;\n    entry.replicas = replicas;\n    return { service: name, environment: entry.environment, before, replicas: entry.replicas };\n  },\n});\n\nexport const post_update = defineTool({\n  name: 'post_update',\n  description: 'Post a status-page update for the incident (visible to stakeholders)',\n  input: z.object({\n    message: z.string().describe('The update text, e.g. \"payments-api restarted; error rate recovering\"'),\n    severity: z.enum(['info', 'warning', 'critical']).optional(),\n  }),\n  execute({ message, severity = 'info' }) {\n    const update: UpdateEntry = { at: new Date().toISOString(), severity, message };\n    infra.updates.push(update);\n    return { posted: true, update };\n  },\n});\n\n/**\n * The destructive capabilities the estate exposes - present so the permission\n * rules have something real to fence. Both are denied by agent.json; if that\n * gate ever regressed these would actually destroy fixture state.\n */\nexport const drop_table = defineTool({\n  name: 'drop_table',\n  description: 'Drop a database table and all its rows. DESTRUCTIVE - never within the incident mandate.',\n  input: z.object({ table: z.string().describe('Table name, e.g. \"payments\"') }),\n  execute({ table }) {\n    const target = infra.databases[table];\n    if (!target) return { error: `unknown table '${table}'. Known tables: ${Object.keys(infra.databases).join(', ')}` };\n    const rows = target.rows;\n    delete infra.databases[table];\n    return { dropped: table, rowsLost: rows };\n  },\n});\n\nexport const delete_data = defineTool({\n  name: 'delete_data',\n  description: 'Delete rows from a database table. DESTRUCTIVE - never within the incident mandate.',\n  input: z.object({\n    table: z.string(),\n    where: z.string().optional().describe('Row predicate; without it every row goes'),\n  }),\n  execute({ table, where }) {\n    const target = infra.databases[table];\n    if (!target) return { error: `unknown table '${table}'. Known tables: ${Object.keys(infra.databases).join(', ')}` };\n    const deleted = where === undefined ? target.rows : Math.floor(target.rows / 10);\n    target.rows -= deleted;\n    return { table, rowsDeleted: deleted, rowsRemaining: target.rows };\n  },\n});\n\nexport default [\n  check_logs,\n  query_metrics,\n  get_runbook,\n  check_status,\n  restart_service,\n  scale_replicas,\n  post_update,\n  drop_table,\n  delete_data,\n];\n"
+      "content": "/**\n * The kit's simulated infrastructure: a canned production/staging estate plus\n * the tools the responder calls against it. Everything runs offline - `infra`\n * is an in-memory fixture the tools read and mutate, so a restart or a scale\n * is visible to later calls (a test reloads this module and calls\n * `resetInfra()`).\n *\n * The remediation tools take an `environment` argument AND cross-check it\n * against the service's real environment: a permission rule that allows\n * \"staging\" trusts the argument the model wrote, so the tool refuses a call\n * that labels a production service as staging.\n */\nimport { z } from 'zod';\nimport { defineTool } from '@linuxdevil/lousho';\n\nexport type Environment = 'staging' | 'production';\nexport type ServiceStatus = 'healthy' | 'degraded' | 'down' | 'restarting';\n\nexport interface ServiceState {\n  name: string;\n  environment: Environment;\n  status: ServiceStatus;\n  replicas: number;\n  desiredReplicas: number;\n  version: string;\n  restarts: number;\n}\n\nexport interface UpdateEntry {\n  at: string;\n  severity: 'info' | 'warning' | 'critical';\n  message: string;\n}\n\nexport interface InfraState {\n  services: Record<string, ServiceState>;\n  /** table -> rows still present; drop_table / delete_data eat into this. */\n  databases: Record<string, { rows: number }>;\n  /** Status-page updates the agent posted. */\n  updates: UpdateEntry[];\n  logs: Record<string, string[]>;\n  runbooks: Record<string, { title: string; steps: string[] }>;\n}\n\nconst seed = (): InfraState => ({\n  services: {\n    'payments-api': {\n      name: 'payments-api',\n      environment: 'production',\n      status: 'degraded',\n      replicas: 3,\n      desiredReplicas: 3,\n      version: 'v2.14.0',\n      restarts: 1,\n    },\n    'checkout-web': {\n      name: 'checkout-web',\n      environment: 'staging',\n      status: 'healthy',\n      replicas: 2,\n      desiredReplicas: 2,\n      version: 'v1.9.3',\n      restarts: 0,\n    },\n    'orders-db': {\n      name: 'orders-db',\n      environment: 'production',\n      status: 'healthy',\n      replicas: 1,\n      desiredReplicas: 1,\n      version: 'postgres-16.2',\n      restarts: 0,\n    },\n  },\n  databases: {\n    payments: { rows: 184_203 },\n    sessions: { rows: 51_977 },\n  },\n  updates: [],\n  logs: {\n    'payments-api': [\n      '2024-05-11T14:02:11Z ERROR pool: connection timeout after 5000ms (pool exhausted, 32/32 in use)',\n      '2024-05-11T14:02:14Z ERROR handler POST /charges failed: upstream timeout (payments-db)',\n      '2024-05-11T14:02:31Z WARN  heap: 87% of limit, GC pause 1.2s',\n      '2024-05-11T14:03:02Z ERROR pool: connection timeout after 5000ms (pool exhausted, 32/32 in use)',\n      '2024-05-11T14:03:19Z ERROR handler POST /charges failed: upstream timeout (payments-db)',\n    ],\n    'checkout-web': [\n      '2024-05-11T13:58:40Z INFO  GET /cart 200 in 41ms',\n      '2024-05-11T14:01:55Z INFO  GET /checkout 200 in 63ms',\n    ],\n    'orders-db': [\n      '2024-05-11T14:00:00Z INFO  checkpoint completed, wrote 812 buffers',\n      '2024-05-11T14:05:00Z INFO  automatic vacuum of \"orders\": index scans 0',\n    ],\n  },\n  runbooks: {\n    'high-error-rate': {\n      title: 'Elevated error rate on a service',\n      steps: [\n        'Correlate check_logs and query_metrics(error_rate, latency_p99) to find the failing dependency.',\n        'If logs show an exhausted resource (pool, heap), a rolling restart clears the leak - this is tier 2 in production.',\n        'If errors track a traffic spike, scale replicas instead - check the spike is real, not a retry storm.',\n        'Verify error_rate returns to baseline with query_metrics before calling the incident mitigated.',\n      ],\n    },\n    restart: {\n      title: 'Rolling restart of a service',\n      steps: [\n        'restart_service performs a rolling restart; replicas stay up one short during the roll.',\n        'Staging restarts are pre-approved. Production restarts need approval - state the blast radius in the request.',\n        'After the restart, check_status must report healthy and query_metrics(error_rate) must fall before you post \"mitigated\".',\n      ],\n    },\n    scale: {\n      title: 'Scaling a service',\n      steps: [\n        'scale_replicas changes desiredReplicas; the platform converges within ~60s.',\n        'Never scale to 0 during an incident - that is an outage, not a remediation. The approver refuses it.',\n        'Verify with check_status that replicas converged.',\n      ],\n    },\n  },\n});\n\n/** The live fixture the tools operate on. */\nexport const infra: InfraState = seed();\n\n/** Back to the seeded state (tests). Mutates in place so importers keep their reference. */\nexport function resetInfra(): InfraState {\n  const fresh = seed();\n  infra.services = fresh.services;\n  infra.databases = fresh.databases;\n  infra.updates = fresh.updates;\n  infra.logs = fresh.logs;\n  infra.runbooks = fresh.runbooks;\n  return infra;\n}\n\nconst serviceArg = z.string().describe('The service name, e.g. \"payments-api\"');\nconst environmentArg = z.enum(['staging', 'production']).describe('The environment the caller believes the service runs in - verified against the estate.');\n\n/** The service entry, or a model-facing error string. */\nfunction service(name: string): ServiceState | { error: string } {\n  const entry = infra.services[name];\n  return entry ?? { error: `unknown service '${name}'. Known services: ${Object.keys(infra.services).join(', ')}` };\n}\n\n/**\n * Guards the environment claim: a permission rule that allows \"staging\" sees\n * only the argument, so the tool itself refuses when the claim disagrees with\n * the estate.\n */\nfunction envGuard(entry: ServiceState, claimed: Environment): { error: string } | undefined {\n  if (entry.environment !== claimed) {\n    return {\n      error: `environment mismatch: '${entry.name}' runs in ${entry.environment}, not ${claimed}. Re-issue the call with the real environment so it passes through the right approval tier.`,\n    };\n  }\n  return undefined;\n}\n\nexport const check_logs = defineTool({\n  name: 'check_logs',\n  description: 'Read the most recent log lines of a service (read-only)',\n  input: z.object({\n    service: serviceArg,\n    severity: z.enum(['info', 'warn', 'error']).optional().describe('Only lines at or above this severity'),\n    limit: z.number().int().min(1).max(50).optional().describe('Maximum lines to return (default 20)'),\n  }),\n  annotations: { readOnlyHint: true },\n  execute({ service: name, severity, limit = 20 }) {\n    const entry = service(name);\n    if ('error' in entry) return entry;\n    const floor = severity === 'error' ? 'ERROR' : severity === 'warn' ? 'WARN' : '';\n    const lines = (infra.logs[name] ?? []).filter((line) => floor === '' || line.includes(floor)).slice(-limit);\n    return { service: name, environment: entry.environment, lines };\n  },\n});\n\n/** A plausible metric series: baseline wiggle, with a spike while the service is degraded. */\nfunction series(entry: ServiceState, metric: string): { t: string; v: number }[] {\n  const baseline: Record<string, number> = { error_rate: 0.4, latency_p99: 120, cpu: 34, memory: 58, restarts: entry.restarts };\n  const spiked: Record<string, number> = { error_rate: 14.2, latency_p99: 5100, cpu: 61, memory: 87, restarts: entry.restarts };\n  const hot = entry.status === 'degraded' || entry.status === 'down';\n  const now = Date.UTC(2024, 4, 11, 14, 0, 0);\n  return [0, 1, 2, 3, 4].map((i) => {\n    const base = baseline[metric] ?? 0;\n    const value = hot && i >= 3 ? (spiked[metric] ?? base) : base + i * 0.05;\n    return { t: new Date(now - (4 - i) * 60_000).toISOString(), v: Math.round(value * 100) / 100 };\n  });\n}\n\nexport const query_metrics = defineTool({\n  name: 'query_metrics',\n  description: 'Query a service metric over the last window (read-only): error_rate, latency_p99, cpu, memory or restarts',\n  input: z.object({\n    service: serviceArg,\n    metric: z.enum(['error_rate', 'latency_p99', 'cpu', 'memory', 'restarts']),\n    windowMinutes: z.number().int().min(1).max(120).optional().describe('Lookback window (default 5m)'),\n  }),\n  annotations: { readOnlyHint: true },\n  execute({ service: name, metric, windowMinutes = 5 }) {\n    const entry = service(name);\n    if ('error' in entry) return entry;\n    const points = series(entry, metric);\n    const latest = points.at(-1)!.v;\n    return {\n      service: name,\n      metric,\n      windowMinutes,\n      points,\n      summary: { current: latest, baseline: points[0].v, elevated: latest > points[0].v * 1.5 },\n    };\n  },\n});\n\nexport const get_runbook = defineTool({\n  name: 'get_runbook',\n  description: 'Fetch the runbook procedure for a topic (read-only): \"high-error-rate\", \"restart\", \"scale\"',\n  input: z.object({ topic: z.string().describe('Runbook topic, e.g. \"high-error-rate\"') }),\n  annotations: { readOnlyHint: true },\n  execute({ topic }) {\n    const runbook = infra.runbooks[topic];\n    if (!runbook) return { error: `no runbook for '${topic}'. Available: ${Object.keys(infra.runbooks).join(', ')}` };\n    return { topic, ...runbook };\n  },\n});\n\nexport const check_status = defineTool({\n  name: 'check_status',\n  description: 'Current status of a service: health, replica count vs desired, version, restart count (read-only)',\n  input: z.object({ service: serviceArg }),\n  annotations: { readOnlyHint: true },\n  execute({ service: name }) {\n    const entry = service(name);\n    if ('error' in entry) return entry;\n    return { ...entry, converged: entry.replicas === entry.desiredReplicas };\n  },\n});\n\nexport const restart_service = defineTool({\n  name: 'restart_service',\n  description: 'Perform a rolling restart of a service. Staging restarts are pre-approved; production restarts need human approval.',\n  input: z.object({\n    service: serviceArg,\n    environment: environmentArg,\n    reason: z.string().optional().describe('Why the restart is needed - recorded on the incident timeline'),\n  }),\n  execute({ service: name, environment, reason }) {\n    const entry = service(name);\n    if ('error' in entry) return entry;\n    const mismatch = envGuard(entry, environment);\n    if (mismatch) return mismatch;\n    const before = entry.status;\n    entry.status = 'healthy';\n    entry.restarts += 1;\n    return {\n      service: name,\n      environment: entry.environment,\n      before,\n      after: entry.status,\n      restarts: entry.restarts,\n      ...(reason !== undefined && { reason }),\n    };\n  },\n});\n\nexport const scale_replicas = defineTool({\n  name: 'scale_replicas',\n  description: 'Set the desired replica count of a service (1-20). Scaling to 0 during an incident is refused by policy.',\n  input: z.object({\n    service: serviceArg,\n    environment: environmentArg,\n    replicas: z.number().int().min(0).max(20).describe('Desired replica count'),\n  }),\n  execute({ service: name, environment, replicas }) {\n    const entry = service(name);\n    if ('error' in entry) return entry;\n    const mismatch = envGuard(entry, environment);\n    if (mismatch) return mismatch;\n    const before = entry.desiredReplicas;\n    entry.desiredReplicas = replicas;\n    entry.replicas = replicas;\n    return { service: name, environment: entry.environment, before, replicas: entry.replicas };\n  },\n});\n\nexport const post_update = defineTool({\n  name: 'post_update',\n  description: 'Post a status-page update for the incident (visible to stakeholders)',\n  input: z.object({\n    message: z.string().describe('The update text, e.g. \"payments-api restarted; error rate recovering\"'),\n    severity: z.enum(['info', 'warning', 'critical']).optional(),\n  }),\n  execute({ message, severity = 'info' }) {\n    const update: UpdateEntry = { at: new Date().toISOString(), severity, message };\n    infra.updates.push(update);\n    return { posted: true, update };\n  },\n});\n\n/**\n * The destructive capabilities the estate exposes - present so the permission\n * rules have something real to fence. Both are denied by agent.json; if that\n * gate ever regressed these would actually destroy fixture state.\n */\nexport const drop_table = defineTool({\n  name: 'drop_table',\n  description: 'Drop a database table and all its rows. DESTRUCTIVE - never within the incident mandate.',\n  input: z.object({ table: z.string().describe('Table name, e.g. \"payments\"') }),\n  execute({ table }) {\n    const target = infra.databases[table];\n    if (!target) return { error: `unknown table '${table}'. Known tables: ${Object.keys(infra.databases).join(', ')}` };\n    const rows = target.rows;\n    delete infra.databases[table];\n    return { dropped: table, rowsLost: rows };\n  },\n});\n\nexport const delete_data = defineTool({\n  name: 'delete_data',\n  description: 'Delete rows from a database table. DESTRUCTIVE - never within the incident mandate.',\n  input: z.object({\n    table: z.string(),\n    where: z.string().optional().describe('Row predicate; without it every row goes'),\n  }),\n  execute({ table, where }) {\n    const target = infra.databases[table];\n    if (!target) return { error: `unknown table '${table}'. Known tables: ${Object.keys(infra.databases).join(', ')}` };\n    const deleted = where === undefined ? target.rows : Math.floor(target.rows / 10);\n    target.rows -= deleted;\n    return { table, rowsDeleted: deleted, rowsRemaining: target.rows };\n  },\n});\n\nexport default [\n  check_logs,\n  query_metrics,\n  get_runbook,\n  check_status,\n  restart_service,\n  scale_replicas,\n  post_update,\n  drop_table,\n  delete_data,\n];\n"
     }
   ],
   "permissions": {
@@ -45,6 +45,6 @@
     "needsApproval": true
   },
   "dependencies": [
-    "lousho"
+    "@linuxdevil/lousho"
   ]
 }
diff --git a/registry/dist/items/open-meteo-weather.json b/registry/dist/items/open-meteo-weather.json
index e6b655b85..c7bfde102 100644
--- a/registry/dist/items/open-meteo-weather.json
+++ b/registry/dist/items/open-meteo-weather.json
@@ -5,7 +5,7 @@
   "files": [
     {
       "path": "tools/open-meteo-weather.ts",
-      "content": "import { z } from 'zod';\nimport { defineTool } from 'lousho';\n\ninterface GeocodingResponse {\n  results?: { latitude: number; longitude: number; name: string; country?: string }[];\n}\n\ninterface ForecastResponse {\n  current_weather?: { temperature: number; windspeed: number; winddirection: number; weathercode: number; time: string };\n}\n\nasync function readJson(url: string): Promise<unknown> {\n  const response = await fetch(url);\n  if (!response.ok) throw new Error(`request failed: HTTP ${response.status}`);\n  return response.json();\n}\n\nexport default defineTool({\n  name: 'open-meteo-weather',\n  description: 'Get the current weather for a city through the Open-Meteo API (free, no API key)',\n  input: z.object({ city: z.string().describe('The city to look up, e.g. \"Berlin\"') }),\n  async execute({ city }) {\n    const geo = (await readJson(`https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(city)}&count=1`)) as GeocodingResponse;\n    const place = geo.results?.[0];\n    if (!place) return { error: `No place named '${city}' found.` };\n    const forecast = (await readJson(\n      `https://api.open-meteo.com/v1/forecast?latitude=${place.latitude}&longitude=${place.longitude}&current_weather=true`\n    )) as ForecastResponse;\n    return { place: `${place.name}${place.country ? `, ${place.country}` : ''}`, weather: forecast.current_weather ?? null };\n  },\n});\n"
+      "content": "import { z } from 'zod';\nimport { defineTool } from '@linuxdevil/lousho';\n\ninterface GeocodingResponse {\n  results?: { latitude: number; longitude: number; name: string; country?: string }[];\n}\n\ninterface ForecastResponse {\n  current_weather?: { temperature: number; windspeed: number; winddirection: number; weathercode: number; time: string };\n}\n\nasync function readJson(url: string): Promise<unknown> {\n  const response = await fetch(url);\n  if (!response.ok) throw new Error(`request failed: HTTP ${response.status}`);\n  return response.json();\n}\n\nexport default defineTool({\n  name: 'open-meteo-weather',\n  description: 'Get the current weather for a city through the Open-Meteo API (free, no API key)',\n  input: z.object({ city: z.string().describe('The city to look up, e.g. \"Berlin\"') }),\n  async execute({ city }) {\n    const geo = (await readJson(`https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(city)}&count=1`)) as GeocodingResponse;\n    const place = geo.results?.[0];\n    if (!place) return { error: `No place named '${city}' found.` };\n    const forecast = (await readJson(\n      `https://api.open-meteo.com/v1/forecast?latitude=${place.latitude}&longitude=${place.longitude}&current_weather=true`\n    )) as ForecastResponse;\n    return { place: `${place.name}${place.country ? `, ${place.country}` : ''}`, weather: forecast.current_weather ?? null };\n  },\n});\n"
     }
   ],
   "permissions": {
@@ -15,7 +15,7 @@
     ]
   },
   "dependencies": [
-    "lousho",
+    "@linuxdevil/lousho",
     "zod"
   ]
 }
diff --git a/registry/generic-webhook/channels/generic-webhook.ts b/registry/generic-webhook/channels/generic-webhook.ts
index b813f86d7..34de8db95 100644
--- a/registry/generic-webhook/channels/generic-webhook.ts
+++ b/registry/generic-webhook/channels/generic-webhook.ts
@@ -1,4 +1,4 @@
-import { webhookChannel } from 'lousho';
+import { webhookChannel } from '@linuxdevil/lousho';
 
 // Verifies `x-signature-256: sha256=<hmac of the raw body>` against WEBHOOK_SECRET
 // (the format GitHub webhooks use). The channel refuses to load when the secret
diff --git a/registry/generic-webhook/item.json b/registry/generic-webhook/item.json
index eec2f2b1b..7dc113fcc 100644
--- a/registry/generic-webhook/item.json
+++ b/registry/generic-webhook/item.json
@@ -5,5 +5,5 @@
   "permissions": {
     "env": ["WEBHOOK_SECRET"]
   },
-  "dependencies": ["lousho"]
+  "dependencies": ["@linuxdevil/lousho"]
 }
diff --git a/registry/github-issues/item.json b/registry/github-issues/item.json
index c415c361d..bcaa24bcd 100644
--- a/registry/github-issues/item.json
+++ b/registry/github-issues/item.json
@@ -7,5 +7,5 @@
     "env": ["GITHUB_TOKEN"],
     "needsApproval": true
   },
-  "dependencies": ["lousho", "zod"]
+  "dependencies": ["@linuxdevil/lousho", "zod"]
 }
diff --git a/registry/github-issues/tools/github-issues.ts b/registry/github-issues/tools/github-issues.ts
index 505d0836a..f8f50bcd6 100644
--- a/registry/github-issues/tools/github-issues.ts
+++ b/registry/github-issues/tools/github-issues.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 
 function token(): string {
   const value = process.env.GITHUB_TOKEN;
diff --git a/registry/inbox-triage/approve.ts b/registry/inbox-triage/approve.ts
index cab99ef12..0296024b1 100644
--- a/registry/inbox-triage/approve.ts
+++ b/registry/inbox-triage/approve.ts
@@ -1,4 +1,4 @@
-import type { ApproveToolCall } from 'lousho';
+import type { ApproveToolCall } from '@linuxdevil/lousho';
 import { autoApproveSenders, findDraft, getMessage } from './lib/mailstore.ts';
 
 /**
diff --git a/registry/inbox-triage/channels/inbound.ts b/registry/inbox-triage/channels/inbound.ts
index e41738f96..f36c86f0d 100644
--- a/registry/inbox-triage/channels/inbound.ts
+++ b/registry/inbox-triage/channels/inbound.ts
@@ -11,7 +11,7 @@
  * A paused turn replies 200 with the pending `approval`; decide it at
  * `POST /channels/inbound/approvals/<id>` like every channel.
  */
-import { defineChannel } from 'lousho';
+import { defineChannel } from '@linuxdevil/lousho';
 import { addMessage } from '../lib/mailstore.ts';
 
 export default defineChannel({
diff --git a/registry/inbox-triage/hooks.ts b/registry/inbox-triage/hooks.ts
index 0f436710a..3a85fc368 100644
--- a/registry/inbox-triage/hooks.ts
+++ b/registry/inbox-triage/hooks.ts
@@ -1,4 +1,4 @@
-import type { AgentHook } from 'lousho';
+import type { AgentHook } from '@linuxdevil/lousho';
 import { findDraft } from './lib/mailstore.ts';
 
 /**
diff --git a/registry/inbox-triage/item.json b/registry/inbox-triage/item.json
index 81f04184b..9b9ff5f24 100644
--- a/registry/inbox-triage/item.json
+++ b/registry/inbox-triage/item.json
@@ -6,5 +6,5 @@
     "filesystem": "write",
     "env": ["INBOX_TRIAGE_HOME", "INBOUND_TOKEN", "INBOX_TRIAGE_AUTO_APPROVE", "OPENROUTER_API_KEY"]
   },
-  "dependencies": ["lousho", "zod"]
+  "dependencies": ["@linuxdevil/lousho", "zod"]
 }
diff --git a/registry/inbox-triage/kit.test.ts b/registry/inbox-triage/kit.test.ts
index 3120a79d0..e03e344ba 100644
--- a/registry/inbox-triage/kit.test.ts
+++ b/registry/inbox-triage/kit.test.ts
@@ -5,7 +5,7 @@
  * lands in the outbox). The store is a temp dir via INBOX_TRIAGE_HOME so the
  * kit's seeded data/ stays untouched.
  *
- * The kit's files import `lousho` by name, which resolves to
+ * The kit's files import `@linuxdevil/lousho` by name, which resolves to
  * the workspace self-link (dist/) inside this repo - like
  * examples/coding-harness/kit.test.ts this needs `npm run build` to have run.
  */
@@ -13,9 +13,9 @@ import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { loadAgentDir, resolveAgentDir, startSchedules } from 'lousho';
-import type { ChannelContext, ChannelInbound, ChannelRequest } from 'lousho';
-import { mockModel, type MockModel } from 'lousho/testing';
+import { loadAgentDir, resolveAgentDir, startSchedules } from '@linuxdevil/lousho';
+import type { ChannelContext, ChannelInbound, ChannelRequest } from '@linuxdevil/lousho';
+import { mockModel, type MockModel } from '@linuxdevil/lousho/testing';
 
 const KIT = __dirname;
 const home = fs.mkdtempSync(path.join(os.tmpdir(), 'inbox-triage-'));
diff --git a/registry/inbox-triage/memory/senders.ts b/registry/inbox-triage/memory/senders.ts
index b0a55b6b5..c498e5ae0 100644
--- a/registry/inbox-triage/memory/senders.ts
+++ b/registry/inbox-triage/memory/senders.ts
@@ -12,7 +12,7 @@
  * INBOX_TRIAGE_HOME the mail store uses, under `memory/`.
  */
 import path from 'node:path';
-import { defineMemory, fileMemory, type MemoryProvider } from 'lousho';
+import { defineMemory, fileMemory, type MemoryProvider } from '@linuxdevil/lousho';
 import { home } from '../lib/mailstore.ts';
 
 const backing = (): MemoryProvider => fileMemory({ dir: path.join(home(), 'memory') });
diff --git a/registry/inbox-triage/schedules/poll-inbox.ts b/registry/inbox-triage/schedules/poll-inbox.ts
index afd2be537..84294c250 100644
--- a/registry/inbox-triage/schedules/poll-inbox.ts
+++ b/registry/inbox-triage/schedules/poll-inbox.ts
@@ -1,4 +1,4 @@
-import { defineSchedule } from 'lousho';
+import { defineSchedule } from '@linuxdevil/lousho';
 
 /**
  * The kit's batch intake: every 15 minutes the agent sweeps the inbox for
diff --git a/registry/inbox-triage/tools/inbox.ts b/registry/inbox-triage/tools/inbox.ts
index 0a12c503c..da72f4c6e 100644
--- a/registry/inbox-triage/tools/inbox.ts
+++ b/registry/inbox-triage/tools/inbox.ts
@@ -5,7 +5,7 @@
  * refuses it ("triage never deletes"), which is the kit's guardrail story.
  */
 import { z } from 'zod';
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 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 6ef0dc31b..9d77fa609 100644
--- a/registry/inbox-triage/tools/replies.ts
+++ b/registry/inbox-triage/tools/replies.ts
@@ -5,7 +5,7 @@
  * pauses and a human decides before anything lands in the outbox.
  */
 import { z } from 'zod';
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { appendOutbox, findDraft, getMessage, listDrafts, addDraft, updateDraft, updateMessage } from '../lib/mailstore.ts';
 
 const list = defineTool({
diff --git a/registry/incident-response/approve.ts b/registry/incident-response/approve.ts
index a5c571d02..8408c98a3 100644
--- a/registry/incident-response/approve.ts
+++ b/registry/incident-response/approve.ts
@@ -1,4 +1,4 @@
-import type { ApproveToolCall } from 'lousho';
+import type { ApproveToolCall } from '@linuxdevil/lousho';
 
 /**
  * The kit's approver (pointed at by `agent.json`'s `approve`): what reaches
diff --git a/registry/incident-response/channels/alerts.ts b/registry/incident-response/channels/alerts.ts
index 5cd931910..9b42e83a2 100644
--- a/registry/incident-response/channels/alerts.ts
+++ b/registry/incident-response/channels/alerts.ts
@@ -1,4 +1,4 @@
-import { webhookChannel } from 'lousho';
+import { webhookChannel } from '@linuxdevil/lousho';
 
 /**
  * Alert intake (PagerDuty-style): POSTs land on /channels/alerts; the JSON
diff --git a/registry/incident-response/hooks.ts b/registry/incident-response/hooks.ts
index 9c8d3990b..0f6e059af 100644
--- a/registry/incident-response/hooks.ts
+++ b/registry/incident-response/hooks.ts
@@ -1,6 +1,6 @@
 import { appendFileSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
-import type { AgentHook } from 'lousho';
+import type { AgentHook } from '@linuxdevil/lousho';
 
 /**
  * The kit's hooks (pointed at by `agent.json`'s `hooks`): the incident audit
diff --git a/registry/incident-response/item.json b/registry/incident-response/item.json
index d203e5170..c6cc2db4b 100644
--- a/registry/incident-response/item.json
+++ b/registry/incident-response/item.json
@@ -7,5 +7,5 @@
     "env": ["INCIDENT_WEBHOOK_SECRET", "INCIDENT_TIMELINE_FILE"],
     "needsApproval": true
   },
-  "dependencies": ["lousho"]
+  "dependencies": ["@linuxdevil/lousho"]
 }
diff --git a/registry/incident-response/kit.test.ts b/registry/incident-response/kit.test.ts
index e25bbd1d7..9482939f9 100644
--- a/registry/incident-response/kit.test.ts
+++ b/registry/incident-response/kit.test.ts
@@ -17,8 +17,8 @@ import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { createAgent, loadAgentDir, resolveAgentDir } from 'lousho';
-import { mockModel, type MockModel } from 'lousho/testing';
+import { createAgent, loadAgentDir, resolveAgentDir } from '@linuxdevil/lousho';
+import { mockModel, type MockModel } from '@linuxdevil/lousho/testing';
 // static imports share the module instances the loader's dynamic import gets
 import { infra, resetInfra } from './tools/infra.js';
 import { resetTimeline, timeline } from './hooks.js';
diff --git a/registry/incident-response/tools/infra.ts b/registry/incident-response/tools/infra.ts
index dce056b43..43798e613 100644
--- a/registry/incident-response/tools/infra.ts
+++ b/registry/incident-response/tools/infra.ts
@@ -11,7 +11,7 @@
  * that labels a production service as staging.
  */
 import { z } from 'zod';
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 
 export type Environment = 'staging' | 'production';
 export type ServiceStatus = 'healthy' | 'degraded' | 'down' | 'restarting';
diff --git a/registry/kits.live.test.ts b/registry/kits.live.test.ts
index ae1d1f009..004df3430 100644
--- a/registry/kits.live.test.ts
+++ b/registry/kits.live.test.ts
@@ -5,7 +5,7 @@
  * resolved from OPENROUTER_API_KEY in the shell or a `.env` at the repo
  * root; vitest loads `.env` into `process.env`, `.env` is gitignored).
  *
- *   npm run build        # the kits import 'lousho' -> dist/
+ *   npm run build        # the kits import '@linuxdevil/lousho' -> dist/
  *   npm run test:live
  *
  * NEVER in CI: `*.live.test.ts` is excluded from the default vitest config.
@@ -17,7 +17,7 @@ import { afterAll, 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 { loadAgentDir } from 'lousho';
+import { loadAgentDir } from '@linuxdevil/lousho';
 import { infra, resetInfra } from './incident-response/tools/infra.js';
 import { resetTimeline, timeline } from './incident-response/hooks.js';
 
diff --git a/registry/open-meteo-weather/item.json b/registry/open-meteo-weather/item.json
index 1bab11182..e88ebb6a7 100644
--- a/registry/open-meteo-weather/item.json
+++ b/registry/open-meteo-weather/item.json
@@ -5,5 +5,5 @@
   "permissions": {
     "network": ["api.open-meteo.com", "geocoding-api.open-meteo.com"]
   },
-  "dependencies": ["lousho", "zod"]
+  "dependencies": ["@linuxdevil/lousho", "zod"]
 }
diff --git a/registry/open-meteo-weather/tools/open-meteo-weather.ts b/registry/open-meteo-weather/tools/open-meteo-weather.ts
index d1b41fb7e..44fc75066 100644
--- a/registry/open-meteo-weather/tools/open-meteo-weather.ts
+++ b/registry/open-meteo-weather/tools/open-meteo-weather.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 
 interface GeocodingResponse {
   results?: { latitude: number; longitude: number; name: string; country?: string }[];
diff --git a/scripts/pack-smoke-studio.ts b/scripts/pack-smoke-studio.ts
new file mode 100644
index 000000000..6931003c4
--- /dev/null
+++ b/scripts/pack-smoke-studio.ts
@@ -0,0 +1,249 @@
+// fallow-ignore-file complexity
+/**
+ * pack-smoke:studio
+ *
+ * Proves that what `npm pack` produces for `@linuxdevil/studio` (and the SDK
+ * it depends on) installs and works in a fresh project that has never seen
+ * this checkout:
+ *
+ *   1. builds the SDK and Studio (skip with --skip-build),
+ *   2. `npm pack`s both into a temp dir and checks the Studio tarball (no
+ *      source, tests, maps or `.package.json.prepack`; `package.json` carries
+ *      the bin and a semver SDK range, never `file:`; entry count and sizes
+ *      under the thresholds below), and that `apps/agent-forge/package.json`
+ *      is byte-identical afterwards (prepack/postpack pin+restore),
+ *   3. `npm publish --dry-run` for the Studio tarball (never a real publish),
+ *   4. installs both tarballs into a temp project (the SDK dependency is
+ *      overridden to the SDK tarball, since its semver range is not on npm),
+ *   5. `lousho-studio --help` through node_modules/.bin,
+ *   6. starts `dist-server/cli.cjs` directly: `GET /health` answers `ok` and
+ *      `GET /` serves the built UI,
+ *   7. starts `lousho studio` through the SDK's bin - the W13b launcher must
+ *      find the installed Studio and serve the same UI.
+ *
+ * Both launches run with LOUSHO_STUDIO_COLLECTOR=0 so no observe daemon is
+ * started. Usage: npm run pack-smoke:studio [-- --skip-build] [--keep]
+ *
+ * Needs network access to the npm registry. It is deliberately NOT part of
+ * `npm test`. It never publishes: `npm publish` is only ever run with
+ * --dry-run.
+ */
+import { spawn, spawnSync, type ChildProcess } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { checkTarballContents, cleanSmokeDir, IS_WIN, SDK_NAME, dryRunPublish, freePort, packTarball, reportSmoke, run, smokeDirs, smokeSetup, type TarballLimits } from './smokeKit';
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const STUDIO_DIR = path.join(REPO_ROOT, 'apps', 'agent-forge');
+const STUDIO_NAME = '@linuxdevil/studio';
+
+/**
+ * Thresholds measured on the consolidated W-chain head (2026-11-14): the
+ * Studio tarball ships 12 entries, 9.3 MB unpacked, 2.6 MB packed (the
+ * merged X/W features grew the client bundle well past the W15a figures).
+ * Budgets carry ~15% headroom, like scripts/pack-smoke.ts.
+ */
+const STUDIO_MAX_ENTRIES = 14;
+const STUDIO_MAX_UNPACKED_BYTES = 10_500_000;
+const STUDIO_MAX_PACKED_BYTES = 3_000_000;
+
+const STUDIO_REQUIRED_PATHS = ['dist/index.html', 'dist-server/index.cjs', 'dist-server/cli.cjs', 'package.json', 'README.md'];
+const STUDIO_FORBIDDEN_PATHS = [
+  /\.map$/,
+  /^(src|server|shared|e2e|scripts)\//,
+  /\.test\.[cm]?[jt]sx?$/,
+  /(^|\/)\.env(\.|$)/,
+  /(^|\/)node_modules\//,
+  /\.package\.json\.prepack$/,
+];
+
+const { args, rep, log, fail, mustRun } = smokeSetup('pack-smoke:studio');
+
+const STUDIO_TARBALL_LIMITS: TarballLimits = {
+  maxEntries: STUDIO_MAX_ENTRIES,
+  maxUnpackedBytes: STUDIO_MAX_UNPACKED_BYTES,
+  maxPackedBytes: STUDIO_MAX_PACKED_BYTES,
+  requiredPaths: STUDIO_REQUIRED_PATHS,
+  forbiddenPatterns: STUDIO_FORBIDDEN_PATHS,
+};
+
+/** Reads the packed package.json and checks name/bin/SDK range (prepack pin ran). */
+function checkStudioPackageJson(unpackedPackageJson: unknown): void {
+  const pkg = unpackedPackageJson as { name?: string; bin?: Record<string, string>; dependencies?: Record<string, string> };
+  if (pkg.name !== STUDIO_NAME) fail(`studio package.json name is ${JSON.stringify(pkg.name)}, expected ${STUDIO_NAME}`);
+  if (pkg.bin?.['lousho-studio'] !== 'dist-server/cli.cjs') fail(`studio bin.lousho-studio is ${JSON.stringify(pkg.bin?.['lousho-studio'])}, expected 'dist-server/cli.cjs'`);
+  const sdkRange = pkg.dependencies?.[SDK_NAME];
+  if (!sdkRange || !/^\^\d/.test(sdkRange)) fail(`studio dependency ${SDK_NAME} is ${JSON.stringify(sdkRange)}, expected a ^<semver> range (prepack pin did not run)`);
+}
+
+/** Step 5: `lousho-studio --help` through node_modules/.bin exits 0 and mentions --workspace. */
+function checkStudioBin(project: string): void {
+  const res = IS_WIN
+    ? run('npx', ['--no-install', 'lousho-studio', '--help'], project)
+    : run(path.join(project, 'node_modules', '.bin', 'lousho-studio'), ['--help'], project);
+  if (res.status !== 0 || !res.stdout.includes('--workspace')) {
+    fail(`lousho-studio --help failed (exit ${res.status}):\n${res.stdout}${res.stderr}`);
+  } else {
+    log('lousho-studio --help: ok');
+  }
+}
+
+interface ServerHandle {
+  child: ChildProcess;
+  port: number;
+  stderr: () => string;
+}
+
+/** Spawns a detached Studio process; the caller kills it via killTree. */
+function startStudioProcess(nodeArgs: string[], project: string, port: number): ServerHandle {
+  const child = spawn(process.execPath, nodeArgs, {
+    cwd: project,
+    env: { ...process.env, LOUSHO_STUDIO_COLLECTOR: '0' },
+    stdio: ['ignore', 'pipe', 'pipe'],
+    detached: true,
+  });
+  let stderr = '';
+  child.stderr?.on('data', (d: Buffer) => {
+    stderr += d.toString();
+    if (stderr.length > 64 * 1024) stderr = stderr.slice(-16 * 1024);
+  });
+  child.stdout?.resume();
+  return { child, port, stderr: () => stderr };
+}
+
+/** Kills the whole process tree: taskkill on Windows, the process group elsewhere. */
+function killTree(child: ChildProcess): void {
+  if (!child.pid) return;
+  if (IS_WIN) {
+    spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+    return;
+  }
+  try {
+    process.kill(-child.pid, 'SIGTERM');
+  } catch {
+    child.kill('SIGTERM');
+  }
+}
+
+/** Resolves once the killed process exits (5s cap) so a leaked Studio cannot hold the port. */
+function waitExit(child: ChildProcess): Promise<void> {
+  if (child.exitCode !== null || child.killed) return Promise.resolve();
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, 5_000);
+    child.once('exit', () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+
+/** Polls GET /health for `ok` then GET / for the built UI, within 20s. */
+async function waitForStudio(handle: ServerHandle, label: string): Promise<void> {
+  const deadline = Date.now() + 20_000;
+  let last = '';
+  while (Date.now() < deadline) {
+    try {
+      const health = await fetch(`http://127.0.0.1:${handle.port}/health`);
+      const text = await health.text();
+      last = `health ${health.status} ${text.slice(0, 80)}`;
+      if (health.status === 200 && text.trim() === 'ok') {
+        const root = await fetch(`http://127.0.0.1:${handle.port}/`);
+        const html = await root.text();
+        if (root.status === 200 && html.includes('<div id="root">')) {
+          rep.log(`${label}: /health ok and / serves the UI`);
+          return;
+        }
+        last = `GET / -> ${root.status}, ${html.length} bytes`;
+      }
+    } catch (e) {
+      last = String(e);
+    }
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  rep.fail(`${label}: Studio did not come up within 20s (last: ${last}; stderr: ${handle.stderr().slice(-500)})`);
+}
+
+/** Steps 6+7: boot Studio directly and through `lousho studio`, each on a free port. */
+async function checkStudioServes(project: string): Promise<void> {
+  const cliPath = path.join(project, 'node_modules', ...STUDIO_NAME.split('/'), 'dist-server', 'cli.cjs');
+  const loushoBin = path.join(project, 'node_modules', ...SDK_NAME.split('/'), 'bin', 'lousho.js');
+
+  const port1 = await freePort();
+  const direct = startStudioProcess([cliPath, '--port', String(port1), '--workspace', project], project, port1);
+  try {
+    await waitForStudio(direct, 'lousho-studio (cli.cjs)');
+  } finally {
+    killTree(direct.child);
+    await waitExit(direct.child);
+  }
+
+  const port2 = await freePort();
+  const viaLauncher = startStudioProcess([loushoBin, 'studio', '--port', String(port2)], project, port2);
+  try {
+    await waitForStudio(viaLauncher, 'lousho studio (launcher)');
+  } finally {
+    killTree(viaLauncher.child);
+    await waitExit(viaLauncher.child);
+  }
+}
+
+/** `file:` spec relative to the project dir - npm requires the override and the direct dep to be the same spec string. */
+function fileSpec(fromDir: string, p: string): string {
+  return `file:${path.relative(fromDir, p).replace(/\\/g, '/')}`;
+}
+
+async function main(): Promise<void> {
+  if (!args.has('--skip-build')) {
+    mustRun('npm run build', 'npm', ['run', 'build'], REPO_ROOT);
+    mustRun('npm run build:studio', 'npm', ['run', 'build:studio'], REPO_ROOT);
+  }
+  const { base, packDir, project } = smokeDirs('lousho-studio-pack-smoke');
+  log(`temp dir ${base}`);
+
+  const studioPkgJsonBefore = fs.readFileSync(path.join(STUDIO_DIR, 'package.json'), 'utf8');
+  try {
+    const sdk = packTarball(rep, '(sdk)', REPO_ROOT, packDir);
+    const studio = packTarball(rep, '(studio)', STUDIO_DIR, packDir);
+
+    // `npm pack` runs prepack/postpack; unpack once to read the shipped package.json.
+    const unpackDir = path.join(base, 'studio-unpack');
+    fs.mkdirSync(unpackDir);
+    const tar = run('tar', ['-xzf', path.relative(unpackDir, studio.tarball)], unpackDir);
+    if (tar.status !== 0) fail(`could not unpack the studio tarball: ${tar.stderr}`);
+    else {
+      const shippedPkg = JSON.parse(fs.readFileSync(path.join(unpackDir, 'package', 'package.json'), 'utf8'));
+      checkStudioPackageJson(shippedPkg);
+      checkTarballContents(rep, studio.entry, STUDIO_TARBALL_LIMITS);
+    }
+
+    // prepack pins file:../.. to a semver range and postpack restores it - even on failure.
+    const pkgJsonAfter = fs.readFileSync(path.join(STUDIO_DIR, 'package.json'), 'utf8');
+    if (pkgJsonAfter !== studioPkgJsonBefore) fail('apps/agent-forge/package.json changed after npm pack (pin/restore did not restore it)');
+    else log('apps/agent-forge/package.json restored after pack');
+
+    dryRunPublish(rep, '(studio)', studio.tarball, base);
+
+    // The override must carry the same spec string npm records for the direct dependency.
+    const sdkSpec = fileSpec(project, sdk.tarball);
+    const studioSpec = fileSpec(project, studio.tarball);
+    fs.writeFileSync(
+      path.join(project, 'package.json'),
+      JSON.stringify({ name: 'studio-smoke', version: '0.0.0', private: true, overrides: { [SDK_NAME]: sdkSpec } }, null, 2)
+    );
+    mustRun('npm install sdk + studio tarballs', 'npm', ['install', '--no-audit', '--no-fund', sdkSpec, studioSpec], project);
+
+    checkStudioBin(project);
+    await checkStudioServes(project);
+  } finally {
+    if (fs.readFileSync(path.join(STUDIO_DIR, 'package.json'), 'utf8') !== studioPkgJsonBefore) {
+      rep.fail('apps/agent-forge/package.json was left modified - restoring is the postpack script\'s job');
+    }
+    cleanSmokeDir(rep, base, args.has('--keep'));
+  }
+  reportSmoke(rep);
+}
+
+main().catch((err: unknown) => {
+  console.error(err);
+  process.exit(1);
+});
diff --git a/scripts/pack-smoke.ts b/scripts/pack-smoke.ts
index eced1aefd..ef51282ce 100644
--- a/scripts/pack-smoke.ts
+++ b/scripts/pack-smoke.ts
@@ -5,13 +5,13 @@
  * Proves that what `npm pack` produces installs and works, in a fresh project
  * that has never seen this checkout:
  *
- *   1. builds the SDK, `create-lousho` and Agent Forge (the
- *      `build:studio` step `prepublishOnly` also runs, so the packed tarball is
- *      the one that is really published; skip with --skip-build),
+ *   1. builds the SDK and `create-lousho` (the `prepublishOnly` build, so the
+ *      packed tarball is the one that is really published; skip with
+ *      --skip-build),
  *   2. `npm pack`s both into a temp dir and checks the SDK tarball (no `.env`,
- *      tests, fixtures or secret-looking strings; the files `lousho build` and
- *      `lousho studio` need are present; entry count and unpacked size under
- *      the thresholds below),
+ *      tests, fixtures or secret-looking strings; the files `lousho build`
+ *      needs are present - Studio left the tarball in W13b; entry count and
+ *      unpacked size under the thresholds below),
  *   3. `npm publish <tarball> --dry-run` for both packages (nothing is
  *      published; a tarball argument also skips the prepublishOnly build),
  *   4. installs the tarballs plus the required peers from the REGISTRY into a
@@ -31,9 +31,8 @@
  */
 import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
-import * as os from 'node:os';
 import * as path from 'node:path';
-import { IS_WIN, SDK_NAME, checkBin, checkModuleLoads, createReporter, listExports, mustRun as mustRunIn, run } from './smokeKit';
+import { checkTarballContents, cleanSmokeDir, IS_WIN, packTarball, reportSmoke, SDK_NAME, checkBin, checkModuleLoads, dryRunPublish, listExports, run, smokeDirs, smokeSetup, type PackEntry, type TarballLimits } from './smokeKit';
 
 const REPO_ROOT = path.resolve(__dirname, '..');
 
@@ -79,10 +78,16 @@ const REPO_ROOT = path.resolve(__dirname, '..');
  * 2026-11-12); unpacked budget raised to 26 MiB (~8% headroom).
  * CI measured 7,401,846 bytes packed on main after R07 chain triggers and
  * R08b channel triggers landed (2026-11-14); packed budget raised to 8 MiB.
+ * Studio left the SDK tarball (2026-11-13, W13b): measured 1016 entries /
+ * 15,289,389 bytes unpacked / 4,393,121 bytes packed; budgets ~10% headroom.
+ * The entry count still sits under the existing 1040 budget (new subpath
+ * entries offset Studio's removal), so MAX_ENTRIES stays put.
+ * Re-measured after the main sync (trigger host + studio removal):
+ * 1246 entries / 17.9 MiB unpacked / 5.1 MiB packed; budgets ~10% headroom.
  */
-const MAX_ENTRIES = 1300;
-const MAX_UNPACKED_BYTES = 26 * 1024 * 1024;
-const MAX_PACKED_BYTES = 8 * 1024 * 1024;
+const MAX_ENTRIES = 1370;
+const MAX_UNPACKED_BYTES = 20 * 1024 * 1024;
+const MAX_PACKED_BYTES = 6 * 1024 * 1024;
 
 const DEFAULT_PEERS = 'ai@7 zod@4 @ai-sdk/openai@4 react@19 vue@3 @opentelemetry/api@1';
 const FORBIDDEN_PATHS = [
@@ -95,7 +100,8 @@ const FORBIDDEN_PATHS = [
   /__snapshots__\//,
   /__cassettes__\//,
   /(^|\/)node_modules\//,
-  /^apps\/agent-forge\/dist-server\/.*\.map$/,
+  // Nothing under apps/ ships: Studio is the separate @linuxdevil/studio package (W13b).
+  /^apps\//,
   /^dist\/.*\.map$/,
   // bin/lousho.js loads only the ESM CLI build (dist/cli/*.mjs); the CJS one is not shipped.
   /^dist\/cli\/[^/]+\.js(\.map)?$/,
@@ -105,9 +111,7 @@ const FORBIDDEN_PATHS = [
 /**
  * Files the published package must contain: `lousho build` bundles
  * `src/deploy/runtime.worker.ts`, `src/deploy/shims/node.worker.ts` and
- * `src/index.ts` from the installed package root (see `src/deploy/bundle.ts`),
- * and `lousho studio` serves `apps/agent-forge/dist` and runs
- * `apps/agent-forge/dist-server/index.cjs`.
+ * `src/index.ts` from the installed package root (see `src/deploy/bundle.ts`).
  */
 const REQUIRED_PATHS = [
   'src/index.ts',
@@ -115,42 +119,21 @@ const REQUIRED_PATHS = [
   'src/deploy/runtime.worker.ts',
   'src/deploy/shims/node.worker.ts',
   'templates/support-triage/spec.yaml',
-  'apps/agent-forge/dist-server/index.cjs',
-  'apps/agent-forge/dist/index.html',
 ];
 const SECRET_PATTERNS = [/sk-[A-Za-z0-9]{32,}/, /AKIA[0-9A-Z]{16}/, /ghp_[A-Za-z0-9]{30,}/, /-----BEGIN [A-Z ]*PRIVATE KEY-----/, /_authToken\s*=/];
 
-const args = new Set(process.argv.slice(2));
-const rep = createReporter('pack-smoke');
-const { log, fail, failures } = rep;
-const mustRun = (label: string, cmd: string, argv: string[], cwd: string, env?: NodeJS.ProcessEnv) => mustRunIn(rep, label, cmd, argv, cwd, env);
+const { args, rep, log, fail, mustRun } = smokeSetup('pack-smoke');
 
-interface PackEntry {
-  filename: string;
-  entryCount: number;
-  size: number;
-  unpackedSize: number;
-  files: { path: string }[];
-}
-
-function pack(label: string, cwd: string, dest: string): { entry: PackEntry; tarball: string } {
-  const res = mustRun(`npm pack ${label}`, 'npm', ['pack', '--json', '--pack-destination', dest], cwd);
-  const entry = (JSON.parse(res.stdout) as PackEntry[])[0];
-  return { entry, tarball: path.join(dest, entry.filename) };
-}
+const TARBALL_LIMITS: TarballLimits = {
+  maxEntries: MAX_ENTRIES,
+  maxUnpackedBytes: MAX_UNPACKED_BYTES,
+  maxPackedBytes: MAX_PACKED_BYTES,
+  requiredPaths: REQUIRED_PATHS,
+  forbiddenPatterns: FORBIDDEN_PATHS,
+};
 
 function checkTarball(entry: PackEntry, tarball: string): void {
-  log(`tarball ${entry.filename}: ${entry.entryCount} entries, ${(entry.unpackedSize / 1048576).toFixed(1)} MB unpacked, ${(entry.size / 1048576).toFixed(1)} MB packed`);
-  if (entry.entryCount > MAX_ENTRIES) fail(`tarball has ${entry.entryCount} entries (max ${MAX_ENTRIES})`);
-  if (entry.unpackedSize > MAX_UNPACKED_BYTES) fail(`tarball unpacked size ${entry.unpackedSize} exceeds ${MAX_UNPACKED_BYTES}`);
-  if (entry.size > MAX_PACKED_BYTES) fail(`tarball packed size ${entry.size} exceeds ${MAX_PACKED_BYTES}`);
-  const packed = new Set(entry.files.map((f) => f.path));
-  for (const p of REQUIRED_PATHS) {
-    if (!packed.has(p)) fail(`tarball is missing required file ${p}`);
-  }
-  for (const f of entry.files) {
-    if (FORBIDDEN_PATHS.some((re) => re.test(f.path))) fail(`tarball contains forbidden file ${f.path}`);
-  }
+  checkTarballContents(rep, entry, TARBALL_LIMITS);
   const extracted = fs.mkdtempSync(path.join(path.dirname(tarball), 'unpack-'));
   // Relative tarball path: GNU tar (Git Bash) reads "C:" in an absolute Windows path as a remote host.
   const tar = run('tar', ['-xzf', path.relative(extracted, tarball)], extracted);
@@ -162,21 +145,6 @@ function checkTarball(entry: PackEntry, tarball: string): void {
   }
 }
 
-function dryRunPublish(label: string, tarball: string, cwd: string): void {
-  // `--tag next`: the versions are prereleases and npm 11 refuses a prerelease without an explicit tag.
-  const res = run('npm', ['publish', tarball, '--dry-run', '--tag', 'next', '--access', 'public'], cwd);
-  const out = res.stdout + res.stderr;
-  // After a release the version in the repo is the one on npm until the next bump. The dry run
-  // then fails only on that; the tarball itself was accepted, which is what this step checks.
-  if (/cannot publish over the previously published versions/i.test(out)) {
-    log(`npm publish --dry-run ${label}: ok (this version is already on npm; bump it before the next release)`);
-  } else if (res.status !== 0 || /npm (error|ERR!)/.test(out)) {
-    fail(`npm publish --dry-run ${label} failed:\n${out}`);
-  } else {
-    log(`npm publish --dry-run ${label}: ok`);
-  }
-}
-
 /**
  * What a subpath's declarations may import, beyond the SDK itself. A subpath
  * whose packages are not all installed in the smoke project is skipped by the
@@ -313,21 +281,15 @@ function main(): void {
   if (!args.has('--skip-build')) {
     mustRun('npm run build', 'npm', ['run', 'build'], REPO_ROOT);
     mustRun('npm run build (create-lousho)', 'npm', ['run', 'build', '--workspace=packages/create-lousho'], REPO_ROOT);
-    // prepublishOnly also builds Agent Forge; without it the tarball is ~5 MB smaller than the published one.
-    mustRun('npm run build:studio', 'npm', ['run', 'build:studio'], REPO_ROOT);
   }
-  const base = fs.mkdtempSync(path.join(os.tmpdir(), 'lousho-pack-smoke-'));
+  const { base, packDir, project } = smokeDirs('lousho-pack-smoke');
   log(`temp dir ${base}`);
-  const packDir = path.join(base, 'tarballs');
-  const project = path.join(base, 'project');
-  fs.mkdirSync(packDir);
-  fs.mkdirSync(project);
   try {
-    const sdk = pack('(sdk)', REPO_ROOT, packDir);
-    const creator = pack('(create-lousho)', path.join(REPO_ROOT, 'packages', 'create-lousho'), packDir);
+    const sdk = packTarball(rep, '(sdk)', REPO_ROOT, packDir);
+    const creator = packTarball(rep, '(create-lousho)', path.join(REPO_ROOT, 'packages', 'create-lousho'), packDir);
     checkTarball(sdk.entry, sdk.tarball);
-    dryRunPublish('(sdk)', sdk.tarball, base);
-    dryRunPublish('(create-lousho)', creator.tarball, base);
+    dryRunPublish(rep, '(sdk)', sdk.tarball, base);
+    dryRunPublish(rep, '(create-lousho)', creator.tarball, base);
 
     const peers = (process.env.PACK_SMOKE_PEERS ?? DEFAULT_PEERS).split(/\s+/).filter(Boolean);
     const fileUrl = (p: string) => `file:${p.replace(/\\/g, '/')}`;
@@ -358,14 +320,9 @@ function main(): void {
       else log('create-lousho --help: ok');
     }
   } finally {
-    if (args.has('--keep')) log(`kept ${base}`);
-    else fs.rmSync(base, { recursive: true, force: true });
-  }
-  if (failures.length) {
-    console.error(`\n[pack-smoke] ${failures.length} failure(s):\n- ${failures.join('\n- ')}`);
-    process.exit(1);
+    cleanSmokeDir(rep, base, args.has('--keep'));
   }
-  log('all checks passed');
+  reportSmoke(rep);
 }
 
 main();
diff --git a/scripts/prepack-check.mjs b/scripts/prepack-check.mjs
index d4207cc40..2473a6357 100644
--- a/scripts/prepack-check.mjs
+++ b/scripts/prepack-check.mjs
@@ -1,15 +1,15 @@
-// `npm pack` / `npm publish` (prepack): warn when the tarball would ship without
-// the Agent Forge build, so `lousho studio` would not work from it. The build is
-// not run here because `npm pack` of the checkout also runs for
-// `lousho init --sdk-path`, docs:verify-snippets and the scaffold tests, which
-// do not need it; prepublishOnly builds it for a real publish.
-import { existsSync, readFileSync } from 'node:fs';
+// `npm pack` / `npm publish` (prepack): the release guard. The tarball never
+// contains Studio (apps/agent-forge left the package in W13b; `lousho studio`
+// launches the separately installed @linuxdevil/studio). The build is not run
+// here because `npm pack` of the checkout also runs for `lousho init
+// --sdk-path`, docs:verify-snippets and the scaffold tests; prepublishOnly
+// builds the SDK for a real publish.
+import { readFileSync } from 'node:fs';
 import { missingChangelogHeading } from './changelogGuard.mjs';
 
 // Release guard: the version being packed must have its own CHANGELOG heading.
-// Unlike the Agent Forge warning below this fails the pack, and so
-// `npm publish`. CI's pack-smoke packs the current version, so main keeps a
-// heading for the version in package.json.
+// This fails the pack, and so `npm publish`. CI's pack-smoke packs the
+// current version, so main keeps a heading for the version in package.json.
 const changelogError = missingChangelogHeading(
   readFileSync('CHANGELOG.md', 'utf8'),
   JSON.parse(readFileSync('package.json', 'utf8')).version
@@ -18,11 +18,3 @@ if (changelogError) {
   console.error(changelogError);
   process.exit(1);
 }
-
-// npm runs prepack in the package root.
-if (!existsSync('apps/agent-forge/dist-server/index.cjs')) {
-  console.warn(
-    "prepack: apps/agent-forge is not built, so 'lousho studio' will not work from this tarball. " +
-      "Run 'npm run build:studio' first if you need it (npm publish builds it in prepublishOnly)."
-  );
-}
diff --git a/scripts/publish-github-packages.mjs b/scripts/publish-github-packages.mjs
index 88f9b43a5..065b512c6 100644
--- a/scripts/publish-github-packages.mjs
+++ b/scripts/publish-github-packages.mjs
@@ -1,8 +1,8 @@
 // Mirrors the two npm packages to GitHub Packages (npm.pkg.github.com) so they
-// are listed on the repo's Packages tab. GitHub only accepts packages scoped to
-// the repo owner, so the mirror is renamed @linuxdevil/*; npmjs.com keeps the
-// original names. Run after `npm run build`, `npm run build:studio` and
-// `npm run build -w create-lousho`. Needs NODE_AUTH_TOKEN with packages:write.
+// are listed on the repo's Packages tab. npm and GitHub Packages use the same
+// @linuxdevil/* names, so the dependency ranges resolve as-is. Run after
+// `npm run build`, `npm run build:studio` and `npm run build -w create-lousho`.
+// Needs NODE_AUTH_TOKEN with packages:write.
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -13,12 +13,10 @@ const REGISTRY = 'https://npm.pkg.github.com';
 const tag = process.env.NPM_TAG || 'alpha';
 const dry = process.argv.includes('--dry-run');
 
-const SDK = 'lousho';
 const targets = [
   { dir: '.', name: `${SCOPE}/lousho` },
   { dir: 'packages/create-lousho', name: `${SCOPE}/create-lousho` },
 ];
-const sdkVersion = JSON.parse(fs.readFileSync('package.json', 'utf8')).version;
 const run = (cmd, args, cwd) => execFileSync(cmd, args, { cwd, stdio: ['ignore', 'pipe', 'inherit'], shell: process.platform === 'win32' }).toString().trim();
 
 for (const t of targets) {
@@ -33,8 +31,8 @@ for (const t of targets) {
   // The tarball is already built. Its lifecycle scripts (prepare: husky,
   // prepublishOnly) would otherwise run here, where their deps don't exist.
   delete pkg.scripts;
-  // The scaffolder resolves the SDK by its npm name; alias keeps that working.
-  if (pkg.dependencies?.[SDK]) pkg.dependencies[SDK] = `npm:${SCOPE}/lousho@^${sdkVersion}`;
+  // npm and GitHub Packages now use the same @linuxdevil/* names, so the
+  // SDK dependency range resolves to this registry's mirror as-is.
   fs.writeFileSync(file, JSON.stringify(pkg, null, 2) + '\n');
   fs.writeFileSync(path.join(pkgDir, '.npmrc'), `//npm.pkg.github.com/:_authToken=${process.env.NODE_AUTH_TOKEN}
 `);
diff --git a/scripts/size-budget.json b/scripts/size-budget.json
index 5a7581b51..9976a5e50 100644
--- a/scripts/size-budget.json
+++ b/scripts/size-budget.json
@@ -1,4 +1,4 @@
 {
-  "bundleBytes": 658035,
-  "tarballUnpackedBytes": 27200000
+  "bundleBytes": 467582,
+  "tarballUnpackedBytes": 19692926
 }
diff --git a/scripts/size-check.ts b/scripts/size-check.ts
index beb2e00fe..8e1d83349 100644
--- a/scripts/size-check.ts
+++ b/scripts/size-check.ts
@@ -13,9 +13,8 @@
  *      published package (what lands in node_modules).
  *
  * Needs a built `dist/` (`npm run build`). `npm pack` runs with --dry-run and
- * --ignore-scripts, so nothing is written; the tarball figure includes the
- * Agent Forge build only when `npm run build:studio` ran first (CI does both,
- * so its figure is the real one).
+ * --ignore-scripts, so nothing is written; the tarball never includes Studio
+ * (apps/agent-forge left the package in W13b).
  *
  * Usage: npm run size-check [-- --update]
  *   --update  rewrites the budgets to the current measurement + 5%.
diff --git a/scripts/smokeKit.ts b/scripts/smokeKit.ts
index 726237546..e68534353 100644
--- a/scripts/smokeKit.ts
+++ b/scripts/smokeKit.ts
@@ -5,10 +5,12 @@
  * two scripts cannot drift and `fallow` sees no duplicated code.
  */
 import { spawnSync } from 'node:child_process';
+import { createServer, type AddressInfo } from 'node:net';
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 
-export const SDK_NAME = 'lousho';
+export const SDK_NAME = '@linuxdevil/lousho';
 export const IS_WIN = process.platform === 'win32';
 
 /** Optional peers: a subpath whose load fails because one of these is absent is checked by file existence only. */
@@ -16,6 +18,7 @@ const OPTIONAL_PEERS = ['vue', 'react', 'svelte', '@opentelemetry/api', '@modelc
 
 /** Collects failures and prints `[<prefix>]` lines. */
 export interface Reporter {
+  prefix: string;
   failures: string[];
   log(msg: string): void;
   fail(msg: string): void;
@@ -24,6 +27,7 @@ export interface Reporter {
 export function createReporter(prefix: string): Reporter {
   const failures: string[] = [];
   return {
+    prefix,
     failures,
     log: (msg) => console.log(`[${prefix}] ${msg}`),
     fail: (msg) => {
@@ -49,7 +53,7 @@ export function run(cmd: string, argv: string[], cwd: string, env: NodeJS.Proces
   return { status: res.status ?? 1, stdout: res.stdout ?? '', stderr: res.stderr ?? '' };
 }
 
-export function mustRun(rep: Reporter, label: string, cmd: string, argv: string[], cwd: string, env?: NodeJS.ProcessEnv): RunResult {
+function mustRun(rep: Reporter, label: string, cmd: string, argv: string[], cwd: string, env?: NodeJS.ProcessEnv): RunResult {
   rep.log(label);
   const res = run(cmd, argv, cwd, env);
   if (res.status !== 0) {
@@ -59,6 +63,113 @@ export function mustRun(rep: Reporter, label: string, cmd: string, argv: string[
   return res;
 }
 
+/**
+ * `npm publish <tarball> --dry-run` - never a real publish. Tolerates the
+ * "cannot publish over the previously published versions" failure that only
+ * means this version is already on npm.
+ */
+export function dryRunPublish(rep: Reporter, label: string, tarball: string, cwd: string): void {
+  // `--tag next`: the versions are prereleases and npm 11 refuses a prerelease without an explicit tag.
+  const res = run('npm', ['publish', tarball, '--dry-run', '--tag', 'next', '--access', 'public'], cwd);
+  const out = res.stdout + res.stderr;
+  if (/cannot publish over the previously published versions/i.test(out)) {
+    rep.log(`npm publish --dry-run ${label}: ok (this version is already on npm; bump it before the next release)`);
+  } else if (res.status !== 0 || /npm (error|ERR!)/.test(out)) {
+    rep.fail(`npm publish --dry-run ${label} failed:\n${out}`);
+  } else {
+    rep.log(`npm publish --dry-run ${label}: ok`);
+  }
+}
+
+export interface PackEntry {
+  filename: string;
+  entryCount: number;
+  size: number;
+  unpackedSize: number;
+  files: { path: string }[];
+}
+
+/** `npm pack --json` for one package; tolerates prepack/postpack stdout before the JSON array. */
+export function packTarball(rep: Reporter, label: string, cwd: string, dest: string): { entry: PackEntry; tarball: string } {
+  const res = mustRun(rep, `npm pack ${label}`, 'npm', ['pack', '--json', '--pack-destination', dest], cwd);
+  const jsonStart = res.stdout.search(/^\[/m);
+  if (jsonStart < 0) throw new Error(`npm pack ${label}: no JSON array in output:\n${res.stdout}`);
+  const entry = (JSON.parse(res.stdout.slice(jsonStart)) as PackEntry[])[0];
+  return { entry, tarball: path.join(dest, entry.filename) };
+}
+
+export interface TarballLimits {
+  maxEntries: number;
+  maxUnpackedBytes: number;
+  maxPackedBytes: number;
+  requiredPaths: readonly string[];
+  forbiddenPatterns: readonly RegExp[];
+}
+
+/** Entry count, sizes, required/forbidden paths and budgets for one packed tarball. */
+export function checkTarballContents(rep: Reporter, entry: PackEntry, limits: TarballLimits): void {
+  rep.log(`tarball ${entry.filename}: ${entry.entryCount} entries, ${(entry.unpackedSize / 1048576).toFixed(1)} MB unpacked, ${(entry.size / 1048576).toFixed(1)} MB packed`);
+  if (entry.entryCount > limits.maxEntries) rep.fail(`tarball has ${entry.entryCount} entries (max ${limits.maxEntries})`);
+  if (entry.unpackedSize > limits.maxUnpackedBytes) rep.fail(`tarball unpacked size ${entry.unpackedSize} exceeds ${limits.maxUnpackedBytes}`);
+  if (entry.size > limits.maxPackedBytes) rep.fail(`tarball packed size ${entry.size} exceeds ${limits.maxPackedBytes}`);
+  const packed = new Set(entry.files.map((f) => f.path));
+  for (const p of limits.requiredPaths) {
+    if (!packed.has(p)) rep.fail(`tarball is missing required file ${p}`);
+  }
+  for (const f of entry.files) {
+    if (limits.forbiddenPatterns.some((re) => re.test(f.path))) rep.fail(`tarball contains forbidden file ${f.path}`);
+  }
+}
+
+/** The argv/reporter/mustRun preamble every pack-smoke script shares. */
+export function smokeSetup(prefix: string): {
+  args: Set<string>;
+  rep: Reporter;
+  log(msg: string): void;
+  fail(msg: string): void;
+  mustRun(label: string, cmd: string, argv: string[], cwd: string, env?: NodeJS.ProcessEnv): RunResult;
+} {
+  const args = new Set(process.argv.slice(2));
+  const rep = createReporter(prefix);
+  const { log, fail } = rep;
+  const mustRunLocal = (label: string, cmd: string, argv: string[], cwd: string, env?: NodeJS.ProcessEnv) => mustRun(rep, label, cmd, argv, cwd, env);
+  return { args, rep, log, fail, mustRun: mustRunLocal };
+}
+
+/** `<tmp>/<prefix>-XXXX/{tarballs,project}` for a smoke run. */
+export function smokeDirs(prefix: string): { base: string; packDir: string; project: string } {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-`));
+  const packDir = path.join(base, 'tarballs');
+  const project = path.join(base, 'project');
+  fs.mkdirSync(packDir);
+  fs.mkdirSync(project);
+  return { base, packDir, project };
+}
+
+/** Shared tail, step 1: keep or remove the temp dir (call from `finally`). */
+export function cleanSmokeDir(rep: Reporter, base: string, keep: boolean): void {
+  if (keep) rep.log(`kept ${base}`);
+  else fs.rmSync(base, { recursive: true, force: true });
+}
+
+/** Shared tail, step 2: report collected failures, or pass. */
+export function reportSmoke(rep: Reporter): void {
+  if (rep.failures.length) {
+    console.error(`\n[${rep.prefix}] ${rep.failures.length} failure(s):\n- ${rep.failures.join('\n- ')}`);
+    process.exit(1);
+  }
+  rep.log('all checks passed');
+}
+
+/** An ephemeral loopback port, free at call time (a small race window is fine for smoke tests). */
+export async function freePort(): Promise<number> {
+  const server = createServer();
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const port = (server.address() as AddressInfo).port;
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+  return port;
+}
+
 /** All `exports` subpaths with their targets, from the installed package.json. */
 export function listExports(pkgDir: string): { subpath: string; spec: string; targets: string[] }[] {
   const pkg = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf8'));
@@ -144,12 +255,12 @@ export function checkModuleLoads(rep: Reporter, project: string, pkgDir: string)
 export function checkBin(rep: Reporter, project: string): void {
   const installed = path.join(project, 'node_modules', '.bin', IS_WIN ? 'lousho.cmd' : 'lousho');
   if (!fs.existsSync(installed)) return rep.fail(`node_modules/.bin/lousho was not created (${installed})`);
-  const help = run('npx', ['--no-install', 'lousho', '--help'], project);
+  const help = run('npx', ['--no-install', '@linuxdevil/lousho', '--help'], project);
   if (help.status !== 0 || !/lousho init/.test(help.stdout + help.stderr)) rep.fail(`npx lousho --help failed: ${help.stdout}${help.stderr}`);
   else rep.log('npx lousho --help: ok');
   const clean = { ...process.env };
   for (const k of ['OPENAI_API_KEY', 'ANTHROPIC_API_KEY', 'OPENROUTER_API_KEY']) delete clean[k];
-  const doctor = run('npx', ['--no-install', 'lousho', 'doctor', '--json'], project, clean);
+  const doctor = run('npx', ['--no-install', '@linuxdevil/lousho', 'doctor', '--json'], project, clean);
   // doctor exits non-zero when a check fails (e.g. no API key); only a crash is a smoke failure.
   try {
     const parsed = JSON.parse(doctor.stdout);
diff --git a/scripts/sync-version.mjs b/scripts/sync-version.mjs
index 781186980..e0d64808b 100644
--- a/scripts/sync-version.mjs
+++ b/scripts/sync-version.mjs
@@ -14,7 +14,7 @@ if (next !== indexSrc) fs.writeFileSync(indexPath, next);
 
 const scaffoldPath = 'packages/create-lousho/package.json';
 const scaffold = JSON.parse(fs.readFileSync(scaffoldPath, 'utf8'));
-scaffold.dependencies['lousho'] = `^${version}`;
+scaffold.dependencies['@linuxdevil/lousho'] = `^${version}`;
 fs.writeFileSync(scaffoldPath, JSON.stringify(scaffold, null, 2) + '\n');
 
 console.log(`sync-version: VERSION and scaffold pin set to ${version}`);
diff --git a/scripts/verify-docs-snippets.ts b/scripts/verify-docs-snippets.ts
index b2c72ebae..e0d981fc7 100644
--- a/scripts/verify-docs-snippets.ts
+++ b/scripts/verify-docs-snippets.ts
@@ -64,13 +64,13 @@ const REPO_ROOT = path.resolve(__dirname, '..');
 /** Docs whose every snippet is type-checked AND executed against the packed tarball (stage B); see isRunnableByDefault. */
 const RUNNABLE_DOCS = [path.join(REPO_ROOT, 'docs', 'quick-start.md')];
 /** Ambient names (typed against the SDK where possible) that intentionally-partial snippets may use without defining. */
-const SDK = "import('lousho')";
+const SDK = "import('@linuxdevil/lousho')";
 const PLACEHOLDERS: Record<string, string> = {
   agent: `${SDK}.AgentConfig`,
   provider: `${SDK}.LLMProvider`,
-  registry: `import('lousho/executor').ToolRegistry`,
-  toolRegistry: `import('lousho/executor').ToolRegistry`,
-  storage: `import('lousho/utils').StorageService`,
+  registry: `import('@linuxdevil/lousho/executor').ToolRegistry`,
+  toolRegistry: `import('@linuxdevil/lousho/executor').ToolRegistry`,
+  storage: `import('@linuxdevil/lousho/utils').StorageService`,
   approvalStore: `${SDK}.ApprovalStore`,
   checkpointStore: `${SDK}.CheckpointStore`,
   mcpClient: "import('@modelcontextprotocol/sdk/client/index.js').Client",
@@ -172,7 +172,7 @@ function setUpProject(projectDir: string, skipBuild: boolean): void {
   // `@ai-sdk/*` peer on several majors: pin the pairing the repo
   // develops against (its devDependencies), not whatever the widest range resolves to.
   const dependencies: Record<string, string> = {
-    'lousho': `file:./${tarball}`,
+    '@linuxdevil/lousho': `file:./${tarball}`,
     ai: dev.ai,
     zod: peers.zod,
     '@ai-sdk/openai': dev['@ai-sdk/openai'],
@@ -387,7 +387,7 @@ function allDocFiles(): string[] {
 /** tsconfig `paths` mapping each package.json export's types entry (dist/*.d.ts) to its src/*.ts source. */
 function sourcePaths(): Record<string, string[]> {
   const pkg = readJson(path.join(REPO_ROOT, 'package.json'));
-  // `lousho/spec` builds dist/spec/ from src/spec/v2/index.ts: src/spec/index.ts
+  // `@linuxdevil/lousho/spec` builds dist/spec/ from src/spec/v2/index.ts: src/spec/index.ts
   // is already the v1 spec barrel, so the mechanical dist->src mapping misses it.
   const SOURCE_OVERRIDES: Record<string, string[]> = { [`${pkg.name}/spec`]: ['src/spec/v2/index.ts'] };
   const paths: Record<string, string[]> = {};
diff --git a/src/agentDir/collectTools.ts b/src/agentDir/collectTools.ts
index bd93f9dc0..3380514f5 100644
--- a/src/agentDir/collectTools.ts
+++ b/src/agentDir/collectTools.ts
@@ -31,7 +31,7 @@ export interface ToolModule {
 const EXAMPLE = `Expected a tool made with defineTool(), for example:
 
   import { z } from 'zod';
-  import { defineTool } from 'lousho';
+  import { defineTool } from '@linuxdevil/lousho';
   export default defineTool({ name: 'ping', description: 'Ping', input: z.object({}), execute: () => 'pong' });`;
 
 /** Tools found in one exported value: a tool, an array of tools, or (CJS) an exports object of tools. */
diff --git a/src/agentDir/dualPackage.test.ts b/src/agentDir/dualPackage.test.ts
index 16c4933b5..84430575d 100644
--- a/src/agentDir/dualPackage.test.ts
+++ b/src/agentDir/dualPackage.test.ts
@@ -50,9 +50,9 @@ describe('brands across two loaded copies of the SDK', () => {
 function project(): string {
   const dir = mkdtempSync(path.join(tmpdir(), 'lousho-dual-'));
   dirs.push(dir);
-  mkdirSync(path.join(dir, 'node_modules'), { recursive: true });
+  mkdirSync(path.join(dir, 'node_modules', '@linuxdevil'), { recursive: true });
   // 'junction' makes a directory link without the symlink privilege on Windows; other platforms ignore the type.
-  symlinkSync(ROOT, path.join(dir, 'node_modules', 'lousho'), 'junction');
+  symlinkSync(ROOT, path.join(dir, 'node_modules', '@linuxdevil', 'lousho'), 'junction');
   symlinkSync(path.join(ROOT, 'node_modules', 'zod'), path.join(dir, 'node_modules', 'zod'), 'junction');
   writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name: 'dual', private: true }));
   const agent = path.join(dir, 'simple');
@@ -61,12 +61,12 @@ function project(): string {
   writeFileSync(path.join(agent, 'instructions.md'), 'You are simple.\n');
   writeFileSync(
     path.join(agent, 'tools', 'ping.mjs'),
-    "import { z } from 'zod';\nimport { defineTool } from 'lousho';\n" +
+    "import { z } from 'zod';\nimport { defineTool } from '@linuxdevil/lousho';\n" +
       "export default defineTool({ name: 'ping', description: 'Ping', input: z.object({}), execute: () => 'pong' });\n"
   );
   writeFileSync(
     path.join(agent, 'tools', 'pong.cjs'),
-    "const { z } = require('zod');\nconst { defineTool } = require('lousho');\n" +
+    "const { z } = require('zod');\nconst { defineTool } = require('@linuxdevil/lousho');\n" +
       "module.exports = defineTool({ name: 'pong', description: 'Pong', input: z.object({}), execute: () => 'ping' });\n"
   );
   return dir;
@@ -77,14 +77,14 @@ const LIST_TOOLS = `.then(async (r) => { const { manifest } = await r.resolveAge
 describe.skipIf(!BUILT)('agent directory tools through both builds (needs npm run build)', () => {
   it('loads ESM and CJS tool files from the CJS build', () => {
     const cwd = project();
-    const res = spawnSync(process.execPath, ['-e', `Promise.resolve(require('lousho'))${LIST_TOOLS}`], { cwd, encoding: 'utf8' });
+    const res = spawnSync(process.execPath, ['-e', `Promise.resolve(require('@linuxdevil/lousho'))${LIST_TOOLS}`], { cwd, encoding: 'utf8' });
     expect(res.stderr).toBe('');
     expect(res.stdout.trim()).toBe('ping,pong');
   });
 
   it('loads ESM and CJS tool files from the ESM build', () => {
     const cwd = project();
-    const res = spawnSync(process.execPath, ['--input-type=module', '-e', `import('lousho')${LIST_TOOLS}`], { cwd, encoding: 'utf8' });
+    const res = spawnSync(process.execPath, ['--input-type=module', '-e', `import('@linuxdevil/lousho')${LIST_TOOLS}`], { cwd, encoding: 'utf8' });
     expect(res.stderr).toBe('');
     expect(res.stdout.trim()).toBe('ping,pong');
   });
diff --git a/src/agentDir/loadAgentDir.test.ts b/src/agentDir/loadAgentDir.test.ts
index cd1cc891b..aabaff0dd 100644
--- a/src/agentDir/loadAgentDir.test.ts
+++ b/src/agentDir/loadAgentDir.test.ts
@@ -641,12 +641,12 @@ describe('helpers', () => {
   });
 
   it('codes an unresolvable package import with a hint naming the package and where Node looks for it', () => {
-    const esm = Object.assign(new Error("Cannot find package 'lousho' imported from /k/tools/fs.ts"), { code: 'ERR_MODULE_NOT_FOUND' });
+    const esm = Object.assign(new Error("Cannot find package '@linuxdevil/lousho' imported from /k/tools/fs.ts"), { code: 'ERR_MODULE_NOT_FOUND' });
     const error = explainImportError('/k/tools/fs.ts', esm) as SDKError;
     expect(error).toBeInstanceOf(SDKError);
     expect(error.code).toBe('LOUSHO_AGENT_DIR_INVALID');
     expect(error.message).toContain('failed to import /k/tools/fs.ts');
-    expect(error.hint).toContain('npm install lousho');
+    expect(error.hint).toContain('npm install @linuxdevil/lousho');
     expect(error.hint).toContain('node_modules');
     const cjs = Object.assign(new Error("Cannot find module 'zod/v4'\nRequire stack:\n- /k/a.ts"), { code: 'MODULE_NOT_FOUND' });
     expect((explainImportError('/k/a.ts', cjs) as SDKError).hint).toContain('npm install zod');
diff --git a/src/agentDir/loadAuth.ts b/src/agentDir/loadAuth.ts
index 08ba2f398..a35330b2c 100644
--- a/src/agentDir/loadAuth.ts
+++ b/src/agentDir/loadAuth.ts
@@ -17,7 +17,7 @@ type AgentDirAccessRules = Pick<ChatRoutesAccess, 'authorizeSession' | 'authoriz
 /**
  * The route auth of an agent directory, from its `auth.{ts,js,mjs,cjs,mts}`
  * file, which default-exports an auth entry or an ordered list of them
- * (`jwt()`, `oidc()`, `basic()`, `apiToken()`, ... from `lousho/auth`),
+ * (`jwt()`, `oidc()`, `basic()`, `apiToken()`, ... from `@linuxdevil/lousho/auth`),
  * plus its optional named `authorizeSession` / `authorizeApproval` exports
  * (docs/auth.md). `undefined` when the directory has no such file.
  */
diff --git a/src/agentDir/spec.ts b/src/agentDir/spec.ts
index 0a5bdf0a5..cfcfeed58 100644
--- a/src/agentDir/spec.ts
+++ b/src/agentDir/spec.ts
@@ -37,7 +37,7 @@ import { listSubagentDirs } from './subagents';
 import { fail, validateConfig, type AgentDirConfig, type AgentDirPermissionRule } from './validateConfig';
 
 // The pure write side moved to `src/spec/v2/specToAgentDir.ts` (S19); these
-// re-exports keep `import { specToAgentDir } from 'lousho'` working.
+// re-exports keep `import { specToAgentDir } from '@linuxdevil/lousho'` working.
 export { specToAgentDir };
 export type { DroppedField, SpecToAgentDirResult };
 
diff --git a/src/auth/index.ts b/src/auth/index.ts
index ebbe1f6f8..92bc24fe6 100644
--- a/src/auth/index.ts
+++ b/src/auth/index.ts
@@ -1,5 +1,5 @@
 /**
- * `lousho/auth`: route auth helpers that run as an
+ * `@linuxdevil/lousho/auth`: route auth helpers that run as an
  * ordered list and fail closed, and the `Principal` they hand to the run.
  * Web Crypto and `fetch` only: usable in Node, Workers and edge routes.
  * See docs/auth.md.
diff --git a/src/auth/routeAuth.test.ts b/src/auth/routeAuth.test.ts
index ac0099aef..f198fd8e2 100644
--- a/src/auth/routeAuth.test.ts
+++ b/src/auth/routeAuth.test.ts
@@ -99,7 +99,7 @@ describe('routeAuth', () => {
   });
 });
 
-describe('lousho/auth', () => {
+describe('@linuxdevil/lousho/auth', () => {
   afterEach(() => stop());
 
   it('exports the helpers', () => {
diff --git a/src/channels/defineChannel.ts b/src/channels/defineChannel.ts
index dae592fc0..3c6e7a2d3 100644
--- a/src/channels/defineChannel.ts
+++ b/src/channels/defineChannel.ts
@@ -181,7 +181,7 @@ const SESSION_ID = /^[A-Za-z0-9_-]{1,128}$/;
  *
  * @example
  * ```ts
- * import { defineChannel } from 'lousho';
+ * import { defineChannel } from '@linuxdevil/lousho';
  *
  * const sms = defineChannel({
  *   name: 'sms',
diff --git a/src/channels/discordChannel.ts b/src/channels/discordChannel.ts
index 6524ef932..5b896eb81 100644
--- a/src/channels/discordChannel.ts
+++ b/src/channels/discordChannel.ts
@@ -130,7 +130,7 @@ function button(label: string, customId: string, style: number) {
  *
  * @example
  * ```ts
- * import { discordChannel } from 'lousho';
+ * import { discordChannel } from '@linuxdevil/lousho';
  *
  * const discord = discordChannel({
  *   publicKey: process.env.DISCORD_PUBLIC_KEY ?? '',
diff --git a/src/channels/githubChannel.ts b/src/channels/githubChannel.ts
index 229e813ee..f9eb14a92 100644
--- a/src/channels/githubChannel.ts
+++ b/src/channels/githubChannel.ts
@@ -228,7 +228,7 @@ async function signatureMatches(secret: string, header: string, rawBody: Uint8Ar
  *
  * @example
  * ```ts
- * import { githubChannel } from 'lousho';
+ * import { githubChannel } from '@linuxdevil/lousho';
  *
  * const github = githubChannel({
  *   webhookSecret: process.env.GITHUB_WEBHOOK_SECRET ?? '',
diff --git a/src/channels/httpChannel.ts b/src/channels/httpChannel.ts
index cc20dc530..f4087c597 100644
--- a/src/channels/httpChannel.ts
+++ b/src/channels/httpChannel.ts
@@ -30,7 +30,7 @@ export interface HttpChannelOptions {
  *
  * @example
  * ```ts
- * import { httpChannel } from 'lousho';
+ * import { httpChannel } from '@linuxdevil/lousho';
  *
  * const api = httpChannel({ verify: async (req) => req.headers.authorization === `Bearer ${process.env.API_TOKEN}` });
  * ```
diff --git a/src/channels/mountChannels.ts b/src/channels/mountChannels.ts
index df5f071ba..423935cb6 100644
--- a/src/channels/mountChannels.ts
+++ b/src/channels/mountChannels.ts
@@ -66,7 +66,7 @@ export interface ChannelsHandler {
  * @example
  * ```ts
  * import * as http from 'node:http';
- * import { createAgent, createMockProvider, httpChannel, mountChannels } from 'lousho';
+ * import { createAgent, createMockProvider, httpChannel, mountChannels } from '@linuxdevil/lousho';
  *
  * const agent = createAgent({ prompt: 'You are helpful.', provider: createMockProvider() });
  * const channels = mountChannels(agent, [httpChannel()]);
diff --git a/src/channels/slackChannel.ts b/src/channels/slackChannel.ts
index f86419b58..ae56f30b1 100644
--- a/src/channels/slackChannel.ts
+++ b/src/channels/slackChannel.ts
@@ -127,7 +127,7 @@ function button(text: string, actionId: string, style: string, value: string) {
  *
  * @example
  * ```ts
- * import { slackChannel } from 'lousho';
+ * import { slackChannel } from '@linuxdevil/lousho';
  *
  * const slack = slackChannel({
  *   signingSecret: process.env.SLACK_SIGNING_SECRET ?? '',
diff --git a/src/channels/teamsChannel.ts b/src/channels/teamsChannel.ts
index 3eb110ef0..d18675619 100644
--- a/src/channels/teamsChannel.ts
+++ b/src/channels/teamsChannel.ts
@@ -146,7 +146,7 @@ const submit = (title: string, data: Decision) => ({ type: 'Action.Submit', titl
  *
  * @example
  * ```ts
- * import { teamsChannel } from 'lousho';
+ * import { teamsChannel } from '@linuxdevil/lousho';
  *
  * const teams = teamsChannel({
  *   appId: process.env.MICROSOFT_APP_ID ?? '',
diff --git a/src/channels/telegramChannel.ts b/src/channels/telegramChannel.ts
index 3f4b34b84..daffa83d4 100644
--- a/src/channels/telegramChannel.ts
+++ b/src/channels/telegramChannel.ts
@@ -128,7 +128,7 @@ function escapeRegExp(text: string): string {
  *
  * @example
  * ```ts
- * import { telegramChannel } from 'lousho';
+ * import { telegramChannel } from '@linuxdevil/lousho';
  *
  * const telegram = telegramChannel({
  *   botToken: process.env.TELEGRAM_BOT_TOKEN ?? '',
diff --git a/src/channels/webhookChannel.ts b/src/channels/webhookChannel.ts
index 72d050214..a5342132d 100644
--- a/src/channels/webhookChannel.ts
+++ b/src/channels/webhookChannel.ts
@@ -80,7 +80,7 @@ async function verifyWebhook(auth: WebhookAuth | undefined, req: ChannelRequest)
  *
  * @example
  * ```ts
- * import { webhookChannel } from 'lousho';
+ * import { webhookChannel } from '@linuxdevil/lousho';
  *
  * const hooks = webhookChannel({
  *   secret: process.env.WEBHOOK_SECRET ?? '',
diff --git a/src/claude/claudeProject.ts b/src/claude/claudeProject.ts
index 2585a4d04..b22c18062 100644
--- a/src/claude/claudeProject.ts
+++ b/src/claude/claudeProject.ts
@@ -7,7 +7,7 @@
  * duplicating anything into a Lousho-specific layout:
  *
  * ```ts
- * import { createAgent, claudeProject } from 'lousho';
+ * import { createAgent, claudeProject } from '@linuxdevil/lousho';
  *
  * const project = await claudeProject('./my-repo', { provider });
  * const agent = createAgent({ provider, ...project });
diff --git a/src/cli/addCheck.test.ts b/src/cli/addCheck.test.ts
index 9acf0a4e5..615415fe1 100644
--- a/src/cli/addCheck.test.ts
+++ b/src/cli/addCheck.test.ts
@@ -27,8 +27,8 @@ describe('checkItem', () => {
       ["import shell from 'shelljs';"],
       ["const cp = await import('node:child_process');"],
       ["export { spawn } from 'child_process';"],
-      ["import { createShellTool } from 'lousho';\nexport default createShellTool();"],
-      ["import { SubprocessSandbox } from 'lousho';"],
+      ["import { createShellTool } from '@linuxdevil/lousho';\nexport default createShellTool();"],
+      ["import { SubprocessSandbox } from '@linuxdevil/lousho';"],
     ])('needs exec: true for %s', (code) => {
       expect(refused(code).join('\n')).toContain('declare exec: true in permissions');
       expect(refused(code, { exec: true })).toEqual([]);
@@ -51,8 +51,8 @@ describe('checkItem', () => {
     });
 
     it('treats createFsTools as filesystem access', () => {
-      expect(refused("import { createFsTools } from 'lousho';")).toHaveLength(1);
-      expect(refused("import { createFsTools } from 'lousho';", { filesystem: 'read' })).toEqual([]);
+      expect(refused("import { createFsTools } from '@linuxdevil/lousho';")).toHaveLength(1);
+      expect(refused("import { createFsTools } from '@linuxdevil/lousho';", { filesystem: 'read' })).toEqual([]);
     });
   });
 
diff --git a/src/cli/bin.test.ts b/src/cli/bin.test.ts
index 0aff86ee6..5cc160fa0 100644
--- a/src/cli/bin.test.ts
+++ b/src/cli/bin.test.ts
@@ -28,6 +28,7 @@ describe('bin/lousho.js', () => {
     expect(banner).not.toContain('stub');
     expect(banner).toContain('[--timeout <ms>]');
     expect(banner).toContain('lousho --version');
+    expect(banner).toContain('lousho studio [--port N] [--host H]');
     expect(banner).toContain('[--allowed-hosts a,b]');
     expect(banner).toContain('2 usage error');
     expect(banner).toContain('lousho improve <agent-dir|agent.ts> --check <module>');
diff --git a/src/cli/defaultRegistry.test.ts b/src/cli/defaultRegistry.test.ts
index b5994665f..09e5650c2 100644
--- a/src/cli/defaultRegistry.test.ts
+++ b/src/cli/defaultRegistry.test.ts
@@ -23,7 +23,7 @@ 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';
+import { resolveAgentDir } from '@linuxdevil/lousho';
 import { runAdd } from './add';
 import { IndexSchema, ItemSchema } from './registry';
 
@@ -128,7 +128,7 @@ describe('default registry (registry/dist)', () => {
     const kits = index.items.filter((entry) => entry.type === 'kit');
     expect(kits.length).toBeGreaterThan(0);
     const loader =
-      "const { resolveAgentDir } = await import('lousho');" +
+      "const { resolveAgentDir } = await import('@linuxdevil/lousho');" +
       '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.
diff --git a/src/cli/init.test.ts b/src/cli/init.test.ts
index 1f3dae46a..61764a0d8 100644
--- a/src/cli/init.test.ts
+++ b/src/cli/init.test.ts
@@ -114,12 +114,12 @@ describe('runInit --yes', () => {
 
   it('writes a caret range of the SDK version, or a tarball with --sdk-path', async () => {
     await runInit(['plain', '--yes', '--no-install', '--no-git'], harness().environment);
-    expect(JSON.parse(read('plain', 'package.json')).dependencies['lousho']).toBe('^1.0.0-alpha.8');
+    expect(JSON.parse(read('plain', 'package.json')).dependencies['@linuxdevil/lousho']).toBe('^1.0.0-alpha.8');
 
     const tarball = path.join(root, 'sdk-9.9.9.tgz');
     fs.writeFileSync(tarball, 'tgz');
     await runInit(['local', '--yes', '--no-install', '--no-git', '--sdk-path', tarball], harness().environment);
-    expect(JSON.parse(read('local', 'package.json')).dependencies['lousho']).toBe('file:./sdk-9.9.9.tgz');
+    expect(JSON.parse(read('local', 'package.json')).dependencies['@linuxdevil/lousho']).toBe('file:./sdk-9.9.9.tgz');
     expect(fs.existsSync(path.join(root, 'local', 'sdk-9.9.9.tgz'))).toBe(true);
     // The vendored tarball is a local build, not source: it is git-ignored.
     expect(read('local', '.gitignore')).toMatch(/^sdk-9\.9\.9\.tgz$/m);
diff --git a/src/cli/init/__snapshots__/templates.test.ts.snap b/src/cli/init/__snapshots__/templates.test.ts.snap
index 7e54dddf3..94dd54122 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 CreateAgentConfig, type LLMProvider } from 'lousho';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -38,7 +38,7 @@ export function buildAgent(provider?: LLMProvider) {
 `;
 
 exports[`renderProject > snapshot: anthropic / telegram agent.ts 1`] = `
-"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from 'lousho';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -82,7 +82,7 @@ export function buildAgent(provider?: LLMProvider) {
 `;
 
 exports[`renderProject > snapshot: anthropic / tools agent.ts 1`] = `
-"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from 'lousho';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -135,7 +135,7 @@ export function buildAgent(provider?: LLMProvider) {
 `;
 
 exports[`renderProject > snapshot: google / minimal agent.ts 1`] = `
-"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from 'lousho';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -172,7 +172,7 @@ export function buildAgent(provider?: LLMProvider) {
 `;
 
 exports[`renderProject > snapshot: google / telegram agent.ts 1`] = `
-"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from 'lousho';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -216,7 +216,7 @@ export function buildAgent(provider?: LLMProvider) {
 `;
 
 exports[`renderProject > snapshot: google / tools agent.ts 1`] = `
-"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from 'lousho';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -284,8 +284,8 @@ exports[`renderProject > snapshot: minimal package.json 1`] = `
   },
   "dependencies": {
     "@ai-sdk/openai": "^4.0.0",
+    "@linuxdevil/lousho": "^1.0.0-alpha.8",
     "ai": "^7.0.0",
-    "lousho": "^1.0.0-alpha.8",
     "zod": "^3.25.76"
   },
   "devDependencies": {
@@ -304,7 +304,7 @@ exports[`renderProject > snapshot: minimal package.json 1`] = `
 `;
 
 exports[`renderProject > snapshot: ollama / minimal agent.ts 1`] = `
-"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from 'lousho';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -341,7 +341,7 @@ export function buildAgent(provider?: LLMProvider) {
 `;
 
 exports[`renderProject > snapshot: ollama / telegram agent.ts 1`] = `
-"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from 'lousho';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -385,7 +385,7 @@ export function buildAgent(provider?: LLMProvider) {
 `;
 
 exports[`renderProject > snapshot: ollama / tools agent.ts 1`] = `
-"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from 'lousho';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -438,7 +438,7 @@ export function buildAgent(provider?: LLMProvider) {
 `;
 
 exports[`renderProject > snapshot: openai / minimal agent.ts 1`] = `
-"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from 'lousho';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -475,7 +475,7 @@ export function buildAgent(provider?: LLMProvider) {
 `;
 
 exports[`renderProject > snapshot: openai / telegram agent.ts 1`] = `
-"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from 'lousho';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -519,7 +519,7 @@ export function buildAgent(provider?: LLMProvider) {
 `;
 
 exports[`renderProject > snapshot: openai / tools agent.ts 1`] = `
-"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from 'lousho';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -572,7 +572,7 @@ export function buildAgent(provider?: LLMProvider) {
 `;
 
 exports[`renderProject > snapshot: openrouter / minimal agent.ts 1`] = `
-"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from 'lousho';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -609,7 +609,7 @@ export function buildAgent(provider?: LLMProvider) {
 `;
 
 exports[`renderProject > snapshot: openrouter / telegram agent.ts 1`] = `
-"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from 'lousho';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -653,7 +653,7 @@ export function buildAgent(provider?: LLMProvider) {
 `;
 
 exports[`renderProject > snapshot: openrouter / tools agent.ts 1`] = `
-"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from 'lousho';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -706,7 +706,7 @@ export function buildAgent(provider?: LLMProvider) {
 `;
 
 exports[`renderProject > snapshot: pi / minimal agent.ts 1`] = `
-"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from 'lousho';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -743,7 +743,7 @@ export function buildAgent(provider?: LLMProvider) {
 `;
 
 exports[`renderProject > snapshot: pi / telegram agent.ts 1`] = `
-"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from 'lousho';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -787,7 +787,7 @@ export function buildAgent(provider?: LLMProvider) {
 `;
 
 exports[`renderProject > snapshot: pi / tools agent.ts 1`] = `
-"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from 'lousho';
+"import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 /** An example tool: the model calls it when it needs the current date or time. */
@@ -857,8 +857,8 @@ exports[`renderProject > snapshot: telegram package.json 1`] = `
   },
   "dependencies": {
     "@ai-sdk/openai": "^4.0.0",
+    "@linuxdevil/lousho": "^1.0.0-alpha.8",
     "ai": "^7.0.0",
-    "lousho": "^1.0.0-alpha.8",
     "zod": "^3.25.76"
   },
   "devDependencies": {
@@ -892,8 +892,8 @@ exports[`renderProject > snapshot: tools package.json 1`] = `
   },
   "dependencies": {
     "@ai-sdk/openai": "^4.0.0",
+    "@linuxdevil/lousho": "^1.0.0-alpha.8",
     "ai": "^7.0.0",
-    "lousho": "^1.0.0-alpha.8",
     "zod": "^3.25.76"
   },
   "devDependencies": {
@@ -926,8 +926,8 @@ exports[`renderProject > snapshot: yaml package.json 1`] = `
   },
   "dependencies": {
     "@ai-sdk/openai": "^4.0.0",
+    "@linuxdevil/lousho": "^1.0.0-alpha.8",
     "ai": "^7.0.0",
-    "lousho": "^1.0.0-alpha.8",
     "zod": "^3.25.76"
   },
   "devDependencies": {
diff --git a/src/cli/init/projectConfig.ts b/src/cli/init/projectConfig.ts
index bd420eabd..acda132fe 100644
--- a/src/cli/init/projectConfig.ts
+++ b/src/cli/init/projectConfig.ts
@@ -24,7 +24,7 @@ export interface ProjectConfig {
   provider: string;
   template: Template;
   packageManager: PackageManager;
-  /** `dependencies["lousho"]`: a range, or `file:./<tarball>`. */
+  /** `dependencies["@linuxdevil/lousho"]`: a range, or `file:./<tarball>`. */
   sdkDependency: string;
   sdk: SdkManifest;
   /** Telegram template only: --bot-* / --persona flag values baked into .env and the persona. */
diff --git a/src/cli/init/sdkDependency.ts b/src/cli/init/sdkDependency.ts
index 635982498..c9feaf4e9 100644
--- a/src/cli/init/sdkDependency.ts
+++ b/src/cli/init/sdkDependency.ts
@@ -1,5 +1,5 @@
 /**
- * How the generated project depends on `lousho`.
+ * How the generated project depends on `@linuxdevil/lousho`.
  *
  * Normally a semver range of the version that generated it. For local
  * development (and the scaffolder's own e2e test) `--sdk-path` /
@@ -51,7 +51,7 @@ function vendorSdk(sdkPath: string, projectDir: string): string {
 }
 
 /**
- * The `dependencies["lousho"]` value for the generated
+ * The `dependencies["@linuxdevil/lousho"]` value for the generated
  * project: a caret range of `version` (e.g. `^1.2.3`), or `file:./<tarball>` when `sdkPath` is given
  * (which also writes the tarball into `projectDir`).
  */
diff --git a/src/cli/init/telegramTemplate.ts b/src/cli/init/telegramTemplate.ts
index fafb7f880..5ebb27cee 100644
--- a/src/cli/init/telegramTemplate.ts
+++ b/src/cli/init/telegramTemplate.ts
@@ -224,7 +224,7 @@ const BRIDGE_TS = [
   ' */',
   "import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';",
   "import { basename, dirname, join } from 'node:path';",
-  "import type { Agent, Session } from 'lousho';",
+  "import type { Agent, Session } from '@linuxdevil/lousho';",
   'import {',
   '  answerCallbackQuery,',
   '  downloadFile,',
@@ -616,7 +616,7 @@ function agentSource(config: ProjectConfig, bot: BotOptions): string {
   const info = providerInfo(config.provider);
   const persona = bot.persona?.trim() || 'a helpful assistant that lives on Telegram';
   const lines = [
-    "import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from 'lousho';",
+    "import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@linuxdevil/lousho';",
     "import { z } from 'zod';",
     '',
     '/** An example tool: the model calls it when it needs the current date or time. */',
@@ -663,7 +663,7 @@ function agentSource(config: ProjectConfig, bot: BotOptions): string {
 
 function testSource(): string {
   return `import { describe, expect, it } from 'vitest';
-import { mockModel } from 'lousho/testing';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { buildAgent } from './agent.js';
 
 // mockModel scripts the model turn by turn: no network and no API key needed.
diff --git a/src/cli/init/templates.test.ts b/src/cli/init/templates.test.ts
index 117bb2323..91bf16307 100644
--- a/src/cli/init/templates.test.ts
+++ b/src/cli/init/templates.test.ts
@@ -73,7 +73,7 @@ describe('renderProject', () => {
     expect(pkg).toMatchObject({ name: 'demo-agent', type: 'module', private: true });
     expect(Object.keys(pkg.scripts)).toEqual(expect.arrayContaining(['dev', 'test', 'doctor']));
     expect(pkg.scripts.doctor).toMatch(/^lousho doctor/);
-    expect(pkg.dependencies['lousho']).toBe('^1.0.0-alpha.8');
+    expect(pkg.dependencies['@linuxdevil/lousho']).toBe('^1.0.0-alpha.8');
     expect(pkg.dependencies).toMatchObject({ ai: SCAFFOLD_PAIRINGS[provider]!.ai, zod: provider === 'ollama' ? '^4.0.0' : '^3.25.76' });
 
     expect(JSON.parse(files['tsconfig.json']!).compilerOptions).toMatchObject({ strict: true, module: 'NodeNext' });
@@ -98,7 +98,7 @@ describe('renderProject', () => {
     (provider, template) => {
       const files = renderProject(config(provider, template));
       expect(files['src/agent.ts']).toContain(
-        "import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from 'lousho';"
+        "import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@linuxdevil/lousho';"
       );
       // The default export is what `lousho dev|chat|mcp|acp|build src/agent.ts` load.
       expect(files['src/agent.ts']).toContain('export default config;');
@@ -107,7 +107,7 @@ describe('renderProject', () => {
       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/testing';");
+      expect(files['src/agent.test.ts']).toContain("import { mockModel } from '@linuxdevil/lousho/testing';");
       expect(files['agent.yaml']).toBeUndefined();
       expect(JSON.parse(files['package.json']!).scripts.dev).toContain('src/index.ts');
     }
diff --git a/src/cli/init/templates.ts b/src/cli/init/templates.ts
index a70342ffc..fa93cfd11 100644
--- a/src/cli/init/templates.ts
+++ b/src/cli/init/templates.ts
@@ -69,7 +69,7 @@ function packageJson(config: ProjectConfig): string {
     type: 'module',
     scripts: scripts(config),
     dependencies: sortKeys({
-      'lousho': config.sdkDependency,
+      '@linuxdevil/lousho': config.sdkDependency,
       zod: zodRange(peers.zod, config.provider),
       ...aiPackages(config.provider),
     }),
@@ -142,7 +142,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 CreateAgentConfig, type LLMProvider } from 'lousho';
+  return `import { createAgent, defineTool, type CreateAgentConfig, type LLMProvider } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 ${TIME_TOOL}${extra}
@@ -174,7 +174,7 @@ function indexSource(): string {
   return `import { readFileSync } from 'node:fs';
 import { createInterface } from 'node:readline/promises';
 import { parseEnv } from 'node:util';
-import { SDKError } from 'lousho';
+import { SDKError } from '@linuxdevil/lousho';
 import { buildAgent } from './agent.js';
 
 // Load .env when there is one; variables already set in the environment win. The byte order mark
@@ -235,7 +235,7 @@ process.exit(0);
 
 function testSource(): string {
   return `import { describe, expect, it } from 'vitest';
-import { mockModel } from 'lousho/testing';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { buildAgent } from './agent.js';
 
 // mockModel scripts the model turn by turn: no network and no API key needed.
@@ -268,7 +268,7 @@ describe('agent', () => {
 function yamlTestSource(config: ProjectConfig): string {
   return `import { fileURLToPath } from 'node:url';
 import { describe, expect, it } from 'vitest';
-import { loadSpec } from 'lousho';
+import { loadSpec } from '@linuxdevil/lousho';
 
 describe('agent.yaml', () => {
   it('is a valid agent spec', () => {
@@ -358,7 +358,7 @@ function agentsMd(config: ProjectConfig): string {
 - Give any tool with side effects \`needsApproval: true\` (or a predicate) so a human approves the call.
 - The model string is \`provider/model\`, here \`${config.provider}/${info.defaultModel}\`.
 - Replies are capped by \`modelSettings.maxTokens\` (4096) in \`src/agent.ts\`; raise it for longer answers.
-- Test offline with \`mockModel([...])\` from \`lousho/testing\`; never call a live model in tests.`;
+- Test offline with \`mockModel([...])\` from \`@linuxdevil/lousho/testing\`; never call a live model in tests.`;
   return `# ${config.name}
 
 An agent built with \`lousho\` (provider: ${config.provider}). Read this before changing code.
diff --git a/src/cli/studio.test.ts b/src/cli/studio.test.ts
index bc5e4632f..75e43c3bd 100644
--- a/src/cli/studio.test.ts
+++ b/src/cli/studio.test.ts
@@ -1,163 +1,236 @@
 import { describe, it, expect, vi } from 'vitest';
+import { EventEmitter } from 'node:events';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { runStudio, startStudio, resolveAgentForgeDir, studioUrl } from './studio';
+import type { ChildProcess } from 'node:child_process';
+import { findStudio, runStudio, startStudio, STUDIO_MISSING, STUDIO_PACKAGE, studioUrl } from './studio';
 
 const tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'lousho-studio-test-'));
 
-function makeApp(root: string, entry?: string): string {
+/** A checkout's apps/agent-forge: package.json naming Studio, optional cli.cjs/server source. */
+function makeCheckout(root: string, opts: { cli?: boolean; serverSource?: boolean } = {}): string {
   const appDir = path.join(root, 'apps', 'agent-forge');
   fs.mkdirSync(path.join(appDir, 'dist-server'), { recursive: true });
-  fs.writeFileSync(path.join(appDir, 'package.json'), '{}');
-  if (entry !== undefined) fs.writeFileSync(path.join(appDir, 'dist-server', 'index.cjs'), entry);
+  fs.writeFileSync(path.join(appDir, 'package.json'), JSON.stringify({ name: STUDIO_PACKAGE }));
+  if (opts.cli) fs.writeFileSync(path.join(appDir, 'dist-server', 'cli.cjs'), 'process.exit(0);');
+  if (opts.serverSource) {
+    fs.mkdirSync(path.join(appDir, 'server'), { recursive: true });
+    fs.writeFileSync(path.join(appDir, 'server', 'index.ts'), 'export {};');
+  }
   return appDir;
 }
 
-function waitForFile(file: string): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const deadline = Date.now() + 10_000;
-    const tick = (): void => {
-      if (fs.existsSync(file) && fs.readFileSync(file, 'utf8')) resolve(fs.readFileSync(file, 'utf8'));
-      else if (Date.now() > deadline) reject(new Error('timed out waiting for ' + file));
-      else setTimeout(tick, 25);
-    };
-    tick();
+/** An installed @linuxdevil/studio under <root>/node_modules. */
+function makeInstalled(root: string): { packageDir: string; cliPath: string } {
+  const packageDir = path.join(root, 'node_modules', ...STUDIO_PACKAGE.split('/'));
+  fs.mkdirSync(path.join(packageDir, 'dist-server'), { recursive: true });
+  fs.writeFileSync(path.join(packageDir, 'package.json'), JSON.stringify({ name: STUDIO_PACKAGE, version: '0.0.0' }));
+  const cliPath = path.join(packageDir, 'dist-server', 'cli.cjs');
+  fs.writeFileSync(cliPath, 'process.exit(0);');
+  return { packageDir, cliPath };
+}
+
+/** A spawn stand-in: records calls, returns a killable EventEmitter child. */
+function fakeSpawn() {
+  const calls: { cmd: unknown; args: unknown; opts: unknown }[] = [];
+  const fn = vi.fn((cmd: unknown, args: unknown, opts: unknown) => {
+    calls.push({ cmd, args, opts });
+    const child = new EventEmitter() as unknown as ChildProcess;
+    child.kill = vi.fn(() => true);
+    return child;
   });
+  return { fn: fn as unknown as typeof import('node:child_process').spawn, calls };
 }
 
-describe('startStudio', () => {
-  it('throws a clear error when apps/agent-forge is not found under repoRoot', () => {
-    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'lousho-studio-test-'));
-    expect(() => startStudio({ repoRoot, packageRoot: tmp() })).toThrow(/could not find apps\/agent-forge/);
+describe('findStudio', () => {
+  it('returns the checkout when <cwd>/apps/agent-forge is named @linuxdevil/studio', () => {
+    const cwd = tmp();
+    const appDir = makeCheckout(cwd);
+    expect(findStudio(cwd, { packageRoot: tmp(), globalRoot: () => undefined })).toEqual({ kind: 'checkout', appDir });
   });
 
-  it("--prod throws a clear, build-pointing error when apps/agent-forge/dist-server is missing", () => {
-    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'lousho-studio-test-'));
-    fs.mkdirSync(path.join(repoRoot, 'apps', 'agent-forge'), { recursive: true });
-    fs.writeFileSync(path.join(repoRoot, 'apps', 'agent-forge', 'package.json'), '{}');
-    expect(() => startStudio({ repoRoot, mode: 'prod' })).toThrow(/build:studio/);
+  it('ignores an apps/agent-forge whose package.json has another name', () => {
+    const cwd = tmp();
+    const appDir = path.join(cwd, 'apps', 'agent-forge');
+    fs.mkdirSync(appDir, { recursive: true });
+    fs.writeFileSync(path.join(appDir, 'package.json'), '{}');
+    expect(findStudio(cwd, { packageRoot: tmp(), globalRoot: () => undefined })).toBeUndefined();
   });
 
-  it("--dev throws a clear error when apps/agent-forge/server source is missing", () => {
-    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'lousho-studio-test-'));
-    fs.mkdirSync(path.join(repoRoot, 'apps', 'agent-forge'), { recursive: true });
-    fs.writeFileSync(path.join(repoRoot, 'apps', 'agent-forge', 'package.json'), '{}');
-    expect(() => startStudio({ repoRoot, mode: 'dev' })).toThrow(/dev mode/);
+  it('resolves an installed Studio from the cwd node_modules', () => {
+    const cwd = tmp();
+    const { packageDir, cliPath } = makeInstalled(cwd);
+    expect(findStudio(cwd, { packageRoot: tmp(), globalRoot: () => undefined })).toEqual({
+      kind: 'installed',
+      cliPath,
+      packageDir,
+    });
   });
 
-  it("mode: 'auto' on a package packed without Agent Forge says so, not 'monorepo only' (a local npm pack)", () => {
-    const packageRoot = tmp();
-    fs.mkdirSync(path.join(packageRoot, 'apps', 'agent-forge'), { recursive: true });
-    fs.writeFileSync(path.join(packageRoot, 'apps', 'agent-forge', 'package.json'), '{}');
-    expect(() => startStudio({ repoRoot: tmp(), packageRoot })).toThrow(/has no Agent Forge build .*npm run build:studio' before 'npm pack'/);
+  it('falls through to the SDK package root, then the global root', () => {
+    const cwd = tmp();
+    const sdkRoot = tmp();
+    const { packageDir, cliPath } = makeInstalled(sdkRoot);
+    const hit = findStudio(cwd, { packageRoot: sdkRoot, globalRoot: () => tmp() });
+    expect(hit).toEqual({ kind: 'installed', cliPath, packageDir });
+
+    const globalRoot = tmp();
+    // `npm root -g` points at the global node_modules: <root>/@linuxdevil/studio.
+    const globalPackageDir = path.join(globalRoot, ...STUDIO_PACKAGE.split('/'));
+    fs.mkdirSync(path.join(globalPackageDir, 'dist-server'), { recursive: true });
+    fs.writeFileSync(path.join(globalPackageDir, 'package.json'), JSON.stringify({ name: STUDIO_PACKAGE }));
+    fs.writeFileSync(path.join(globalPackageDir, 'dist-server', 'cli.cjs'), 'process.exit(0);');
+    const globalHit = findStudio(cwd, { packageRoot: tmp(), globalRoot: () => globalRoot });
+    expect(globalHit).toEqual({
+      kind: 'installed',
+      cliPath: path.join(globalPackageDir, 'dist-server', 'cli.cjs'),
+      packageDir: globalPackageDir,
+    });
   });
 
-  it("mode: 'auto' resolves to prod when apps/agent-forge/dist-server/index.cjs has been built", () => {
-    // Exercised indirectly: 'auto' with a built dist-server/index.cjs present
-    // should hit the *prod* code path, which spawns `node <entry>` - proven
-    // here by asserting it does NOT throw the dev-mode-only source error,
-    // and instead returns a handle with mode: 'prod' (no viteProcess).
-    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'lousho-studio-test-'));
-    const appDir = path.join(repoRoot, 'apps', 'agent-forge');
-    fs.mkdirSync(path.join(appDir, 'dist-server'), { recursive: true });
-    fs.writeFileSync(path.join(appDir, 'package.json'), '{}');
-    // A trivial entry that exits immediately so the child process doesn't
-    // linger past the test.
-    fs.writeFileSync(path.join(appDir, 'dist-server', 'index.cjs'), 'process.exit(0);');
+  it('skips an installed package whose dist-server/cli.cjs is missing', () => {
+    const cwd = tmp();
+    const packageDir = path.join(cwd, 'node_modules', ...STUDIO_PACKAGE.split('/'));
+    fs.mkdirSync(packageDir, { recursive: true });
+    fs.writeFileSync(path.join(packageDir, 'package.json'), JSON.stringify({ name: STUDIO_PACKAGE }));
+    expect(findStudio(cwd, { packageRoot: tmp(), globalRoot: () => undefined })).toBeUndefined();
+  });
 
-    const handle = startStudio({ repoRoot, apiPort: 0 });
+  it('returns undefined when nothing is found', () => {
+    expect(findStudio(tmp(), { packageRoot: tmp(), globalRoot: () => undefined })).toBeUndefined();
+  });
+});
+
+describe('startStudio', () => {
+  it('throws STUDIO_MISSING when no Studio exists', () => {
+    expect(() => startStudio({ repoRoot: tmp(), packageRoot: tmp(), globalRoot: () => undefined })).toThrow(STUDIO_MISSING);
+  });
+
+  it('launches an installed Studio as cli.cjs --workspace <cwd> --port --host', () => {
+    const cwd = tmp();
+    const { cliPath } = makeInstalled(cwd);
+    const { fn, calls } = fakeSpawn();
+    const handle = startStudio({ repoRoot: cwd, apiPort: 4750, apiHost: '127.0.0.1', packageRoot: tmp(), globalRoot: () => undefined, spawnFn: fn });
     try {
-      expect(handle.mode).toBe('prod');
-      expect(handle.viteProcess).toBeUndefined();
+      expect(handle.mode).toBe('installed');
+      expect(calls).toHaveLength(1);
+      expect(calls[0].cmd).toBe(process.execPath);
+      expect(calls[0].args).toEqual([cliPath, '--workspace', cwd, '--port', '4750', '--host', '127.0.0.1']);
+      expect(calls[0].opts).toEqual({ stdio: 'inherit' });
     } finally {
       handle.stop();
     }
   });
 
-  it('uses the installed package copy when repoRoot has no apps/agent-forge', () => {
+  it('refuses --prod/--dev with an installed target (usage error, exit 2)', async () => {
+    const cwd = tmp();
+    makeInstalled(cwd);
+    const err = vi.spyOn(console, 'error').mockImplementation(() => {});
+    try {
+      expect(await runStudioWith(['--dev'], cwd)).toBe(2);
+      expect(String(err.mock.calls[0]?.[0])).toMatch(/only apply inside the SDK repository/);
+    } finally {
+      err.mockRestore();
+    }
+  });
+
+  it("checkout 'auto' resolves to prod when dist-server/cli.cjs is built and passes --workspace to it", () => {
     const repoRoot = tmp();
-    const packageRoot = tmp();
-    const appDir = makeApp(packageRoot, 'process.exit(0);');
-    expect(resolveAgentForgeDir(repoRoot, packageRoot)).toBe(appDir);
-    const handle = startStudio({ repoRoot, packageRoot, apiPort: 0 });
+    const appDir = makeCheckout(repoRoot, { cli: true });
+    const { fn, calls } = fakeSpawn();
+    const handle = startStudio({ repoRoot, apiPort: 0, packageRoot: tmp(), globalRoot: () => undefined, spawnFn: fn });
     try {
       expect(handle.mode).toBe('prod');
-      expect(handle.apiProcess.spawnargs[1]).toBe(path.join(appDir, 'dist-server', 'index.cjs'));
+      expect(handle.viteProcess).toBeUndefined();
+      expect(calls[0].args).toEqual([
+        path.join(appDir, 'dist-server', 'cli.cjs'),
+        '--workspace',
+        repoRoot,
+        '--port',
+        '0',
+        '--host',
+        '127.0.0.1',
+      ]);
     } finally {
       handle.stop();
     }
   });
 
-  it('prefers the repoRoot copy when both exist', () => {
+  it("checkout 'auto' resolves to dev when only the server source exists", () => {
     const repoRoot = tmp();
-    const packageRoot = tmp();
-    const repoApp = makeApp(repoRoot, 'process.exit(0);');
-    makeApp(packageRoot, 'process.exit(0);');
-    expect(resolveAgentForgeDir(repoRoot, packageRoot)).toBe(repoApp);
-    const handle = startStudio({ repoRoot, packageRoot, apiPort: 0 });
+    makeCheckout(repoRoot, { serverSource: true });
+    const { fn, calls } = fakeSpawn();
+    const handle = startStudio({ repoRoot, apiPort: 0, packageRoot: tmp(), globalRoot: () => undefined, spawnFn: fn });
     try {
-      expect(handle.apiProcess.spawnargs[1]).toBe(path.join(repoApp, 'dist-server', 'index.cjs'));
+      expect(handle.mode).toBe('dev');
+      expect(handle.viteProcess).toBeDefined();
+      expect(handle.token).toMatch(/^[A-Za-z0-9_-]{32}$/);
+      expect(calls).toHaveLength(2);
+      const apiEnv = (calls[0].opts as { env: Record<string, string> }).env;
+      expect(apiEnv.BASE_DIR).toBe(repoRoot);
+      expect(apiEnv.LOUSHO_STUDIO_TOKEN).toBe(handle.token);
+      expect(apiEnv.NO_STATIC).toBe('1');
     } finally {
       handle.stop();
     }
   });
 
-  it('--dev against a package copy without server source gives the dev-mode message', () => {
-    const packageRoot = tmp();
-    makeApp(packageRoot, 'process.exit(0);');
-    expect(() => startStudio({ repoRoot: tmp(), packageRoot, mode: 'dev' })).toThrow(/dev mode/);
+  it("--prod throws a clear, build-pointing error when dist-server/cli.cjs is missing", () => {
+    const repoRoot = tmp();
+    makeCheckout(repoRoot);
+    expect(() => startStudio({ repoRoot, mode: 'prod', packageRoot: tmp(), globalRoot: () => undefined })).toThrow(/build:studio/);
   });
 
-  it('keeps the repoRoot as BASE_DIR for the child, also with the package copy', async () => {
+  it("'auto' with neither build nor source says to run build:studio", () => {
     const repoRoot = tmp();
-    const packageRoot = tmp();
-    const out = path.join(tmp(), 'base-dir.txt');
-    makeApp(packageRoot, `require('node:fs').writeFileSync(${JSON.stringify(out)}, process.env.BASE_DIR);`);
-    const handle = startStudio({ repoRoot, packageRoot, apiPort: 0 });
-    try {
-      expect(await waitForFile(out)).toBe(repoRoot);
-    } finally {
-      handle.stop();
-    }
+    makeCheckout(repoRoot);
+    expect(() => startStudio({ repoRoot, packageRoot: tmp(), globalRoot: () => undefined })).toThrow(/build:studio/);
   });
 
-  it('mints a per-launch token, hands it to the child and puts it in the printed URL', async () => {
+  it("--dev throws a clear error when the server source is missing", () => {
     const repoRoot = tmp();
-    const packageRoot = tmp();
-    const out = path.join(tmp(), 'token.txt');
-    makeApp(packageRoot, `require('node:fs').writeFileSync(${JSON.stringify(out)}, process.env.LOUSHO_STUDIO_TOKEN);`);
-    const handle = startStudio({ repoRoot, packageRoot, apiPort: 0 });
-    try {
-      expect(handle.token).toMatch(/^[A-Za-z0-9_-]{32}$/);
-      expect(await waitForFile(out)).toBe(handle.token);
-    } finally {
-      handle.stop();
-    }
-    expect(studioUrl('0.0.0.0', 4750, 'abc')).toBe('http://127.0.0.1:4750/?token=abc');
-    expect(studioUrl('127.0.0.1', 5000, 'a+b')).toBe('http://127.0.0.1:5000/?token=a%2Bb');
+    makeCheckout(repoRoot, { cli: true });
+    expect(() => startStudio({ repoRoot, mode: 'dev', packageRoot: tmp(), globalRoot: () => undefined })).toThrow(/dev mode/);
   });
 
-  // Actually spawning the real API server + Vite dev server child processes
-  // (npm run server:dev / npm run dev in apps/agent-forge) is exercised
-  // manually/in the real monorepo rather than here: it needs a full
-  // `npm install` in apps/agent-forge and binds real ports, which would
-  // make this suite slow and environment-dependent. The server's own
-  // behavior (routes, run/stop/approve semantics) is covered directly by
-  // apps/agent-forge/server/__tests__/*.test.ts instead - this file only
-  // covers startStudio()'s own pure logic (the apps/agent-forge lookup and
-  // dev/prod/auto mode resolution).
+  it('checkout wins over an installed copy in the same directory', () => {
+    const cwd = tmp();
+    makeCheckout(cwd);
+    makeInstalled(cwd);
+    const target = findStudio(cwd, { packageRoot: tmp(), globalRoot: () => undefined });
+    expect(target?.kind).toBe('checkout');
+  });
 });
 
+/** runStudio with process.cwd() pointed at `cwd`. */
+async function runStudioWith(args: string[], cwd: string): Promise<number> {
+  const spy = vi.spyOn(process, 'cwd').mockReturnValue(cwd);
+  try {
+    return await runStudio(args);
+  } finally {
+    spy.mockRestore();
+  }
+}
+
 describe('lousho studio --help', () => {
-  it('describes every flag', async () => {
+  it('describes every flag and the separate-install story', 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`));
+      for (const flag of ['--port', '--host', '--prod', '--dev']) expect(help).toMatch(new RegExp(`\\n  ${flag.replace('-', '\\-')}\\b[^\\n]* {2,}\\S`));
+      expect(help).toContain(STUDIO_PACKAGE);
+      expect(help).toContain('separate package');
     } finally {
       log.mockRestore();
     }
   });
 });
+
+describe('studioUrl', () => {
+  it('formats host, port and token', () => {
+    expect(studioUrl('0.0.0.0', 4750, 'abc')).toBe('http://127.0.0.1:4750/?token=abc');
+    expect(studioUrl('127.0.0.1', 5000, 'a+b')).toBe('http://127.0.0.1:5000/?token=a%2Bb');
+  });
+});
diff --git a/src/cli/studio.ts b/src/cli/studio.ts
index 287e6a89e..33d05f082 100644
--- a/src/cli/studio.ts
+++ b/src/cli/studio.ts
@@ -1,83 +1,86 @@
 /**
- * `lousho studio` - launches Agent Forge, the visual dashboard for building,
+ * `lousho studio` - opens Lousho Studio, the visual dashboard for building,
  * running and debugging agents built with this SDK.
  *
- * Two modes:
+ * Studio is a separate package (`@linuxdevil/studio`, W13a/W13b): the SDK
+ * tarball no longer ships `apps/agent-forge`, so this command resolves a
+ * Studio install and launches its CLI (`dist-server/cli.cjs`) as a child
+ * process. Two kinds of target:
  *
- *   - **prod** (single process, single port): the runtime control
- *     server (`apps/agent-forge/server`, bundled to plain JS by
- *     `apps/agent-forge/server/tsup.config.ts` into `dist-server/index.cjs`)
- *     serves both its own REST/WS API *and* the pre-built client
- *     (`apps/agent-forge/dist`, `vite build`'s output) as static files - see
- *     `createApp`'s `staticDir` option in `apps/agent-forge/server/app.ts`.
- *     No Vite process, no TypeScript loader (`tsx`), no dev dependencies:
- *     this is what actually ships in the published npm package and what
- *     `lousho studio` runs by default once `apps/agent-forge` has been
- *     built (`build:studio` - see the root `package.json`'s
- *     `prepublishOnly`, which always runs it before `npm publish`).
+ *   - **checkout**: `<cwd>/apps/agent-forge` whose package.json is named
+ *     `@linuxdevil/studio` - i.e. this SDK repository. Keeps the
+ *     contributor modes:
  *
- *   - **dev** (two sibling processes, original shape): the API
- *     server run via `tsx` straight off its TypeScript source, plus
- *     `apps/agent-forge`'s own Vite dev server (HMR) proxying `/agents/**`
- *     to it. Only usable from inside a source checkout that has
- *     `apps/agent-forge/src`/`server` and its devDependencies installed
- *     (this monorepo, or a project vendoring `apps/agent-forge` the same
- *     way) - not something the published package can rely on, which is
- *     exactly why prod mode above exists.
+ *       - **prod**: `dist-server/cli.cjs --workspace <cwd> --port <p>
+ *         --host <h>` - one process serving the built UI and API (the
+ *         Studio CLI mints and prints its own per-launch token).
+ *       - **dev**: the API server via `tsx` plus the Vite dev server
+ *         (HMR), exactly as before; only meaningful with the app's
+ *         devDependencies installed.
  *
- * Mode selection: `--prod` / `--dev` force one or the other (and error
- * clearly if what they need isn't present); with neither flag, `lousho
- * studio` auto-detects by checking whether `apps/agent-forge/dist-server`
- * has already been built - present (the normal case for anyone who `npm
- * install`ed the published package) means prod, absent (the normal case
- * mid-development in this monorepo, before running `build:studio`) means
- * dev. This means the *same* `lousho studio` command is the right one to
- * document for both audiences; only what's on disk differs.
+ *   - **installed**: `@linuxdevil/studio` resolved from the current
+ *     directory's node_modules, then next to the SDK package, then npm's
+ *     global root. Launched the same way as prod (`cli.cjs` with
+ *     `--workspace <cwd>`); `--prod`/`--dev` are a usage error there.
  *
- * Both modes are still started as child process(es) rather than imported
- * in-process, deliberately: `apps/agent-forge` is a separate workspace
- * package (its own `package.json`, `"type": "module"`, its own dependency
- * graph) - importing its code as a module from this SDK's own CLI bundle
- * would mean bundling all of `apps/agent-forge`'s dependencies into the
- * SDK's own `dist/`. Spawning `node dist-server/index.cjs` (prod) or two
- * ordinary `npm`-script child processes (dev) keeps `apps/agent-forge/**`
- * genuinely optional for every other SDK consumer, and says so clearly if
- * the app directory (or its build output, in `--prod`) isn't found.
+ * With no Studio anywhere the command prints STUDIO_MISSING and exits 1.
+ * Spawning a child process (rather than importing the app) is deliberate:
+ * Studio's dependency graph stays out of the SDK's own CLI bundle.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { spawn, type ChildProcess } from 'node:child_process';
+import { spawn, spawnSync, type ChildProcess } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
+import { createRequire } from 'node:module';
 import { exitCodeFor, parseCommand, portValue, stringValue, usageError, type CommandSpec } from './args';
 import { ConfigurationError } from '../execution/errors';
 import { findSdkRoot } from '../deploy/bundle';
 
+/** The published Studio package `lousho studio` looks for. */
+export const STUDIO_PACKAGE = '@linuxdevil/studio';
+/** Printed when no Studio checkout or install can be found. */
+export const STUDIO_MISSING = `Studio is a separate install: npx ${STUDIO_PACKAGE}`;
+
 export type StudioMode = 'auto' | 'dev' | 'prod';
 
+export type StudioTarget =
+  /** `<cwd>/apps/agent-forge` in the SDK repository. */
+  | { kind: 'checkout'; appDir: string }
+  /** An installed `@linuxdevil/studio` package. */
+  | { kind: 'installed'; cliPath: string; packageDir: string };
+
+export interface FindStudioOptions {
+  /** Root of the installed SDK package (step 3 of the search). Defaults to findSdkRoot(). */
+  packageRoot?: string;
+  /** npm's global root (`npm root -g`). Injectable for tests. */
+  globalRoot?: () => string | undefined;
+}
+
 export interface StudioOptions {
-  /** Repo root containing `apps/agent-forge`. Defaults to process.cwd(). */
+  /** Directory `lousho studio` was run from: the checkout lookup root and the installed `--workspace`. Default process.cwd(). */
   repoRoot?: string;
-  /** Port for the API server (env `PORT` for the child process). Default 4750. */
+  /** Port for the studio server. Default 4750. */
   apiPort?: number;
-  /** Host for the API server. Default 127.0.0.1. */
+  /** Host for the studio server. Default 127.0.0.1. */
   apiHost?: string;
   /**
-   * 'prod' | 'dev' force a mode (and throw if what it needs isn't present);
-   * 'auto' (default) picks 'prod' when `apps/agent-forge/dist-server` has
-   * been built, else 'dev'.
+   * 'prod' | 'dev' force a checkout mode (and throw if what they need isn't
+   * present); 'auto' (default) picks 'prod' when the checkout's
+   * `dist-server/cli.cjs` has been built, else 'dev'. With an installed
+   * target any explicit mode is a usage error.
    */
   mode?: StudioMode;
-  /**
-   * Root of the installed `lousho` package, whose own
-   * `apps/agent-forge` is used when `repoRoot` has none. Defaults to the
-   * package this CLI runs from; tests point it at a temporary directory.
-   */
+  /** Forwarded to {@link findStudio}. */
   packageRoot?: string;
+  /** Forwarded to {@link findStudio}. */
+  globalRoot?: () => string | undefined;
+  /** Test seam replacing `node:child_process`'s spawn for the launched Studio. */
+  spawnFn?: typeof spawn;
 }
 
 /**
- * Env var carrying the per-launch API token to the studio server
- * (and, in dev mode, to Vite's proxy). Mirrors `STUDIO_TOKEN_ENV` in
+ * Env var carrying the per-launch API token to the studio server in dev
+ * mode (and to Vite's proxy). Mirrors `STUDIO_TOKEN_ENV` in
  * `apps/agent-forge/server/auth.ts`.
  */
 const STUDIO_TOKEN_ENV = 'LOUSHO_STUDIO_TOKEN';
@@ -92,13 +95,17 @@ export function studioUrl(apiHost: string, apiPort: number, token: string): stri
 }
 
 export interface StudioHandle {
-  /** The per-launch token every API/WebSocket request must carry (it is in the printed URL). */
-  token: string;
-  /** The API server (prod: also serves the UI). Always present. */
+  /**
+   * The per-launch token every API/WebSocket request must carry. Only known
+   * in checkout dev mode - prod and installed launches let the Studio CLI
+   * mint and print its own.
+   */
+  token?: string;
+  /** The studio server process (dev mode: the API server; viteProcess is the UI). */
   apiProcess: ChildProcess;
-  /** The Vite dev server. Only present in dev mode. */
+  /** The Vite dev server. Only present in checkout dev mode. */
   viteProcess?: ChildProcess;
-  mode: 'dev' | 'prod';
+  mode: 'dev' | 'prod' | 'installed';
   stop: () => void;
 }
 
@@ -110,20 +117,97 @@ function resolveNpmCommand(): string {
   return process.platform === 'win32' ? 'npm.cmd' : 'npm';
 }
 
-function distServerEntry(appDir: string): string {
+function studioCliEntry(appDir: string): string {
   // `.cjs`, not `.js` - see `apps/agent-forge/server/tsup.config.ts`'s doc
   // comment for why the server is bundled to CommonJS.
-  return path.join(appDir, 'dist-server', 'index.cjs');
+  return path.join(appDir, 'dist-server', 'cli.cjs');
+}
+
+/** True when `dir/apps/agent-forge/package.json` names the Studio package (the SDK checkout). */
+function isStudioCheckout(dir: string): boolean {
+  const pkgPath = path.join(dir, 'apps', 'agent-forge', 'package.json');
+  if (!fs.existsSync(pkgPath)) return false;
+  try {
+    return JSON.parse(fs.readFileSync(pkgPath, 'utf8')).name === STUDIO_PACKAGE;
+  } catch {
+    return false;
+  }
+}
+
+/** Step 1: the SDK checkout's own `apps/agent-forge`. */
+function checkoutTarget(cwd: string): StudioTarget | undefined {
+  return isStudioCheckout(cwd) ? { kind: 'checkout', appDir: path.join(cwd, 'apps', 'agent-forge') } : undefined;
+}
+
+/** The directory holding `@linuxdevil/studio`'s package.json as resolved from `fromDir`, if any. */
+function resolveStudioPackageDir(fromDir: string): string | undefined {
+  try {
+    const require = createRequire(path.join(fromDir, 'package.json'));
+    return path.dirname(require.resolve(`${STUDIO_PACKAGE}/package.json`));
+  } catch {
+    return undefined;
+  }
+}
+
+/** An installed target, or undefined when `packageDir` lacks the runnable CLI. */
+function installedTarget(packageDir: string | undefined): StudioTarget | undefined {
+  if (!packageDir) return undefined;
+  const cliPath = path.join(packageDir, 'dist-server', 'cli.cjs');
+  if (!fs.existsSync(path.join(packageDir, 'package.json')) || !fs.existsSync(cliPath)) return undefined;
+  return { kind: 'installed', cliPath, packageDir };
+}
+
+/** Steps 2+3: Studio installed next to `cwd`, then next to the SDK package. */
+function localStudioTarget(cwd: string, packageRoot: string | undefined): StudioTarget | undefined {
+  for (const dir of [cwd, packageRoot]) {
+    const target = dir ? installedTarget(resolveStudioPackageDir(dir)) : undefined;
+    if (target) return target;
+  }
+  return undefined;
+}
+
+function sdkRootSafe(): string | undefined {
+  try {
+    return findSdkRoot();
+  } catch {
+    return undefined;
+  }
+}
+
+/** npm's global root (`npm root -g`); undefined when npm cannot answer. */
+function defaultGlobalRoot(): string | undefined {
+  const res = spawnSync(resolveNpmCommand(), ['root', '-g'], { encoding: 'utf8' });
+  const root = res.status === 0 ? res.stdout.trim() : '';
+  return root || undefined;
+}
+
+/** Step 4: Studio installed globally (`npm i -g @linuxdevil/studio`). */
+function globalStudioTarget(globalRoot: () => string | undefined): StudioTarget | undefined {
+  const root = globalRoot();
+  return root ? installedTarget(path.join(root, STUDIO_PACKAGE)) : undefined;
+}
+
+/**
+ * Finds Studio: the checkout copy under `cwd` first, then an installed
+ * `@linuxdevil/studio` resolved from `cwd`, from the SDK package, then npm's
+ * global root. Returns undefined when nothing runnable exists.
+ */
+export function findStudio(cwd: string, options: FindStudioOptions = {}): StudioTarget | undefined {
+  return (
+    checkoutTarget(cwd) ??
+    localStudioTarget(cwd, options.packageRoot ?? sdkRootSafe()) ??
+    globalStudioTarget(options.globalRoot ?? defaultGlobalRoot)
+  );
 }
 
 function resolveMode(appDir: string, requested: StudioMode): 'dev' | 'prod' {
   if (requested === 'dev' || requested === 'prod') return requested;
-  if (fs.existsSync(distServerEntry(appDir))) return 'prod';
+  if (fs.existsSync(studioCliEntry(appDir))) return 'prod';
   if (!fs.existsSync(path.join(appDir, 'server', 'index.ts'))) {
-    // Neither the build nor the source: a package packed without Agent Forge (a local `npm pack`).
+    // Neither the build nor the source: a checkout packed without a Studio build.
     throw new ConfigurationError(
-      `lousho studio: this copy of lousho has no Agent Forge build ('${distServerEntry(appDir)}' is missing). ` +
-        "It was packed without it: install a published release, or in the SDK checkout run 'npm run build:studio' before 'npm pack'.",
+      `lousho studio: this checkout's Studio has no build ('${studioCliEntry(appDir)}' is missing). ` +
+        "Run 'npm run build:studio' from the repo root first.",
       'studio'
     );
   }
@@ -131,45 +215,27 @@ function resolveMode(appDir: string, requested: StudioMode): 'dev' | 'prod' {
 }
 
 /**
- * Starts Agent Forge: in prod mode, a single API server process that
- * also serves the pre-built UI; in dev mode, that same API server (run from
- * TS source via `tsx`) alongside a sibling Vite dev server process. Both
- * inherit this process's stdio so their output (including each one's own
- * "listening on ..." line) shows up directly in the terminal that ran
- * `lousho studio`.
+ * Launches Studio: a checkout's prod/dev modes, or an installed package's
+ * `cli.cjs`. Child processes inherit this process's stdio so their output
+ * shows up in the terminal that ran `lousho studio`.
  */
 export function startStudio(options: StudioOptions = {}): StudioHandle {
   const { repoRoot = process.cwd(), apiPort = 4750, apiHost = '127.0.0.1', mode: requested = 'auto' } = options;
-  const packageRoot = options.packageRoot ?? findSdkRoot();
-  const appDir = resolveAgentForgeDir(repoRoot, packageRoot);
-
-  if (!appDir) throw agentForgeNotFound(repoRoot, packageRoot);
-
-  const mode = resolveMode(appDir, requested);
-  const token = randomBytes(24).toString('base64url');
-
-  if (mode === 'prod') return startProdStudio(appDir, repoRoot, apiPort, apiHost, token);
-  return startDevStudio(appDir, repoRoot, apiPort, apiHost, token);
-}
+  const spawnImpl = options.spawnFn ?? spawn;
+  const target = findStudio(repoRoot, options);
 
-/**
- * Finds the Agent Forge app: the project's own `apps/agent-forge` first (the
- * SDK repo, or a project that vendors the app), else the copy shipped inside
- * the installed package. Returns undefined when neither has a `package.json`.
- */
-export function resolveAgentForgeDir(repoRoot: string, packageRoot: string): string | undefined {
-  for (const root of [repoRoot, packageRoot]) {
-    const dir = path.join(root, 'apps', 'agent-forge');
-    if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
+  if (!target) throw new ConfigurationError(STUDIO_MISSING, 'studio');
+  if (target.kind === 'installed') {
+    if (requested !== 'auto') {
+      throw usageError(SPEC, '--prod and --dev only apply inside the SDK repository (apps/agent-forge).');
+    }
+    return startInstalledStudio(target, repoRoot, apiPort, apiHost, spawnImpl);
   }
-  return undefined;
-}
 
-function agentForgeNotFound(repoRoot: string, packageRoot: string): ConfigurationError {
-  return new ConfigurationError(
-    `lousho studio: could not find apps/agent-forge under '${repoRoot}' or in the installed package ` +
-      `('${path.join(packageRoot, 'apps', 'agent-forge')}'). Run this from the root of a repo that ` +
-      'includes the Agent Forge app, or reinstall lousho.', 'studio');
+  const mode = resolveMode(target.appDir, requested);
+  if (mode === 'prod') return startProdStudio(target.appDir, repoRoot, apiPort, apiHost, spawnImpl);
+  const token = randomBytes(24).toString('base64url');
+  return startDevStudio(target.appDir, repoRoot, apiPort, apiHost, token, spawnImpl);
 }
 
 /** Logs a child process's non-zero exit (a null code means it was killed by a signal). */
@@ -179,10 +245,28 @@ function reportUnexpectedExit(label: string, code: number | null): void {
   }
 }
 
+/** Launches an installed Studio: `cli.cjs --workspace <cwd> --port <p> --host <h>`. */
+function startInstalledStudio(
+  target: Extract<StudioTarget, { kind: 'installed' }>,
+  workspace: string,
+  apiPort: number,
+  apiHost: string,
+  spawnImpl: typeof spawn
+): StudioHandle {
+  console.log(`[lousho studio] starting ${STUDIO_PACKAGE} (port ${apiPort})...`);
+  const apiProcess = spawnImpl(
+    process.execPath,
+    [target.cliPath, '--workspace', workspace, '--port', String(apiPort), '--host', apiHost],
+    { stdio: 'inherit' }
+  );
+  apiProcess.on('exit', (code) => reportUnexpectedExit('Studio', code));
+  return { apiProcess, mode: 'installed', stop: () => apiProcess.kill() };
+}
+
 function assertProdBuildPresent(appDir: string, entry: string): void {
   if (!fs.existsSync(entry)) {
     throw new ConfigurationError(
-      `lousho studio --prod: '${entry}' does not exist. Build Agent Forge first: ` +
+      `lousho studio --prod: '${entry}' does not exist. Build Studio first: ` +
         "run 'npm run build:studio' from the repo root (this bundles both the client " +
         "'vite build' output into apps/agent-forge/dist and the server into " +
         'apps/agent-forge/dist-server).', 'studio');
@@ -196,17 +280,24 @@ function assertProdBuildPresent(appDir: string, entry: string): void {
   }
 }
 
-function startProdStudio(appDir: string, repoRoot: string, apiPort: number, apiHost: string, token: string): StudioHandle {
-  const entry = distServerEntry(appDir);
+function startProdStudio(
+  appDir: string,
+  repoRoot: string,
+  apiPort: number,
+  apiHost: string,
+  spawnImpl: typeof spawn
+): StudioHandle {
+  const entry = studioCliEntry(appDir);
   assertProdBuildPresent(appDir, entry);
 
   console.log(`[lousho studio] starting production server (port ${apiPort})...`);
 
-  const apiProcess = spawn(process.execPath, [entry], {
-    cwd: appDir,
-    stdio: 'inherit',
-    env: { ...process.env, PORT: String(apiPort), HOST: apiHost, BASE_DIR: repoRoot, [STUDIO_TOKEN_ENV]: token },
-  });
+  // cli.cjs mints and prints its own per-launch token; no BASE_DIR/token env.
+  const apiProcess = spawnImpl(
+    process.execPath,
+    [entry, '--workspace', repoRoot, '--port', String(apiPort), '--host', apiHost],
+    { cwd: appDir, stdio: 'inherit' }
+  );
 
   function stop(): void {
     apiProcess.kill();
@@ -214,28 +305,33 @@ function startProdStudio(appDir: string, repoRoot: string, apiPort: number, apiH
 
   apiProcess.on('exit', (code) => reportUnexpectedExit('server', code));
 
-  console.log(`[lousho studio] Agent Forge: ${studioUrl(apiHost, apiPort, token)}`);
-
-  return { apiProcess, mode: 'prod', token, stop };
+  return { apiProcess, mode: 'prod', stop };
 }
 
 function assertDevSourcePresent(appDir: string): void {
   if (!fs.existsSync(path.join(appDir, 'server', 'index.ts'))) {
     throw new ConfigurationError(
       `lousho studio --dev: '${path.join(appDir, 'server', 'index.ts')}' does not exist - dev mode ` +
-        'needs the Agent Forge TypeScript source (this only works from inside the SDK monorepo, ' +
+        'needs the Studio TypeScript source (this only works inside the SDK repository, ' +
         "not from an installed npm package). Use the default/--prod mode instead, after running " +
         "'npm run build:studio'.", 'studio');
   }
 }
 
-function startDevStudio(appDir: string, repoRoot: string, apiPort: number, apiHost: string, token: string): StudioHandle {
+function startDevStudio(
+  appDir: string,
+  repoRoot: string,
+  apiPort: number,
+  apiHost: string,
+  token: string,
+  spawnImpl: typeof spawn
+): StudioHandle {
   assertDevSourcePresent(appDir);
   const npmCmd = resolveNpmCommand();
 
   console.log(`[lousho studio] starting API server (port ${apiPort}) and Vite dev server...`);
 
-  const apiProcess = spawn(npmCmd, ['run', 'server:dev'], {
+  const apiProcess = spawnImpl(npmCmd, ['run', 'server:dev'], {
     cwd: appDir,
     stdio: 'inherit',
     env: {
@@ -253,7 +349,7 @@ function startDevStudio(appDir: string, repoRoot: string, apiPort: number, apiHo
     },
   });
 
-  const viteProcess = spawn(npmCmd, ['run', 'dev'], {
+  const viteProcess = spawnImpl(npmCmd, ['run', 'dev'], {
     cwd: appDir,
     stdio: 'inherit',
     // Tells vite.config.ts's dev-server proxy where the API server it just
@@ -280,26 +376,24 @@ function startDevStudio(appDir: string, repoRoot: string, apiPort: number, apiHo
   });
 
   console.log(`[lousho studio] API server:  http://${apiHost}:${apiPort}`);
-  console.log(`[lousho studio] Agent Forge UI: ${VITE_DEV_ORIGINS[0]}/?token=${encodeURIComponent(token)}`);
+  console.log(`[lousho studio] Studio UI: ${VITE_DEV_ORIGINS[0]}/?token=${encodeURIComponent(token)}`);
 
   return { apiProcess, viteProcess, mode: 'dev', token, stop };
 }
 
-const USAGE = 'Usage: lousho studio [--port N] [--host H] [--prod|--dev]';
+const USAGE = 'Usage: lousho studio [--port N] [--host H]';
 
 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.
+Opens Lousho Studio on this project. Studio is a separate package: install it with npm i -g @linuxdevil/studio
+(or run npx @linuxdevil/studio). This command finds it and opens this folder as a workspace.
 
 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.`;
+  --prod      (SDK repository only) serve the built UI from one process
+  --dev       (SDK repository only) run the API and the Vite dev server
+  -h, --help  show this help`;
 
 const SPEC: CommandSpec = {
   command: 'studio',
diff --git a/src/cli/traces.test.ts b/src/cli/traces.test.ts
index 1ce0f3125..b8e1e2847 100644
--- a/src/cli/traces.test.ts
+++ b/src/cli/traces.test.ts
@@ -95,7 +95,7 @@ describe('lousho traces', () => {
     const { code, out } = await run([]);
     expect(code).toBe(0);
     expect(out).toBe(
-      "No traces in .lousho/traces. Add exporter: fileTraceExporter() to createAgent() (import { fileTraceExporter } from 'lousho/traces'), or run lousho dev / chat with --traces."
+      "No traces in .lousho/traces. Add exporter: fileTraceExporter() to createAgent() (import { fileTraceExporter } from '@linuxdevil/lousho/traces'), or run lousho dev / chat with --traces."
     );
   });
 
diff --git a/src/cli/traces.ts b/src/cli/traces.ts
index f062d12c3..662ff4fc1 100644
--- a/src/cli/traces.ts
+++ b/src/cli/traces.ts
@@ -274,7 +274,7 @@ function renderTraceTree(traceId: string, spans: Span[], options: { color: boole
 }
 
 function noTracesHint(dir: string): string {
-  return `No traces in ${dir}. Add exporter: fileTraceExporter() to createAgent() (import { fileTraceExporter } from 'lousho/traces'), or run lousho dev / chat with --traces.`;
+  return `No traces in ${dir}. Add exporter: fileTraceExporter() to createAgent() (import { fileTraceExporter } from '@linuxdevil/lousho/traces'), or run lousho dev / chat with --traces.`;
 }
 
 async function showList(args: TracesArgs, dir: string, deps: Required<TracesDeps>): Promise<number> {
diff --git a/src/createAgent.ts b/src/createAgent.ts
index ce844bcfe..cad1a0eaf 100644
--- a/src/createAgent.ts
+++ b/src/createAgent.ts
@@ -409,13 +409,13 @@ export interface CreateAgentBase<TOutput extends StandardSchemaV1 = StandardSche
    * session turns, `resume()` and runs continued by `agent.approvals.resolve()`.
    * Each run is one `invoke_agent` span with `chat` and `execute_tool` spans
    * under it; sub-agents' spans join the lead's trace. `fileTraceExporter()`
-   * from `lousho/traces` writes them to `.lousho/traces` for
+   * from `@linuxdevil/lousho/traces` writes them to `.lousho/traces` for
    * `npx lousho traces`; `createOtelTraceExporter()` sends them to
    * OpenTelemetry. See docs/observability.md.
    *
    * @example
    * ```ts
-   * import { fileTraceExporter } from 'lousho/traces';
+   * import { fileTraceExporter } from '@linuxdevil/lousho/traces';
    * createAgent({ model: 'openai/gpt-4o-mini', exporter: fileTraceExporter() });
    * ```
    */
@@ -441,7 +441,7 @@ export interface CreateAgentBase<TOutput extends StandardSchemaV1 = StandardSche
    *
    * @example
    * ```ts
-   * import { fileTraceExporter } from 'lousho/traces';
+   * import { fileTraceExporter } from '@linuxdevil/lousho/traces';
    * createAgent({ model: 'openai/gpt-4o-mini', exporter: fileTraceExporter(), redactContent: false });
    * // Your own redaction of captured content (replaces the built-in scrubber):
    * createAgent({ model: 'openai/gpt-4o-mini', redactContent: (text) => text.replace(/\b\d{16}\b/g, '[card]') });
diff --git a/src/deploy/adapters/__fixtures__/node-server-approvals/auth.ts b/src/deploy/adapters/__fixtures__/node-server-approvals/auth.ts
index 8468b15d4..44a0029f4 100644
--- a/src/deploy/adapters/__fixtures__/node-server-approvals/auth.ts
+++ b/src/deploy/adapters/__fixtures__/node-server-approvals/auth.ts
@@ -1,5 +1,5 @@
-import { apiToken } from 'lousho/auth';
-import type { ApprovalAccessRequest, SessionAccessRequest } from 'lousho';
+import { apiToken } from '@linuxdevil/lousho/auth';
+import type { ApprovalAccessRequest, SessionAccessRequest } from '@linuxdevil/lousho';
 
 // One token per user; the principal's id is the user.
 export default [apiToken('alice-token', { id: 'alice' }), apiToken('bob-token', { id: 'bob' }), apiToken('manager-token', { id: 'manager' })];
diff --git a/src/deploy/adapters/__fixtures__/node-server-approvals/tools/submit_expense.ts b/src/deploy/adapters/__fixtures__/node-server-approvals/tools/submit_expense.ts
index 862804aec..8240b4e14 100644
--- a/src/deploy/adapters/__fixtures__/node-server-approvals/tools/submit_expense.ts
+++ b/src/deploy/adapters/__fixtures__/node-server-approvals/tools/submit_expense.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 
 // The registry's mock provider calls a tool the user message names, with { input: 'mock input' }.
 export default defineTool({
diff --git a/src/deploy/adapters/__fixtures__/worker-agent-dir-full/channels/api.ts b/src/deploy/adapters/__fixtures__/worker-agent-dir-full/channels/api.ts
index 7b61dc1d2..570f40faa 100644
--- a/src/deploy/adapters/__fixtures__/worker-agent-dir-full/channels/api.ts
+++ b/src/deploy/adapters/__fixtures__/worker-agent-dir-full/channels/api.ts
@@ -1,4 +1,4 @@
-import { httpChannel } from 'lousho';
+import { httpChannel } from '@linuxdevil/lousho';
 
 // A JSON API channel under POST /channels/api.
 export default httpChannel({ name: 'api' });
diff --git a/src/deploy/adapters/__fixtures__/worker-agent-dir-full/memory/notes.ts b/src/deploy/adapters/__fixtures__/worker-agent-dir-full/memory/notes.ts
index 63865182d..d9e38c198 100644
--- a/src/deploy/adapters/__fixtures__/worker-agent-dir-full/memory/notes.ts
+++ b/src/deploy/adapters/__fixtures__/worker-agent-dir-full/memory/notes.ts
@@ -1,4 +1,4 @@
-import { defineMemory, kvMemory } from 'lousho';
+import { defineMemory, kvMemory } from '@linuxdevil/lousho';
 
 // kvMemory() is bound to the Worker's KV namespace (env.AGENT_CHECKPOINTS) per request.
 export default defineMemory({
diff --git a/src/deploy/adapters/__fixtures__/worker-agent-dir-full/schedules/report.ts b/src/deploy/adapters/__fixtures__/worker-agent-dir-full/schedules/report.ts
index e2fe26f21..eee65df30 100644
--- a/src/deploy/adapters/__fixtures__/worker-agent-dir-full/schedules/report.ts
+++ b/src/deploy/adapters/__fixtures__/worker-agent-dir-full/schedules/report.ts
@@ -1,4 +1,4 @@
-import { defineSchedule } from 'lousho';
+import { defineSchedule } from '@linuxdevil/lousho';
 
 export default defineSchedule({
   cron: '0 9 * * MON',
diff --git a/src/deploy/adapters/__fixtures__/worker-agent-dir-full/tools/echo.ts b/src/deploy/adapters/__fixtures__/worker-agent-dir-full/tools/echo.ts
index b17fcc737..2bb9745cd 100644
--- a/src/deploy/adapters/__fixtures__/worker-agent-dir-full/tools/echo.ts
+++ b/src/deploy/adapters/__fixtures__/worker-agent-dir-full/tools/echo.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 
 // The registry's mock provider calls a tool the user message names, with { input: 'mock input' }.
 export default defineTool({
diff --git a/src/deploy/adapters/__fixtures__/worker-agent-dir/tools/echo.ts b/src/deploy/adapters/__fixtures__/worker-agent-dir/tools/echo.ts
index b17fcc737..2bb9745cd 100644
--- a/src/deploy/adapters/__fixtures__/worker-agent-dir/tools/echo.ts
+++ b/src/deploy/adapters/__fixtures__/worker-agent-dir/tools/echo.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 
 // The registry's mock provider calls a tool the user message names, with { input: 'mock input' }.
 export default defineTool({
diff --git a/src/deploy/adapters/cloudflare-errors.test.ts b/src/deploy/adapters/cloudflare-errors.test.ts
index 984dbec70..94bc1b261 100644
--- a/src/deploy/adapters/cloudflare-errors.test.ts
+++ b/src/deploy/adapters/cloudflare-errors.test.ts
@@ -69,12 +69,12 @@ describe('cloudflare-worker build errors', () => {
     const dir = writeAgentDir({
       'instructions.md': 'Be brief.\n',
       'agent.json': '{ "model": "mock/test" }\n',
-      'tools/store.ts': "import { fileStore } from 'lousho';\nexport default fileStore;\n",
+      'tools/store.ts': "import { fileStore } from '@linuxdevil/lousho';\nexport default fileStore;\n",
     });
     const { run, thrown } = await buildInChild(dir);
     expect(thrown?.code).toBe('LOUSHO_DEPLOY_FAILED');
     expect(thrown?.message).toContain('for import "fileStore"');
-    expect(thrown?.message).toContain("the files of an agent directory can import only these from 'lousho'");
+    expect(thrown?.message).toContain("the files of an agent directory can import only these from '@linuxdevil/lousho'");
     expect(run.stderr).not.toMatch(/\[ERROR\]|Build failed/);
   }, 180_000);
 });
diff --git a/src/deploy/adapters/cloudflare.dir.test.ts b/src/deploy/adapters/cloudflare.dir.test.ts
index 88691c404..87dd63d43 100644
--- a/src/deploy/adapters/cloudflare.dir.test.ts
+++ b/src/deploy/adapters/cloudflare.dir.test.ts
@@ -239,7 +239,7 @@ describe('cloudflare-worker target: agent directories (#298)', () => {
       const dir = agentDir({
         ...MINIMAL,
         'schedules/report.ts':
-          "import { defineSchedule } from 'lousho';\n" +
+          "import { defineSchedule } from '@linuxdevil/lousho';\n" +
           "export default defineSchedule({ cron: '0 9 * * MON', timezone: 'Europe/Berlin', prompt: 'Hi' });\n",
       });
       await expect(CloudflareWorkerAdapter.scaffold(dir, outDirFor(dir))).rejects.toMatchObject({
@@ -295,7 +295,7 @@ describe('cloudflare-worker target: agent directories (#298)', () => {
     const explained = explainWorkerBuildError(esbuild) as Error & { code?: string; cause?: unknown };
     expect(explained.code).toBe('LOUSHO_DEPLOY_FAILED');
     expect(explained.message).toContain('for import "fileStore"');
-    expect(explained.message).toContain(`from 'lousho': ${WORKER_SDK_EXPORTS.join(', ')}`);
+    expect(explained.message).toContain(`from '@linuxdevil/lousho': ${WORKER_SDK_EXPORTS.join(', ')}`);
     expect(explained.cause).toBe(esbuild);
     const other = new Error('Build failed with 1 error: Could not resolve "x"');
     expect(explainWorkerBuildError(other)).toBe(other);
diff --git a/src/deploy/adapters/docker.test.ts b/src/deploy/adapters/docker.test.ts
index 809a9d12d..80acb0b09 100644
--- a/src/deploy/adapters/docker.test.ts
+++ b/src/deploy/adapters/docker.test.ts
@@ -97,7 +97,7 @@ describe('DockerAdapter', () => {
     const sdk = JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', '..', 'package.json'), 'utf8'));
     // 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']).toBeUndefined();
+    expect(manifest.dependencies['@linuxdevil/lousho']).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');
diff --git a/src/deploy/adapters/node-server-dir.test.ts b/src/deploy/adapters/node-server-dir.test.ts
index 686ee49d9..86aff52f3 100644
--- a/src/deploy/adapters/node-server-dir.test.ts
+++ b/src/deploy/adapters/node-server-dir.test.ts
@@ -17,16 +17,16 @@ import { withBuildLock } from '../buildLock.testkit';
 
 const FILES: Record<string, string> = {
   'instructions.md': 'You are a deployed agent directory.\n',
-  'agent.ts': `import { createMockProvider } from 'lousho';
+  'agent.ts': `import { createMockProvider } from '@linuxdevil/lousho';
 export default { provider: createMockProvider({ name: 'mock', responses: ['pong'] }) };
 `,
-  'schedules/daily.ts': `import { defineSchedule } from 'lousho';
+  'schedules/daily.ts': `import { defineSchedule } from '@linuxdevil/lousho';
 export default defineSchedule({ cron: '0 9 * * *', prompt: 'Good morning' });
 `,
-  'auth.ts': `import { apiToken, basic } from 'lousho/auth';
+  'auth.ts': `import { apiToken, basic } from '@linuxdevil/lousho/auth';
 export default [basic({ users: { ops: 'pw' } }), apiToken('dir-token', { id: 'ci' })];
 `,
-  'channels/echo.ts': `import { defineChannel } from 'lousho';
+  'channels/echo.ts': `import { defineChannel } from '@linuxdevil/lousho';
 export default defineChannel({
   name: 'echo',
   async parse(req) { return { sessionKey: 'k', input: req.text, replyTo: null }; },
diff --git a/src/deploy/adapters/node-server-errors.test.ts b/src/deploy/adapters/node-server-errors.test.ts
index b4e650f6a..85550addb 100644
--- a/src/deploy/adapters/node-server-errors.test.ts
+++ b/src/deploy/adapters/node-server-errors.test.ts
@@ -26,7 +26,7 @@ describe('node-server build errors', () => {
   it('reports an unresolved import as a coded error that says what to install, and leaves no dist/', async () => {
     const dir = writeAgentDir({
       'instructions.md': 'Be brief.\n',
-      'agent.ts': "import { createMockProvider } from 'lousho';\nexport default { provider: createMockProvider({ name: 'mock', responses: ['x'] }) };\n",
+      'agent.ts': "import { createMockProvider } from '@linuxdevil/lousho';\nexport default { provider: createMockProvider({ name: 'mock', responses: ['x'] }) };\n",
       'tools/uses-missing.ts': "import { nope } from 'definitely-not-installed-pkg';\nexport default nope;\n",
     });
     const outDir = path.join(path.dirname(dir), 'out');
diff --git a/src/deploy/adapters/node-server-module.test.ts b/src/deploy/adapters/node-server-module.test.ts
index 8a7da6a1f..d52959d75 100644
--- a/src/deploy/adapters/node-server-module.test.ts
+++ b/src/deploy/adapters/node-server-module.test.ts
@@ -12,7 +12,7 @@ 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';
+const AGENT_TS = `import { createMockProvider, type CreateAgentConfig } from '@linuxdevil/lousho';
 
 const instructions: string = 'You are a deployed agent module.';
 const config: CreateAgentConfig = { instructions, provider: createMockProvider({ name: 'mock', responses: ['module pong'] }) };
diff --git a/src/deploy/adapters/node-server-providers.test.ts b/src/deploy/adapters/node-server-providers.test.ts
index 7f039fab0..5b8e6be95 100644
--- a/src/deploy/adapters/node-server-providers.test.ts
+++ b/src/deploy/adapters/node-server-providers.test.ts
@@ -7,7 +7,7 @@ import { NodeServerAdapter, providersInSource } from './node-server';
 describe('providersInSource', () => {
   it('finds literal model prefixes and SDK provider classes', () => {
     expect(providersInSource("createAgent({ model: 'anthropic/claude-sonnet-4-5' })")).toEqual(['anthropic']);
-    expect(providersInSource("import { OpenRouterProvider } from 'lousho';\nnew OpenRouterProvider({ apiKey })")).toEqual(['openrouter']);
+    expect(providersInSource("import { OpenRouterProvider } from '@linuxdevil/lousho';\nnew OpenRouterProvider({ apiKey })")).toEqual(['openrouter']);
     expect(providersInSource('new OpenAIProvider({}); new OllamaProvider({})').sort()).toEqual(['ollama', 'openai']);
     expect(providersInSource('const x = 1')).toEqual([]);
   });
diff --git a/src/deploy/bundle.ts b/src/deploy/bundle.ts
index 656d30ae8..4391e0130 100644
--- a/src/deploy/bundle.ts
+++ b/src/deploy/bundle.ts
@@ -2,7 +2,7 @@
  * Shared bundling helpers for the built-in deployment adapters.
  *
  * Scaffolded entrypoints (server.ts / worker.ts) import the SDK through a
- * virtual specifier, `lousho/deploy-runtime` (or
+ * virtual specifier, `@linuxdevil/lousho/deploy-runtime` (or
  * `.../deploy-runtime-worker`). At build time sdkRuntimePlugin() resolves
  * that specifier to the runtime source file of the SDK copy that is
  * running `lousho build` - so the output is bundled against exactly the
@@ -16,8 +16,8 @@ import type { OnResolveArgs, OnResolveResult, Plugin, PluginBuild, ResolveResult
 import { SDKError } from '../execution/errors';
 import { moduleDir } from '../utils/moduleDir';
 
-export const RUNTIME_SPECIFIER = 'lousho/deploy-runtime';
-export const WORKER_RUNTIME_SPECIFIER = 'lousho/deploy-runtime-worker';
+export const RUNTIME_SPECIFIER = '@linuxdevil/lousho/deploy-runtime';
+export const WORKER_RUNTIME_SPECIFIER = '@linuxdevil/lousho/deploy-runtime-worker';
 
 /**
  * Walks up from this module's directory to the lousho
@@ -44,7 +44,7 @@ function isSdkPackageRoot(dir: string): boolean {
   const pkgPath = path.join(dir, 'package.json');
   if (!fs.existsSync(pkgPath)) return false;
   try {
-    return JSON.parse(fs.readFileSync(pkgPath, 'utf8')).name === 'lousho';
+    return JSON.parse(fs.readFileSync(pkgPath, 'utf8')).name === '@linuxdevil/lousho';
   } catch {
     // not a readable package.json - keep walking up
     return false;
@@ -69,18 +69,18 @@ export function sdkRuntimePlugin({ sdkEntry = 'main' }: { sdkEntry?: 'main' | 'w
   return {
     name: 'lousho-deploy-runtime',
     setup(build) {
-      build.onResolve({ filter: /^lousho\/deploy-runtime(-worker)?$/ }, (args) => ({
+      build.onResolve({ filter: /^(?:lousho|@linuxdevil\/lousho)\/deploy-runtime(-worker)?$/ }, (args) => ({
         path: runtimeSourceFile(
           args.path === WORKER_RUNTIME_SPECIFIER ? 'runtime.worker.ts' : 'runtime.ts'
         ),
       }));
-      // An agent directory's own `import ... from 'lousho'` bundles this SDK copy
+      // An agent directory's own `import ... from '@linuxdevil/lousho'` bundles this SDK copy
       // (the one the runtime above comes from), so tools, schedules and channels share its classes.
-      build.onResolve({ filter: /^lousho$/ }, () => ({
+      build.onResolve({ filter: /^(?:lousho|@linuxdevil\/lousho)$/ }, () => ({
         path: sdkEntry === 'worker' ? runtimeSourceFile('workerSdk.ts') : path.join(findSdkRoot(), 'src', 'index.ts'),
       }));
       // An agent directory's auth.ts imports its helpers from the auth subpath.
-      build.onResolve({ filter: /^lousho\/auth$/ }, () => ({
+      build.onResolve({ filter: /^(?:lousho|@linuxdevil\/lousho)\/auth$/ }, () => ({
         path: path.join(findSdkRoot(), 'src', 'auth', 'index.ts'),
       }));
     },
@@ -170,7 +170,7 @@ export function workerUnsupportedPeerPlugin(): Plugin {
 }
 
 /**
- * The specifiers the `lousho/worker` entry leaves external
+ * The specifiers the `@linuxdevil/lousho/worker` entry leaves external
  * (#289): `ai`, `zod` and `@opentelemetry/api` are the SDK's own peers a
  * user installs, and `@ai-sdk/openai` / `@ai-sdk/anthropic` are the
  * provider packages a real `openai`/`anthropic`/`openrouter` agent lazy-
@@ -185,7 +185,7 @@ export const WORKER_ENTRY_EXTERNALS = ['ai', 'zod', '@opentelemetry/api', '@ai-s
 
 /**
  * The esbuild plugins that build the Worker-safe
- * `lousho/worker` entry (src/deploy/worker.ts ->
+ * `@linuxdevil/lousho/worker` entry (src/deploy/worker.ts ->
  * dist/deploy/worker.*) - the same shims the cloudflare-worker adapter
  * applies at `lousho build` time, baked into the published entry instead
  * (#289): `workerNodeShimPlugin` and `workerSandboxShimPlugin` redirect the
diff --git a/src/deploy/kv.test.ts b/src/deploy/kv.test.ts
index 5a52438be..be1c0212f 100644
--- a/src/deploy/kv.test.ts
+++ b/src/deploy/kv.test.ts
@@ -1,5 +1,5 @@
 /**
- * R2: `lousho/kv` must bundle for a hand-written Cloudflare
+ * R2: `@linuxdevil/lousho/kv` must bundle for a hand-written Cloudflare
  * Worker, which has no shim for Node builtins. This guards the barrel's
  * import graph: no module it reaches may import a `node:` path.
  */
@@ -11,7 +11,7 @@ import * as kv from './kv';
 // esbuild keeps a service process alive after build(); end it so it does not outlive this file.
 afterAll(() => stop());
 
-describe('lousho/kv (R2)', () => {
+describe('@linuxdevil/lousho/kv (R2)', () => {
   it('bundles for the browser platform with no node: import in its graph', async () => {
     const result = await build({
       entryPoints: [join(__dirname, 'kv.ts')],
diff --git a/src/deploy/kv.ts b/src/deploy/kv.ts
index 9462f4711..5b190468a 100644
--- a/src/deploy/kv.ts
+++ b/src/deploy/kv.ts
@@ -1,5 +1,5 @@
 /**
- * `lousho/kv` (R2): the Cloudflare Workers KV stores, for a
+ * `@linuxdevil/lousho/kv` (R2): the Cloudflare Workers KV stores, for a
  * hand-written Worker. Node-free on purpose (no `node:*` import anywhere in
  * its graph, guarded by kv.test.ts) so it bundles for the Workers runtime
  * without shims.
diff --git a/src/deploy/nodeServer.ts b/src/deploy/nodeServer.ts
index b50ca2dd7..ab4d8716f 100644
--- a/src/deploy/nodeServer.ts
+++ b/src/deploy/nodeServer.ts
@@ -7,7 +7,7 @@
  * approvals and the legacy `POST /chat { message }`, plus `GET /ready`
  * (readiness: 200 while serving, 503 once `shutdown()` has begun; `/health` stays
  * the liveness probe). When auth is configured (a bearer
- * token, or an auth list from `lousho/auth`), every route except
+ * token, or an auth list from `@linuxdevil/lousho/auth`), every route except
  * `/health` and `/ready` requires it, including a channel route, unless that channel
  * authenticates its own requests (it has a `verify`: a signed platform channel,
  * a webhook with a secret, an `httpChannel({ verify })`).
diff --git a/src/deploy/otelTracing.ts b/src/deploy/otelTracing.ts
index 26d58a92e..819647592 100644
--- a/src/deploy/otelTracing.ts
+++ b/src/deploy/otelTracing.ts
@@ -116,7 +116,7 @@ export async function otelTracingFromEnv(options: OtelTracingOptions): Promise<O
     provider.register();
     log.log('lousho server: exporting OTel traces to ' + endpoint);
     return {
-      exporter: createOtelTraceExporter({ tracer: provider.getTracer('lousho') }),
+      exporter: createOtelTraceExporter({ tracer: provider.getTracer('@linuxdevil/lousho') }),
       shutdown: () => provider.shutdown(),
     };
   } catch (error) {
diff --git a/src/deploy/runtime.ts b/src/deploy/runtime.ts
index 1cfabbed8..b14503966 100644
--- a/src/deploy/runtime.ts
+++ b/src/deploy/runtime.ts
@@ -2,7 +2,7 @@
  * Node runtime for generated deployment servers.
  *
  * The server.ts that the node-server/docker adapters scaffold imports
- * `lousho/deploy-runtime`; at build time that import is
+ * `@linuxdevil/lousho/deploy-runtime`; at build time that import is
  * resolved to this file (see sdkRuntimePlugin in ./bundle.ts) and bundled
  * into dist/server.js, so the built server is self-contained.
  *
diff --git a/src/deploy/runtime.worker.ts b/src/deploy/runtime.worker.ts
index 3f0a56f89..6e5e7eded 100644
--- a/src/deploy/runtime.worker.ts
+++ b/src/deploy/runtime.worker.ts
@@ -2,7 +2,7 @@
  * Cloudflare Worker runtime for generated workers.
  *
  * The worker.ts the cloudflare-worker adapter scaffolds imports
- * `lousho/deploy-runtime-worker`, resolved at build time to
+ * `@linuxdevil/lousho/deploy-runtime-worker`, resolved at build time to
  * this file. Everything reachable from here must run without Node builtins
  * (Workers have no node:fs/node:http/...): the adapter bundles with
  * platform 'browser' and swaps the one Node-dependent module on
diff --git a/src/deploy/shims/mcp.worker.ts b/src/deploy/shims/mcp.worker.ts
index e0a683aeb..b54e0da39 100644
--- a/src/deploy/shims/mcp.worker.ts
+++ b/src/deploy/shims/mcp.worker.ts
@@ -1,6 +1,6 @@
 /**
  * Worker-safe stand-in for every `@modelcontextprotocol/sdk` specifier the
- * `lousho/worker` entry reaches (#289).
+ * `@linuxdevil/lousho/worker` entry reaches (#289).
  *
  * `createAgent({ mcpServers })` lazy-imports the optional MCP peer through
  * tools/mcp/connect.ts (client/index.js, client/stdio.js,
diff --git a/src/deploy/worker.test.ts b/src/deploy/worker.test.ts
index 65450c33c..7feb20cc9 100644
--- a/src/deploy/worker.test.ts
+++ b/src/deploy/worker.test.ts
@@ -1,5 +1,5 @@
 /**
- * #289: `lousho/worker` must bundle for a hand-written
+ * #289: `@linuxdevil/lousho/worker` must bundle for a hand-written
  * Cloudflare Worker, which has no shim for Node builtins (unlike the
  * generated Worker, whose `lousho build` applies them itself). The SDK
  * ships the entry pre-shimmed: tsup.config.ts builds src/deploy/worker.ts
@@ -18,7 +18,7 @@ import * as workerSdk from './workerSdk';
 // esbuild keeps a service process alive after build(); end it so it does not outlive this file.
 afterAll(() => stop());
 
-describe('lousho/worker (#289)', () => {
+describe('@linuxdevil/lousho/worker (#289)', () => {
   it('bundles for the browser platform with no node: import in its graph or output', async () => {
     const result = await build({
       entryPoints: [join(__dirname, 'worker.ts')],
diff --git a/src/deploy/worker.ts b/src/deploy/worker.ts
index c4f2ba72a..019437fef 100644
--- a/src/deploy/worker.ts
+++ b/src/deploy/worker.ts
@@ -1,10 +1,10 @@
 /**
- * The Worker-safe entry point `lousho/worker` (#289): what a
+ * The Worker-safe entry point `@linuxdevil/lousho/worker` (#289): what a
  * hand-written Cloudflare Worker imports `createAgent` and friends from.
  *
  * The package root (`src/index.ts`) also exports file stores, the
  * agent-directory loader, MCP over stdio, sandboxes and other Node-only
- * modules, so `import { createAgent } from 'lousho'` cannot
+ * modules, so `import { createAgent } from '@linuxdevil/lousho'` cannot
  * be bundled for a Worker: esbuild fails resolving `node:fs`, `node:crypto`
  * & co. This entry exports `createAgent` and the rest of what a Worker can
  * run, and the SDK's own build produces it through workerEntryPlugins()
diff --git a/src/deploy/workerMemory.ts b/src/deploy/workerMemory.ts
index 24090f768..9f256336f 100644
--- a/src/deploy/workerMemory.ts
+++ b/src/deploy/workerMemory.ts
@@ -70,7 +70,7 @@ function unbound(): never {
  *
  * ```ts
  * // memory/notes.ts
- * import { defineMemory, kvMemory } from 'lousho';
+ * import { defineMemory, kvMemory } from '@linuxdevil/lousho';
  * export default defineMemory({ name: 'notes', scope: 'global', provider: kvMemory() });
  * ```
  *
diff --git a/src/deploy/workerSdk.ts b/src/deploy/workerSdk.ts
index b3d825c31..b83ffd1e9 100644
--- a/src/deploy/workerSdk.ts
+++ b/src/deploy/workerSdk.ts
@@ -1,5 +1,5 @@
 /**
- * What `import ... from 'lousho'` means inside an agent
+ * What `import ... from '@linuxdevil/lousho'` means inside an agent
  * directory built with `lousho build --target=cloudflare-worker` (and
  * #298 for schedules, channels and memory).
  *
diff --git a/src/deploy/workerSdkExports.ts b/src/deploy/workerSdkExports.ts
index ef6ae269d..8412b8128 100644
--- a/src/deploy/workerSdkExports.ts
+++ b/src/deploy/workerSdkExports.ts
@@ -1,13 +1,13 @@
 /**
  * The names an agent directory's files may import from
- * 'lousho' in a cloudflare-worker build: the exports of
+ * '@linuxdevil/lousho' in a cloudflare-worker build: the exports of
  * src/deploy/workerSdk.ts (a test keeps the two equal). In its own module so
  * the adapter (adapters/cloudflare.ts) and the build-time module evaluation
  * (./evalModule.ts) can share it without a circular import.
  */
 import { SDKError } from '../execution/errors';
 
-/** The names an agent directory's files may import from 'lousho' in a Worker build. */
+/** The names an agent directory's files may import from '@linuxdevil/lousho' in a Worker build. */
 export const WORKER_SDK_EXPORTS = [
   'AnthropicProvider',
   'ConfigurationError',
@@ -49,7 +49,7 @@ export function explainWorkerBuildError(error: unknown): unknown {
   return new SDKError(
     `cloudflare-worker build: ${message}
 In a Cloudflare Worker, the files of an agent directory can import only these ` +
-      `from 'lousho': ${WORKER_SDK_EXPORTS.join(', ')}. Use --target=node-server or --target=docker for the rest.`,
+      `from '@linuxdevil/lousho': ${WORKER_SDK_EXPORTS.join(', ')}. Use --target=node-server or --target=docker for the rest.`,
     'LOUSHO_DEPLOY_FAILED',
     { cause: error }
   );
diff --git a/src/execution/guardrailStarterSet.ts b/src/execution/guardrailStarterSet.ts
index 75556aeee..d500db59e 100644
--- a/src/execution/guardrailStarterSet.ts
+++ b/src/execution/guardrailStarterSet.ts
@@ -113,7 +113,7 @@ const PII_DETECTORS: Record<PiiType, Detector<PiiType>> = {
  *
  * @example
  * ```ts
- * import { piiGuardrail } from 'lousho';
+ * import { piiGuardrail } from '@linuxdevil/lousho';
  *
  * const redactContacts = piiGuardrail({ types: ['email', 'phone'], action: 'rewrite' });
  * ```
diff --git a/src/execution/index.ts b/src/execution/index.ts
index ebe7a16b7..7d019c1e0 100644
--- a/src/execution/index.ts
+++ b/src/execution/index.ts
@@ -3,12 +3,12 @@
  * Agent execution engine with streaming support
  */
 
-// The executor API moved to 'lousho/executor'. The
+// The executor API moved to '@linuxdevil/lousho/executor'. The
 // root keeps PropagatingToolError and the result types createAgent() uses.
 export { PropagatingToolError } from './propagatingToolError';
 export type { ExecutionResult, ExecutionFinishReason } from './AgentExecutor';
 export * from './errors';
-// StorageServiceApprovalStore moved to 'lousho/utils'.
+// StorageServiceApprovalStore moved to '@linuxdevil/lousho/utils'.
 export {
   ASK_QUESTION_TOOL_NAME,
   approvalExpired,
@@ -28,8 +28,8 @@ export {
   type SuspendedBackgroundTasks,
 } from './ApprovalGate';
 export { InMemoryApprovalStore } from './InMemoryApprovalStore';
-// The resume functions moved to 'lousho/executor'.
-// LocalStorageCheckpointStore moved to 'lousho/utils'.
+// The resume functions moved to '@linuxdevil/lousho/executor'.
+// LocalStorageCheckpointStore moved to '@linuxdevil/lousho/utils'.
 export {
   appendToRing,
   DEFAULT_CHECKPOINT_HISTORY_LIMIT,
diff --git a/src/execution/ioGuardrails.ts b/src/execution/ioGuardrails.ts
index 45f5605b9..da70f26d8 100644
--- a/src/execution/ioGuardrails.ts
+++ b/src/execution/ioGuardrails.ts
@@ -327,7 +327,7 @@ export function maxLengthGuardrail({ maxChars }: { maxChars: number }): IoGuardr
  *
  * @example
  * ```ts
- * import { regexGuardrail } from 'lousho';
+ * import { regexGuardrail } from '@linuxdevil/lousho';
  *
  * const ssn = regexGuardrail({ name: 'ssn', pattern: /\b\d{3}-\d{2}-\d{4}\b/, action: 'rewrite' });
  * ```
diff --git a/src/execution/otel.ts b/src/execution/otel.ts
index 121877f7e..42b8d5383 100644
--- a/src/execution/otel.ts
+++ b/src/execution/otel.ts
@@ -8,7 +8,7 @@
  * `examples/tracing/run-otel.ts` every time.
  *
  * This module is the ready-made version of that adapter: import
- * `createOtelTraceExporter()` from the `lousho/otel`
+ * `createOtelTraceExporter()` from the `@linuxdevil/lousho/otel`
  * subpath to translate this SDK's Span/TraceExporter shape into real
  * OpenTelemetry spans via `@opentelemetry/api`'s `trace.getTracer(...)`,
  * without pulling any OTel SDK/exporter backend into this package.
@@ -17,7 +17,7 @@
  * it is only required at runtime by consumers who import this subpath.
  * Importing `lousho` (or any other subpath) never loads
  * this module and never requires `@opentelemetry/api` to be installed.
- * If it isn't installed, importing `lousho/otel` throws a
+ * If it isn't installed, importing `@linuxdevil/lousho/otel` throws a
  * clear module-not-found error at that import site, not at package-import
  * time.
  */
@@ -54,7 +54,7 @@ import { Span, TraceExporter } from './tracing';
 export interface OtelTraceExporterOptions {
   /**
    * Name passed to `trace.getTracer(tracerName, tracerVersion)`. Defaults
-   * to `'lousho'`. Ignored when `tracer` is supplied.
+   * to `'@linuxdevil/lousho'`. Ignored when `tracer` is supplied.
    */
   tracerName?: string;
   /**
@@ -135,7 +135,7 @@ const LEGACY_KEYS: ReadonlySet<string> = new Set(Object.values(LegacyAttr));
  *
  * @example
  * ```ts
- * import { createOtelTraceExporter } from 'lousho/otel';
+ * import { createOtelTraceExporter } from '@linuxdevil/lousho/otel';
  *
  * const exporter = createOtelTraceExporter({ tracerName: 'my-agent' });
  * await AgentExecutor.execute({ agent, input, provider, toolRegistry, exporter });
@@ -143,7 +143,7 @@ const LEGACY_KEYS: ReadonlySet<string> = new Set(Object.values(LegacyAttr));
  */
 export function createOtelTraceExporter(options: OtelTraceExporterOptions = {}): TraceExporter {
   const tracer =
-    options.tracer ?? trace.getTracer(options.tracerName ?? 'lousho', options.tracerVersion);
+    options.tracer ?? trace.getTracer(options.tracerName ?? '@linuxdevil/lousho', options.tracerVersion);
 
   // Our Span.id -> the OTel span + context it was started in, so a child
   // Span (matched by parentId) can be started as a child of the right
@@ -227,7 +227,7 @@ export function createOtelTraceExporter(options: OtelTraceExporterOptions = {}):
 /** The metrics recorder for `options`: a no-op when `metrics` is `false`. */
 function resolveMetricsRecorder(options: OtelTraceExporterOptions): (span: Span) => void {
   if (options.metrics === false) return () => undefined;
-  const name = options.tracerName ?? 'lousho';
+  const name = options.tracerName ?? '@linuxdevil/lousho';
   return createMetricsRecorder(options.meter ?? otelMetrics.getMeter(name, options.tracerVersion));
 }
 
diff --git a/src/execution/permissions.ts b/src/execution/permissions.ts
index bb4bcb1ab..64811548c 100644
--- a/src/execution/permissions.ts
+++ b/src/execution/permissions.ts
@@ -53,7 +53,7 @@ export interface PermissionAuditContext {
  *
  * @example
  * ```ts
- * import type { PermissionRule } from 'lousho';
+ * import type { PermissionRule } from '@linuxdevil/lousho';
  *
  * const rules: PermissionRule[] = [
  *   { tool: 'shell', when: (args) => String(args.command).startsWith('rm '), action: 'deny', reason: 'No deletes' },
@@ -135,7 +135,7 @@ export interface PermissionOptions {
    *
    * @example
    * ```ts
-   * import { allow, ask, deny } from 'lousho';
+   * import { allow, ask, deny } from '@linuxdevil/lousho';
    *
    * const permissions = [deny('delete_file', 'Deleting is not allowed'), ask(['shell', 'write_file']), allow('*')];
    * ```
@@ -153,7 +153,7 @@ export interface PermissionOptions {
    *
    * @example
    * ```ts
-   * import { createAgent } from 'lousho';
+   * import { createAgent } from '@linuxdevil/lousho';
    *
    * const agent = createAgent({ provider, instructions: 'Review the code.', tools, permissionMode: 'plan' });
    * ```
diff --git a/src/index.ts b/src/index.ts
index 4f65ecace..6c91f3bf1 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -9,15 +9,15 @@
 export { VERSION } from './version';
 
 // The executor API (AgentBuilder, AgentExecutor, resume functions,
-// ToolRegistry) moved to 'lousho/executor'.
+// ToolRegistry) moved to '@linuxdevil/lousho/executor'.
 
 // Type exports
 export * from './types';
 
-// Tools (ToolRegistry moved to 'lousho/executor')
+// Tools (ToolRegistry moved to '@linuxdevil/lousho/executor')
 export * from './tools/rootTools';
 
-// Flows moved to 'lousho/flows'.
+// Flows moved to '@linuxdevil/lousho/flows'.
 
 
 
@@ -39,7 +39,7 @@ export * from './security';
 // boundary, not a security boundary - see docs/specs/0001-observability-platform/0001-sandboxing.md.
 export * from './sandbox';
 
-// Storage moved to 'lousho/utils'.
+// Storage moved to '@linuxdevil/lousho/utils'.
 
 
 // Token estimation and model registry
@@ -49,7 +49,7 @@ export * from './models';
 export * from './context';
 
 // Utils: the error helpers stay on the root; encryption, StorageService and
-// the validators moved to 'lousho/utils'.
+// the validators moved to '@linuxdevil/lousho/utils'.
 export * from './utils/errors';
 export * from './utils/errorCodes';
 
@@ -64,7 +64,7 @@ export * from './createAgent';
 export { createAgent } from './createAgent';
 // Handoffs: hand the conversation to another agent
 export * from './handoffs';
-// Who is calling: the helpers live in 'lousho/auth'; the type rides in SendOptions.
+// Who is calling: the helpers live in '@linuxdevil/lousho/auth'; the type rides in SendOptions.
 export type { Principal } from './auth/types';
 export type { AgentApprovals, ApproveToolCall, ResolveApprovalOptions } from './createAgentApprovals';
 export type { PendingRun } from './agentPending';
diff --git a/src/integrations/index.ts b/src/integrations/index.ts
index 9c7bc7c4c..a687532d1 100644
--- a/src/integrations/index.ts
+++ b/src/integrations/index.ts
@@ -2,7 +2,7 @@
  * Integrations
  * The credentialed third-party tools - Jira, GitHub, Slack and email. They
  * used to ship on the package root (and `./tools`); import them from
- * `lousho/integrations`. The files themselves still live in
+ * `@linuxdevil/lousho/integrations`. The files themselves still live in
  * `src/tools/built-in/`; this barrel only re-exports them.
  */
 
diff --git a/src/oauth/defineOAuthProvider.ts b/src/oauth/defineOAuthProvider.ts
index ff24a1ea6..c263f3e76 100644
--- a/src/oauth/defineOAuthProvider.ts
+++ b/src/oauth/defineOAuthProvider.ts
@@ -80,7 +80,7 @@ function assertUrl(value: unknown, field: string, name: string): void {
  *
  * @example
  * ```ts
- * import { defineOAuthProvider } from 'lousho';
+ * import { defineOAuthProvider } from '@linuxdevil/lousho';
  *
  * export const github = defineOAuthProvider({
  *   name: 'github',
diff --git a/src/observe/index.test.ts b/src/observe/index.test.ts
index 12d387b25..1a9e81121 100644
--- a/src/observe/index.test.ts
+++ b/src/observe/index.test.ts
@@ -1,11 +1,11 @@
 /**
- * W14: `lousho/observe` is the public surface Studio (and other hosts) use to
+ * W14: `@linuxdevil/lousho/observe` is the public surface Studio (and other hosts) use to
  * run and probe the collector — named re-exports of the daemon helpers only.
  */
 import { describe, expect, it } from 'vitest';
 import * as observe from './index';
 
-describe('lousho/observe', () => {
+describe('@linuxdevil/lousho/observe', () => {
   it('exports exactly the documented surface', () => {
     expect(Object.keys(observe).sort()).toEqual([
       'OBSERVE_DEFAULT_PORT',
diff --git a/src/publicSurface.test-d.ts b/src/publicSurface.test-d.ts
index cb566ce51..34763170e 100644
--- a/src/publicSurface.test-d.ts
+++ b/src/publicSurface.test-d.ts
@@ -9,83 +9,83 @@ import { describe, it, expectTypeOf } from 'vitest';
 
 describe('public surface: moved types are off the root, on their subpath', () => {
   it('flow types moved to ./flows', () => {
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T1 = import('./index').AgentFlow;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T2 = import('./index').EditorStep;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T3 = import('./index').FlowExecutionEvent;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T4 = import('./index').FlowExecutionEventOf;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T5 = import('./index').FlowExecutionResult;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T6 = import('./index').FlowExecutionContext;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T7 = import('./index').FlowChunkEvent;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T8 = import('./index').FlowInputVariable;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T9 = import('./index').FlowInputType;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T10 = import('./index').FlowAgentDefinition;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T11 = import('./index').FlowToolSetting;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T12 = import('./index').FlowExecutionMode;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T13 = import('./index').FlowOutputMode;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T14 = import('./index').EditorShapeStep;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T15 = import('./index').RuntimeStep;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T16 = import('./index').StepNode;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T17 = import('./index').SequenceNode;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T18 = import('./index').ParallelNode;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T19 = import('./index').OneOfNode;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T20 = import('./index').ForEachNode;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T21 = import('./index').EvaluatorNode;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T22 = import('./index').BestOfAllNode;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T23 = import('./index').ToolNode;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T24 = import('./index').UIComponentNode;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T25 = import('./index').ConditionNode;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T26 = import('./index').LoopNode;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T27 = import('./index').OneOfOption;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T28 = import('./index').OneOfOptionsNode;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T29 = import('./index').ForEachItemsNode;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T30 = import('./index').ExpressionEvaluatorNode;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T31 = import('./index').LLMCallNode;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T32 = import('./index').ToolCallNode;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T33 = import('./index').SetVariableNode;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T34 = import('./index').ReturnNode;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T35 = import('./index').EndNode;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T36 = import('./index').ThrowNode;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T37 = import('./index').FlowDefinitionNode;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T38 = import('./index').FlowExecutionEventType;
-    // @ts-expect-error - moved to 'lousho/flows'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/flows'
     type _T39 = import('./index').FlowExecutionEventDataMap;
 
     // Present on './flows':
@@ -131,31 +131,31 @@ describe('public surface: moved types are off the root, on their subpath', () =>
   });
 
   it('integration types moved to ./integrations', () => {
-    // @ts-expect-error - moved to 'lousho/integrations'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/integrations'
     type _T1 = import('./index').EmailToolOptions;
-    // @ts-expect-error - moved to 'lousho/integrations'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/integrations'
     type _T2 = import('./index').JiraConfig;
-    // @ts-expect-error - moved to 'lousho/integrations'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/integrations'
     type _T3 = import('./index').JiraTicket;
-    // @ts-expect-error - moved to 'lousho/integrations'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/integrations'
     type _T4 = import('./index').JiraComment;
-    // @ts-expect-error - moved to 'lousho/integrations'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/integrations'
     type _T5 = import('./index').JiraTransition;
-    // @ts-expect-error - moved to 'lousho/integrations'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/integrations'
     type _T6 = import('./index').GitHubConfig;
-    // @ts-expect-error - moved to 'lousho/integrations'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/integrations'
     type _T7 = import('./index').GitHubFile;
-    // @ts-expect-error - moved to 'lousho/integrations'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/integrations'
     type _T8 = import('./index').GitHubSearchResult;
-    // @ts-expect-error - moved to 'lousho/integrations'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/integrations'
     type _T9 = import('./index').GitHubPullRequest;
-    // @ts-expect-error - moved to 'lousho/integrations'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/integrations'
     type _T10 = import('./index').GitHubBranch;
-    // @ts-expect-error - moved to 'lousho/integrations'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/integrations'
     type _T11 = import('./index').SlackBlock;
-    // @ts-expect-error - moved to 'lousho/integrations'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/integrations'
     type _T12 = import('./index').SlackAlertPayload;
-    // @ts-expect-error - moved to 'lousho/integrations'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/integrations'
     type _T13 = import('./index').SlackToolOptions;
 
     expectTypeOf<import('./integrations').EmailToolOptions>().not.toBeNever();
@@ -174,19 +174,19 @@ describe('public surface: moved types are off the root, on their subpath', () =>
   });
 
   it('utility types moved to ./utils', () => {
-    // @ts-expect-error - moved to 'lousho/utils'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/utils'
     type _T1 = import('./index').EncryptionConfig;
-    // @ts-expect-error - moved to 'lousho/utils'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/utils'
     type _T2 = import('./index').DTOEncryptionSettings;
-    // @ts-expect-error - moved to 'lousho/utils'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/utils'
     type _T3 = import('./index').AuthorizationContext;
-    // @ts-expect-error - moved to 'lousho/utils'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/utils'
     type _T4 = import('./index').FileSystemAdapter;
-    // @ts-expect-error - moved to 'lousho/utils'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/utils'
     type _T5 = import('./index').PathAdapter;
-    // @ts-expect-error - moved to 'lousho/utils'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/utils'
     type _T6 = import('./index').IStorageService;
-    // @ts-expect-error - moved to 'lousho/utils'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/utils'
     type _T7 = import('./index').StorageConfig;
 
     expectTypeOf<import('./utils').EncryptionConfig>().not.toBeNever();
@@ -301,11 +301,11 @@ describe('public surface: the patch-guardrail type names are gone', () => {
 
 describe('public surface: the executor API moved to ./executor', () => {
   it('moved types are off the root, on ./executor', () => {
-    // @ts-expect-error - moved to 'lousho/executor'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/executor'
     type _T1 = import('./index').ExecuteOptions;
-    // @ts-expect-error - moved to 'lousho/executor'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/executor'
     type _T2 = import('./index').ResumeExecuteOptions;
-    // @ts-expect-error - moved to 'lousho/executor'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/executor'
     type _T3 = import('./index').ResumeRequest;
     expectTypeOf<import('./executor').ExecuteOptions>().not.toBeNever();
     expectTypeOf<import('./executor').ResumeExecuteOptions>().not.toBeNever();
@@ -313,19 +313,19 @@ describe('public surface: the executor API moved to ./executor', () => {
   });
 
   it('moved values are off the root, on ./executor', () => {
-    // @ts-expect-error - moved to 'lousho/executor'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/executor'
     type _V1 = typeof import('./index').AgentBuilder;
-    // @ts-expect-error - moved to 'lousho/executor'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/executor'
     type _V2 = typeof import('./index').AgentExecutor;
-    // @ts-expect-error - moved to 'lousho/executor'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/executor'
     type _V3 = typeof import('./index').resumeAfterApproval;
-    // @ts-expect-error - moved to 'lousho/executor'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/executor'
     type _V4 = typeof import('./index').streamResumeAfterApproval;
-    // @ts-expect-error - moved to 'lousho/executor'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/executor'
     type _V5 = typeof import('./index').resumeRequest;
-    // @ts-expect-error - moved to 'lousho/executor'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/executor'
     type _V6 = typeof import('./index').ToolRegistry;
-    // @ts-expect-error - moved to 'lousho/executor'
+    // @ts-expect-error - moved to '@linuxdevil/lousho/executor'
     type _V7 = typeof import('./index').globalToolRegistry;
     expectTypeOf<typeof import('./executor').AgentBuilder>().not.toBeNever();
     expectTypeOf<typeof import('./executor').AgentExecutor>().not.toBeNever();
diff --git a/src/publicSurface.test.ts b/src/publicSurface.test.ts
index 6cfcebbac..64cbfaf3f 100644
--- a/src/publicSurface.test.ts
+++ b/src/publicSurface.test.ts
@@ -21,7 +21,7 @@ type Entry = Record<string, unknown>;
 const MOVED: Array<[mod: Entry, specifier: string, names: string[]]> = [
   [
     flows as Entry,
-    'lousho/flows',
+    '@linuxdevil/lousho/flows',
     [
       'FlowBuilder',
       'FlowExecutor',
@@ -40,7 +40,7 @@ const MOVED: Array<[mod: Entry, specifier: string, names: string[]]> = [
   ],
   [
     integrations as Entry,
-    'lousho/integrations',
+    '@linuxdevil/lousho/integrations',
     [
       'createEmailTool',
       'createJiraTools',
@@ -57,7 +57,7 @@ const MOVED: Array<[mod: Entry, specifier: string, names: string[]]> = [
   ],
   [
     utils as Entry,
-    'lousho/utils',
+    '@linuxdevil/lousho/utils',
     [
       'EncryptionUtils',
       'DTOEncryptionFilter',
@@ -78,7 +78,7 @@ const MOVED: Array<[mod: Entry, specifier: string, names: string[]]> = [
   ],
   [
     executor as Entry,
-    'lousho/executor',
+    '@linuxdevil/lousho/executor',
     [
       'AgentBuilder',
       'AgentExecutor',
diff --git a/src/react/index.ts b/src/react/index.ts
index 4fd7d44ec..2bfab6e3e 100644
--- a/src/react/index.ts
+++ b/src/react/index.ts
@@ -1,5 +1,5 @@
 /**
- * `lousho/react`: the `useLoushoAgent()` hook, and
+ * `@linuxdevil/lousho/react`: the `useLoushoAgent()` hook, and
  * the framework-neutral reducer and stream parser it is built on (now in
  * src/ui, shared with the Vue binding).
  */
diff --git a/src/react/react.test-d.ts b/src/react/react.test-d.ts
index 2eebd614f..0314c9a22 100644
--- a/src/react/react.test-d.ts
+++ b/src/react/react.test-d.ts
@@ -1,5 +1,5 @@
 /**
- * The public types of `lousho/react`.
+ * The public types of `@linuxdevil/lousho/react`.
  */
 import { describe, it, expectTypeOf } from 'vitest';
 import { createAgent } from '../createAgent';
@@ -24,7 +24,7 @@ import {
   type UseLoushoAgentResult,
 } from './index';
 
-describe('lousho/react types', () => {
+describe('@linuxdevil/lousho/react types', () => {
   it('accepts an in-process agent or a URL as the source', () => {
     const agent = createAgent({ provider: createMockProvider() });
     expectTypeOf({ agent }).toMatchTypeOf<LoushoAgentSource>();
diff --git a/src/security/index.ts b/src/security/index.ts
index ee199a994..4508b5de7 100644
--- a/src/security/index.ts
+++ b/src/security/index.ts
@@ -4,7 +4,7 @@
  * Provides cryptographic utilities, sandboxing, and security-related functions
  */
 
-// './types' and './crypto' moved to 'lousho/utils'
+// './types' and './crypto' moved to '@linuxdevil/lousho/utils'
 // (src/utils/index.ts re-exports them).
 
 // Sandboxing
diff --git a/src/server/routeHandler.ts b/src/server/routeHandler.ts
index 2153813bc..1801b7939 100644
--- a/src/server/routeHandler.ts
+++ b/src/server/routeHandler.ts
@@ -26,7 +26,7 @@ export interface RouteHandlerOptions extends ChatRoutesAccess {
   basePath?: string;
   /**
    * Who may call (docs/auth.md): an ordered list of auth entries from
-   * `lousho/auth` (`jwt()`, `oidc()`, `basic()`, `apiToken()`, ...)
+   * `@linuxdevil/lousho/auth` (`jwt()`, `oidc()`, `basic()`, `apiToken()`, ...)
    * or one entry; the accepted `principal` reaches the run. Also a bearer token
    * string (`apiToken(token)`), or a function returning a boolean (`true`
    * accepts with principal `{ id: 'anonymous', type: 'user', authenticator: 'custom' }`).
diff --git a/src/session/sessionId.ts b/src/session/sessionId.ts
index 073e11a72..efb40211b 100644
--- a/src/session/sessionId.ts
+++ b/src/session/sessionId.ts
@@ -1,6 +1,6 @@
 /**
  * Session id validation, in a module with no Node builtins so Worker code
- * (`KVStore`, `lousho/kv`) can import it. `sessionStore.ts`
+ * (`KVStore`, `@linuxdevil/lousho/kv`) can import it. `sessionStore.ts`
  * re-exports `assertSessionId`.
  */
 
diff --git a/src/spec/generators/__snapshots__/typescript.test.ts.snap b/src/spec/generators/__snapshots__/typescript.test.ts.snap
index e188d9e4c..2bbfe3a26 100644
--- a/src/spec/generators/__snapshots__/typescript.test.ts.snap
+++ b/src/spec/generators/__snapshots__/typescript.test.ts.snap
@@ -4,7 +4,7 @@ exports[`specToCode > renders a spec with every section 1`] = `
 "// Generated by lousho from AgentSpec v2 'a'. Edit the spec, not this file.
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { createAgent, guardrailsFromSpec, handoffFromSpec, hooksFromSpec, jsonSchemaToStandardSchema, memoryFromSpec, outputFromSpec, permissionsFromSpec, resolveMcpServers, resolveSkillRef, resolveToolRef, specV2ToAgent, subagentFromSpec } from 'lousho';
+import { createAgent, guardrailsFromSpec, handoffFromSpec, hooksFromSpec, jsonSchemaToStandardSchema, memoryFromSpec, outputFromSpec, permissionsFromSpec, resolveMcpServers, resolveSkillRef, resolveToolRef, specV2ToAgent, subagentFromSpec } from '@linuxdevil/lousho';
 
 /** Where relative paths in the spec start, and how named secrets resolve (environment variables here). */
 const host = { baseDir: path.dirname(fileURLToPath(import.meta.url)), resolveSecret: (name: string) => process.env[name], resolveHandoffAgent: async (name: string) => subagents[name] };
diff --git a/src/spec/generators/typescript.test.ts b/src/spec/generators/typescript.test.ts
index 84e22946e..f40552e09 100644
--- a/src/spec/generators/typescript.test.ts
+++ b/src/spec/generators/typescript.test.ts
@@ -71,7 +71,7 @@ describe('specToCode', () => {
       "// Generated by lousho from AgentSpec v2 'a'. Edit the spec, not this file.
       import path from 'node:path';
       import { fileURLToPath } from 'node:url';
-      import { createAgent } from 'lousho';
+      import { createAgent } from '@linuxdevil/lousho';
 
       /** Where relative paths in the spec start, and how named secrets resolve (environment variables here). */
       const host = { baseDir: path.dirname(fileURLToPath(import.meta.url)), resolveSecret: (name: string) => process.env[name] };
@@ -116,7 +116,7 @@ describe('specToCode', () => {
     expect(importLines(code)).toEqual([
       "import path from 'node:path';",
       "import { fileURLToPath } from 'node:url';",
-      "import { createAgent, resolveToolRef } from 'lousho';",
+      "import { createAgent, resolveToolRef } from '@linuxdevil/lousho';",
     ]);
   });
 
diff --git a/src/spec/generators/typescript.ts b/src/spec/generators/typescript.ts
index 242a80b1c..f7f989175 100644
--- a/src/spec/generators/typescript.ts
+++ b/src/spec/generators/typescript.ts
@@ -15,7 +15,7 @@ import { toTsLiteral, tsObjectKey } from './tsLiteral';
 
 /** specToCode() options. */
 export interface SpecToCodeOptions {
-  /** Import specifier the SDK is imported from in the generated module. Default 'lousho'. */
+  /** Import specifier the SDK is imported from in the generated module. Default '@linuxdevil/lousho'. */
   packageName?: string;
 }
 
@@ -299,10 +299,10 @@ function specKeysTrailer(spec: AgentSpecV2): string[] | undefined {
  * Deterministic: two calls with the same spec return identical strings, and
  * the option order follows KEY_ORDER regardless of the input's key order.
  * `options.packageName` overrides the specifier the SDK is imported from
- * (default 'lousho').
+ * (default '@linuxdevil/lousho').
  */
 export function specToCode(spec: AgentSpecV2, options?: SpecToCodeOptions): string {
-  const packageName = options?.packageName ?? 'lousho';
+  const packageName = options?.packageName ?? '@linuxdevil/lousho';
   const ctx: RenderContext = { imports: new Set(), subagentsConst: needsHandoffResolver(spec) && spec.subagents !== undefined };
 
   const optionLines: string[] = [];
diff --git a/src/spec/schema.ts b/src/spec/schema.ts
index 379bc8c61..c987b6132 100644
--- a/src/spec/schema.ts
+++ b/src/spec/schema.ts
@@ -105,7 +105,7 @@ export interface McpOAuthOptions {
   /** The secret of a confidential pre-registered client. */
   clientSecret?: string;
   scopes?: readonly string[];
-  /** Shown on the consent screen when registering. Default `'lousho'`. */
+  /** Shown on the consent screen when registering. Default `'@linuxdevil/lousho'`. */
   clientName?: string;
 }
 
@@ -141,7 +141,7 @@ export interface McpHttpServerSpec {
  */
 export type McpServerSpec = McpStdioServerSpec | McpHttpServerSpec;
 
-/** The v1 agent spec shape (a `.yaml`/`.json` agent file); v2 specs use `AgentSpecV2` (`lousho/spec`). */
+/** The v1 agent spec shape (a `.yaml`/`.json` agent file); v2 specs use `AgentSpecV2` (`@linuxdevil/lousho/spec`). */
 export interface AgentSpec {
   /** Agent name. */
   name: string;
@@ -345,5 +345,5 @@ export const agentSpecProviderSchema = providerSchema as unknown as SpecSchema<A
 export const agentSpecPolicySchema = policySchema as unknown as SpecSchema<AgentSpecPolicy>;
 export const agentSpecTriggerSchema = triggerSchema as unknown as SpecSchema<AgentSpecTrigger>;
 export const mcpServerSpecSchema = mcpServerSchema as unknown as SpecSchema<McpServerSpec>;
-/** The v1 agent spec schema (zod): what `loadSpec()` and `lousho/spec`'s `agentSpecSchema` validate against. */
+/** The v1 agent spec schema (zod): what `loadSpec()` and `@linuxdevil/lousho/spec`'s `agentSpecSchema` validate against. */
 export const agentSpecSchema = specSchema as unknown as SpecObjectSchema<AgentSpec>;
diff --git a/src/spec/specToAgent.ts b/src/spec/specToAgent.ts
index c17ab67de..6de40528d 100644
--- a/src/spec/specToAgent.ts
+++ b/src/spec/specToAgent.ts
@@ -46,7 +46,7 @@ export function resolveSpecTool(name: string): ToolDescriptor {
     throw new ConfigurationError(
       `specToAgent: tool '${name}' needs credentials: build it with ` +
         `create${name === 'github' ? 'GitHub' : 'Jira'}Tools(config) from ` +
-        `'lousho/integrations' and pass it to createAgent(); an AgentSpec has no ` +
+        `'@linuxdevil/lousho/integrations' and pass it to createAgent(); an AgentSpec has no ` +
         `field for credentials.`,
       'tools',
       'LOUSHO_TOOL_NEEDS_CREDENTIALS'
diff --git a/src/spec/v2/index.test.ts b/src/spec/v2/index.test.ts
index af46854ff..e00e71c08 100644
--- a/src/spec/v2/index.test.ts
+++ b/src/spec/v2/index.test.ts
@@ -1,8 +1,8 @@
 /**
- * S23: `lousho/spec` must bundle for a browser consumer (Studio's Vite
+ * S23: `@linuxdevil/lousho/spec` must bundle for a browser consumer (Studio's Vite
  * build), so nothing in its import graph may import a `node:` path or
  * resolve to a module a browser bundler cannot reach. This guards the
- * barrel's graph the way `src/deploy/kv.test.ts` guards `lousho/kv`.
+ * barrel's graph the way `src/deploy/kv.test.ts` guards `@linuxdevil/lousho/kv`.
  */
 import { afterAll, describe, expect, it } from 'vitest';
 import { build, stop } from 'esbuild';
@@ -12,7 +12,7 @@ import * as spec from './index';
 // esbuild keeps a service process alive after build(); end it so it does not outlive this file.
 afterAll(() => stop());
 
-describe('lousho/spec (S23)', () => {
+describe('@linuxdevil/lousho/spec (S23)', () => {
   it('bundles for the browser platform with no node: import in its graph', async () => {
     const result = await build({
       entryPoints: [join(__dirname, 'index.ts')],
diff --git a/src/spec/v2/index.ts b/src/spec/v2/index.ts
index cae13ecee..5632460d7 100644
--- a/src/spec/v2/index.ts
+++ b/src/spec/v2/index.ts
@@ -1,5 +1,5 @@
 /**
- * The browser-safe spec layer of the SDK (`lousho/spec`): the AgentSpec v1
+ * The browser-safe spec layer of the SDK (`@linuxdevil/lousho/spec`): the AgentSpec v1
  * and v2 schemas, their hand-written types and the pure helpers Studio
  * needs in both its browser and server bundles — catalogs, the v1→v2
  * upgrader, the JSON Schema export, the `specToCode` generator, node-id and
diff --git a/src/storage/sqlite/SqliteStore.ts b/src/storage/sqlite/SqliteStore.ts
index bb59fe6af..c01f23823 100644
--- a/src/storage/sqlite/SqliteStore.ts
+++ b/src/storage/sqlite/SqliteStore.ts
@@ -47,7 +47,7 @@ export interface PruneResult {
  *
  * @example
  * ```ts
- * import { SqliteStore } from 'lousho/sqlite';
+ * import { SqliteStore } from '@linuxdevil/lousho/sqlite';
  *
  * const store = new SqliteStore('./.lousho/agent.db'); // or ':memory:'
  * const session = agent.session({ id: 'user-42', store: store.sessions });
diff --git a/src/storage/sqlite/driver.ts b/src/storage/sqlite/driver.ts
index a43ed9bbd..70304fa68 100644
--- a/src/storage/sqlite/driver.ts
+++ b/src/storage/sqlite/driver.ts
@@ -2,7 +2,7 @@ import { SDKError } from '../../execution/errors';
 /**
  * Minimal structural types for the parts of `node:sqlite` this package uses,
  * plus the lazy loader. `@types/node` older than 22.5 has no `node:sqlite`
- * typings, and loading it lazily keeps `import 'lousho/sqlite'`
+ * typings, and loading it lazily keeps `import '@linuxdevil/lousho/sqlite'`
  * safe on Node versions that lack it.
  */
 
diff --git a/src/storage/sqlite/index.ts b/src/storage/sqlite/index.ts
index 89bc2b7ef..16e338100 100644
--- a/src/storage/sqlite/index.ts
+++ b/src/storage/sqlite/index.ts
@@ -1,5 +1,5 @@
 /**
- * `lousho/sqlite`: one SQLite file for sessions, checkpoints
+ * `@linuxdevil/lousho/sqlite`: one SQLite file for sessions, checkpoints
  * and approvals. Deliberately NOT re-exported from the root entry.
  */
 export { SqliteStore } from './SqliteStore';
diff --git a/src/storage/sqlite/sqliteMemory.ts b/src/storage/sqlite/sqliteMemory.ts
index fb8439d7e..0f0292239 100644
--- a/src/storage/sqlite/sqliteMemory.ts
+++ b/src/storage/sqlite/sqliteMemory.ts
@@ -13,7 +13,7 @@ import { Statements } from './stores';
  *
  * @example
  * ```ts
- * import { SqliteStore, sqliteMemory } from 'lousho/sqlite';
+ * import { SqliteStore, sqliteMemory } from '@linuxdevil/lousho/sqlite';
  *
  * const store = new SqliteStore('./.lousho/agent.db');
  * const prefs = defineMemory({ name: 'prefs', scope: 'global', provider: sqliteMemory(store) });
diff --git a/src/storage/sqlite/sqliteVectorMemory.ts b/src/storage/sqlite/sqliteVectorMemory.ts
index f2479ddd8..03c63e807 100644
--- a/src/storage/sqlite/sqliteVectorMemory.ts
+++ b/src/storage/sqlite/sqliteVectorMemory.ts
@@ -23,7 +23,7 @@ function decode(bytes: unknown, dimensions: number): Float32Array {
  *
  * @example
  * ```ts
- * import { SqliteStore, sqliteVectorMemory } from 'lousho/sqlite';
+ * import { SqliteStore, sqliteVectorMemory } from '@linuxdevil/lousho/sqlite';
  *
  * const store = new SqliteStore('./.lousho/agent.db');
  * const facts = sqliteVectorMemory(store, { embedder: aiSdkEmbedder(openai.embedding('text-embedding-3-small')) });
diff --git a/src/subagents/piAgent.ts b/src/subagents/piAgent.ts
index f6eb3e991..150031fa2 100644
--- a/src/subagents/piAgent.ts
+++ b/src/subagents/piAgent.ts
@@ -509,7 +509,7 @@ function settle(session: PiSession, gate: ReturnType<typeof makeGate>, ctx: PiRu
  *
  * @example
  * ```ts
- * import { piAgent } from 'lousho';
+ * import { piAgent } from '@linuxdevil/lousho';
  *
  * const lead = createAgent({
  *   model: 'openai/gpt-4o-mini',
diff --git a/src/svelte/index.ts b/src/svelte/index.ts
index dcbdafa86..d76d81460 100644
--- a/src/svelte/index.ts
+++ b/src/svelte/index.ts
@@ -1,5 +1,5 @@
 /**
- * `lousho/svelte`: the `loushoAgent()` store, and the
+ * `@linuxdevil/lousho/svelte`: the `loushoAgent()` store, and the
  * framework-neutral reducer and stream parser it is built on.
  */
 
diff --git a/src/svelte/svelte.test-d.ts b/src/svelte/svelte.test-d.ts
index 44499d5aa..ea8c03590 100644
--- a/src/svelte/svelte.test-d.ts
+++ b/src/svelte/svelte.test-d.ts
@@ -1,5 +1,5 @@
 /**
- * The public types of `lousho/svelte`.
+ * The public types of `@linuxdevil/lousho/svelte`.
  */
 import { describe, it, expectTypeOf } from 'vitest';
 import { createAgent } from '../createAgent';
@@ -7,7 +7,7 @@ import { createMockProvider } from '../providers/mock';
 import type { AgentInput } from '../providers/content';
 import { loushoAgent, loushoTodos, type TodoView, type AgentUIState, type LoushoAgentSource, type LoushoAgentStore } from './index';
 
-describe('lousho/svelte types', () => {
+describe('@linuxdevil/lousho/svelte types', () => {
   it('takes an in-process agent or a URL as the source', () => {
     const agent = createAgent({ provider: createMockProvider() });
     expectTypeOf({ agent, sessionId: 'chat-1' }).toMatchTypeOf<LoushoAgentSource>();
diff --git a/src/testing/cassette.ts b/src/testing/cassette.ts
index 9c2d32421..657bbaa53 100644
--- a/src/testing/cassette.ts
+++ b/src/testing/cassette.ts
@@ -214,7 +214,7 @@ function readSdkVersion(): string {
         name?: string;
         version?: string;
       };
-      if (manifest.name === 'lousho' && manifest.version) return manifest.version;
+      if (manifest.name === '@linuxdevil/lousho' && manifest.version) return manifest.version;
     } catch {
       // keep walking up
     }
diff --git a/src/testing/index.ts b/src/testing/index.ts
index f20b99ff6..6905e7126 100644
--- a/src/testing/index.ts
+++ b/src/testing/index.ts
@@ -1,5 +1,5 @@
 /**
- * `lousho/testing` - test doubles for agents.
+ * `@linuxdevil/lousho/testing` - test doubles for agents.
  *
  * Re-exports the in-memory repository mocks, the scripted `mockModel` and the
  * `recordReplay` VCR provider.
diff --git a/src/testing/mockModel.ts b/src/testing/mockModel.ts
index daf0fedad..06a6289a9 100644
--- a/src/testing/mockModel.ts
+++ b/src/testing/mockModel.ts
@@ -56,7 +56,7 @@ export interface MockToolCall {
  *
  * @example
  * ```ts
- * const call: MockHostedToolCall = { name: 'web_search', args: { query: 'lousho' }, result: { results: [] } };
+ * const call: MockHostedToolCall = { name: 'web_search', args: { query: '@linuxdevil/lousho' }, result: { results: [] } };
  * ```
  */
 export interface MockHostedToolCall {
@@ -406,7 +406,7 @@ class ScriptedMockModel implements MockModel {
  *
  * @example
  * ```ts
- * import { mockModel } from 'lousho/testing';
+ * import { mockModel } from '@linuxdevil/lousho/testing';
  *
  * const model = mockModel([
  *   { toolCalls: [{ name: 'get_weather', args: { city: 'Paris' } }] },
diff --git a/src/testing/recordReplay.ts b/src/testing/recordReplay.ts
index a4fb2ff7a..d84613776 100644
--- a/src/testing/recordReplay.ts
+++ b/src/testing/recordReplay.ts
@@ -509,7 +509,7 @@ function resolveMode(options: RecordReplayOptions): 'record' | 'replay' {
  *
  * @example
  * ```ts
- * import { recordReplay } from 'lousho/testing';
+ * import { recordReplay } from '@linuxdevil/lousho/testing';
  *
  * const provider = recordReplay(() => resolveProvider('openai/gpt-4o-mini'), {
  *   cassette: './__cassettes__/refund-flow.json',
diff --git a/src/tools/approvalPolicies.ts b/src/tools/approvalPolicies.ts
index 9ae5df8c3..bbc9432c9 100644
--- a/src/tools/approvalPolicies.ts
+++ b/src/tools/approvalPolicies.ts
@@ -36,7 +36,7 @@ export function never(): false {
  *
  * @example
  * ```ts
- * import { defineTool, once } from 'lousho';
+ * import { defineTool, once } from '@linuxdevil/lousho';
  * import { z } from 'zod';
  *
  * const deploy = defineTool({
diff --git a/src/tools/built-in/index.ts b/src/tools/built-in/index.ts
index cb5ec98cc..844b10f46 100644
--- a/src/tools/built-in/index.ts
+++ b/src/tools/built-in/index.ts
@@ -8,6 +8,6 @@ export * from './dayName';
 export * from './http';
 export { webFetchTool, createWebFetchTool, type WebFetchToolOptions, type WebFetchResult } from './webFetch';
 // The credentialed integrations (email, jira, github, slack) moved to
-// 'lousho/integrations' (src/integrations/index.ts).
+// '@linuxdevil/lousho/integrations' (src/integrations/index.ts).
 export * from './todo';
 export { askQuestionTool, type AskQuestionInput, type AskQuestionResult } from './askQuestion';
diff --git a/src/tools/index.ts b/src/tools/index.ts
index c5207a64c..f47c6ee58 100644
--- a/src/tools/index.ts
+++ b/src/tools/index.ts
@@ -1,4 +1,4 @@
 export * from './rootTools';
 // ToolRegistry / globalToolRegistry left the root for
-// 'lousho/executor' but stay on this subpath.
+// '@linuxdevil/lousho/executor' but stay on this subpath.
 export * from './ToolRegistry';
diff --git a/src/tools/mcp/mcpOAuth.test.ts b/src/tools/mcp/mcpOAuth.test.ts
index 7978239a7..5892da393 100644
--- a/src/tools/mcp/mcpOAuth.test.ts
+++ b/src/tools/mcp/mcpOAuth.test.ts
@@ -127,7 +127,7 @@ describe('MCP servers with OAuth', () => {
     expect(params.get('redirect_uri')).toBe(REDIRECT);
     expect(server.registrations).toBe(1);
     expect(JSON.parse(server.requests.find((request) => request.path === '/register')?.body ?? '{}')).toMatchObject({
-      client_name: 'lousho',
+      client_name: '@linuxdevil/lousho',
       redirect_uris: [REDIRECT],
       grant_types: ['authorization_code', 'refresh_token'],
       response_types: ['code'],
diff --git a/src/tools/mcp/mcpOAuth.ts b/src/tools/mcp/mcpOAuth.ts
index 8cf7b6c90..b4b2d8e6d 100644
--- a/src/tools/mcp/mcpOAuth.ts
+++ b/src/tools/mcp/mcpOAuth.ts
@@ -166,7 +166,7 @@ export function storeOAuthProvider(server: string, spec: McpOAuthServerSpec, sto
   return {
     redirectUrl: oauth.redirectUri,
     clientMetadata: {
-      client_name: oauth.clientName ?? 'lousho',
+      client_name: oauth.clientName ?? '@linuxdevil/lousho',
       redirect_uris: [oauth.redirectUri],
       grant_types: ['authorization_code', 'refresh_token'],
       response_types: ['code'],
diff --git a/src/tools/rootTools.ts b/src/tools/rootTools.ts
index 1d81ab635..7061bd606 100644
--- a/src/tools/rootTools.ts
+++ b/src/tools/rootTools.ts
@@ -1,8 +1,8 @@
 /**
  * The tool exports of the package root: everything `src/tools/index.ts`
  * re-exports except `ToolRegistry` / `globalToolRegistry`, which moved to
- * `lousho/executor` (they are also still here, on
- * `lousho/tools`, for the `JiraTools` / `GitHubTools`
+ * `@linuxdevil/lousho/executor` (they are also still here, on
+ * `@linuxdevil/lousho/tools`, for the `JiraTools` / `GitHubTools`
  * subclasses and the `/tools` subpath).
  */
 export * from './defineTool';
diff --git a/src/tools/workspace/MemoryWorkspace.ts b/src/tools/workspace/MemoryWorkspace.ts
index 01da77882..c90c76b9a 100644
--- a/src/tools/workspace/MemoryWorkspace.ts
+++ b/src/tools/workspace/MemoryWorkspace.ts
@@ -45,7 +45,7 @@ function byteLength(text: string): number {
  *
  * @example
  * ```ts
- * import { MemoryWorkspace } from 'lousho';
+ * import { MemoryWorkspace } from '@linuxdevil/lousho';
  * const ws = new MemoryWorkspace({
  *   files: { 'src/a.ts': 'export const a = 1;\n' },
  *   exec: (command) => (command === 'npm test' ? { stdout: 'ok\n' } : { exitCode: 1, stderr: 'unknown\n' }),
diff --git a/src/tools/workspace/NodeWorkspace.ts b/src/tools/workspace/NodeWorkspace.ts
index 1d86b03e9..3e2584ced 100644
--- a/src/tools/workspace/NodeWorkspace.ts
+++ b/src/tools/workspace/NodeWorkspace.ts
@@ -110,7 +110,7 @@ function resolveRoot(root: string | undefined): string {
  *
  * @example
  * ```ts
- * import { NodeWorkspace, createFsTools, createShellTool } from 'lousho';
+ * import { NodeWorkspace, createFsTools, createShellTool } from '@linuxdevil/lousho';
  * const workspace = new NodeWorkspace({ root: '.' });
  * const tools = [...createFsTools(workspace), createShellTool(workspace)];
  * ```
diff --git a/src/tools/workspace/SandboxShell.ts b/src/tools/workspace/SandboxShell.ts
index 9e43c61a2..77f300a3e 100644
--- a/src/tools/workspace/SandboxShell.ts
+++ b/src/tools/workspace/SandboxShell.ts
@@ -54,7 +54,7 @@ function joinCwd(base: string | undefined, sub: string | undefined): string | un
  *
  * @example
  * ```ts
- * import { createShellTool, SandboxShell, SubprocessSandbox } from 'lousho';
+ * import { createShellTool, SandboxShell, SubprocessSandbox } from '@linuxdevil/lousho';
  * const shell = new SandboxShell(new SubprocessSandbox({ image: 'node:20-alpine' }), { cwd: '/abs/path/to/project' });
  * const tool = createShellTool(shell, { needsApproval: false });
  * ```
diff --git a/src/tools/workspace/checkpointFileStore.ts b/src/tools/workspace/checkpointFileStore.ts
index 652b920f6..7a2b38db7 100644
--- a/src/tools/workspace/checkpointFileStore.ts
+++ b/src/tools/workspace/checkpointFileStore.ts
@@ -52,7 +52,7 @@ function isLog(value: unknown): value is WorkspaceCheckpointLog {
  *
  * @example
  * ```ts
- * import { FileWorkspaceCheckpointStore, NodeWorkspace, WorkspaceCheckpoints } from 'lousho';
+ * import { FileWorkspaceCheckpointStore, NodeWorkspace, WorkspaceCheckpoints } from '@linuxdevil/lousho';
  * const workspace = new NodeWorkspace({ root: '.' });
  * const checkpoints = new WorkspaceCheckpoints(workspace, { store: new FileWorkspaceCheckpointStore('.lousho/rewind') });
  * ```
diff --git a/src/tools/workspace/checkpoints.ts b/src/tools/workspace/checkpoints.ts
index 12dccb831..61d17ede0 100644
--- a/src/tools/workspace/checkpoints.ts
+++ b/src/tools/workspace/checkpoints.ts
@@ -233,8 +233,8 @@ function groupByPath(backups: readonly WorkspaceFileBackup[]): Map<string, Works
  *
  * @example
  * ```ts
- * import { createAgent, createFsTools, MemoryWorkspace, WorkspaceCheckpoints } from 'lousho';
- * import { mockModel } from 'lousho/testing';
+ * import { createAgent, createFsTools, MemoryWorkspace, WorkspaceCheckpoints } from '@linuxdevil/lousho';
+ * import { mockModel } from '@linuxdevil/lousho/testing';
  * const workspace = new MemoryWorkspace({ files: { 'a.txt': 'one\n' } });
  * const checkpoints = new WorkspaceCheckpoints(workspace);
  * const agent = createAgent({
diff --git a/src/tools/workspace/fsTools.ts b/src/tools/workspace/fsTools.ts
index 0acd44c6a..4cabd5518 100644
--- a/src/tools/workspace/fsTools.ts
+++ b/src/tools/workspace/fsTools.ts
@@ -288,8 +288,8 @@ function mutatingTools(links: LinkGuard, limits: FsLimits, approvals: FsToolAppr
  *
  * @example
  * ```ts
- * import { createAgent, createFsTools, MemoryWorkspace } from 'lousho';
- * import { mockModel } from 'lousho/testing';
+ * import { createAgent, createFsTools, MemoryWorkspace } from '@linuxdevil/lousho';
+ * import { mockModel } from '@linuxdevil/lousho/testing';
  * const workspace = new MemoryWorkspace({ files: { 'notes.md': '# Notes\n' } });
  * const agent = createAgent({
  *   instructions: 'You edit files in the workspace.',
diff --git a/src/tools/workspace/shellTool.ts b/src/tools/workspace/shellTool.ts
index f36f0ac5a..a766be556 100644
--- a/src/tools/workspace/shellTool.ts
+++ b/src/tools/workspace/shellTool.ts
@@ -301,7 +301,7 @@ function toToolResult(result: ShellExecResult, timeoutMs: number, maxChars: numb
  *
  * @example
  * ```ts
- * import { createShellTool, NodeWorkspace } from 'lousho';
+ * import { createShellTool, NodeWorkspace } from '@linuxdevil/lousho';
  * const workspace = new NodeWorkspace({ root: '.' });
  * const shell = createShellTool(workspace, {
  *   needsApproval: (command) => !command.startsWith('git status'),
diff --git a/src/tools/workspace/types.ts b/src/tools/workspace/types.ts
index 0a1dcb4b9..a04c0353d 100644
--- a/src/tools/workspace/types.ts
+++ b/src/tools/workspace/types.ts
@@ -39,7 +39,7 @@ export interface WorkspaceDirEntry {
  *
  * @example
  * ```ts
- * import type { FsProvider } from 'lousho';
+ * import type { FsProvider } from '@linuxdevil/lousho';
  * const files = new Map<string, string>();
  * const fsProvider: FsProvider = {
  *   async readFile(path) { const c = files.get(path); if (c === undefined) throw new Error(`File not found: ${path}`); return c; },
@@ -128,7 +128,7 @@ export interface ShellExecResult {
  *
  * @example
  * ```ts
- * import type { ShellProvider } from 'lousho';
+ * import type { ShellProvider } from '@linuxdevil/lousho';
  * const echoShell: ShellProvider = {
  *   async exec(command) {
  *     return { stdout: `would run: ${command}\n`, stderr: '', exitCode: 0, timedOut: false };
diff --git a/src/traces/fileTraceExporter.ts b/src/traces/fileTraceExporter.ts
index 4b1a742d4..1938d8afe 100644
--- a/src/traces/fileTraceExporter.ts
+++ b/src/traces/fileTraceExporter.ts
@@ -79,8 +79,8 @@ function lineOf(span: Span, traceId: string): TraceLine {
  *
  * @example
  * ```ts
- * import { createAgent } from 'lousho';
- * import { fileTraceExporter } from 'lousho/traces';
+ * import { createAgent } from '@linuxdevil/lousho';
+ * import { fileTraceExporter } from '@linuxdevil/lousho/traces';
  *
  * const agent = createAgent({ model: 'openai/gpt-4o-mini', exporter: fileTraceExporter() });
  * ```
diff --git a/src/traces/index.ts b/src/traces/index.ts
index ddbed09bd..080283776 100644
--- a/src/traces/index.ts
+++ b/src/traces/index.ts
@@ -1,5 +1,5 @@
 /**
- * `lousho/traces`: local trace files for `lousho traces`.
+ * `@linuxdevil/lousho/traces`: local trace files for `lousho traces`.
  * A subpath of its own because it uses `node:fs`.
  */
 export { fileTraceExporter, type FileTraceExporterOptions } from './fileTraceExporter';
diff --git a/src/traces/readTraces.ts b/src/traces/readTraces.ts
index 6640d6d89..19288b942 100644
--- a/src/traces/readTraces.ts
+++ b/src/traces/readTraces.ts
@@ -163,7 +163,7 @@ function summarize(entry: TraceFile, lines: TraceLine[]): TraceSummary | undefin
  *
  * @example
  * ```ts
- * import { listTraces } from 'lousho/traces';
+ * import { listTraces } from '@linuxdevil/lousho/traces';
  * const [latest] = await listTraces({ limit: 1 });
  * ```
  */
@@ -196,7 +196,7 @@ export function findTraces(idOrPrefix: string, options: { dir?: string } = {}):
  *
  * @example
  * ```ts
- * import { readTrace } from 'lousho/traces';
+ * import { readTrace } from '@linuxdevil/lousho/traces';
  * const spans = await readTrace('k3f9');
  * ```
  */
diff --git a/src/triggers/index.ts b/src/triggers/index.ts
index 2fe01d39d..3d3928b2a 100644
--- a/src/triggers/index.ts
+++ b/src/triggers/index.ts
@@ -1,7 +1,7 @@
 /**
  * Trigger adapters module
  *
- * Public surface for `lousho/triggers`: the TriggerAdapter
+ * Public surface for `@linuxdevil/lousho/triggers`: the TriggerAdapter
  * interface, TriggerRegistry, and the three built-in adapters
  * (webhook/cron/slack). See types.ts for the full design rationale.
  */
diff --git a/src/types/index.ts b/src/types/index.ts
index 2fbc09bd2..bd9ce526c 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -1,4 +1,4 @@
 // './common' and './repository' removed (nothing implemented or used them).
 export * from './agent';
 export * from './tool';
-// './flow' moved to 'lousho/flows'.
+// './flow' moved to '@linuxdevil/lousho/flows'.
diff --git a/src/utils/index.ts b/src/utils/index.ts
index 682405d2e..8756bcdf5 100644
--- a/src/utils/index.ts
+++ b/src/utils/index.ts
@@ -1,6 +1,6 @@
 /**
  * Utilities
- * The `lousho/utils` subpath: encryption, the StorageService
+ * The `@linuxdevil/lousho/utils` subpath: encryption, the StorageService
  * and the stores built on it, and the small validators. These used to ship
  * on the package root; the error helpers (`errors`, `errorCodes`) stayed on
  * the root and are NOT re-exported here.
diff --git a/src/vue/index.ts b/src/vue/index.ts
index 7e53db7c6..a1a4c5866 100644
--- a/src/vue/index.ts
+++ b/src/vue/index.ts
@@ -1,5 +1,5 @@
 /**
- * `lousho/vue`: the `useLoushoAgent()` composable,
+ * `@linuxdevil/lousho/vue`: the `useLoushoAgent()` composable,
  * and the framework-neutral reducer and stream parser it is built on.
  */
 
diff --git a/src/vue/vue.test-d.ts b/src/vue/vue.test-d.ts
index 6e8654a4a..b62abb6b7 100644
--- a/src/vue/vue.test-d.ts
+++ b/src/vue/vue.test-d.ts
@@ -1,5 +1,5 @@
 /**
- * The public types of `lousho/vue`.
+ * The public types of `@linuxdevil/lousho/vue`.
  */
 import { describe, it, expectTypeOf } from 'vitest';
 import type { ComputedRef, Ref } from 'vue';
@@ -21,7 +21,7 @@ import {
   type UseLoushoAgentResult,
 } from './index';
 
-describe('lousho/vue types', () => {
+describe('@linuxdevil/lousho/vue types', () => {
   it('accepts an in-process agent or a URL as the source, plain or as a ref', () => {
     const agent = createAgent({ provider: createMockProvider() });
     expectTypeOf({ agent, sessionId: 'chat-1' }).toMatchTypeOf<LoushoAgentSource>();
diff --git a/src/workspaces/gates/g9.embed.test.ts b/src/workspaces/gates/g9.embed.test.ts
index 744254743..852a27cbb 100644
--- a/src/workspaces/gates/g9.embed.test.ts
+++ b/src/workspaces/gates/g9.embed.test.ts
@@ -561,7 +561,7 @@ describe('G9 static checks', () => {
     expect(findings).toEqual([]);
   });
 
-  it('lousho/workspaces/client pulls in no crypto and no quickjs', () => {
+  it('@linuxdevil/lousho/workspaces/client pulls in no crypto and no quickjs', () => {
     const graph = moduleGraph([join(REPO, 'src/workspaces/client/index.ts')]);
     expect([...graph.bare].filter((spec) => /^(?:node:)?crypto$|quickjs/.test(spec))).toEqual([]);
     expect([...graph.files].map((file) => relative(REPO, file)).filter((file) => file.startsWith('apps/'))).toEqual([]);
diff --git a/tsconfig.json b/tsconfig.json
index e7f51d944..7947eb3c3 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -22,32 +22,32 @@
     "noFallthroughCasesInSwitch": true,
     "types": ["node"],
     "paths": {
-      "lousho": ["./src/index.ts"],
-      "lousho/executor": ["./src/executor/index.ts"],
-      "lousho/tools": ["./src/tools/index.ts"],
-      "lousho/flows": ["./src/flows/index.ts"],
-      "lousho/integrations": ["./src/integrations/index.ts"],
-      "lousho/utils": ["./src/utils/index.ts"],
-      "lousho/improve": ["./src/improve/index.ts"],
-      "lousho/goals": ["./src/goals/index.ts"],
-      "lousho/workspaces": ["./src/workspaces/index.ts"],
-      "lousho/workspaces/client": ["./src/workspaces/client/index.ts"],
-      "lousho/mcp": ["./src/tools/mcp/index.ts"],
-      "lousho/observe": ["./src/observe/index.ts"],
-      "lousho/types": ["./src/types/index.ts"],
-      "lousho/spec": ["./src/spec/v2/index.ts"],
-      "lousho/testing": ["./src/testing/index.ts"],
-      "lousho/otel": ["./src/execution/otel.ts"],
-      "lousho/hooks": ["./src/execution/hooks.ts"],
-      "lousho/sqlite": ["./src/storage/sqlite/index.ts"],
-      "lousho/auth": ["./src/auth/index.ts"],
-      "lousho/kv": ["./src/deploy/kv.ts"],
-      "lousho/worker": ["./src/deploy/worker.ts"],
-      "lousho/traces": ["./src/traces/index.ts"],
-      "lousho/triggers": ["./src/triggers/index.ts"],
-      "lousho/react": ["./src/react/index.ts"],
-      "lousho/vue": ["./src/vue/index.ts"],
-      "lousho/svelte": ["./src/svelte/index.ts"]
+      "@linuxdevil/lousho": ["./src/index.ts"],
+      "@linuxdevil/lousho/executor": ["./src/executor/index.ts"],
+      "@linuxdevil/lousho/tools": ["./src/tools/index.ts"],
+      "@linuxdevil/lousho/flows": ["./src/flows/index.ts"],
+      "@linuxdevil/lousho/integrations": ["./src/integrations/index.ts"],
+      "@linuxdevil/lousho/utils": ["./src/utils/index.ts"],
+      "@linuxdevil/lousho/improve": ["./src/improve/index.ts"],
+      "@linuxdevil/lousho/goals": ["./src/goals/index.ts"],
+      "@linuxdevil/lousho/workspaces": ["./src/workspaces/index.ts"],
+      "@linuxdevil/lousho/workspaces/client": ["./src/workspaces/client/index.ts"],
+      "@linuxdevil/lousho/mcp": ["./src/tools/mcp/index.ts"],
+      "@linuxdevil/lousho/observe": ["./src/observe/index.ts"],
+      "@linuxdevil/lousho/types": ["./src/types/index.ts"],
+      "@linuxdevil/lousho/spec": ["./src/spec/v2/index.ts"],
+      "@linuxdevil/lousho/testing": ["./src/testing/index.ts"],
+      "@linuxdevil/lousho/otel": ["./src/execution/otel.ts"],
+      "@linuxdevil/lousho/hooks": ["./src/execution/hooks.ts"],
+      "@linuxdevil/lousho/sqlite": ["./src/storage/sqlite/index.ts"],
+      "@linuxdevil/lousho/auth": ["./src/auth/index.ts"],
+      "@linuxdevil/lousho/kv": ["./src/deploy/kv.ts"],
+      "@linuxdevil/lousho/worker": ["./src/deploy/worker.ts"],
+      "@linuxdevil/lousho/traces": ["./src/traces/index.ts"],
+      "@linuxdevil/lousho/triggers": ["./src/triggers/index.ts"],
+      "@linuxdevil/lousho/react": ["./src/react/index.ts"],
+      "@linuxdevil/lousho/vue": ["./src/vue/index.ts"],
+      "@linuxdevil/lousho/svelte": ["./src/svelte/index.ts"]
     }
   },
   "include": ["src/**/*", "typings/**/*.d.ts"],
diff --git a/tsup.config.ts b/tsup.config.ts
index 9c48dd093..52790e71b 100644
--- a/tsup.config.ts
+++ b/tsup.config.ts
@@ -99,7 +99,7 @@ export default defineConfig([
   },
   {
     /**
-     * The Worker-safe `lousho/worker` entry (#289), built
+     * The Worker-safe `@linuxdevil/lousho/worker` entry (#289), built
      * with the same shims `lousho build --target=cloudflare-worker` applies,
      * so the published file has no `node:` import for a hand-written
      * Worker's bundler to fail on. A separate config because the plugins