@plurnk/plurnk-service 1.16.5 → 1.17.0

package/.env.defaults

@@ -1,286 +1,162 @@
-# ⚠ REFERENCE — this is @plurnk/plurnk-service's shipped .env.defaults: the operative floor
-# for its knobs and source of the derived --<knob> CLI flags. Run
-# `plurnk-service config defaults` for the complete owner-labelled installed aggregate. Put user
-# overrides in $XDG_CONFIG_HOME/plurnk/.env (seeded once, never overwritten), ./.env, or the shell.
-#
-# THE STANDARD (every plurnk package, third-party included): ship a `.env.defaults` at your
-# package root declaring YOUR knobs (prefix = your package's name); the file IS the documentation.
-# The daemon assembles every installed member's file into one floor. ONE LAW: a key claimed by
-# 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.
-#
-# Source classes (low → high precedence; higher classes win):
-#   assembled .env.defaults floor  (this file + every installed member's, uniqueness-checked)
-#   < $XDG_CONFIG_HOME/plurnk/.env (your user 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)
-# Later repeated explicit files win.
-# Feature-flag bools use `=== "1"` exactly, never `=== "true"`. `~/` expands to your home.
-
-# --- Storage ---
-# Empty derives $XDG_DATA_HOME/plurnk/plurnk.db (default ~/.local/share/plurnk/plurnk.db).
-# An explicit non-empty path overrides it; `~/` expands to home.
+# @plurnk/plurnk-service — daemon configuration.
+# Active declarations are defaults; commented declarations are optional examples.
+# Put overrides in the shell, ./.env, or $XDG_CONFIG_HOME/plurnk/.env.
+# Full installed reference: plurnk-service config defaults
+# Precedence (highest first): CLI flags > shell > --env-file* > --config >
+# ./.env > user .env > package defaults. Later explicit env files win.
+# Service flags mirror these names: PLURNK_SERVICE_MAX_TURNS → --service-max-turns.
+
+# --- Storage and listener ---
+# Database path; empty = $XDG_DATA_HOME/plurnk/plurnk.db (~/.local/share by default).
 PLURNK_SERVICE_DB_PATH=
+# AG-UI listener bind address.
+PLURNK_HOST=127.0.0.1
+# AG-UI listener TCP port, shared by all client interfaces.
+PLURNK_PORT=1066
 
-# Filesystem creation ceiling. none = deny new files; root = only project_root (default);
-# namespace = also permit canonical outside-root paths. Existing-member writes are unaffected.
-# A workspace may narrow this with settings.fileCreateScope, never widen it.
-PLURNK_SERVICE_FILE_CREATE_SCOPE=root
-
-# --- Sqlite tuning (curated knobs passed through to sqlrite; optional) ---
-# sqlrite already sets the safe posture (WAL + synchronous=NORMAL + busy_timeout=5000ms).
-# These are operator overrides — integers; unset = sqlrite/sqlite default. Uncomment to tune.
-# busy_timeout (ms): how long a writer waits on a lock before SQLITE_BUSY. 0 = immediate.
+# --- SQLite (optional sqlrite overrides) ---
+# Lock wait, ms; 0 = immediate failure. sqlrite defaults to 5000, WAL, synchronous=NORMAL.
 # PLURNK_SERVICE_SQLITE_TIMEOUT=5000
-# cache_size: positive = pages, negative = KiB of memory. Bigger = fewer disk reads on a hot db.
+# Page cache: positive = pages; negative = KiB. Unset = SQLite default.
 # PLURNK_SERVICE_SQLITE_CACHE_SIZE=-16000
-# mmap_size: bytes of memory-mapped I/O (read perf on large file-backed dbs). 0 disables.
+# Memory-mapped I/O limit, bytes; 0 = off. Unset = SQLite default.
 # PLURNK_SERVICE_SQLITE_MMAP_SIZE=268435456
-# max_page_count: hard db-size ceiling in PAGES — a write past it errors (disk-fill guard).
+# Database size ceiling, pages; writes beyond it fail. Unset = SQLite default.
 # PLURNK_SERVICE_SQLITE_MAX_PAGE_COUNT=524288
 
