@plurnk/plurnk-execs-common 1.20.0 → 1.21.1

package/.env.defaults

@@ -0,0 +1,11 @@
+# @plurnk/plurnk-execs-common — secondary interpreters are opt-in.
+# Set a runtime to 1 to register it; its interpreter must also be on PATH.
+# sh, node, and python3 remain enabled through the executor framework's default.
+PLURNK_EXECS_PERL=0
+PLURNK_EXECS_RUBY=0
+PLURNK_EXECS_LUA=0
+PLURNK_EXECS_DENO=0
+PLURNK_EXECS_BUN=0
+PLURNK_EXECS_TCL=0
+PLURNK_EXECS_BC=0
+PLURNK_EXECS_AWK=0

package/.env.example

@@ -1,15 +1,13 @@
 # @plurnk/plurnk-execs-common — environment
 
-# Operator kill-switch per runtime tag. Set to 0 (or false) to disable a tag
-# even when its interpreter is installed on the host. Absent = enabled (the tag
-# is offered when its binary is on PATH). Disabling drops it from the model's
-# available-runtimes list with a "disabled" reason on the 501.
-#
-# PLURNK_EXECS_PERL=0
-# PLURNK_EXECS_RUBY=0
-# PLURNK_EXECS_LUA=0
-# PLURNK_EXECS_DENO=0
-# PLURNK_EXECS_BUN=0
-# PLURNK_EXECS_TCL=0
-# PLURNK_EXECS_BC=0
-# PLURNK_EXECS_AWK=0
+# sh, node, and python3 are enabled when their interpreter is available.
+# Uncomment any optional runtime to enable it at the next service start.
+# An enabled runtime still requires its interpreter on PATH.
+# PLURNK_EXECS_PERL=1
+# PLURNK_EXECS_RUBY=1
+# PLURNK_EXECS_LUA=1
+# PLURNK_EXECS_DENO=1
+# PLURNK_EXECS_BUN=1
+# PLURNK_EXECS_TCL=1
+# PLURNK_EXECS_BC=1
+# PLURNK_EXECS_AWK=1

package/README.md

