@checkstack/common 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # @checkstack/common
 
+## 0.14.0
+
+### Minor Changes
+
+- 13373ce: Break the publish-time dependency cycle between `@checkstack/backend-api` and `@checkstack/cache-api` / `@checkstack/queue-api`.
+
+  `cache-api` and `queue-api` only ever used `Logger` and `Migration` from `backend-api` as `import type`, yet declared `@checkstack/backend-api` as a runtime dependency. In the monorepo this is harmless (everything resolves via `workspace:*`), but once published, `bun publish` freezes each `workspace:*` into a concrete pin of the _other_ package's then-current version. Because the dependency is mutual, a consumer installing these packages from the registry must resolve `backend-api -> cache-api -> backend-api -> ...` backward through release history until it reaches ancient versions that shipped raw `workspace:*` ranges and a long-removed `@checkstack/cache-api@0.1.0` pin - which fail to resolve. This surfaced as `bun install` errors (and a missing `checkstack-dev` binary) in freshly scaffolded standalone plugins.
+
+  `Logger` and `Migration` now live in `@checkstack/common` (a dependency-free leaf package). `@checkstack/backend-api` re-exports both for backward compatibility, so existing `import type { Logger, Migration } from "@checkstack/backend-api"` call sites are unchanged. `cache-api` and `queue-api` now depend on `@checkstack/common` instead of `@checkstack/backend-api`, removing the cycle.
+
+## 0.13.0
+
+### Minor Changes
+
+- 9dcc848: Cut initial-load JS: lazy plugin contributions, a hardened lazy-by-default contribution contract, on-demand Monaco, and a lighter icon/chart load.
+
+  - Lazy plugin route pages: each plugin's route `element` references a `React.lazy`-wrapped page rendered inside a shared `<Suspense>` boundary. Plugins still register synchronously, so nav, slots, commands, API factories, and `foreignSignals` are available on first paint. This moves ~37 route-page chunks (~600 KB) out of the entry; the entry chunk drops from ~2.4 MB to ~190 KB. Auth flow pages stay eager. The `@checkstack/scripts` scaffold template generates lazy route pages too.
+  - Hardened contribution contract (BREAKING, frontend plugin contract): plugins declare contributions lazily and let the framework own code-splitting, Suspense, and per-plugin error isolation. Routes use `load: () => import("./Page").then((m) => ({ default: m.Page }))` instead of `element: <Page />` (`element` is still accepted for the rare page that must paint without a chunk fetch; provide exactly one). Slot extensions accept either an eager `component` or a lazy `load`; new `getLazyContribution` + `ExtensionComponent` exports from `@checkstack/frontend-api` render either kind. This also fixes runtime-installed plugins: `ExtensionSlot` subscribes to the plugin registry, and the API registry rebuilds when the plugin set changes (`getPlugins()` returns an immutable snapshot via `useSyncExternalStore`). A per-plugin error boundary contains a bad contribution.
+  - On-demand Monaco: the `@checkstack/ui` barrel no longer pulls the `@codingame/*` / `monaco-languageclient` stack into the initial load. `CodeEditor` lazy-loads its Monaco-backed editor behind `React.lazy` + Suspense, `validateTypeScriptSources` imports the editor API via in-body `await import(...)`, and the "vscode services ready" signal moved to a Monaco-free module. The ~10 MB editor body loads only when a `CodeEditor` mounts. A `react-vendor` `manualChunks` split was added for stable vendor caching.
+  - lucide-react 1.x + lighter icons/charts (BREAKING for icon consumers): lucide-react unified from three drifting ranges to `^1.17.0`. lucide v1 removed brand icons, so the GitHub/GitLab marks are vendored in `@checkstack/ui` (`GithubIcon`, `GitlabIcon`, `brandIcons`); a new `IconName` type (`LucideIconName | BrandIconName`) in `@checkstack/common` is canonical, accepted by `AuthStrategy.icon` and the card components, so data-driven brand names keep working. `DynamicIcon` no longer eagerly imports lucide's ~1600-icon map (~1 MB) - it lives in a `React.lazy` `iconRegistry` chunk fetched on first data-driven render, while statically named-imported icons tree-shake normally. The recharts-backed health-check charts (~300 KB) and the `HealthCheckSystemOverview` drawer leave the initial load.
+
+  BREAKING CHANGES:
+
+  - Frontend plugin contract: routes/slot contributions are lazy-by-default (`load` instead of `element`/eager elements) as described above.
+  - Any external consumer importing a brand icon from `lucide-react` (e.g. `import { Github } from "lucide-react"`) must switch to the vendored `@checkstack/ui` brand icons or a custom SVG.
+
+  This is a beta minor.
+
+- 9dcc848: Move primary navigation into a left sidebar, and serve the user guide in-app.
+
+  Feature navigation (a ~20-item user-menu dropdown) now lives in a persistent left sidebar (a slide-over drawer on mobile), grouped by section with the active route highlighted; the user menu keeps only account actions. A route opts into the sidebar with new `nav` metadata (`{ group, icon, label?, order?, accessRule? }`) on its registration, co-located with path + access + title. The sidebar filters entries with the same access check as page guards. `@checkstack/common` gains `isAccessRuleSatisfied` and a centralized set of in-app doc slugs (`APP_DOC_SLUGS` + `docsPath`, with a test asserting each resolves to a real docs page); `@checkstack/auth-frontend` exports `useAccessRules`.
+
+  The backend now serves the Astro Starlight docs build same-origin at `/checkstack/*` (the same artifact deployed to GitHub Pages), so the user guide is available inside the app including for self-hosted / air-gapped installs (served verbatim, no rebuild, no link rewriting; from `CHECKSTACK_DOCS_DIST`, before the SPA catch-all, degrading gracefully when absent; the Docker image builds and ships `docs/dist`; Vite proxies `/checkstack` in dev). The "Docs" link is a shell-owned external sidebar entry under the Documentation group (book icon), opening `/checkstack/user-guide/` in a new tab; the group renders even when no plugin route contributes to it.
+
+  BREAKING (plugin authors): `UserMenuItemsSlot` is no longer the way to add navigation - registering a top user-menu item no longer surfaces it anywhere. Add `nav` to the page's route instead. `UserMenuItemsBottomSlot` (account items) is unchanged. All bundled plugins have been migrated.
+
+  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
+
+- 9dcc848: Assorted bug fixes and small hardening across the platform.
+
+  - announcement-backend: `updateAnnouncement` now invalidates the active-announcements and admin-list caches (it was missing the `invalidateAllActive` / `invalidateListAll` calls), so an edited announcement no longer stays stale up to the 45s TTL.
+  - anomaly-backend: anomaly/drift state transitions (confirmations, recoveries, self-resolutions) now log at `debug` instead of info/warn - they are already surfaced via the `ANOMALY_STATE_CHANGED` signal, so logging them louder just added noise; genuine failure paths stay `warn`.
+  - backend: the `/api/:pluginId/*` dispatcher now populates `requestHeaders` on the per-request RPC context, so a handler that re-enters the router as the originating user (e.g. an AI tool's user-scoped client) can forward the caller's session cookie / bearer - previously the loopback failed with "Authentication required". Guarded by a real end-to-end integration test. The HTTP server idle timeout is also raised (default 255s, configurable via `CHECKSTACK_SERVER_IDLE_TIMEOUT_SECONDS`, clamped 0-255, reset on each streamed chunk) so long AI chat SSE turns are not severed mid-stream.
+  - backend: a request for an unknown plugin id (`/api/<unknown>/...`) now returns `404 Not Found` instead of `500` (and logs at warn, not error, since it is a client request) - an unknown _procedure_ on a known plugin already 404'd. The in-app docs namespace `/checkstack/*` now serves Starlight's own `404.html` with a real 404 status for a missing doc, instead of falling through to the SPA catch-all and 200-ing the app shell. Both guarded by tests.
+  - automation-common: remove polynomial-time backtracking from `toShellEnvKey`'s underscore-trim (CodeQL `js/polynomial-redos`); a negative look-behind anchors the trailing run, keeping the trim linear.
+  - common + script-packages-common: the pure transport-safe sandbox-policy schema (`sandboxPolicySchema` and its sub-schemas + inferred types) moved to `@checkstack/common` (the neutral base), removing two inverted deps that existed only to reach the shape; `@checkstack/backend-api` continues to re-export it. The schema is no longer exported from `@checkstack/script-packages-common`. Pure refactor, no behavior change.
+  - catalog-backend: reject duplicate system names (a `CONFLICT` on create/rename, enforced by a pre-write check AND a new DB unique index on `systems.name`, migration 0004 which first resolves pre-existing duplicates by suffixing).
+  - catalog-frontend: detail-page cleanups (use `<NotFound />` not `<AccessDenied />` on the not-found branch, a readable key/value metadata list via `normalizeMetadata`, runtime locale via `formatDate`); and stop the browse view re-rendering on every health report (adopt a new statuses report only when a value actually changed, via `healthStatusesEqual`, so rows stay stable and interactive).
+  - healthcheck-backend: fix the daily-rollup retention step failing with an `ON CONFLICT` mismatch (SQLSTATE 42P10) after `environmentId` joined the `health_check_aggregates` unique constraint - the rollup now groups by (day, environmentId, sourceId) and uses a single exported conflict-target constant (`DAILY_AGGREGATE_CONFLICT_TARGET`) kept in lock-step with the schema by a unit test.
+  - automation-frontend: the service-account picker's "Learn more" links are now absolute URLs to the deployed Astro docs site (they 404ed as in-app relative paths). The Monaco script editor double-init crash is fixed (serialized cold init, a guarded `monacoGuard` accessor, theme/type effects gated on `apiReady`).
+  - auth-frontend: bound the desktop user-menu popover height (`max-h-[var(--radix-popover-content-available-height)]` + `overflow-y-auto`) so it no longer clips on short viewports, and fold the standalone `Account > Profile` item into a focusable name/email header (`profileHref` on `UserMenu`); the now-empty `Account` group no longer renders.
+  - satellite-frontend: picked up via the sidebar-nav migration (account-only user menu).
+
+  (Related UI fixes - the Monaco editor following the app theme, the `DynamicOptionsField` no-flash fix, the shared `Spinner`, GFM tables, and the user-menu popover bound - land their `@checkstack/ui` bump in the UI/perf changesets where `@checkstack/ui` is already minored.)
+
+  This is a beta patch.
+
 ## 0.12.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/common",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "./src/index.ts",
@@ -13,14 +13,14 @@
     }
   },
   "dependencies": {
-    "@orpc/contract": "^1.13.14",
-    "lucide-react": "0.562.0",
+    "@orpc/contract": "^1.14.4",
+    "lucide-react": "^1.17.0",
     "zod": "^4.0.0"
   },
   "devDependencies": {
     "typescript": "^5.7.2",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.3.3"
+    "@checkstack/scripts": "0.4.0"
   },
   "scripts": {
     "typecheck": "tsgo -b",

package/src/access-utils.ts

@@ -125,6 +125,26 @@ export function qualifyAccessRuleId(
   return `${pluginMetadata.pluginId}.${rule.id}`;
 }
 
+/**
+ * Pure predicate: does a set of granted access-rule ids satisfy a rule?
+ *
+ * This is the single source of truth for client-side access checks - the
+ * `useAccess` API and the sidebar both delegate here so nav visibility always
+ * matches page accessibility. A rule is satisfied by the wildcard `*`, an exact
+ * id match, or (for `read` rules) a `manage` grant on the same resource.
+ */
+export function isAccessRuleSatisfied(
+  grantedRuleIds: readonly string[],
+  rule: Pick<AccessRule, "id" | "resource" | "level">,
+): boolean {
+  if (grantedRuleIds.includes("*")) return true;
+  if (grantedRuleIds.includes(rule.id)) return true;
+  if (rule.level === "read") {
+    return grantedRuleIds.includes(`${rule.resource}.manage`);
+  }
+  return false;
+}
+
 /**
  * Creates an access rule for a resource.
  *

package/src/docs-links.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { APP_DOC_SLUGS, docsPath } from "./docs-links";
+
+/**
+ * Guards the docs<->app contract: every user-guide page the app deep-links to
+ * (navbar + "Learn more" links) MUST exist in the docs. If a page is renamed or
+ * moved, the in-app links would silently 404; this test fails instead.
+ *
+ * Source of truth is the actual docs content (`docs/src/content/docs`), resolved
+ * relative to this file (core/common/src -> repo root).
+ */
+const DOCS_ROOT = resolve(import.meta.dir, "../../../docs/src/content/docs");
+
+/** A slug resolves if `<slug>.md(x)` or `<slug>/index.md(x)` exists. */
+function slugExists(slug: string): boolean {
+  return [
+    `${slug}.md`,
+    `${slug}.mdx`,
+    `${slug}/index.md`,
+    `${slug}/index.mdx`,
+  ].some((candidate) => existsSync(resolve(DOCS_ROOT, candidate)));
+}
+
+describe("app doc links resolve to real docs pages", () => {
+  test("the docs content root is found (guards the relative path)", () => {
+    // If this fails the path is wrong, which would otherwise mask real
+    // missing-page failures below.
+    expect(existsSync(DOCS_ROOT)).toBe(true);
+  });
+
+  for (const [key, slug] of Object.entries(APP_DOC_SLUGS)) {
+    test(`${key} -> "${slug}" exists in the docs`, () => {
+      expect(slugExists(slug)).toBe(true);
+    });
+  }
+
+  test("docsPath builds a /checkstack-based trailing-slash URL", () => {
+    expect(docsPath(APP_DOC_SLUGS.teamsAndAccess)).toBe(
+      "/checkstack/user-guide/concepts/teams-and-access/",
+    );
+  });
+});

package/src/docs-links.ts

@@ -0,0 +1,27 @@
+/**
+ * User-guide pages the APP deep-links to (the navbar "Docs" entry and in-context
+ * "Learn more" links). Centralised as a SINGLE source of truth and guarded by
+ * `docs-links.test.ts`, which asserts each slug resolves to a real docs page -
+ * so renaming/moving a doc fails the test instead of silently 404-ing the
+ * in-app links.
+ *
+ * A slug is the path under the docs content root WITHOUT the `/checkstack` base
+ * and WITHOUT a trailing slash, e.g. `user-guide/concepts/teams-and-access`.
+ */
+export const APP_DOC_SLUGS = {
+  userGuideHome: "user-guide",
+  teamsAndAccess: "user-guide/concepts/teams-and-access",
+  apiKeys: "user-guide/reference/api-keys",
+} as const;
+
+export type AppDocSlugKey = keyof typeof APP_DOC_SLUGS;
+
+/**
+ * Build the same-origin in-app URL for a docs slug. The backend serves the Astro
+ * Starlight build at `/checkstack/*` (base path `/checkstack`), and Starlight
+ * pages are directory routes, so the URL is `/checkstack/<slug>/` (trailing
+ * slash). Pass a value from {@link APP_DOC_SLUGS}.
+ */
+export function docsPath(slug: string): string {
+  return `/checkstack/${slug}/`;
+}

package/src/icons.ts

@@ -15,12 +15,27 @@ import { z } from "zod";
 export type LucideIconName = keyof typeof icons;
 
 /**
- * Zod schema for LucideIconName.
- * Uses string at runtime but infers LucideIconName type for compile-time safety.
+ * Brand icon names that lucide-react v1 removed (all brand marks were dropped
+ * for trademark reasons) but that we still support as data-driven icon names.
+ * The frontend's `DynamicIcon` resolves these to vendored brand SVGs in
+ * `@checkstack/ui`. Keep this in sync with the `brandIcons` map there.
+ */
+export type BrandIconName = "Github" | "Gitlab";
+
+/**
+ * Any icon name accepted across the platform: a lucide icon or a vendored
+ * brand icon.
+ * @example "CircleAlert", "Settings", "Github"
+ */
+export type IconName = LucideIconName | BrandIconName;
+
+/**
+ * Zod schema for {@link IconName}.
+ * Uses string at runtime but infers `IconName` for compile-time safety.
  * Use this in RPC contracts to get proper type inference.
  *
  * @example
  * const schema = z.object({ icon: lucideIconSchema.optional() });
- * // Infers: { icon?: LucideIconName }
+ * // Infers: { icon?: IconName }
  */
-export const lucideIconSchema = z.string() as z.ZodType<LucideIconName>;
+export const lucideIconSchema = z.string() as z.ZodType<IconName>;

package/src/index.ts

@@ -1,4 +1,6 @@
 export * from "./types";
+export * from "./logger";
+export * from "./migration";
 export * from "./actor";
 export * from "./pagination";
 export * from "./routes";
@@ -12,3 +14,5 @@ export * from "./json-schema";
 export * from "./chart-types";
 export * from "./procedure-builder";
 export * from "./error-utils";
+export * from "./sandbox-policy";
+export * from "./docs-links";

package/src/logger.ts

@@ -0,0 +1,46 @@
+/**
+ * Backend logger interface used everywhere in the platform via `RpcContext.logger`
+ * and the various `coreServices.logger` accessors.
+ *
+ * Each method accepts a free-form trailing argument list (`...args: unknown[]`)
+ * so the long-standing varargs callsites - `logger.error("…", err)` where `err`
+ * is an `Error`, or `logger.info("…", value1, value2)` - keep working unchanged.
+ *
+ * For NEW code, prefer the structured-metadata shape:
+ *
+ *   logger.info("did something", { userId, durationMs });
+ *
+ * Winston's `splat` handling treats a single trailing plain object as
+ * structured metadata (merged into the log entry), and an `Error` instance as
+ * a special-cased error (with stack). Either shape lands in the same vararg
+ * slot here, so this signature covers both without overload churn.
+ *
+ * Auto-injected metadata (when the request flows through
+ * `correlationMiddleware`): `{ correlationId, pluginId, userId? }`. Do NOT
+ * include secrets in the structured-metadata object - it is forwarded
+ * verbatim to the log destination.
+ *
+ * Lives in `@checkstack/common` (rather than `@checkstack/backend-api`) so that
+ * low-level packages such as `@checkstack/cache-api` and `@checkstack/queue-api`
+ * can reference it without taking a dependency on `backend-api` - which would
+ * create a publish-time dependency cycle. `@checkstack/backend-api` re-exports
+ * it for backward compatibility.
+ */
+export interface Logger {
+  info(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  debug(message: string, ...args: unknown[]): void;
+  /**
+   * Returns a derived logger with the supplied metadata bound to every
+   * subsequent log entry. Used by `correlationMiddleware` to attach
+   * `{ correlationId, pluginId, userId? }`, and available to handlers that
+   * want a tighter scope (e.g. `ctx.logger.child({ jobId })`).
+   *
+   * Optional only to keep minimal test-mock logger objects compatible with
+   * this interface - production loggers (Winston via `core/backend`) always
+   * implement it. Call sites that rely on metadata binding should branch
+   * on presence and fall back to the base logger when it is not available.
+   */
+  child?(meta: Record<string, unknown>): Logger;
+}

package/src/migration.ts

@@ -0,0 +1,21 @@
+/**
+ * Type-safe migration from one data version to another.
+ * Used for backward-compatible schema evolution (see `Versioned` /
+ * `MigrationBuilder` in `@checkstack/backend-api`).
+ *
+ * Lives in `@checkstack/common` (rather than `@checkstack/backend-api`) so that
+ * low-level packages such as `@checkstack/cache-api` and `@checkstack/queue-api`
+ * can reference it without taking a dependency on `backend-api` - which would
+ * create a publish-time dependency cycle. `@checkstack/backend-api` re-exports
+ * it for backward compatibility.
+ */
+export interface Migration<TFrom = unknown, TTo = unknown> {
+  /** Version number migrating from */
+  fromVersion: number;
+  /** Version number migrating to (must be fromVersion + 1) */
+  toVersion: number;
+  /** Human-readable description of what this migration does */
+  description: string;
+  /** Migration function that transforms old data to new format */
+  migrate(data: TFrom): TTo | Promise<TTo>;
+}

package/src/sandbox-policy.ts

@@ -0,0 +1,189 @@
+import { z } from "zod";
+
+/**
+ * Canonical, transport-safe sandbox policy schema (the single source of truth
+ * for the policy SHAPE).
+ *
+ * This lives in `@checkstack/common` - the neutral base every tier already
+ * depends on - NOT in `@checkstack/backend-api` and NOT in a plugin's
+ * `*-common` package, so it can be imported by:
+ *
+ *  - the script-packages RPC contract (`@checkstack/script-packages-common`),
+ *    which exposes the admin read / write endpoints for the global policy;
+ *  - the satellite WS protocol (`@checkstack/satellite-common`), which relays
+ *    the resolved global policy to satellites on connect and on change;
+ *  - `@checkstack/backend-api`, whose `script-sandbox/policy.ts` re-exports this
+ *    schema and layers the runtime-only helpers (the shipped default profile,
+ *    the env-seeded UID/GID resolution, and `mergeSandboxPolicy`) on top.
+ *
+ * Common packages cannot depend on `backend-api`, and putting the pure schema
+ * in a single plugin's `*-common` forced backward dependencies from
+ * `backend-api` and `satellite-common` onto that plugin. Hosting it in the
+ * neutral base keeps it shareable across the contract + protocol + platform
+ * without an inverted dependency or a duplicated definition (which would risk
+ * drift).
+ *
+ * Phase 1 implemented: resource caps (rlimits + output truncation), privilege
+ * dropping (uid/gid), and the env-key denylist. Filesystem and network
+ * isolation are enforced in later phases; the schema scaffolds every layer.
+ */
+
+/** What to do when a requested layer cannot be enforced on this host. */
+export const onUnavailableSchema = z
+  .enum(["degrade", "fail"])
+  .describe(
+    "degrade = drop this layer to the portable subset and surface a downgrade; " +
+      "fail = refuse to run when the layer can't be enforced.",
+  );
+
+export type OnUnavailable = z.infer<typeof onUnavailableSchema>;
+
+/** Per-run resource caps. All optional; unset = not capped by this layer. */
+export const resourceLimitsSchema = z
+  .object({
+    cpuSeconds: z
+      .number()
+      .int()
+      .positive()
+      .max(3600)
+      .optional()
+      .describe(
+        "Max CPU time (RLIMIT_CPU). Distinct from the wall-clock timeout.",
+      ),
+    memoryBytes: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe(
+        "Max address space (RLIMIT_AS). On the ESM runner also derives " +
+          "--smol / --max-old-space-size as the portable fallback.",
+      ),
+    maxOpenFiles: z
+      .number()
+      .int()
+      .positive()
+      .max(1_048_576)
+      .optional()
+      .describe("Max open file descriptors (RLIMIT_NOFILE)."),
+    maxProcesses: z
+      .number()
+      .int()
+      .positive()
+      .max(65_536)
+      .optional()
+      .describe(
+        "Max processes/threads for the run's UID (RLIMIT_NPROC). Fork-bomb guard.",
+      ),
+    maxOutputBytes: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe(
+        "Hard cap on captured stdout+stderr; the runner truncates and flags overflow.",
+      ),
+    maxFileSizeBytes: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe(
+        "Max single-file write size (RLIMIT_FSIZE). Disk-filler guard.",
+      ),
+  })
+  .strict();
+
+export type ResourceLimits = z.infer<typeof resourceLimitsSchema>;
+
+export const filesystemPolicySchema = z
+  .object({
+    mode: z
+      .enum(["off", "scratch-only", "scratch-plus-ro"])
+      .default("off")
+      .describe(
+        "off = current behavior (full host FS). " +
+          "scratch-only = child sees only its per-run scratch dir (writable) + a minimal /usr,/bin,/lib read-only. " +
+          "scratch-plus-ro = scratch-only PLUS a read-only bind of resolutionRoot/node_modules for managed packages.",
+      ),
+    scratchBytes: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe(
+        "Optional tmpfs size cap for the scratch dir when the mechanism supports it.",
+      ),
+  })
+  .strict();
+
+export type FilesystemPolicy = z.infer<typeof filesystemPolicySchema>;
+
+export const networkPolicySchema = z
+  .object({
+    mode: z
+      .enum(["unrestricted", "deny", "allowlist"])
+      .default("unrestricted")
+      .describe(
+        "unrestricted = current behavior. " +
+          "deny = no egress (loopback only). " +
+          "allowlist = only the listed destinations are reachable.",
+      ),
+    /** v1: IP / CIDR only. Domains are a v2 extension. */
+    allow: z
+      .array(z.string())
+      .default([])
+      .describe(
+        "IPv4/IPv6 addresses or CIDR blocks reachable when mode=allowlist.",
+      ),
+    denyLinkLocalAndMetadata: z
+      .boolean()
+      .default(true)
+      .describe(
+        "Always block 169.254.0.0/16, fc00::/7 link-local, and cloud metadata IPs, even under unrestricted, when a network layer is active.",
+      ),
+  })
+  .strict();
+
+export type NetworkPolicy = z.infer<typeof networkPolicySchema>;
+
+export const privilegePolicySchema = z
+  .object({
+    mode: z
+      .enum(["inherit", "drop-to-uid"])
+      .default("inherit")
+      .describe(
+        "inherit = run as the host process UID (current). drop-to-uid = run as the configured low-priv UID/GID.",
+      ),
+    uid: z.number().int().nonnegative().optional(),
+    gid: z.number().int().nonnegative().optional(),
+  })
+  .strict();
+
+export type PrivilegePolicy = z.infer<typeof privilegePolicySchema>;
+
+export const sandboxPolicySchema = z
+  .object({
+    /**
+     * Master switch. Schema default is TRUE (on-by-default with opt-out).
+     * Set `enabled: false` to restore the pre-hardening behavior (the
+     * documented opt-out). The GLOBAL default policy that the runner actually
+     * parses against is the permissive DEFAULT PROFILE, not the bare per-field
+     * zod defaults below - the field defaults stay conservative so an explicit
+     * partial override (e.g. just `{ network: { mode: "deny" } }`) doesn't
+     * accidentally widen the other layers.
+     */
+    enabled: z.boolean().default(true),
+    onUnavailable: onUnavailableSchema.default("degrade"),
+    // `.prefault({})` runs the empty default THROUGH the nested schema so each
+    // layer's own field defaults (e.g. `filesystem.mode = "off"`) are applied.
+    // Plain `.default({})` would store a literal `{}` and skip nested defaults.
+    resources: resourceLimitsSchema.prefault({}),
+    filesystem: filesystemPolicySchema.prefault({}),
+    network: networkPolicySchema.prefault({}),
+    privilege: privilegePolicySchema.prefault({}),
+  })
+  .strict();
+
+export type SandboxPolicy = z.infer<typeof sandboxPolicySchema>;
+export type SandboxPolicyInput = z.input<typeof sandboxPolicySchema>;