-# --- Daemon transport ---
-PLURNK_HOST=127.0.0.1
-# THE client surface — the AG-UI+ listener (the plurnk-agui daughter module binds it at boot).
-# Production is single-listener: every first-party client rides this surface.
-PLURNK_PORT=1066
-
-# --- Loop control ---
-# Service-wide capability ceiling as a CapabilityPolicy JSON object. `deny`
-# removes matching demands; an optional `only` admits only matching demands.
+# --- Permissions and membership ---
+# CapabilityPolicy JSON: deny removes matching demands; only admits only matches.
 # Workspace, Worker, and loop policies may narrow this ceiling, never widen it.
 PLURNK_SERVICE_CAPABILITIES={}
-# Optional default child-model selector (declared alias or provider/model route).
-# Unset = each WORK/FORK child inherits its spawning loop's model. Clients may
-# override this per top-level loop.
+# New filesystem files: none | root | namespace (also outside root). Existing-member writes unchanged.
+PLURNK_SERVICE_FILE_CREATE_SCOPE=root
+# Model-added membership: none | root | namespace. Workspaces may narrow it.
+# Operator definitions use PLURNK_MEMBERS_<alias>=<glob> and PLURNK_MEMBERS_ENABLED=["alias"].
+PLURNK_SERVICE_MEMBERS_MODEL_SCOPE=none
+# Git membership, status, and branch integration: 1 = permitted; 0 = denied service-wide.
+PLURNK_SERVICE_GIT_ALLOWED=1
+# Include the repository containing project_root as members: 1 = yes; 0 = explicit members only.
+PLURNK_SERVICE_GIT_AUTO=1
+# Maximum stdout/stderr bytes accepted from one native Git subprocess.
+PLURNK_SERVICE_GIT_OUTPUT_MAX_BYTES=67108864
+# Maximum bytes per workspace-file snapshot, 1..104857600. Larger sources return 413 on READ/EDIT.
+PLURNK_SERVICE_FILE_MATERIALIZE_MAX_BYTES=104857600
+
+# --- Loop limits and recovery ---
+# Default child model: alias or provider/model. Unset = inherit the spawning loop's model.
 # PLURNK_MODEL_CHILD=fast
-# Operator turn ceiling. -1 (default) = no cap (loops end via SEND, provider capacity,
-# strikes, or cycle detection). A positive value is an inviolable hard cap a
-# CoreSeam runLoop({maxTurns}) request cannot exceed (min wins).
+# Model turns per loop, including resumes; -1 = unlimited. Client limits may tighten it.
 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).
+# Actions per emission; -1 = unlimited. Final disposition remains; excess actions report an error.
 PLURNK_SERVICE_MAX_COMMANDS=-1
-# Live & demo test harness story timeout (ms) — 10 minutes (600000ms).
+# Concurrent nonterminal runs per workspace; -1 = unlimited. Excess spawns return 508, not a queue.
+PLURNK_SERVICE_WORKSPACE_WORKERS_MAX_ACTIVE=-1
+# Active execution allowance per task, positive ms; WAIT pauses it, wakes retain it. Exhaustion: 504.
+PLURNK_SERVICE_LOOP_TIMEOUT=86400000
+# Live/demo whole-specimen deadline, ms; includes all prompts and cancels before cleanup.
 PLURNK_SERVICE_LIVE_TIMEOUT=600000
-# {§crash-only-stop} — the daemon's settle deadline on stop(): past this the
-# shutdown abandons its waits instead of hanging forever on a wedged child.
+# Shutdown settlement deadline, positive ms; abandon outstanding waits after expiry.
 PLURNK_SERVICE_STOP_TIMEOUT_MS=30000
