@plurnk/plurnk-service 1.24.0 → 1.26.0

package/SPEC.md

@@ -133,7 +133,7 @@ package map. The default installed composition is specified in {§bundled-set}.
 
 OpenTelemetry may observe PLURNK; it never becomes product state, failure transport, scheduler input, model teaching, or client protocol. Domain and client activity remain on AG-UI. Reusable packages depend on the OTel API only; the daemon constructs only the explicitly configured trace and metric providers. An unconfigured or standards-valid disabled process loads no SDK or exporter implementation and keeps the API's no-op behavior with bounded overhead. OTel Logs have no provider or initialization path.
 
-Configuration uses the standard `OTEL_*` environment: `OTEL_TRACES_EXPORTER` / `OTEL_METRICS_EXPORTER` select `otlp` or `console` per signal (a missing or `none` value keeps that signal off; no SDK default selects an exporter), `OTEL_SERVICE_NAME` names the service (default `plurnk-service`), case-insensitive `true` in `OTEL_SDK_DISABLED` turns the boundary off, and OTLP exporters honor `OTEL_EXPORTER_OTLP_*`. An unknown exporter name fails daemon boot; a typo never silently disables observation. OTel Logs and direct draft semantic-convention use are excluded. HTTP spans carry only an AG-UI-owned bounded route class, never an input pathname or query. Spans otherwise carry high-cardinality identifiers; metric labels stay low-cardinality. Prompts, reasoning, file bodies, arbitrary URLs, secrets, and plugin payloads are never recorded as attributes or metric values by default. Exporter failure cannot change product results or client lifecycle. Daemon, telemetry, and database teardown are independent reverse-ownership phases; every phase runs and aggregate failure preserves every cause.
+Configuration uses the standard `OTEL_*` environment: `OTEL_TRACES_EXPORTER` / `OTEL_METRICS_EXPORTER` select `otlp` or `console` per signal (a missing or `none` value keeps that signal off; no SDK default selects an exporter), `OTEL_SERVICE_NAME` names the service (default `plurnk-service`), case-insensitive `true` in `OTEL_SDK_DISABLED` turns the boundary off, and OTLP exporters honor `OTEL_EXPORTER_OTLP_*`. An unknown exporter name makes observability unavailable with a configuration diagnostic ({§configuration-repair-path}); offline checking rejects the same input before loading an SDK. OTel Logs and direct draft semantic-convention use are excluded. HTTP spans carry only an AG-UI-owned bounded route class, never an input pathname or query. Spans otherwise carry high-cardinality identifiers; metric labels stay low-cardinality. Prompts, reasoning, file bodies, arbitrary URLs, secrets, and plugin payloads are never recorded as attributes or metric values by default. Exporter failure cannot change product results or client lifecycle. Daemon, telemetry, and database teardown are independent reverse-ownership phases; every phase runs and aggregate failure preserves every cause.
 
 §observability-genai-conventions **GenAI convention projection.** Provider
 request spans follow the [GenAI registry at `c88d504`](https://github.com/open-telemetry/semantic-conventions-genai/tree/c88d504ab3d9879f8e50d3cc87e69775e11db234),
@@ -188,12 +188,13 @@ an explicitly specified subpath, not in the frozen root barrel.
 ```mermaid
 flowchart LR
     LISTENER["Bind client listener<br/>unready: HTTP 503"] --> DB["Acquire daemon lock<br/>and admit SQLite schema"]
-    DB --> PROVIDER["Resolve and verify<br/>selected provider"]
-    PROVIDER --> DAEMON["Construct and start<br/>daemon composition"]
+    DB --> DAEMON["Construct and start<br/>daemon composition"]
     DAEMON --> CLIENT["Activate client transport"]
+    CLIENT --> SELECT["Worker selects or first uses a model"]
+    SELECT --> PROVIDER["Construct and verify<br/>selected provider"]
     LISTENER -. failure .-> FAIL["Fail startup<br/>durable state untouched"]
     DB -. failure .-> CLOSE_LISTENER["Close listener"] --> FAIL
-    PROVIDER -. failure .-> CLOSE["Close database<br/>and release lock"] --> FAIL
+    PROVIDER -. failure .-> REPAIR["Return selection failure<br/>client remains available"]
     DAEMON -. failure .-> TEARDOWN["Close every started owner"] --> FAIL
 ```
 
@@ -220,14 +221,17 @@ address by URL, never by port (#641): AG-UI mounts `/` and `/agui`, A2A the
 well-known card and its endpoint path, on the same address.
 
 §startup-admission-order After listener ownership, database admission completes
-before provider or capability initialization can perform external work. Every
+before capability initialization can perform external work. Provider construction
+and endpoint verification occur on worker selection or first use, never merely
+because a default selector is configured. Startup validates selectors without
+provider I/O and retains their configuration diagnostics. Every
 later startup failure closes resources in reverse ownership order while
 preserving the originating failure: daemon, observability, database, listener.
 
 §startup-readiness-line **Readiness is one stdout line.** After the client interface is mounted
 the service prints exactly one line, `plurnk-service agui=<url> db=<json string> route=<json string>`:
 the URL brackets an IPv6 host, and the database path and the route (the active model route or
-`no model`) are JSON strings, so a path or route containing spaces is exact and a consumer parses
+`no model`, or `invalid model configuration`) are JSON strings, so a path or route containing spaces is exact and a consumer parses
 the URL as a URL and the strings as JSON; nothing else the service prints on stdout before it has
 that prefix. Before the line the listener answers `503 service-starting`; after it,
 `discover` is the identity check a launcher uses to tell this daemon from any other listener. A bind
@@ -378,7 +382,7 @@ direct-entry-plus-directory count; `-1` enables the ordinary markerless page;
 unset / `0` disables previews. `log://` is absent because the current worker's
 log already renders in present mode.
 
-§worker-initialization-entry **Model-worker initialization is a real `_plurnk` turn.** A model worker's first loop begins with one packetless `{ producer="_plurnk", kind="initialization" }` turn submitted through {§turn-ops-admission-path}. Its reasoning and program are stored before execution. NOTEs from its reasoning and program, the orienting READ/FIND surveys, and the reasoning READ in {§reasoning-initial-read} execute under {§op-execution-order}. Its program is announced at `log:///1/1/1/emission` ({§emission-row}) and supplies the worked example as the first request's assistant message ({§packet-wire-envelope}); no program READ, actionless source row or simulated READ is added. Every orienting row is structurally classified `_plurnk` and `init`. The namespace surveys and their asides follow {§actor-boundary-catalog-preview}.
+§worker-initialization-entry **Model-worker initialization is a real reasoning-only `_plurnk` turn.** A model worker's first loop begins with one packetless `{ producer="_plurnk", kind="initialization" }` turn submitted through {§turn-ops-admission-path}. Its authored reasoning contains the orientation NOTE, READ/FIND surveys and its own reasoning READ ({§reasoning-initial-read}); it is stored before those operations execute through {§reasoning-operations} and {§op-execution-order}. No content program or emission row is fabricated ({§emission-row}). The first request sees ordinary results and the reasoning READ, not an assistant-content copy of the surveys. Every orienting row is structurally classified `_plurnk` and `init`. The namespace surveys and their asides follow {§actor-boundary-catalog-preview}.
 
 Incoming messages publish once as inbound SEND rows in the first model turn
 ({§message-arrival}); initialization neither READs nor archives them. The turn
@@ -1049,7 +1053,7 @@ boundary.
 - §worker-lifecycle-wake-liveness **A stream conclusion always reaches its worker.** The stream first persists its terminal state. A worker **blocked on a 202 wait** for that stream ({§wait-obligation-matrix}) then **awakens that loop in place** — the blocked loop *is* the continuation, so there is no fresh loop and no summary-as-prompt fiction. An already-active worker needs no injected prompt or second wake because its next packet reads the durable terminal state. A concluded worker receives no synthetic loop from ambient stream closure. The result remains available in the stream's own state under every case.
 - §worker-lifecycle-child-wake **Each child task completion notifies its parent.** Terminal-task publication, including failure and cancellation of a parked task, notifies the direct parent without injecting a prompt. Other unfinished tasks or streams in that child remain independent obligations; they cannot suppress notification. The parent's eligible waits requeue in place under {§loop-wake-identity} and the bounded {§worker-optimistic-settlement} opportunity. Durable revisioning covers completion-before-park and restart; drain teardown and whole-worker quiescence are not completion identities.
 - §worker-optimistic-settlement **Asynchronous settlement receives one bounded worker-local opportunity before model dispatch.** An initiating turn lets only the streams it started settle before program completion; separately, a stream conclusion, direct-child conclusion or addressed reply persists and publishes immediately but holds eligible parked loops' `202→100` requeues while another stream or direct child remains live. Both use `PLURNK_SERVICE_OPTIMISTIC_WAIT_MS`, shipped at five seconds; zero disables the opportunity. The wake hold ends as soon as no sibling obligation remains, never extends its original deadline, and coalesces arrivals within that window into at most one requeue per eligible loop. With no sibling obligation the wake is immediate; at the deadline, surviving work follows the ordinary monitored lifecycle. An arrival after provider dispatch begins retains its next wake, while poll, new-request and operator wakes never open this hold. Only packet/provider dispatch waits: durable state, client events, cancellation and the replying program do not. One redaction-safe span records elapsed time, quiescence versus deadline, and arrival count without entering the packet.
-- §worker-lifecycle-idle-is-concluded **Idle is not unanswered.** An empty WAIT continues; an eligible final response with answered messages, observed results and no held work concludes under {§wait-obligation-matrix}. A concluded worker retains durable history; a later addressed arrival starts a new loop.
+- §worker-lifecycle-idle-is-concluded **Idle is not completion.** An empty WAIT continues; an eligible parameterless KILL with observed arrivals and results and no held work concludes under {§wait-obligation-matrix}, with or without an answer body. A concluded worker retains durable history; a later addressed arrival starts a new loop.
 - §worker-lifecycle-no-lost-loop **A loop is never stranded by a drain's exit.** A drain relinquishes its registry slot only after a lock-held re-claim confirms the queue is empty; a loop enqueued during that teardown is either re-claimed by the exiting drain or claimed by a fresh drain that a later inject starts. The relinquish and the start are serialized, so neither the lost-loop hang nor a transient double-drain can occur.
 - §worker-lifecycle-durable-disposition **Durable disposition wins cancellation races.** At a turn boundary, the engine reads the loop's durable status before interpreting a process-local abort. A committed `202` park survives a later daemon-shutdown signal; only a loop still durably running at `102` can be terminalized by that cancellation. Wake selection rechecks shutdown and worker cancellation before requeuing each parked loop.
 - §worker-lifecycle-restart-recovery **Restart is owner-loss reconciliation, not replay.** Before opening client transports, the service holds an exclusive database-adjacent daemon lock; a second live owner fails before touching SQLite, while a dead-PID crash claim is replaced atomically without a timeout lease. Boot preserves accepted `100` loops and restores their drains. A `102` loop belonged to a vanished drain/provider call, so it settles `500` with the interruption on its durable row—never replayed across an unknown effect boundary. Every pending physical provider request first settles as an error with absent usage and explicitly unknown cost; then its logical model call closes. Recovery never fabricates zero evidence. Every durable proposed operation likewise lost its process-local resolution waiter and settles as a visible `500 owner_vanished` occurrence rather than an unresolvable interrupt ({§proposal-list}). A pending client interaction also lost its exact awaiting operation, so boot removes the orphan instead of replaying work or inventing a response ({§client-interactions}). Every durable-open subscription belonged to a vanished callable: active channels become errored and its row closes `500`. A `202` continuation requeues on an unseen completion or when no live obligation remains. Otherwise it stays parked on surviving children; the drain restores inherited stream observation through the same guarded scheduler ({§worker-wait-timing}). Child terminalization wakes its parked parent on every outcome, including provider exceptions, cancellation, and restart interruption, recursively through the durable parent edges. These operations are idempotent, so an interrupted recovery safely repeats.
@@ -1078,6 +1082,16 @@ plugin-authored operation turns; exposing that path must not introduce a
 parallel record or lifecycle. Producer and kind never change. Process-restart
 recovery completes any turn whose producer vanished.
 
+§turn-exception-outcome An exceptional inference exit completes every still-open
+turn it acquired, without overwriting completed turns or inventing provider evidence.
+The turn owner propagates the original exception unchanged.
+
+| Exception cause | Turn status |
+|---|---|
+| The owning aborted signal's reason, directly or through an `Error.cause` chain | 499 for cancellation; 504 for the loop execution deadline. |
+| An unrelated exception, including an unrelated `AbortError` concurrent with cancellation | 500. An aborted signal alone does not prove causation. |
+| An `AggregateError` combining cancellation with other failures | 500; cancellation does not conceal another failure. |
+
 §turn-ops-admission-path **Source acquisition varies; admitted-turn execution does not.**
 A provider response, deterministic `_plurnk` program, or future client/plugin
 program crosses one admission boundary into the same executor. That executor
@@ -1214,7 +1228,8 @@ A crossing terminal names the source that struck the crossing turn — `repetiti
 `no_operation`, then `operation` — in its detail, in that order when a turn matches more
 than one. The three are not interchangeable: a turn that authored no operation did not *fail*
 one, and reporting it as a failed turn misreads a model answering without the fence as a model
-whose operations broke. This is the crossing turn's source, not the streak's composition; the
+whose operations broke. A cycle of empty turns names repeated responses without operations,
+not repeated operations or results. This is the crossing turn's source, not the streak's composition; the
 rail rules on the crossing and does not retain the kinds behind it. What the crossing turn
 actually said is cited, not discarded ({§terminal-evidence}). Naming the source is not the
 private accounting {§rail-accounting-private} withholds: the streak, the cycle verdict and
@@ -1277,7 +1292,7 @@ The parser owns its boundaries; core admits determinate work and exposes its fai
 | Bounded program, including malformed operations | Admit valid operations and record parser failures; with no authored operation, apply {§empty-turn}. |
 | Outside response text | Store it as the turn's `outside` source under {§outside-text}; never a row, never delivered, never completion. |
 | Lost boundary after a closed operation | Admit the closed operations and record the boundary diagnostic under {§unparsed-tail-boundary}. |
-| Lost boundary before any closed operation | Reject the attempt; neither outside text nor a reasoning NOTE substitutes for a closed response operation. |
+| Lost boundary before any closed operation | Reject the attempt; neither outside text nor a reasoning NOTE substitutes for a closed operational statement. Reasoning FIND/READ count as such statements ({§reasoning-operations}). |
 | Outside text carrying a log-entry heading, other than an emission row's | Reject the attempt ({§fabricated-log-entry}). |
 | A response the provider stopped at a repeated line | Reject the attempt with the provider's sentence as its diagnostic ({§repetition-stop}); no provider recovery, notice, or problem row. |
 
@@ -1460,9 +1475,23 @@ sequences; native messages and workspace outputs use opaque identifiers rather t
 pretending to be turn coordinates. `worker://<name>` addresses the actor, not a
 historical execution. No address grants ownership or access restrictions.
 
-§fs-namespace **The workspace is a mount namespace; `project_root` is the model's `/`.** A namespace *names*; it does not confine. Host paths do not exist in it, and no engine surface folds a host-absolute spelling onto a member — not because a wall refuses them, but because those coordinates have no meaning here. What the model can reach is exactly the mount table, which the operator composes: a membership overlay routinely mounts a path from above the root (`../house-policy.md` is an ordinary `include` grantor, {§fs-visibility-grantors}), and it arrives named in namespace coordinates like everything else. Plurnk is therefore not a sandbox and claims no containment — confinement is the host's job; what Plurnk owns is authority, consent and audit. The root is **fixed immutably at workspace creation** (headless is forever); the mount table changes only through the declared membership overlay ({§membership}), never by re-rooting. At `project_root = /` the namespace is the whole filesystem and every rule below degenerates to identity — the design's proof case, and the common benchmark topology.
+§fs-namespace **Filesystem coordinates are ordinary paths; internal addresses are project-relative.** `project_root` is the base directory, not a replacement for the operating-system `/`. It is fixed at workspace creation; a headless workspace has no implicit filesystem base. Absolute paths and paths emitted by executors name the same filesystem locations as they do on the host. Resolution never grants membership or creation authority ({§fs-visibility-grantors}, {§fs-write-surface}); an outside-root member retains its `../`-prefixed key. Plurnk is not a sandbox: confinement belongs to the host.
+
+§fs-namei **Resolve, then relativize, through one pathname resolver.** Resolve relative input against `project_root` and absolute input from the operating-system root, normalize lexical `.`/`..` segments, then translate the result to a `project_root`-relative key before storage, comparison or canonical rendering. Physical membership and symlink checks remain separate. No failed absolute lookup retries as a project-relative spelling.
+
+| Input with `project_root=/work/project` | Canonical address |
+|---|---|
+| `src/x.md`, `./src/x.md`, `/work/project/src/x.md` | `src/x.md` |
+| `/src/x.md` | `../../src/x.md` |
+| `../policy.md`, `/work/policy.md` | `../policy.md` |
+| `.`, `/work/project/` | The project collection, not a file entry |
+| `/` | `../../`, the operating-system root collection |
+
+At `project_root=/`, `/src/x.md` and `src/x.md` resolve to the same key. Without a project root, absolute paths cannot be translated; no process CWD or home directory is substituted.
+
+Folders and globs select members in those same filesystem coordinates. Parent-directory selectors may include in-root and outside-root members; they never scan or admit unrelated disk contents. Catalog paths and grouped subtree selectors remain project-relative.
 
-§fs-namei **Resolution is namei over the mount table.** The model's CWD is permanently `/`, so `src/x.md` and `/src/x.md` are the same name — the slash rule is a corollary, never a legislated equivalence. Resolution is lexical: `.` and `..` resolve before anything touches storage (`..` is legal *during* traversal); the final name lands in the root subtree (a bare key), on a declared outside-root mount (a `../`-prefixed key — the git-style overlay), or names nothing (404 carrying the resolved form). Containment is the resolution semantics — there is no separate traversal check to forget.
+§file-path-normalization An authored model file operation using an absolute path receives a `scheme:file/path_normalized` warning Notice naming its project-relative address. COPY/MOVE cover each absolute operand. The Notice neither changes the operation result nor causes a strike, and does not repeat for automatic observations or already-relative paths. Root-mounted workspaces need no such notice. It never suggests that an unadmitted path has become a member.
 
 §fs-canonical-name **One canonical name, storage ≡ wire: the git pathspec.** Member keys follow gitformat-index(5) verbatim (reference edition: git 2.47.3): relative to the workspace `project_root`, without leading slash, `/`-separated, no trailing slash or NUL. Directories are never entries and the root needs no name. When `project_root` is below the containing repository's top level, Git members above it naturally use the same `../`-prefixed CWD-relative names that `git ls-files` emits without `--full-name`; these are not outside-repository mounts. The database stores that root-relative key directly because workspace identity is rooted at the access point. Every model spelling canonicalizes before storage or comparison.
 
@@ -1529,6 +1558,8 @@ invalid range, read-only authority, and occupied hidden state without guessing.
 
 §file-directory-target **A directory is named as a directory.** Inside the root, a READ (or other exact-path read), KILL or EDIT whose target is a directory on disk — with or without a trailing slash — is refused `path-is-directory`, never as a missing or non-member file, since admitting it is not what the model needs: READ and KILL answer 404, EDIT 403. The detail is `'<key>' is a directory, not a file; <OP> reads/removes/writes one file.` and the recovery names the listing that reaches its files, `` List its files with `FIND (<key>/)`, then READ one by its path. `` (KILL: `then KILL each by its path`; EDIT: `` Name a file inside it, as `EDIT (<key>/<file>)`; list its files with `FIND (<key>/)`. ``). Beyond the root the disk stays dark and {§membership-read-refusal} holds unchanged.
 
+§file-find-directory **FIND recognizes existing directories without requiring a trailing slash.** An exact target naming a directory inside the workspace root resolves to the same recursive collection as its slash-suffixed spelling, including content matching and result pagination. Only workspace members appear; an empty directory or one containing only non-members yields a successful empty survey. Exact files stay exact, genuinely absent paths retain their missing-entry error, and this resolution does not inspect disk paths beyond the root. Shared glob and non-file URI semantics are unchanged.
+
 ### §scheme-manifest Manifest
 
 §scheme-manifest-manifest Per the framework-owned author contract ({§manifest}), each registered scheme exposes one closed `SchemeManifest`. `Manifest.of` validates the complete declaration and enforces that `manifest.name` matches `package.json#plurnk.name` before registration.
@@ -2171,11 +2202,12 @@ same transitions the dispatcher's atomic curation event makes, without the row.
 
 ### §reasoning-initial-read Initial reasoning observation
 
-The initialization turn records a short `_plurnk`-authored rationale containing
-a fenced NOTE. The shared reasoning extractor ({§reasoning-notes}) executes that
-NOTE through ordinary dispatch, creating its log item and immutable source.
-The program begins with its own NOTE and READs its reasoning,
-demonstrating both NOTE placements and their ordinary results. The initial message arrives separately as an
+The initialization turn records its `_plurnk`-authored rationale and complete
+NOTE/FIND/READ program as one reasoning source before dispatch. The shared
+reasoning extractor ({§reasoning-operations}) admits every operation once, in
+source order. Its final READ observes that same reasoning source, including
+the READ itself; this is an ordinary read of already stored text, not recursion
+or a future-source subscription. The initial message arrives separately as an
 inbound SEND ({§message-arrival}). Neither initialization nor later turns
 manufacture a task inventory.
 `PLURNK_REASONING_VIEW_LINES` (alias-scoped, default in `.env.defaults`) selects this one READ's
@@ -2184,13 +2216,14 @@ bounds it to the first N lines. Source retention, deliberate READs, and client
 streaming are independent. The only other automatic reasoning READ follows an empty
 turn ({§reasoning-empty-turn-read}).
 
-§reasoning-empty-turn-read **An empty turn's reasoning is read back to the model.** After a
-turn admitted under {§empty-turn}, one runtime turn of the same loop
+§reasoning-empty-turn-read **Operation-free reasoning is read back for recovery.** After a
+turn admitted under {§empty-turn} with no admitted reasoning operations, one runtime turn of the same loop
 (`{ producer="_plurnk", kind="operation" }`) dispatches
 `READ (reasoning://<worker>/<loop>/<turn>) <!-- turn N emitted no OP -->` over that turn's stored
 reasoning source; its receipt renders in the next packet like any other log row.
 `PLURNK_REASONING_EMPTY_TURN_LINES` (alias-scoped, default in `.env.defaults`) selects the scope on the same
-scale as `PLURNK_REASONING_VIEW_LINES`. No read follows a turn without reasoning, and none follows
+scale as `PLURNK_REASONING_VIEW_LINES`. Any admitted reasoning NOTE, FIND or READ suppresses
+this recovery readback. No read follows a turn without reasoning, and none follows
 a turn whose emission or reasoning carries a foreign tool-call grammar or leaked template token
 (`KnownToxins` names them); the strike and its error row are unchanged.
 
@@ -2370,7 +2403,7 @@ single line past the end, a reversed range, empty content, a command's log row
 
 ### §turn-ops-entry The admitted turn program
 
-§turn-ops-log-curation A source-backed turn preserves its **exact admitted Plurnk program**, including ignored interstitial text, before dispatch. `turn_sources` records that source once, separately from the curatable log and optional provider evidence. Retention does not manufacture a log row; the one row an admitted emission gains is its announcement ({§emission-row}). Ordinary READ creates a receipt governed by {§log-readable-projection}; curation of either never changes the source.
+§turn-ops-log-curation A source-backed turn preserves its **exact content emission**, including ignored interstitial text, before dispatch. `turn_sources` records that source once, separately from reasoning, the curatable log and optional provider evidence. Retention does not manufacture a log row; the one row an admitted emission gains is its announcement ({§emission-row}). Ordinary READ creates a receipt governed by {§log-readable-projection}; curation of either never changes the source.
 
 ### §emission-row The emission row
 
@@ -2380,22 +2413,24 @@ like any other row.
 
 | Surface | Contract |
 |---|---|
-| When | An inference turn that admitted at least one statement from its provider content, and turn zero's survey ({§worker-initialization-entry}). A programmatic batch, an empty turn ({§empty-turn}), a client operation and a rejected attempt ({§rejected-emission-entry}) announce nothing. |
+| When | An inference turn that admitted at least one content statement. Reasoning-only turns, including initialization ({§worker-initialization-entry}), a programmatic batch, an empty turn ({§empty-turn}), a client operation and a rejected attempt ({§rejected-emission-entry}) announce nothing. |
 | Place | After the turn's inputs (arrivals, deltas, open-path READs) and before its reasoning NOTEs and operations, written after the selection snapshot ({§turn-ops-selection-snapshot}): the emission sits between what the worker had seen and what it caused. |
 | Row | A `_plurnk` READ of the turn's own source, `ops://<worker>/L/T`, with `attrs.kind="emission"` and the canonical leaf `/emission`: `### log:///L/T/S/emission → ops://<worker>/L/T · N`. It renders its author, the turn's producer, as `origin`, so a model's row carries none. It is no operation: no receipt, tool call or strike, and outside the op mix. |
-| Body | Frozen: the canonical rendering ({§statement-rendering}) of every statement the parser admitted, in order. Free text and unadmitted forms are absent; a recovered native call ({§native-tool-calls}) appears as the operation it was read as; an operation whose receipt failed stays. Turn zero's is its survey as authored. `ops://` keeps the exact source ({§turn-source-resources}). |
+| Body | Frozen at announcement: the canonical rendering ({§statement-rendering}) of admitted content statements, each in a closed fence. Each body appears within the shared preview bound ({§body-projection}), `PLURNK_SERVICE_PREVIEW_LINES` and `PLURNK_SERVICE_PREVIEW_CHARS`. A longer body keeps its head, and its closing fence carries `<!-- Automatically truncated op body: READ (ops://<worker>/L/T) to retrieve in full -->`; nothing the harness writes enters a fence. Absent and empty bodies remain empty. All heading operands, scopes, metadata, patterns and asides remain. Free text and unadmitted forms are absent; a recovered native call ({§native-tool-calls}) appears as the operation it was read as; an operation whose receipt failed stays. Reasoning operations retain their own source and normal receipts, never an assistant-content copy. No body text is inspected for nested operations. |
+| Sources and memory | Dispatch and immutable `ops://` sources retain complete bodies ({§turn-source-resources}); an explicit source READ returns them normally. The wire omits NOTE and WAIT blocks, whose own rows show them whole ({§body-projection}), so curating a NOTE row removes its text; an emission of only NOTE and WAIT delivers nothing, its row stands, and no assistant message follows it ({§packet-wire-envelope}); reasoning-only NOTEs never enter this projection. |
+| Stability | The projection is fixed from its first appearance, never aged or resized under budget pressure. Already frozen announcements and historical request captures are not rewritten. |
 | Presentation | Born folded: the record shows its header, and its body follows the record as the worker's assistant message. |
-| Accounting | `logTokens` charges the record and the emission it delivers ({§packet-token-accounting}). |
+| Accounting | `logTokens` charges the record and the emission the wire delivers, truncation asides included, never the omitted NOTE and WAIT blocks or the cut remainder ({§packet-token-accounting}). An explicit source READ has its own ordinary charge. |
 | Curation | Curated whole ({§log-kill-scope}): KILL retires it, and so does a scope covering every line (`<1,-1>`); on its exact coordinate a narrower scope is 422 `emission-curated-whole`, and a sweep whose scope would only trim it leaves it intact. |
 | Schema | Migration 12 admits `kind="emission"` only on this shape: one per turn, the turn's newest row when written, frozen, and curated whole. A database from before version 12 keeps its rows and gains no announcement. FORK copies it with the inherited turns, still naming its writer. |
-| Echoes | A worker that repeats the heading in its own text is tolerated ({§fabricated-log-entry}); the digest counts the echoes. |
+| Echoes | A worker that repeats the heading in its own text is tolerated ({§fabricated-log-entry}); the digest counts the echoes. A worker that copies the truncation aside onto its own closer keeps its body intact; the aside is outside text ({§outside-text}). |
 
 ### §turn-source-resources Immutable turn-source resources
 
 | Surface | Contract |
 |---|---|
 | Identity | `ops://<worker>/<loop>/<turn>`, `reasoning://<worker>/<loop>/<turn>`, and `note://<worker>/<loop>/<turn>/<item>` name a worker in the current workspace and its durable coordinates. A note's item is its dispatched NOTE ordinal. The `outside` source ({§outside-text}) has no address: no `outside://` scheme exists, and it is reached only through `outside/event`, FORK and the digest. The worker authority is required and case-sensitive; userinfo, ports, and queries are invalid. Source identity never depends on the reading worker. `log:///` remains local; READ, FIND and KILL reject log authorities, userinfo, ports and queries with 400, never substitute the caller's log. |
-| Source | `ops` is exact admitted `text/vnd.plurnk`, and its turn's emission row carries the canonical rendering ({§emission-row}); `reasoning` is `text/plain` containing the selected original provider reasoning or a non-model producer's authored rationale. Producer identity comes from the owning turn; a harness rationale is not provider evidence. The turn decides existence and the source decides content: a turn that exists but has no source of that kind reads as the ordinary empty resource (204, empty body), never a fabricated one; a worker or turn that does not exist is 404. |
+| Source | `ops` is exact admitted `text/vnd.plurnk`, and its turn's emission row carries the preview-bounded projection ({§emission-row}); `reasoning` is `text/plain` containing the selected original provider reasoning or a non-model producer's authored rationale. Producer identity comes from the owning turn; a harness rationale is not provider evidence. The turn decides existence and the source decides content: a turn that exists but has no source of that kind reads as the ordinary empty resource (204, empty body), never a fabricated one; a worker or turn that does not exist is 404. |
 | Notes | Each dispatched NOTE stores its exact literal body as an immutable `text/plain` source and returns its worker-qualified address. There may be multiple notes in a turn, from reasoning, content, or another producer. A missing note is 404, not an empty invented note. Sharing its URI uses ordinary SEND; the receiver deliberately READs it. NOTE itself sends no ambient update. |
 | Retention | One ops source, one reasoning source and one outside source per turn; one note source per NOTE ordinal. An optional inference-call link records provenance. Source removal follows deletion of its owning turn, never log curation. |
 | Operations | Ordinary scoped READ, FIND, content search and COPY from any named worker's source within the workspace. FIND accepts authority and path patterns, retaining complete worker-qualified identities in results and folder selectors. READ returns data and never executes it. Sources are read-only for every actor and have no edit hashes. |
@@ -2631,7 +2666,7 @@ Log history preserved — `log_entries` stores path tuple as text, not FK to `en
 - §find-line-anchors **A FIND regex anchors each line**, as READ, EDIT and KILL do ({§read-pattern}, {§edit-pattern}): `^` and `$` are a line's ends in every FIND content match — over entries, log rows, turn sources and a binary channel's bytes — so ```` ```FIND (django/urls/resolvers.py) /^from|^import/ ```` locates the same import lines a READ with that pattern shows, never a false 204.
 - §find-candidate-containment **One candidate's crash is that candidate's problem** — arbitrary member content can crash a mimetype handler mid-match (an unbalanced template partial crashed Readability and killed a 1,916-file FIND as a blank 500, #449). `Matcher.matchCandidates` contains a per-candidate handler throw: the candidate drops out exactly like unsupported content, the cause goes to daemon stderr, and only a FIND whose every candidate crashed reports a 415 whose Problem names the first crashing member and handler. The operation's other candidates always answer.
 
-- §find-scope-prefix-filter Filters entries within scope. A **bare** path is the exact entry; an explicit **shell glob**, classified once by {§path-glob}, expands to a scope. Path globs use segment semantics: `*` and `?` never cross `/`; `**` does — in every spelling: a `**` glued to a name (`**.go`, `src/**.ts`) is matched as `**/*.go` / `src/**/*.ts`, never demoted to a one-level `*` the way a native matcher reads it. Terminal `*` and `**` are structural catalog selectors and include dot-prefixed entries, so a complete map does not hide `.env.defaults` or `.github`; richer patterns retain native shell behavior. SQLite prefix queries may reduce the candidate set but never decide the match. A trailing slash is a recursive FIND scope only for a scheme whose manifest declares `folderScopes: true`; otherwise it is ordinary resource syntax. This is an explicit plugin contract, never inferred from URL punctuation.
+- §find-scope-prefix-filter Filters entries within scope. A **bare** path is the exact entry unless the file scheme resolves a directory under {§file-find-directory}; an explicit **shell glob**, classified once by {§path-glob}, expands to a scope. Path globs use segment semantics: `*` and `?` never cross `/`; `**` does — in every spelling: a `**` glued to a name (`**.go`, `src/**.ts`) is matched as `**/*.go` / `src/**/*.ts`, never demoted to a one-level `*` the way a native matcher reads it. Terminal `*` and `**` are structural catalog selectors and include dot-prefixed entries, so a complete map does not hide `.env.defaults` or `.github`; richer patterns retain native shell behavior. SQLite prefix queries may reduce the candidate set but never decide the match. A trailing slash is a recursive FIND scope only for a scheme whose manifest declares `folderScopes: true`; otherwise it is ordinary resource syntax. This is an explicit plugin contract, never inferred from URL punctuation.
 
   Resource-authority globs select authorities independently of the path scope.
   Matching resources retain their full addresses through pattern matching,
@@ -2648,7 +2683,7 @@ Log history preserved — `log_entries` stores path tuple as text, not FK to `en
 - §find-fulltext-selection Every matcher operates only over the candidate set selected by `(target)`; indexed matchers do not bypass that selection. `~query` passes the native FTS5 expression to SQLite and ranks matching candidates by ascending BM25, with resource identity breaking ties. Native BM25 uses the shared index's term statistics; candidate visibility, owner, channel and target filters determine which resources can be returned. The ordinary FIND pager selects resources for broad targets or match locations for exact targets: markerless search uses {§markerless-first-page}, `<N>` selects position N and `<N,M>` selects an inclusive range. Fractions are invalid result coordinates, not similarity thresholds. Results expose addressable matched text regions; neither cosine scores nor percentage similarity is invented. Native query-syntax failures return 400 with SQLite's diagnostic; database and implementation failures propagate.
 - §fts-word-phrase **A word with inner punctuation is the phrase of its tokens.** FTS5 barewords hold only letters, digits, `_` and non-ASCII, so before the query reaches SQLite each word outside a quoted string or `NEAR(…)` group that is not a bareword (with optional leading `^` and trailing `*`) is quoted as a phrase: `~inherited-members` searches `"inherited-members"` — the adjacent tokens `inherited members` — instead of failing as `no such column: members`, and `c++`, `x.y`, `a/b` likewise. FTS5's own syntax passes untouched: `AND`/`OR`/`NOT`/`NEAR`, `+`, quoted phrases, parentheses, and column filters (a word containing `:`, `{` or `}`, or opening with `-`). A column-filter failure keeps SQLite's diagnostic and its recovery says what the filter is and gives the bare-word and `NOT` forms: `` `members:` and `-members` are FTS5 column filters, and the index has one column; to search for a word write it bare, as `~members`, and to exclude one write `NOT` between terms, as `~a NOT members`. ``
 - §find-scoped-isolation Workspace + scheme scoped — no cross-workspace/cross-scheme leakage.
-- §find-result-projection **The authored target shape determines the result unit; result cardinality never changes it** ({§find-result-unit}). Returns `FindResult { status, content, mimetype, results, range, matchingPathCount, matchLocationCount, itemsWeightTotal, returnedItemsWeightTotal }`:
+- §find-result-projection **The resolved target selection determines the result unit; result cardinality never changes it** ({§find-result-unit}). Returns `FindResult { status, content, mimetype, results, range, matchingPathCount, matchLocationCount, itemsWeightTotal, returnedItemsWeightTotal }`:
 
   | Target | Matcher | `range.unit` | Result rows |
   |---|---|---|---|
@@ -2734,10 +2769,9 @@ same durable liveness.
 | Fresh operation/parser failure, without an authored WAIT | Continue before any automatic parking. |
 | Neither an authored WAIT nor an eligible completion request ({§kill-conclusion}) | Continue, regardless of earlier replies or live work. |
 | Live work and either WAIT or an eligible completion request | Park the same loop; message arrival, child or stream settlement, or stream cadence wakes it. No final-answer body is delivered while joining. |
-| WAIT without live work | Continue; never invent a future wake. The first such WAIT is an honest yield and its row says only `Nothing is in flight. Continuing.`; a second in the same loop is the model waiting on a wake nothing can send, so its own row instead names what WAIT is for and what to reach for — `WAIT doesn't wait unless there's a child worker or stream to wait on. Use schedule for specific timing decisions.` The correction rides the operation's own result, which is the surface the model is certain to read. |
-| Unanswered messages | Continue. |
+| WAIT without live work | Continue; never invent a future wake. Its row says only `Nothing is in flight. Continuing.`, however often the loop yields this way. |
 | Unobserved operation results, failures, child results or stream conclusions | Continue; the next packet presents them. |
-| Eligible completion request with no outstanding messages, live work or unobserved results | Conclude successfully. |
+| Eligible completion request with no unpublished arrivals, live work or unobserved results | Conclude successfully, whether or not it delivers an answer. |
 
 An empty emission is handled by {§empty-turn}. Ordinary strikes, cycles and
 execution limits remain independent. NOTE and successful targeted KILL do not themselves
@@ -2797,11 +2831,12 @@ accounting and model-visible failure evidence remain separately owned by
   outstanding condition. Valid sibling operations always execute. Only an admitted
   KILL delivers its literal body through {§send-response-receipt}; a deferred body
   remains forensic evidence, never a stored draft to replay automatically. An empty
-  KILL concludes without repeating an already-delivered answer, but cannot abandon an
-  unanswered message. SEND, NOTE and targeted KILL never request successful
+  KILL concludes silently even when an observed message has no delivered answer. It neither
+  invents delivery nor replaces an earlier answer; immutable input and reply history remain intact.
+  SEND, NOTE and targeted KILL never request successful
   completion. New arrivals still guard the terminal transition atomically
-  ({§completion-defers-to-messages}); an arrival concurrent with an accepted reply
-  remains unanswered and keeps the loop running. No implicit successful exit exists.
+  ({§completion-defers-to-messages}); an unobserved arrival concurrent with completion
+  keeps the loop running. No implicit successful exit exists.
 - §outside-text **Text outside the operations is the turn's `outside` source: stored, weighed, never a row.**
   The spans {§response-text} supplies are stored verbatim as one immutable `outside` turn source
   per admitted emission, in source order joined by a blank line ({§turn-source-resources}); no
@@ -2821,15 +2856,16 @@ accounting and model-visible failure evidence remain separately owned by
   {§response-text} alone owns which bytes are operations, quotations or outside text.
 - §loop-answer **A loop's address is what it said.** READ `ops://<worker>/<loop>` resolves to
   the latest reply the loop gave to the message that started it: the body of a SEND
-  or accepted final KILL that answered that message. A running loop without one is 425; a loop that
-  ended without one is its terminal problem (404 when it ended 2xx) — and that problem cites what
-  the model last left unconcluded, so the loop's own address never reports silence from a loop that
-  spoke ({§terminal-evidence}). `ops://<worker>/<loop>/<turn>`
+  or accepted final KILL that answered that message. A failed terminal takes precedence over
+  an earlier reply and retains its exact Problem, including {§terminal-evidence}. A running loop
+  without a reply is 425; a concluded loop without one returns its terminal outcome, including
+  successful silence. Completion never fabricates an answer or a missing-resource failure.
+  `ops://<worker>/<loop>/<turn>`
   remains that turn's emission. A concluded child's `loop_termination` row to its parent
   READs this same loop resource. Witness: `test/intg/loop-answer.test.ts`.
 - §empty-turn **No authored response operation is a recoverable turn, never completion.**
-  Count parsed response operations before reasoning NOTEs join them; neither they nor outside
-  text ({§outside-text}) enter the count. When none exist and no boundary was lost, retain the turn
+  Count parsed content operations and reasoning FIND/READs ({§reasoning-operations}); neither
+  reasoning NOTEs nor outside text ({§outside-text}) enter the count. When none exist and no boundary was lost, retain the turn
   and its raw sources and count one progress-contract strike, whether or not the turn carried text. The strike sends no notice of its own: the turn records one `_plurnk`
   error row, `422` `The turn performed no operation.`, which rides the next packet's errors like
   any failure ({§operation-result-uniform-error-channel}), and its reasoning is read back to the
@@ -2938,8 +2974,9 @@ target that cannot be read keeps the owning READ's failure identity (#163) and s
 the slot contract in its recovery — the resource is the program and the body its stdin;
 a command belongs beneath a targetless heading — without guessing which was meant (#425). The started receipt always
 names the working directory only when it is not the project root, and then in the
-model's own project-relative form ({§fs-namespace}: the root is the model's `/`, so it
-is never rendered, and no receipt or Problem carries a host-absolute path). The `(path)` is a program — a script for an interpreter, a tool name for a tool
+project-relative form ({§fs-namespace}); the default directory is omitted rather
+than repeated in every receipt. Native file addresses resolve from that same project
+directory, while absolute input retains its filesystem meaning. The `(path)` is a program — a script for an interpreter, a tool name for a tool
 family — and neither a command nor a working directory is ever a target. The default
 shell is written as its own fence, ```` ```sh ````; no runtime-less form exists.
 
@@ -3047,13 +3084,15 @@ the workspace snapshot. Installed siblings form the immutable base:
 they are discovered and probed at startup, and availability is cached.
 Workspace Functionality providers may atomically overlay additional names under
 {§module-workspace-capabilities}; a name has one owner within a workspace, while
-independent workspaces may use the same name. An absent or empty tag selects
-`sh`; a non-empty tag selects exactly that registered executable tool. Unknown
-tags are refused 501 with the advertised catalogue and are never reinterpreted
-as shell command words. The common mistaken `[shell]` alias is narrowly told to
-omit that signal for the default shell; arbitrary unknown tags receive no guessed
-alternative intent. An unavailable runtime is also 501 and carries the probe
-`detail`.
+independent workspaces may use the same name. The fence name selects exactly
+that registered executable tool. Unknown tags are refused 400 with the
+advertised catalogue and are never reinterpreted as shell command words.
+A runtime unavailable after an ordinary probe is 501 with the probe `detail`.
+Typed configuration failures preserve the declaration, with no executor instance
+or output scheme; invocation returns the exact 503 configuration Problem
+({§configuration-repair-path}). No executor, including `sh`, is required for
+daemon startup. Internal constructor defects remain failures, not unavailable
+configuration verdicts.
 
 For a family runtime, `ExecutorRegistry.toolRegistry(tag, workspaceId)`
 validates the one executor-owned snapshot used by packet presentation,
@@ -3230,8 +3269,8 @@ Each layer uses the same value and masking rules. A worker's list includes works
 defaults by reference with `origin: "workspace"`; worker overrides and masks remain
 worker-owned. Enabling an inherited entry clears this layer's mask, not a mask in a
 lower layer; an explicit local value can override that lower layer. A mask follows
-the name even when its lower-layer origin changes. Removing an override reveals the lower entry disabled, as for a service
-baseline. Forking copies only worker state, not the workspace defaults. Workspace edits
+the name even when its lower-layer origin changes. Removing an override restores the
+lower entry and its enabledness ({§configuration-definition-resolution}). Forking copies only worker state, not the workspace defaults. Workspace edits
 affect subsequent launches, not existing processes or other workspaces. A shared
 capability never acquires an invoking worker's overrides or ownership.
 
@@ -3297,7 +3336,7 @@ body prefixes.
 
 ## §proposal Proposals and client interactions
 
-§proposal-202-pauses A side-effecting op does not execute on dispatch — it **proposes**. The scheme returns **202** (an execution on a `host` runtime {§exec}, an EDIT to a member file {§membership}); the engine writes the log row `state='proposed'`, registers a waiter keyed by `logEntryId`, and **pauses `dispatch`** awaiting a resolution. The provider exchange and emitted operation are already durable, while the turn remains open until dispatch settles; {§engine-rails} therefore sees the *resolved* status, never the provisional 202. On accept the status becomes 200 and the scheme's effect runs.
+§proposal-202-pauses A side-effecting op does not execute on dispatch — it **proposes**. The scheme returns **202** (an execution on a `host` runtime {§exec}, an EDIT to a member file {§membership}); the engine writes the log row `state='proposed'`, registers a waiter keyed by `logEntryId`, and **pauses `dispatch`** awaiting a resolution. The provider exchange and emitted operation are already durable, while the turn remains open until dispatch settles; {§engine-rails} therefore sees the *resolved* status, never the provisional 202. Acceptance runs the scheme's effect and settles with its result ({§proposal-accept-applies}).
 
 **Resolution arrives through one lifecycle:**
 
@@ -3309,7 +3348,7 @@ body prefixes.
 
 | decision                        | state | `status_rx` | default outcome | effect |
 |---------------------------------|---|---|---|---|
-| §proposal-accept-applies accept | `resolved` | 200 | — | runs the scheme's **`applyResolution`** — the real side effect (disk write, exec spawn). An unavailable handler returns `410 handler-unavailable`, never success. A failing apply (≥400) downgrades to reject, carrying the apply's own outcome — e.g. a member EDIT's `edit_collision` from its write-back compare-and-swap ({§membership-edit-write-cas}) — or `apply_failed` when it names none. |
+| §proposal-accept-applies accept | `resolved`, or `failed` when application fails | applied result's status, otherwise 200 | — | runs the scheme's **`applyResolution`** — the real side effect (disk write, exec spawn). An unavailable handler returns `410 handler-unavailable`, never success. A failing apply (≥400) preserves its result and marks the row failed without changing the client's decision; its outcome is retained, or `apply_failed` when it names none. |
 | §proposal-reject-fails reject   | `failed` | 400 | `rejected` | none — the action did not occur. |
 | §proposal-cancel-aborts cancel  | `cancelled` | 499 | `loop_aborted` | none — the loop is abandoning. |
 
@@ -3431,11 +3470,19 @@ was said ({§methods-loop-run-fold-consistency}). `LoopPolicies.compose` then ma
 once. `PLURNK_SERVICE_ATTENDED` answers an unstated attendance, and the attendance picks which
 knob answers an unstated disposition: `PLURNK_SERVICE_PROPOSALS` for an attended loop,
 `PLURNK_SERVICE_UNATTENDED_PROPOSALS` for an unattended one, whose vocabulary has no `review`.
-Every panel state is therefore lawful, and an invalid knob fails boot by its name. No code,
+Every valid panel state is therefore lawful; an invalid knob is diagnosed at startup
+and refuses a loop that needs it ({§configuration-repair-path}). No code,
 schema or column holds a default ({§operator-config-only-home}): `loops.policy` and
-`loops.max_turns` carry none, so every insert states both, and an administrative loop — a
-client's direct statements, the runtime's own narration — states the panel's policy like any
-other loop whose creator said nothing.
+`loops.max_turns` carry none, so every insert states both. Client-authored administrative
+loops use the same composition.
+
+§runtime-bookkeeping-policy **Runtime bookkeeping has no reviewer and cannot acquire
+new authority.** Its administrative loops explicitly state
+`{ attended: false, proposals: "reject" }`; this is a runtime invariant, not an
+interactive default. Generated reference publication and audit narration therefore
+do not depend on client policy configuration. Runtime-authored proposals do not
+use effect-policy auto-admission; bookkeeping proposals settle as failures through
+the ordinary proposal lifecycle, never wait for a client or auto-accept.
 
 §loop-policy-effective-read `loops.policy` persists one complete immutable
 `LoopPolicy`; every runtime policy read validates that snapshot before use.
@@ -3538,7 +3585,7 @@ No generator. SQLite-optimal: STRICT (3.37+), `INTEGER PRIMARY KEY` aliasing, ex
 | §db-maintenance-optimize Statistics at shutdown | The daemon's last database step before the caller closes SQLite is `PRAGMA optimize` on the writer (`maintenance_optimize`), so `sqlite_stat1` reflects tables the connection planned against, bounded by SQLite's own analysis limit; a failure there is a reported shutdown error, never silent. Retention runs before it under the operator's policy ({§retention-policy}) and ends with a WAL truncation ({§db-space-reclamation}); no periodic `ANALYZE` runs. |
 | §db-space-reclamation The daemon keeps its own file healthy | `PLURNK_SERVICE_AUTO_VACUUM` (`incremental` or `none`) names the mode the daemon keeps its file in. At start, before any drain, a database in another mode is converted (set the mode, one `VACUUM`, which rewrites the file and needs free disk about its size) and the journal says so with page counts before and after. Under `incremental`, every retention pass ends by stepping `PRAGMA incremental_vacuum` to completion once free pages reach `PLURNK_SERVICE_RECLAIM_MIN_FREE_BYTES` (0 = every pass), and reports `reclaimedPages`; below the floor, free pages stay for SQLite to reuse. Under `none` the file never shrinks and freed pages are reused. No operator step is involved beyond the knobs. The WAL stays bounded by SQLite's automatic checkpoint (#764). |
 | §content-store Every body is stored once | `contents` holds each settled body once, addressed by its SHA-256, however many channels, workspaces, forks or derivations carry it; rows are immutable. `entry_channel_rows` points a settled channel at its body and keeps an active stream's body as a private buffer until it settles, when it is interned. Every reader and writer uses the `entry_channels` view, whose `INSTEAD OF` triggers intern bodies, refuse a bound `content_hash` that is not the content's, and write each column group only when it changed, so a search attachment is never a representation write. SQLite counts no changes for a view, so a write that must know whether its channel exists returns the channel's name; an outer join cannot flatten the view, so the two statements that need one read `entry_channel_rows` and `contents` directly. `derivation_fts` is an external-content index over `derivation_texts` (a derivation joined to its body); `derivations.content_id` names the indexed text, and the triggers in `_entry-fts.sql` move the index with it and forget it on delete. A body no channel holds and no derivation indexes is collected by retention under `PLURNK_SERVICE_COLLECT_CONTENTS`. Witnesses: `test/intg/retention.test.ts`, `test/intg/entries.test.ts`, `test/intg/fulltext-index.test.ts`. |
-| §retention-policy Retention is the operator's policy; information is kept by default | `Retention` (`src/server/Retention.ts`, statements in `Retention.sql`) reads ten knobs from `.env.defaults` once at daemon construction (the two storage knobs are {§db-space-reclamation}) and runs four set statements in dependency order — on `PLURNK_SERVICE_RETENTION_INTERVAL_MS` cadence while the daemon runs (0 = shutdown only) and once more at shutdown before `PRAGMA optimize`. `PLURNK_SERVICE_RETAIN_PACKET_TURNS` (-1 = every packet) and `PLURNK_SERVICE_RETAIN_PACKET_MS` (-1 = no age limit) retire a completed turn's packet composition (`turn_sections`, {§packet-items}) once it is beyond the newest N packet-bearing turns of its loop or older than the age; the turn, its bag, its log rows and its accounting stay, and an open turn is never retired. `PLURNK_SERVICE_COLLECT_PACKET_ITEMS` collects items no composition references. `PLURNK_SERVICE_COLLECT_CONTENTS` collects stored bodies nothing holds ({§content-store}), after the collectors that release them. `PLURNK_SERVICE_COLLECT_DERIVATIONS` collects derivations no channel, turn source, or log row cites — superseded editions — with their symbols (cascade) and their full-text shadow (`derivations_delete_fts`, a process trigger beside the FTS statements, on every delete path). `PLURNK_SERVICE_RETAIN_RESPONSE_TURNS` and `PLURNK_SERVICE_RETAIN_RESPONSE_MS` retire a settled call's response body (`model_call_responses`) once it is beyond the newest N body-bearing calls of its loop or its turn is older than the age; the call's identity, failure, capacity, admission and accounting stay, and the digest renders such a call request-only. The durable record is kept; packets and response bodies — transient evidence — age out, so a daemon left running for months stops growing (#788). A malformed knob refuses daemon construction. Witness: `test/intg/retention.test.ts`. |
+| §retention-policy Retention is the operator's policy; information is kept by default | `Retention` (`src/server/Retention.ts`, statements in `Retention.sql`) reads ten knobs from `.env.defaults` once at daemon start (the two storage knobs are {§db-space-reclamation}) and runs four set statements in dependency order — on `PLURNK_SERVICE_RETENTION_INTERVAL_MS` cadence while the daemon runs (0 = shutdown only) and once more at shutdown before `PRAGMA optimize`. `PLURNK_SERVICE_RETAIN_PACKET_TURNS` (-1 = every packet) and `PLURNK_SERVICE_RETAIN_PACKET_MS` (-1 = no age limit) retire a completed turn's packet composition (`turn_sections`, {§packet-items}) once it is beyond the newest N packet-bearing turns of its loop or older than the age; the turn, its bag, its log rows and its accounting stay, and an open turn is never retired. `PLURNK_SERVICE_COLLECT_PACKET_ITEMS` collects items no composition references. `PLURNK_SERVICE_COLLECT_CONTENTS` collects stored bodies nothing holds ({§content-store}), after the collectors that release them. `PLURNK_SERVICE_COLLECT_DERIVATIONS` collects derivations no channel, turn source, or log row cites — superseded editions — with their symbols (cascade) and their full-text shadow (`derivations_delete_fts`, a process trigger beside the FTS statements, on every delete path). `PLURNK_SERVICE_RETAIN_RESPONSE_TURNS` and `PLURNK_SERVICE_RETAIN_RESPONSE_MS` retire a settled call's response body (`model_call_responses`) once it is beyond the newest N body-bearing calls of its loop or its turn is older than the age; the call's identity, failure, capacity, admission and accounting stay, and the digest renders such a call request-only. The durable record is kept; packets and response bodies — transient evidence — age out, so a daemon left running for months stops growing (#788). An invalid policy withholds retention, including storage conversion and shutdown collection, and reports its configuration diagnostic without blocking the client ({§configuration-repair-path}). Storage I/O failures remain ordinary startup or shutdown failures. Witness: `test/intg/retention.test.ts`. |
 
 - DDL = storage truth; JSON Schemas = wire truth. They are allowed to differ where ergonomics demand.
 - §entry-identity-no-null **Identity components are never NULL.** `(workspace_id, scheme, authority, pathname)` is a unique key. `workspace_id` references the workspace directly with cascading deletion. Namespace schemes use empty authority; resource schemes retain their canonical authority. File members use nonempty `scheme="file"` and render as bare paths. Registration refuses `storedScheme: null`.
@@ -3684,11 +3731,14 @@ and is ignored rather than resolved against the working directory.
 
 | Class | Base | Plurnk member |
 |---|---|---|
-| Configuration | `$XDG_CONFIG_HOME` (default `~/.config`) | `plurnk/.env`, `plurnk/AGENTS.md` |
+| Configuration | `$XDG_CONFIG_HOME` (default `~/.config`) | `plurnk/.env`, `plurnk/AGENTS.md`, plurnk-only MCP definitions `plurnk/mcp.json`, Agent Skills `plurnk/skills/<name>/SKILL.md`, and Agent Plugins `plurnk/plugins/<plugin>/` |
 | Durable user data | `$XDG_DATA_HOME` (default `~/.local/share`) | `plurnk/plurnk.db` and SQLite sidecars |
 | Persistent operational state | `$XDG_STATE_HOME` (default `~/.local/state`) | On-demand workspace/module directories ({§module-workspace-directory}). |
 | Reproducible cache | `$XDG_CACHE_HOME` (default `~/.cache`) | Reserved; no directory is created without an owned artifact. |
 | Shared global Agent Skills | User home | `.agents/skills/<name>/SKILL.md` |
+| Shared global MCP definitions | User home | `.agents/mcp.json` |
+| Shared global Agent Plugins | User home | `.agents/plugins/<plugin>/` ({§agent-plugins-hosting}) |
+| A plugin's `PLUGIN_DATA` | `$XDG_DATA_HOME` | `plurnk/plugins/<plugin>/` |
 
 §state-root **A private daemon has one root.** `PLURNK_SERVICE_STATE_ROOT` (absolute; a leading
 `~/` expands; a relative value fails hard by name) replaces the data, state, cache and runtime homes
@@ -3710,15 +3760,34 @@ ordinary precedence; XDG variables themselves require absolute paths.
 |---------:|------------------------------------|-----------------------------------------------------------|
 |        1 | Assembled package `.env.defaults` | Set-if-unset floor; one owner per key.                     |
 |        2 | `$XDG_CONFIG_HOME/plurnk/.env`     | User-level ambient configuration.                         |
-|        3 | `./.env`                           | Working-directory ambient configuration.                  |
-|        4 | `--config=<path>`                  | Singular service-owned explicit file.                     |
-|        5 | `--env-file*`                      | Repeatable explicit files; later selected files win.      |
-|        6 | Initial shell environment          | Preserved over every file layer.                          |
-|        7 | Derived service CLI flags          | Assigned last.                                            |
+|        3 | `--config=<path>`                  | Singular service-owned explicit file.                     |
+|        4 | `--env-file*`                      | Repeatable explicit files; later selected files win.      |
+|        5 | Initial shell environment          | Preserved over every file layer.                          |
+|        6 | Derived service CLI flags          | Assigned last.                                            |
+
+A working directory's `.env` configures that directory's application, never plurnk (#926); a
+project's variables reach its commands through the workspace environment ({§workspace-env}).
 
 Node's pre-script env-file form and the executable's post-script form share the same later-file-wins ordering. `--env-file-if-exists` skips an absent file without changing the order of selected files.
 
-§operator-config-env-defaults **Every package owns its knobs — `.env.defaults` is the standard.** Each package in the daemon's ecosystem — internal or third-party — ships a `.env.defaults` at its package root declaring its own knobs; the file is the package's configuration reference, traveling in the tarball and changing with the code that reads it. At boot the daemon assembles every installed member's file into one floor (membership = the `@plurnk/*` scope or a `plurnk` package.json field, gated by `PLURNK_PLUGINS_TRUSTED_ONLY` with discover()'s exact semantics) and applies it set-if-unset under every operator source. `plurnk-service config defaults` renders the same complete, owner-labelled aggregate to stdout on demand, preserving comments and optional declarations without persisting a second copy or exposing effective secret values. A key claimed by two packages fails boot naming both. With the reader-declares discipline, each key has one implementation and one defaults owner.
+§operator-config-env-defaults **Every package owns its knobs — one assembled floor.**
+
+| Source | Panel | Admission |
+|---|---|---|
+| Platform capability package | `.env.defaults` at the package root | `@plurnk/*` or a `plurnk` package field; {§plugin-trust-boundary} |
+| Agent Plugin native extension | `ai.plurnk/.env.defaults` | The winning daemon-wide plugin in {§agent-plugins-hosting}, a valid native declaration, and the same trust gate |
+
+Root and trust flags apply before collection. A project plugin contributes no native panel.
+Non-module native panels follow their npm-only family discovery ({§plugin-manifest-read});
+a plain-folder declaration does not suppress an installed capability's panel.
+Linked packages resolve panels against the same canonical root as native code;
+an absent panel is optional, but a panel escaping that root is rejected.
+The file travels with its code and is its configuration reference. All admitted files compose
+one floor, applied set-if-unset beneath operator sources. `plurnk-service config defaults`
+renders those same owner-labelled files, preserving comments and optional declarations without
+persisting another copy or exposing effective values. Duplicate key ownership fails naming both
+owners. Invalid optional native panels are diagnosed and prevent that extension from loading;
+they do not block the remaining floor or the repair path ({§configuration-repair-path}).
 
 §operator-config-only-home **The cascading environment is the only home for a choice.** The principle and its reasons are ARCHITECTURE.md's (*Configuration authority*); this is what `scripts/env-surface-policy.mjs` enforces in `root:lint`, over the source Git tracks:
 
@@ -3750,6 +3819,34 @@ or provider request. The seeded `.env`, first-run diagnostic, service help, and
 missing-model recovery all signpost `plurnk-service config defaults` as the
 complete installed option catalog.
 
+§operator-config-offline-validation **`config check` and runtime use the same
+owning configuration readers, with different failure boundaries.** An offline
+check rejects invalid configuration with a nonzero exit. Runtime contains
+optional-family errors according to {§configuration-repair-path}. Failure
+names the offending variable or file/entry and retains its cause.
+
+| Owner | Offline validation |
+|---|---|
+| Core | Model selection, file-creation/effect/loop policy, members definitions and controls, skill-fetch settings and root selection |
+| MCP | Whole definitions from the environment and selected files (cwd is the project for this check), future-alias controls, catalog settings, timeouts, retry pacing and registry URL |
+| A2A | Whole outbound definitions and controls, timeout/diagnostic bounds, configured inbound exposure |
+| Schedule | Whole definitions and controls, recurrence syntax, time zone and preview count |
+| Hooks | Command/argument/event configuration and delivery bounds |
+
+Disabled definitions and controls without a resource are validated, not skipped.
+Checking creates no database, starts no process or listener, arms no schedule,
+and contacts no provider or endpoint. Symbolic credential references remain
+symbolic: availability belongs to workspace preparation, not offline validation.
+
+First-run seeding publishes the complete private configuration directory atomically.
+Concurrent initializers adopt the winning seed; a failed initializer removes only
+its own staging directory. An existing operator directory is never reseeded.
+
+§systemd-user-unit The service package ships `plurnk.service` as an example
+systemd user unit. Installation and enablement are explicit operator actions;
+package installation performs neither. The template documents executable-path
+and environment adjustments instead of introducing a service-management command.
+
 Model selection uses one selector vocabulary in `ProviderRegistry` ({§provider-instantiation}). `PLURNK_MODEL_<alias>=<provider>/<model-id>` optionally declares a friendly route and tuning scope; `PLURNK_MODEL=<selector>` selects either that alias or an exact provider/model route. `PLURNK_MODEL_CHILD=<selector>` uses the same vocabulary for the default child provider; unset means inherit the spawning loop's provider. Operator selections and alias declarations live in `.env`, not `.env.defaults`.
 
 Each knob's value lives on its panel and nowhere else (`plurnk-service config defaults` prints them all); this table says what the service's knobs mean.
@@ -3870,7 +3967,7 @@ the policy renders in exactly one packet section. Every other tier runs the
 test cascade, so shipped-default regressions are otherwise invisible by
 construction.
 
-§operator-config-real-model-profile **Real-model gate profile.** `plurnk-core/.env.test` is committed source and is the single shared profile for live, demo, and the candidate daemon used by benchlets. Live/demo load it after operator files; the candidate daemon loads it below its inherited environment. Direct shell/benchmark overrides win in both paths. Its exact allowlist is limited to gate-wide service posture that is identical on every machine: complete catalog orientation, automatic Git membership when the operator ceiling permits Git, ambient operator-file docs/packet notes cleared, ambient MCP selections and schedules disabled, and `PLURNK_EXECS_QUESTION=0` for unattended runs. The ordinary executor switch removes the question tool and its teaching; an explicit override can opt into an attended drill. Configuration with a narrower or variable owner stays outside it:
+§operator-config-real-model-profile **Real-model gate profile.** `plurnk-core/.env.test` is committed source and is the single shared profile for live, demo, and the candidate daemon used by benchlets. Live/demo load it after operator files; the candidate daemon loads it below its inherited environment. Direct shell/benchmark overrides win in both paths. Its exact allowlist is limited to gate-wide service posture that is identical on every machine: complete catalog orientation, automatic Git membership when the operator ceiling permits Git, ambient operator-file docs/packet notes cleared, the operator's installed skills and plugins left unread ({§agent-roots}), ambient MCP/A2A and schedules default disabled, and `PLURNK_EXECS_QUESTION=0` for unattended runs. The ordinary executor switch removes the question tool and its teaching; an explicit override can opt into an attended drill. The drivers also project per-alias `ENABLED=0` overrides for named MCP, A2A, schedule, membership, and skill resources in the operator's config file. Definitions remain inspectable; explicit shell/benchmark controls win. Mock-tier bootstrap clears these ambient families before loading its fixture floor. No operator file is rewritten. Configuration with a narrower or variable owner stays outside it:
 
 | Owner | Configuration |
 |---|---|
@@ -3953,36 +4050,55 @@ proceeds. `setup` is the readiness boundary for every capability registered
 with Core: recovery may demand a workspace provider before `start`. For a
 pre-bound client interface, requests remain unavailable until `start`; every
 other module opens its module-owned exterior ingress only after recovery. No
-registered capability may depend on exterior ingress. Shutdown begins started
-and self-closing module closure in reverse order and surfaces aggregated close
-failures.
-
-§module-discovery **Third-party daemon-module composition is manifest
-discovery.** A package declares `plurnk: { kind: "module", module:
-"<export-subpath>" }`; the export is one DaemonModule (an object, or a no-arg
-factory returning one). At boot, core scans installed packages under the
-executor family's discovery and trust rules ({§plugin-discovery}) and
-registers every trusted declaring module before any module setup runs, in
-package-name order. The service's explicit composition — the AG-UI,
-hooks, and MCP modules — carries init options and is wired in service.ts;
-discovery never duplicates those packages. An untrusted declaring package is
-skipped with a boot warning, never executed. A module export that is neither
-an object nor a no-arg factory, a factory returning a non-object, or an object
-with a non-function lifecycle member fails boot loudly.
+registered capability may depend on exterior ingress. A module, and any distinct
+lifetime object returned by `start`, may implement the following phases:
+
+| Phase | Obligation |
+|---|---|
+| `stop()` | Reject new ingress, stop timers and other producers, and settle owned work that can emit core events. Keep event subscriptions and resources needed for settlement alive. |
+| `close()` | Unsubscribe observers and release remaining resources after producer settlement; await admitted notification deliveries. Do not start new core work. |
+
+Both phases are optional and idempotent; repeated calls join the same work.
+Core tracks a module before `setup` so partially acquired resources are released
+even if setup fails. A returned object identical to its module is tracked once.
+
+§module-discovery **Daemon modules compose through their shared lifecycle.**
+
+| Source | Declaration | Lifetime |
+|---|---|---|
+| Platform capability package | `package.json#plurnk` with `kind: "module"` and `module` | Daemon-wide |
+| Agent Plugin | `plugin.json#extensions.ai.plurnk` with `kind: "module"` and a `module` path under `ai.plurnk/` | Daemon-wide; npm and selected user roots only |
+| Project Agent Plugin | Portable components only | Workspace-scoped; native code is not imported |
+
+The export is one DaemonModule object or no-argument factory. Standard bundles follow
+{§agent-plugins-hosting} source order, then other installed module packages load in package-name
+order. All trusted modules register before setup. The service's explicit AG-UI, hooks and MCP
+composition is never duplicated. Untrusted modules are reported and not imported. Invalid
+declarations, unavailable module files and configuration errors during construction are diagnosed
+at the affected native extension; healthy siblings remain available. A factory validates startup
+configuration before `setup` acquires resources. Failures after registration begins follow
+{§module-lifecycle} cleanup, not a partial-registration fallback.
+An invalid module object, factory result or lifecycle member is an implementation contract failure,
+not configuration, and fails loudly. Native capabilities register through their owning public
+interfaces and release registrations during {§module-lifecycle} resource teardown.
 
 §module-shutdown-order `Daemon.stop()` first rejects new capability demand and
-aborts proposals, branches, derivations, and worker scopes. It simultaneously
-begins every module closer in reverse registration order, allowing exterior
-listeners to stop accepting work while active requests observe those
-cancellations. It then settles branches, drains, module closers, streaming
-producers, derivations, mimetypes, and schemes before its final worker-settlement
-barrier. The supervisor owns each asynchronous cancellation and wake task from
+aborts proposals, branches, derivations, and worker scopes. It begins module
+`stop()` calls in reverse registration order without serially awaiting them,
+so every producer is asked to stop even if another stalls. Core settles drains,
+capability publications, module producers, streaming producers, derivations,
+mimetypes, schemes, and the final worker-settlement barrier while observers
+remain subscribed. Only then does it begin and join module `close()` calls in
+reverse order. Failures do not skip later phases and join one shutdown aggregate.
+The supervisor owns each asynchronous cancellation and wake task from
 acceptance through settlement, including immediately acknowledged and explicitly
 awaited cancellation; a task failure participates in the shutdown aggregate.
 After asynchronous selection, the supervisor rechecks shutdown before creating
 a drain or installing a timer; parked-loop wake mutations also recheck worker
 cancellation under {§worker-lifecycle-durable-disposition}.
-The database may be released only after the final settlement barrier resolves.
+The database remains available through observer closure and final maintenance.
+The shared deadline bounds every phase, including observer delivery; forced
+shutdown may therefore lose notifications and reports the unfinished phase.
 
 §crash-only-stop The settle sequence is deadline-bounded
 (`PLURNK_SERVICE_STOP_TIMEOUT_MS`, default 30000): past the deadline each wait
@@ -3996,21 +4112,22 @@ backstop, not the exit.
 ```mermaid
 flowchart LR
     stop[Begin stop] --> abort[Abort core producers]
-    stop --> moduleClose[Begin reverse module closure]
+    stop --> moduleStop[Begin reverse module stop]
     abort --> drains[Settle worker drains]
-    drains --> joined[Settle module closures]
-    moduleClose --> joined
+    drains --> joined[Settle module producers]
+    moduleStop --> joined
     joined --> producers[Settle streaming producers]
     producers --> resources[Dispose derivations,<br/>mimetypes, and schemes]
     resources --> settlement[Settle cancellations and wakes]
-    settlement --> database[Release database]
+    settlement --> observers[Close observers and resources]
+    observers --> database[Maintain and release database]
 ```
 
 | Setup function | Contract |
 |---|---|
 | `registerRuntimes([{ decl, executor, availability, scheme? }, ...])` | Validates the complete canonical tag set under {§executor-runtime-declaration}, then publishes every process-wide executor and optional claimed scheme facet atomically. |
 | `registerScheme(name, handler)` | Adds one process-wide addressable scheme handler; scheme readiness and model-facing capability publication remain core-owned. |
-| §module-action-registration `registerModuleAction({ name, scope, inputSchema, outputSchema, handler })` | Adds one non-empty, extension-unique action with resolvable JSON Schemas. `scope` is exactly `worldless`, `workspace`, or `worker`; the handler receives schema-validated params and a separate matching context. Scoped contexts contain trusted bound identifiers, never client parameters. A client-interface module decides whether and how the name becomes public, validates successful output, and owns collisions with its built-ins. |
+| §module-action-registration `registerModuleAction({ name, scope, residency, inputSchema, outputSchema, handler })` | Adds one non-empty, extension-unique action with resolvable JSON Schemas. `scope` is exactly `worldless`, `workspace`, or `worker`; the handler receives schema-validated params and a separate matching context. `residency` is explicitly `required` or `none`: only the former acquires workspace capabilities and reconciles worker documents. Worldless actions require `none`. Scoped contexts contain trusted bound identifiers, never client parameters. A client-interface module decides whether and how the name becomes public, validates successful output, and owns collisions with its built-ins. |
 | §module-workspace-provider `registerWorkspaceCapabilityProvider(namespaceOwner, provider)` | Registers one extension-unique Functionality provider. `activate({ workspaceId, retain })` reconstructs the workspace snapshot; idempotent `deactivate({ workspaceId })` releases process resources. Core coalesces demand and supplies residency leases for work that outlives its caller. |
 | §module-workspace-state `readWorkspaceModuleState(workspaceId, namespaceOwner)` | Reads one nullable JSON state value per workspace and provider. Core owns storage and lifecycle; the provider owns its schema. Store symbolic credential references, not copied secrets. A worker-scoped family's coordinator reads and replaces the same shape per worker in `worker_module_state` ({§functionality-scope}). |
 | `readWorkspaceEnvironment(workspaceId)` | Captures the workspace env layer ({§workspace-env}) and returns its composer. No argument uses admitted host values; a supplied environment supplies a module's reference-resolution context. Both apply the same captured values and masks, without worker overrides. |
@@ -4060,7 +4177,7 @@ A conflicting alias is rejected explicitly; it never produces a hidden second
 definition for the submitting client or worker.
 
 §module-workspace-residency **Persistence is not residency.** Model execution,
-capability-aware operations, scoped module actions, and retained provider work
+capability-aware operations, module actions declaring required residency, and retained provider work
 lease the workspace's Functionality. Boot, workspace or worker creation,
 attachment, listing, naming, idle clients, and parked state alone do not.
 After the last lease releases, `PLURNK_SERVICE_WORKSPACE_WARM_MS` and
@@ -4090,10 +4207,10 @@ registry. Deleting the workspace cascades its state; worker lifecycle does not.
 ## Workspace Functionality
 
 §functionality-coordinator **One coordinator owns the common lifecycle.**
-Agent Skills, MCP, outbound A2A agents, and membership are adapters beneath
+Functionality families are adapters beneath
 `list | discover | add | enable | disable | remove`. State and mutations
-serialize per workspace and family. Client actions
-`workspace.<family>.<verb>` and model manager executors invoke the same
+serialize per workspace and family. Scope-bound client actions
+`workspace.<family>.<verb>` / `worker.<family>.<verb>` and model manager executors invoke the same
 coordinator. Families do not invent another management grammar, proposal
 policy, or hotload path.
 
@@ -4101,12 +4218,98 @@ Retryability describes the actual failed condition, not its numeric status.
 
 | Verb | Common contract |
 |---|---|
-| `list` | Project definitions, origin, enabledness, and preparation outcome: disabled, active, unavailable with its Problem, or authorization-required. No credential values. |
+| `list` | Project definitions, ownership (`origin`), winning configuration source (`provenance`), enabledness, and published preparation outcome: disabled, dormant, active, unavailable with its Problem, or authorization-required. No credential values. |
 | `discover` | Return inert candidates. Never install, persist, enable, or execute them. |
-| `add` | Admit and persist a workspace definition, prepare it, and enable it atomically. It may override the service baseline. Reapplying the same workspace definition enables it idempotently (200); a different definition for that alias fails 409 without replacing it. |
+| `add` | Admit and persist a local definition, prepare it, and enable it atomically. It may override an inherited definition. Reapplying the same local definition enables it idempotently (200); a different local definition for that alias fails 409 without replacing it. |
 | `enable` | Publish an available definition; retry preparation if unavailable. |
 | `disable` | Withdraw live capability; retain its definition and saved results. |
-| `remove` | Disable and forget the workspace definition. A same-alias service baseline reappears disabled. Service definitions are disable-only. Saved results remain. |
+| `remove` | Forget the locally owned definition and its enabledness override. Restore any inherited definition with its inherited enabledness. Inherited definitions cannot be removed at this scope. Saved results remain. |
+
+§configuration-definition-resolution **Named resource definitions replace whole;
+independent behavior controls remain independent.** Source readers and scope
+overlays apply the same boundary:
+
+| Value | Resolution |
+|---|---|
+| Named definition | Select the complete definition from the highest-precedence source or scope declaring that alias. Omitted fields, arrays and nested objects never inherit from a lower definition. |
+| Environment resource declaration | Use {§resource-environment}: absence inherits, an empty definition is invalid, and an explicit enabledness switch disables without erasing the definition. |
+| Definition validity | Validate the selected definition against its family's schema. Missing required fields are errors, not requests to fill from a lower definition; rejected live changes preserve the previous publication. |
+| Independently declared behavior control | Resolve its own value through its cascade. An enabledness override does not copy or patch the definition it controls. |
+| Local definition removal | Remove this scope's definition and enabledness override. Restore the current inherited definition and enabledness, or leave no entry if none exists. Do not persist a replacement or disabling mask; subsequent inherited changes remain effective. Restoration follows the same preparation and publication failure policy as other mutations ({§functionality-publication}). |
+
+§configuration-provenance **Inspection names the winning definition's input, not
+its owner or runtime.** `provenance` uses the same `{kind, source, reference?}`
+shape as discovery candidates. Source readers contribute it; the coordinator
+preserves it through inheritance, enabledness changes, and every readiness state.
+
+| Definition source | Inspection |
+|---|---|
+| Assembled environment | `kind: environment`, `source`: exact definition key; never its value or an inferred dotenv filename. |
+| Discovered skill root | `kind: file`, `source`: the winning `SKILL.md` path. |
+| Standalone MCP file | `kind: file`, `source`: the winning `mcp.json` path; `reference`: its entry's JSON Pointer. |
+| Local workspace/worker definition or host-provided tree with no configuration input | No fabricated provenance; `origin` identifies ownership and the family definition describes the resource. |
+| Local override | Replaces inherited provenance with the local definition; removal restores the current inherited provenance. |
+
+Only the winning definition's source is reported. Shadowed definitions, secrets,
+and environment-file loading history are not tracked. Source metadata is derived
+on inspection, not persisted in the local overlay or used as runtime identity.
+
+§configuration-repair-path **Invalid optional configuration cannot remove the
+agent's repair environment.** Capability owners reject typed operator input
+errors. The launcher and shared coordinator contain them at their respective
+composition boundaries, not arbitrary exceptions:
+
+| Boundary | Outcome |
+|---|---|
+| Optional startup integration (hooks, hosted A2A, observability) cannot be configured | Withhold that integration and retain its exact configuration diagnostic. Activate the client interface and unrelated capabilities; never invent a replacement setting. |
+| Invalid default model or child selector | Retain its diagnostic at startup; keep client inspection and explicit selection available. A request relying on the invalid selector fails with `daemon:configuration/configuration-invalid` (503), naming its key. Never substitute another model or silently inherit a child model. |
+| Model construction or endpoint verification fails | Reject selection/use before inference or committing the selection. Keep the client available; a later selection can retry or choose another route. |
+| Invalid effect, file-creation, or loop-default policy | Retain the startup diagnostic. Reject the affected operation or unresolved loop policy as `daemon:configuration/configuration-invalid` (503); no guessed admission policy, external effect, or orphan approval wait. Independent operations and explicitly supplied valid loop policies remain usable. |
+| Invalid retention configuration | Withhold collection and automatic storage conversion, including shutdown collection. Preserve stored evidence and expose the diagnostic; do not substitute a deletion policy. |
+| Invalid packet configuration or retired capacity knobs | Retain the startup diagnostic and keep client inspection available. Reject affected packet construction before inference with `daemon:configuration/configuration-invalid` (503). Never guess a capacity or projection setting. |
+| Invalid executor construction/probe configuration | Keep the installed declaration and its diagnostic, but no executable instance or output scheme. Other executors and ordinary READ/EDIT remain usable. Invoking the unavailable tag returns its exact 503 configuration Problem. |
+| Invalid execution scheduling, input, or scratch configuration | Diagnose at startup and validate on the affected execution path before admission, stream creation, or external effects. Scratch configuration applies only to resource-backed execution; inline programs remain independent. Never substitute concurrency, timeout, or directory settings. |
+| Invalid model-alias catalog | Fail catalog inspection explicitly; omit its unavailable snapshot rather than report an empty catalog. Exact provider/model selection does not depend on aliases. |
+| Offline `config check` | Validate the same inputs without activating integrations; an invalid setting remains a nonzero failure. |
+| Family configuration cannot be resolved | Keep its manager available, identify the configuration failure in its generated documentation, and preserve durable definitions. Do not publish the family's operational capabilities or pretend its catalog is empty. Other families and ordinary model work remain usable. |
+| Inspection or mutation of an unresolved family | Return the exact configuration Problem, naming the key and required correction, through both client and model paths. No silent source fallback or change to stored settings. |
+| Invalid live mutation | Reject atomically and preserve the preceding publication. |
+| Previously valid family becomes invalid | Withdraw its operational capabilities at normal publication, then release the old snapshot. Keep the manager and diagnostic. |
+| Configuration source is corrected or removed | Inspection resolves the current source immediately, even in the repairing turn; a previous source-resolution error cannot override a successful read. Not-yet-published definitions remain dormant. Normal publication restores capabilities; inspection does not activate them. |
+| Preparation configuration is corrected | The published preparation failure remains until ordinary preparation succeeds. Successful source inspection alone does not establish runtime readiness. Environment-file edits follow their ordinary process lifetime, not an implicit reload. |
+| Internal invariant, state, or implementation failure | Preserve the exception; never reclassify it as an operator configuration error. |
+
+Client discovery and passive synchronization report startup diagnostics through the
+existing Notice channel, even without a usable model. The first turn of a drain, and a changed diagnostic
+thereafter, reports unresolved configuration to both client and model. An
+unchanged diagnostic is not repeated every turn. Operation failures remain Problems.
+
+§functionality-inspection **Inspection is not demand.** `list` and `discover` do not
+acquire residency, join preparation, reconcile worker documents, or extend warm
+retention. An enabled definition no resident publication has prepared is `dormant`: every one while
+the family is cold, and one that arrived or changed out of band until the next turn publishes it
+({§functionality-hotload}). During replacement the preceding publication remains authoritative;
+the candidate is never presented as active. A published outcome belongs to the
+complete definition prepared, not merely its alias. Cooling leaves durable definitions
+inspectable. Mutations and protocol continuations retain their residency rules.
+
+§functionality-preparation-visibility **Preparation is workspace activity, not
+model context.** The coordinator owns a current `FunctionalityPreparationActivity`
+per preparing family. `workspacePreparationStatus(workspaceId)` returns that same
+state without demand; `workspace/preparation` broadcasts
+`{ workspaceId, preparation: [...] }` whenever it changes.
+
+| Boundary | Visible state |
+|---|---|
+| Preparation begins | Family, `phase: preparing`, `alias: null`, UTC `since` |
+| Adapter calls `progress(alias)` | Enabled alias being prepared; a fresh `since` |
+| Prepared candidate enters publication | `phase: publishing`, `alias: null` |
+| Commit, rejection, or rollback settles | Family removed; empty array means no preparation |
+
+Preparation reports neither definitions nor credentials, does not alter the
+publication contract, and creates no log entries or model Notices. Published
+failures retain their exact Problems in `list`. Concurrent consumers share the
+workspace activity; a client disconnect does not clear another consumer's work.
 
 §functionality-adapter **An adapter owns protocol truth.** It declares its
 family, namespace owner, definition schema, contributed defaults, discovery,
@@ -4116,16 +4319,66 @@ family declares, at admission, in the service projection, and on persisted
 state, so an environment variable's name is an alias exactly as a skill name
 is. Admission distinguishes explicit client
 actions from model operations where the family contract requires it
-({§members-model-scope}). Preparation returns runtimes, documents, per-alias
+({§members-model-scope}). Preparation receives each complete definition with optional
+adapter-owned interpretation context. Context is source semantics, not policy or provenance;
+it participates in runtime identity and hot-load comparisons, is never projected as configuration
+or persisted into a workspace override, and cannot survive replacement by a local definition.
+Removing that override restores the current inherited definition and context together.
+Descriptive provenance alone does not change runtime identity. Preparation returns runtimes, documents, per-alias
 outcomes, and a snapshot with `commit`/`abort`. Successful publication commits;
 failure aborts; cooling tears down. Protocol continuations remain ordinary
 module actions. Optional `forget` releases an installed or provisioned
-definition before removal; failure rejects removal ({§skills-remove}). The
+definition before removal; failure rejects removal. The
 seam's shapes — the identity a verb acts under, its options, definition
 sources, outcomes, preparation, the prepared result and the family handle —
 are declared once in `plurnk-contracts` and imported by core and every
 module; core adds only its own face of the seam, the runtime registration a
 resident family prepares and the scheme facet it may expose.
+An adapter may expose current partial-source `configurationNotices`; these join the ordinary
+workspace diagnostics without preventing independently valid definitions from preparing.
+
+§functionality-hotload **Out-of-band state is admitted before the next turn.** An adapter whose
+`available` reads state that changes outside the daemon, such as skill roots ({§skills-hotload}) or
+installed plugins ({§agent-plugins-hosting}), implements `refreshIfChanged`. Turn admission calls it
+for every family under the workspace gate before packet assembly. The family handle's `refresh` with
+`ifChanged` republishes a resident family only when the enabled definitions it would prepare differ
+from the ones its publication prepared. The coordinator makes that comparison because it alone knows
+what it published, so a change `list` saw first is still published at the next turn. A family whose
+definitions do not capture its published content, such as a skill's files, republishes
+unconditionally when that content changed. An unchanged family dispatches nothing.
+
+§agent-plugins-hosting **Installed Agent Plugins are found like skills.** A workspace's plugins are
+the immediate child directories of its project's `.agents/plugins`, then
+`$XDG_CONFIG_HOME/plurnk/plugins` (plurnk alone), then `~/.agents/plugins` (every agent), loaded and
+validated by `@plurnk/plurnk-agent-plugins` ({§agent-plugins-roots}), followed by standard plugin
+bundles in the installed npm graph. An earlier source shadows a later plugin of the same manifest
+name, regardless of distribution or directory name. Native discovery uses that same cascade with
+the project root omitted; workspace discovery includes it. A plugin's `PLUGIN_DATA` is
+`$XDG_DATA_HOME/plurnk/plugins/<name>/<sha256(canonical-root)>`, kept across in-place updates and
+moved with a state root ({§state-root}). Distinct installations never share data by name alone;
+workspaces referencing the same canonical installation share its data. Modules receive a workspace's plugins,
+in precedence order, through the setup seam's `readWorkspacePlugins`, with one signature that changes
+exactly when a plugin, its manifest, its MCP configuration, or its skills change
+({§functionality-hotload}), and the roots the workspace has. This read-only source loader does
+not install or delete plugins. MCP's own lifecycle is independent ({§mcp-definitions}).
+
+Portable components use each family's existing management and publication path. Within a source
+scope, standalone definitions precede bundled components; nearer scopes precede farther scopes,
+with npm last. Complete environment definitions override those inputs, followed by workspace
+definitions and enabledness. Inspection names the winning component file as plugin provenance.
+Removing a workspace override restores inheritance; it never deletes the installed bundle.
+Current plugin-source diagnostics join the workspace's configuration notices before inference.
+
+§agent-roots **A daemon reads the roots `PLURNK_SERVICE_ROOTS` names.** A comma list drawn from
+`project`, `plurnk` and `global`, nearest first, selects which Agent Skills, Agent Plugins and standalone MCP roots a
+daemon reads; the default names all three. The real-model gate profile selects
+its discovery roots explicitly ({§operator-config-real-model-profile}), so
+operator roots do not shape a gate. Root selection does not restrict explicit
+source definitions. Skills mutations change workspace bindings, not these roots
+({§skills-functionality}); MCP mutations likewise remain workspace-owned. The module setup seam's
+`workspaceConfigurationDirectories` supplies selected `<project>/.agents`,
+`$XDG_CONFIG_HOME/plurnk`, and `~/.agents` directories in precedence order, omitting
+project when no project is bound. Modules own their file formats; core owns discovery roots.
 
 An adapter may expose a `scheme` facet beneath its family's runtime namespace
 ({§runtime-resource-binding}). A facet claims a path subtree and is the scheme's
@@ -4145,9 +4398,10 @@ operator's ceiling ({§exec-env-scoped}, service origin) precede workspace defau
 worker overrides ({§workspace-env}). `add` takes
 the name as the alias and `{ "value": "…" }` as the definition, used verbatim with no
 interpolation. `disable` withholds a name in the selected scope while retaining it;
-`remove` forgets a locally-owned entry and a same-name lower baseline reappears
-disabled, so removal never silently changes what the next spawn sees. Definitions
-from a lower layer are disable-only in the current scope.
+`remove` forgets a locally-owned entry and restores any same-name inherited value
+and enabledness ({§configuration-definition-resolution}). Use `disable` to keep
+an inherited name out of subsequent launches. Definitions from a lower layer
+cannot be removed in the current scope.
 
 `list` projects effective values with their origin. Values are shown: the ceiling is the security
 boundary, not the projection, and any admitted name is already readable by every command the
@@ -4550,12 +4804,14 @@ adding a loop to it. LOOK text anchors resolve through the same
 
 | Event                                                        | Payload | When fired |
 |--------------------------------------------------------------|---------|------------|
+| §notifications-operation-event `operation/event` | `ApplicationOperationEvent`: `{ workerId, loopId, turnId, sequence, origin, projectRoot, statement, phase, result? }` | One admitted dispatch starts before capability/proposal admission and settles after its durable receipt(s). Only the settled phase has `result`, the exact returned operation result. READ fan-out is one dispatch; BARE starts before prompt preparation and settles after ordered receipt persistence. Automatic stream observations and log writes are not dispatches. An asynchronous executor's successful dispatch does not assert process exit. An internal exception that prevents settlement has no invented result event. |
 | §notifications-log-entry-notify `log/entry`                  | `{ entry: LogEntry }` | A non-proposed `log_entries` row is committed, or a proposed row reaches terminal settlement under {§proposal-proposed-hidden}. Delivery completes before a later event may terminate the owning Loop. |
 | §notifications-loop-terminated `loop/terminated`             | `{ workerId, loopId, result, hitMaxTurns, turnIds, usage: { accounting, curationWeight, curationBudget, contextTokens, contextCapacity, meta }, attributions }` | One loop reaches a terminal state. `result` is the exact universal operation result, including its RFC 9457 Problem Details on failure. `accounting` is the loop's contracts-owned {§provider-accounting}; the two curation facts and two physical-context facts follow {§tokenomics-client-gauge}; `meta` is that turn's opaque provider bag. `attributions` is the sorted union of exact provider-request evidence ({§attribution}), separate from accounting. Worker and loop are an inseparable owning coordinate. |
 | §notifications-loop-packet `loop/packet`                     | `{ workerId, loopId, packetCount }` | One provider packet becomes durable. `packetCount` is the exact count of packet-bearing turns in that Loop; packetless producer turns and physical provider retries never contribute. |
 | §notifications-loop-proposal `loop/proposal`                 | contracts-owned `ProposalProjection` | Dispatch pauses on a durable 202 proposal. `disposition` is the sole authority for whether a client presents review UI; live and reconnect share {§proposal-projection}. |
 | §notifications-loop-interaction `loop/interaction`           | contracts-owned `ClientInteractionProjection` | An operation is paused on client input. Live delivery and reconnect discovery share {§client-interactions}; workspace scope remains the event envelope. |
 | §notifications-workspace-created `workspace/created`         | `{ id, name, projectRoot }` | A workspace is created. This is the only current global event. |
+| `workspace/preparation` | `{ workspaceId, preparation: FunctionalityPreparationActivity[] }` | Workspace capability preparation changes; snapshot and clearing semantics follow {§functionality-preparation-visibility}. |
 | §notifications-stream-event-on-channel-change `stream/event` | `{ entryId, workerId, target, channel, state, contentLength, mimetype?, loop_seq?, turn_seq?, sequence? }` | Channel content grows or channel state transitions. `workerId` is the initiating actor used for conversation routing, never entry ownership or access control. `target` is the canonical resource URI. Optional numeric coordinates identify the causal log item, independently of that URI. Core-managed channel writes include the current stored `mimetype`, which may change per call ({§channel-mimetype}); the generic plugin notification capability does not require it. It carries metadata, not content; consumers read bytes by canonical workspace address. |
 | §notifications-stream-concluded `stream/concluded`           | `{ entryId, workerId, target, subscriptionId, scheme, result, summary, wakeAction, loop_seq?, turn_seq?, sequence? }` | A subscription closes. `workerId` identifies the initiating actor; `target` is the canonical resource URI. Optional numeric fields identify the causal log item, never parsed from `target`. Exact result truth is preserved. `wakeAction` reports `wake-pending` before settlement, `no-op-active-loop` when work is already executing, `no-loop`, or `skipped-aborted`/`skipped-cancelled` for an aborted worker scope. A pending wake predicts neither execution nor recipient count; subsequent ordinary loop events report actual progress and completion. |
 | §notifications-notice-event `notice/event`                   | `{ workerId, loopId, notice: Notice }` | A transient observation or progress notice occurs. `workerId` owns loop activity; only workspace derivation progress uses `null` with `loopId=0`. It cannot alter durable history, scheduling, recovery, or model-visible failure truth. |
@@ -4618,16 +4874,17 @@ The packet reaches the provider as a transcript, under the roles the model was t
 | Message | Role | Content |
 |:--|:--|:--|
 | 1 | `system` | the system slot, as rendered |
-| 2, 4, … | `user` | the user slot's text up to and including the next placed emission row's record ({§emission-row}); the first opens with `## Log` |
-| 3, 5, … | `assistant` | that row's emission, as the worker's own message |
-| last | `user` | the records after the last placed emission, then the remaining user sections in {§packet-cache-monotone} order; native parts ride here ({§packet-attachment-parts}) |
+| 2, 4, … | `user` | the user slot's text up to and including the record of the next placed emission that delivers text ({§emission-row}); the first opens with `## Log` |
+| 3, 5, … | `assistant` | that row's frozen emission projection less its NOTE and WAIT blocks, as the worker's own message ({§emission-row}) |
+| last | `user` | the records after the last emission delivered, then the remaining user sections in {§packet-cache-monotone} order; native parts ride here ({§packet-attachment-parts}) |
 
 Only role boundaries are added: joined by blank lines, the user messages are the user slot's
 bytes, in record order. An emission is placed exactly when its row is present in the final log
 section, so curation governs the transcript: a KILLed emission row, or one a trusted transform
 removed ({§packet-plugin-transform}), takes its emission with it, and a log without emission rows
-is one user message. The Worker block and the status clump always follow the log, so a request
-never ends on an emission, and the projection refuses one that would. The digest's packet
+is one user message. An emission of only NOTE and WAIT delivers nothing, so its record runs on
+into the next user message. The Worker block and the status clump always follow the log, so a
+request never ends on an emission, and the projection refuses one that would. The digest's packet
 artifacts record the sections, and `.wire.json` the messages ({§share-packet-names}).
 
 ### §packet-cache-monotone Default order and cache locality
@@ -4936,7 +5193,7 @@ source independently from this optional model-exchange record; a request-only
 turn receives a note instead of a fabricated response.
 
 §digest-turn-artifact-identity **Digest packet artifacts project durable turns.**
-After selectors are applied, digest retains every turn with exact program source, a
+After selectors are applied, digest retains every turn with exact content or reasoning source, a
 valid stored provider request, or malformed stored packet evidence; orders those
 turns by durable chronology; and names each by its log coordinate ({§share-packet-names}). The
 producer does not affect projection.
@@ -4951,6 +5208,7 @@ consumer reconstructs a name. A name that cannot be a file name, or two turns sh
 | Artifact | Present when | Authority |
 |----------|--------------|-----------|
 | `<stem>.assistant.md` | The turn has an `ops` source | Exact `turn_sources.content`, independent of log rows |
+| `<stem>.reasoning.md` | The turn has a `reasoning` source | Exact `turn_sources.content`, without relabeling it as content |
 | `<stem>.system.md`, `<stem>.user.md` | The turn stored a provider request | Stored text sections projected through `PacketWire`; native parts are not Markdown |
 | `<stem>.wire.json` | The turn stored a provider request | The request's text messages in order, its worker's emission rows placed ({§packet-wire-envelope}); `<stem>.wire.invalid.json` names a stored log that cannot be projected |
 | `digest.json` turn `attachments` | Every turn | Stored native attachment descriptors; `[]` means a request without attachments, `null` means no valid stored request. Selection is not proof of provider acceptance. |
@@ -4959,8 +5217,8 @@ consumer reconstructs a name. A name that cannot be a file name, or two turns sh
 | `<stem>.packet.raw.txt` | The stored packet fails typed validation | Exact stored packet text |
 | `<stem>.packet.invalid.json` | The stored packet fails typed validation | Turn identity and complete validation error chain |
 
-A source-backed turn without provider participation therefore produces only
-`assistant.md`; a request-only turn produces no fabricated assistant. A
+A source-backed turn without provider participation produces only its source-channel
+artifacts; a request-only turn produces no fabricated assistant. A
 source-less programmatic turn with no provider request has no forensic payload
 to project and writes no files.
 
@@ -5074,7 +5332,7 @@ ordered set exactly once. Recovery retries complete the same queued loop and nev
 mint duplicate work. Output withholding preserves readable arrival rows; explicit
 KILL follows the ordinary log contract.
 
-§completion-defers-to-messages **Conclusion does not cross an unanswered arrival.** The end-of-program check includes messages that arrived during inference. The final database transition rechecks unanswered messages atomically. An arrival that wins the race continues the current loop; one admitted after conclusion belongs to a new loop. Orphan recovery preserves messages accepted before an independently forced termination.
+§completion-defers-to-messages **Conclusion does not cross an unobserved arrival.** The end-of-program check includes messages that arrived during inference. The final database transition atomically requires every inbox message to be published and the loop's observed wake revision to equal its worker's current revision. Answer delivery is not this barrier. An arrival that wins the race continues the current loop; one admitted after conclusion belongs to a new loop. Orphan recovery preserves messages accepted before an independently forced termination.
 
 §packet-catalog **Catalogs are query results, not packet state.** The packet
 stores no materialized manifest. Complete and one-level entry directories,
@@ -5172,7 +5430,21 @@ retain distinct contracts and lifetimes.
 
 §digest-wire-line **Wire health aggregated.** Each worker summary renders a `Wire:` line — total physical provider requests, error-outcome count, and the error percentage when nonzero. Provider-level failures are absorbed by retries below the packet stream, so without this aggregate a rate-limit storm is invisible in every summary while the model's experience stays clean.
 
-§digest-cache-ledger **Cacheable versus cached, per request.** For every physical provider request the digest computes its cacheable prefix: the longest common prefix, in characters, between the prompt its turn stored (the request's messages in order, each role above its content — the messages `.wire.json` carries) and the prompt of the previous provider request in the same loop, taken as that prefix's share of the whole prompt in the packet's own token estimate ({§tokenomics-agnostic-ruler}) and applied to the provider's reported input count, so `cacheableTokens` sits in the same units as the cache read beside it; a loop's first request has 0, and a request whose turn stores no valid packet or whose provider reported no input count has none. Beside it sit the provider's reported cache read as `cachedTokens` (`provider_requests.usage_input_cache_read`) and `inputTokens` (`usage_input`). `digest.json` carries the three on every provider-request row; an inference turn line carries `cache=<cached>/<cacheable>` summed over the turn's requests; each workspace heading is followed by `Cache: <cached> of <cacheable> cacheable tokens reported (<pct>%) over <n> requests`. A provider that reported no cache field at all (null, not 0) renders `?` on the turn line and is counted apart on the workspace line (`· <k> unreported (cached=?)`), outside both sums and the percentage; a request without a stored packet or without a reported input count is likewise counted apart. The prefix measures what the daemon kept identical between consecutive requests; it is no claim about the provider's tokenization or cache-block alignment, so a provider that under-caches an identical prefix reads as such, apart from a prefix the daemon itself broke.
+§digest-cache-ledger **Measured cache reuse and estimated prompt overlap are separate.**
+
+| Projection | Meaning |
+|---|---|
+| `digest.json` provider-request `cachedTokens`, `inputTokens` | Exact provider-reported cache reads and input tokens; absent quantities remain `null`, reported zero remains zero. Every physical request counts, including retries and first requests of new loops. Stored packet availability is irrelevant to these counters. |
+| Turn `cache=<cached>/<input>` | Sum each measured quantity over that turn's requests. If any request omits a quantity, that sum is `?`. |
+| Workspace `Cache: <cached> of <input> reported input tokens read from cache (<pct>%) over <n> requests` | Sum only requests reporting both counters. Percentage is cache reads / input, rounded to one decimal; zero input is `n/a`. Requests missing either counter are counted separately as `missing input or cache usage (excluded)`. |
+| `digest.json` provider-request `adjacentPrefixTokensEstimate` | Optional loop-local diagnostic: the longest common character prefix with the preceding request, weighted under {§tokenomics-agnostic-ruler} as a share of the current stored prompt, multiplied by reported input tokens. First request: `0`; missing current/preceding packet or current input: `null`. Empty prompts have zero overlap. |
+
+The prefix estimate uses the stored emission packet's wire message order, roles
+and content. A BARE request's input is not that packet; its prefix estimate and
+the following request's comparison are unknown. The estimate is
+neither provider tokenization nor a cache ceiling, and never supplies a cache-ratio
+denominator. Caching across loops or against other provider-resident prefixes
+does not make the measured counters inconsistent.
 
 §digest-edit-census **Every model EDIT by the form it authored, how it landed, and whether it came back.** For each worker the digest reads every model-authored EDIT row and classifies the form from the row's stored marker and the durable statement's pattern: `hash` (one anchor), `line` (one line number), `range` (two marks), `insert` (the zero-width `<L,1,L,1>` form, {§zero-width-column-one-insert}), `column` (any other four-mark region), `prepend` / `append` (`<0>` / `<-1>`), `offset` (a tolerated anchor offset, {§anchor-offset}), `pattern` (a selection matcher), `whole` (no marker: a creation when it lands 201). It counts the EDITs, those refused (status ≥ 400), and the *revisits*: an EDIT of a path the same worker had edited within its previous two model turns — the shape of a repair without the claim of one. Each worker summary renders `EDITs: <n> · <form>=<count>… · refused=<k> · revisits=<r>` (`(no edits)` for none); `digest.json` carries the census as `edit_census` on every worker and stamps every EDIT log entry with its `edit_form` and `edit_revisit`. A form is a fact about what was written, never about intent; the bench sheet reads the counts as friction and leaves the judgement to the reader.
 
@@ -5293,8 +5565,10 @@ enable | disable | remove`, `workspace.members.<verb>` for the client,
 ```` ```members (<verb>) ```` for the model — for what the model may see, exactly as they do for skills and
 MCP servers. A definition is one gitignore-style glob, `{ glob }`, relative to the project
 root; a leading `!` excludes matching members, and an exclusion wins over every inclusion.
-The coordinator's provenance (`service-configuration`, `client-action`, `model-proposal`)
-rides the definition; its alias is a short name, suggested from the glob. `list` shows each
+Admission provenance (`service-configuration`, `client-action`, `model-proposal`)
+rides the definition to enforce {§members-model-scope}; configuration-source
+provenance belongs to the shared inspection projection ({§configuration-provenance}).
+The alias is a short name, suggested from the glob. `list` shows each
 definition with what it resolved to — `include` or `exclude`, the pattern, the members it
 admits or removes (count and a bounded sample), and for a model's inclusion the matches the
 repository's ignore rules refused — so the model sees what its glob did and adapts.
@@ -5303,10 +5577,12 @@ repository's ignore rules refused — so the model sees what its glob did and ad
 untracked, absent); a glob previews what `add` would include or exclude. Names only, never
 content; nothing is added.
 
-§members-configuration *Available definitions.* The operator's `PLURNK_MEMBERS_<ALIAS>=<glob>`
-(`!glob` excludes) and `PLURNK_MEMBERS_ENABLED=[…]` (`[]` enables none) are the
-service-origin definitions, the shape `PLURNK_MCP_*` already has; an empty glob, a bare `!`,
-or an unknown enabled alias fails the daemon at boot.
+§members-configuration *Available definitions.* `PLURNK_MEMBERS_<alias>=<glob>`
+declares one service-origin rule (`!glob` excludes). The shared naming and
+enabledness dialect is {§resource-environment}; `PLURNK_MEMBERS_ENABLED` supplies
+the panel default and `PLURNK_MEMBERS_<alias>_ENABLED` overrides one rule.
+An empty glob or a bare `!` fails validation. Controls may precede their rule;
+they are validated without creating a definition ({§resource-environment}).
 
 §members-model-scope *The model's authority.* A model's `add` is admitted against
 `PLURNK_SERVICE_MEMBERS_MODEL_SCOPE` in the file-creation lattice `none < root <
@@ -5338,53 +5614,98 @@ verbs are these verbs.
 §skills-functionality **Agent Skills are one workspace Functionality family.**
 Core registers the `skills` family with the coordinator ({§functionality-coordinator});
 its adapter owns protocol truth for standard Agent Skills and nothing else. A
-definition is `SkillDefinition` — the standard skill `name`, its source
-`scope` (`project` = `<projectRoot>/.agents/skills`, `global` =
-`~/.agents/skills`, `service` = a host-provided resource tree), and for a workspace-installed skill the standard installer
-`source` that provides it. Plurnk seeds no universal root and mutates none
-absent an explicit `add`/`remove`.
+definition is `SkillDefinition`: the standard skill `name`, its `source`, and
+optional Git `ref`/resolved `commit` ({§skills-sources}). Only a host-provided
+resource tree omits `source`. Source location is not mutation ownership: standard
+project/global roots are read-only configuration inputs; live changes belong to
+the workspace. Plurnk neither installs into nor deletes from those roots.
 
 *Available definitions.* The filesystem is the only truth about installation:
-every `<root>/<name>/SKILL.md` directory under the project then the global
-root is one service-origin definition, enabled by default, project shadowing
-global and then host-provided trees by name; when the standard installer's `skills-lock.json` records a
-source it rides the definition. The workspace's durable state owns enablement
-({§functionality-state}); a disabled skill stays client-visible and leaves no
-model-facing trace.
-
-*Discovery is inert.* `discover {query}` searches the ecosystem registry
-(`PLURNK_SERVICE_SKILLS_REGISTRY_URL`; empty disables it
-with 501 `registry-not-configured`) and returns one candidate per hit with
-`registry` provenance and the exact `owner/repo` source. `discover {source}`
-lists the skills one standard package reference contains with `source`
-provenance. Neither installs, persists, or enables. Client `configuration`
-contributes nothing and is refused with 400.
-
-*Admission.* `add {alias, definition}` requires `alias = name`, a `source`,
-and a project root when `scope` is `project`; the workspace definition may
-shadow a service skill of the same name. The family's aliases use the standard
-skill-name grammar ({§agent-skills-name}), including digit-leading and Unicode
-names, rather than the coordinator's generic default.
+every `<root>/<name>/SKILL.md` directory under the project, plurnk, then global
+root is one service-origin definition, a nearer root shadowing a farther one and
+all of them shadowing host-provided trees by name. Each filesystem definition
+names its actual source directory. The workspace's durable state owns
+enablement ({§functionality-state}); a disabled skill stays client-visible and
+leaves no model-facing trace.
+
+§skills-configuration **Skills use the shared definition cascade.**
+
+| Layer, low to high | Definition source |
+|---|---|
+| Service | Host-provided trees |
+| Standard locations | Global, plurnk, then project roots selected by {§agent-roots} |
+| Cascading environment | `PLURNK_SKILLS_<name>={"name":"<name>","source":"…","ref"?:"…"}` replaces the complete definition |
+| Live workspace | `skills (add)` creates a workspace definition through {§functionality-coordinator} |
+
+`PLURNK_SKILLS_ENABLED` supplies default enabledness; `<name>_ENABLED` overrides
+it independently ({§resource-environment}). The decoded environment alias must
+equal the standard skill name, including digit-leading and Unicode names.
+Blank definitions are invalid; controls may precede a definition. Environment
+validation checks shape, names, remote URL rules, and Git-only `ref` without
+fetching or opening a source; `commit` is service-recorded, not an input.
+
+*Discovery is inert.* `discover {source}` lists the standard skills one source
+carries, each a candidate with `source` provenance and the exact definition to
+add; it never installs, persists, or enables. Agent Skills have no standard
+registry, so `discover {query}` is 400 `query-unsupported`, naming the source
+forms. Client `configuration` contributes nothing and is refused with 400.
+
+*Admission.* `add {alias, definition}` requires `alias = name` and a `source`;
+the workspace definition may shadow a service skill of the same name. Relative
+sources require a project root; absolute sources work in headless workspaces.
+A local source is recorded as its absolute path.
+A git source records the `commit` its `ref` names at admission, or its default
+branch's when no `ref` is given; `ref` belongs to git sources, and a supplied
+`commit` is refused because the service records it. The family's aliases use
+the standard skill-name grammar ({§agent-skills-name}), including digit-leading
+and Unicode names, rather than the coordinator's generic default.
 
 *Preparation.* For each enabled alias the adapter selects the host-provided
-tree for `service` scope or locates the directory at the filesystem scope;
-a workspace definition whose directory is absent is installed
-through the standard CLI (`PLURNK_SERVICE_SKILLS_CLI`, invoked as
-`<cli> add <source> --agent universal --skill <name> --yes [--global]`, run with
-`HOME` set to the service's user home so the installer's `~` is the global
-root) and the installed `SKILL.md` — never the installer's output — is the
-evidence.
+tree or resolves the complete source definition ({§skills-sources}). Local
+folders and their `SKILL.md` files remain live references, including supporting
+resources and symlink retargeting. Git/archive sources are materialized only
+inside {§module-workspace-directory}; different workspaces and complete source
+definitions cannot reuse each other's materializations accidentally.
+The first fetched Git/archive copy remains stable across enable, cooling, and
+restart until the complete source definition changes. In particular, an
+operator-configured symbolic Git ref is not an implicit update subscription.
 Each admitted skill requires standard `name` and `description` frontmatter
 with `name` matching its directory. A missing, uninstallable, or invalid skill
-is `unavailable` with its exact Problem (`skill-missing`, `install-failed`,
-`skill-invalid`) under the coordinator's failure policy
-({§functionality-model-mutation}); one bad skill never fails the family.
+is `unavailable` with its exact Problem ({§problems-functionality}) under the
+coordinator's failure policy ({§functionality-model-mutation}); one bad skill
+never fails the family.
+
+Removal follows {§skills-remove}.
 
-Installer provenance follows the upstream lock locations: project
-`skills-lock.json`; global `$XDG_STATE_HOME/skills/.skill-lock.json` when
-configured, otherwise `~/.agents/.skill-lock.json`. A lock's source belongs to
-its scope, never a same-named installation in another root. Missing locks mean
-unknown provenance; malformed or unreadable locks surface their cause.
+§skills-sources **A source is a git remote, a folder, or a file, read with standard tools.**
+Fetching runs nothing it fetched. Materialized copies cannot contain references
+outside their skill; live resources retain {§agent-skills-directory} containment.
+
+| Source | How it is read |
+|---|---|
+| Git remote: a full `https://` or `ssh://` URL, or `user@host:path` | `git ls-remote` resolves the ref at admission; preparation shallow-clones it with hooks and submodules off, and a checkout at any other commit is 409 `source-moved` |
+| Folder: absolute, `~/`, or relative to the project root | Live reference; standard directory/name matching applies |
+| A file named `SKILL.md` | Live reference to its skill directory and supporting resources |
+| A `.zip`, `.tar`, `.tgz`, `.tar.gz`, `.tar.bz2`, `.tar.xz`, or `.tar.zst` archive | Unpacked into private staging with `unzip` or `tar`; a lone top-level directory is the source's root |
+
+Any other scheme, plain `http`, `owner/repo` shorthand, and an https URL carrying
+credentials are refused with `source-invalid` or `source-missing`: shorthand names no
+forge, and a recorded source is listed to every client. Git runs with the
+operator's configuration, credentials, and SSH agent, never plurnk's secrets, and
+never prompts; `PLURNK_SERVICE_SKILLS_FETCH_TIMEOUT_MS` bounds each fetch. The
+retired vendor-installer knobs (`PLURNK_SERVICE_SKILLS_CLI`, `_CLI_TIMEOUT_MS`,
+`_REGISTRY_URL`, `_REGISTRY_LIMIT`, `_REGISTRY_TIMEOUT_MS`) make the skills family
+unavailable when set, each naming what replaced it ({§configuration-repair-path}).
+
+A source's skills are the directories holding a `SKILL.md`, found by walking
+from its root without entering `.git` or a skill already found. A fetched skill at
+the root is named by its frontmatter ({§agent-skills-name}); local references and
+directories below the root use the standard folder rule. A source with `plugin.json` at its root is an
+Agent Plugin and is refused with 422 `source-is-plugin`, so its skills keep the
+plugin's identity. Materialization copies the named skill beside its workspace-owned destination
+and renames it to `<root>/<name>`; a copy that holds a link out of the skill, or
+anything but files, directories, and inward links, is refused with 422
+`source-unsafe` and leaves nothing behind.
 
 §skills-resources **A skill is a resource tree, not a rewritten document.**
 The family exposes enabled, available {§agent-skills-tree} sources through
@@ -5401,13 +5722,13 @@ serialized URI address the same resource, not separate skill identities.
 | `READ (skill://<name>/SKILL.md)` | Original frontmatter and Markdown, unchanged; relative links remain relative to the source layout. |
 | `READ` / `FIND` below the authority | References, scripts, and assets retain their source paths and ordinary pattern, channel, byte, and multimodal semantics. Acquisition observes current source contents, including disappearance. |
 | ```` ```runtime (skill://<name>/scripts/program.ext) ```` | Ordinary resource execution and proposal policy; preserve the native file and its siblings under {§exec-source-temporary}. Discovery and READ never execute scripts. |
-| Model mutation | Read-only; no EDIT, SEND, or KILL of installed resources. Manage installation and enablement through ```` ```skills ````. |
+| Model mutation | Read-only; no EDIT, SEND, or KILL of skill resources. Manage definitions and enablement through ```` ```skills ````. |
 | Disable / unavailable / remove | Withdraw the authority from new resource access and discovery. Existing log receipts remain historical evidence. |
 | WORK / FORK | Use the same workspace Functionality, not copied definitions or resource caches. |
 
 Explicit skill URIs address these resources; bare operation paths still address
 project files, with no implicit current-skill directory. Source resolution follows
-{§agent-skills-directory}, including installer symlinks and containment of references.
+{§agent-skills-directory}, including symlinked skill directories and containment of references.
 An uninstalled Git skill is not manufactured by repository detection.
 
 §plurnk-skill **Plurnk's own reference is an ordinary service-provided skill.**
@@ -5420,24 +5741,22 @@ same {§operator-config-env-defaults} renderer as the operator command, never th
 effective environment. Native chapter files retain their owners and locations;
 runtime-generated bytes have no invented disk location. Disable/enable,
 shared workspace visibility, and project/global shadowing use the ordinary Skills lifecycle.
-Service-provided skills are not installer targets; service definitions are
-disable-only under {§skills-remove}.
-
-§skills-remove **`remove` uninstalls the workspace definition's installation.** Before the
-coordinator forgets a workspace-origin skill definition the adapter removes that
-skill from the definition's scope through the standard CLI (`remove <name>
---yes [--global]`), verified by the directory's absence; a failed removal
-rejects the mutation. A same-named skill at a lower-precedence root is then
-revealed as a service definition, disabled ({§functionality-coordinator}).
-Service definitions are disable-only.
-
-§skills-hotload **Out-of-band installers are admitted at the next turn.** The
-family keeps one signature of both installed roots, source locations, frontmatter
-sources, and installer provenance per resident workspace; turn
-admission recomputes it under the workspace gate before packet assembly and
-republishes the family through the coordinator when it changed, so a skill
-installed or removed by any other tool is discoverable in the first subsequent
-model turn while an unchanged set dispatches nothing. The model manages skills
+Service-provided skills are not installer targets; removal follows {§skills-remove}.
+
+§skills-remove **`remove` forgets the workspace binding, not the source.**
+It withdraws that definition and restores any inherited definition and enabledness
+({§functionality-coordinator}). External folders are never deleted. Fetched
+materializations remain workspace-owned operational state, reusable only for the
+same complete definition; they confer no availability without a definition.
+Inherited definitions cannot be removed here; their enabledness can be overridden.
+
+§skills-hotload **Skills placed out of band are admitted at the next turn** ({§functionality-hotload}). The
+family keeps one signature of the discovered roots, configured definitions, source locations, and `SKILL.md` sources
+per resident workspace, read before a publication loads the skills it describes. Turn admission
+recomputes it under the workspace gate before packet assembly: a changed signature republishes the
+family, and an unchanged one republishes only when the skills the coordinator would publish differ
+from the published ones. A skill installed, edited or removed by any other tool is therefore
+discoverable in the first subsequent model turn, while an unchanged set dispatches nothing. The model manages skills
 only through the generated ```` ```skills ```` family
 ({§functionality-model-projection}); it is never taught a package manager.
 
@@ -5896,6 +6215,7 @@ Every Problem code core mints is named here under its family ({§problem-error-c
 |---|---:|---|
 | `service-starting` | 503 | The PLURNK service owns this listener but has not admitted its client interface yet. |
 | `configuration-unsupported` | 400 | Environment discovery reads this installation's declared configuration; client configuration contributes nothing. |
+| `configuration-invalid` | 503 | The owning configuration reader's diagnostic, naming the invalid key. Recovery: Correct the named configuration input. Other capabilities remain available. |
 | `name-reserved` | 400 | '*alias*' is plurnk's own: PLURNK_* configuration and provider credential names never reach a subprocess. |
 | `value-invalid` | 400 | '*alias*' needs a string value. |
 | `env-invalid` | 400 | `env` must be an object of string values; '*name*' is not a name a shell can export. |
@@ -5903,14 +6223,19 @@ Every Problem code core mints is named here under its family ({§problem-error-c
 | `headless` | 409 | The workspace has no project root, so there are no file members. Recovery: Open the workspace on a project root. |
 | `definition-invalid` | 400 | A members definition is { glob }: a gitignore-style pattern, `!glob` to exclude; a skill definition names an installable skill. |
 | `model-scope` | 403 | The model may not change membership here: the members scope is none. Recovery: `git add` the file so git tracks it, or ask the operator to add it (/members add) or raise PLURNK_SERVICE_MEMBERS_MODEL_SCOPE. |
-| `registry-unreachable` | 502 | Skills registry *url* could not be reached. |
-| `registry-rejected` | 502 | Skills registry *url* answered *status*. |
-| `registry-invalid` | 502 | Skills registry *url* returned no skills array. |
-| `discover-failed` | 502 | Agent Skills source '*source*' could not be listed: *cause*. |
+| `query-unsupported` | 400 | Agent Skills have no standard registry to search; discover takes a source: a git remote as a full https or ssh URL, a folder, a lone SKILL.md, or a zip or tar archive. |
+| `source-invalid` | 400 | '*source*' is not a valid git remote URL; an https source carries no credentials (git's credential helper supplies them); is not a source: a git remote is a full https or ssh URL; is relative, and this workspace has no project root to resolve it against; or is neither a folder, a SKILL.md, nor a zip or tar archive. |
+| `source-missing` | 404 | No folder or file is at '*source*' (; owner/repo shorthand names no forge, so give the repository's full https or ssh URL). |
+| `source-unreadable` | 422 | '*source*' cannot be read: *cause*; or '*path*' could not be unpacked: *reason*. |
+| `source-unreachable` | 502 | git could not reach '*remote*', or fetch it (at '*ref*'): *reason*. |
+| `ref-missing` | 404 | '*remote*' has no branch or tag '*ref*', or names no default branch. |
+| `source-moved` | 409 | '*source*' *ref* now names *current*; this skill was added at *commit*. Recovery: Remove the skill and add it again to take the current commit. |
+| `source-is-plugin` | 422 | '*source*' is an Agent Plugin; install it as a plugin, so its skills keep the plugin's identity and servers. |
+| `source-unsafe` | 422 | '*path*' links outside its skill, or is neither a file, a directory, nor an inward link. |
+| `skill-not-found` | 404 | '*source*' carries no Agent Skill named '*name*'. |
+| `skill-ambiguous` | 409 | '*source*' carries *count* skills named '*name*'. |
 | `alias-mismatch` | 400 | Alias '*alias*' must equal the skill name '*name*'. |
-| `scope-not-installable` | 400 | Service-provided skills can be enabled or disabled; adding a skill requires project or global scope. Recovery: Add it with scope "global" or open a workspace rooted in a project. |
-| `source-required` | 400 | Adding '*alias*' requires the standard installer source that provides it. |
-| `uninstall-failed` | 502 | Agent Skill '*name*' could not be removed from its *scope* root: *cause*. |
+| `source-required` | 400 | Adding '*alias*' requires the source that provides it. |
 | `workspace-not-found` | 404 | Workspace *id* does not exist. |
 | `state-not-json` | 400 | Worker module state is not JSON-serializable. |
 | `workspace-busy` | 409 | Workspace *id* is running an operation or another capability change. Recovery: Settle the current operation and retry the capability change. |
@@ -5923,9 +6248,8 @@ Every Problem code core mints is named here under its family ({§problem-error-c
 | `loop-policy-invalid` | 400 | An unattended loop cannot hold a proposal for review: nobody is present to answer. Recovery: State proposals accept or reject, or attend the loop. |
 | `scope-cancelled` | 499 | The worker scope was cancelled: *reason*. |
 | `range-not-satisfiable` | 416 | `Range <0,-1>` starts at 0, which is not a line; lines are numbered from 1. Recovery: Write `<1,-1>` to trim every line of the body; `KILL (log:///…/READ)` with no scope retires the item. |
-| `registry-not-configured` | 501 | Skills registry search is disabled; PLURNK_SERVICE_SKILLS_REGISTRY_URL is empty. |
-| `install-failed` | 502 | Agent Skill '*name*' could not be installed from '*source*': *cause* (or the installer reported it but its SKILL.md does not exist). |
-| `skill-missing` | 404 | Agent Skill '*alias*' is not installed under its *scope* root, or is not provided by this service. |
+| `install-failed` | 500 | Agent Skill '*name*' could not be placed under *root*: *cause*. |
+| `skill-missing` | 404 | Agent Skill '*alias*' is not provided by this service. |
 | `skill-invalid` | 422 | Agent Skill '*alias*' is not a valid standard skill: *cause*. |
 
 §pinned-wording-core **Pinned wording.** Verbatim sentences tests pin: each is contract, and a change here is a change of contract.