@@ -2,8 +2,8 @@
 
 The **universal subprocess executor** for
 [plurnk-service](https://github.com/plurnk/plurnk-service)'s `exec` scheme. One
-package covers the shell, Node.js, Python 3, and whichever supported host
-interpreters are present. Node is guaranteed; the rest are detected.
+package offers the shell, Node.js, and Python 3 by default, with other supported
+host interpreters available as opt-ins. Node is guaranteed; the rest are detected.
 
 A `@plurnk/plurnk-execs-*` sibling built on the [plurnk-execs](https://github.com/plurnk/plurnk-service/tree/main/plurnk-execs) framework.
 
@@ -25,7 +25,7 @@ detects every other interpreter, so one executor adapts to the host.
 | `bc` 🧮                          | bc                | stdin (for example, `6 * 7`)             |
 | `awk` 🪄                         | awk               | program arg, empty stdin (`BEGIN { … }`) |
 
-Each runtime's catalog Summary includes a short executable inline body, with
+Each enabled runtime's catalog Summary includes a short executable inline body, with
 literal `\n` separators keeping the invocation on one discovery line.
 
 ### A script — the `(target)` slot
@@ -37,19 +37,19 @@ selects the working directory. Script arguments use `[{"args": ["arg",...]}]`;
 each string is passed literally, without shell expansion ({§executor-metadata}).
 These options work for local, Worker, and Skill script targets alike.
 
-````sh (./deploy.sh)
+```sh (./deploy.sh)
 yes
 yes
 no
-````
+```
 
-````python3 (transform.py) [{"args": ["--format","json"]}]
+```python3 (transform.py) [{"args": ["--format","json"]}]
 3
 1
 4
 1
 5
-````
+```
 
 The first operation answers a shell script's prompts through stdin. The second
 feeds records to a Python script.
@@ -62,6 +62,13 @@ separate input channel; script targets receive stdin from the body.
 
 ## Configuration
 
+The shipped [`.env.defaults`](./.env.defaults) disables `perl`, `ruby`, `lua`,
+`deno`, `bun`, `tcl`, `bc`, and `awk`. To expose one, set its switch to `1`
+in the ordinary environment cascade and restart the service; commented opt-ins
+are in [`.env.example`](./.env.example). For example, `PLURNK_EXECS_PERL=1`
+enables the Perl executor when Perl is installed. These switches do not prevent
+calling an interpreter through `sh`.
+
 Per-tag kill-switches (`PLURNK_EXECS_<TAG>=0`) and the
 `PLURNK_EXECS_ONLY` allowlist are honored by framework discovery, uniformly
 across every plugin ({§executor-policy}). A disabled tag is not registered and

package/docs/awk.md

@@ -1,30 +1,21 @@
 # awk
 
-For continuing input, launch with `[{"stdin": "open"}]`, then SEND exact text to the
-returned execution address; `[{"eof": true}]` closes stdin. See the
-[live-input example](node.md#live-input), including newline framing.
-
 The body is the AWK program, passed as the one positional argument with an
-empty stdin: with no input file it only runs `BEGIN` blocks. To process data,
-name the file(s) in `[{"args": [...]}]`, or run a script target and feed it the body
-as stdin.
+empty stdin: with no input file it only runs `BEGIN` blocks. Input files are
+named in `[{"args": [...]}]`; a script target runs that file and receives the
+body as stdin. Working directory, environment, channels and exit status are the
+executor family's (`sh.md`); `exit 1` in the program closes with status 500.
 
-````awk [{"args": ["data.csv"]}] <!-- the body is the program -->
+```awk [{"args": ["data.csv"]}] <!-- the body is the program -->
 BEGIN { FS = "," }
 NR > 1 { total += $3 }
 END { printf "rows=%d total=%.2f\n", NR - 1, total }
-````
+```
 
-````awk (tools/summarize.awk) <!-- the script runs; the body is its stdin -->
+```awk (tools/summarize.awk) <!-- the script runs; the body is its stdin -->
 alpha,1
 beta,2
-````
-
-Output goes to `#stdout`, diagnostics to `#stderr`; `exit 1` in the program
-closes with status 500. `[{"cwd": "<directory>"}]` selects the working directory
-for relative file arguments. AWK is the right tool for column arithmetic and
-line reshaping over text; for JSON use `jq`, for anything else `node` or `sh`.
+```
 
-`[{"env": {"NAME": "value"}}]` on the same fence line sets variables for this run
-alone, over the entries in your `env` registry; names are the shell's, and plurnk's own
-(`PLURNK_*`, provider credentials) are refused by name.
+Live input (`[{"stdin": "open"}]`, SEND, `[{"eof": true}]`) is as `node.md`
+shows.

package/docs/bc.md

@@ -1,22 +1,17 @@
 # bc
 
-For continuing input, launch with `[{"stdin": "open"}]`, then SEND exact text to the
-returned execution address; `[{"eof": true}]` closes stdin. See the
-[live-input example](node.md#live-input), including newline framing.
+The body is a `bc` program fed on stdin (a trailing newline is added, so the
+last line evaluates). Arbitrary precision: `scale` is set before dividing, or
+every quotient is truncated to an integer.
 
-The body is a `bc` program fed on stdin (a trailing newline is added, so the last
-line evaluates). Arbitrary precision: set `scale` before dividing, or every
-quotient is truncated to an integer.
-
-````bc <!-- the body is the program -->
+```bc <!-- the body is the program -->
 scale=6
 22/7
 2^64
-````
+```
 
 Each expression prints its value on its own line to `#stdout`; `#stderr`
-carries parse errors such as `syntax error`. The exit status is 0 even when
-a line failed to parse, so read `#stderr` when a result is missing. A script
-target (`bc (rates.bc)`) runs that file with the body as stdin.
-Use bc for exact decimal or big-integer arithmetic; for anything with strings,
-loops over data, or JSON, reach for `awk`, `node`, or `sh`.
+carries parse errors such as `syntax error`, and the exit status is 0 even when
+a line failed to parse, so a missing result is explained on `#stderr`. A script
+target (`bc (rates.bc)`) runs that file with the body as stdin. Live input
+(`[{"stdin": "open"}]`, SEND, `[{"eof": true}]`) is as `node.md` shows.

package/docs/bun.md

@@ -1,22 +1,18 @@
 # bun
 
-For continuing input, launch with `[{"stdin": "open"}]`, then SEND exact text to the
-returned execution address; `[{"eof": true}]` closes stdin. See the
-[live-input example](node.md#live-input), including newline framing.
-
 The body is TypeScript or JavaScript, run with `bun -e`. A script target runs
 that file and receives the body as stdin; `[{"args": [...]}]` passes literal
-arguments, readable as `Bun.argv` or `process.argv`.
+arguments, readable as `Bun.argv` or `process.argv`. Node is always present;
+bun only when the host has it.
 
-````bun <!-- the body is the program -->
+```bun <!-- the body is the program -->
 const file = Bun.file("package.json");
 console.log((await file.json()).name);
-````
+```
 
-````bun (scripts/build.ts) [{"args": ["--watch=false"]}]
-````
+```bun (scripts/build.ts) [{"args": ["--watch=false"]}]
+```
 
 `console.log` streams to `#stdout`, `console.error` to `#stderr`; an uncaught
-error or `process.exit(1)` closes with status 500. Prefer `node` unless the
-project is a Bun project: node is always present, bun only when the host
-has it.
+error or `process.exit(1)` closes with status 500. Live input
+(`[{"stdin": "open"}]`, SEND, `[{"eof": true}]`) is as `node.md` shows.

package/docs/deno.md

@@ -1,23 +1,19 @@
 # deno
 
-For continuing input, launch with `[{"stdin": "open"}]`, then SEND exact text to the
-returned execution address; `[{"eof": true}]` closes stdin. See the
-[live-input example](node.md#live-input), including newline framing.
-
 The body is TypeScript or JavaScript, run with `deno eval` (permissions are
-Deno's defaults for `eval`; import what you need from the project or a URL).
-A script target runs that file and receives the body as stdin;
-`[{"args": [...]}]` passes literal arguments, readable as `Deno.args`.
+Deno's defaults for `eval`; imports come from the project or a URL). A script
+target runs that file and receives the body as stdin; `[{"args": [...]}]` passes
+literal arguments, readable as `Deno.args`. Node is always present; deno only
+when the host has it.
 
-````deno <!-- the body is the program -->
+```deno <!-- the body is the program -->
 const versions: Record<string, string> = Deno.version;
 console.log(JSON.stringify(versions));
-````
+```
 
-````deno (scripts/check.ts) [{"args": ["--strict"]}]
-````
+```deno (scripts/check.ts) [{"args": ["--strict"]}]
+```
 
 `console.log` streams to `#stdout`, `console.error` to `#stderr`; an uncaught
-error or `Deno.exit(1)` closes with status 500. Prefer `node` when the task
-does not need Deno specifically: node is always present, deno only when the
-host has it.
+error or `Deno.exit(1)` closes with status 500. Live input
+(`[{"stdin": "open"}]`, SEND, `[{"eof": true}]`) is as `node.md` shows.

package/docs/lua.md

@@ -1,23 +1,20 @@
 # lua
 
-For continuing input, launch with `[{"stdin": "open"}]`, then SEND exact text to the
-returned execution address; `[{"eof": true}]` closes stdin. See the
-[live-input example](node.md#live-input), including newline framing.
-
 The body is Lua code, run with `lua -e`. A script target runs that file and
-receives the body as stdin; `[{"args": [...]}]` passes literal script arguments,
-readable through the `arg` table.
+receives the body as stdin; `[{"args": [...]}]` passes literal script
+arguments, readable through the `arg` table.
 
-````lua <!-- the body is the program -->
+```lua <!-- the body is the program -->
 local t = { 3, 1, 2 }
 table.sort(t)
 print(table.concat(t, ","))
-````
+```
 
-````lua (scripts/lint.lua) [{"args": ["src/main.lua"]}]
-````
+```lua (scripts/lint.lua) [{"args": ["src/main.lua"]}]
+```
 
-`print` streams to `#stdout`, `io.stderr:write` to `#stderr`; `error(...)`
-or `os.exit(1)` closes with status 500. The standalone interpreter is the
-host's `lua` on PATH; project modules resolve through its ordinary
-`package.path` from the working directory.
+`print` streams to `#stdout`, `io.stderr:write` to `#stderr`; `error(...)` or
+`os.exit(1)` closes with status 500. The standalone interpreter is the host's
+`lua` on PATH; project modules resolve through its ordinary `package.path` from
+the working directory. Live input (`[{"stdin": "open"}]`, SEND,
+`[{"eof": true}]`) is as `node.md` shows.

package/docs/node.md

@@ -1,64 +1,44 @@
 # node
 
-A JavaScript snippet, run via `node -e`. Node is the daemon's own runtime, so it's always available (no PATH probe).
+A JavaScript snippet, run via `node -e`. Node is the daemon's own runtime, so it
+is always available (no PATH probe).
 
-````node <!-- the body is the snippet -->
+```node <!-- the body is the snippet -->
 const os = require("node:os");
 console.log(JSON.stringify({ platform: os.platform(), cpus: os.cpus().length }));
-````
+```
+
+`node (tool.js)` runs that JavaScript file and receives the body as stdin;
+`[{"args": ["--format","json"]}]` passes literal script arguments, also for
+`worker://` and `skill://` targets. Relative imports resolve from the script;
+ordinary relative filesystem paths resolve from the working directory.
+Environment, working directory, channels, first page, exit status and lifetime
+are the executor family's, as `sh.md` states. Stdout is text, so structured
+output is serialized (`console.log(JSON.stringify(value))`); a thrown error
+exits nonzero (status 500) with its stack on stderr.
 
 ## Live input
 
 `[{"stdin": "open"}]` keeps stdin open for later SENDs to the receipt's execution
 address. Without it, initial input ends with EOF as usual.
 
-````node [{"stdin": "open"}]
+```node [{"stdin": "open"}]
 process.stdin.on("data", chunk => process.stdout.write(chunk));
-````
+```
 
 Using the address returned by that invocation (here `node:///ab3d5678`):
 
-````SEND (node:///ab3d5678)
+```SEND (node:///ab3d5678)
 hello
 
-````
+```
 
 The blank line before the closing fence supplies a newline after `hello`.
 SEND adds no newline of its own. Its receipt acknowledges pipe delivery, not
 program completion. READ that same address to inspect stdout while it runs.
 
-````SEND (node:///ab3d5678) [{"eof": true}]
-````
+```SEND (node:///ab3d5678) [{"eof": true}]
+```
 
 EOF closes stdin, not the process. KILL terminates the execution. Any worker
 in the workspace can send input to the same execution address.
-
-## Environment
-
-The same scoped environment as `sh`: the daemon's own secrets (`PLURNK_*`, provider keys) are stripped, so `process.env` inside the snippet sees the project's environment, not plurnk's.
-
-## Output
-
-Whatever the snippet writes to stdout streams to `#stdout`; stderr streams to
-`#stderr`. Both are text under the receipt's `stream` address, such as
-`node:///ab3d5678`. On completion, the harness adds a READ of each channel's
-first page (up to 16 lines). READ the stream address for additional lines;
-the log READ holds only its recorded page. To return structured data, use
-`console.log(JSON.stringify(value))`. A thrown error exits nonzero (status 500)
-with its stack on stderr. The receipt's own body is the snippet as you sent
-it, never output; a non-200 receipt with no `stream` address ran nothing.
-
-## Working directory
-
-Runs in the workspace project root by default, or the daemon's own cwd in a
-workspace without one; a `[{"cwd": "<directory>"}]` block on the opening fence line selects
-another. The target is a script, never a command or a directory:
-`node (tool.js)` runs that JavaScript file and receives the body as
-stdin. `[{"args": ["--format","json"]}]` passes literal script arguments, also for
-`worker://` and `skill://` targets. Relative imports resolve from the script;
-ordinary relative filesystem paths resolve from cwd. The receipt names cwd
-when it differs from the project root.
-
-`[{"env": {"NAME": "value"}}]` on the same fence line sets variables for this run
-alone, over the entries in your `env` registry; names are the shell's, and plurnk's own
-(`PLURNK_*`, provider credentials) are refused by name.

package/docs/perl.md

@@ -1,23 +1,19 @@
 # perl
 
-For continuing input, launch with `[{"stdin": "open"}]`, then SEND exact text to the
-returned execution address; `[{"eof": true}]` closes stdin. See the
-[live-input example](node.md#live-input), including newline framing.
+The body is Perl code, run with `perl -e`; `-n`/`-p` have no equivalent here,
+so a line loop is written in the body. A script target runs that file and
+receives the body as stdin; `[{"args": [...]}]` passes literal arguments.
+Environment, channels and exit status are the executor family's (`sh.md`):
+`die` or a nonzero `exit` closes with status 500.
 
-The body is Perl code, run with `perl -e`. A script target runs that file and
-receives the body as stdin; `[{"args": [...]}]` passes literal script arguments.
-
-````perl <!-- the body is the program -->
+```perl <!-- the body is the program -->
 use strict; use warnings;
 my %count; $count{$_}++ for qw(a b a c a);
 printf "%s=%d\n", $_, $count{$_} for sort keys %count;
-````
+```
 
-````perl (tools/rename.pl) [{"args": ["--dry-run"]}]
-````
+```perl (tools/rename.pl) [{"args": ["--dry-run"]}]
+```
 
-stdout streams to `#stdout`, stderr to `#stderr`; `die` or a nonzero `exit`
-closes with status 500. The environment is scoped exactly as for `sh`
-(plurnk's own settings and provider keys are stripped). Use `-n`/`-p`-style
-one-liners by writing the loop yourself, or run a script target over the
-files you name in `{args}`.
+Live input (`[{"stdin": "open"}]`, SEND, `[{"eof": true}]`) is as `node.md`
+shows.

package/docs/python3.md

@@ -1,26 +1,18 @@
 # python3
 
-For continuing input, launch with `[{"stdin": "open"}]`, then SEND exact text to the
-returned execution address; `[{"eof": true}]` closes stdin. See the
-[live-input example](node.md#live-input), including newline framing.
-
 The body is Python code, run with `python3 -c`. A script target instead runs
-that file and receives the body as stdin. Script arguments and working directory
-are optional header metadata:
+that file and receives the body as stdin; `[{"args": [...]}]` passes literal
+arguments and `[{"cwd": "<directory>"}]` selects the working directory, as for
+every interpreter (`sh.md`).
 
-````python3 <!-- the body is the program -->
+```python3 <!-- the body is the program -->
 import json, sys
 print(json.dumps({"python": list(sys.version_info[:2])}))
-````
-
-````python3 (tools/report.py) [{"args": ["--help"]}]
-````
+```
 
-Each argument is a literal string, without shell expansion. `[{"cwd": "<directory>"}]`
-selects the working directory; otherwise it remains the workspace root. The
-same options apply to local and `worker://` script targets. Native skill files
-retain their sibling imports and source-relative assets.
+```python3 (tools/report.py) [{"args": ["--help"]}]
+```
 
-`[{"env": {"NAME": "value"}}]` on the same fence line sets variables for this run
-alone, over the entries in your `env` registry; names are the shell's, and plurnk's own
-(`PLURNK_*`, provider credentials) are refused by name.
+Native skill files retain their sibling imports and source-relative assets.
+Live input (`[{"stdin": "open"}]`, SEND, `[{"eof": true}]`) is as `node.md`
+shows.

package/docs/ruby.md

@@ -1,26 +1,20 @@
 # ruby
 
-For continuing input, launch with `[{"stdin": "open"}]`, then SEND exact text to the
-returned execution address; `[{"eof": true}]` closes stdin. See the
-[live-input example](node.md#live-input), including newline framing.
-
 The body is Ruby code, run with `ruby -e`. A script target runs that file and
 receives the body as stdin; `[{"args": [...]}]` passes literal `ARGV` entries.
 
-````ruby <!-- the body is the program -->
+```ruby <!-- the body is the program -->
 require "json"
 words = %w[alpha beta alpha]
 puts JSON.generate(words.tally)
-````
+```
 
-````ruby (bin/migrate.rb) [{"args": ["--check"]}]
-````
+```ruby (bin/migrate.rb) [{"args": ["--check"]}]
+```
 
 `puts` and `print` stream to `#stdout`, `warn` to `#stderr`; an unrescued
-exception or `exit 1` closes with status 500 with the backtrace on stderr.
-Gems resolve from the project's ordinary Ruby environment; `[{"cwd": "<directory>"}]`
+exception or `exit 1` closes with status 500 with the backtrace on stderr. Gems
+resolve from the project's ordinary Ruby environment; `[{"cwd": "<directory>"}]`
 selects the working directory when the project's `Gemfile` lives elsewhere.
-
-`[{"env": {"NAME": "value"}}]` on the same fence line sets variables for this run
-alone, over the entries in your `env` registry; names are the shell's, and plurnk's own
-(`PLURNK_*`, provider credentials) are refused by name.
+Environment metadata is the executor family's (`sh.md`). Live input
+(`[{"stdin": "open"}]`, SEND, `[{"eof": true}]`) is as `node.md` shows.

package/docs/sh.md

@@ -1,92 +1,77 @@
 # sh
 
-For continuing input, launch with `[{"stdin": "open"}]`, then SEND exact text to the
-returned execution address; `[{"eof": true}]` closes stdin. See the
-[live-input example](node.md#live-input), including newline framing.
-
 The `sh` fence runs the body via `sh -c`, character-perfect including whitespace.
 
-````sh <!-- the body is the script itself -->
+```sh <!-- the body is the script itself -->
 printf 'hello\n' > hello.txt
 wc -l hello.txt
-````
+```
+
+A script target runs that script: `sh (greet.sh)` runs it with an empty stdin;
+a nonempty body becomes its stdin. The interpreter reads the script directly,
+so it needs no executable bit; a script path authored inside a shell body still
+follows the kernel's ordinary executable-bit rules. Script arguments go in
+`[{"args": ["--release","two words"]}]`: each string is one literal argument,
+without shell expansion. The target is a program, never a command and never a
+directory; a target that is not a script is refused before anything runs. The
+same options apply to local, `worker://`, and `skill://` script targets across
+every interpreter.
 
 ## Environment
 
-The command receives a **scoped** environment. Provider keys and every
-`PLURNK_*` setting are stripped before the child starts, so `printenv` cannot
-read plurnk's credentials. The project's environment passes through.
+The command receives a scoped environment: provider keys and every `PLURNK_*`
+setting are stripped before the child starts, so `printenv` cannot read
+plurnk's credentials, and the project's environment passes through.
+`[{"env": {"LC_ALL": "C"}}]` on the fence line sets variables for this run
+alone, over the entries in the `env` registry (`env.md`); plurnk's own names
+are refused by name.
 
 ## Working directory
 
-The working directory is the workspace project root — where file operations
-write — or, in a workspace without one, the directory the shell would run in
-anyway. A `[{"cwd": "<directory>"}]` block on the opening fence line overrides it for its body:
-
-````sh [{"cwd": "./dir"}]
-pwd
-````
-
-The receipt always names the directory the command ran in.
-
-`env` on the same line sets variables for this run alone, over the entries in
-your `env` registry; plurnk's own names (`PLURNK_*`, provider credentials) are
-refused by name:
-
-````sh [{"env": {"LC_ALL": "C"}}]
-sort names.txt
-````
-
-A script target runs that script: `sh (greet.sh)` runs it with an empty
-stdin; a nonempty body becomes its stdin. The interpreter reads the script
-directly, so it needs no executable bit; a script path authored inside a shell
-body still follows the kernel's ordinary executable-bit rules.
-
-Script arguments go in `[{"args": ["--release","two words"]}]`: each string is
-one literal argument, without shell expansion. The same options apply to
-local, `worker://`, and `skill://` script targets across the common interpreters.
-
-The target is a program — a script — never a command and never a directory. A
-target that is not a script is refused before anything runs.
+The working directory is the workspace project root, or in a workspace without
+one the directory the shell would run in anyway. `[{"cwd": "<directory>"}]` on
+the fence line overrides it for its body; the receipt always names the
+directory the command ran in.
 
 ## Channels
 
-Every shell invocation is host-effecting and proposes for review before it
-runs. Output then streams under the receipt's `stream` address, such as
-`sh:///ab3d5678`: `#stdout` is the default channel and
-`#stderr` is the second; both are `text/stream`. While it runs, the packet's
-`## Delegation` streams list reports each channel's size and growth and READ can
-inspect any range. On
-completion, the harness adds one `_plurnk` READ per channel: its first page
-(up to 16 lines), `range` extent, and terminal exit status. READ that observation's
-`path` for more; the `log:///…/READ` item holds only its recorded page:
-
-````READ (sh:///ab3d5678#stdout) <17,40>
-````
+An execution is a host effect, admitted under the loop's policy. Output streams
+under the receipt's `stream` address, such as `sh:///ab3d5678`: `#stdout` is
+the default channel and `#stderr` the second; both are `text/stream`. While it
+runs, the packet's `## Delegation` streams list reports each channel's size and
+growth, and READ can inspect any range. On completion, the harness adds one
+`_plurnk` READ per channel: its first page, `range` extent, and terminal exit
+status. READ the observation's `path` for more; the `log:///…/READ` item holds
+only its recorded page:
 
-A nonzero exit closes with status 500; inspect both channels because either
-may carry the useful diagnostic.
+```READ (sh:///ab3d5678#stdout) <17,40>
+```
 
-The `log:///…/sh` receipt's own body is the program exactly as you sent it,
-never output: output lives on the stream and in the harness READs. A receipt
-with a non-200 status and no `stream` address ran nothing; its body is still
-your program, and its Problem says why it was refused.
+A nonzero exit closes with status 500; stdout and stderr are separate channels,
+and a diagnostic may be on either. The `log:///…/sh` receipt's own body is the
+program exactly as sent, never output. A receipt with a non-200 status and no
+`stream` address ran nothing; its body is still the program, and its Problem
+says why it was refused.
 
 ## Lifetime
 
 How long a command may run is one metadata field; absent, it ends with the loop.
 
-````sh [{"lifetime": "30m"}]
+```sh [{"lifetime": "30m"}]
 npm run e2e
-````
+```
 
-````sh [{"lifetime": "detached"}]
+```sh [{"lifetime": "detached"}]
 npm run dev
-````
+```
 
 A duration (`30s`, `30m`, `2h`) kills the command at that deadline. `detached`
-outlives the loop — it runs until it exits or you KILL it, so a server you must
-leave running takes it. `turn` keeps the command only through the current turn.
-While you wait on a stream, the service wakes you to inspect it; you never ask
-for that, and you never poll from inside a loop. To act again later with nothing
-in flight, add a rule with the `schedule` family targeting yourself.
+outlives the loop: it runs until it exits or is KILLed. `turn` keeps the command
+only through the current turn. While a stream is live, observation wakes arrive
+on the daemon's cadence and present it for inspection.
+
+## Live input
+
+`[{"stdin": "open"}]` keeps stdin open for later SENDs to the returned execution
+address; `[{"eof": true}]` closes it. The worked example, including newline
+framing, is on `node.md`.

package/docs/tcl.md

@@ -1,23 +1,20 @@
 # tcl
 
-For continuing input, launch with `[{"stdin": "open"}]`, then SEND exact text to the
-returned execution address; `[{"eof": true}]` closes stdin. See the
-[live-input example](node.md#live-input), including newline framing.
-
 The body is a Tcl script fed to `tclsh` on stdin (a trailing newline is added).
-A script target runs that file and receives the body as stdin; `[{"args": [...]}]`
-passes literal arguments, readable as `$argv`.
+A script target runs that file and receives the body as stdin;
+`[{"args": [...]}]` passes literal arguments, readable as `$argv`.
 
-````tcl <!-- the body is the program -->
+```tcl <!-- the body is the program -->
 set words {alpha beta alpha}
 foreach w $words { dict incr count $w }
 puts [dict get $count alpha]
-````
+```
 
-````tcl (tests/all.tcl) [{"args": ["-verbose","bps"]}]
-````
+```tcl (tests/all.tcl) [{"args": ["-verbose","bps"]}]
+```
 
 `puts` streams to `#stdout`, `puts stderr ...` to `#stderr`; an uncaught error
 or `exit 1` closes with status 500 with the Tcl error info on stderr. tclsh
 evaluates the script line by line, so an incomplete command at the end is an
-error, not a silent no-op.
+error, not a silent no-op. Live input (`[{"stdin": "open"}]`, SEND,
+`[{"eof": true}]`) is as `node.md` shows.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plurnk/plurnk-execs-common",
-  "version": "1.20.0",
+  "version": "1.21.1",
   "description": "Universal subprocess executor for plurnk-service's exec scheme — one package exposing the shell, Node.js, Python 3, and supported host interpreters.",
   "keywords": [
     "plurnk",
@@ -255,12 +255,13 @@
   "files": [
     "dist/**/*",
     "README.md",
+    ".env.defaults",
     ".env.example",
     "docs/**/*"
   ],
   "scripts": {
     "test:lint": "tsc --noEmit",
-    "test:unit": "node --conditions=plurnk-dev --env-file-if-exists=../plurnk-execs/.env.defaults --test \"src/**/*.test.ts\"",
+    "test:unit": "node --conditions=plurnk-dev --env-file-if-exists=.env.defaults --env-file-if-exists=../plurnk-execs/.env.defaults --test \"src/**/*.test.ts\"",
     "test": "npm run test:lint && npm run test:unit",
     "build:clean": "rm -rf dist",
     "build:dist": "tsc -p tsconfig.build.json",
@@ -269,6 +270,6 @@
     "prepublishOnly": "npm audit --audit-level=moderate && npm test"
   },
   "peerDependencies": {
-    "@plurnk/plurnk-execs": "^1.20.0"
+    "@plurnk/plurnk-execs": "^1.21.1"
   }
 }