-# Capability residency is demand-owned. After the final lease, keep the
-# worker warm this many ms for quick reuse. 0 = no grace; -1 = no time bound.
-PLURNK_SERVICE_WORKER_WARM_MS=900000
-# Maximum lease-free worker Functionality snapshots retained process-wide. Active work is
-# exempt. 0 = retain none; -1 = no idle-LRU bound.
-PLURNK_SERVICE_WORKER_WARM_MAX=2
-# Proposal resolution bound (ms). Empty = a stopped world waits for its human indefinitely;
-# a finite positive value auto-cancels unattended (outcome=timeout). Every other explicit
-# value is invalid and fails at the proposal lifecycle owner.
+# Provider recovery window, ms; 0 = park immediately. Expiry parks until the next prompt/wake.
+PLURNK_SERVICE_PROVIDER_RECOVERY=900000
+# First recovery delay, ms; doubles on failure, capped at 12 times this value.
+PLURNK_SERVICE_PROVIDER_RECOVERY_BACKOFF=5000
+# Consecutive turn-contract strike threshold.
+PLURNK_SERVICE_MAX_STRIKES=3
+# Completed responses allowed to produce an admissible turn against the same packet.
+PLURNK_SERVICE_EMISSION_ATTEMPTS=3
+# Minimum repetitions before cycle detection fires.
+PLURNK_SERVICE_MIN_CYCLES=3
+# Maximum repeating period examined by cycle detection, turns.
+PLURNK_SERVICE_MAX_CYCLE_PERIOD=4
+# Maximum characters of runtime diagnostics exposed in model-facing errors.
+PLURNK_SERVICE_ERROR_DETAIL_LIMIT=512
+
+# --- Workspace residency and execution ---
+# Idle workspace Functionality grace, ms; 0 = cool immediately; -1 = no time limit.
+PLURNK_SERVICE_WORKSPACE_WARM_MS=900000
+# Retained idle workspace snapshots; 0 = none; -1 = unlimited. Active work is exempt.
+PLURNK_SERVICE_WORKSPACE_WARM_MAX=2
+# Proposal wait, positive ms; empty = wait indefinitely. Expiry cancels the proposal.
 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>` holds only
-# that effect class. The retired web-search family names are gone; declare operator
-# runtimes explicitly.
+# Comma-separated runtime or runtime:effect names that hold the next turn while executing; empty = none.
 PLURNK_SERVICE_EXEC_HOLD=
+# Maximum turn hold, ms; expiry lets the loop continue while the stream remains live.
 PLURNK_SERVICE_EXEC_HOLD_MS=300000
-# Maximum EXEC producers admitted concurrently in one workspace. Additional
-# executions retain their durable streams and wait FIFO; -1 removes the bound.
+# Concurrent EXEC producers per workspace; excess executions wait FIFO; -1 = unlimited.
 PLURNK_SERVICE_EXEC_CONCURRENCY=12
-# Effect admission overrides ({§effect-policy-tunable}): comma-separated
-# <effect>:<policy> entries (host/read/pure → propose/auto). Unlisted effects
-# keep the default map (host proposes; read/pure auto-run). Empty = defaults.
+# Live input delivery deadline, positive ms, including queued writes; expiry retires input, not the process.
+PLURNK_SERVICE_EXEC_INPUT_TIMEOUT_MS=10000
+# Effect overrides, comma-separated effect:policy (host/read/pure → propose/auto).
+# Empty = host proposes, read/pure auto-run.
 PLURNK_SERVICE_EFFECT_POLICY=
-# 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.
+# Brief settlement wait for new streams/completing siblings, ms; 0 = off; quiescence ends it early.
 PLURNK_SERVICE_OPTIMISTIC_WAIT_MS=5000
-# Exec poll backoff ({§exec-poll}, https://github.com/plurnk/plurnk-service/issues/521):
-# 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).
+# Initial parked-EXEC poll delay, seconds; explicit <,P> wins and <,0> disables polling.
 PLURNK_SERVICE_EXEC_POLL_SEC=60
+# Backoff steps: delay doubles to BASE * 2^(TURNS-1), then stays capped.
 PLURNK_SERVICE_EXEC_POLL_TURNS=8
-# Teardown reap grace: when a loop/run tears down a background exec, the spawn gets a polite
-# signal first (SIGHUP, or the model's KILL[code]); a stream that IGNORES it is hard-killed
-# (SIGKILL, to the whole process group) this many ms later — so the reap can't wedge on a
-# signal-ignoring child. plurnk-execs refuses to bake this number; the consumer owns it.
+# Grace after a termination signal, ms; then SIGKILL the surviving process group.
 PLURNK_SERVICE_EXEC_KILL_GRACE_MS=2000
-PLURNK_SERVICE_LOOP_TIMEOUT=86400000
-# {§provider-recovery} A recoverable provider failure (network failure, rate limit, deadline,
-# interrupted resource) never ends a loop. After the provider's own retries the turn records the
-# failure, waits with exponential backoff, and re-issues the same call for up to RECOVERY ms
-# (0 parks at once); past that the loop parks like a `### SEND0 [202]` wait and resumes on the
-# next prompt or wake. BACKOFF is the first delay (ms); it doubles per failure, capped at twelve
-# times itself.
-PLURNK_SERVICE_PROVIDER_RECOVERY=900000
-PLURNK_SERVICE_PROVIDER_RECOVERY_BACKOFF=5000
 
