skillscript-runtime 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 Each release carries an **Upgrade impact:** line (first in its section) so a bump's requirements are visible at a glance. Tags (closed set): **BREAKING** (a manual change is needed to keep working) · **RE-APPROVE** (secured-mode signature invalidation — skills must be re-approved before they run) · **CONFIG** (`connectors.json` / config edit needed) · **none (additive)** (no action; backward-compatible). Standard from 0.20.0 forward; the pre-0.20 transitions that need action are flagged inline below (0.14.0, 0.18.8, 0.19.0). Full walkthrough: [UPGRADING.md](UPGRADING.md).
 
+## 0.24.0 — 2026-06-25 — adopter wishlist: bootstrapFromEnv + remote-store polling + connector reaping
+
+**Upgrade impact:** none (additive). All four items are backward-compatible — a new export, an optional contract method, an opt-in tool param, and an internal lifecycle fix. Existing programmatic `bootstrap()` code keeps working; `bootstrapFromEnv()` is an *optional* simplification.
+
+From an AMP-backed remote-store adopter dogfooding the runtime:
+
+- **`bootstrapFromEnv()` — a blessed programmatic entry point.** Most adopters run `skillfile init` once, then operate via the web dashboard. This new exported helper stands that dashboard up from your own code *exactly the way the CLI does*: it loads `$SKILLSCRIPT_HOME/.env` + `skillscript.config.json` + `connectors.json`, resolves the full `SKILLSCRIPT_*` env cascade, calls `bootstrap()`, wires declarative triggers, and assembles the `DashboardServer`. Returns `{ wired, server }` (both unstarted; the caller `start()`s them and calls `wired.registry.disposeAll()` on shutdown). Precedence: explicit option > env > config.json > default. The CLI's `dashboard`/`serve` commands are now thin wrappers over it — closing the silent "every capability the CLI auto-wires had to be hand-assembled programmatically, and each omission failed silently" asymmetry.
+- **`SkillStore.version()` — optional change-token kills the skill_list N+1 for remote stores.** Building the `skill_list` catalog loads every skill's body to parse its effectful footprint — free against a local store, but a network round-trip *per skill* against a remote one, so a polling dashboard hammered the substrate. A new optional `version()` returns a cheap store-wide token (no body loads); `skill_list` returns it as `catalog_version` and honors a caller's `if_none_match`, replying `{ not_modified: true }` and skipping the rebuild when nothing changed. The SPA now sends it (and pauses its poll when the browser tab is backgrounded). Bundled stores implement it (FS: per-file mtimes; sqlite: `(name, status, current_version)` in one query). Optional — a store without it just always rebuilds.
+- **Connector reaping on shutdown.** `Registry.disposeAll()` (new) disposes connectors holding child processes on runtime shutdown, so a stdio-bridged MCP server child (`RemoteMcpConnector`) is reaped rather than orphaned to a dead parent across restarts. The CLI shutdown handler calls it; `bootstrapFromEnv()` callers should too. (Distinct from 0.23.1's respawn-on-death, which self-heals a child that dies *while running* — this reaps a child on *intentional* shutdown.)
+
+## 0.23.1 — 2026-06-23 — fixes: connector-arg lint advisory + RemoteMcpConnector self-heal
+
+**Upgrade impact:** none (additive).
+
+- **Fix — `RemoteMcpConnector` now respawns a dead child instead of latching a permanent outage (adopter finding).** When the connector's stdio child exited (e.g. an external `SIGTERM`, exit code 143), it latched a terminal error state and **never respawned** — every subsequent dispatch returned `RemoteMcpConnector in error state` until a full runtime restart. A single child death = total connector outage. `start()` now self-heals: a dead prior session is discarded and the next dispatch (or `describeTools` warm) relaunches the child, mirroring a session reconnect. An intentional `dispose()` still blocks respawn (a post-dispose dispatch throws). Independent of what killed the child. Verified with a real spawned child that exits mid-request.
+- **Fix — stale tier-3 advisory contradicting connector-arg lint (adopter finding).** The tier-3 `unverified-qualified-tool` advisory ("connector doesn't declare its tool surface statically; can't validate at compile time") co-fired against a connector wired via `describeTools()` but no `staticTools()` — i.e. every `RemoteMcpConnector` — and *contradicted* the 0.23.0 tier-2 connector-arg validation on the **same** op: an author saw "you passed an unknown arg (so I clearly know your schema)" alongside "I can't validate this tool." It now skips an op whose tool is verified by the warmed schema, and still fires only when neither a static nor a warmed dynamic surface is reachable (a truly-opaque connector, or a misspelled tool name not in the fetched surface). Probe-verified against the live ddg `RemoteMcpConnector`.
+
 ## 0.23.0 — 2026-06-23 — connector tool-schema discovery + connector-aware lint
 
 **Upgrade impact:** none (additive). One thing to know: the new tier-2 lint can surface a *pre-existing* wrong-arg-name in an existing skill (it was always wrong; it just failed at dispatch before). Tier-2 is a warning — it never blocks compile or execution.

package/dist/bootstrap-from-env.d.ts

@@ -0,0 +1,46 @@
+import { type BootstrapResult, type BootstrapOpts } from "./bootstrap.js";
+import { DashboardServer } from "./dashboard/server.js";
+export interface BootstrapFromEnvOptions {
+    /** "dashboard" mounts the SPA at `/`; "serve" runs headless on `/rpc`. Default "dashboard". */
+    mode?: "serve" | "dashboard";
+    /** Config root. Default `$SKILLSCRIPT_HOME` ?? `~/.skillscript`. */
+    home?: string;
+    /** Override the skillscript.config.json path (default `<home>/skillscript.config.json`). */
+    configPath?: string;
+    /** Override the connectors.json path (default `<home>/connectors.json`). */
+    connectorsConfigPath?: string;
+    /** Override the HTTP port (else env `SKILLSCRIPT_PORT` / config / 7878). */
+    port?: number;
+    /** Override the bind address (else env `SKILLSCRIPT_HOST` / config / 127.0.0.1). */
+    host?: string;
+    /**
+     * Pass-through to `bootstrap()`, merged LAST so it wins over the env/config
+     * resolution. This is how you inject CUSTOM in-process substrate instances —
+     * `overrides: { skillStore: new MyRemoteSkillStore(...) }` — while letting
+     * everything else auto-wire from `$SKILLSCRIPT_HOME`. (A custom substrate that
+     * IS expressible declaratively can instead use the `connectors.json`
+     * `{ type: "custom", module, export }` form and skip this.)
+     */
+    overrides?: Partial<BootstrapOpts>;
+}
+export interface BootstrapFromEnvResult {
+    /** The wired runtime (registry, mcpServer, scheduler, skillStore, traceStore). */
+    wired: BootstrapResult;
+    /** The assembled DashboardServer — NOT started. Call `server.start()` + `wired.scheduler.start()`. */
+    server: DashboardServer;
+}
+/**
+ * Wire a runtime + DashboardServer from the environment, exactly as the CLI
+ * `dashboard` / `serve` commands do. Returns both UNSTARTED — the caller decides
+ * when to `scheduler.start()` + `server.start()` (and is responsible for
+ * `wired.registry.disposeAll()` on shutdown to reap connector children).
+ *
+ * Resolution precedence per knob: explicit option > `SKILLSCRIPT_*` env >
+ * `skillscript.config.json` > built-in default. Secured mode + approval keys +
+ * the shell/fs allowlists + timeouts are resolved inside `bootstrap()`; the
+ * dashboard auth token / approval passcode / caller-identity header are resolved
+ * inside `DashboardServer`. This helper layers the config-file values + home
+ * paths on top.
+ */
+export declare function bootstrapFromEnv(opts?: BootstrapFromEnvOptions): Promise<BootstrapFromEnvResult>;
+//# sourceMappingURL=bootstrap-from-env.d.ts.map

package/dist/bootstrap-from-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap-from-env.d.ts","sourceRoot":"","sources":["../src/bootstrap-from-env.ts"],"names":[],"mappings":"AAeA,OAAO,EAAsC,KAAK,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC9G,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAMxD,MAAM,WAAW,uBAAuB;IACtC,+FAA+F;IAC/F,IAAI,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;IAC7B,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,sBAAsB;IACrC,kFAAkF;IAClF,KAAK,EAAE,eAAe,CAAC;IACvB,sGAAsG;IACtG,MAAM,EAAE,eAAe,CAAC;CACzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,GAAE,uBAA4B,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA+D1G"}

package/dist/bootstrap-from-env.js

@@ -0,0 +1,130 @@
+// v0.23.x — `bootstrapFromEnv()`: one blessed entry point that wires a runtime
+// + DashboardServer exactly the way the `skillfile dashboard` / `skillfile
+// serve` CLI does — loading `$SKILLSCRIPT_HOME/.env`, `skillscript.config.json`,
+// and `connectors.json`, resolving the full SKILLSCRIPT_* env cascade, then
+// bootstrap()ing and assembling the DashboardServer.
+//
+// Most adopters run the CLI once for `init`, then operate via the web
+// dashboard. This helper is the programmatic equivalent: an adopter calls it,
+// gets a fully-wired runtime + server, and swaps only the substrates they
+// customize — closing the silent CLI-vs-programmatic wiring asymmetry where
+// each capability the CLI auto-wires had to be hand-assembled (and each
+// omission failed silently). Adopter wishlist 82e17077.
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { bootstrap, wireDeclarativeTriggers } from "./bootstrap.js";
+import { DashboardServer } from "./dashboard/server.js";
+import { loadSkillscriptConfig } from "./runtime-config.js";
+import { loadEnvFile } from "./dotenv-loader.js";
+import { isSecuredMode, evaluateApprovalGate } from "./approval.js";
+/**
+ * Wire a runtime + DashboardServer from the environment, exactly as the CLI
+ * `dashboard` / `serve` commands do. Returns both UNSTARTED — the caller decides
+ * when to `scheduler.start()` + `server.start()` (and is responsible for
+ * `wired.registry.disposeAll()` on shutdown to reap connector children).
+ *
+ * Resolution precedence per knob: explicit option > `SKILLSCRIPT_*` env >
+ * `skillscript.config.json` > built-in default. Secured mode + approval keys +
+ * the shell/fs allowlists + timeouts are resolved inside `bootstrap()`; the
+ * dashboard auth token / approval passcode / caller-identity header are resolved
+ * inside `DashboardServer`. This helper layers the config-file values + home
+ * paths on top.
+ */
+export async function bootstrapFromEnv(opts = {}) {
+    const home = opts.home ?? process.env["SKILLSCRIPT_HOME"] ?? join(homedir(), ".skillscript");
+    // Load `<home>/.env` so SKILLSCRIPT_* vars are populated — the CLI does this
+    // at startup; a programmatic adopter would otherwise miss it. Missing file is
+    // a no-op (per dotenv-loader).
+    loadEnvFile({ path: join(home, ".env") });
+    const mode = opts.mode ?? "dashboard";
+    const configPath = opts.configPath ?? join(home, "skillscript.config.json");
+    const { config: fileConfig } = loadSkillscriptConfig({ path: configPath });
+    const triggersFilePath = fileConfig.triggersFilePath ?? join(home, "triggers.json");
+    const connectorsConfigPath = opts.connectorsConfigPath ?? fileConfig.connectorsConfigPath ?? join(home, "connectors.json");
+    // env ?? config per knob, so `bootstrap()`'s own env resolution (opts win over
+    // env there) preserves the env > config > default precedence the CLI uses.
+    const enableUnsafeShell = boolEnv(process.env["SKILLSCRIPT_ENABLE_UNSAFE_SHELL"]) ?? fileConfig.enableUnsafeShell;
+    const forceAlwaysDraft = boolEnv(process.env["SKILLSCRIPT_FORCE_ALWAYS_DRAFT"]) ?? fileConfig.forceAlwaysDraft;
+    const pollIntervalSeconds = posIntEnv(process.env["SKILLSCRIPT_POLL_INTERVAL_SECONDS"]) ?? fileConfig.pollIntervalSeconds;
+    const absoluteTimeoutMs = posIntEnv(process.env["SKILLSCRIPT_ABSOLUTE_TIMEOUT_MS"]) ?? fileConfig.absoluteTimeoutMs;
+    const maxRecursionDepth = posIntEnv(process.env["SKILLSCRIPT_MAX_RECURSION_DEPTH"], 1) ?? fileConfig.maxRecursionDepth;
+    const shellAllowlist = listEnv(process.env["SKILLSCRIPT_SHELL_ALLOWLIST"]) ?? fileConfig.shellAllowlist;
+    const fsAllowlist = listEnv(process.env["SKILLSCRIPT_FS_ALLOWLIST"]) ?? fileConfig.fsAllowlist;
+    const wired = bootstrap({
+        skillsDir: fileConfig.skillsDir ?? join(home, "skills"),
+        traceDir: fileConfig.traceDir ?? join(home, "traces"),
+        dataDbPath: fileConfig.dataDbPath ?? join(home, "data.db"),
+        triggersFilePath,
+        connectorsConfigPath,
+        mode,
+        ...(pollIntervalSeconds !== undefined ? { pollIntervalSeconds } : {}),
+        ...(absoluteTimeoutMs !== undefined ? { absoluteTimeoutMs } : {}),
+        ...(maxRecursionDepth !== undefined ? { maxRecursionDepth } : {}),
+        ...(shellAllowlist !== undefined ? { shellAllowlist } : {}),
+        ...(fsAllowlist !== undefined ? { fsAllowlist } : {}),
+        ...(enableUnsafeShell !== undefined ? { enableUnsafeShell } : {}),
+        ...(forceAlwaysDraft === true ? { forceAlwaysDraft: true } : {}),
+        // Scheduler-fired skills record traces by default.
+        trace: { mode: "on" },
+        // Adopter overrides win last — notably custom substrate INSTANCES
+        // (e.g. overrides.skillStore = new MyRemoteSkillStore(...)).
+        ...opts.overrides,
+    });
+    await wireDeclarativeTriggers(wired);
+    await warnStaleApprovals(wired.skillStore);
+    const server = new DashboardServer({
+        mcpServer: wired.mcpServer,
+        mountSpa: mode === "dashboard",
+        // Scheduler is passed unconditionally: the /event route gates on its own
+        // enable flag, but the dashboard /approve route needs the scheduler to
+        // re-register a skill's declarative triggers on approval.
+        scheduler: wired.scheduler,
+        skillStore: wired.skillStore,
+        ...(opts.port !== undefined ? { port: opts.port } : {}),
+        ...(opts.host !== undefined ? { bindAddress: opts.host } : {}),
+        // port / host / mcpCallerIdentityHeader / eventIngress* / dashboard auth
+        // token / approval passcode / approval key file are all resolved from env by
+        // DashboardServer itself.
+    });
+    return { wired, server };
+}
+/** Warn (best-effort) when secured mode is on and stored Approved skills lack a valid signature. */
+async function warnStaleApprovals(skillStore) {
+    if (!isSecuredMode())
+        return;
+    try {
+        const approved = await skillStore.query({ status: "Approved" });
+        const stale = [];
+        for (const m of approved) {
+            const loaded = await skillStore.load(m.name);
+            if (!evaluateApprovalGate(loaded.source).ok)
+                stale.push(m.name);
+        }
+        if (stale.length === 0)
+            return;
+        const shown = stale.slice(0, 5).join(", ");
+        const more = stale.length > 5 ? `, +${stale.length - 5} more` : "";
+        process.stderr.write(`\n⚠  Secured mode: ${stale.length} stored skill${stale.length === 1 ? "" : "s"} ` +
+            `${stale.length === 1 ? "is" : "are"} Approved but carry no valid signature — ` +
+            `they will be REFUSED until re-approved.\n` +
+            `   Re-bless the set:  skillfile reapprove --apply\n` +
+            `   (${shown}${more})\n\n`);
+    }
+    catch {
+        /* best-effort — a scan failure must never block the runtime starting */
+    }
+}
+// ─── env coercion helpers (mirror the CLI's cascade semantics) ───────────────
+function boolEnv(raw) {
+    return raw !== undefined ? raw === "true" : undefined;
+}
+function posIntEnv(raw, min = 0) {
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    return Number.isInteger(n) && n >= (min || 1) ? n : undefined;
+}
+function listEnv(raw) {
+    return raw !== undefined ? raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0) : undefined;
+}
+//# sourceMappingURL=bootstrap-from-env.js.map

