@plurnk/plurnk-service 3.1.0 → 3.3.0

package/.env.defaults

@@ -20,8 +20,11 @@ PLURNK_SERVICE_SHARE_FOLDER=
 # The listener's address, PLURNK_HOST and PLURNK_PORT, is shared with every client and so is
 # declared by @plurnk/plurnk-contracts; --host and --port still spell it for one invocation.
 
-# --- SQLite (optional sqlrite overrides) ---
-# Lock wait, ms; 0 = immediate failure. sqlrite defaults to 5000, WAL, synchronous=NORMAL.
+# --- SQLite ---
+# WAL durability ({§db-durability}): FULL syncs every commit; NORMAL may lose recent commits
+# on power loss; OFF may corrupt the database; EXTRA equals FULL in WAL. Applied before migration.
+PLURNK_SERVICE_SQLITE_SYNCHRONOUS=FULL
+# Lock wait, ms; 0 = immediate failure. Unset = sqlrite's default.
 # PLURNK_SERVICE_SQLITE_TIMEOUT=5000
 # Page cache: positive = pages; negative = KiB. Unset = SQLite default.
 # PLURNK_SERVICE_SQLITE_CACHE_SIZE=-16000
@@ -69,7 +72,7 @@ PLURNK_SERVICE_FILE_MATERIALIZE_MAX_BYTES=104857600
 # Opt-in model-call ceiling shared by the worker tree, including BARE and resumes; -1 = uncapped.
 # Runtime (_plurnk) ancestry supplies no ceiling. Clients may tighten the model tree's limit.
 PLURNK_SERVICE_MAX_TURNS=-1
-# Actions per emission; -1 = unlimited. Final disposition remains; excess actions report an error.
+# Resolved actions per emission, including glob targets; -1 = unlimited. WAIT remains exempt.
 PLURNK_SERVICE_MAX_COMMANDS=-1
 # Concurrent live workers per workspace; -1 = unlimited. Excess spawns return 508, not a queue.
 PLURNK_SERVICE_WORKSPACE_WORKERS_MAX_ACTIVE=-1
@@ -131,11 +134,11 @@ PLURNK_SERVICE_OPTIMISTIC_WAIT_MS=5000
 # Maximum park before reassessing live work, positive seconds; WAIT [seconds] overrides one park.
 PLURNK_SERVICE_WAIT_SEC=300
 # Ambient environment an EXEC subprocess may inherit from the host: exact names, or one
-# trailing-* prefix glob. This is a CEILING — a worker or a heading modifier narrows it,
-# nothing widens it. plurnk's own secrets (PLURNK_* and every provider credential name) are
-# stripped beneath it unconditionally and are not governed by this knob.
+# trailing-* prefix glob. This bounds inherited host values, not explicit non-reserved values.
+# PLURNK_* and provider credential names remain excluded regardless of these selectors.
+# Module-owned launches and explicit MCP bindings follow their own launch contract.
 # The shipped list is what a shell, git, node and python need to run at all. An operator
-# who wants a tool's credential reachable by model-written commands adds it by name.
+# who wants a non-reserved tool credential inherited by commands adds its name.
 PLURNK_SERVICE_EXEC_ENV_INHERIT=PATH,HOME,USER,LOGNAME,SHELL,PWD,TMPDIR,TERM,TZ,LANG,LC_*,PAGER,GIT_PAGER,NO_COLOR,CI
 # Names removed after INHERIT, same shapes; narrows without rewriting the list above.
 PLURNK_SERVICE_EXEC_ENV_EXCLUDE=
@@ -151,14 +154,15 @@ PLURNK_SERVICE_EDIT_RECEIPT_CONTEXT_LINES=4
 PLURNK_SERVICE_EDIT_RECEIPT_REMOVED_LINES=40
 # Paths named per class in the packet's git status; the rest are counted.
 PLURNK_SERVICE_GIT_STATUS_PATHS=8
-# Above this share of the budget, measured before adding either, the Context gauge names its largest rows
-# and a packet within its budget carries the budget_pressure notice ({§context-pressure-notice}).
+# Above this share of the budget, measured before adding the inventory, the Context gauge names its largest
+# rows ({§context-gauge}); the gauge's percent is on every packet regardless.
 PLURNK_SERVICE_BUDGET_PRESSURE=80%
 # Heaviest retained log rows the pressured Context gauge names, as {path, tokens}; 0 names none.
 PLURNK_SERVICE_BUDGET_LARGEST_ITEMS=5
 # First page of everything that comes back unasked in size: a READ or FIND without a scope, a stream's
 # delivery, a peer worker's message, a receipt the model did not author ({§markerless-first-page}).
-# Lines of text, bytes of a byte view, results of a FIND; explicit scopes stay exact.
+# Lines of text, bytes of a byte view, results of a FIND; explicit scopes stay exact. 100 is a page for
+# the million-token windows hosted models have; a deployment with a small room tunes it down.
 PLURNK_SERVICE_PREVIEW_LINES=100
 # Independent bound on the same page, Unicode code points; CRLF counts as one separator.
 PLURNK_SERVICE_PREVIEW_CHARS=16000