-# --- 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
-# workspace.create({projectRoot}) or never (headless is forever);
-# stored on workspaces.project_root. No env-level default.)
-
-# --- Git integration ---
-# 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 — automatic project-repository membership. =1 includes the Git
-# repository containing project_root; =0 leaves member definitions as the only membership source.
-PLURNK_SERVICE_GIT_AUTO=1
-# Maximum stdout/stderr payload accepted from one native Git subprocess.
-PLURNK_SERVICE_GIT_OUTPUT_MAX_BYTES=67108864
-
-# --- Membership ({§membership-baseline}) ---
-# PLURNK_SERVICE_MEMBERS_MODEL_SCOPE — the ceiling a MODEL's `### EXEC0 [members] (add)` is admitted
-# against, in the file-creation lattice none < root < namespace: `none` refuses every model
-# definition (the model widens visibility only through `git add`); `root` admits globs inside the
-# project root; `namespace` admits `../` too. A workspace narrows it with settings.membersModelScope.
-# The operator's own definitions are PLURNK_MEMBERS_<ALIAS>=<glob> (`!glob` excludes) and
-# PLURNK_MEMBERS_ENABLED=[…] in the operator env.
-PLURNK_SERVICE_MEMBERS_MODEL_SCOPE=none
-# Maximum bytes admitted into one materialized workspace-file snapshot (1..100 MiB,
-# matching the storage ceiling). A larger member remains addressable, but READ/EDIT
-# return its durable 413 size result.
-PLURNK_SERVICE_FILE_MATERIALIZE_MAX_BYTES=104857600
-
-# Ordinary bounded OPEN-body projection. READ/FIND results and PLAN working
-# memory render complete; prompt initialization uses its separate budget share.
-# Every remaining log body renders at most these independent line and character
-# bounds. A truncated body carries its canonical log URI.
+# --- Context and receipts ---
+# Maximum lines in automatic text previews and markerless READs. Explicit scopes stay exact.
 PLURNK_SERVICE_PREVIEW_LINES=16
+# Independent bound on the same previews, Unicode code points; CRLF counts as one separator.
 PLURNK_SERVICE_PREVIEW_CHARS=2560
-
-# Number of complete neighboring lines hashed on each side of a model-facing
-# line anchor. 0 authenticates only the addressed line.
+# Turn0 reasoning READ: -1 = complete; 0 = omit; N = first N lines. Later reads are model-chosen.
+# Alias override: PLURNK_REASONING_VIEW_LINES_<alias>. Source retention/streaming are unchanged.
+PLURNK_REASONING_VIEW_LINES=-1
+# Cold-start input allowance reserved for automatic prompt bodies, percentage in (0,100).
+# Alias override: PLURNK_SERVICE_PROMPT_PROJECTION_<alias>. Full prompts remain addressable.
+PLURNK_SERVICE_PROMPT_PROJECTION=25%
+# Neighboring lines hashed on each side of an editable line anchor; 0 = addressed line only.
 PLURNK_SERVICE_LINE_ANCHOR_CONTEXT_LINES=2
