@plurnk/plurnk-service 1.3.12 → 1.5.0

package/.env.defaults

@@ -10,13 +10,14 @@
 # two packages crashes boot naming both. Reader declares: every knob your code reads appears in
 # your file — the floor guarantees it set, so code carries no inline fallback.
 #
-# Cascade (low → high precedence — last writer wins):
+# Source classes (low → high precedence; higher classes win):
 #   assembled .env.defaults floor  (this file + every installed member's, uniqueness-checked)
 #   < ~/.plurnk/.env               (your home config — seeded once, yours to keep)
 #   < ./.env                       (per-project, current directory)
 #   < --env-file=… / --config=…
 #   < shell environment
 #   < --<knob> CLI flags           (the 1:1 mirror: --service-max-turns <-> PLURNK_SERVICE_MAX_TURNS)
+# Ordering among repeated explicit files is currently unspecified (#84).
 # Feature-flag bools use `=== "1"` exactly, never `=== "true"`. `~/` expands to your home.
 
 # --- Storage ---
@@ -41,31 +42,36 @@ PLURNK_HOST=127.0.0.1
 PLURNK_PORT=3044
 
 # --- Loop control ---
+# Optional default child-provider alias. Unset = each WORK/FORK child inherits
+# its spawning loop's provider. Clients may override this per top-level loop.
+# PLURNK_MODEL_CHILD=fast
 # Operator turn ceiling. -1 (default) = no cap (loops end via SEND, budget,
 # strikes, or cycle detection). A positive value is an inviolable hard cap a
-# per-call loop.run({maxTurns}) cannot exceed (min wins).
+# CoreSeam runLoop({maxTurns}) request cannot exceed (min wins).
 PLURNK_SERVICE_MAX_TURNS=-1
 # Per-emission op ceiling. -1 (default) = no cap: every generated op dispatches (a runaway
 # op-loop is a sampler concern, not grounds to drop already-generated work). A positive value
 # is an operator ceiling a client may tighten per workspace via workspace.create settings.maxCommands
 # (min wins), never raise past (#232).
 PLURNK_SERVICE_MAX_COMMANDS=-1
+# Live & demo test harness story timeout (ms) — 10 minutes (600000ms).
+PLURNK_SERVICE_LIVE_TIMEOUT=600000
 # Proposal resolution bound (ms). Empty = a stopped world waits for its human indefinitely;
-# set to auto-cancel unattended (resolves cancel, outcome=timeout).
+# a finite positive value auto-cancels unattended (outcome=timeout). Every other explicit
+# value is invalid and fails at the proposal lifecycle owner.
 PLURNK_SERVICE_PROPOSAL_TIMEOUT_MS=
 # Turn-hold runtimes: while a listed runtime's stream is in flight the cycle pauses (no next
 # turn) until it concludes. Bounded by _HOLD_MS, fail-open at the cap. Empty = no holds.
-# A bare name holds ALL of that runtime's spawns; `<runtime>:<effect>` (e.g. github:read) holds
-# only that effect-class — an MCP server's read tools opt in while its host mutations background (#485).
+# A bare name holds all of that runtime's spawns; `<runtime>:<effect>` holds only
+# that effect class.
 PLURNK_SERVICE_EXEC_HOLD=search,images,videos,news,map,music,it,science,social,downloadable
 PLURNK_SERVICE_EXEC_HOLD_MS=300000
-# Post-EXEC breath: after a turn fires a non-inline EXEC whose spawn is still in
-# flight at the turn boundary, wait this many ms before assembling the next packet
-# so a fast exec's output can land in it instead of a turn later. A fixed grace
-# beat, NOT a wait-for-completion (slow execs proceed + surface via the wake path).
-# 0 = off (the model sees fast-exec output a turn late, as today).
-PLURNK_SERVICE_EXEC_WAIT_MS=1000
-# Exec poll backoff (#521, §exec-poll): a parked exec with NO explicit `<,P>` cadence is no longer
+# Optimistic worker settlement: before model dispatch, allow newly started
+# streams or a completion wake with live siblings this many ms to quiesce.
+# Settlement ends immediately at quiescence and never extends its first
+# deadline; survivors follow the monitored lifecycle. 0 = off.
+PLURNK_SERVICE_OPTIMISTIC_WAIT_MS=5000
+# Exec poll backoff (#521, {§exec-poll}): a parked exec with NO explicit `<,P>` cadence is no longer
 # park-blind-forever — the loop wakes on an exponential backoff so the model regains a turn to read
 # partial output and re-park a slow long-runner or KILL a stuck one. Wake N fires at BASE·2^min(N,TURNS-1)
 # seconds (60,120,240,…,7680), then holds at the cap. An explicit `<,P>` wins; `<,0>` opts out (blind).
@@ -88,9 +94,20 @@ PLURNK_SERVICE_LOOP_TIMEOUT=86400000
 # PLURNK_QUESTIONS=0
 
 # --- Engine rails ---
+# Maximum characters retained from caught runtime diagnostics in a model-facing
+# Problem detail. Complete errors remain in daemon diagnostics.
+PLURNK_SERVICE_ERROR_DETAIL_LIMIT=512
 PLURNK_SERVICE_MAX_STRIKES=3
+# Completed responses that do not form a valid PLAN...SEND turn are retried
+# beneath the same engine turn and against the identical packet.
+PLURNK_SERVICE_EMISSION_ATTEMPTS=3
 PLURNK_SERVICE_MIN_CYCLES=3
 PLURNK_SERVICE_MAX_CYCLE_PERIOD=4
+# Requiem is an out-of-band forensic interview. Reasoning-heavy witnesses may
+# consume most of the first budget before emitting testimony; an empty
+# length-limited response receives the retry budget.
+PLURNK_SERVICE_REQUIEM_MAX_TOKENS=16384
+PLURNK_SERVICE_REQUIEM_RETRY_MAX_TOKENS=32768
 
 # --- Schemes ---
 # (Workspace root for file ops is per-workspace — supplied at
@@ -98,47 +115,46 @@ PLURNK_SERVICE_MAX_CYCLE_PERIOD=4
 # stored on workspaces.project_root. No env-level default.)
 
 # --- Git integration ---
