@plurnk/plurnk-execs 0.3.0 → 0.4.1

package/README.md

@@ -9,10 +9,10 @@ Framework + contract for `@plurnk/plurnk-execs-*` runtime executor packages. Con
 
 ## Exports
 
-- `BaseExecutor` — abstract base a `@plurnk/plurnk-execs-*` sibling subclasses: declares its output channels and implements `run(args) → ExecResult`.
-- `SubprocessExecutor` — concrete `BaseExecutor` for subprocess runtimes (sh/node/python): spawns via `resolveRuntime`, streams stdout/stderr, honors cancellation, reports exit code. Siblings subclass it.
+- `BaseExecutor` — abstract base a `@plurnk/plurnk-execs-*` sibling subclasses: declares its output channels, implements `run(args) → ExecResult`, and optionally overrides `probe()` (env availability) and `effect(target)` (proposal gating).
+- `SubprocessExecutor` — concrete `BaseExecutor` for subprocess runtimes (sh/node/python): spawns via `resolveRuntime`, streams stdout/stderr, honors cancellation (process-group kill on abort), reports exit code, probes its `binary`. Siblings subclass it.
 - `discover(options?)` — scans `node_modules/@plurnk/` for `plurnk.kind === "exec"` packages and builds the runtime-tag registry (fail-hard on tag collision).
-- `ExecArgs`, `ExecResult`, `ChannelDecl`, `ChannelState`, `ExecutorMetadata`, `ExecInfo`, `ExecRegistry`, `Discovery`, `DiscoverOptions` — contract types.
+- `ExecArgs`, `ExecResult`, `ChannelDecl`, `ChannelState`, `ExecutorMetadata`, `RuntimeAvailability`, `Effect`, `ExecInfo`, `ExecRegistry`, `Discovery`, `DiscoverOptions` — contract types.
 - `TelemetryEvent`, `ContentOffset`, `LogCoordinate` — local mirror of grammar's telemetry envelope (the `emit` sink's payload).
 - `resolveRuntime(runtime, command)`, `isKnownRuntime(runtime)`, `KNOWN_RUNTIMES`, `SpawnArgs`, `RuntimeResolver` — subprocess-family helper for the consumer's legacy spawn path (§4).
 

package/SPEC.md

@@ -6,7 +6,7 @@ Contract for `@plurnk/plurnk-execs-*` sibling packages — runtime executors tha
 
 A runtime executor handles one or more EXEC `runtime` slot values (`sh`, `node`, `python`, `search`, `news`, …). It is a `BaseExecutor` subclass that declares its output channels and implements `run()`; the framework discovers it from its `package.json` `plurnk` block. The consuming scheme owns all I/O and lifecycle machinery (db, channels, subscriptions, AbortController bridging, wake-on-completion) and hands the executor sinks — the executor stays stateless across runs beyond its construction metadata.
 