package/dist/bootstrap-from-env.js.map

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

package/dist/cli.js

@@ -25,9 +25,8 @@ import { SqliteDataStore } from "./connectors/data-store.js";
 import { parse } from "./parser.js";
 import { FilesystemTraceStore } from "./trace.js";
 import { healthMetrics } from "./metrics.js";
-import { DashboardServer } from "./dashboard/server.js";
-import { bootstrap, defaultRegistry, wireDeclarativeTriggers, ensureApprovalKeys, defaultApprovalKeyFile, defaultApprovalPublicKeyFile } from "./bootstrap.js";
-import { loadSkillscriptConfig } from "./runtime-config.js";
+import { defaultRegistry, ensureApprovalKeys, defaultApprovalKeyFile, defaultApprovalPublicKeyFile } from "./bootstrap.js";
+import { bootstrapFromEnv } from "./bootstrap-from-env.js";
 import { loadEnvFile } from "./dotenv-loader.js";
 import { createHash } from "node:crypto";
 const HOME_DIR = process.env["SKILLSCRIPT_HOME"] ?? join(homedir(), ".skillscript");
@@ -907,34 +906,6 @@ async function cmdReapprove(args) {
     process.stdout.write(`\nDone — ${ok} re-blessed${fail > 0 ? `, ${fail} failed` : ""}.\n`);
     return fail === 0 ? 0 : 1;
 }