-
-# 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).
+# Surrounding and changed lines shown at each EDIT boundary; overlapping windows coalesce.
+PLURNK_SERVICE_EDIT_RECEIPT_CONTEXT_LINES=4
+# Turn-0 surveys: -1 = ordinary first pages; N > 0 caps file-map rows; 0 = off.
+# Workspace settings.filesItems overrides this default; other surveys keep ordinary pages.
 PLURNK_SERVICE_FILES_ITEMS=-1
 
-# Number of full SHA-256 revision characters rendered on each model-facing
-# EDIT receipt. The durable operation result retains all 64 characters; this
-# 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.
-
-# Number of surrounding and landed lines shown at each boundary of an EDIT
-# result. Overlapping windows coalesce; the model can READ omitted content.
-PLURNK_SERVICE_EDIT_RECEIPT_CONTEXT_LINES=2
-
-# Workspace-tier ceiling on CONCURRENT active runs (a run with a non-terminal loop)
-# — the fork-bomb / destabilization brake. -1 = no cap (default); only concurrency
-# is bounded, never lifetime, since workspaces persist for months. A spawn/fork past
-# the ceiling fails hard (508 — no queue, no retry); the acting run counts itself.
-PLURNK_SERVICE_WORKSPACE_WORKERS_MAX_ACTIVE=-1
-
-# --- Prompt projection — PER ALIAS ---
-# Providers derive physical input capacity from model limits and the total output envelope.
-# Core projects that number into its model-facing curation gauge; no second service-side token
-# budget or packing margin exists. The retired PLURNK_SERVICE_{PROMPT_BUDGET,SAFETY,
-# CONTEXT_WINDOW,REASONING,COMPLETION} names fail hard at boot.
-# Maximum aggregate share of the model-facing curation budget used by
-# automatic OPEN prompt bodies. The complete prompt remains stored and
-# READ/FIND-addressable; this controls projection, not prompt admission.
-# Alias-scoped overrides follow the ordinary _<alias> convention.
-PLURNK_SERVICE_PROMPT_PROJECTION=25%
-
-# --- Plugins (third-party trust) ---
-# (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 names dropped from BOTH the teaching oneliner
-# and its materialized pull-doc on load. Executable tools instead use their one enablement policy,
-# so an enabled tool is always discoverable. Empty → exclude nothing. Unknown names are inert.
+# --- Teaching and skills ---
+# Scheme names omitted from discoverable references, comma-separated; empty = none.
+# Executable docs instead follow tool enablement. Plugin trust lives in plurnk-meta's defaults.
 PLURNK_SERVICE_DOCS_EXCLUDE="plurnk,file,exec"
-
-# PLURNK_SERVICE_SKILLS_CLI — the standard Agent Skills installer command line beneath the Worker
-# `skills` Functionality family (`add` installs, `remove` uninstalls, `discover {source}` lists).
-# The installed SKILL.md, never the CLI's output, is the evidence. Point it at a pinned binary
-# or a fixture; it is never taught to the model or run by a client.
+# Agent Skills installer command, used by the service beneath skills add/remove/discover.
 PLURNK_SERVICE_SKILLS_CLI="npx --yes skills"
-# PLURNK_SERVICE_SKILLS_REGISTRY_URL — the ecosystem registry behind `discover {query}`
-# (GET <url>/api/search?q=…). Empty disables registry search (501 registry-not-configured).
+# Skills search registry (GET /api/search?q=...); empty = registry search disabled.
 PLURNK_SERVICE_SKILLS_REGISTRY_URL=https://skills.sh
-
-# PLURNK_SERVICE_PACKET_INJECT — an operator markdown file injected as a section right after the teaching
-# (the cached prefix). Read per-turn (live edits); a set-but-unreadable path fails the turn HARD.
-# `~/` expands to home. Unset → no section. The pressure valve for "improve the packet" without a fork.
+# Extra Markdown after language teaching, reread each turn; unreadable explicit paths fail.
 # PLURNK_SERVICE_PACKET_INJECT="~/injection.md"