-The framework ships `SubprocessExecutor` (§4), the concrete `BaseExecutor` for subprocess runtimes (sh/node/python). plurnk-service's exec scheme still consumes the lower-level `resolveRuntime` / `SpawnArgs` helper on its legacy `streamShellCommand` path; its migration onto `SubprocessExecutor` is phased and on service's own timeline (plurnk-service#174 Q2). Both paths coexist until that cutover.
+The framework ships `SubprocessExecutor` (§4), the concrete `BaseExecutor` for subprocess runtimes (sh/node/python), built on the lower-level `resolveRuntime` / `SpawnArgs` helper. plurnk-service's exec scheme has adopted `SubprocessExecutor`; the discovery-registry + `probe()`/`effect()` consumption is realized in service `0.9.0` (`ExecutorRegistry` boot-discovers and probes siblings; `EffectPolicy` gates the proposal lifecycle).
 
 ## §2 Executor contract
 
@@ -63,12 +63,32 @@ abstract class BaseExecutor {
 
 Consumer contract (plurnk-service#181): probe **once at boot, per package** (not per tag — stamp all of a package's tags with the one result), **concurrently under a per-probe timeout**, and **cache**. `probe()` MAY reject; the consumer treats rejection as `{ available: false, detail: <error> }`, so a buggy probe degrades only its runtime. The model is offered a positive list of available runtimes; an attempt at an unavailable one returns **501 carrying `detail`** (so `detail` is model-facing — terse and actionable). A configured default runtime that probes unavailable is a **fail-hard boot error**.
 
-### §2.3 Telemetry
+### §2.3 Effect (proposal gating)
+
+```ts
+type Effect = "pure" | "read" | "host";
+
+abstract class BaseExecutor {
+    effect(target: string | null): Effect { return "host"; }  // default: conservative
+}
+```
+
+`effect()` classifies an invocation's side effect so the consumer can gate the proposal lifecycle per runtime (service#182). The executor declares the **fact**; the consumer owns the **policy** (an `effect → propose/auto` map, deployment-tunable: default `host → propose`, `read`/`pure → auto`).
+
+- **`host`** — runs code / mutates the host (subprocess; file-backed sqlite) → propose.
+- **`read`** — observes external state, no host mutation (search) → auto.
+- **`pure`** — no observable side effect (sqlite `:memory:`, transforms) → auto.
+
+`effect()` MUST be **pure, synchronous, and cheap** — it runs on the dispatch hot path at propose time. It classifies the **target only** (known pre-`run()`); it MUST NOT inspect the command (parsing SQL/shell to judge intent is a sandbox-escape footgun) and MUST NOT do I/O. Default `host` is conservative — anything unclassifiable is proposed (fail-safe, the mirror of `probe()`'s fail-open default).
+
+For `exec`, per-runtime `effect()` supersedes the static `Exec.manifest.flags.proposes`. Auto-run (`read`/`pure`) runtimes may run **inline** — synchronous return rather than entry-then-read-next-turn — while still landing the result as a re-readable entry.
+
+### §2.4 Telemetry
 
 Runtime failures are emitted as a grammar `TelemetryEvent` via the `emit` sink (plurnk-service#174 Q3); the scheme routes it to the engine's telemetry buffer — the same path grammar's `parse_error` takes. Events are not encoded into `stderr` (that pollutes program output) nor returned on `ExecResult` (that loses mid-run events).
 
 - `source`: `"exec:<runtime>"` (e.g. `"exec:search"`) or `"scheme:exec"`.
-- `kind`: producer-minted — `runtime_not_configured`, `spawn_failed`, `exited_nonzero`, `aborted`, and runtime-specific kinds (search: `searxng_unreachable`, `searxng_http_<n>`).
+- `kind`: producer-minted, open vocabulary. What the shipped executors actually emit: `SubprocessExecutor` → `spawn_failed` (a failed *start*; a nonzero exit is the program's own result and stays on `stderr`, **not** telemetered); search → `searxng_not_configured` / `searxng_unreachable` / `searxng_timeout` / `searxng_http_<n>` / `external_bang_refused`; sqlite → `sqlite_open_failed` / `sqlite_error`. A cancellation (`signal` abort) is normal flow — **not** emitted.
 - `message`: terse, factual. `position`: typically null at the runtime layer.
 
 The envelope is mirrored locally (`TelemetryEvent`, `ContentOffset`, `LogCoordinate`) so the framework needs no `@plurnk/plurnk-grammar` dependency; grammar's `dist/schema/TelemetryEvent.json` is the source of truth.
@@ -92,7 +112,7 @@ The envelope is mirrored locally (`TelemetryEvent`, `ContentOffset`, `LogCoordin
 
 A package may claim multiple tags backed by one handler. Tags form a **flat global namespace**; `registry` maps tag → `{ runtime, glyph, packageName }`. Unlike plurnk-mimetypes (last-loaded wins), a tag **collision is fail-hard**: two packages claiming the same runtime is an unresolvable install ambiguity the operator must fix.
 
-Each runtime exports its `BaseExecutor` subclass; the consumer instantiates it per matched tag with the tag + glyph from the registry. (Module-export convention for the subclass settles as the first siblings ship.)
+Each runtime package's **default export** is its `BaseExecutor` subclass (also a named export — `export { default as Sh }` / `export { default }`); the consumer instantiates it per matched tag with the tag + glyph from the registry.
 
 ## §4 Subprocess helper (legacy path)
 
@@ -111,16 +131,16 @@ interface SpawnArgs { cmd: string; args: string[]; useShell: boolean; }
 
 `resolveRuntime` never throws; consumers gate unknown runtimes with `isKnownRuntime` and return 501 before invoking.
 
-The framework wraps this in **`SubprocessExecutor extends BaseExecutor`** — declares `{ stdout, stderr }` channels and implements `run()` (spawn via `resolveRuntime`, stream into the channels, honor `signal`, `emit` `spawn_failed` on a failed start, return `{ status, exitCode }`). The `plurnk-execs-sh` / `-node` / `-python` siblings subclass it and differ only in their claimed `runtimes[]` tags. plurnk-service consumes `resolveRuntime` directly on its legacy path today and adopts `SubprocessExecutor` when it migrates.
+The framework wraps this in **`SubprocessExecutor extends BaseExecutor`** — declares `{ stdout, stderr }` channels and implements `run()` (spawn via `resolveRuntime`, stream into the channels, honor `signal`, `emit` `spawn_failed` on a failed start, return `{ status, exitCode }`). Subclasses with their own interpreter table override the **`protected spawnArgs(runtime, command) → SpawnArgs`** hook (default delegates to `resolveRuntime`) — and so inherit run()'s streaming + process-group abort handling. `SpawnArgs.stdin?` lets filter-style runtimes feed their program/input via stdin (`bc`, `tclsh`; or `""` for an `awk` BEGIN with EOF). On abort it kills the whole **process group** (`detached` spawn + `process.kill(-pid, …)`, SIGTERM→SIGKILL grace) so shell grandchildren can't leak (plurnk-execs#4). The `plurnk-execs-sh` / `-node` / `-python` siblings subclass it and differ only in their claimed `runtimes[]` tags and their `binary` getter (for `probe()`). `isKnownRuntime` / `KNOWN_RUNTIMES` are the legacy 501 gate; the discovery registry + `probe()` supersede them once a consumer wires the registry.
 
 ## §5 Consumer surface (plurnk-service)
 
-Per plurnk-service#174, the exec scheme:
+Per plurnk-service#174/#181/#182, realized in service `0.9.0`, the exec scheme:
 
-1. Resolves the runtime tag against the discovery registry; routes `search` (and future siblings) through the executor's `run()`.
-2. Seeds the exec entry's channels from `executor.channels`.
+1. Boot-discovers executors (`discover()`), `probe()`s each per-package, and offers the model the positive available-runtimes list; an unavailable runtime returns 501 carrying `probe()` `detail`.
+2. Resolves the runtime tag to its executor and runs it through `run()`, seeding the exec entry's channels from `executor.channels`.
 3. Provides the `write` / `setState` / `emit` sinks bound to its channel-write, channel-state, and engine-telemetry machinery; bridges its AbortController to `args.signal`; maps the `ExecResult` to close-status + wake summary.
-4. Keeps the legacy `streamShellCommand` path (via `resolveRuntime`) for subprocess runtimes until the `SubprocessExecutor` migration.
+4. Gates the proposal lifecycle by `effect(target)` (`EffectPolicy`: `host → propose`, `read`/`pure → auto`), running auto-run runtimes inline (synchronous return) while still landing the result as a re-readable entry.
 
 ## §6 Forbidden (for siblings)
 

package/dist/BaseExecutor.d.ts

@@ -1,4 +1,4 @@
-import type { ChannelDecl, ExecArgs, ExecResult, ExecutorMetadata, RuntimeAvailability } from "./types.ts";
+import type { ChannelDecl, Effect, ExecArgs, ExecResult, ExecutorMetadata, RuntimeAvailability } from "./types.ts";
 export default abstract class BaseExecutor {
     readonly runtime: string;
     readonly glyph: string;
@@ -6,5 +6,6 @@ export default abstract class BaseExecutor {
     abstract get channels(): Readonly<Record<string, ChannelDecl>>;
     abstract run(args: ExecArgs): Promise<ExecResult>;
     probe(): Promise<RuntimeAvailability>;
+    effect(_target: string | null): Effect;
 }
 //# sourceMappingURL=BaseExecutor.d.ts.map

package/dist/BaseExecutor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BaseExecutor.d.ts","sourceRoot":"","sources":["../src/BaseExecutor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAW3G,MAAM,CAAC,OAAO,CAAC,QAAQ,OAAO,YAAY;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,gBAAgB;IAUhD,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IAO/D,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC;IAY3C,KAAK,IAAI,OAAO,CAAC,mBAAmB,CAAC;CAG9C"}
+{"version":3,"file":"BaseExecutor.d.ts","sourceRoot":"","sources":["../src/BaseExecutor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAWnH,MAAM,CAAC,OAAO,CAAC,QAAQ,OAAO,YAAY;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,gBAAgB;IAUhD,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IAO/D,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC;IAY3C,KAAK,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAW3C,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM;CAGzC"}

package/dist/BaseExecutor.js

@@ -27,5 +27,15 @@ export default class BaseExecutor {
     async probe() {
         return { available: true };
     }
+    // Side-effect class of an invocation against `target` (the parsed EXEC
+    // target — what run() receives as cwd), for the consumer's proposal-gating
+    // policy (service#182). MUST be pure, synchronous, and cheap — it runs on
+    // the dispatch hot path at propose time: classify the target only, NEVER
+    // the command (parsing SQL/shell to judge intent is a sandbox-escape
+    // footgun). Default `host` is the conservative, fail-safe end — anything we
+    // can't classify is treated as host code-execution and proposed.
+    effect(_target) {
+        return "host";
+    }
 }
 //# sourceMappingURL=BaseExecutor.js.map

package/dist/BaseExecutor.js.map

@@ -1 +1 @@
-{"version":3,"file":"BaseExecutor.js","sourceRoot":"","sources":["../src/BaseExecutor.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAChF,6EAA6E;AAC7E,6EAA6E;AAC7E,yEAAyE;AACzE,EAAE;AACF,2EAA2E;AAC3E,6EAA6E;AAC7E,2EAA2E;AAC3E,mDAAmD;AACnD,MAAM,CAAC,OAAO,OAAgB,YAAY;IAC7B,OAAO,CAAS;IAChB,KAAK,CAAS;IAEvB,YAAY,EAAE,OAAO,EAAE,KAAK,EAAoB;QAC5C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACvB,CAAC;IAgBD,wEAAwE;IACxE,0EAA0E;IAC1E,wEAAwE;IACxE,iEAAiE;IACjE,EAAE;IACF,0EAA0E;IAC1E,yEAAyE;IACzE,2EAA2E;IAC3E,yEAAyE;IACzE,4DAA4D;IAC5D,KAAK,CAAC,KAAK;QACP,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAC/B,CAAC;CACJ"}
+{"version":3,"file":"BaseExecutor.js","sourceRoot":"","sources":["../src/BaseExecutor.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAChF,6EAA6E;AAC7E,6EAA6E;AAC7E,yEAAyE;AACzE,EAAE;AACF,2EAA2E;AAC3E,6EAA6E;AAC7E,2EAA2E;AAC3E,mDAAmD;AACnD,MAAM,CAAC,OAAO,OAAgB,YAAY;IAC7B,OAAO,CAAS;IAChB,KAAK,CAAS;IAEvB,YAAY,EAAE,OAAO,EAAE,KAAK,EAAoB;QAC5C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACvB,CAAC;IAgBD,wEAAwE;IACxE,0EAA0E;IAC1E,wEAAwE;IACxE,iEAAiE;IACjE,EAAE;IACF,0EAA0E;IAC1E,yEAAyE;IACzE,2EAA2E;IAC3E,yEAAyE;IACzE,4DAA4D;IAC5D,KAAK,CAAC,KAAK;QACP,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAC/B,CAAC;IAED,uEAAuE;IACvE,2EAA2E;IAC3E,0EAA0E;IAC1E,yEAAyE;IACzE,qEAAqE;IACrE,4EAA4E;IAC5E,iEAAiE;IACjE,MAAM,CAAC,OAAsB;QACzB,OAAO,MAAM,CAAC;IAClB,CAAC;CACJ"}

package/dist/SubprocessExecutor.d.ts

@@ -1,9 +1,11 @@
 import BaseExecutor from "./BaseExecutor.ts";
-import type { ChannelDecl, ExecArgs, ExecResult, RuntimeAvailability } from "./types.ts";
+import type { ChannelDecl, Effect, ExecArgs, ExecResult, RuntimeAvailability, SpawnArgs } from "./types.ts";
 export default class SubprocessExecutor extends BaseExecutor {
     get channels(): Readonly<Record<string, ChannelDecl>>;
     protected get binary(): string | null;
+    effect(_target: string | null): Effect;
     probe(): Promise<RuntimeAvailability>;
+    protected spawnArgs(runtime: string, command: string): SpawnArgs;
     run({ runtime, command, cwd, signal, write, setState, emit }: ExecArgs): Promise<ExecResult>;
 }
 //# sourceMappingURL=SubprocessExecutor.d.ts.map

package/dist/SubprocessExecutor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SubprocessExecutor.d.ts","sourceRoot":"","sources":["../src/SubprocessExecutor.ts"],"names":[],"mappings":"AACA,OAAO,YAAY,MAAM,mBAAmB,CAAC;AAE7C,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAWzF,MAAM,CAAC,OAAO,OAAO,kBAAmB,SAAQ,YAAY;IACxD,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAKpD;IAKD,SAAS,KAAK,MAAM,IAAI,MAAM,GAAG,IAAI,CAEpC;IAEc,KAAK,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAqBpD,GAAG,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC;CAwC/F"}
+{"version":3,"file":"SubprocessExecutor.d.ts","sourceRoot":"","sources":["../src/SubprocessExecutor.ts"],"names":[],"mappings":"AACA,OAAO,YAAY,MAAM,mBAAmB,CAAC;AAE7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAgB5G,MAAM,CAAC,OAAO,OAAO,kBAAmB,SAAQ,YAAY;IACxD,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAKpD;IAKD,SAAS,KAAK,MAAM,IAAI,MAAM,GAAG,IAAI,CAEpC;IAGQ,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM;IAIhC,KAAK,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAyBpD,SAAS,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS;IAIhE,GAAG,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC;CAoE/F"}

package/dist/SubprocessExecutor.js

@@ -1,6 +1,10 @@
 import { spawn } from "node:child_process";
 import BaseExecutor from "./BaseExecutor.js";
 import { resolveRuntime } from "./runtime.js";
+// Grace period between SIGTERM and SIGKILL when tearing down an aborted process
+// group — long enough for a well-behaved process to clean up, bounded so a
+// process ignoring SIGTERM can't wedge cancellation.
+const ABORT_GRACE_MS = 2000;
 // Concrete BaseExecutor for subprocess runtimes (sh, node, python, …). Spawns
 // via resolveRuntime, streams the process's stdout/stderr into the declared
 // channels, honors cancellation, and reports the exit code. The sibling
@@ -23,6 +27,10 @@ export default class SubprocessExecutor extends BaseExecutor {
     get binary() {
         return null;
     }
+    // Subprocess runtimes execute code on the host — always `host`.
+    effect(_target) {
+        return "host";
+    }
     async probe() {
         const bin = this.binary;
         if (bin === null)
@@ -47,36 +55,73 @@ export default class SubprocessExecutor extends BaseExecutor {
                 : { available: false, detail: `${bin} --version exited ${code}` }));
         });
     }
+    // Translate the matched tag + command into spawn args. Default delegates to
+    // resolveRuntime (sh/node/python); subclasses with their own interpreter
+    // table (e.g. the common-REPL harness) override this — and so inherit run()'s
+    // streaming + process-group abort handling rather than reimplementing it.
+    spawnArgs(runtime, command) {
+        return resolveRuntime(runtime, command);
+    }
     run({ runtime, command, cwd, signal, write, setState, emit }) {
-        const { cmd, args, useShell } = resolveRuntime(runtime, command);
+        const { cmd, args, useShell, stdin } = this.spawnArgs(runtime, command);
         return new Promise((resolve) => {
-            // Abort and close both fire on signal-kill; settle exactly once so
-            // channel state isn't transitioned twice.
+            // Already cancelled before we start — don't launch a doomed process.
+            if (signal.aborted) {
+                setState("stdout", "errored");
+                setState("stderr", "errored");
+                resolve({ status: 499, exitCode: -1 });
+                return;
+            }
             let settled = false;
+            let killTimer;
+            // `detached` makes the child its own process-group leader, so abort
+            // can signal the WHOLE group (`-pid`) — reaching shell grandchildren
+            // (e.g. the `sleep` in `sh -c "sleep 30"`) that a bare SIGTERM to the
+            // direct child orphans, leaking the process and its stdout pipe. We
+            // drive cancellation manually rather than via spawn's `signal`
+            // option, which only kills the direct child (plurnk-execs#4).
+            const child = spawn(cmd, args, { shell: useShell, cwd: cwd ?? undefined, detached: true });
+            // Filter-style runtimes feed their program/input via stdin; closing
+            // it also delivers EOF (awk BEGIN-only). Left untouched otherwise.
+            if (stdin !== undefined)
+                child.stdin?.end(stdin);
+            const killGroup = (sig) => {
+                if (child.pid === undefined)
+                    return;
+                try {
+                    process.kill(-child.pid, sig);
+                }
+                catch { /* group already gone */ }
+            };
+            const onAbort = () => {
+                killGroup("SIGTERM");
+                // Escalate if the group ignores SIGTERM. `close` fires once the
+                // pipes drain, which now happens because the grandchildren die.
+                killTimer = setTimeout(() => killGroup("SIGKILL"), ABORT_GRACE_MS);
+            };
             const finish = (result, state) => {
                 if (settled)
                     return;
                 settled = true;
+                if (killTimer)
+                    clearTimeout(killTimer);
+                signal.removeEventListener("abort", onAbort);
                 setState("stdout", state);
                 setState("stderr", state);
                 resolve(result);
             };
-            const child = spawn(cmd, args, { shell: useShell, signal, cwd: cwd ?? undefined });
+            signal.addEventListener("abort", onAbort, { once: true });
             child.stdout?.on("data", (chunk) => write("stdout", chunk.toString("utf8")));
             child.stderr?.on("data", (chunk) => write("stderr", chunk.toString("utf8")));
             child.on("error", (err) => {
-                if (err.code === "ABORT_ERR") {
-                    finish({ status: 499, exitCode: -1 }, "errored");
-                    return;
-                }
                 // The process could not be started — a framework-level failure
                 // the model benefits from seeing as telemetry (a nonzero exit,
                 // by contrast, is the program's own result and lives on stderr).
                 emit({ source: `exec:${runtime}`, kind: "spawn_failed", message: err.message });
                 finish({ status: 500, exitCode: -1 }, "errored");
             });
-            child.on("close", (code, killedBySignal) => {
-                if (killedBySignal !== null) {
+            child.on("close", (code) => {
+                if (signal.aborted) {
                     finish({ status: 499, exitCode: code ?? -1 }, "errored");
                     return;
                 }

package/dist/SubprocessExecutor.js.map

@@ -1 +1 @@
-{"version":3,"file":"SubprocessExecutor.js","sourceRoot":"","sources":["../src/SubprocessExecutor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SubprocessExecutor.js","sourceRoot":"","sources":["../src/SubprocessExecutor.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -2,6 +2,6 @@ export { default as BaseExecutor } from "./BaseExecutor.ts";
 export { default as SubprocessExecutor } from "./SubprocessExecutor.ts";
 export { discover } from "./discover.ts";
 export { KNOWN_RUNTIMES, isKnownRuntime, resolveRuntime } from "./runtime.ts";
-export type { ChannelState, ChannelDecl, ExecutorMetadata, ExecArgs, ExecResult, RuntimeAvailability, ExecInfo, ExecRegistry, Discovery, DiscoverOptions, SpawnArgs, RuntimeResolver, } from "./types.ts";
+export type { ChannelState, ChannelDecl, ExecutorMetadata, ExecArgs, ExecResult, Effect, RuntimeAvailability, ExecInfo, ExecRegistry, Discovery, DiscoverOptions, SpawnArgs, RuntimeResolver, } from "./types.ts";
 export type { TelemetryEvent, ContentOffset, LogCoordinate } from "./TelemetryEvent.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9E,YAAY,EACR,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,QAAQ,EACR,UAAU,EACV,mBAAmB,EACnB,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,eAAe,EACf,SAAS,EACT,eAAe,GAClB,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9E,YAAY,EACR,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,QAAQ,EACR,UAAU,EACV,MAAM,EACN,mBAAmB,EACnB,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,eAAe,EACf,SAAS,EACT,eAAe,GAClB,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/types.d.ts

@@ -21,6 +21,7 @@ export interface ExecResult {
     status: number;
     exitCode?: number;
 }
+export type Effect = "pure" | "read" | "host";
 export interface RuntimeAvailability {
     available: boolean;
     detail?: string;
@@ -45,6 +46,12 @@ export interface SpawnArgs {
     args: string[];
     /** When true, the command is interpreted as a shell line (cmd is the whole line, args ignored). */
     useShell: boolean;
+    /**
+     * When set, written to the child's stdin which is then closed. For filter-style
+     * runtimes that read their program/input from stdin (`bc`, `tclsh`) or that need
+     * EOF with no input (`awk` BEGIN-only). Omitted = stdin left at its default.
+     */
+    stdin?: string;
 }
 /**
  * Translate a runtime tag + command string into spawn args for `node:child_process.spawn`.

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI1D,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAM3D,MAAM,WAAW,WAAW;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,YAAY,CAAC;CAC/B;AAKD,MAAM,WAAW,gBAAgB;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACjB;AAOD,MAAM,WAAW,QAAQ;IAGrB,OAAO,EAAE,MAAM,CAAC;IAEhB,OAAO,EAAE,MAAM,CAAC;IAGhB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnB,MAAM,EAAE,WAAW,CAAC;IAEpB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAEhD,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IAGzD,IAAI,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;CACzC;AAKD,MAAM,WAAW,UAAU;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAOD,MAAM,WAAW,mBAAmB;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAGD,MAAM,WAAW,QAAQ;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACvB;AAID,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAEzD,MAAM,WAAW,SAAS;IACtB,QAAQ,EAAE,YAAY,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAG5B,GAAG,CAAC,EAAE,MAAM,CAAC;IAGb,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAID,MAAM,WAAW,SAAS;IACtB,wFAAwF;IACxF,GAAG,EAAE,MAAM,CAAC;IACZ,kCAAkC;IAClC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,mGAAmG;IACnG,QAAQ,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,SAAS,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI1D,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAM3D,MAAM,WAAW,WAAW;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,YAAY,CAAC;CAC/B;AAKD,MAAM,WAAW,gBAAgB;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACjB;AAOD,MAAM,WAAW,QAAQ;IAGrB,OAAO,EAAE,MAAM,CAAC;IAEhB,OAAO,EAAE,MAAM,CAAC;IAGhB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnB,MAAM,EAAE,WAAW,CAAC;IAEpB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAEhD,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IAGzD,IAAI,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;CACzC;AAKD,MAAM,WAAW,UAAU;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAQD,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAO9C,MAAM,WAAW,mBAAmB;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAGD,MAAM,WAAW,QAAQ;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACvB;AAID,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAEzD,MAAM,WAAW,SAAS;IACtB,QAAQ,EAAE,YAAY,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAG5B,GAAG,CAAC,EAAE,MAAM,CAAC;IAGb,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAID,MAAM,WAAW,SAAS;IACtB,wFAAwF;IACxF,GAAG,EAAE,MAAM,CAAC;IACZ,kCAAkC;IAClC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,mGAAmG;IACnG,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,SAAS,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@plurnk/plurnk-execs",
-    "version": "0.3.0",
+    "version": "0.4.1",
     "description": "Framework + contract for the @plurnk/plurnk-execs-* runtime executor family.",
     "keywords": ["plurnk", "exec", "runtime", "executor"],
     "homepage": "https://github.com/plurnk/plurnk-execs#readme",
@@ -34,7 +34,7 @@
     ],
     "scripts": {
         "test:lint": "tsc --noEmit",
-        "test:unit": "node --test src/**/*.test.ts",
+        "test:unit": "node --test \"src/**/*.test.ts\"",
         "test": "npm run test:lint && npm run test:unit",
         "build:dist": "tsc -p tsconfig.build.json",
         "build": "npm run build:dist",