-# PLURNK_SERVICE_GIT_ALLOWED — hard ceiling for git membership + integration (repo telemetry,
-# EXEC[git]). =1 permits it (then declared repos + per-workspace config decide; a client
+# PLURNK_SERVICE_GIT_ALLOWED — hard ceiling for Git membership + integration (repository
+# telemetry, EXEC[git]). =1 permits it (then project repository + workspace config decide; a client
 # may deny its own workspace via workspace.create settings.git:false, #232); =0 flatly
 # denies it service-wide, un-re-enableable (the sandbox/benchmark lockout).
 PLURNK_SERVICE_GIT_ALLOWED=1
-# PLURNK_SERVICE_GIT_AUTO — default repo declaration. =1 auto-declares an implicit `repo` at
-# project_root (no-op when it isn't a git tree); =0 declares nothing — clients add
-# repos explicitly via the `repo` overlay. SPEC §membership forest.
+# PLURNK_SERVICE_GIT_AUTO — automatic project-repository membership. =1 includes the Git
+# repository containing project_root; =0 leaves `pick` as the only membership source.
 PLURNK_SERVICE_GIT_AUTO=1
-# PLURNK_SERVICE_GIT_NATIVE — git READ backend. Default (0) = in-process isomorphic-git:
-# portable, sandbox-safe, no subprocess, hermetic by construction. =1 routes membership +
-# status to the system git binary — in-process membership measures ~8x native (~130ms at
-# 20k files) and the status read ~55x. Native is also the explicit remedy when
-# isomorphic-git cannot read a repository shape; it requires the git binary.
-PLURNK_SERVICE_GIT_NATIVE=0
+# PLURNK_SERVICE_GIT_ISO - git READ backend. Default (0) uses the native Git
+# binary. =1 explicitly selects the slower, in-process isomorphic-git backend
+# for a deployment that cannot spawn Git. The two backends never fail over.
+PLURNK_SERVICE_GIT_ISO=0
+# Maximum stdout/stderr payload accepted from one native Git subprocess. The
+# optional in-process reader does not use this bound.
+PLURNK_SERVICE_GIT_OUTPUT_MAX_BYTES=67108864
 
-# PLURNK_SERVICE_ARRIVAL_PREVIEW_LINES — the arrival law (§arrival-law, #499): content another
-# actor pushes at a worker (a prompt, a child's deliverable, terminal stream output) rides OPEN only up to this many
-# lines AND 80×N chars (the char cap guards single-line bombs); over, a bounded head + the
-# address + the full price ride instead. Self-invited content (a worker's own READ/FIND) is
-# budget-bounded, never previewed. 16 = generous but not dangerous.
-PLURNK_SERVICE_ARRIVAL_PREVIEW_LINES=16
+# Ordinary bounded OPEN-body projection. READ/FIND results render their selected
+# operation result complete; every other log body renders at most these
+# independent line and character bounds. A truncated body carries its canonical
+# log URI.
+PLURNK_SERVICE_PREVIEW_LINES=16
+PLURNK_SERVICE_PREVIEW_CHARS=2560
 
-# --- Reference docs (auto-READ at turn 1) ---
-# PLURNK_SERVICE_MD_<ALIAS>=<path> materializes <path>'s markdown as a plurnk://<ALIAS>.md
+# --- Reference docs (auto-READ at turn 0) ---
+# PLURNK_SERVICE_MD_<ALIAS>=<path> materializes <path>'s markdown as a
+# worker://plurnk/<ALIAS>.md
 # entry the model READs at turn 0 — an idiomatic way to inject standing context
 # (an ordinary entry + READ op, not a bespoke packet section). ~ expands to home;
 # relative paths resolve against the package root. A client may add its own docs
 # per workspace via workspace.create settings.mdDocs (content, not a path); those UNION
 # with these env docs, keyed by alias — the client wins a collision (#231).
 # Commented out = no docs by default. (The operating policy is NOT a doc: readSystemPolicy
-# already renders ~/.plurnk/AGENTS.md as the ## Plurnk Service Policy section — pointing a
+# already renders ~/.plurnk/AGENTS.md as the ## Policy section — pointing a
 # PLURNK_SERVICE_MD_* alias at it injects the same file twice.)
-# Turn-0 catalog preview, FIND-served (foisted as FIND(<scheme>:///**) per scheme) so a run
-# opens oriented, not blank. The model's OWN surface — known/unknown (memory), run (scratch),
-# plurnk (docs) — always foists FULL when the preview is on, never truncated: a partial view of
-# the model's own memory reads as withheld. This knob's first-N cap applies ONLY to the FILE list
-# (FIND(file:///**)), the one catalog that's external and arbitrarily large: -1 = the whole tree
-# (everything full); N = the first N files (memory still full); 0 = preview off entirely (the model
-# FINDs on demand). Servicewide default; a client overrides per workspace via workspace.create
-# settings.filesItems (#231).
+# Turn-0 catalog preview so a run opens oriented, not blank. Folder-capable schemes use
+# FIND(<scheme>:///*): direct entries plus exact dir/** summaries carrying each subtree's
+# recursive item and token counts. Curated kernel docs remain recursive, demonstrating both
+# navigation forms. -1 = each ordinary FIND's markerless first page; N = an explicit first-N
+# project-file page (other schemes remain markerless); 0 = preview off. Service-wide default;
+# a client overrides per workspace through workspace.create settings.filesItems (#231).
 PLURNK_SERVICE_FILES_ITEMS=-1
 
 # Number of full SHA-256 revision characters rendered on each model-facing
@@ -146,6 +162,10 @@ PLURNK_SERVICE_FILES_ITEMS=-1
 # abbreviation is display correlation only, never identity or comparison.
 PLURNK_SERVICE_EDIT_RECEIPT_REVISION_CHARS=8
 
+# Number of Git commit characters rendered in model-facing branch receipts.
+# The durable batch retains complete commit ids; this is display-only.
+PLURNK_SERVICE_BRANCH_RECEIPT_REVISION_CHARS=8
+
 # Number of neighboring lines (or top-level JSON items) rendered on each side
 # of an EDIT's resulting range. The model can READ for arbitrary final content.
 PLURNK_SERVICE_EDIT_RECEIPT_CONTEXT_LINES=2
