@plurnk/plurnk-service 0.6.0 → 0.8.0

package/SPEC.md

@@ -90,6 +90,27 @@ Three independent axes on entries and channels. Confusion across them is a recur
 
 ## §1 Architecture
 
+### §1.1 Ecosystem
+
+The plurnk project is a modular monorepo-of-repos in the `@plurnk/*` npm namespace. Each repo has one published package and one agent who owns it; cross-repo coordination happens through issues, not shared code. This service sits in the middle of that ecosystem and is its **runtime substrate** — the daemon other repos plug into.
+
+Dependency direction (from root to leaf):
+
+- **`plurnk-grammar`** — root. Owns the JSON-Schema contracts (Packet, TelemetryEvent, AST shapes), the ANTLR parser that turns model output into `PlurnkStatement[]`, and `PlurnkParseError` with its `toTelemetryEvent()` helper. Nothing in the ecosystem can speak the DSL without it; everything else pins it exactly.
+- **Framework siblings** consume grammar and define their own author-facing contracts:
+    - `plurnk-providers` — Provider/Alias types, `parseAliasesFromEnv`, `resolveActiveAlias`, `Mock`, `ProviderUsage` (currency-aware, includes `reasoning`). Vendor-specific implementations are children: `plurnk-providers-openai`, `-google`, `-ollama`, `-openrouter`, `-cloudflare`, `-xai`.
+    - `plurnk-mimetypes` — handler base classes, discovery, fitting algorithm, matcher dispatch. Handler children are per-mimetype: `plurnk-mimetypes-text-{python,typescript,markdown,html,csv,plain}`, `plurnk-mimetypes-application-{json,yaml,toml,pdf}`, …
+    - `plurnk-schemes` — scheme-author types (`SchemeManifest`, `WriterTier`, `LoopFlags`), result-shape contracts (`EntryResult` / `ProposalResult` / `PassthroughResult`), slicing primitives, matcher helpers, `schemeError(...)` constructor. Future scheme children: `plurnk-schemes-http`, `plurnk-schemes-git`, …
+    - `plurnk-execs` — `BaseExecutor`, `SubprocessExecutor`, runtime resolver, discovery. Children declare runtimes: `plurnk-execs-sh`, future `plurnk-execs-search`, `plurnk-execs-node`, …
+- **`plurnk-service`** (this repo) — consumes all of the above. Implements the engine, dispatches ops through scheme handlers, hosts the in-tree set of schemes (`plurnk`, `log`, `exec`, `known`, `unknown`, `skill`, `file`), discovers installed mimetype handlers + provider vendors + executor siblings at boot, hosts the daemon (`bin/plurnk-service.js` over WebSocket + JSON-RPC), and projects packets to the wire per `Packet.json`. Most of the substantive runtime work lives here.
+- **`plurnk`** (client) — terminal UI consuming the daemon's RPC surface. Renders `telemetry/event` notifications, subscribes to log/stream/proposal events. No engine logic of its own.
+
+The grammar is the contract. The frameworks consume the contract and add author-facing surfaces. The service consumes the frameworks and runs the engine. The client consumes the service and renders to humans. Each tier is its own published package; each tier's evolution happens in its own repo.
+
+**This service's central role:** sole consumer of every author-facing framework contract (one set of integrations across the ecosystem), sole producer of the engine's runtime behavior (one canonical implementation of dispatch, log, packet wire), and sole orchestrator of cross-scheme operations (COPY/MOVE flow through engine-mediated `readEntry` / `writeEntry` / `deleteEntry`, never scheme-to-scheme). Most cross-repo coordination flows through us — we file the consumer-need issues at upstream repos, adopt their decisions, document the surface in SPEC.
+
+### §1.2 In-process architecture
+
 Engine library + admin CLI + daemon. Four plug points:
 
 - **Providers** (§2) — LLM transports. Engine sends a turn's messages, receives raw content + usage; engine parses the content into `PlurnkStatement[]`.