-// v0.20.1 — secured-mode startup nudge. Scans the store for skills that are
-// Approved but fail the gate (no/legacy/invalid signature) and warns once at
-// boot, pointing at `skillfile reapprove`. Best-effort: never blocks startup.
-async function warnStaleApprovals(skillStore) {
-    if (!isSecuredMode())
-        return;
-    try {
-        const approved = await skillStore.query({ status: "Approved" });
-        const stale = [];
-        for (const m of approved) {
-            const loaded = await skillStore.load(m.name);
-            if (!evaluateApprovalGate(loaded.source).ok)
-                stale.push(m.name);
-        }
-        if (stale.length === 0)
-            return;
-        const shown = stale.slice(0, 5).join(", ");
-        const more = stale.length > 5 ? `, +${stale.length - 5} more` : "";
-        process.stderr.write(`\n⚠  Secured mode: ${stale.length} stored skill${stale.length === 1 ? "" : "s"} ` +
-            `${stale.length === 1 ? "is" : "are"} Approved but carry no valid signature — ` +
-            `they will be REFUSED until re-approved.\n` +
-            `   Re-bless the set:  skillfile reapprove --apply\n` +
-            `   (${shown}${more})\n\n`);
-    }
-    catch {
-        /* best-effort — a scan failure must never block the runtime starting */
-    }
-}
 function parseRunCompileArgs(args) {
     const opts = { inputs: {}, format: "prompt", mechanical: false, inlineProvenance: false };
     for (let i = 0; i < args.length; i++) {
@@ -1066,144 +1037,23 @@ async function copyScaffoldFile(src, dest) {
     await writeFile(dest, body, "utf8");
 }
 async function cmdRuntimeHost(args, opts) {
-    // v0.7.3 — load skillscript.config.json if present. CLI flags override
-    // config-file values; config-file values override defaults.
-    const configPath = extractFlag(args, "--config") ?? join(HOME_DIR, "skillscript.config.json");
-    const { config: fileConfig, errors: configErrors } = loadSkillscriptConfig({ path: configPath });
-    for (const err of configErrors)
-        process.stderr.write(`[cli] ${err}\n`);
-    // v0.17.4 — env-cascade for operator-config switches. Precedence:
-    // CLI flag (most specific, per-invocation) > env var (per-process,
-    // drop in `.env`) > JSON config (per-deployment) > built-in default.
-    // This mirrors the standard layered-config pattern adopters expect
-    // from any well-behaved Node service.
-    const portStr = extractFlag(args, "--port") ?? process.env["SKILLSCRIPT_PORT"];
-    const port = portStr !== undefined ? parseInt(portStr, 10) : fileConfig.dashboard?.port ?? 7878;
-    // --host is the bind address inside the running process. 127.0.0.1 is
-    // the safe default for local invocation; container deployments pass
-    // --host 0.0.0.0 so the host-side port-forward can reach the listener
-    // (host port mapping still enforces 127.0.0.1 externally).
-    const host = extractFlag(args, "--host") ?? process.env["SKILLSCRIPT_HOST"] ?? fileConfig.dashboard?.host ?? "127.0.0.1";
-    // v0.17.4 — env cascade for the v0.17.0 inbound caller-identity header.
-    // Operator-config surface; env-natural for installer workflows.
-    const mcpCallerIdentityHeader = process.env["SKILLSCRIPT_MCP_CALLER_IDENTITY_HEADER"] ?? fileConfig.dashboard?.mcpCallerIdentityHeader;
-    // v0.17.4 — env cascade for the unsafe-shell posture switch.
-    // Security-relevant; env-natural so operators can flip without
-    // editing JSON.
-    const envUnsafeShell = process.env["SKILLSCRIPT_ENABLE_UNSAFE_SHELL"];
-    const enableUnsafeShell = envUnsafeShell !== undefined
-        ? envUnsafeShell === "true"
-        : fileConfig.enableUnsafeShell;
-    const triggersFilePath = fileConfig.triggersFilePath ?? join(HOME_DIR, "triggers.json");
-    // v0.4.3 — auto-discover connectors.json from HOME_DIR. Closes the
-    // last-mile gap of the v0.4.x arc: pre-v0.4.3 the loader + lint +
-    // runtime + allowlist all worked, but the canonical CLI entry point
-    // didn't read connectors.json. --connectors <path> overrides the
-    // default for non-standard layouts. Loader is graceful on missing.
-    const connectorsConfigPath = extractFlag(args, "--connectors") ?? fileConfig.connectorsConfigPath ?? join(HOME_DIR, "connectors.json");
-    // v0.17.4 — forceAlwaysDraft cascade: env var > config file > default
-    // false. SKILLSCRIPT_FORCE_ALWAYS_DRAFT=true forces every outside-MCP
-    // skill_write to land Draft regardless of body declaration. Closes
-    // the agent-self-approval path for adopters wanting a human approval
-    // gate. Drop a `.env` with the value, restart — done.
-    const envForceAlwaysDraft = process.env["SKILLSCRIPT_FORCE_ALWAYS_DRAFT"];
-    const forceAlwaysDraft = envForceAlwaysDraft !== undefined
-        ? envForceAlwaysDraft === "true"
-        : fileConfig.forceAlwaysDraft;
-    // v0.18.7 — env cascade for three previously-hidden operator knobs.
-    // Each follows the same cascade shape: env > config > default. Parsing
-    // errors (non-numeric / non-positive) are silently ignored — the
-    // config-layer schema parser is the authoritative validator for these
-    // fields, and env values failing here fall through to config/default.
-    const envPollSecondsRaw = process.env["SKILLSCRIPT_POLL_INTERVAL_SECONDS"];
-    const envPollSeconds = envPollSecondsRaw !== undefined ? Number(envPollSecondsRaw) : undefined;
-    const pollIntervalSeconds = envPollSeconds !== undefined && Number.isFinite(envPollSeconds) && envPollSeconds > 0
-        ? envPollSeconds
-        : fileConfig.pollIntervalSeconds;
-    const envAbsoluteTimeoutRaw = process.env["SKILLSCRIPT_ABSOLUTE_TIMEOUT_MS"];
-    const envAbsoluteTimeout = envAbsoluteTimeoutRaw !== undefined ? Number(envAbsoluteTimeoutRaw) : undefined;
-    const absoluteTimeoutMs = envAbsoluteTimeout !== undefined && Number.isInteger(envAbsoluteTimeout) && envAbsoluteTimeout > 0
-        ? envAbsoluteTimeout
-        : fileConfig.absoluteTimeoutMs;
-    const envMaxRecursionRaw = process.env["SKILLSCRIPT_MAX_RECURSION_DEPTH"];
-    const envMaxRecursion = envMaxRecursionRaw !== undefined ? Number(envMaxRecursionRaw) : undefined;
-    const maxRecursionDepth = envMaxRecursion !== undefined && Number.isInteger(envMaxRecursion) && envMaxRecursion >= 1
-        ? envMaxRecursion
-        : fileConfig.maxRecursionDepth;
-    // v0.18.8 — shell binary allowlist. Comma-separated env value, trimmed.
-    // Default-deny: when neither env nor config is set, leave undefined →
-    // runtime refuses ALL shell() ops. Empty env string is an explicit
-    // empty list (also refuses all) — distinct from undefined for
-    // observability (operator can declare "no shell at all" intentionally).
-    const envShellAllowlistRaw = process.env["SKILLSCRIPT_SHELL_ALLOWLIST"];
-    const shellAllowlist = envShellAllowlistRaw !== undefined
-        ? envShellAllowlistRaw.split(",").map((b) => b.trim()).filter((b) => b.length > 0)
-        : fileConfig.shellAllowlist;
-    // v1.0 Gate #7 — filesystem path allowlist (env > config.json), same shape as
-    // SKILLSCRIPT_SHELL_ALLOWLIST. Default-deny when unset.
-    const envFsAllowlistRaw = process.env["SKILLSCRIPT_FS_ALLOWLIST"];
-    const fsAllowlist = envFsAllowlistRaw !== undefined
-        ? envFsAllowlistRaw.split(",").map((p) => p.trim()).filter((p) => p.length > 0)
-        : fileConfig.fsAllowlist;
-    // v0.19.0 — event ingress (memory `ceaf4579`). Two env knobs:
-    //   - SKILLSCRIPT_EVENT_INGRESS_ENABLED=true  (opt-in; default off)
-    //   - SKILLSCRIPT_EVENT_INGRESS_AUTH_TOKEN=… (optional bearer-token;
-    //     when set, every POST /event requires Authorization: Bearer <token>)
-    const envEventIngressEnabled = process.env["SKILLSCRIPT_EVENT_INGRESS_ENABLED"];
-    const eventIngressEnabled = envEventIngressEnabled !== undefined
-        ? envEventIngressEnabled === "true"
-        : false;
-    const eventIngressAuthToken = process.env["SKILLSCRIPT_EVENT_INGRESS_AUTH_TOKEN"];
-    const wired = bootstrap({
-        skillsDir: fileConfig.skillsDir ?? SKILLS_DIR,
-        traceDir: fileConfig.traceDir ?? TRACE_DIR,
-        dataDbPath: fileConfig.dataDbPath ?? DATA_DB,
-        triggersFilePath,
-        connectorsConfigPath,
+    // v0.23.x — the env-cascade + bootstrap + DashboardServer assembly lives in
+    // the reusable `bootstrapFromEnv()` (so programmatic adopters wire it
+    // identically). The CLI is a thin wrapper: CLI flags become explicit
+    // overrides (highest precedence), then start + handle shutdown.
+    const portFlag = extractFlag(args, "--port");
+    const { wired, server } = await bootstrapFromEnv({
         mode: opts.mode,
-        ...(pollIntervalSeconds !== undefined ? { pollIntervalSeconds } : {}),
-        ...(absoluteTimeoutMs !== undefined ? { absoluteTimeoutMs } : {}),
-        ...(maxRecursionDepth !== undefined ? { maxRecursionDepth } : {}),
-        ...(shellAllowlist !== undefined ? { shellAllowlist } : {}),
-        ...(fsAllowlist !== undefined ? { fsAllowlist } : {}),
-        ...(enableUnsafeShell !== undefined ? { enableUnsafeShell } : {}),
-        ...(forceAlwaysDraft === true ? { forceAlwaysDraft: true } : {}),
-        // Scheduler-fired skills record traces by default; `fires` / `health` /
-        // `health_metrics` (MCP) all read from the trace store.
-        trace: { mode: "on" },
+        home: HOME_DIR,
+        ...(extractFlag(args, "--config") !== undefined ? { configPath: extractFlag(args, "--config") } : {}),
+        ...(extractFlag(args, "--connectors") !== undefined ? { connectorsConfigPath: extractFlag(args, "--connectors") } : {}),
+        ...(portFlag !== undefined ? { port: parseInt(portFlag, 10) } : {}),
+        ...(extractFlag(args, "--host") !== undefined ? { host: extractFlag(args, "--host") } : {}),
     });
-    // Register declarative `# Triggers:` headers BEFORE arming the tick loop
-    // so the first tick can fire any minute-aligned cron entries.
-    await wireDeclarativeTriggers(wired);
-    // v0.20.1 — when secured mode is armed, loudly flag any stored skill that's
-    // Approved-but-unsigned (e.g. a pre-secured v1 corpus) so the operator runs
-    // `reapprove` instead of discovering refusals skill-by-skill at runtime.
-    await warnStaleApprovals(wired.skillStore);
     wired.scheduler.start();
-    // v0.2.7: dashboard mounts the SPA; serve runs headless on /rpc only.
-    const server = new DashboardServer({
-        mcpServer: wired.mcpServer,
-        port,
-        bindAddress: host,
-        mountSpa: opts.mode === "dashboard",
-        ...(mcpCallerIdentityHeader !== undefined ? { mcpCallerIdentityHeader } : {}),
-        // v0.19.0 — event ingress, off-by-default, scheduler reference required
-        eventIngressEnabled,
-        ...(eventIngressAuthToken !== undefined ? { eventIngressAuthToken } : {}),
-        // Scheduler is passed unconditionally: the /event route is gated on
-        // eventIngressEnabled, but the dashboard /approve route also needs the
-        // scheduler to re-register a skill's declarative triggers on approval
-        // (without it, dashboard-approved cron/event skills don't fire / don't
-        // show in the Triggers view).
-        scheduler: wired.scheduler,
-        // v0.20.2 — in-browser approval (passcode session-unlock). Mounts /unlock +
-        // /approve only when SKILLSCRIPT_APPROVAL_PASSCODE is set + secured + keyed.
-        skillStore: wired.skillStore,
-        approvalKeyFile: process.env["SKILLSCRIPT_APPROVAL_KEY_FILE"] ?? defaultApprovalKeyFile(),
-    });
     await server.start();
     const label = opts.mode === "dashboard" ? "dashboard" : "serve (headless)";
-    process.stdout.write(`skillfile ${label} running on http://${host}:${port}\nctrl-C to stop\n`);
+    process.stdout.write(`skillfile ${label} running on http://${server.boundAddress()}:${server.boundPort()}\nctrl-C to stop\n`);
     await new Promise((resolve) => {
         let shuttingDown = false;
         const shutdown = () => {
@@ -1213,6 +1063,9 @@ async function cmdRuntimeHost(args, opts) {
             void (async () => {
                 await wired.scheduler.stop();
                 await server.stop();
+                // Reap connector child processes (stdio-bridged MCP servers) so they
+                // don't orphan to a dead parent across restarts.
+                await wired.registry.disposeAll();
                 resolve();
             })();
         };
@@ -1221,6 +1074,8 @@ async function cmdRuntimeHost(args, opts) {
     });
     return 0;
 }
+// Retired: the body below is superseded by bootstrapFromEnv(); kept only as a
+// marker so the diff is legible. Removed in the edit that follows.
 async function cmdFires(args) {
     const skill = args.find((a) => !a.startsWith("--"));
     if (skill === undefined) {