@@ -156,54 +176,34 @@ PLURNK_SERVICE_EDIT_RECEIPT_CONTEXT_LINES=2
 # the ceiling fails hard (508 — no queue, no retry); the acting run counts itself.
 PLURNK_SERVICE_WORKSPACE_WORKERS_MAX_ACTIVE=-1
 
-# --- The window partition (§tokenomics-window-partition) — PER ALIAS (#352) ---
-# The window splits WITHOUT remainder: promptBudget = min(CONTEXT_WINDOW, real window) − REASONING −
-# COMPLETION − SAFETY is what the service may send; REASONING+COMPLETION is the generation
-# envelope (max_tokens on every call — no decode is unbounded); SAFETY covers chat-template
-# overhead. The prompt ceiling is DERIVED, never set directly.
+# --- Prompt budget and packing safety — PER ALIAS (#352) ---
+# Providers report physical context and response capacity. Core's natural prompt budget is the
+# remaining physical input room after the response envelope and SAFETY margin.
 #
-# #507 (owner-ruled): the generation envelope is PROVIDER-owned — window + reserves live in the
-# provider tier (`PLURNK_PROVIDERS_CONTEXT_WINDOW` / `PLURNK_PROVIDERS_REASONING_RESERVE` /
-# `PLURNK_PROVIDERS_COMPLETION_RESERVE`, ingested from the backend or pinned there; percent or
-# absolute forms — see plurnk-providers/.env.defaults). Core keeps ONE knob: SAFETY, the ruler's
-# own packing margin (a service fact, not a model fact). Resolves per alias: _<alias> wins over bare.
+# PROMPT_BUDGET is optional virtual pressure: it makes the model-facing gauge and grinder enforce
+# a smaller input budget without changing provider context or generation settings. Unset uses the
+# natural physical prompt budget; a set value can only tighten it. Both core knobs resolve per
+# alias: _<alias> wins over bare.
 # The retired PLURNK_SERVICE_{CONTEXT_WINDOW,REASONING,COMPLETION} names FAIL HARD at boot naming
 # their successors — a stale .env never silently loses its envelope.
+# PLURNK_SERVICE_PROMPT_BUDGET=128000
 PLURNK_SERVICE_SAFETY=1024
 #
-# PLURNK_SERVICE_BUDGET_MERMAID — the Budget section as visual mermaid (#440, §budget-mermaid). Default
-# `on`: the ceiling/usage/free headline PLUS three budget-scaled diagrams (turn-composition treemap,
-# heaviest-items xychart, used/free pie) — budget-awareness at a glance, and the pie doubles as a
-# training exemplar for the model's own user-facing SENDs. Validated to render on GitHub. Set `off` to
-# A/B against the tabular baseline (#440's before/after measurement).
-PLURNK_SERVICE_BUDGET_MERMAID=on
-#
 # LOCAL aliases (llama-server): the window is PROBED and the reserves DERIVE from it in the
 # provider tier (percent defaults) — zero-config. Absolute pins, when wanted, are provider-tier:
 # PLURNK_PROVIDERS_{REASONING,COMPLETION}_RESERVE_<alias> (see plurnk-providers/.env.defaults).
-# COUPLING (F7): per-request numeric reasoning budgets are IGNORED by llama-server — a local
-# thinking model's serving box MUST clamp via --reasoning-budget = the alias's resolved reasoning
-# reserve, or the reserve is fiction. The service warns at boot. Pinned absolutes exceeding the
-# detected window fail HARD at build time, naming the provider-tier knobs.
-
-# PLURNK_SERVICE_VERSION_POLL_TTL — how long (ms) discover caches its npm-registry version poll
-# (service + client `latest`) before a background refresh. Best-effort; the poll never
-# blocks discover, and offline/registry-down omits `latest`. ~hourly is plenty. #235
-PLURNK_SERVICE_VERSION_POLL_TTL=3600000
-# Grammar-constrained sampling: SELECTS the GBNF variant the provider constrains every
-# generate() to, so capable backends can only sample valid plurnk DSL. A bare name
-# (plurnk.gbnf) is a variant shipped by @plurnk/plurnk-grammar; a path is your own; =0
-# (or empty) disables.
-#
-
+# The provider sends the resolved reasoning allowance per request; no llama-server launch-flag
+# synchronization is required. Pinned absolutes exceeding the detected window fail HARD at build
+# time, naming the provider-tier knobs.
 
 # --- Plugins (third-party trust) ---
-# (PLURNK_PLUGINS_TRUSTED_ONLY moved to @plurnk/plurnk-plugins — reader-declares: the
+# (PLURNK_PLUGINS_TRUSTED_ONLY lives in @plurnk/plurnk-meta — reader-declares: the
 # trust rule's one implementation lives there and so does its knob.)
 
 # PLURNK_SERVICE_DOCS_EXCLUDE — comma list of scheme/exec names dropped from BOTH the teaching oneliner
-# and the materialized pull-doc on load. The self-evident (plurnk/file) + retired (exec) names the
-# model needs no doc for. Empty → exclude nothing. Unknown names are inert (a filter, not a contract).
+# and the materialized pull-doc on load. The default names are omitted from this generic
+# catalogue because their teaching is owned elsewhere. Empty → exclude nothing. Unknown names
+# are inert (a filter, not a contract).
 PLURNK_SERVICE_DOCS_EXCLUDE="plurnk,file,exec"
 
 # PLURNK_SERVICE_PACKET_INJECT — an operator markdown file injected as a section right after the teaching
@@ -211,23 +211,20 @@ PLURNK_SERVICE_DOCS_EXCLUDE="plurnk,file,exec"
 # `~/` expands to home. Unset → no section. The pressure valve for "improve the packet" without a fork.
 # PLURNK_SERVICE_PACKET_INJECT="~/injection.md"
 
-# PLURNK_SERVICE_POLICY — the operating-policy markdown, rendered as the ## Plurnk Service Policy
+# PLURNK_SERVICE_POLICY — the operating-policy markdown, rendered as the ## Policy
 # section. Unset = the seeded ~/.plurnk/AGENTS.md; a path = that file; EXPLICITLY empty = policy off.
 # PLURNK_SERVICE_POLICY=
 # PLURNK_SERVICE_PROJECT — a per-project policy markdown (relative to projectRoot). Unset = <root>/AGENTS.md.
 # PLURNK_SERVICE_PROJECT=