@@ -219,23 +223,24 @@ PLURNK_SERVICE_DERIVE_STORE_BATCH=1024
 # Progress heartbeat, ms; starts, failures, and completion are immediate; no-op passes stay silent.
 PLURNK_SERVICE_DERIVE_PROGRESS_HEARTBEAT_MS=15000
 
-# --- Retention: information is kept; transient data is collected ({§retention-policy}) ---
-# Packet compositions kept per loop, newest first; -1 = every packet, forever.
+# --- Retention: packet/response bodies and unreferenced content ({§retention-policy}) ---
+# Packet compositions kept per loop, newest first; -1 disables the count limit, not the age limit.
 PLURNK_SERVICE_RETAIN_PACKET_TURNS=-1
-# Packet compositions kept by age, ms since the turn completed; -1 = no age limit. Thirty days:
-# no worker reads its own packets back that late, and a daemon left running for months stops growing.
+# Packet compositions kept by age, ms since the turn completed; -1 disables the age limit.
 PLURNK_SERVICE_RETAIN_PACKET_MS=2592000000
-# Model response bodies kept per loop, newest first; -1 = every body, forever. The call's
-# evidence, admission and accounting always stay.
+# Calls with captured payloads kept per loop, newest first; -1 disables the count limit.
+# These controls do not retire messages, turn sources, operations, approval decisions or accounting.
 PLURNK_SERVICE_RETAIN_RESPONSE_TURNS=-1
-# Model response bodies kept by age, ms since the turn completed; -1 = no age limit. Thirty days, as above.
+# Call payloads kept by age, ms since the turn completed; -1 disables the age limit.
+# Covers normalized responses and all physical-request payloads, including failed retries.
+# Identities, status, usage and cost remain; retirement is timestamped on the logical call.
 PLURNK_SERVICE_RETAIN_RESPONSE_MS=2592000000
 # 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
-# Collect stored bodies no channel holds and no derivation indexes (1), or keep them (0)
-# ({§content-store}).
+# Collect unreferenced text and native bodies (1), or keep them (0).
+# Retained messages, operations and packet attachments pin native bytes ({§native-content-lifetime}).
 PLURNK_SERVICE_COLLECT_CONTENTS=1
 # Retention cadence while the daemon runs, ms; 0 = at shutdown only.
 PLURNK_SERVICE_RETENTION_INTERVAL_MS=3600000

package/INSTALL.md

@@ -79,6 +79,25 @@ sidecars together. Copy the backup to a fresh working path, select that path wit
 `PLURNK_SERVICE_DB_PATH`, and start the same or a newer compatible service version.
 Do not overwrite a live database or pair a restored file with old sidecars.
 
+| Restored input | Startup behaviour |
+| --- | --- |
+| Database | Retained history, approval decisions, attachments and workspace/worker configuration return. Interrupted work is settled without replaying uncertain effects ({§worker-lifecycle-restart-recovery}). |
+| Project files and service configuration | Restore separately. Current files remain authoritative; startup reads the current configuration, not an earlier ambient environment captured in history. |
+| Schedules | Enabled definitions rearm from the present; missed occurrences are not replayed ({§schedule-residency}, {§schedule-first-arming}). |
+| Interactive MCP authorization | Reauthorize. Tokens and pending sign-ins are process-local, not part of the database backup ({§oauth-lifetime}). |
+
+Retention controls expire packet compositions and call payloads, including physical-request
+captures. Messages, turn sources, operation receipts, approval decisions and request accounting
+remain with their containing history ({§retention-policy}); referenced attachment bytes remain
+too ({§native-content-lifetime}). This is not content erasure. A share contains only what remains
+when it is taken.
+
+`PLURNK_SERVICE_SQLITE_SYNCHRONOUS` selects the database's WAL durability before migrations
+or startup writes. Its shipped setting is in `.env.defaults`. `FULL` synchronizes every commit
+to storage; selecting `NORMAL` explicitly trades power-loss durability for fewer synchronizations.
+The guarantees and storage assumptions are defined in {§db-durability}. Neither setting makes
+project-file writes transactional or replaces backups.
+
 ## Precedence
 
 Highest priority first ({§operator-config-precedence}):
@@ -125,7 +144,7 @@ outside the package.
 | --- | --- |
 | Startup defaults or installed extension configuration | The daemon's environment cascade. A remote client's shell does not change it. |
 | Model, reasoning, child model | Worker selections persist. Set them through client controls; changing a startup default does not retarget an existing Worker. |
-| MCPs, skills, outbound agents, schedules, membership | Workspace Functionality: list, discover, add, enable, disable, remove. Workers share the workspace's current selection. |
+| MCPs, skills, outbound agents, schedules, membership | Workspace Functionality: list, discover, add, replace, enable, disable, remove. Workers share the workspace's current selection. |
 | Command environment | `env` manages worker overrides or workspace defaults. It does not reconfigure the daemon; running processes keep their launch environment. |
 | External capabilities | Service policy is a ceiling; workspace policy can narrow it for every worker. Hiding a doc does not grant or revoke authority. |
 | Proposal review / YOLO | Decides who accepts or rejects an admitted operation. Automatic acceptance never overrides capability or resource permissions. |