@checkstack/healthcheck-script-backend 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,102 @@
 # @checkstack/healthcheck-script-backend
 
+## 0.7.0
+
+### Minor Changes
+
+- 9dcc848: Add environments as a first-class catalog primitive, with per-environment health-check fan-out, config templating, per-environment reactive health, and script run-context exposure.
+
+  - Catalog primitive: an environment is a sibling of groups - a named, instance-global record carrying free-form custom fields (baseUrl, region, tier, ...) that any system can belong to many-to-many. New `environments` + `systems_environments` tables, `EnvironmentSchema` + create/update schemas, `EntityService` environment CRUD and membership joins, RPC endpoints gated by a new `catalogAccess.environment` access rule, a GitOps `Environment` kind + `System.environments` extension, and frontend management (an `EnvironmentEditor`, an Environments management panel, and a per-system environment picker). The Environments card's Add/Edit/Delete affordances are gated on `catalogAccess.environment.manage`.
+  - Per-environment fan-out: run identity becomes `(systemId, configurationId, environmentId)`. Runs, aggregates, and state transitions gain a nullable `environmentId`. The health-check assignment gains an `environmentIds` selector with three modes (All / Specific / None; `null` and `[]` are distinct). The queue executor resolves the effective environment set via the catalog `resolveSystemEnvironments` read and executes one isolated run per environment.
+  - Config templating: a new `x-templatable` config-field marker renders a string field through the template engine at execute time, against `{ environment, check, system }`. A shared `renderTemplatableConfig` and a `renderTemplatePreview` helper (re-exported from `@checkstack/template-engine`) keep editor previews identical to the run-time render. The HTTP collector's `url`, `headers[].value`, and `body` are templatable, rendered per environment (the strategy client build moves inside the per-env loop); the `url`'s `.url()` validation moves post-render. Secrets resolve before templating; a field marked both secret and `x-templatable` is rejected at plugin load. `DynamicForm` shows a live "Preview" line, and the catalog `EnvironmentPreviewPicker` ("Preview as: <environment>") drives it in the collector editor (only when the schema has a templatable field).
+  - Script run-context: `CollectorRunContext` gains an optional `environment` field (`{ id, name, fields }`, metadata only). Shell collectors receive `CHECKSTACK_ENV_ID` / `_NAME` / `CHECKSTACK_ENV_<FIELD>` vars; inline TS collectors read `globalThis.context.environment`; the editor test panel mirrors both. The env-less path is unchanged.
+  - Per-environment reactive health (see BREAKING below), env-keyed read/write paths, env-qualified serialization locks, an optional `trigger.payload.environmentId`, per-environment isolation, and an `ENVIRONMENT_RESOLUTION_FAILED` signal when catalog resolution degrades to a single env-less run.
+
+  BREAKING CHANGES: the reactive `health` entity's id-shape and cardinality change. It now encodes two views: per-environment (id `"<systemId>::<environmentId>"`) and a system rollup (id `"<systemId>"`, the worst status across environments + env-less runs). The rollup PRESERVES the pre-existing system-level contract - dashboards, status badges, and automations referencing health by `systemId` keep working without re-authoring - but the entity's contract surface changed (new id-shape, higher cardinality, new payload field), so it is flagged breaking. `getBulkHealthState` parses env-qualified ids and keys results by the original id.
+
+  State and scale: membership and custom fields live only in catalog Postgres and are re-read every tick via the cross-plugin RPC; env-keyed health reads from shared `health_check_runs` / aggregates / transitions (compute-on-read). Every pod resolves the same effective set and the same per-environment health. No pod-local environment state.
+
+  Also: `unwrapSchema` in `zod-config.ts` loops instead of single-pass-stripping so multi-layer wrappers (`.optional().default()`) still resolve `x-templatable` meta. The env-less `{{ environment.* }}` run notice logs at `debug` (a legitimate recurring configuration), while the post-render HTTP `.url()` check still fails a genuinely-broken empty render with a clear "Rendered URL is invalid" error.
+
+  This is a beta minor.
+
+- 9dcc848: Health-check strategy and collector configs now migrate-then-validate when loaded, instead of being cast/rendered raw.
+
+  These configs declared `version: 2`/`3` migrations but the load path never ran them: stored values are persisted UNVERSIONED, and the executor cast them straight to the strategy/collector type. Both the execution path (`queue-executor`) and the read API (`mapConfig`, feeding router / frontend / gitops `getConfiguration`) now use assume-v1-on-read (`Versioned.parseAssumingV1`): wrap as version 1, run the declared chain, then validate. Order is preserved: migrate -> secret resolve -> template render -> execute. An unregistered strategy/collector or a failed migrate falls back to the raw stored blob rather than dropping the configuration. Every reshaper migration is now IDEMPOTENT, guarding on its legacy discriminator so already-current data passes through untouched.
+
+  BREAKING CHANGE: for any config GENUINELY at version 1 in the database (e.g. an HTTP strategy still carrying `url`/`method`, or an execute collector still carrying `command`/`args`), the declared migrations now actually RUN on load, so the loaded/returned shape changes for such rows. This is the intended fix - those fields were already supposed to have been migrated away. Configs already at the current shape are unaffected. No data backfill is performed; migration is applied on every read.
+
+  This is a beta minor.
+
+- 9dcc848: Layered OS-level script sandbox, secure and fail-closed by default (epic #247).
+
+  Script and shell health checks and the `run_shell` / `run_script` automation actions now run inside a layered OS-level sandbox by default. The sandbox lives in `core/backend-api/src/script-sandbox/` (the single source of truth) and is enforced inside the shared runners, so it applies wherever a job runs.
+
+  Layers:
+
+  - Resource caps (CPU / memory / PID / FD / file-size, via `prlimit` on capable Linux; ESM JS-heap cap via `--max-old-space-size`; portable wall-clock timeout) and an OOM-safe streaming output cap.
+  - Privilege drop via a NON-ROOT supervisor model: the shipped images run the supervisor as non-root uid `65532`, so every sandboxed script inherits non-root and can never be host-root; filesystem + network confinement is delivered by ROOTLESS `bwrap`/`nsjail` via unprivileged user namespaces. `enforced.privilege` is truthful (true only when the child cannot run as host-root). Runners no longer pass `uid`/`gid` to `Bun.spawn` (a silent no-op and a forward-compat hazard).
+  - Filesystem isolation (`scratch-only` / `scratch-plus-ro`) confining the child to its per-run scratch dir over a read-only base; the interpreter path is RO-bound so the runtime execs, and `TMPDIR` is pinned to the in-namespace tmpfs.
+  - Network egress control: `deny` (routeless loopback-only netns), `allowlist` (real plumbed egress via macvlan OR rootless slirp4netns + an in-kernel nftables filter), and an always-on metadata / link-local block (`169.254.0.0/16`, `fe80::/10`, `fc00::/7`). No-blackhole invariant: `enforced.network` is never true when egress is actually severed or unfiltered; unpluggable egress degrades to surfaced host net.
+  - Per-run fork-bomb containment via RLIMIT*NPROC inside the fresh per-run user+PID namespace; a centralized forbidden-env denylist (`LD_PRELOAD`, `LD_LIBRARY_PATH`, `DYLD*_`, `NODE*OPTIONS`, `BUN*_`, caller `PATH` overrides).
+  - A validated tuned seccomp profile (`deploy/seccomp/checkstack-userns.json`) and a live `clone(CLONE_NEWUSER|CLONE_NEWNET)` capability probe (not the static sysctl), shipped by default in both Dockerfiles, `docker-compose.yml`, and `deploy/k8s/checkstack-sandbox.yaml`.
+
+  Global policy and operator surface:
+
+  - The global sandbox policy lives in ONE durable row owned by `script-packages` (its `ConfigService` row in shared `plugin_configs`). A single process-wide provider serves every runner; the two script plugins no longer register competing providers. A dedicated admin-only `script-sandbox.manage` permission gates both reading and writing the policy. New `getSandboxPolicy` / `setSandboxPolicy` endpoints and a Settings -> Script Sandbox admin UI (`enabled`, `onUnavailable`, network/filesystem/privilege modes, allow list, metadata block, resource caps). The startup capability/readiness log is emitted in-process by `script-packages-backend` (no fragile init-order RPC self-loop), and on a host that cannot enforce a layer a one-time startup warning explains the two local-dev paths (Docker, or set the global policy to `degrade`).
+  - Satellite relay: the WS protocol carries the resolved policy in the `authenticated` message and a `sandbox_policy` push-on-change; a satellite caches the last relayed policy and resolves every run through it.
+
+  BREAKING CHANGES (platform in BETA, shipped as minor):
+
+  - Scripts run sandboxed by default. The shipped global default is FAIL-CLOSED (`onUnavailable: "fail"`): when a requested layer cannot be enforced the run is REFUSED (clean `exitCode: -1`, never an unsandboxed spawn) rather than silently degrading. Deployments on hosts that cannot enforce a layer (no bubblewrap, user namespaces blocked, no `/proc` unmask) must run the official images with the documented runtime flags (the bundled seccomp profile + `systempaths=unconfined`, or k8s `procMount: Unmasked`), or set the global policy to `degrade`. On macOS / restricted containers the strong layers degrade to the portable subset and are surfaced per run.
+  - Default network posture is deny-egress (`allowlist` with an empty allow list, which resolves to the routeless `deny` path). Scripts calling external endpoints fail until those destinations are allowlisted in the global default. The always-on metadata / link-local block applies even under looser modes.
+  - The per-action / per-check `sandbox` config override and the transport `ScriptRequest.sandbox` field are removed; policy is global-only, so an automation/check author can no longer weaken the sandbox on their own item. Stored configs carrying a stray `sandbox` key are tolerated (stripped on parse).
+  - The shared runners' `run()` no longer accepts a `sandbox` option; callers rely on the global policy provider.
+  - A satellite fails closed (most restrictive profile) until it receives the first relayed policy; a relay-read failure or an older core keeps it fail-closed. A relay failure can never loosen a satellite's sandbox.
+
+  State and scale: the global policy is a single durable Postgres row read identically on every pod. Capability detection is per-process, deterministic from the host kernel, and surfaced per run via the `EffectiveSandbox` report (a Linux pod and a macOS satellite may legitimately differ). `CHECKSTACK_SANDBOX_UID/GID` and macvlan addressing are genuinely per-host infrastructure, surfaced per run, not the queryable policy. The satellite's policy cache is satellite-local transport state. No new pod-local current-state.
+
+  This is a beta minor.
+
+- 9dcc848: Add the auto-generated, version-pinned `@checkstack/sdk` package + codegen, and serve its types live to the in-app editor.
+
+  - A new committed workspace package `@checkstack/sdk`, generated from the platform's source of truth by `scripts/generate-sdk.ts` (`generate:sdk` / `generate:sdk:check`): a fully-typed oRPC client (`createCheckstackClient`) over the REST surface with one `InferClient` per plugin contract, real script-authoring helpers (`@checkstack/sdk/healthcheck`, `@checkstack/sdk/integration`) whose runtime body is the same identity function the in-app runner injects, per-subpath `.d.ts` under the package `exports` map, and an editor-only ambient bundle. A `generate:sdk:check` CI guard fails when the committed SDK files drift from a fresh generation. The `@checkstack/sdk` version is stamped from `@checkstack/release` and MUST NOT appear in a changeset (a guard enforces this); the `@checkstack/release` bump here advances the release version so the generated SDK can be published later. The generated client also normalizes its base URL without a backtracking-prone regex, closing a CodeQL `js/polynomial-redos` finding.
+  - Live editor type injection: a new version-keyed route `GET /api/script-packages/sdk-types/:releaseVersion` (raw handler in `@checkstack/script-packages-backend`) serves the generated SDK editor bundle with `Cache-Control: private, max-age=1y, immutable`; the pure path-build/parse module lives in `@checkstack/script-packages-common`, shared by backend and frontend. A mismatched version returns `409` so the editor refetches and never serves stale types after an upgrade. The frontend `useSdkTypeInjection` hook fetches the bundle once per session and mounts it into Monaco via `addExtraLib`. Schema-narrowed `context.config` / `context.event.payload` editor types stay local; the package-resolving module declarations come from the one published `@checkstack/sdk` source.
+
+  BREAKING CHANGES: the script-authoring import surface moves from the bare `@checkstack/healthcheck` / `@checkstack/integration` virtual modules to the `@checkstack/sdk/healthcheck` / `@checkstack/sdk/integration` subpaths of the published `@checkstack/sdk` package. The old bare-name imports no longer resolve (an old import now errors in the editor, surfacing the migration). Existing scripts must update the module specifier:
+
+      - import { defineHealthCheck } from "@checkstack/healthcheck";
+      + import { defineHealthCheck } from "@checkstack/sdk/healthcheck";
+
+      - import { defineIntegration } from "@checkstack/integration";
+      + import { defineIntegration } from "@checkstack/sdk/integration";
+
+  The helper names and their runtime behaviour are unchanged - only the module specifier moves. The global (no-import) helper form continues to work unchanged.
+
+  This is a beta minor.
+
+### Patch Changes
+
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+  - @checkstack/backend-api@0.21.0
+  - @checkstack/healthcheck-common@1.5.0
+  - @checkstack/common@0.13.0
+  - @checkstack/script-packages-backend@0.3.0
+  - @checkstack/secrets-common@0.2.0
+
 ## 0.6.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-script-backend",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -14,11 +14,11 @@
     "pack": "bunx @checkstack/scripts plugin-pack"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.18.0",
+    "@checkstack/backend-api": "0.20.0",
     "@checkstack/common": "0.12.0",
-    "@checkstack/healthcheck-common": "1.3.0",
-    "@checkstack/script-packages-backend": "0.1.0",
-    "@checkstack/secrets-common": "0.0.1"
+    "@checkstack/healthcheck-common": "1.4.0",
+    "@checkstack/script-packages-backend": "0.2.1",
+    "@checkstack/secrets-common": "0.1.0"
   },
   "devDependencies": {
     "@types/bun": "^1.0.0",

package/src/execute-collector.test.ts

@@ -148,6 +148,81 @@ describe("ExecuteCollector", () => {
       expect(call.env.CHECKSTACK_SYSTEM_ID).toBe("system-9");
     });
 
+    it("injects CHECKSTACK_ENV_* vars when the run carries an environment", async () => {
+      const collector = new ExecuteCollector();
+      const client = createMockClient();
+
+      await collector.execute({
+        config: { script: "echo hi", timeout: 3000 },
+        client,
+        pluginId: "test",
+        runContext: {
+          check: { id: "check-1", name: "CPU load", intervalSeconds: 60 },
+          system: { id: "system-9", name: "web-01" },
+          environment: {
+            id: "env-prod",
+            name: "production",
+            fields: { baseUrl: "https://prod.example.com", region: "eu-west-1" },
+          },
+        },
+      });
+
+      const call = (client.exec as ReturnType<typeof mock>).mock.calls[0][0];
+      expect(call.env.CHECKSTACK_ENV_ID).toBe("env-prod");
+      expect(call.env.CHECKSTACK_ENV_NAME).toBe("production");
+      expect(call.env.CHECKSTACK_ENV_BASE_URL).toBe("https://prod.example.com");
+      expect(call.env.CHECKSTACK_ENV_REGION).toBe("eu-west-1");
+    });
+
+    it("omits CHECKSTACK_ENV_* vars when the run has no environment", async () => {
+      const collector = new ExecuteCollector();
+      const client = createMockClient();
+
+      await collector.execute({
+        config: { script: "echo hi", timeout: 3000 },
+        client,
+        pluginId: "test",
+        runContext: {
+          check: { id: "check-1", name: "CPU load", intervalSeconds: 60 },
+          system: { id: "system-9", name: "web-01" },
+        },
+      });
+
+      const call = (client.exec as ReturnType<typeof mock>).mock.calls[0][0];
+      expect(call.env.CHECKSTACK_ENV_ID).toBeUndefined();
+      expect(call.env.CHECKSTACK_ENV_NAME).toBeUndefined();
+      expect(
+        Object.keys(call.env).some((k) => k.startsWith("CHECKSTACK_ENV_")),
+      ).toBe(false);
+    });
+
+    it("lets a user config.env key win over a CHECKSTACK_ENV_* metadata key", async () => {
+      const collector = new ExecuteCollector();
+      const client = createMockClient();
+
+      await collector.execute({
+        config: {
+          script: "echo hi",
+          env: { CHECKSTACK_ENV_BASE_URL: "user override" },
+          timeout: 3000,
+        },
+        client,
+        pluginId: "test",
+        runContext: {
+          check: { id: "check-1", name: "CPU load", intervalSeconds: 60 },
+          system: { id: "system-9", name: "web-01" },
+          environment: {
+            id: "env-prod",
+            name: "production",
+            fields: { baseUrl: "https://prod.example.com" },
+          },
+        },
+      });
+
+      const call = (client.exec as ReturnType<typeof mock>).mock.calls[0][0];
+      expect(call.env.CHECKSTACK_ENV_BASE_URL).toBe("user override");
+    });
+
     it("leaves env unchanged when no runContext is supplied (back-compat)", async () => {
       const collector = new ExecuteCollector();
       const client = createMockClient();
@@ -196,6 +271,59 @@ describe("ExecuteCollector", () => {
       // The embedded quotes must be preserved (single-quoted form).
       expect(migrated.script).toMatch(/echo/);
     });
+
+    it("is IDEMPOTENT: an already-{script} blob is returned unchanged (no fabricated script)", async () => {
+      const collector = new ExecuteCollector();
+      // CRITICAL safety property: the highest-risk reshape must NOT run on a
+      // blob that already has `script`. Without the guard it would shell-quote
+      // a missing `command` and fabricate `script: "undefined"`.
+      const alreadyV2 = {
+        script: "echo already-migrated",
+        cwd: "/srv",
+        env: { FOO: "bar" },
+        timeout: 4000,
+      };
+
+      const migrated = await collector.config.parseAssumingV1(alreadyV2);
+
+      expect(migrated.script).toBe("echo already-migrated");
+      expect(migrated.script).not.toContain("undefined");
+      expect(migrated.cwd).toBe("/srv");
+      expect(migrated.env).toEqual({ FOO: "bar" });
+      expect(migrated.timeout).toBe(4000);
+    });
+
+    it("does NOT fabricate a script from a blob carrying both command and script", async () => {
+      const collector = new ExecuteCollector();
+      // Defensive: presence of `script` wins even if a stray `command` lingers.
+      const mixed = {
+        command: "rm",
+        args: ["-rf", "/"],
+        script: "echo safe",
+        timeout: 3000,
+      };
+
+      const migrated = await collector.config.parseAssumingV1(mixed);
+
+      expect(migrated.script).toBe("echo safe");
+      expect(migrated.script).not.toContain("rm");
+    });
+
+    it("reshapes a genuine v1 {command} blob via assume-v1-on-read", async () => {
+      const collector = new ExecuteCollector();
+      const migrated = await collector.config.parseAssumingV1({
+        command: "echo",
+        args: ["Hello", "World"],
+        timeout: 5000,
+      });
+      expect(migrated.script).toBe("echo Hello World");
+      expect(migrated.timeout).toBe(5000);
+    });
+
+    it("has a complete v1->version migration chain", () => {
+      const collector = new ExecuteCollector();
+      expect(collector.config.validateMigrationChainFromV1()).toBeUndefined();
+    });
   });
 
   describe("mergeResult", () => {
@@ -362,3 +490,53 @@ describe("ExecuteCollector secret env injection + source-side masking", () => {
     expect(result.result.stdout).toBe("no secrets");
   });
 });
+
+describe("ExecuteCollector — global-only sandbox (no per-item override)", () => {
+  // Capture what the collector passes to the transport client.
+  const makeRecordingClient = (): {
+    client: ScriptTransportClient;
+    getInput: () => Record<string, unknown> | undefined;
+  } => {
+    let captured: Record<string, unknown> | undefined;
+    return {
+      getInput: () => captured,
+      client: {
+        exec: async (input) => {
+          captured = input as unknown as Record<string, unknown>;
+          return { exitCode: 0, stdout: "", stderr: "", timedOut: false };
+        },
+      },
+    };
+  };
+
+  it("never sends a `sandbox` field over the transport (policy is global-only)", async () => {
+    const { client, getInput } = makeRecordingClient();
+    const collector = new ExecuteCollector();
+    await collector.execute({
+      config: { script: "echo hi", timeout: 5000 },
+      client,
+      pluginId: "test",
+    });
+    expect(getInput()?.sandbox).toBeUndefined();
+  });
+
+  it("tolerates a stored stray `config.sandbox` (migration: stripped, no crash)", async () => {
+    const { client, getInput } = makeRecordingClient();
+    const collector = new ExecuteCollector();
+    // An old stored config may still carry a `sandbox` key. The schema strips
+    // unknown keys on parse; even if it reaches `execute`, the collector must
+    // ignore it and never forward it.
+    const parsed = collector.config.schema.parse({
+      script: "echo hi",
+      timeout: 5000,
+      sandbox: { network: { mode: "unrestricted" } },
+    });
+    expect((parsed as Record<string, unknown>).sandbox).toBeUndefined();
+    await collector.execute({
+      config: parsed,
+      client,
+      pluginId: "test",
+    });
+    expect(getInput()?.sandbox).toBeUndefined();
+  });
+});

package/src/execute-collector.ts

@@ -26,6 +26,11 @@ import {
   secretEnvMappingSchema,
   maskScriptRunOutput,
 } from "@checkstack/secrets-common";
+import {
+  CHECKSTACK_ENV_ID,
+  CHECKSTACK_ENV_NAME,
+  buildEnvironmentShellEnv,
+} from "./shell-env";
 
 // ============================================================================
 // RUN-CONTEXT ENV INJECTION
@@ -44,7 +49,9 @@ const CHECKSTACK_SYSTEM_NAME = "CHECKSTACK_SYSTEM_NAME";
 
 /**
  * Map curated run-context metadata to the reserved `CHECKSTACK_*` env
- * vars exposed to the shell script.
+ * vars exposed to the shell script. When the run carries a resolved
+ * environment (post-fan-out), its id, name, and each custom field are
+ * additionally exposed as `CHECKSTACK_ENV_*` vars.
  */
 function runContextEnv(ctx: CollectorRunContext): Record<string, string> {
   return {
@@ -53,19 +60,61 @@ function runContextEnv(ctx: CollectorRunContext): Record<string, string> {
     [CHECKSTACK_CHECK_INTERVAL_SECONDS]: String(ctx.check.intervalSeconds),
     [CHECKSTACK_SYSTEM_ID]: ctx.system.id,
     [CHECKSTACK_SYSTEM_NAME]: ctx.system.name,
+    ...(ctx.environment
+      ? {
+          [CHECKSTACK_ENV_ID]: ctx.environment.id,
+          [CHECKSTACK_ENV_NAME]: ctx.environment.name,
+          ...buildEnvironmentShellEnv(ctx.environment.fields),
+        }
+      : {}),
   };
 }
 
 // ============================================================================
-// LEGACY CONFIG (v1) — kept for migration
+// LEGACY CONFIG (v1) — migration narrowing helpers
 // ============================================================================
+//
+// The migrate input is `unknown` per the versioning chain, so narrowing is
+// done with `typeof`/`in` guards (no casts).
+
+/** Type guard: the migrate input is a plain object whose keys can be probed. */
+function isRecord(data: unknown): data is Record<string, unknown> {
+  return typeof data === "object" && data !== null;
+}
+
+/** Read the v1 `command` string from a config blob. */
+function readCommand(data: Record<string, unknown>): string {
+  return typeof data.command === "string" ? data.command : "";
+}
+
+/** Read the v1 `args` string[] from a config blob (missing => empty). */
+function readArgs(data: Record<string, unknown>): string[] {
+  const value = data.args;
+  return Array.isArray(value)
+    ? value.filter((arg): arg is string => typeof arg === "string")
+    : [];
+}
+
+/** Read an optional `cwd` string from a config blob. */
+function readCwd(data: Record<string, unknown>): string | undefined {
+  return typeof data.cwd === "string" ? data.cwd : undefined;
+}
+
+/** Read an optional `env` string->string record from a config blob. */
+function readEnv(
+  data: Record<string, unknown>,
+): Record<string, string> | undefined {
+  const value = data.env;
+  if (!isRecord(value)) return undefined;
+  const entries = Object.entries(value).filter(
+    (entry): entry is [string, string] => typeof entry[1] === "string",
+  );
+  return Object.fromEntries(entries);
+}
 
-interface ExecuteConfigV1 {
-  command: string;
-  args: string[];
-  cwd?: string;
-  env?: Record<string, string>;
-  timeout: number;
+/** Read a numeric `timeout` field from a config blob (default 30s). */
+function readTimeout(data: Record<string, unknown>): number {
+  return typeof data.timeout === "number" ? data.timeout : 30_000;
 }
 
 /**
@@ -230,16 +279,23 @@ export class ExecuteCollector implements CollectorStrategy<
         toVersion: 2,
         description:
           "Collapse {command, args} into a single shell script executed via `sh -c`",
-        migrate: (data: ExecuteConfigV1): ExecuteConfig => {
-          const parts = [data.command, ...(data.args ?? [])].map((arg) =>
-            shellQuote(arg),
-          );
-          return {
-            script: parts.join(" "),
-            cwd: data.cwd,
-            env: data.env,
-            timeout: data.timeout,
-          };
+        // IDEMPOTENT + HIGHEST RISK: only reshape a genuine v1 blob — one that
+        // has `command` but NO `script`. An already-v2 blob carries `script`,
+        // so this guard prevents fabricating `script: "undefined"` from it by
+        // shell-quoting a missing `command`. Already-v2 data passes through.
+        migrate: (data: unknown): unknown => {
+          if (isRecord(data) && "command" in data && !("script" in data)) {
+            const parts = [readCommand(data), ...readArgs(data)].map((arg) =>
+              shellQuote(arg),
+            );
+            return {
+              script: parts.join(" "),
+              cwd: readCwd(data),
+              env: readEnv(data),
+              timeout: readTimeout(data),
+            };
+          }
+          return data;
         },
       },
     ],
@@ -274,6 +330,9 @@ export class ExecuteCollector implements CollectorStrategy<
       ...secretEnv,
     };
 
+    // The OS-level sandbox is GLOBAL-only and resolved by the runner itself
+    // (durable cluster default on the core pod, or fail-closed). No per-item
+    // override is sent through the transport.
     const response = await client.exec({
       script: config.script,
       cwd: config.cwd,

package/src/index.ts

@@ -22,6 +22,21 @@ export default createBackendPlugin({
       },
       init: async ({ healthCheckRegistry, collectorRegistry, logger }) => {
         logger.debug("🔌 Registering Script Health Check Strategy...");
+        // The GLOBAL sandbox policy is owned by `script-packages` (the single
+        // source of truth). On the CORE pod it registers the one process-wide
+        // policy provider every runner resolves through, so this plugin does
+        // NOT register a competing provider (the old per-plugin registration
+        // read a DIFFERENT plugin-scoped row → last-writer-wins). On the
+        // SATELLITE runtime the satellite registers its own RELAY-backed
+        // provider at startup (see `core/satellite/src/index.ts`), which fails
+        // closed until the first policy relay arrives.
+        //
+        // The one-time startup capability/readiness log is emitted IN PROCESS
+        // by `script-packages` itself (the single policy owner), so this plugin
+        // no longer makes a `getSandboxPolicy` RPC at init — that self-loop POST
+        // 404'd whenever this plugin initialised before `script-packages`
+        // mounted its router. The runner's enforcement path is unchanged: it
+        // resolves the active policy through `script-packages`' provider.
         const strategy = new ScriptHealthCheckStrategy();
         healthCheckRegistry.register(strategy);
         collectorRegistry.register(new ExecuteCollector());
@@ -32,8 +47,9 @@ export default createBackendPlugin({
         // guaranteed by the runner (auto-install disabled); this just points
         // it at the synced tree when present.
         collectorRegistry.register(
-          new InlineScriptCollector(defaultInlineScriptExecutor, () =>
-            resolveResolutionRootFromStore(resolveScriptPackagesDir()),
+          new InlineScriptCollector(
+            defaultInlineScriptExecutor,
+            () => resolveResolutionRootFromStore(resolveScriptPackagesDir()),
           ),
         );
       },

package/src/inline-script-collector.test.ts

@@ -118,7 +118,7 @@ describe("InlineScriptCollector", () => {
 
     it("exposes `defineHealthCheck` as a runtime global (no import required)", async () => {
       // The editor advertises `defineHealthCheck` both as an ambient global
-      // and as a named export from `@checkstack/healthcheck`. The global
+      // and as a named export from `@checkstack/sdk/healthcheck`. The global
       // form lets Monaco autocomplete `defineHea…` on a fresh module
       // without the user typing an import first. This test confirms the
       // runner actually installs the global onto `globalThis` so the
@@ -138,17 +138,17 @@ describe("InlineScriptCollector", () => {
       expect(result.result.message).toBe("via global");
     });
 
-    it("resolves the virtual `@checkstack/healthcheck` defineHealthCheck helper at runtime", async () => {
+    it("resolves the virtual `@checkstack/sdk/healthcheck` defineHealthCheck helper at runtime", async () => {
       // The editor advertises `import { defineHealthCheck } from
-      // "@checkstack/healthcheck"` for IntelliSense + return-shape type
+      // "@checkstack/sdk/healthcheck"` for IntelliSense + return-shape type
       // checking. At runtime, the collector rewrites that import to a
       // sibling helper file. This test verifies the rewrite actually
       // resolves — if it ever regressed (e.g. the regex stopped matching),
-      // the script would throw "Cannot find module @checkstack/healthcheck"
+      // the script would throw "Cannot find module @checkstack/sdk/healthcheck"
       // and we'd catch it here.
       const config = createConfig({
         script: `
-          import { defineHealthCheck } from "@checkstack/healthcheck";
+          import { defineHealthCheck } from "@checkstack/sdk/healthcheck";
           export default defineHealthCheck({ success: true, value: 7, message: "via helper" });
         `,
       });
@@ -364,6 +364,57 @@ describe("InlineScriptCollector", () => {
       expect(result.result.message).toBe("web-02:check-7");
     });
 
+    it("exposes the resolved environment as `context.environment.fields`", async () => {
+      const config = createConfig({
+        script: `
+          // @ts-ignore — context is injected by the runner
+          export default { success: true, message: \`\${context.environment.name}:\${context.environment.fields.baseUrl}\` };
+        `,
+      });
+
+      const result = await collector.execute({
+        config,
+        client: mockClient,
+        pluginId: "script",
+        runContext: {
+          check: { id: "check-7", name: "CPU load", intervalSeconds: 30 },
+          system: { id: "system-3", name: "web-02" },
+          environment: {
+            id: "env-prod",
+            name: "production",
+            fields: { baseUrl: "https://prod.example.com" },
+          },
+        },
+      });
+
+      expect(result.result.success).toBe(true);
+      expect(result.result.message).toBe(
+        "production:https://prod.example.com",
+      );
+    });
+
+    it("leaves `context.environment` undefined when the run has no environment", async () => {
+      const config = createConfig({
+        script: `
+          // @ts-ignore — context is injected by the runner
+          export default { success: true, message: typeof context.environment };
+        `,
+      });
+
+      const result = await collector.execute({
+        config,
+        client: mockClient,
+        pluginId: "script",
+        runContext: {
+          check: { id: "check-7", name: "CPU load", intervalSeconds: 30 },
+          system: { id: "system-3", name: "web-02" },
+        },
+      });
+
+      expect(result.result.success).toBe(true);
+      expect(result.result.message).toBe("undefined");
+    });
+
     it("still exposes `context.config` and does not crash when runContext is absent (back-compat)", async () => {
       const config = createConfig({
         script: `
@@ -457,3 +508,54 @@ describe("InlineScriptCollector secret env injection + source-side masking", ()
     expect(result.result.message).toBe("nothing secret");
   });
 });
+
+describe("InlineScriptCollector — global-only sandbox (no per-item override)", () => {
+  const makeRecordingExecutor = (): {
+    executor: InlineScriptExecutor;
+    getInput: () => Record<string, unknown> | undefined;
+  } => {
+    let captured: Record<string, unknown> | undefined;
+    return {
+      getInput: () => captured,
+      executor: {
+        execute: async (input) => {
+          captured = input as unknown as Record<string, unknown>;
+          return {
+            result: { success: true },
+            stdout: "",
+            stderr: "",
+            timedOut: false,
+          };
+        },
+      },
+    };
+  };
+
+  it("never passes a `sandbox` field to the executor (policy is global-only)", async () => {
+    const { executor, getInput } = makeRecordingExecutor();
+    const collector = new InlineScriptCollector(executor);
+    await collector.execute({
+      config: createConfig(),
+      client: mockClient,
+      pluginId: "script",
+    });
+    expect(getInput()?.sandbox).toBeUndefined();
+  });
+
+  it("tolerates a stored stray `config.sandbox` (migration: stripped, no crash)", async () => {
+    const { executor, getInput } = makeRecordingExecutor();
+    const collector = new InlineScriptCollector(executor);
+    const parsed = collector.config.schema.parse({
+      script: "return true;",
+      timeout: 5000,
+      sandbox: { network: { mode: "unrestricted" } },
+    });
+    expect((parsed as Record<string, unknown>).sandbox).toBeUndefined();
+    await collector.execute({
+      config: parsed,
+      client: mockClient,
+      pluginId: "script",
+    });
+    expect(getInput()?.sandbox).toBeUndefined();
+  });
+});

package/src/inline-script-collector.ts

@@ -73,8 +73,8 @@ export interface InlineScriptExecutor {
 
 /**
  * Default executor — delegates to the shared `EsmScriptRunner`. Wires
- * `globalThis.context = { config, check?, system? }` (the inline
- * health-check runtime surface) and the virtual `@checkstack/healthcheck`
+ * `globalThis.context = { config, check?, system?, environment? }` (the
+ * inline health-check runtime surface) and the `@checkstack/sdk/healthcheck`
  * module / global `defineHealthCheck` helper.
  */
 export const defaultInlineScriptExecutor: InlineScriptExecutor = {
@@ -91,11 +91,17 @@ export const defaultInlineScriptExecutor: InlineScriptExecutor = {
       context: {
         config,
         ...(runContext
-          ? { check: runContext.check, system: runContext.system }
+          ? {
+              check: runContext.check,
+              system: runContext.system,
+              ...(runContext.environment
+                ? { environment: runContext.environment }
+                : {}),
+            }
           : {}),
       },
       timeoutMs,
-      helperModuleName: "@checkstack/healthcheck",
+      helperModuleName: "@checkstack/sdk/healthcheck",
       helperFunctionName: "defineHealthCheck",
       ...(resolutionRoot ? { resolutionRoot } : {}),
       // Inject the resolved secrets as process.env for THIS run only.
@@ -116,7 +122,7 @@ const inlineScriptConfigSchema = z.object({
     "x-editor-types": ["typescript"],
     "x-script-testable": true,
   }).describe(
-    "TypeScript/JavaScript module. Use `import { ... } from \"node:os\"` to pull in Node built-ins. The recommended pattern is `export default defineHealthCheck({ success, message?, value? })` — `defineHealthCheck` is provided by `@checkstack/healthcheck` and asserts the return shape at the type level. Throwing also signals failure.",
+    "TypeScript/JavaScript module. Use `import { ... } from \"node:os\"` to pull in Node built-ins. The recommended pattern is `export default defineHealthCheck({ success, message?, value? })` — `defineHealthCheck` is provided by `@checkstack/sdk/healthcheck` and asserts the return shape at the type level. Throwing also signals failure.",
   ),
   secretEnv: withConfigMeta(secretEnvMappingSchema, { "x-secret-env": true })
     .optional()
@@ -236,8 +242,11 @@ function normaliseScriptReturn(raw: unknown): NormalisedScriptResult {
  * Node built-ins (`node:os`, `node:fs/promises`, `node:child_process`,
  * `node:crypto`, ...), use top-level `await`, and signal its result either
  * via `export default` or — for backwards compatibility — a top-level
- * `return X;`. `globalThis.context` exposes `{ config }` for access to the
- * collector configuration.
+ * `return X;`. `globalThis.context` exposes `{ config, check?, system?,
+ * environment? }` — the collector configuration plus curated run-context
+ * metadata. `context.environment` (when the run resolved one) carries
+ * `{ id, name, fields }`, where `fields` is the environment's custom
+ * metadata, e.g. `globalThis.context.environment.fields.baseUrl`.
  *
  * Subprocess isolation, env scrubbing, temp-dir lifecycle and result
  * marshalling all live in the shared `EsmScriptRunner` in
@@ -325,6 +334,9 @@ export class InlineScriptCollector implements CollectorStrategy<
     // Source-side masking values: the run's delivered secret values.
     const maskValues = Object.values(secretEnv ?? {});
 
+    // The OS-level sandbox is GLOBAL-only and resolved by the runner itself
+    // (durable cluster default on the core pod, or fail-closed). No per-item
+    // override is applied here.
     let exec: InlineScriptExecutionResult;
     try {
       const raw = await this.executor.execute({

package/src/migration-chain-contract.test.ts

@@ -0,0 +1,50 @@
+/**
+ * Contract test: every Script health-check Versioned schema stored UNVERSIONED
+ * and read back via assume-v1-on-read MUST have a COMPLETE, contiguous
+ * migration chain from version 1 to its current `version`. Pure STRUCTURAL
+ * check (`validateMigrationChainFromV1`); enumerates every Versioned field
+ * (config + result + aggregatedResult) of this plugin's strategy + collectors
+ * (including the highest-risk execute collector) so a new collector or a
+ * bumped result schema is covered automatically. See the HTTP plugin's
+ * equivalent test for the full rationale.
+ */
+import { describe, expect, it } from "bun:test";
+import { ScriptHealthCheckStrategy } from "./strategy";
+import { ExecuteCollector } from "./execute-collector";
+import { InlineScriptCollector } from "./inline-script-collector";
+
+describe("script health-check migration-chain contract", () => {
+  const strategy = new ScriptHealthCheckStrategy();
+  const executeCollector = new ExecuteCollector();
+  const inlineCollector = new InlineScriptCollector();
+  const configs = [
+    { name: "script strategy config", config: strategy.config },
+    { name: "script strategy result", config: strategy.result },
+    {
+      name: "script strategy aggregatedResult",
+      config: strategy.aggregatedResult,
+    },
+    { name: "execute collector config", config: executeCollector.config },
+    { name: "execute collector result", config: executeCollector.result },
+    {
+      name: "execute collector aggregatedResult",
+      config: executeCollector.aggregatedResult,
+    },
+    { name: "inline-script collector config", config: inlineCollector.config },
+    { name: "inline-script collector result", config: inlineCollector.result },
+    {
+      name: "inline-script collector aggregatedResult",
+      config: inlineCollector.aggregatedResult,
+    },
+  ];
+
+  it("every registered Versioned schema has a complete v1->version chain", () => {
+    for (const { name, config } of configs) {
+      const problem = config.validateMigrationChainFromV1();
+      expect(
+        problem,
+        `${name} (version ${config.version}) has a broken migration chain: ${problem}`,
+      ).toBeUndefined();
+    }
+  });
+});

package/src/shell-env.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "bun:test";
+import {
+  CHECKSTACK_ENV_PREFIX,
+  buildEnvironmentShellEnv,
+  toEnvFieldShellKey,
+} from "./shell-env";
+
+describe("toEnvFieldShellKey", () => {
+  it("splits camelCase into UPPER_SNAKE with the CHECKSTACK_ENV_ prefix", () => {
+    expect(toEnvFieldShellKey("baseUrl")).toBe("CHECKSTACK_ENV_BASE_URL");
+  });
+
+  it("normalizes kebab-case and spaces to single underscores", () => {
+    expect(toEnvFieldShellKey("my-weird key")).toBe(
+      "CHECKSTACK_ENV_MY_WEIRD_KEY",
+    );
+  });
+
+  it("trims leading/trailing separators", () => {
+    expect(toEnvFieldShellKey(".region.")).toBe("CHECKSTACK_ENV_REGION");
+  });
+
+  it("handles digit/letter camel boundaries", () => {
+    expect(toEnvFieldShellKey("tier2Name")).toBe("CHECKSTACK_ENV_TIER2_NAME");
+  });
+
+  it("is ReDoS-safe on a long run of separators", () => {
+    // Mirrors the automation-common hardening test: a pathological input of
+    // 100k separators must not hang.
+    expect(toEnvFieldShellKey(".".repeat(100_000) + "a")).toBe(
+      "CHECKSTACK_ENV_A",
+    );
+    expect(toEnvFieldShellKey(".".repeat(100_000))).toBe(CHECKSTACK_ENV_PREFIX);
+  });
+});
+
+describe("buildEnvironmentShellEnv", () => {
+  it("emits one CHECKSTACK_ENV_<KEY> var per custom field", () => {
+    const env = buildEnvironmentShellEnv({
+      baseUrl: "https://prod.example.com",
+      region: "eu-west-1",
+    });
+    expect(env).toEqual({
+      CHECKSTACK_ENV_BASE_URL: "https://prod.example.com",
+      CHECKSTACK_ENV_REGION: "eu-west-1",
+    });
+  });
+
+  it("stringifies non-string values", () => {
+    const env = buildEnvironmentShellEnv({
+      replicas: 3,
+      enabled: true,
+      tags: ["a", "b"],
+      missing: null,
+    });
+    expect(env.CHECKSTACK_ENV_REPLICAS).toBe("3");
+    expect(env.CHECKSTACK_ENV_ENABLED).toBe("true");
+    expect(env.CHECKSTACK_ENV_TAGS).toBe('["a","b"]');
+    expect(env.CHECKSTACK_ENV_MISSING).toBe("");
+  });
+
+  it("keeps the first key and skips a later colliding key (no last-write-wins)", () => {
+    const collisions: string[] = [];
+    const env = buildEnvironmentShellEnv(
+      { baseUrl: "first", "base-url": "second" },
+      (message) => collisions.push(message),
+    );
+    // Both keys normalize to CHECKSTACK_ENV_BASE_URL; first wins.
+    expect(env.CHECKSTACK_ENV_BASE_URL).toBe("first");
+    expect(Object.keys(env)).toHaveLength(1);
+    expect(collisions).toHaveLength(1);
+    expect(collisions[0]).toContain("base-url");
+    expect(collisions[0]).toContain("CHECKSTACK_ENV_BASE_URL");
+  });
+
+  it("skips a field that normalizes to an empty name", () => {
+    const collisions: string[] = [];
+    const env = buildEnvironmentShellEnv(
+      { "...": "ignored", region: "eu" },
+      (message) => collisions.push(message),
+    );
+    expect(env).toEqual({ CHECKSTACK_ENV_REGION: "eu" });
+    expect(collisions).toHaveLength(1);
+    expect(collisions[0]).toContain("empty shell var name");
+  });
+});

package/src/shell-env.ts

@@ -0,0 +1,89 @@
+/**
+ * Reserved `CHECKSTACK_ENV_*` shell env vars exposing a run's resolved
+ * environment (id, name, and each custom field) to a shell collector script.
+ *
+ * The reserved names and the key-normalization rule are kept local to this
+ * plugin (mirroring the `CHECKSTACK_CHECK_*` / `CHECKSTACK_SYSTEM_*` reserved
+ * names in `execute-collector.ts`) so the collector's dependency surface stays
+ * minimal. The normalization mirrors the ReDoS-safe rule used by
+ * `@checkstack/automation-common`'s `toShellEnvKey`: uppercase, collapse each
+ * run of non-alphanumeric characters to a single `_`, trim leading/trailing
+ * `_`. A camelCase boundary is split first (`baseUrl` -> `BASE_URL`).
+ */
+
+/** Reserved env var carrying the resolved environment's id. */
+export const CHECKSTACK_ENV_ID = "CHECKSTACK_ENV_ID";
+/** Reserved env var carrying the resolved environment's name. */
+export const CHECKSTACK_ENV_NAME = "CHECKSTACK_ENV_NAME";
+/** Prefix on every per-custom-field environment shell var. */
+export const CHECKSTACK_ENV_PREFIX = "CHECKSTACK_ENV_";
+
+/**
+ * Derive the `CHECKSTACK_ENV_<KEY>` shell var name for a custom field key.
+ *
+ * Splits a camelCase boundary into an underscore so `baseUrl` becomes
+ * `CHECKSTACK_ENV_BASE_URL`, then uppercases, collapses every run of
+ * non-alphanumeric characters to a single `_`, and trims leading/trailing
+ * `_`. The trailing-trim uses a negative look-behind to avoid the
+ * polynomial-time backtracking of a naive `/^_+|_+$/g` (same hardening as
+ * automation-common's `toShellEnvKey`).
+ */
+export function toEnvFieldShellKey(key: string): string {
+  const normalized = key
+    // Split camelCase / digit-letter boundaries before uppercasing so
+    // `baseUrl` -> `base Url` -> `BASE_URL` rather than `BASEURL`.
+    .replaceAll(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .toUpperCase()
+    .replaceAll(/[^A-Z0-9]+/g, "_")
+    .replaceAll(/^_+|(?<!_)_+$/g, "");
+  return `${CHECKSTACK_ENV_PREFIX}${normalized}`;
+}
+
+/**
+ * Build the `CHECKSTACK_ENV_<KEY>` shell vars for an environment's custom
+ * fields. Values are stringified (objects/arrays via JSON). Two keys that
+ * normalize to the same shell var name collide: the FIRST wins and the
+ * later one is skipped + reported via `onCollision` (never last-write-wins).
+ * Keys that normalize to an empty name (so just `CHECKSTACK_ENV_`) are
+ * skipped + reported the same way.
+ */
+export function buildEnvironmentShellEnv(
+  fields: Record<string, unknown>,
+  onCollision: (message: string) => void = (message) =>
+    console.warn(message),
+): Record<string, string> {
+  const env: Record<string, string> = {};
+  // Track which original field key first claimed each shell var name so the
+  // collision message can name both conflicting keys.
+  const claimedBy: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(fields)) {
+    const shellKey = toEnvFieldShellKey(key);
+    if (shellKey === CHECKSTACK_ENV_PREFIX) {
+      onCollision(
+        `Environment custom field "${key}" normalizes to an empty shell var name; skipping.`,
+      );
+      continue;
+    }
+    if (shellKey in env) {
+      onCollision(
+        `Environment custom fields "${claimedBy[shellKey]}" and "${key}" both map to ${shellKey}; keeping the first, skipping "${key}".`,
+      );
+      continue;
+    }
+    env[shellKey] = stringifyFieldValue(value);
+    claimedBy[shellKey] = key;
+  }
+
+  return env;
+}
+
+/** Stringify a custom-field value for a shell env var. */
+function stringifyFieldValue(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return JSON.stringify(value);
+}

package/src/strategy.test.ts

@@ -215,4 +215,28 @@ describe("ScriptHealthCheckStrategy", () => {
       expect(aggregated.successRate.rate).toBe(0);
     });
   });
+
+  describe("config migration (assume-v1-on-read)", () => {
+    const strategy = new ScriptHealthCheckStrategy();
+
+    it("migrates a genuine v1 blob (command/args/...) down to {timeout}", async () => {
+      const migrated = await strategy.config.parseAssumingV1({
+        command: "/usr/bin/uptime",
+        args: ["-p"],
+        cwd: "/tmp",
+        env: { FOO: "bar" },
+        timeout: 9000,
+      });
+      expect(migrated).toEqual({ timeout: 9000 });
+    });
+
+    it("is idempotent: an already-current {timeout} blob is unchanged", async () => {
+      const migrated = await strategy.config.parseAssumingV1({ timeout: 2500 });
+      expect(migrated).toEqual({ timeout: 2500 });
+    });
+
+    it("has a complete v1->version migration chain", () => {
+      expect(strategy.config.validateMigrationChainFromV1()).toBeUndefined();
+    });
+  });
 });

package/src/strategy.ts

@@ -42,13 +42,19 @@ export const scriptConfigSchema = baseStrategyConfigSchema.extend({});
 export type ScriptConfig = z.infer<typeof scriptConfigSchema>;
 export type ScriptConfigInput = z.input<typeof scriptConfigSchema>;
 
-// Legacy config type for migrations
-interface ScriptConfigV1 {
-  command: string;
-  args: string[];
-  cwd?: string;
-  env?: Record<string, string>;
-  timeout: number;
+// The migrate input is `unknown` per the versioning chain, so narrowing is
+// done with `typeof`/`in` guards (no casts).
+
+/** Type guard: the migrate input is a plain object whose keys can be probed. */
+function isRecord(data: unknown): data is Record<string, unknown> {
+  return typeof data === "object" && data !== null;
+}
+
+/** Read a numeric `timeout` field from a legacy/current config blob. */
+function readTimeout(data: unknown): number | undefined {
+  if (!isRecord(data)) return undefined;
+  const value = data.timeout;
+  return typeof value === "number" ? value : undefined;
 }
 
 /**
@@ -201,9 +207,14 @@ export class ScriptHealthCheckStrategy implements HealthCheckStrategy<
         fromVersion: 1,
         toVersion: 2,
         description: "Remove command/args/cwd/env (moved to ExecuteCollector)",
-        migrate: (data: ScriptConfigV1): ScriptConfig => ({
-          timeout: data.timeout,
-        }),
+        // IDEMPOTENT: only a genuine v1 blob still carries `command`. An
+        // already-v2 blob (just `{ timeout }`) passes through untouched.
+        migrate: (data: unknown): unknown => {
+          if (isRecord(data) && "command" in data) {
+            return { timeout: readTimeout(data) };
+          }
+          return data;
+        },
       },
     ],
   });