-# PLURNK_SERVICE_REQUIREMENTS — override the requirements.md recency-footer path (relative to the package
-# root). Unset = the packaged requirements.md.
+# PLURNK_SERVICE_REQUIREMENTS — Recap source override (relative to the package root).
+# Unset = the packaged requirements.md.
 # PLURNK_SERVICE_REQUIREMENTS=
 
 # --- Semantic search (~query chunking) ---
-# Project Semantics tiles each entry into <=window chunks so a large body is fully
-# searchable, not truncated. ACTIVE only when the installed embedder reports its
-# tokenizer; otherwise one whole-entry chunk (today's behavior). The chunk knobs are read
-# only when chunking is active.
-# Ranked results returned by a markerless `FIND(...):~query:FIND`. A positive
-# integer `<K>` overrides this count; a decimal marker selects by similarity.
-PLURNK_SERVICE_SEMANTIC_TOP_K=10
+# Project Semantics tiles each vector-eligible entry into <=window chunks so a large
+# body is fully searchable, not truncated. Chunking requires the embedder's exact
+# counter or an exact fallback tokenizer; an estimate refuses semantic derivation.
+# The chunk knobs are read only when an embedder declares its input window.
 # Chunk budget in TOKENS. EMPTY (the default) = the installed embedder's reported
 # window — NO model-specific number is assumed, so it scales to whatever embedder you
 # install. Set a positive value ONLY to cap below the window (e.g. to sweep
@@ -241,20 +238,27 @@ PLURNK_SERVICE_SEMANTIC_CHUNK_OVERLAP=0.15
 PLURNK_SERVICE_MAX_EMBED_SIZE=0
 # =1 forces the FTS-only path even with the embeddings package installed — the ~query
 # degrades to keyword ranking and no vectors are derived (no MiniLM pool spun up). For
-# hosts/runs that don't want vector search; the fast test lane sets it in .env.test.
+# hosts/runs that don't want vector search; the Mock bootstrap and constrained benchmarks set it.
 PLURNK_SERVICE_EMBED_DISABLE=0
 
 # Which exec runtimes the search gate treats as searches — the per-turn cap and identical-query
-# dedup apply to these (the search family delegates page fetches to the entry() sink; §exec-entry-sink).
+# dedup apply to these (the search family delegates page fetches to the entry() sink; {§exec-entry-sink}).
 PLURNK_SERVICE_SEARCH_RUNTIMES=search
 # Per-turn search flood cap: the (N+1)th search EXEC in one turn is refused 429 (dedup of
 # identical queries is unconditional and separate — it strikes and serves the prior results).
 PLURNK_SERVICE_SEARCH_MAX_PER_TURN=3
