@checkstack/satellite-common 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,124 @@
 # @checkstack/satellite-common
 
+## 0.8.0
+
+### Minor Changes
+
+- 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: Align workspace dependency versions and migrate React Router to v7.
+
+  BREAKING CHANGES (React Router v7): All frontend packages now depend on `react-router-dom@^7.16.0`. Previously the workspace declared four divergent ranges (`^6.20.0`, `^6.22.0`, `^7.1.1`, `^7.14.2`), which resolved both `react-router@6` and `react-router@7` into a single bundle. Everything is now unified on v7. The public imports the app uses (`BrowserRouter`, `Routes`, `Route`, `Link`, `NavLink`, `MemoryRouter`, `useNavigate`, `useParams`, `useSearchParams`, `useLocation`) are unchanged between v6 and v7, so no source rewrites were required - but any out-of-tree plugin still on react-router v6 should upgrade to v7 (see the React Router v6 -> v7 upgrade guide) to share the host's single router instance via the import map.
+
+  Other unified ranges (no API change): `react` -> `^18.3.1`, the `@orpc/*` family (`contract`, `server`, `client`, `tanstack-query`, `openapi`, `zod`) -> `^1.14.4`, and `better-auth` -> `^1.6.13`.
+
+  Removed the pre-rename `@orpc/react-query` leftover from `@checkstack/frontend-api`; its `createRouterUtils` / `RouterUtils` / `ProcedureUtils` now come from `@orpc/tanstack-query` (the package already in use).
+
+  Stale in-range runtime deps pulled up to current published versions: `hono` `^4.12.23`, `@tanstack/react-query` (+devtools) `^5.100.14`, `date-fns` `^4.4.0`, `jose` `^6.2.3`, `tar` `^7.5.16`, `semver` `^7.8.1`, `@xyflow/react` `^12.11.0`.
+
+### 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]
+  - @checkstack/healthcheck-common@1.5.0
+  - @checkstack/common@0.13.0
+  - @checkstack/signal-common@0.2.6
+
+## 0.7.0
+
+### Minor Changes
+
+- 270ef29: Extend the satellite protocol for script-package distribution: the
+  `authenticated` / `config_updated` payloads now carry an optional
+  `scriptPackagesLockfileHash` (the durable convergence backstop), a new
+  `refresh_script_packages { lockfileHash }` core->satellite control push,
+  and a new `script_package_sync_state` satellite->core report message. All
+  additions are optional / additive, so existing satellites and protocol
+  tests are unaffected.
+- 270ef29: Satellite-side script-package reconciliation over the WS channel.
+
+  - `satellite-common`: WS request/reply messages for pulling the manifest +
+    blobs from core (`request_script_package_manifest` /
+    `request_script_package_blob` -> `script_package_manifest` /
+    `script_package_blob`).
+  - `satellite-backend`: the WS handler answers those requests from the
+    script-packages store (satellites pull from core, never the registry).
+  - `@checkstack/satellite`: the client gains request/reply plumbing + a
+    `SatelliteScriptPackages` manager that reuses the Phase 2 reconciler
+    (`reconcileToHash` + `createReconcileFsDeps`) over the WS transport. It
+    reconciles on a `refresh_script_packages` push and on the
+    assignment-carried hash (startup / reconnect backstop), pulls only missing
+    blobs (delta), materializes via `bun install --offline`, atomically flips
+    `current`, reports sync state back, and degrades cleanly (error state, no
+    stale tree, no registry access) when a blob can't be fetched. Reconciles
+    are serialized + coalesced + idempotent.
+
+- 270ef29: Secrets platform Phase 3: just-in-time secret delivery to satellites + source-side masking, and central-execution injection for healthcheck collectors.
+
+  - New satellite WS messages `request_run_secrets` / `run_secrets`: just
+    before a satellite runs a collector that declares a `secretEnv`, it asks
+    core for that collector's resolved env; core resolves ONLY the secrets the
+    collector's OWN persisted assignment declares (least-privilege — the
+    satellite cannot choose) and replies with the env map (or a clear error).
+    The satellite injects it memory-only for the run and drops it on
+    completion. Secrets never ride the persisted assignment and never touch
+    disk.
+  - Source-side masking: the satellite runs `maskSecrets` over the collector's
+    stdout/stderr/result/error using the run's delivered values BEFORE the
+    result leaves the satellite (defense in depth).
+  - `CollectorStrategy.execute` gains an optional `secretEnv`. The
+    inline-script and shell collectors inject it into the runner
+    (`process.env` / `$VAR`) and mask the values out of their output.
+  - Healthcheck collectors running centrally (the queue executor) also resolve
+    - inject `secretEnv` via `secretResolverRef`, closing the gap where a
+      centrally-run secretEnv collector got no secrets. A missing required
+      secret fails the run clearly in all paths.
+
+### Patch Changes
+
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+  - @checkstack/healthcheck-common@1.4.0
+
 ## 0.6.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/satellite-common",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "license": "Elastic-2.0",
   "type": "module",
   "exports": {
@@ -9,16 +9,16 @@
     }
   },
   "dependencies": {
-    "@checkstack/common": "0.11.0",
-    "@checkstack/healthcheck-common": "1.2.0",
-    "@checkstack/signal-common": "0.2.4",
-    "@orpc/contract": "^1.13.14",
+    "@checkstack/common": "0.12.0",
+    "@checkstack/healthcheck-common": "1.4.0",
+    "@checkstack/signal-common": "0.2.5",
+    "@orpc/contract": "^1.14.4",
     "zod": "^4.2.1"
   },
   "devDependencies": {
     "typescript": "^5.7.2",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.3.3"
+    "@checkstack/scripts": "0.3.4"
   },
   "scripts": {
     "typecheck": "tsgo -b",

package/src/index.ts

@@ -29,6 +29,14 @@ export {
   type AuthFailedMessage,
   type ConfigUpdatedMessage,
   type ShutdownMessage,
+  type ScriptPackageSyncStateMessage,
+  type RefreshScriptPackagesMessage,
+  type ScriptPackageManifestMessage,
+  type ScriptPackageBlobMessage,
+  type RequestScriptPackageManifestMessage,
+  type RequestScriptPackageBlobMessage,
+  type RequestRunSecretsMessage,
+  type RunSecretsMessage,
 } from "./protocol";
 export {
   SATELLITE_STATUS_CHANGED,

package/src/protocol.test.ts

@@ -1,5 +1,9 @@
 import { describe, test, expect } from "bun:test";
-import { SatelliteAssignmentSchema } from "./protocol";
+import {
+  SatelliteAssignmentSchema,
+  CoreToSatelliteMessageSchema,
+  SatelliteToCoreMessageSchema,
+} from "./protocol";
 
 describe("SatelliteAssignmentSchema", () => {
   const base = {
@@ -28,3 +32,171 @@ describe("SatelliteAssignmentSchema", () => {
     expect(parsed.systemName).toBeUndefined();
   });
 });
+
+describe("script-packages protocol extensions", () => {
+  test("authenticated carries an optional scriptPackagesLockfileHash", () => {
+    const withHash = CoreToSatelliteMessageSchema.parse({
+      type: "authenticated",
+      satelliteId: "sat-1",
+      assignments: [],
+      scriptPackagesLockfileHash: "abc123",
+    });
+    expect(withHash.type).toBe("authenticated");
+    if (withHash.type === "authenticated") {
+      expect(withHash.scriptPackagesLockfileHash).toBe("abc123");
+    }
+  });
+
+  test("authenticated WITHOUT the hash still parses (version-skew safe)", () => {
+    const parsed = CoreToSatelliteMessageSchema.parse({
+      type: "authenticated",
+      satelliteId: "sat-1",
+      assignments: [],
+    });
+    expect(parsed.type).toBe("authenticated");
+    if (parsed.type === "authenticated") {
+      expect(parsed.scriptPackagesLockfileHash).toBeUndefined();
+    }
+  });
+
+  test("config_updated carries the optional hash", () => {
+    const parsed = CoreToSatelliteMessageSchema.parse({
+      type: "config_updated",
+      assignments: [],
+      scriptPackagesLockfileHash: null,
+    });
+    if (parsed.type === "config_updated") {
+      expect(parsed.scriptPackagesLockfileHash).toBeNull();
+    }
+  });
+
+  test("refresh_script_packages round-trips", () => {
+    const parsed = CoreToSatelliteMessageSchema.parse({
+      type: "refresh_script_packages",
+      lockfileHash: "deadbeef",
+    });
+    expect(parsed.type).toBe("refresh_script_packages");
+    if (parsed.type === "refresh_script_packages") {
+      expect(parsed.lockfileHash).toBe("deadbeef");
+    }
+  });
+
+  test("script_package_sync_state round-trips (satellite -> core)", () => {
+    const parsed = SatelliteToCoreMessageSchema.parse({
+      type: "script_package_sync_state",
+      lockfileHash: "abc",
+      status: "ready",
+    });
+    expect(parsed.type).toBe("script_package_sync_state");
+    if (parsed.type === "script_package_sync_state") {
+      expect(parsed.status).toBe("ready");
+      expect(parsed.lockfileHash).toBe("abc");
+    }
+  });
+
+  test("script_package_sync_state carries an error", () => {
+    const parsed = SatelliteToCoreMessageSchema.parse({
+      type: "script_package_sync_state",
+      lockfileHash: null,
+      status: "error",
+      errorMessage: "blob fetch failed",
+    });
+    if (parsed.type === "script_package_sync_state") {
+      expect(parsed.status).toBe("error");
+      expect(parsed.errorMessage).toBe("blob fetch failed");
+    }
+  });
+});
+
+describe("run-secrets request/reply (Phase 3 JIT delivery)", () => {
+  test("parses request_run_secrets", () => {
+    const parsed = SatelliteToCoreMessageSchema.parse({
+      type: "request_run_secrets",
+      requestId: "req-1",
+      configId: "config-1",
+      collectorId: "inline-script",
+      runId: "run-1",
+    });
+    expect(parsed.type).toBe("request_run_secrets");
+    if (parsed.type === "request_run_secrets") {
+      expect(parsed.requestId).toBe("req-1");
+      expect(parsed.collectorId).toBe("inline-script");
+    }
+  });
+
+  test("parses run_secrets reply with env", () => {
+    const parsed = CoreToSatelliteMessageSchema.parse({
+      type: "run_secrets",
+      requestId: "req-1",
+      env: { API_TOKEN: "resolved-value" },
+    });
+    if (parsed.type === "run_secrets") {
+      expect(parsed.env).toEqual({ API_TOKEN: "resolved-value" });
+      expect(parsed.error).toBeUndefined();
+    }
+  });
+
+  test("parses run_secrets reply with error (no env)", () => {
+    const parsed = CoreToSatelliteMessageSchema.parse({
+      type: "run_secrets",
+      requestId: "req-1",
+      error: "required secret not available",
+    });
+    if (parsed.type === "run_secrets") {
+      expect(parsed.error).toBe("required secret not available");
+      expect(parsed.env).toBeUndefined();
+    }
+  });
+});
+
+describe("sandbox-policy protocol extensions", () => {
+  const policy = {
+    enabled: true,
+    onUnavailable: "degrade" as const,
+    resources: { cpuSeconds: 30 },
+    filesystem: { mode: "scratch-plus-ro" as const },
+    network: {
+      mode: "allowlist" as const,
+      allow: ["10.0.0.1"],
+      denyLinkLocalAndMetadata: true,
+    },
+    privilege: { mode: "drop-to-uid" as const },
+  };
+
+  test("authenticated carries an optional sandboxPolicy that round-trips", () => {
+    const parsed = CoreToSatelliteMessageSchema.parse({
+      type: "authenticated",
+      satelliteId: "sat-1",
+      assignments: [],
+      sandboxPolicy: policy,
+    });
+    if (parsed.type === "authenticated") {
+      expect(parsed.sandboxPolicy?.network.mode).toBe("allowlist");
+      expect(parsed.sandboxPolicy?.network.allow).toEqual(["10.0.0.1"]);
+      expect(parsed.sandboxPolicy?.resources.cpuSeconds).toBe(30);
+    }
+  });
+
+  test("authenticated WITHOUT sandboxPolicy parses (version-skew safety)", () => {
+    const parsed = CoreToSatelliteMessageSchema.parse({
+      type: "authenticated",
+      satelliteId: "sat-1",
+      assignments: [],
+    });
+    if (parsed.type === "authenticated") {
+      expect(parsed.sandboxPolicy).toBeUndefined();
+    }
+  });
+
+  test("sandbox_policy push message round-trips the full policy", () => {
+    const parsed = CoreToSatelliteMessageSchema.parse({
+      type: "sandbox_policy",
+      policy,
+    });
+    expect(parsed.type).toBe("sandbox_policy");
+    if (parsed.type === "sandbox_policy") {
+      expect(parsed.policy.network.mode).toBe("allowlist");
+      expect(parsed.policy.privilege.mode).toBe("drop-to-uid");
+    }
+  });
+});

package/src/protocol.ts

@@ -3,6 +3,7 @@ import {
   HealthCheckStatusSchema,
   HealthCheckRunResultSchema,
 } from "@checkstack/healthcheck-common";
+import { sandboxPolicySchema } from "@checkstack/common";
 
 // =============================================================================
 // SATELLITE ASSIGNMENT (Core → Satellite configuration payload)
@@ -78,6 +79,64 @@ const StrategyErrorMessageSchema = z.object({
   message: z.string(),
 });
 
+/**
+ * Reports the satellite's script-package reconcile state back to the core,
+ * which persists it in `script_package_satellite_state` for the admin UI.
+ * Sent after a reconcile attempt (success or failure).
+ */
+const ScriptPackageSyncStateMessageSchema = z.object({
+  type: z.literal("script_package_sync_state"),
+  /** Active lockfile hash this satellite has materialized, or null. */
+  lockfileHash: z.string().nullable(),
+  /** "pending" | "syncing" | "ready" | "error" */
+  status: z.enum(["pending", "syncing", "ready", "error"]),
+  errorMessage: z.string().optional(),
+});
+
+/**
+ * Satellite -> core request for the manifest of a lockfile hash, so the
+ * satellite can diff against its local cache. The core replies with a
+ * `script_package_manifest` message. Delivered over the existing
+ * authenticated WS channel (no separate satellite HTTP auth surface).
+ */
+const RequestScriptPackageManifestMessageSchema = z.object({
+  type: z.literal("request_script_package_manifest"),
+  lockfileHash: z.string(),
+});
+
+/**
+ * Satellite -> core request for one content-addressed blob by integrity.
+ * The core replies with a `script_package_blob` message (base64 bytes).
+ */
+const RequestScriptPackageBlobMessageSchema = z.object({
+  type: z.literal("request_script_package_blob"),
+  integrity: z.string(),
+});
+
+/**
+ * Satellite -> core just-in-time request for a collector run's resolved
+ * secret env, sent right before the satellite executes a collector that
+ * declares a `secretEnv` mapping. The core resolves ONLY that collector's
+ * declared `secretEnv` (read from the persisted assignment — the satellite
+ * does not get to choose which secrets), and replies with a `run_secrets`
+ * message carrying the env map (or an error).
+ *
+ * Secrets NEVER ride the persisted assignment payload; they are delivered
+ * over this authenticated channel per-run and held in satellite memory only
+ * for the lifetime of the run. `requestId` correlates the reply (a config
+ * can run repeatedly; `runId` is for logging/audit).
+ */
+const RequestRunSecretsMessageSchema = z.object({
+  type: z.literal("request_run_secrets"),
+  /** Correlation id for the reply. */
+  requestId: z.string(),
+  /** The assignment/collector whose declared secretEnv to resolve. */
+  configId: z.string(),
+  collectorId: z.string(),
+  /** Opaque per-run id for audit/logging on the core side. */
+  runId: z.string(),
+});
+
 /**
  * Discriminated union of all messages that a satellite can send to the core.
  */
@@ -86,6 +145,10 @@ export const SatelliteToCoreMessageSchema = z.discriminatedUnion("type", [
   HeartbeatMessageSchema,
   ResultMessageSchema,
   StrategyErrorMessageSchema,
+  ScriptPackageSyncStateMessageSchema,
+  RequestScriptPackageManifestMessageSchema,
+  RequestScriptPackageBlobMessageSchema,
+  RequestRunSecretsMessageSchema,
 ]);
 
 export type SatelliteToCoreMessage = z.infer<
@@ -97,6 +160,18 @@ export type AuthenticateMessage = z.infer<typeof AuthenticateMessageSchema>;
 export type HeartbeatMessage = z.infer<typeof HeartbeatMessageSchema>;
 export type ResultMessage = z.infer<typeof ResultMessageSchema>;
 export type StrategyErrorMessage = z.infer<typeof StrategyErrorMessageSchema>;
+export type ScriptPackageSyncStateMessage = z.infer<
+  typeof ScriptPackageSyncStateMessageSchema
+>;
+export type RequestScriptPackageManifestMessage = z.infer<
+  typeof RequestScriptPackageManifestMessageSchema
+>;
+export type RequestScriptPackageBlobMessage = z.infer<
+  typeof RequestScriptPackageBlobMessageSchema
+>;
+export type RequestRunSecretsMessage = z.infer<
+  typeof RequestRunSecretsMessageSchema
+>;
 
 // =============================================================================
 // CORE → SATELLITE MESSAGES
@@ -106,6 +181,23 @@ const AuthenticatedMessageSchema = z.object({
   type: z.literal("authenticated"),
   satelliteId: z.string(),
   assignments: z.array(SatelliteAssignmentSchema),
+  /**
+   * Desired script-package lockfile hash. Carried alongside assignments as
+   * the durable convergence backstop: a satellite that booted after (or
+   * missed) a `refresh_script_packages` push still converges on connect.
+   * Optional for version-skew safety; null means "no packages installed".
+   */
+  scriptPackagesLockfileHash: z.string().nullable().optional(),
+  /**
+   * The resolved GLOBAL script-sandbox policy, pushed at auth time so the
+   * satellite enforces the operator's cluster-wide policy from its very first
+   * script run. The satellite caches it and resolves every run through it;
+   * until this arrives it FAILS CLOSED (denies egress) rather than using the
+   * permissive shipped default. Optional for version-skew safety: an older
+   * core omits it, and the satellite then stays fail-closed until a
+   * `sandbox_policy` push or a reconnect against a newer core delivers it.
+   */
+  sandboxPolicy: sandboxPolicySchema.optional(),
 });
 
 const AuthFailedMessageSchema = z.object({
@@ -116,6 +208,8 @@ const AuthFailedMessageSchema = z.object({
 const ConfigUpdatedMessageSchema = z.object({
   type: z.literal("config_updated"),
   assignments: z.array(SatelliteAssignmentSchema),
+  /** See {@link AuthenticatedMessageSchema.scriptPackagesLockfileHash}. */
+  scriptPackagesLockfileHash: z.string().nullable().optional(),
 });
 
 const ShutdownMessageSchema = z.object({
@@ -123,6 +217,73 @@ const ShutdownMessageSchema = z.object({
   reason: z.string(),
 });
 
+/**
+ * Control push telling the satellite to reconcile its script packages to a
+ * new lockfile hash. Sent by each core instance's `script-packages.changed`
+ * broadcast handler to its currently-connected satellites. Best-effort
+ * liveness; the assignment-carried `scriptPackagesLockfileHash` is the
+ * durable backstop.
+ */
+const RefreshScriptPackagesMessageSchema = z.object({
+  type: z.literal("refresh_script_packages"),
+  lockfileHash: z.string(),
+});
+
+/**
+ * Push the new GLOBAL script-sandbox policy to a connected satellite when an
+ * admin changes it (the push-on-change relay). Sent by each core instance's
+ * `script-sandbox.policy-changed` broadcast handler to its currently-connected
+ * satellites. The satellite replaces its cached policy so subsequent runs
+ * enforce it immediately. Best-effort liveness; the policy carried in the
+ * `authenticated` message on (re)connect is the durable backstop.
+ */
+const SandboxPolicyMessageSchema = z.object({
+  type: z.literal("sandbox_policy"),
+  policy: sandboxPolicySchema,
+});
+
+/** One resolved package in a manifest reply. */
+const ManifestEntryWireSchema = z.object({
+  name: z.string(),
+  version: z.string(),
+  integrity: z.string(),
+});
+
+/** Core reply to `request_script_package_manifest`. */
+const ScriptPackageManifestMessageSchema = z.object({
+  type: z.literal("script_package_manifest"),
+  lockfileHash: z.string(),
+  entries: z.array(ManifestEntryWireSchema),
+});
+
+/** Core reply to `request_script_package_blob` (base64 compressed bytes). */
+const ScriptPackageBlobMessageSchema = z.object({
+  type: z.literal("script_package_blob"),
+  integrity: z.string(),
+  /** base64-encoded compressed blob bytes, or null if not found. */
+  data: z.string().nullable(),
+});
+
+/**
+ * Core reply to `request_run_secrets`. Carries the resolved env map on
+ * success, or an `error` when a required secret could not be resolved /
+ * the collector was not found. The satellite injects `env` memory-only for
+ * the run and drops it on completion; on `error` it fails the run clearly
+ * rather than running without the secret.
+ *
+ * The env map never persists on the core side and is never written to disk
+ * on the satellite.
+ */
+const RunSecretsMessageSchema = z.object({
+  type: z.literal("run_secrets"),
+  /** Correlates with the originating `request_run_secrets`. */
+  requestId: z.string(),
+  /** Resolved env, present only on success. */
+  env: z.record(z.string(), z.string()).optional(),
+  /** Set when resolution failed; `env` is then absent. */
+  error: z.string().optional(),
+});
+
 /**
  * Discriminated union of all messages that the core can send to a satellite.
  */
@@ -131,6 +292,11 @@ export const CoreToSatelliteMessageSchema = z.discriminatedUnion("type", [
   AuthFailedMessageSchema,
   ConfigUpdatedMessageSchema,
   ShutdownMessageSchema,
+  RefreshScriptPackagesMessageSchema,
+  SandboxPolicyMessageSchema,
+  ScriptPackageManifestMessageSchema,
+  ScriptPackageBlobMessageSchema,
+  RunSecretsMessageSchema,
 ]);
 
 export type CoreToSatelliteMessage = z.infer<
@@ -142,3 +308,14 @@ export type AuthenticatedMessage = z.infer<typeof AuthenticatedMessageSchema>;
 export type AuthFailedMessage = z.infer<typeof AuthFailedMessageSchema>;
 export type ConfigUpdatedMessage = z.infer<typeof ConfigUpdatedMessageSchema>;
 export type ShutdownMessage = z.infer<typeof ShutdownMessageSchema>;
+export type RefreshScriptPackagesMessage = z.infer<
+  typeof RefreshScriptPackagesMessageSchema
+>;
+export type SandboxPolicyMessage = z.infer<typeof SandboxPolicyMessageSchema>;
+export type ScriptPackageManifestMessage = z.infer<
+  typeof ScriptPackageManifestMessageSchema
+>;
+export type ScriptPackageBlobMessage = z.infer<
+  typeof ScriptPackageBlobMessageSchema
+>;
+export type RunSecretsMessage = z.infer<typeof RunSecretsMessageSchema>;