@@ -113,23 +134,23 @@ Author-facing contract: [plurnk-providers#1](https://github.com/plurnk/plurnk-pr
 
 Three entry points:
 
-- `provider.generate({messages, signal})` — once per turn; returns `{ assistant: { content, reasoning, usage, finishReason, model }, assistantRaw }`. **Engine parses `assistant.content`** into `PlurnkStatement[]` via `@plurnk/plurnk-grammar`.
-- `provider.countTokens(text)` — synchronous, called at write-time (§14.2) and render-time. Non-negative integer.
-- `provider.costFor(usage)` — once per completed turn; pico-USD. Engine writes to `turns.usage_cost_pico`; triggers cascade to `runs.cost_pico` / `sessions.cost_pico`.
+- `provider.generate({messages, signal})` — once per turn; returns `{ assistant: { content, reasoning, usage, finishReason, model }, assistantRaw }`. **Engine parses `assistant.content`** into `PlurnkStatement[]` via `@plurnk/plurnk-grammar`. {§2.1-generate}
+- `provider.countTokens(text)` — synchronous, called at write-time (§14.2) and render-time. Non-negative integer. {§2.1-counttokens}
+- `provider.costFor(usage)` — once per completed turn; pico-USD. Engine writes to `turns.usage_cost_pico`; triggers cascade to `runs.cost_pico` / `sessions.cost_pico`. {§2.1-costfor}
 
-Plus immutable identity: `provider.contextSize` (token total, or `null` → "no budget info") and `provider.model`.
+Plus immutable identity: `provider.contextSize` (token total, or `null` → "no budget info"), read by the budget {§2.1-identity}; and `provider.model` — the instance identity the deferred model-switch recompute compares (§14.2-hot-switch-recompute), exposed but not yet consumed here.
 
 ### §2.2 Engine → provider guarantees
 
 - `messages` is a complete prompt (`system_definition`, `persona`, `index`, `log`, `prompt`, `telemetry`, `system_requirements` pre-assembled). Provider does not reorder.
-- `signal` is wired to the run's AbortController.
-- `generate` is single-call per turn. No parallel calls on the same instance.
-- `assistantRaw` is opaque to the engine (forensics-only).
+- `signal` is wired to the run's AbortController. {§2.2-signal-wired}
+- `generate` is single-call per turn. No parallel calls on the same instance. {§2.2-single-call}
+- `assistantRaw` is opaque to the engine (forensics-only). {§2.2-assistantraw-opaque}
 - `countTokens` is cheap by contract; engine calls frequently.
 
 ### §2.3 Provider instantiation
 
-Model alias parsing (`parseAliasesFromEnv` / `resolveActiveAlias`) lives in [`@plurnk/plurnk-providers`](https://github.com/plurnk/plurnk-providers). Dynamic provider instantiation (`instantiateProvider` / `loadActiveProvider`) lives in `src/core/ProviderInstantiate.ts` here — `import()` resolves package specifiers relative to the calling module, so the dynamic-import path stays in the consumer where the `@plurnk/plurnk-providers-<vendor>` packages are installed.
+Model alias parsing (`parseAliasesFromEnv` / `resolveActiveAlias`) lives in [`@plurnk/plurnk-providers`](https://github.com/plurnk/plurnk-providers). {§2.3-alias-resolution} Dynamic provider instantiation (`instantiateProvider` / `loadActiveProvider`) lives in `src/core/ProviderInstantiate.ts` here — `import()` resolves package specifiers relative to the calling module, so the dynamic-import path stays in the consumer where the `@plurnk/plurnk-providers-<vendor>` packages are installed.
 
 ```
 PLURNK_MODEL_gemma=openai/macher.gguf
@@ -139,9 +160,9 @@ PLURNK_MODEL=gemma
 
 First path segment = provider plugin; rest = provider's own model id.
 
-### §2.4 In-tree Mock provider
+### §2.4 Mock provider (sibling fixture)
 
-`Mock` (exported from `@plurnk/plurnk-providers`) — intg fixture + reference implementation. `{ contextSize, responses }` constructor; `generate` shifts from the queue. `MockResponse.assistant.ops?: PlurnkStatement[]` is a pre-parsed escape hatch the engine consumes directly when present; production providers don't expose this.
+`Mock` (exported from `@plurnk/plurnk-providers`) — intg fixture + reference implementation. `{ contextSize, responses }` constructor; `generate` shifts from the queue. `MockResponse.assistant.ops?: PlurnkStatement[]` is a pre-parsed escape hatch the engine consumes directly when present; production providers don't expose this. {§2.4-mock-fixture}
 
 ---
 
@@ -151,15 +172,15 @@ Author-facing contract: [plurnk-schemes#1](https://github.com/plurnk/plurnk-sche
 
 ### §3.1 Manifest
 
-Per author contract. Each scheme declares a `static manifest: SchemeManifest` with `name`, `channels`, `defaultChannel`, `category`, `scope`, `writableBy`, `volatile`, `modelVisible`, optional `flags`. Identity match enforced at plugin load: `manifest.name` must equal `package.json#plurnk.name`.
+Per author contract. Each scheme declares a `static manifest: SchemeManifest` with `name`, `channels`, `defaultChannel`, `category`, `scope`, `writableBy`, `volatile`, `modelVisible`, optional `flags`. {§3.1-manifest} Identity match enforced at plugin load: `manifest.name` must equal `package.json#plurnk.name`.
 
 ### §3.2 CRUD primitives
 
-Per author contract (`readEntry` / `writeEntry` / `deleteEntry`). Engine drives cross-scheme COPY/MOVE/SEND[410] through these. Each method is one SQL transaction; engine owns the outer transaction for orchestrations.
+Per author contract (`readEntry` / `writeEntry` / `deleteEntry`). Engine drives cross-scheme COPY/MOVE/SEND[410] through these — the orchestration and its 404/409/415 semantics are anchored under §6.4/§6.5. Each method is one SQL transaction; engine owns the outer transaction for orchestrations.
 
 ### §3.3 Op methods
 
-Per author contract (`edit`/`read`/`show`/`hide`/`find`/`send`/`exec?`). Engine dispatches by `PlurnkStatement.op`. COPY and MOVE are NOT scheme methods — engine orchestrates over CRUD primitives.
+Per author contract (`edit`/`read`/`show`/`hide`/`find`/`send`/`exec?`). Engine dispatches by `PlurnkStatement.op`. {§3.3-op-dispatch} COPY and MOVE are NOT scheme methods — engine orchestrates over CRUD primitives (§6.4/§6.5).
 
 ### §3.4 Cross-scheme orchestration
 
@@ -179,17 +200,17 @@ move(source_path, dest_path, signal_tags, ctx):
     src_scheme.deleteEntry(source_pathname, ctx)
 ```
 
-Same- and cross-scheme operations share the orchestrator. Same-scheme COPY is not a special case.
+Same- and cross-scheme operations share the orchestrator. Same-scheme COPY is not a special case. Orchestration behavior — 404/409/415, `move` = `copy` + `deleteEntry` — is anchored under §6.4/§6.5.
 
 ### §3.5 SEND dispatch (status-code-as-verb)
 
 Directed SEND (non-null path) routes to scheme's `send`. Status = intent:
 
 - `SEND[200](path)` — write body into resource (WS message, exec stdin).
-- `SEND[410](path)` — delete the resource. {§3.5-410-deletes-resource}
-- `SEND[410](path#fragment)` — delete the named channel only. {§3.5-410-fragment-channel-delete}
 - `SEND[499](path)` — cancel active subscription (§7).
 
+`SEND[410](path[#fragment])` also deletes the target entry/channel — an implemented side-effect, NOT taught to the model and with no live/demo surface. The model-facing delete idiom is MOVE to `/dev/null` (§6.5).
+
 Other status codes return 501 from entry-bearing schemes by default. {§3.5-entry-schemes-501-on-non-410}
 
 Null-path SEND is broadcast (§6.7), engine-handled.
@@ -219,11 +240,11 @@ Engine → scheme guarantees:
 
 - `ctx` is fresh per call. No mutation across calls.
 - `ctx.writer` reflects the actual writer at this dispatch.
-- `manifest.writableBy` checked BEFORE invocation; engine returns 403 directly on exclusion.
-- `ctx.signal` is wired to the run's AbortController.
-- Scheme exceptions become the action-entry's outcome (status 500); summary surfaces in next turn's `packet.user.telemetry.errors[]` (§15.1).
+- `manifest.writableBy` checked BEFORE invocation; engine returns 403 directly on exclusion. {§3.6-writableby-403}
+- `ctx.signal` is wired to the run's AbortController (§2.2-signal-wired).
+- Scheme exceptions become the action-entry's outcome (status 500); summary surfaces in next turn's `packet.user.telemetry.errors[]` (§15.1). {§3.6-exception-500}
 
-**Tokenization participation.** Schemes route writes through the shared `_entry-crud.ts` write helper (in plurnk-service today; migrates to plurnk-schemes). Helper populates `entry_channels.tokens` at write time via `ctx.provider.countTokens`. Raw DB writes bypass tokenization — out of API scope.
+**Tokenization participation.** Schemes route writes through the shared `_entry-crud.ts` write helper (in plurnk-service today; migrates to plurnk-schemes). Helper populates `entry_channels.tokens` at write time via `ctx.provider.countTokens` (§14.2-tokens-stored-at-write). Raw DB writes bypass tokenization — out of API scope.
 
 ---
 
@@ -392,16 +413,17 @@ Per-op semantics. AST shapes from `@plurnk/plurnk-grammar`'s `PlurnkStatement`.
 AST: `{ op: "EDIT", target, body: string | null, signal: tags | null, lineMarker? }`.
 
 - Resolves target channel from fragment (§5.5); unknown channel → 400; undeclared in manifest → engine crash (§5.3).
-- Writes body; `body: null` clears.
-- Sets `indexed=1` for written channel in current run.
-- Returns `{ status: 201, entryId }` for new entries; `{ status: 200, entryId }` for updates.
-- Tags from `signal[]` apply additively via `entry_tags` (scheme may vary).
+- Writes body; `body: null` clears. {§6.1-null-clears}
+- Sets `indexed=1` for written channel in current run. {§6.1-indexed}
+- Returns `{ status: 201, entryId }` for new entries; `{ status: 200, entryId }` for content updates. {§6.1-status-201-200}
+- A write that changes nothing — identical content and no new tag — returns `{ status: 304, entryId }`, mirroring SHOW/HIDE's no-op (§6.3). {§6.1-noop-304}
+- Tags from `signal[]` apply additively via `entry_tags` (scheme may vary). {§6.1-tags-additive}
 
 ### §6.2 READ
 
 AST: `{ op: "READ", target, body: MatcherBody | null, signal: tags | null, lineMarker? }`.
 
-- Returns channel content + mimetype, or 404.
+- Returns channel content + mimetype {§6.2-read-content}, or 404 {§6.2-read-404}.
 - `lineMarker` slices per §16.3.
 - `body` matcher dispatches through `Mimetypes.query` per §16.1 (all four dialects wired).
 
@@ -410,7 +432,7 @@ AST: `{ op: "READ", target, body: MatcherBody | null, signal: tags | null, lineM
 AST: `{ op: "SHOW"|"HIDE", target, body: MatcherBody | null, signal: tags | null, lineMarker? }`.
 
 - Flips `visibility.indexed` for the targeted channel(s) per §5.5 rules.
-- Returns 200 on transition, 304 on no-op, 404 if entry absent.
+- Returns 200 on transition {§6.3-flip-200}, 304 on no-op {§6.3-noop-304}, 404 if entry absent {§6.3-absent-404}.
 
 ### §6.4 COPY (engine-orchestrated)
 
@@ -419,7 +441,7 @@ AST: `{ op: "COPY", target (source), body (destination), signal: tags | null, li
 Engine orchestrates over CRUD primitives (§3.2, §3.4):
 
 1. `src_scheme.readEntry` → 404 if missing. {§6.4-missing-source-404}
-2. `dst_scheme.readEntry` → if exists, 409 (no overwrite). {§6.4-conflict-409}
+2. `dst_scheme.readEntry` → conflict verdict, deferred until the written content is known (step 5): exists with identical content + tags → 304 (no-op, mirrors EDIT §6.1) {§6.4-noop-304}; exists with different content → 409 (no overwrite) {§6.4-conflict-409}; absent → proceed.
 3. Mimetype compat — channels' mimetypes must be accepted by `dst_scheme.manifest.channels`. Mismatch → 415.
 4. Tags: `signal` non-null replaces source tags {§6.4-signal-replaces-source-tags}; null/empty carries source tags {§6.4-no-signal-carries-source-tags}.
 5. `dst_scheme.writeEntry({channels, tags})`.
@@ -432,7 +454,7 @@ Returns 201 on success. Same- and cross-scheme COPY share the orchestrator. {§6
 AST: `{ op: "MOVE", target (source), body: dest | null, signal: tags | null, lineMarker? }`.
 
 - **Relocation** (`body` non-null): COPY (§6.4) + `src_scheme.deleteEntry` in one transaction. 201 on success. {§6.5-relocation-deletes-source} Cross-scheme same as same-scheme. {§6.5-cross-scheme-move}
-- **Deletion** (`body: null`): `src_scheme.deleteEntry` directly. {§6.5-null-body-deletes} 200 on success, 404 if absent. {§6.5-missing-source-404}
+- **Deletion** (`body: null`, or `body` = `/dev/null`): `src_scheme.deleteEntry` directly. {§6.5-null-body-deletes} 200 on success, 404 if absent. {§6.5-missing-source-404} `/dev/null` is the model-facing delete idiom the grammar teaches; a null body is its programmatic equivalent. {§6.5-dev-null-deletes}
 
 Log history preserved — `log_entries` stores path tuple as text, not FK to `entries.id`.
 
@@ -441,7 +463,7 @@ Log history preserved — `log_entries` stores path tuple as text, not FK to `en
 AST: `{ op: "FIND", target (scope), body: MatcherBody | null (predicate), signal: tags | null, lineMarker? }`.
 
 - Filters entries within scope (scheme + pathname prefix). {§6.6-scope-prefix-filter}
-- `body` matcher operates on pathname (glob). {§6.6-glob-filter-on-pathname} Content matchers (xpath/jsonpath/regex over body) live on READ.
+- `body` matcher operates on entry content (glob/regex/jsonpath/xpath), per grammar plurnk.md §"Body matcher dispatch"; the path-glob lives in the (target), not the body. {§6.6-glob-filter-on-content}
 - `signal` is a tag filter; entries match if they have ALL listed tags. {§6.6-tag-filter-and-semantics}
 - Session + scheme scoped — no cross-session/cross-scheme leakage. {§6.6-scoped-isolation}
 - Returns `{ status: 200, results: string }` (newline-separated matching paths, `text/plain`).
@@ -610,7 +632,7 @@ Plugin discovery (§9) registers whatever's in `node_modules/@plurnk/*`.
 - Render budget per channel — `PLURNK_ENTRY_SIZE_DEFAULT_TOKENS` (§12); tokenization per §14.2.
 - Backpressure caps — none (§7.8).
 - Stream cancel — `SEND[499]` (§7.7).
-- Delete — `SEND[410]` (§3.5, §6.5).
+- Delete — MOVE to `/dev/null` (§6.5); `SEND[410]` also deletes as a side-effect (§3.5).
 - Per-loop flags — `loops.flags` JSON column; `yolo` end-to-end today, others scheduled.
 - Default-channel wire rendering — §5.5.
 
@@ -690,7 +712,7 @@ registry.register("loop.run", {
 - `description`: one-liner surfaced by `discover`.
 - `params`: `"type — meaning"` per param; `?` suffix = optional. Self-documenting, not enforced.
 - `requiresInit`: rejects until a session is attached.
-- `longRunning`: exempt from `PLURNK_RPC_TIMEOUT`.
+- `longRunning`: exempt from `PLURNK_RPC_TIMEOUT`. {§13.3-register}
 
 ### §13.4 Discovery
 
@@ -716,7 +738,7 @@ registry.register("loop.run", {
 }
 ```
 
-`capabilities` lists registered plug-ins by `(kind, name)`. Cold clients call `discover` first. No hardcoded method names or capability lists in any client.
+`capabilities` lists registered plug-ins by `(kind, name)`. Cold clients call `discover` first. No hardcoded method names or capability lists in any client. {§13.4-discover}
 
 ### §13.5 Core method set
 
@@ -733,18 +755,18 @@ registry.register("loop.run", {
 |------------------------|---------------------|-------------------|-------|
 | `session.create`       | `name?: string`, `projectRoot?: string`, `persona?: string` | `{ id, name, projectRoot, persona }` | Creates new session; auto-name if unprovided. Optional `projectRoot` pins the workspace (null/omitted = headless). Optional `persona` sets the session-level persona override. |
 | `session.list`         | none                | `{ sessions: Session[] }` | Lists all sessions. |
-| `session.attach`       | `id: number`, `runId?: number`, `runName?: string`, `persona?: string` | `{ id, name, runId, runName }` | Binds this connection to an existing session. Optional `runId` resumes that specific run (must belong to the session). Optional `runName` reuses-or-creates by name within the session. Both omitted → new auto-named run. Optional `persona` sets run-level persona only when a NEW run is created. |
+| `session.attach`       | `id: number`, `runId?: number`, `runName?: string`, `persona?: string` | `{ id, name, runId, runName }` | Binds this connection to an existing session. Optional `runId` resumes that specific run (must belong to the session). Optional `runName` reuses-or-creates by name within the session. Both omitted → new auto-named run. Optional `persona` sets run-level persona only when a NEW run is created. {§13.5-session-attach} |
 | `session.runs`         | `id?: number`       | `{ runs: Run[] }` | Lists runs in a session (defaults to attached session); most-recent first. |
 | `session.set_root`     | `projectRoot: string \| null` | `{ projectRoot }` | Update the workspace pointer on the attached session. Null reverts to headless. |
 | `session.set_persona`  | `persona: string \| null` | `{ persona }`  | Update the session-level persona. Null clears the override (falls through to PLURNK_PERSONA file). |
 
-**Auto-envelope.** Clients calling a `requiresInit: true` method without first attaching get auto-created session → run → client loop. Records persist normally; auto-created ≠ auto-deleted. Cleanup is a future `session.delete` / `session.archive` endpoint.
+**Auto-envelope.** Clients calling a `requiresInit: true` method without first attaching get auto-created session → run → client loop. Records persist normally; auto-created ≠ auto-deleted. Cleanup is a future `session.delete` / `session.archive` endpoint. {§13.5-auto-envelope}
 
 **Loops (model-driven)**
 
 | Method            | Params                              | Result                 | Notes |
 |-------------------|-------------------------------------|------------------------|-------|
-| `loop.run`        | `prompt: string`, `maxTurns?: number`, `alias?: string`, `flags?: LoopFlags`, `persona?: string` | `{ loopId, turnIds, finalStatus, hitMaxTurns, reason }` | Model-driven loop. Optional `alias` overrides the boot-time `PLURNK_MODEL`. Optional `flags` carries per-loop flags (currently `{yolo?: boolean}`; more arrive as wired — see §0.5). Optional `persona` sets the loop-level persona (highest precedence in the cascade). Streams `log/entry` and `loop/proposal` notifications during. `longRunning: true`. |
+| `loop.run`        | `prompt: string`, `maxTurns?: number`, `alias?: string`, `flags?: LoopFlags`, `persona?: string` | `{ loopId, turnIds, finalStatus, hitMaxTurns, reason }` | Model-driven loop. Optional `alias` overrides the boot-time `PLURNK_MODEL`. Optional `flags` carries per-loop flags (currently `{yolo?: boolean}`; more arrive as wired — see §0.5). Optional `persona` sets the loop-level persona (highest precedence in the cascade). Streams `log/entry` and `loop/proposal` notifications during. `longRunning: true`. {§13.5-loop-run} |
 | `loop.resolve`    | `logEntryId: number`, `decision: "accept" \| "reject" \| "cancel"`, `body?: string`, `outcome?: string` | `{ status, logEntryId }` | Resolve a pending proposal (status=202 log entry). Engine.dispatch unpauses on resolution. |
 | `providers.list`  | none                                | `{ aliases: ProviderAlias[] }` | Lists configured `PLURNK_MODEL_<alias>` entries with `{alias, provider, model, active}`. Clients use to populate model-selection UI. |
 
@@ -752,12 +774,12 @@ registry.register("loop.run", {
 
 | Method        | Params                              | Result                 | Notes |
 |---------------|-------------------------------------|------------------------|-------|
-| `entry.read`  | `target: string`                    | `{ status, entry }`    | Read the full entry shape (channels + tags + metadata) at the given URI. |
-| `log.read`    | `loopId?: number`, …                | `{ entries: LogEntry[] }` | Read recent log entries from the attached session, optionally filtered by loop. |
+| `entry.read`  | `target: string`                    | `{ status, entry }`    | Read the full entry shape (channels + tags + metadata) at the given URI. {§13.5-entry-read} |
+| `log.read`    | `loopId?: number`, …                | `{ entries: LogEntry[] }` | Read recent log entries from the attached session, optionally filtered by loop. {§13.5-log-read} |
 
 **DSL operations (client-driven, mirror grammar)**
 
-Per the **Speak in DSL, not plumbing** rule (AGENTS.md): `op.*` methods construct DSL statements internally and dispatch through `Engine.dispatch`. Param shapes are ergonomic (semantic names, not HEREDOC slots); semantics are the DSL's.
+Per the **Speak in DSL, not plumbing** rule (AGENTS.md): `op.*` methods construct DSL statements internally and dispatch through `Engine.dispatch`. {§13.5-op-mirror} Param shapes are ergonomic (semantic names, not HEREDOC slots); semantics are the DSL's.
 
 Each `op.*` call creates a turn in the connection's client loop (§13.7), dispatches, fires `log/entry`, returns the dispatch result.
 
@@ -787,7 +809,7 @@ Server-initiated events on the same WebSocket.
 
 | Notification       | Params                              | When fired |
 |--------------------|-------------------------------------|------------|
-| `log/entry`        | `{ entry: LogEntry }`               | Every `log_entries` write. |
+| `log/entry`        | `{ entry: LogEntry }`               | Every `log_entries` write. {§13.6-log-entry-notify} |
 | `loop/terminated`  | `{ loopId, finalStatus, hitMaxTurns }` | Loop reaches terminal status. |
 | `loop/proposal`    | `{ logEntryId, sessionId, runId, loopId, turnId, op, target, body, attrs, flags }` | Dispatch pauses on status=202. Carries `flags` so server-YOLO clients can suppress review UI. Client responds with `loop.resolve` (or `PLURNK_PROPOSAL_TIMEOUT_MS` fires). |
 | `session/created`  | `{ id, name, projectRoot, persona }` | Any client creates a session. |
@@ -853,7 +875,7 @@ Plurnk-specific (`-32000` to `-32099`):
 | -32006 | Mimetype unavailable                               |
 | -32007 | Timeout                                            |
 
-Error responses MAY include `data: {…}` with structured context (404'd path, timed-out method, etc.).
+Error responses MAY include `data: {…}` with structured context (404'd path, timed-out method, etc.). {§13.8-error-codes}
 
 ### §13.9 Versioning
 
@@ -875,43 +897,73 @@ Each entry: question, answer, rationale, migration path.
 
 **Migration path.** If a plugin needs to inject a packet section, grow a single `packet.augment` hook called after `#buildIndex`; plugins return system/user augmentation objects merged into the packet. Additive — engine-direct base stays.
 
-### §14.2 Tokenomics: real provider tokens, stored at write, summed at render
+### §14.2 Tokenomics: real provider tokens, render-weight budget, per-scheme balance
+
+**Question.** How does plurnk track token costs accurately enough to ground the model's SHOW/HIDE/compose decisions? Accuracy is the whole game — a budget that smells wrong is one the model stops trusting and curating against.
+
+**Two measures, never conflated:**
 
-**Question.** How does plurnk track token costs accurately enough for model SHOW/HIDE/compose decisions, without re-tokenizing every turn?
+- **render-weight** — the tokens the model actually processes this turn (rendered previews + meta + fences). The budget is about this.
+- **content-depth** — an entry's full content size (`entry_channels.tokens`). The manifest's `tokens` is this.
 
-**Decision.** Provider tokenizers authoritative; counts computed at write time and stored; render-time accounting is SQL `SUM` plus tokenization of a small set of wrapper strings. {§14.2-tokenomics-v0}
+**Built.**
 
-Lattice:
+- **Provider tokens, stored at write.** `provider.countTokens` is the source of truth; `entry_channels.tokens` (via `_entry-crud`) and `log_entries.tokens` (via `Engine.#writeLog`) are populated at write as a write-time snapshot. A `ceil(len/DIVISOR)` fallback (the divisor tripwire) applies only when no provider tokenizer is wired. {§14.2-tokens-stored-at-write}
+- **Render-weight budget.** The budget headline — `ceiling`, `tokenUsage`, `tokensFree` — is measured from the *assembled packet* (placeholders substituted after measuring), so it reflects what the model actually receives. A `SUM` of stored content-depth would mis-price previews; render-weight is the accurate measure. {§14.2-render-weight-budget}
+- **Per-scheme balance.** A markdown table groups the model's context by scheme — `indexed`/`archived` counts and render-weight `tokens` — anchored `repo, known, unknown, log`, tail sorted by tokens. The model sees at a glance what's eating its window. {§14.2-per-scheme-balance}
+- **Context-window percent.** The headline carries usage as a percent of the ceiling — `usage Y (P%)` — a fullness gauge beside the absolutes. Reads the ceiling already in hand; no extra provider call. {§14.2-context-percent}
+- **Depth re-counted at render.** The manifest re-tokenizes each entry's `tokens` through the live provider at build — never the write-time snapshot — so a model change between loops can't stale the catalog. Every token figure in the packet is render-fresh, manifest and budget alike; nothing trusts a cross-loop cached total. {§14.2-depth-render-fresh}
+- **Over-budget is honest.** When usage exceeds the ceiling, `free` floors at 0 and the percent passes 100 — the readout shows the overshoot rather than a negative free, so the model knows it's over and curates down. {§14.2-over-budget-floor}
 
-- **`provider.countTokens` is the source of truth.** No chars/DIVISOR approximation. Per-provider tokenizer (§2) is the foundation.
-- **Stored at write time.** `entry_channels.tokens` populated by `_entry-crud.ts` on INSERT/UPDATE. `log_entries.tokens` populated by `Engine.#writeLog`. Write helper IS the contract sister modules see.
-- **Render-time SUM.** `Engine.#buildIndex` adds per-scheme `SUM(tokens)`. Only wrapper strings re-tokenize each render — bounded.
-- **Hot model switch is a feature.** Session model change walks `entry_channels` + `log_entries` and recomputes against new tokenizer. One-time cost at switch boundary.
-- **Budget table self-reference via placeholder substitution.** Render with `{{tokenUsage}}`/`{{tokensFree}}`, measure, substitute. ±1–2 token drift accepted.
-- **Telemetry shape.** Per-scheme breakdown table in `packet.user.telemetry.budget` with `tokenCeiling`/`tokenUsage`/`tokensFree` headline; markdown table groups by scheme with indexed-count, archived-count, tokens.
+**Rejected / obviated.**
 
-**Rationale.** Rummy used chars/DIVISOR + compute-at-SELECT because its sync-only SQL function couldn't call provider tokenizers. plurnk's async `countTokens` is potentially expensive; pay once at write, never re-pay at render. Approximation can't ground SHOW/HIDE decisions — the model curating its own context only works if numbers are accurate.
+- **Hot model-switch recompute** — *obviated* by render-fresh depth (above). There's no cross-loop cache to recompute: the manifest re-tokenizes at build, the budget always did. A model change between loops can't stale a number nothing caches.
+- **Reasoning-token surfacing** — *rejected* for the model-facing budget: reasoning is *output*, not window-context, and the model can't HIDE it. The thinking-vs-output distinction is cost-forensics (the usage breakdown is stored on every packet), not a curation signal.
 
-**Migration path.** If `countTokens` cost becomes prohibitive, retreat to chars/DIVISOR per provider, async-refined to real count when budget permits. Schema unchanged.
+**Rationale.** Rummy used chars/DIVISOR + compute-at-SELECT only because its sync-only SQL couldn't call a tokenizer. plurnk has real `countTokens`: store content tokens once at write (the depth), measure the small rendered output for the budget (the weight). Approximation can't ground curation — the model only curates against numbers it trusts.
+
+**Migration path.** None on cost — SQLite, JS, and a local tokenizer are negligible against the model's token budget, the only thing worth economizing. The fallback divisor is a correctness tripwire (no provider tokenizer wired), not a performance retreat. Schema unchanged.
 
 ### §14.3 Workspace identity, membership, disk co-location
 
 **Question.** How does plurnk represent the project a session works on? Where does file membership come from? Does writing an entry imply writing to disk?
 
-**Decision lattice.** {§14.3-workspace-phase-f}
+**The boundary is the client's.** The client owns the model's filesystem access in both directions: reads are membership-gated (a file is invisible to the model unless it is a member), and writes are proposals the client accepts or rejects (`yolo` auto-accepts). Writing an entry never implies writing to disk — entries are canonical in the store; disk only moves when the client accepts a side-effecting proposal, and only where `project_root` is set (null = headless, client owns materialization).
+
+**Built — git-substrate membership.** {§14.3-git-membership}
+
+- **Identity on the session.** No `projects` table; `sessions.project_root TEXT` (nullable = headless). `entries.scope` unchanged (`∈ {'agent','session'}`). Workspace = session; no users/auth/multi-tenant.
+- **git-ls-files membership.** git present → tracked files (`git ls-files`) are members with no explicit `add` — channel-less markers, disk is truth. git absent → no fs-walk (non-git/headless get no substrate membership).
+- **EMI eager + relevance-bounded.** Materializes only the run's indexed members (`visibility.indexed=1`) at prompt-composition, re-reading disk so a divergent member reflects current content.
+- **Disk-read-first edits.** Disk writes route through `File.edit`, which reads disk before diffing — an untouched member's baseline is its real content, never empty. Silent overwrite is structurally prevented.
 
-- **D1. Workspace identity lives on the session.** No `projects` table. `sessions.project_root TEXT` (nullable = headless). Constraints scoped via `session_constraints`. plurnk has no users/auth/multi-tenant; workspace = session.
-- **D2. No new `entries.scope` value.** Stays `∈ {'agent', 'session'}`.
-- **D3. Disk co-location optional.** `sessions.project_root` set → disk side-effects on accept; null → canonical entries land, no disk write (client owns materialization).
-- **D4. Membership without git: no fs-walk.** git present → ls-files + constraint overlay. git absent → `effect='add'` constraints only.
-- **D5. EMI is eager + relevance-bounded.** Fires at prompt-composition time; checks only entries the current run will include (`visibility.indexed=1`). Divergent → re-read disk + emit synthetic log entry.
-- **D6. Edit-on-untouched-file: disk-read-first.** EDIT targeting a member with no existing entry reads disk first to populate canonical baseline, then diffs. Prevents silent overwrite.
-- **D7. Constraint pattern matching via `node:path.matchesGlob`.** No dep. Helper wrapper for swap-out optionality.
+**Deferred — promised, not yet built.** Each carries an anchor with a deliberately-red test so the deferral is tracked, never silently covered.
 
-**Rationale.** No users/tenants. Session is the right scope unit. git+constraints membership keeps model out of fs-walk territory. EMI's eager-relevance-bounded firing prevents stale previews without per-turn full-repo cost.
+- **Constraint overlay — the client supersede.** {§14.3-constraint-overlay} A `session_constraints` table layering *add* (members git misses), *ignore* (drop ones it tracks), and *read-only* (member for read, writes rejected) over the git substrate; glob matching via `node:path.matchesGlob`. git-absent, these `effect='add'` constraints are the *sole* membership source — so this overlay is not merely the override knob, it is the entire membership mechanism without git.
+- **EMI divergence signal.** {§14.3-emi-divergence-signal} When EMI re-reads a member whose disk content changed out-of-band, emit a synthetic log entry so the model sees the change (the re-read is built; only the signal is deferred).
+
+**Rationale.** No users/tenants. Session is the right scope unit. git+constraints membership keeps the model out of fs-walk territory. EMI's eager-relevance-bounded firing prevents stale previews without per-turn full-repo cost.
 
 **Migration path.** Tenancy / cross-session shared workspaces require a `workspaces` table joining sessions to workspace id, with constraints lifted off `session_constraints`. Disk co-location semantics unchanged.
 
+### §14.4 Budget enforcement: the grinder
+
+**Question.** §14.2 surfaces the budget honestly and the model curates against `tokensFree` — almost always enough. Three states defeat self-regulation, none of them the model's doing: a jumbo prompt, a jumbo repo (the index overflows before the model acts), an unexpectedly large read. What enforces the ceiling when the signal isn't enough?
+
+**Decision — a pre-LLM grinder, fired only on actual overflow.** In `Engine.runTurn`, after the packet is assembled (`#buildRequestPacket`) and before `provider.generate`, the assembled render-weight (§14.2) is measured against the ceiling. At or under → the packet ships untouched; the grinder never trims speculatively or "helpfully." {§14.4-overflow-only} On overflow it reclaims window in two passes, re-measuring between:
+
+- **Prior-turn rollback.** The immediately-prior turn's log entries — the latest emissions, the ones that pushed the packet over — are hidden (`indexed=0`, the same flag the model's own HIDE uses); the prior turn fit by induction, so reverting it usually lands back under. Hidden, not deleted: rows and bodies persist and are re-SHOWable, so log *history* is preserved while the render shrinks. {§14.4-layer1-rollback}
+- **Index collapse.** If clearing replays isn't enough, every catalog entry except `plurnk://manifest.json` is hidden (`indexed=0`); the manifest stays as the lifeline the model reads to pull anything back by path. The index is engine-built scaffolding — a derived, previews-only view regenerated each turn — never the model's context, so collapsing it removes no capability. {§14.4-layer2-index-collapse}
+- **Hard stop.** If the packet still overflows with only the manifest left, the loop abandons at 499 (`engine_loop_cancel`) — the path `maxTurns` and the strike threshold already use. No third pass. {§14.4-hard-413-abort}
+
+**Strike coupling.** A grinder fire bumps the engine's `turnErrors` — the same internal counter cycle detection feeds — so an overflow counts toward the strike streak that ends a runaway loop at 499. This is the pressure that keeps self-curation the path of least resistance. {§14.4-strike-coupling} **Turn 0/1 is exempt:** the first turn's overflow precedes any model action — it's the environment, not the model — so it never strikes. {§14.4-soft-turn-0-1}
+
+**What the model sees.** A `budget_overflow` telemetry event (§15.1), in the model's own terms: which of its entries left the window, by scheme. No mechanism vocabulary — no "layer," no "grinder," no "reclaim" — and no advice. The engine reports *what happened to the model's world*; the per-scheme budget table (§14.2) is the diagnostic surface, and the model — which can see what changed in its repo, its reads, its turn — diagnoses the cause the engine can't attribute. {§14.4-event-model-terms} Per the gamification policy (§15.1), the *strike* the overflow triggers stays engine-internal; the model sees the hidden entries, never the accounting.
+
+**Rationale.** The model owns curation (§14.2); the grinder is the exceptional backstop. It only *hides* — reversibly — the prior turn's render, then the index scaffolding; nothing is deleted, so the model can SHOW any of it back and log history stays intact. Rummy's §1316 spec described clearing log *bodies*, but its code instead hid the prior turn whole — because body-clearing is destructive (it deletes the read result) and bespoke. The code was the lesson; plurnk follows it (and the §1316 index-collapse pass that doc never caught up to).
+
+**Migration path.** None on mechanism. Speculative or non-overflow trimming is a different feature, deliberately excluded — the grinder fires only in response to actual overflow.
+
 ---
 
 ## §15 Packet shape
@@ -941,6 +993,8 @@ type Packet = {
 
 **Prompt as a first-class entry.** Each loop's prompt is written on loop start as a system-origin `EDIT` against `plurnk://prompt/<loop_id>` (indexable, body channel, text/markdown). At render time the current loop's entry is foisted out of `packet.system.index` into `packet.user.prompt` — no duplicate rendering. Previous loops' prompts remain in the index, addressable for READ/HIDE. {§15-current-prompt-foist}
 
+**The entry catalog.** `plurnk://manifest.json` is a real session entry the model READs to discover what's available — rewritten every turn as a live view of the full entry set. Built in the schemes layer (`_entry-manifest`) and materialized like any entry (the engine only orchestrates the per-turn write — the same pattern as git membership), so it's indexed, READable, and queryable. Body is `application/json`: a flat array, one item per entry across all schemes (hidden ones included — the model sees what it could pull in), each `{ path, shown, channels: { <name>: { mimetype, tokens, lines } } }`. `shown` is whether the entry is in this turn's index — `[?(@.shown==false)]` gives the hidden inventory to SHOW; `tokens` is the provider's write-time count (budget depth), `lines` the content extent from `Mimetypes.process().totalLines`. The engine counts neither. It does not list itself. {§15-manifest-catalog}
+
 ### §15.1 user.telemetry — model-facing runtime telemetry
 
 Slot for telemetry the model MUST react to immediately. Rendered at the bottom of the user section. Errors are transient — appear on the turn AFTER the failure, clear once seen. `packet.system.log[]` is the durable audit; `telemetry.errors[]` is the **alert**.
@@ -965,6 +1019,7 @@ Slot for telemetry the model MUST react to immediately. Rendered at the bottom o
 | `parse_error` | Grammar parser failed mid-statement | `source: "grammar"`, `kind`, `message`, `position` (content-offset), `snippet` (model's offending line, N:\t-prefixed), `parserSource` (`lexer`/`parser`/`visitor`) |
 | `action_failure` | Log entry with `status_rx ≥ 400` from previous turn | `kind`, `coordinate` (`<L>/<T>/<S>`), `op`, `status`, `target` (URI or null). May carry scheme-emitted `error` (a terse fact, not guidance). |
 | `max_commands_exceeded` | Single emission exceeded `PLURNK_MAX_COMMANDS` cap; overflow ops dropped without dispatch | `source: "engine:rail"`, `kind`, `emitted`, `dropped` |
+| `budget_overflow` | Assembled packet exceeded the budget ceiling; entries moved out of the window to fit | `source: "engine:rail"`, `kind`, `hidden` (per-scheme `[{scheme, count}]` — entries removed from the window) |
 
 Strike accounting, cycle detection, sudden-death thresholds, and no-ops bookkeeping are all engine-internal — they drive abandonment silently per the gamification policy above. Action-bound failures (handler returned 4xx/5xx or threw) mirror as `action_failure` kind on the next packet. Full detail queryable via `log://`. {§15.1-no-error-scheme}
 
@@ -1052,12 +1107,12 @@ Body: JSON array of `{line, matched, matching?}`. Empty → 204. Mimetype = `app
 
 ### §16.4 Structural EDIT on JSON
 
-When effective mimetype is `application/json`, EDIT dispatches through `applyJsonItemEdit`. Body shape rule (parse-then-discriminate):
+When effective mimetype is `application/json`, EDIT dispatches through `applyJsonItemEdit`. {§16.4-structural-json-edit} Body shape rule (parse-then-discriminate):
 
 - Body parses as JSON array → items to splice
 - Body parses as non-array JSON → single item to splice
 - Empty body → delete the selection
-- Body fails JSON parse → 400 (path-extension declares intent; honor strictly)
+- Body fails JSON parse → 400 (path-extension declares intent; honor strictly) {§16.4-json-parse-fail-400}
 
 **Array source marker × body:**
 
@@ -1088,14 +1143,14 @@ When effective mimetype is `application/json`, EDIT dispatches through `applyJso
 - `known://config.yaml` → `application/yaml`
 - `known://users` (no suffix) → `text/markdown` (Known manifest default)
 
-Same rule applies across Known, Unknown, Skill, Plurnk, File. Effective mimetype is stored in `entry_channels.mimetype` on write and drives `<L>` and matcher dispatch on read.
+Same rule applies across Known, Unknown, Skill, Plurnk, File. Effective mimetype is stored in `entry_channels.mimetype` on write and drives `<L>` and matcher dispatch on read. {§16.5-extension-mimetype}
 
 ### §16.6 Render rule (mimetype-driven)
 
 `packet-wire` log render branches on `isLineNavigableMimetype`:
 
-- **Line-navigable** (text/markdown, text/plain, csv, source code, yaml, toml) → `N:\t` line-number prefix per line
-- **Tree-navigable** (application/json, application/xml, text/html, +json/+xml suffixes) → verbatim body (no `N:\t` — outer line numbers would collide with structural navigation like jsonpath/xpath)
+- **Line-navigable** (text/markdown, text/plain, csv, source code, yaml, toml) → `N:\t` line-number prefix per line {§16.6-line-navigable-prefix}
+- **Tree-navigable** (application/json, application/xml, text/html, +json/+xml suffixes) → verbatim body (no `N:\t` — outer line numbers would collide with structural navigation like jsonpath/xpath) {§16.6-tree-navigable-verbatim}
 
 The `N:\t` prefix is presentation/reference per plurnk.md ("not part of the source"); stripped before any matcher operation on the log entry.
 
@@ -1103,16 +1158,12 @@ The `N:\t` prefix is presentation/reference per plurnk.md ("not part of the sour
 
 Auto-derived text mimetypes anywhere in plurnk-service normalize to `text/markdown`:
 
-- `<L>` slice on line-navigable source → `text/markdown`
+- `<L>` slice on line-navigable source → `text/markdown` {§16.7-text-markdown-normalize}
 - File scheme extension fallback → `text/markdown`
 - `Mimetypes.detect()` returning `text/plain` → normalized via `normalizeAutoTextMimetype`
 
 `text/plain` survives only where a scheme explicitly declares it (exec stdout/stderr — subprocess byte-streams aren't markdown). The model never auto-encounters `text/plain` from defaults.
 
-### §16.8 EDIT response surfaces unified diff
-
-Every EDIT@200/201 carries `diff` (unified diff format) on the result. Both `_entry-ops.editSessionEntry` and `File.edit` produce it. `packet-wire` log render emits the diff under the entry's fence so the model sees what changed without a follow-up READ — wrong-marker mistakes (e.g., `<1>` when `<-1>` was meant) become visible on the next turn. Omitted on no-op edits (content unchanged). {§16.8-edit-diff}
-
 ### §16.9 Op-level invariants and resolved ambiguities
 
 Carried from the contract walk; durable.
@@ -1122,9 +1173,9 @@ Carried from the contract walk; durable.
 - **EDIT `<L>` on non-existent entry** → body becomes content; `<L>` is positional-only on existing content.
 - **COPY `<L>`** → source range, symmetric with READ `<L>`.
 - **READ rx** prefixes each line with `N:\t` per §16.6. `sliceLinesRaw` (used by COPY) returns the lines without prefix.
-- **FIND body matcher** applies to pathname. xpath/jsonpath content matchers dispatch through `Mimetypes.query`.
-- **SHOW/HIDE** has a single-entry path (exact pathname, no slots) and a multi-entry path (any of body/signal/`<L>` present). Multi-entry path treats target as pathname glob scope, applies body matcher to pathnames (regex/glob), filters by `signal` tags, paginates with `<L>`, and flips visibility on the resulting set.
-- **SEND[410]** with `#fragment` deletes that channel only; without fragment, deletes the whole entry. **SEND[499]** is owned by the streaming scheme that holds the subscription.
+- **FIND body matcher** applies to entry content (all dialects), per-candidate via `Matcher.matchAgainstContent` → `Mimetypes.query` (status 200 = content hit → entry selected). Scope + tags select candidates in SQL; the path-glob is the (target).
+- **SHOW/HIDE** has a single-entry path (exact pathname, no slots) and a multi-entry path (any of body/signal/`<L>` present). Multi-entry path treats target as pathname glob scope, applies the body matcher to entry content (shared with FIND via `matchPathnames`), filters by `signal` tags, paginates with `<L>`, and flips visibility on the resulting set.
+- **SEND[410]** deletes as a side-effect (not the model idiom; §6.5): with `#fragment`, that channel only; without, the whole entry. **SEND[499]** is owned by the streaming scheme that holds the subscription.
 - **File scheme** reads disk content with mimetype detected via `Mimetypes.detect({ path })` (plumbed through `PlurnkSchemeContext.mimetypes`). Binary mimetypes → 415 on READ and EDIT.
 
 ### §16.10 Directed-SEND status code policy

package/bin/plurnk-service.ts

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+
+import { parseArgs } from "node:util";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import SqlRite from "@possumtech/sqlrite";
+import type { Db } from "../src/core/Db.ts";
+import Daemon from "../src/server/Daemon.ts";
+import EnvFlags from "../src/core/EnvFlags.ts";
+import ProviderInstantiate from "../src/core/ProviderInstantiate.ts";
+import { resolveActiveAlias } from "@plurnk/plurnk-providers";
+
+export default class Cli {
+    static #projectRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+    static #die(code: number, message: string): never {
+        process.stderr.write(`${message}\n`);
+        process.exit(code);
+    }
+
+    static #loadEnv(path: string, required: boolean): void {
+        if (existsSync(path)) {
+            try { process.loadEnvFile(path); }
+            catch (cause) { Cli.#die(64, `failed to load ${path}: ${cause instanceof Error ? cause.message : String(cause)}`); }
+        } else if (required) {
+            Cli.#die(64, `--config: ${path} does not exist`);
+        }
+    }
+
+    // The .env cascade always populates these from .env.example, so absence is
+    // a broken config, not a runtime branch — fail hard rather than `?? ""`.
+    static #requireEnv(name: string): string {
+        const value = process.env[name];
+        if (value === undefined || value.length === 0) Cli.#die(78, `missing required env ${name} (declare it in .env.example)`);
+        return value;
+    }
+
+    static async #openDb(dbPath: string): Promise<Db> {
+        const db = await SqlRite.open({
+            path: dbPath,
+            dir: [resolve(Cli.#projectRoot, "migrations"), resolve(Cli.#projectRoot, "src")],
+        });
+        return db as unknown as Db;
+    }
+
+    static async #migrate(): Promise<void> {
+        const dbPath = Cli.#requireEnv("PLURNK_DB_PATH");
+        const db = await Cli.#openDb(dbPath);
+        try { process.stdout.write(`migrated: ${dbPath}\n`); }
+        finally { await db.close(); }
+    }
+
+    static async #start(): Promise<void> {
+        const dbPath = Cli.#requireEnv("PLURNK_DB_PATH");
+        const host = Cli.#requireEnv("PLURNK_HOST");
+        const port = Number(Cli.#requireEnv("PLURNK_PORT"));
+
+        const db = await Cli.#openDb(dbPath);
+        const alias = resolveActiveAlias();
+        const provider = alias === null ? null : await ProviderInstantiate.loadActiveProvider();
+        const daemon = new Daemon({ db, provider });
+        const addr = await daemon.start({ host, port });
+        const aliasStr = alias === null ? "no model" : `${alias.alias}=${alias.provider}/${alias.model}`;
+        process.stdout.write(`plurnk-service ws://${addr.host}:${addr.port} db=${dbPath} ${aliasStr}\n`);
+
+        const shutdown = async (): Promise<void> => { await daemon.stop(); await db.close(); process.exit(0); };
+        process.on("SIGINT", shutdown);
+        process.on("SIGTERM", shutdown);
+    }
+
+    static async main(): Promise<void> {
+        // Env cascade: .env.example (shipped defaults) < .env (project) <
+        // .env.<config> (--config) < shell. process.loadEnvFile is set-if-unset,
+        // so loading in low→high precedence order yields the right effective env
+        // (highest precedence loads FIRST — first write wins).
+        const configFlagIndex = process.argv.findIndex((a) => a === "--config" || a.startsWith("--config="));
+        const configFile = ((): string | null => {
+            if (configFlagIndex === -1) return null;
+            const arg = process.argv[configFlagIndex];
+            if (arg.includes("=")) return arg.slice(arg.indexOf("=") + 1);
+            return process.argv[configFlagIndex + 1] ?? null;
+        })();
+
+        if (configFile !== null) Cli.#loadEnv(configFile, true);
+        Cli.#loadEnv(".env", false);
+        Cli.#loadEnv(resolve(Cli.#projectRoot, ".env.example"), false);
+
+        const flagDescriptors = await EnvFlags.parseEnvExample(resolve(Cli.#projectRoot, ".env.example"));
+        const flagOptions: Record<string, { type: "string" }> = {};
+        for (const f of flagDescriptors) {
+            flagOptions[f.flagName.replace(/^--/, "")] = { type: "string" };
+        }
+
+        const usage = `usage: plurnk-service [options] [migrate]
+
+${EnvFlags.formatFlagsHelp(flagDescriptors)}
+
+  --config=<path>  layer additional env from <path>
+  -h, --help       show this help
+`;
+
+        const { positionals, values } = parseArgs({
+            allowPositionals: true,
+            strict: false,
+            options: { help: { type: "boolean", short: "h" }, config: { type: "string" }, ...flagOptions },
+        });
+
+        for (const f of flagDescriptors) {
+            const key = f.flagName.replace(/^--/, "");
+            const v = values[key];
+            if (typeof v === "string") process.env[f.envName] = v;
+        }
+
+        if (values.help) { process.stdout.write(usage); process.exit(0); }
+
+        const dispatch: Record<string, () => Promise<void>> = { migrate: Cli.#migrate, start: Cli.#start };
+        const subcommand = typeof positionals[0] === "string" ? positionals[0] : "start";
+        const handler = dispatch[subcommand];
+        if (handler === undefined) Cli.#die(64, `unknown subcommand: ${subcommand}\n\n${usage}`);
+        if (positionals.length > 1) Cli.#die(64, `unexpected arguments: ${positionals.slice(1).join(" ")}`);
+
+        try { await handler(); }
+        catch (cause) {
+            process.stderr.write(`${subcommand}: ${cause instanceof Error ? cause.message : String(cause)}\n`);
+            if (cause instanceof Error && cause.cause) process.stderr.write(`  cause: ${cause.cause instanceof Error ? cause.cause.message : String(cause.cause)}\n`);
+            process.exit(1);
+        }
+    }
+}
+
+await Cli.main();

package/dist/Paths.d.ts

@@ -0,0 +1,8 @@
+export default class Paths {
+    #private;
+    static migrations: string;
+    static instructionsSystem: string;
+    static defaultPersona: string;
+    static defaultRequirements: string;
+}
+//# sourceMappingURL=Paths.d.ts.map

package/dist/Paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Paths.d.ts","sourceRoot":"","sources":["../src/Paths.ts"],"names":[],"mappings":"AAaA,MAAM,CAAC,OAAO,OAAO,KAAK;;IAItB,MAAM,CAAC,UAAU,SAA8C;IAC/D,MAAM,CAAC,kBAAkB,SAA6C;IAKtE,MAAM,CAAC,cAAc,SAAkC;IAIvD,MAAM,CAAC,mBAAmB,SAAuC;CAuBpE"}