-# FIND match-render budget: a FIND whose match set exceeds this returns a COUNT + narrow-your-query
-# steer instead of enumerating every match (§find-count-not-contents) — a repo-scale FIND(**) over
-# a 19k-entry workspace grinds clean instead of overflowing the window. 0/unset = no gate.
-PLURNK_SERVICE_FIND_MAX_MATCHES=500
+# Comma-separated file pathname patterns omitted from search derivations. Content remains directly
+# readable. Patterns without `/` match the basename; patterns with `/` match the full pathname.
+# Uses body-matcher glob syntax; the first match is the observable exclusion reason. Empty = none.
+PLURNK_SERVICE_SEARCH_EXCLUDE=*.min.*,*.map,package-lock.json,npm-shrinkwrap.json,packages.lock.json,yarn.lock,pnpm-lock.yaml,bun.lockb,Cargo.lock,poetry.lock,uv.lock,Pipfile.lock,Gemfile.lock,composer.lock,go.sum,flake.lock,gradle.lockfile,*/dist/*,dist/*,*/build/*,build/*,*/.next/*,.next/*,*/node_modules/*,node_modules/*,*/vendor/*,vendor/*,*/coverage/*,coverage/*,*/.vuepress/*,.vuepress/*,*/.nuxt/*,.nuxt/*
 # Derivation producer concurrency: how many entries may materialize graphs/chunk plans at once.
 # Unset uses a host-relative square-root fan-out; the separate embedding pool uses the available
 # cores. A positive integer is an exact operator budget; -1 explicitly claims every available core.
 PLURNK_SERVICE_DERIVE_CONCURRENCY=
+# Maximum symbol or reference rows written by one search-index SQLite statement.
+PLURNK_SERVICE_DERIVE_STORE_BATCH=1024
+# Approximate number of aggregate progress milestones emitted during a multi-item
+# indexing pass. This also controls per-item embedding milestones.
+PLURNK_SERVICE_DERIVE_PROGRESS_STEPS=10
+# Minimum interval between progress notices from a long-running individual item.
+PLURNK_SERVICE_DERIVE_PROGRESS_HEARTBEAT_MS=5000

package/INSTALL.md

@@ -1,54 +1,69 @@
 # Configuring plurnk-service
 
-Agent guide. Read this, then generate a `~/.plurnk/.env` fit to the user's box and intent. `.env.defaults` is the terse machine floor — the authoritative flag list and defaults (the ASSEMBLED catalog of every installed package's file lands at `~/.plurnk/.env.defaults`); this is its reasoning layer. Every claimed coupling below is enforced by a `test/intg` check, so it is current with the installed version.
+Operator guide. Put machine-specific choices in `~/.plurnk/.env`. Each installed package's `.env.defaults` is the authoritative list and floor for the knobs that package owns; the daemon assembles those files into the read-only `~/.plurnk/.env.defaults` catalog on every boot.
 
 ## Install
 
 ```
 npm install -g @plurnk/plurnk-service
-plurnk-service start          # `migrate` first if the DB is uninitialized
+plurnk-service migrate        # apply the disposable version-1 schema baseline
+plurnk-service start
 ```
 
-First run creates `~/.plurnk/`: `.env` (yours, seeded once with a model picker — **edit this**), `AGENTS.md` (the operating policy, yours), `.env.defaults` + `INSTALL.md` (package-owned references, **refreshed every boot** — never edit them). No model ships active; a fresh daemon runs until `PLURNK_MODEL` is set.
+First start creates `~/.plurnk/`: `.env` (yours, seeded once with a model picker — **edit this**), `AGENTS.md` (the operating policy, yours), `.env.defaults` + `INSTALL.md` (package-owned references, **refreshed every boot** — never edit them). No model ships active; the daemon can boot without one, but model loops fail until `PLURNK_MODEL` selects a declared alias.
 
-Optional vector search: `npm i @plurnk/plurnk-mimetypes-embeddings` (heavy native deps). Absent → `~query` degrades to FTS keyword ranking.
+The default service includes local embeddings. An explicitly disabled or unavailable embedder makes `~query` fall back to FTS keyword ranking. Set `PLURNK_MIMETYPES_EMBED_BASE_URL` to use a remote OpenAI-compatible embedding endpoint instead.
 
 ## The cascade (where a value actually comes from)
 
-Lowest precedence first; the last writer wins:
+Higher-priority source classes override lower ones ({§operator-config-precedence}):
 
-1. **the assembled `.env.defaults` floor** — every installed package's shipped file, one owner per key (a collision crashes boot naming both), evolves with the installed versions.
-2. **`~/.plurnk/.env.defaults`** — the readable assembled legend, regenerated each boot (a reference, not a place to edit).
-3. **`~/.plurnk/.env`** — the user's home config, seeded once, theirs to keep. **Write generated config here.**
-4. **`./.env`** — per-project, current working directory.
-5. **`--env-file=<path>` / `--config=<path>`** — explicit layers.
-6. **shell environment** — beats every file.
-7. **`--<flag>` CLI args** — top layer, overrides all.
+| Priority | Source                                 | Role                                                                                       |
+|---------:|----------------------------------------|--------------------------------------------------------------------------------------------|
+|        1 | Installed packages' assembled defaults | Versioned floor; one owner per key. A collision fails boot naming both owners.             |
+|        2 | `~/.plurnk/.env`                       | User configuration, seeded once and never overwritten. **Write generated config here.**    |
+|        3 | `./.env`                               | Configuration for the current working directory.                                           |
+|        4 | `--config=<path>`                      | One explicit service configuration file.                                                   |
+|        5 | `--env-file*`                          | Repeatable explicit files; later files win. The `-if-exists` form skips absent files.       |
+|        6 | Shell environment                      | Process-level operator values.                                                              |
+|        7 | `--<flag>`                             | Highest-priority service CLI value.                                                         |
 
-CLI flags are the **1:1 mirror** of the env vars: strip `PLURNK_`, lowercase, `_`→`-`. `PLURNK_SERVICE_MAX_TURNS` ↔ `--service-max-turns`; `PLURNK_MODEL` ↔ `--model`. The flag surface and `--help` are generated from the service's `.env.defaults`, so a var and its flag never diverge. Feature-flag bools are `=== "1"` exactly (never `"true"`); `~/` expands to home.
+`~/.plurnk/.env.defaults` is the regenerated assembled catalog, not another input layer. The service CLI mirrors only the `PLURNK_*` variables declared by the service package's own `.env.defaults`: strip `PLURNK_`, lowercase, and replace `_` with `-` (`PLURNK_SERVICE_MAX_TURNS` ↔ `--service-max-turns`). Installed plugin knobs remain available through env/config files and the assembled catalog without implicitly expanding the service executable's CLI ({§operator-config-cli-flags}). Feature-flag booleans use `1`, not `true`; `~/` expands to home.
 
 ## The prefix law (who owns a flag)
 
-The prefix is the **owning package**: `PLURNK_SERVICE_*` (this daemon), `PLURNK_PROVIDERS_*`, `PLURNK_MIMETYPES_*`, `PLURNK_EXECS_*`, `PLURNK_SCHEMES_HTTP_*`, `PLURNK_AGUI_*` (the AG-UI module's own knobs), `PLURNK_CLIENT_*` (the CLI). **Bare `PLURNK_*` is reserved** for the front-door + cross-package set no single package owns: `PLURNK_MODEL[_*]`, `PLURNK_BASEURL_*`, `PLURNK_HOST`/`PLURNK_PORT` (the connection rendezvous), and `PLURNK_PLUGINS_TRUSTED_ONLY` (the cross-family plugin gate). Vendor keys (`OPENAI_API_KEY`, `FIREWORKS_API_KEY`…) are vendor conventions — untouched.
+Family prefixes identify the semantic owner: `PLURNK_SERVICE_*` (this daemon), `PLURNK_PROVIDERS_*`, `PLURNK_MIMETYPES_*`, `PLURNK_EXECS_*`, `PLURNK_SCHEMES_HTTP_*`, `PLURNK_AGUI_*` (the AG-UI module), and `PLURNK_CLIENT_*` (the CLI). Bare `PLURNK_*` names are reserved for front-door or cross-family concepts such as model aliases, endpoint binding, and plugin trust. Even a cross-family key has one physical reader and one `.env.defaults` owner; “shared” never means duplicate implementations. Vendor keys (`OPENAI_API_KEY`, `FIREWORKS_API_KEY`, and peers) retain their vendor conventions.
 
-A bare flag is a signal: more than one component depends on it. A prefixed one is single-owner. When a flag is `REQUIRED`, an unset or old-named value **fails the boot loudly** naming the var — never a silent default.
+When a value is required, an unset or retired name fails boot naming the violated key rather than selecting a silent default.
 
 ## Couplings (the edges an agent gets wrong)
 
 These are relationships *between* flags. Set them as a unit.
 
-- **The window partition is exact.** `promptBudget = min(PLURNK_SERVICE_CONTEXT_WINDOW, real window) − REASONING − COMPLETION − SAFETY`; `REASONING + COMPLETION` is the per-call `max_tokens`. Shipped invariant: any window ≥ 77Ki partitions to **exactly 65536** prompt tokens (`78848 − 4096 − 8192 − 1024`). Reserves exceeding the window fail the boot. *(Pinned: `Engine.budget` / `shipped-defaults`.)*
-- **Reasoning capacity is one number in three places.** `PLURNK_SERVICE_REASONING` (the partition's reserve) **must equal** `PLURNK_PROVIDERS_THINKING_CAPACITY` (the provider's thinking cap) **must equal** the serving box's `--reasoning-budget` launch flag. llama-server ignores per-request numeric budgets, so only the launch flag clamps it; a mismatch makes the reserve fiction. The daemon warns at boot when thinking is on. *(Pinned: `shipped-defaults` asserts the first equality.)*
+- **Provider capacity and PLURNK pressure are separate.** Providers report
+  physical context and response capacity. Core derives the natural input
+  budget from those facts. Optional `PLURNK_SERVICE_PROMPT_BUDGET_<alias>`
+  only tightens the model-facing gauge and grinder; it is never sent to the
+  provider and never changes generation settings.
+- **Reasoning capacity is request-scoped on llama-server.**
+  `PLURNK_PROVIDERS_REASONING_RESERVE_<alias>` is the adaptive cumulative
+  response allowance. An explicit `PLURNK_PROVIDERS_REASONING_BUDGET_<alias>`
+  may tighten but cannot exceed it. The provider sends the allowance on every
+  request; no serving-box flag synchronization is required.
 - **Local GBNF is optional.** The PLURNK language is always parsed normally.
   Local llama-server users may set `PLURNK_PROVIDERS_GBNF_<alias>`; transport
   and enforcement are verified at boot. Cloud and endpoint-managed aliases
-  leave it unset. Pin `PLURNK_PROVIDERS_LLAMA_SERVER_<alias>=1` only when a
-  llama-server cannot be fingerprinted reliably.
-- **A think-trained model must think somewhere.** `PLURNK_PROVIDERS_THINKING=off` reroutes a reasoning model's thought into the grammar's legal free zone as prose. Keep it `on` with a capacity; providers auto-clamp thinking on in-band grammar backends, so one setting is right everywhere.
+  leave it unset. A configured PLURNK rail requires reasoning `adaptive` or
+  `on`; pairing it with `off` is invalid. Pin
+  `PLURNK_PROVIDERS_LLAMA_SERVER_<alias>=1` only when a llama-server cannot be
+  fingerprinted reliably.
+- **A reasoning model must reason somewhere.**
+  `PLURNK_PROVIDERS_REASONING_<alias>` selects `off`, `adaptive`, or `on`.
+  An explicit `on` also requires a positive provider reasoning budget.
 
 ## Profiles (examples, not a decision tree — adapt to the real box)
 
-- **Local GPU (llama-server).** `PLURNK_MODEL_local="openai/<name>"`, `OPENAI_BASE_URL=http://127.0.0.1:<port>`, `PLURNK_MODEL=local`, `PLURNK_PROVIDERS_LLAMA_SERVER_local=1`, thinking `on`/`4096` **with the box launched `--reasoning-budget 4096`**. Full rails, exact tokenization.
+- **Local GPU (llama-server).** `PLURNK_MODEL_local="openai/<name>"`, `OPENAI_BASE_URL=http://127.0.0.1:<port>`, `PLURNK_MODEL=local`, `PLURNK_PROVIDERS_GBNF_local=plurnk.gbnf`. The provider detects llama-server, verifies its GBNF transport, and derives a request-scoped reasoning allowance from the detected window. Add `PLURNK_PROVIDERS_LLAMA_SERVER_local=1` only when the endpoint cannot be fingerprinted reliably.
 - **Cloud, bring-your-own-key.** `PLURNK_MODEL_cloud="openrouter/<model>"`, `OPENROUTER_API_KEY=…`, `PLURNK_MODEL=cloud`. No local GBNF or `LLAMA_SERVER` pin.
 - **plurnk.ai endpoint.** `PLURNK_MODEL_plurnk="plurnk/plurnk"`, `PLURNK_API_KEY=…`, `PLURNK_MODEL=plurnk`.
 - **Headless / CI / constrained container.** A CPU-only box should NOT disable semantic search — it should point derivation at a real embedder: `PLURNK_MIMETYPES_EMBED_BASE_URL` (any OpenAI-compatible `/v1/embeddings` — a host GPU turns a CPU-hours corpus grind into seconds). Weak hardware is the target workload, not a reason to shed capability; `PLURNK_SERVICE_EMBED_DISABLE=1` exists for test lanes that deterministically assert non-semantic behavior, nothing else. Consider `PLURNK_SERVICE_MAX_TURNS=<n>` as a cost cap, `PLURNK_SERVICE_GIT_ALLOWED=0` to lock out git in a sandbox.
@@ -59,17 +74,28 @@ Each mirrors a `# --- section ---` in the floor; consult the floor for exact def
 
 - **Storage** — `PLURNK_SERVICE_DB_PATH`, and the optional `PLURNK_SERVICE_SQLITE_*` passthroughs (sqlrite already sets a safe WAL posture; tune only for a hot/large DB).
 - **Daemon transport** — bare `PLURNK_HOST`/`PLURNK_PORT`: THE client surface (the AG-UI+ listener, bound by the plurnk-agui module at boot). Production is single-listener; every first-party client rides it.
-- **Model aliases** — bare `PLURNK_MODEL` selects the active provider; `PLURNK_MODEL_<alias>` defines one; `PLURNK_BASEURL_<alias>` overrides its endpoint. The front door — keep these bare and short.
-- **Loop control / Engine rails** — `PLURNK_SERVICE_MAX_TURNS` (−1 = uncapped), `_MAX_COMMANDS`, `_MAX_STRIKES`, `_MIN_CYCLES`, `_MAX_CYCLE_PERIOD`, `_RPC_TIMEOUT`, `_LOOP_TIMEOUT`, `_PROPOSAL_TIMEOUT_MS`, `_EXEC_WAIT_MS`, `_EXEC_KILL_GRACE_MS`, `_SESSION_RUNS_MAX_ACTIVE`. Guardrails; the shipped values are sane.
+- **Model aliases** — bare `PLURNK_MODEL` selects the active provider; `PLURNK_MODEL_<alias>` defines one; `PLURNK_BASEURL_<alias>` overrides its endpoint. Optional `PLURNK_MODEL_CHILD=<alias>` selects WORK/FORK descendants; unset inherits the spawning loop's provider. The front door — keep these bare and short.
+- **Loop control / engine rails** — `PLURNK_SERVICE_MAX_TURNS` (−1 = uncapped), `_MAX_COMMANDS`, `_MAX_STRIKES`, `_EMISSION_ATTEMPTS`, `_MIN_CYCLES`, `_MAX_CYCLE_PERIOD`, `_LOOP_TIMEOUT`, `_PROPOSAL_TIMEOUT_MS`, `_EXEC_HOLD`, `_OPTIMISTIC_WAIT_MS`, `_EXEC_POLL_SEC`/`_TURNS`, `_EXEC_KILL_GRACE_MS`, `_WORKSPACE_WORKERS_MAX_ACTIVE`.
 - **Git** — `PLURNK_SERVICE_GIT_ALLOWED` (0 = hard sandbox lockout), `_GIT_AUTO`.
-- **Packet / reference docs** — `PLURNK_SERVICE_FILES_ITEMS` (turn-1 file catalog cap), `_PROMPT_PREVIEW_CHARS`, `_DOCS_EXCLUDE`, `_PACKET_INJECT` (operator markdown section), `_POLICY`/`_PROJECT`/`_REQUIREMENTS` (policy + footer overrides; unset = the seeded/packaged defaults), `_MD_<alias>` (inject a markdown doc as a turn-0 entry).
+- **Packet / reference docs** — `PLURNK_SERVICE_FILES_ITEMS` (turn-0 shallow file-map cap), `_PREVIEW_LINES`/`_PREVIEW_CHARS`, `_EDIT_RECEIPT_REVISION_CHARS`/`_CONTEXT_LINES`, `_BRANCH_RECEIPT_REVISION_CHARS`, `_DOCS_EXCLUDE`, `_PACKET_INJECT` (operator markdown section), `_POLICY`/`_PROJECT` (policy overrides), `_REQUIREMENTS` (Recap-source override), `_MD_<alias>` (materialized reference entry).
 - **Providers** — the portable provider knobs and defaults are defined by
   `@plurnk/plurnk-providers/.env.defaults`; any provider knob may take an alias
   suffix that wins over the bare fallback.
-- **The window partition** — `PLURNK_SERVICE_CONTEXT_WINDOW`/`_REASONING`/`_ASSISTANT`/`_SAFETY` (see Couplings).
+- **Provider capacity and prompt budget** —
+  `PLURNK_PROVIDERS_CONTEXT_WINDOW`/`_REASONING_RESERVE`/`_COMPLETION_RESERVE`
+  describe provider capacity. `PLURNK_SERVICE_PROMPT_BUDGET` applies optional
+  virtual pressure; `PLURNK_SERVICE_SAFETY` is the packing margin.
 - **Plugins** — bare `PLURNK_PLUGINS_TRUSTED_ONLY` (0/unset = load all installed; a value = `@plurnk/*` plus an allowlist).
-- **Semantic search** — `PLURNK_SERVICE_SEMANTIC_TOP_K` (markerless result count), `_SEMANTIC_CHUNK_TOKENS`/`_CHUNK_OVERLAP` (service-side chunking), `PLURNK_SERVICE_EMBED_DISABLE` (FTS-only), `PLURNK_MIMETYPES_EMBED_WORKERS` (the embedder's pool — mimetypes-owned).
-- **Schemes: http** — `PLURNK_SCHEMES_HTTP_FETCH_TIMEOUT`/`_SALVAGE_MIN_BODY_CHARS`/`_IDLE_TIMEOUT` (required on the HTML render path), optional Playwright/Chromium knobs.
-- **Execs** — `PLURNK_EXECS_<runtime>=0` disables a runtime; `PLURNK_EXECS_MCP_<server>` bridges an MCP server; `PLURNK_EXECS_SEARCH_SEARXNG_URL` enables web search (unset = search off).
+- **Semantic search** — `PLURNK_SERVICE_SEMANTIC_CHUNK_TOKENS`/`_CHUNK_OVERLAP` (service-side chunking), `PLURNK_SERVICE_EMBED_DISABLE` (FTS-only), `PLURNK_MIMETYPES_EMBED_WORKERS` (the embedder's pool — mimetypes-owned).
+- **Schemes: http** — `PLURNK_SCHEMES_HTTP_FETCH_TIMEOUT`, `_TTL_MS`, optional `# TAVILY_API_KEY=`, and `PLURNK_SCHEMES_HTTP_TAVILY_DEPTH`/`_TAVILY_TIMEOUT_MS`.
+- **Execs** - `PLURNK_EXECS_<runtime>=0` disables a runtime; `PLURNK_EXECS_SEARCH_SEARXNG_URL` enables web search (unset = search off).
+- **Hooks** — `PLURNK_HOOKS_COMMAND` plus JSON `PLURNK_HOOKS_ARGS` invokes one exact no-shell command for the core events selected by `PLURNK_HOOKS_EVENTS`; see `@plurnk/plurnk-hooks/README.md`.
+- **Observability** — standard `OTEL_*` env ({§observability-boundary}):
+  `OTEL_TRACES_EXPORTER`/`OTEL_METRICS_EXPORTER` (`otlp` or `console`; unset
+  keeps the signal off), `OTEL_SERVICE_NAME` (default `plurnk-service`),
+  `OTEL_SDK_DISABLED` (opt out), and the OTLP exporters' own
+  `OTEL_EXPORTER_OTLP_*` settings. An unconfigured daemon never loads the OTel
+  SDK. Prompts, reasoning, file bodies, URLs, secrets, and plugin payloads are
+  never exported.
 
 The client's own knobs live under `PLURNK_CLIENT_*` (`--workspace`, `--run`, `--yolo`, `--json`…) — see `plurnk --help`.

package/README.md

@@ -7,28 +7,38 @@ operation dispatch. Its client surface is AG-UI over HTTP/SSE through
 
 ## What an agent can do
 
-Grammar ops: `PLAN` reason · `READ`/`EDIT` files · `FIND` search · `EXEC` run shell/code · `SEND` message or conclude · `COPY`/`MOVE`/`KILL` manage · `OPEN`/`FOLD` curate its own context.
+The exact model-facing language and operation set are owned by
+[`plurnk.md`](https://github.com/plurnk/plurnk-service/blob/main/plurnk-contracts/plurnk.md). In brief, an agent can:
 
-Over schemes: `file://` project files · `exec://` command output · `http(s)://` web fetch · `worker://` scratch + sibling agent runs (commons/own-space/spawn/fork/message) · `prompt://` the task frame · `skill://` bundled reference · `log://` own history.
+- inspect and modify admitted project files and durable worker entries;
+- search lexical, structural, graph, and embedding-derived indexes;
+- run registered executors and observe their runtime-named streams;
+- delegate to workers, communicate, and collect their results; and
+- curate its addressable log with tagged `FOLD`, `OPEN`, and `KILL` operations.
 
-## Loop model
+## Lifecycle model
 
-Workspace = the shared world (one filesystem + membership overlay). Run = one agent's private log. Loop = one `prompt → ops → SEND[terminal]` cycle; every turn leads with `PLAN`. Runs fork and message each other — many clients, many runs, one workspace.
+Workspace = the shared world (one filesystem + membership overlay). Worker = one actor and its private history over that world. Loop = one queued-to-terminal unit of work within a worker; each loop contains turns, and every model turn leads with `PLAN`. Workers fork and message each other — many clients, many workers, one workspace.
 
 ## Integration
 
-Clients use AG-UI management actions and run streams exposed by
+Clients use AG-UI management actions and AG-UI Run streams exposed by
 `@plurnk/plurnk-agui`. Core supplies an in-process daemon seam; it does not open
 a second client transport.
 
-## Run
+## Start
 
 ```
 npm install -g @plurnk/plurnk-service
-plurnk-service start      # daemon (`migrate` initializes the DB)
+plurnk-service migrate    # apply the disposable version-1 schema baseline
+plurnk-service start      # daemon
 ```
 
-Config + state live in `~/.plurnk/` (created on first run): put your config in `~/.plurnk/.env` (yours, seeded once); the DB defaults to `~/.plurnk/plurnk.db`. Provider-agnostic — point `PLURNK_MODEL` at any vendor. **[`INSTALL.md`](./INSTALL.md) is the config guide** — the cascade, the prefix taxonomy, the coupling matrix, and profiles for common deployments; `.env.defaults` is the terse machine floor it breaks down (per-package, assembled at boot). Also exports `{ Engine, Daemon, SchemeRegistry }` for in-process embedding.
+Config + state live in `~/.plurnk/` (created on first start): put your config in `~/.plurnk/.env` (yours, seeded once); the DB defaults to `~/.plurnk/plurnk.db`. Declare a provider/model as `PLURNK_MODEL_<alias>=<provider>/<model-id>`, then select that alias with `PLURNK_MODEL=<alias>`. **[`INSTALL.md`](./INSTALL.md) is the config guide** — the cascade, prefix ownership, coupled settings, and profiles; each installed package's `.env.defaults` supplies its exact machine floor.
+
+The 1.x package retains its frozen root library barrel for SemVer compatibility;
+it is not the client boundary and gains no new APIs. Programmatic forensic use
+imports `@plurnk/plurnk-service/digest`.
 
 ## Contract & siblings
 
@@ -37,14 +47,19 @@ Config + state live in `~/.plurnk/` (created on first run): put your config in `
 - `@plurnk/plurnk-schemes` — addressable resource contract.
 - `@plurnk/plurnk-mimetypes` — content handling contract.
 - `@plurnk/plurnk-execs` — executable capability contract.
+- `@plurnk/plurnk-hooks` — selected lifecycle events delivered to exact commands.
+
+## Observability
+
+The daemon can emit OpenTelemetry traces and low-cardinality metrics through the standard `OTEL_*` environment ({§observability-boundary}): `OTEL_TRACES_EXPORTER` / `OTEL_METRICS_EXPORTER` select `otlp` or `console` per signal, `OTEL_SERVICE_NAME` names the service, and `OTEL_SDK_DISABLED` opts out. Unconfigured, the daemon never loads the SDK. The boundary observes lifecycle (workspace, loop, turn, provider, parse, dispatch, proposal, stream, digest) without ever recording prompts, reasoning, file bodies, URLs, secrets, or plugin payloads.
 
 ## Semantic search
 
-`FIND`'s `~query` ranks semantically via an optional embedder peer, `@plurnk/plurnk-mimetypes-embeddings` (heavy native deps; not installed by default). Absent → `~query` falls back to FTS keyword ranking and `start` prints an `embedder inactive` notice. Enable vector search: `npm i @plurnk/plurnk-mimetypes-embeddings`.
+The default service installation includes `@plurnk/plurnk-mimetypes-embeddings`, so `FIND`'s `~query` uses embedding cosine ranking without a separate package install. `PLURNK_SERVICE_EMBED_DISABLE=1` explicitly selects FTS keyword ranking; a missing required artifact is a broken installation and refuses startup. A remote OpenAI-compatible embedder can replace the included local path; see [`INSTALL.md`](./INSTALL.md).
 
 ## The file sandbox
 
-Plurnk sees what git sees. The model's file surface is defined by three external grantors — your explicit client adds, your git's own inclusion rules (tracked plus untracked-not-ignored, minus ignored), and the AGENTS.md policy knob — and by nothing else: a file inside the project that none of these admit does not exist for the model, and your gitignored secrets can be neither read nor overwritten. Writes are narrower still: create-only inside the project (and only where the result will be visible), proposal-gated edits on members, read-only beyond the root unless you explicitly grant otherwise. The shell (EXEC) deliberately reaches beyond this sandbox — gate it accordingly; it is your machine's perimeter, not the grammar's. Details: SPEC §scheme-address ({§fs-namespace} through {§fs-world-state}).
+Plurnk sees what Git or the client explicitly admits. The AGENTS.md policy path is injected separately as privileged policy, not as a file entry. A project file admitted by neither Git nor the client does not exist to the model, and an ignored secret can be neither read nor overwritten. New files can be created only inside the project and only where the result will remain visible; member edits are proposal-gated; an outside-root member is read-only unless the client explicitly granted it. `EXEC` deliberately reaches beyond this file sandbox, so its proposal policy is the machine perimeter. Details: SPEC {§scheme-address} ({§fs-namespace} through {§fs-world-state}).
 
 ## Tests