-
-# PLURNK_SERVICE_POLICY — the operating-policy markdown, rendered as the ## Policy
-# section. Unset = the seeded $XDG_CONFIG_HOME/plurnk/AGENTS.md; a path = that file;
-# EXPLICITLY empty = policy off.
+# Policy Markdown: unset = $XDG_CONFIG_HOME/plurnk/AGENTS.md; empty = off; otherwise that path.
 # PLURNK_SERVICE_POLICY=
-# PLURNK_SERVICE_RECAP — Recap source override (relative to the package root).
-# Unset = the packaged recap.md; empty content omits the Recap section.
+# Recap file, relative to the package root; unset = packaged recap.md; empty file omits the section.
 # PLURNK_SERVICE_RECAP=
 
-# --- Semantic search (~query chunking) ---
-# 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
-# granularity); it is clamped to the window either way.
-PLURNK_SERVICE_SEMANTIC_CHUNK_TOKENS=
-# Overlap fraction [0,1): trailing context re-covered at each chunk boundary so a
-# concept split across a cut still matches in both. ~0.15 is a standard RAG default.
-PLURNK_SERVICE_SEMANTIC_CHUNK_OVERLAP=0.15
-# Maximum UTF-8 body size eligible for vectors. Oversized entries remain readable,
-# graph-derived, and FTS-indexed. 0 explicitly opts into unlimited vector eligibility.
-PLURNK_SERVICE_MAX_EMBED_SIZE=262144
-# =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 Mock bootstrap and constrained benchmarks set it.
-PLURNK_SERVICE_EMBED_DISABLE=0
-
-# 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.
+# --- Search indexing ---
+# Comma-separated globs excluded from derivation, not READ. No slash = basename; slash = pathname.
 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-vectors-background}: background (default) attaches each artifact's graph, FTS, and
-# summary in the initialization pass and derives its vectors behind it; a semantic query (~) holds
-# until the vectors of its candidates landed. eager derives vectors inside the pass, as before.
-PLURNK_SERVICE_DERIVE_VECTORS=background
-# 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.
+# Concurrent parser derivations: empty = sqrt(available cores); -1 = all cores; positive N = exact cap.
 PLURNK_SERVICE_DERIVE_CONCURRENCY=
-# Maximum symbol or reference rows written by one search-index SQLite statement.
+# Maximum symbol/reference rows per indexing SQLite statement.
 PLURNK_SERVICE_DERIVE_STORE_BATCH=1024
-# Interval between intermediate progress heartbeats during active semantic indexing.
-# Lifecycle start, failure, and completion are immediate; no-op passes stay silent.
+# Progress heartbeat, ms; starts, failures, and completion are immediate; no-op passes stay silent.
 PLURNK_SERVICE_DERIVE_PROGRESS_HEARTBEAT_MS=15000
+
+# --- Forensic interviews ---
+# Initial requiem output allowance, tokens; used only for requested out-of-band interviews.
+PLURNK_SERVICE_REQUIEM_MAX_TOKENS=16384
+# Retry allowance for empty length-limited testimony; must be at least the initial allowance.
+PLURNK_SERVICE_REQUIEM_RETRY_MAX_TOKENS=32768
+
+# --- Retention: information is kept; transient data is collected ({§retention-policy}) ---
+# Packet compositions kept per loop, newest first; -1 = every packet, forever.
+PLURNK_SERVICE_RETAIN_PACKET_TURNS=-1
+# Packet compositions kept by age, ms since the turn completed; -1 = no age limit.
+PLURNK_SERVICE_RETAIN_PACKET_MS=-1
+# Collect packet items no turn's composition references (1), or keep them (0).
+PLURNK_SERVICE_COLLECT_PACKET_ITEMS=1
+# Collect derivations no channel, turn source, or log row cites (1), or keep them (0).
+PLURNK_SERVICE_COLLECT_DERIVATIONS=1
+# Retention cadence while the daemon runs, ms; 0 = at shutdown only.
+PLURNK_SERVICE_RETENTION_INTERVAL_MS=3600000