@bjoernrochel/sevro 0.1.0-rc.8 → 1.1.0

package/src/{runtime-config.ts → runtime/config.ts}

@@ -1,25 +1,38 @@
 import { lstat, readFile, realpath } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import type { ErrorObject } from "ajv";
 import {
   declaredRuntimeRoots,
   optionalRuntimeRoots,
   runtimePathDirectories,
   runtimeInheritedPath,
   requireRuntimeReadRoots,
-} from "./runtime-paths";
-import validate from "./generated/runtime.cjs";
+} from "./paths";
+import validate from "../generated/runtime.cjs";
 import {
   requireArtifactDirectories,
   type RuntimeArtifactDirectory,
-} from "./candidate-artifacts";
-import { runtimeSeedDigest } from "./runtime-seeds";
+} from "../candidate-artifacts";
+import { runtimeSeedDigest } from "./seeds";
+import {
+  resolveSharedCaches,
+  requireSharedCachePolicy,
+  type SharedCacheDirectory,
+} from "./shared-cache";
 import {
   discoverRuntimeSupport,
   type RuntimeDiscoverySource,
-} from "./runtime-discovery";
+} from "./discovery";
 
-export type RuntimeRole =
-  "candidate" | "checks" | "hooks" | "semantic" | "advisory";
+/** Canonical roles; schemas:generate projects this list into the runtime schema. */
+export const RUNTIME_ROLES = [
+  "candidate",
+  "checks",
+  "hooks",
+  "semantic",
+  "advisory",
+] as const;
+export type RuntimeRole = (typeof RUNTIME_ROLES)[number];
 export interface RuntimeSeed {
   source: string;
   target: string;
@@ -27,11 +40,14 @@ export interface RuntimeSeed {
 }
 export interface RuntimeConfiguration {
   format: "sevro.runtime.v1";
+  codexState?: boolean;
+  network?: { localHttp?: boolean };
   nativeTranscripts?: boolean;
   environment?: { inherit?: string[]; set?: Record<string, string> };
   filesystem?: { readOnlyRoots?: string[]; optionalReadOnlyRoots?: string[] };
   runtime?: {
     seedDirectories?: RuntimeSeed[];
+    sharedCacheDirectories?: SharedCacheDirectory[];
     artifactDirectories?: RuntimeArtifactDirectory[];
   };
   hooks?: { nativeGoal?: boolean; plugins?: string[] };
@@ -39,6 +55,8 @@ export interface RuntimeConfiguration {
 
 export interface RuntimePolicy {
   format: "sevro.runtime.v1";
+  codexState?: boolean;
+  network?: { localHttp?: boolean };
   artifactDirectories?: RuntimeArtifactDirectory[];
   nativeTranscripts?: boolean;
   environment: Record<string, string>;
@@ -48,9 +66,18 @@ export interface RuntimePolicy {
   /** Original source denials retained when a derived role policy omits seeds. */
   seedReadDenyRoots?: string[];
   seeds?: (RuntimeSeed & { sha256: string })[];
+  sharedCacheDirectories?: SharedCacheDirectory[];
   hooks?: { nativeGoal?: boolean; plugins?: string[] };
 }
 
+export function runtimeLocalHttpEnabled(
+  policy: RuntimePolicy | undefined,
+  role: RuntimeRole,
+): boolean {
+  const network = policy?.network;
+  return network?.localHttp === true && ["candidate", "checks"].includes(role);
+}
+
 export function runtimeNativeGoalEnabled(
   policy: RuntimePolicy | undefined,
 ): boolean {
@@ -58,28 +85,64 @@ export function runtimeNativeGoalEnabled(
   return hooks?.nativeGoal === true;
 }
 
+const validatedPolicies = new WeakSet<RuntimePolicy>();
+
+export function runtimePolicySnapshot(policy: RuntimePolicy): RuntimePolicy;
+export function runtimePolicySnapshot(
+  policy: RuntimePolicy | undefined,
+): RuntimePolicy | undefined;
 export function runtimePolicySnapshot(
   policy: RuntimePolicy | undefined,
 ): RuntimePolicy | undefined {
   if (!policy) return undefined;
-  requireRuntimeEnvironment(policy.environment);
   const snapshot = structuredClone(policy);
+  if (!validatedPolicies.has(policy)) requireRuntimePolicy(snapshot);
+  Object.freeze(snapshot.network);
   freezeArtifactDirectories(snapshot);
   Object.freeze(snapshot.environment);
   Object.freeze(snapshot.readOnlyRoots);
   freezeDiscovery(snapshot);
-  for (const seed of snapshot.seeds ?? []) {
-    Object.freeze(seed.roles);
-    Object.freeze(seed);
-  }
-  Object.freeze(snapshot.seeds);
+  freezeRuntimeCaches(snapshot);
   Object.freeze(snapshot.seedReadDenyRoots);
   const hooks = snapshot.hooks;
   if (hooks) {
     Object.freeze(hooks.plugins);
     Object.freeze(hooks);
   }
-  return Object.freeze(snapshot);
+  Object.freeze(snapshot);
+  validatedPolicies.add(snapshot);
+  return snapshot;
+}
+
+/** Loaded snapshots are already validated; mutable direct API inputs still need validation. */
+export function requireRuntimePolicy(policy: RuntimePolicy): void {
+  if (validatedPolicies.has(policy)) return;
+  snapshotEnvironment([], policy.environment);
+  requireRuntimeCaches(policy.seeds ?? [], policy.sharedCacheDirectories ?? []);
+  requireSharedCachePolicy(policy);
+  requireArtifactDirectories(policy.artifactDirectories ?? []);
+}
+
+function requireRuntimeCaches(
+  seeds: RuntimeSeed[],
+  caches: SharedCacheDirectory[],
+): void {
+  requireRuntimeSeedTargets([...seeds, ...caches]);
+  for (const seed of seeds)
+    if (seed.roles !== undefined) requireRuntimeRoles(seed.roles, "seed");
+  for (const cache of caches) requireRuntimeRoles(cache.roles, "shared cache");
+}
+
+function freezeRuntimeCaches(snapshot: RuntimePolicy): void {
+  for (const seed of [
+    ...(snapshot.seeds ?? []),
+    ...(snapshot.sharedCacheDirectories ?? []),
+  ]) {
+    Object.freeze(seed.roles);
+    Object.freeze(seed);
+  }
+  Object.freeze(snapshot.seeds);
+  Object.freeze(snapshot.sharedCacheDirectories);
 }
 
 function freezeDiscovery(snapshot: RuntimePolicy): void {
@@ -93,7 +156,6 @@ function freezeDiscovery(snapshot: RuntimePolicy): void {
 
 function freezeArtifactDirectories(snapshot: RuntimePolicy): void {
   const directories = snapshot.artifactDirectories ?? [];
-  requireArtifactDirectories(directories);
   for (const directory of directories) Object.freeze(directory);
   Object.freeze(snapshot.artifactDirectories);
 }
@@ -101,11 +163,27 @@ function freezeArtifactDirectories(snapshot: RuntimePolicy): void {
 function assertRuntimeConfiguration(
   value: unknown,
 ): asserts value is RuntimeConfiguration {
-  if (!validate(value)) throw new Error("invalid runtime configuration schema");
+  if (!validate(value)) {
+    // Ajv always populates errors when validation fails.
+    const issue = (validate.errors as [ErrorObject, ...ErrorObject[]])[0];
+    throw new Error(
+      `runtime configuration schema ${runtimeSchemaPath(issue)}: ${issue.message}`,
+    );
+  }
+}
+
+function runtimeSchemaPath(issue: ErrorObject): string {
+  const params = issue.params as Record<string, unknown>;
+  const property = params.additionalProperty ?? params.missingProperty;
+  const suffix =
+    typeof property === "string"
+      ? "/" + property.replaceAll("~", "~0").replaceAll("/", "~1")
+      : "";
+  return safeFilesystemPath(issue.instancePath + suffix || "/");
 }
 
 const RESERVED_ENVIRONMENT =
-  /^(HOME|TMPDIR|TMP|TEMP|CODEX_HOME|CODEX_THREAD_ID|CLAUDE_CONFIG_DIR|CLAUDE_EFFORT|BASH_ENV|ENV|ZDOTDIR|NODE_OPTIONS|BUN_OPTIONS|UV_OFFLINE|GIT_CONFIG.*|LD_.*|DYLD_.*|CLAUDE_CODE_.*|SEVRO_NATIVE_.*|SEVRO_CANDIDATE_.*)$/i;
+  /^(HOME|TMPDIR|TMPPREFIX|TMP|TEMP|CODEX_HOME|CODEX_THREAD_ID|CLAUDE_CONFIG_DIR|CLAUDE_EFFORT|BASH_ENV|ENV|ZDOTDIR|NODE_OPTIONS|BUN_OPTIONS|UV_OFFLINE|GIT_CONFIG.*|LD_.*|DYLD_.*|CLAUDE_CODE_.*|SEVRO_CODEX_.*|SEVRO_NATIVE_.*|SEVRO_CANDIDATE_.*)$/i;
 
 function requireEnvironmentName(name: string): void {
   if (!/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(name))
@@ -139,16 +217,7 @@ function snapshotEnvironment(
   return environment;
 }
 
-export function requireRuntimeEnvironment(
-  environment: Record<string, string>,
-): void {
-  snapshotEnvironment([], environment);
-}
-
-export function requireRuntimeSeedTargets(
-  seeds: NonNullable<RuntimePolicy["seeds"]>,
-): void {
-  for (const seed of seeds) requireRuntimeSeedRoles(seed.roles);
+function requireRuntimeSeedTargets(seeds: RuntimeSeed[]): void {
   const targets = seeds.map((seed) => seed.target);
   if (
     targets.some(
@@ -175,13 +244,29 @@ export async function loadRuntimeConfiguration(
     const source = await readFile(canonical, "utf8");
     if (Buffer.byteLength(source) > 65536)
       throw new Error("runtime configuration exceeds 64 KiB");
-    return await resolveRuntimeConfiguration(
-      JSON.parse(source),
-      dirname(canonical),
-      protectedRoots,
+    return runtimePolicySnapshot(
+      await resolveRuntimeConfiguration(
+        parseRuntimeConfiguration(source),
+        dirname(canonical),
+        protectedRoots,
+      ),
     );
   } catch (cause) {
-    throw new Error(runtimeConfigurationDiagnostic(cause), { cause });
+    throw new Error(
+      `${runtimeConfigurationDiagnostic(cause)} at ${safeFilesystemPath(path)}`,
+      { cause },
+    );
+  }
+}
+
+function parseRuntimeConfiguration(source: string): unknown {
+  try {
+    return JSON.parse(source);
+  } catch (cause) {
+    throw new Error(
+      "runtime configuration $: invalid JSON; check the JSON syntax",
+      { cause },
+    );
   }
 }
 
@@ -256,7 +341,7 @@ async function resolvedSeeds(
   environment: Record<string, string>,
   base: string,
 ) {
-  const resolved = await Promise.all(
+  return Promise.all(
     seeds.map(async (seed) => {
       const roots = await declaredRuntimeRoots(
         [seed.source],
@@ -274,8 +359,6 @@ async function resolvedSeeds(
       };
     }),
   );
-  requireRuntimeSeedTargets(resolved);
-  return resolved;
 }
 
 async function resolveRuntimeConfiguration(
@@ -308,19 +391,53 @@ async function resolveRuntimeConfiguration(
   requireRuntimeReadRoots(readOnlyRoots, protectedRoots);
   return {
     format: value.format,
+    ...selectedRuntimeCapabilities(value),
     ...artifactConfiguration(value.runtime),
-    ...(value.nativeTranscripts === undefined
-      ? {}
-      : { nativeTranscripts: value.nativeTranscripts }),
     environment,
     readOnlyRoots: [...new Set(readOnlyRoots)].sort(),
     discovery: discovery.sources,
     skippedOptionalReadOnlyRoots: optional.skipped,
-    seeds: await resolvedSeeds(configurationSeeds(value), environment, base),
+    ...(await resolvedRuntimeCaches(value, environment, base, [
+      ...protectedRoots,
+      ...readOnlyRoots,
+    ])),
     hooks: resolvedHooks(value.hooks),
   };
 }
 
+async function resolvedRuntimeCaches(
+  value: RuntimeConfiguration,
+  environment: Record<string, string>,
+  base: string,
+  protectedRoots: string[],
+) {
+  const seeds = await resolvedSeeds(
+    configurationSeeds(value),
+    environment,
+    base,
+  );
+  const caches = await resolveSharedCaches(
+    value.runtime?.sharedCacheDirectories ?? [],
+    environment,
+    base,
+    [...protectedRoots, ...seeds.map((seed) => seed.source)],
+  );
+  return {
+    seeds,
+    ...(caches.length ? { sharedCacheDirectories: caches } : {}),
+  };
+}
+
+function selectedRuntimeCapabilities(value: RuntimeConfiguration) {
+  return {
+    ...(value.network === undefined ? {} : { network: value.network }),
+    ...(value.codexState === undefined ? {} : { codexState: value.codexState }),
+    ...(value.nativeTranscripts === undefined
+      ? {}
+      : { nativeTranscripts: value.nativeTranscripts }),
+  };
+}
+
 async function resolvedRuntimeEnvironment(value: RuntimeConfiguration) {
   const { inherit, set } = configurationEnvironment(value);
   const environment = snapshotEnvironment(inherit, set);
@@ -339,7 +456,6 @@ function configurationEnvironment(value: RuntimeConfiguration) {
 function artifactConfiguration(runtime: RuntimeConfiguration["runtime"]) {
   const directories = runtime?.artifactDirectories;
   if (directories === undefined) return {};
-  requireArtifactDirectories(directories);
   return { artifactDirectories: directories };
 }
 function configurationReadRoots(value: RuntimeConfiguration): string[] {
@@ -356,20 +472,18 @@ function resolvedHooks(hooks: RuntimeConfiguration["hooks"]) {
   };
 }
 
-function requireRuntimeSeedRoles(roles: RuntimeRole[] | undefined): void {
-  if (roles === undefined) return;
-  const allowed = ["candidate", "checks", "hooks", "semantic", "advisory"];
+function requireRuntimeRoles(roles: RuntimeRole[], kind: string): void {
   if (
     !validRoleArray(roles) ||
     new Set(roles).size !== roles.length ||
-    roles.some((role) => !allowed.includes(role))
+    roles.some((role) => !RUNTIME_ROLES.includes(role))
   )
-    throw new Error("runtime seed roles are invalid");
+    throw new Error(`runtime ${kind} roles are invalid`);
 }
 
 export function runtimeRoleSeeds(policy: RuntimePolicy, role: RuntimeRole) {
   return (policy.seeds ?? []).filter(
-    (seed) => seed.roles === undefined || seed.roles.includes(role),
+    (seed) => seed.roles?.includes(role) ?? role !== "checks",
   );
 }
 

package/src/{runtime-discovery-apple.ts → runtime/discovery-apple.ts}

@@ -1,13 +1,13 @@
 import { realpath } from "node:fs/promises";
 import { dirname } from "node:path";
-import { RuntimeMetadataQueryError } from "./runtime-query";
-import { optionalRuntimeRoots, requireRuntimeReadRoots } from "./runtime-paths";
+import { RuntimeMetadataQueryError } from "./query";
+import { optionalRuntimeRoots, requireRuntimeReadRoots } from "./paths";
 import {
   providerExecutable,
   query,
   requireProvider,
   type RuntimeDiscoverySource,
-} from "./runtime-discovery-providers";
+} from "./discovery-providers";
 
 export async function discoverApple(
   path: string,

package/src/{runtime-discovery-providers.ts → runtime/discovery-providers.ts}

@@ -1,8 +1,9 @@
 import { access, realpath } from "node:fs/promises";
 import { constants } from "node:fs";
 import { delimiter, isAbsolute, join } from "node:path";
-import { runtimeMetadataQuery } from "./runtime-query";
-import { requireRuntimeReadRoots } from "./runtime-paths";
+import { runtimeMetadataQuery } from "./query";
+import { requireRuntimeReadRoots } from "./paths";
+import { containsControl } from "../value-guards";
 
 export interface RuntimeDiscoverySource {
   provider: "homebrew" | "apple-developer";
@@ -45,13 +46,6 @@ export async function query(
   }
 }
 
-function containsControl(value: string): boolean {
-  return Array.from(value).some(
-    (character) =>
-      character.charCodeAt(0) < 0x20 || character.charCodeAt(0) === 0x7f,
-  );
-}
-
 export async function requireProvider(
   executable: string,
   protectedRoots: string[],

package/src/{runtime-discovery.ts → runtime/discovery.ts}

@@ -4,14 +4,14 @@ import {
   insideRuntimeRoot,
   optionalRuntimeRoots,
   requireRuntimeReadRoots,
-} from "./runtime-paths";
+} from "./paths";
 import {
   providerExecutable,
   query,
   requireProvider,
   type RuntimeDiscoverySource,
-} from "./runtime-discovery-providers";
-export type { RuntimeDiscoverySource } from "./runtime-discovery-providers";
+} from "./discovery-providers";
+export type { RuntimeDiscoverySource } from "./discovery-providers";
 
 async function homebrew(
   executable: string,
@@ -63,7 +63,7 @@ export async function discoverRuntimeSupport(
     });
   }
   if (process.platform === "darwin") {
-    const { discoverApple } = await import("./runtime-discovery-apple");
+    const { discoverApple } = await import("./discovery-apple");
     await discoverApple(path, environment, sources, protectedRoots);
   }
   return { sources, excludedPrefixes };

package/src/{runtime-hook-processes.ts → runtime/hook-processes.ts}

@@ -1,6 +1,7 @@
+import { spawn } from "../runtime-process";
 import { readFile, readdir, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
-import { isRecord } from "./value-guards";
+import { isRecord } from "../value-guards";
 
 export async function hookExecutions(
   receipts: string,
@@ -22,7 +23,7 @@ export async function hookExecutions(
 }
 
 async function processOutput(argv: string[]): Promise<string> {
-  const child = Bun.spawn(argv, { stdout: "pipe", stderr: "ignore" });
+  const child = spawn(argv, { stdout: "pipe", stderr: "ignore" });
   const output = await new Response(child.stdout).text();
   await child.exited;
   if (Buffer.byteLength(output) > 1024 * 1024)

package/src/{runtime-hooks.ts → runtime/hooks.ts}

@@ -1,3 +1,5 @@
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { existsSync } from "node:fs";
 import {
   cp,
   mkdir,
@@ -7,19 +9,21 @@ import {
   writeFile,
 } from "node:fs/promises";
 import { join } from "node:path";
-import type { RuntimePolicy } from "./runtime-config";
-import { insideRuntimeRoot, requireRuntimeReadRoots } from "./runtime-paths";
-import { runtimeSeedDigest } from "./runtime-seeds";
-import { prepareRuntimeState } from "./runtime-state";
-import { macSandboxProfile } from "./hosts/mac-sandbox";
-import type { IsolatedCommand } from "./hosts/mac-sandbox";
-import { prepareLinuxSandboxCommand } from "./hosts/linux-sandbox";
-import { isRecord, isUnknownArray } from "./value-guards";
-import { hookExecutions, releaseHookProcesses } from "./runtime-hook-processes";
+import { shellQuote as quote } from "../shell";
+import type { RuntimePolicy } from "./config";
+import { insideRuntimeRoot, requireRuntimeReadRoots } from "./paths";
+import { runtimeSeedDigest } from "./seeds";
+import { prepareRuntimeState } from "./state";
+import { sharedCacheDenyRoots, sharedCacheRoots } from "./shared-cache";
+import { macSandboxProfile } from "../hosts/mac-sandbox";
+import type { IsolatedCommand } from "../hosts/mac-sandbox";
+import { prepareLinuxSandboxCommand } from "../hosts/linux-sandbox";
+import { isRecord, isUnknownArray } from "../value-guards";
+import { hookExecutions, releaseHookProcesses } from "./hook-processes";
 import {
   nativeStateParent,
   requireNativeHookRoots,
-} from "./native-transcript-state";
+} from "../native-transcript-state";
 
 export interface HookMounts {
   directories: string[];
@@ -61,10 +65,6 @@ function object(value: unknown): Record<string, unknown> {
   return value;
 }
 
-function quote(value: string): string {
-  return `'${value.replaceAll("'", `'"'"'`)}'`;
-}
-
 /** Materialize immutable mounts; only declared plugin hooks reach the host. */
 export async function prepareHookMounts(options: {
   workspace: string;
@@ -156,7 +156,7 @@ function lazyHookExecution(
         options,
         index,
         readRoots,
-        runtime.root,
+        runtime,
       );
       if (boundary.isolation) isolation.push(boundary.isolation);
       return {
@@ -175,31 +175,43 @@ async function prepareHookIsolation(
   options: Parameters<typeof prepareHookMounts>[0],
   index: number,
   roots: { ordinary: string[]; curated: string[] },
-  runtimeRoot: string,
+  runtime: Awaited<ReturnType<typeof prepareRuntimeState>>,
 ): Promise<{ profile?: string; isolation?: IsolatedCommand }> {
+  const cacheRoots = await sharedCacheRoots(
+    options.policy,
+    "hooks",
+    options.protectedRoots,
+  );
+  const protectedRoots = [
+    ...options.protectedRoots,
+    ...sharedCacheDenyRoots(options.policy, "hooks"),
+  ];
   if (process.platform === "linux")
     return {
       isolation: await prepareLinuxSandboxCommand({
         argv: ["/bin/true"],
         workspace: options.workspace,
-        protectedRoots: options.protectedRoots,
+        protectedRoots,
         privateStateRoot: options.privateRoot,
         denyNetwork: true,
         readOnlyRoots: roots.ordinary,
         hookReadRoots: roots.curated,
-        writableRuntimeRoot: runtimeRoot,
+        writableRuntimeRoot: runtime.root,
+        writableCacheRoots: cacheRoots,
       }),
     };
   const profile = join(options.privateRoot, `hooks-${index}.sb`);
   await writeFile(
     profile,
     macSandboxProfile(
-      options.protectedRoots,
+      protectedRoots,
       true,
       roots.ordinary,
-      runtimeRoot,
+      runtime.root,
       roots.curated,
       options.workspace,
+      undefined,
+      cacheRoots,
     ) + "\n(deny process-info* (require-not (target self)))\n",
     { mode: 0o600 },
   );
@@ -217,7 +229,7 @@ async function hookReadRoots(
   ];
   const curated = trusted ? [root] : [];
   requireRuntimeReadRoots(ordinary, options.protectedRoots);
-  await requireNativeHookRoots(curated);
+  await requireNativeHookRoots(curated, options.privateRoot);
   return { ordinary, curated };
 }
 
@@ -243,23 +255,23 @@ async function rewritePlugin(
   manifest: Record<string, unknown>,
   state: HookRewrite,
 ): Promise<void> {
-  await requireHookOnlyPlugin(state.root);
+  requireHookOnlyPlugin(state.root);
   await rewriteManifest(manifest, state, ".claude-plugin/plugin.json");
   const native = join(state.root, ".codex-plugin/plugin.json");
-  if (await Bun.file(native).exists())
+  if (existsSync(native))
     await rewriteManifest(
       object(JSON.parse(await readFile(native, "utf8"))),
       state,
       ".codex-plugin/plugin.json",
     );
   const standard = join(state.root, "hooks/hooks.json");
-  if (await Bun.file(standard).exists()) await hookFile(standard, state);
+  if (existsSync(standard)) await hookFile(standard, state);
   await rewriteFrontmatter(state.root, state);
 }
 
-async function requireHookOnlyPlugin(root: string): Promise<void> {
+function requireHookOnlyPlugin(root: string): void {
   for (const name of [".mcp.json", ".lsp.json"])
-    if (await Bun.file(join(root, name)).exists())
+    if (existsSync(join(root, name)))
       throw new Error("runtime auxiliary plugin execution is unsupported");
 }
 
@@ -422,7 +434,7 @@ async function rewriteMarkdown(
   else delete metadata.hooks;
   await writeFile(
     path,
-    `---\n${Bun.YAML.stringify(metadata)}---\n${body.slice(header[0].length)}`,
+    `---\n${stringifyYaml(metadata)}\n---\n${body.slice(header[0].length)}`,
   );
 }
 
@@ -430,7 +442,7 @@ function hookFrontmatter(
   header: string | undefined,
 ): Record<string, unknown> | undefined {
   if (!header?.includes("hooks")) return undefined;
-  const metadata = object(Bun.YAML.parse(header));
+  const metadata = object(parseYaml(header));
   return metadata.hooks === undefined ? undefined : metadata;
 }
 

package/src/{runtime-paths.ts → runtime/paths.ts}

@@ -8,27 +8,20 @@ import {
 } from "node:fs/promises";
 import { constants, lstatSync, readlinkSync, realpathSync } from "node:fs";
 import { homedir, userInfo } from "node:os";
-import { nativeStateProtectedRoots } from "./native-transcript-state";
-import { workspaceStatePath } from "./workspace-state";
+import { nativeStateProtectedRoots } from "../native-transcript-state";
+import { workspaceStatePath } from "../fixtures/workspace-state";
+import { insideRoot as insideRuntimeRoot } from "../paths";
+import { containsControl } from "../value-guards";
+export { insideRoot as insideRuntimeRoot } from "../paths";
 import {
   basename,
   delimiter,
   dirname,
   isAbsolute,
   join,
-  relative,
   resolve,
-  sep,
 } from "node:path";
 
-export function insideRuntimeRoot(root: string, path: string): boolean {
-  const child = relative(root, path);
-  return (
-    child === "" ||
-    (!child.startsWith(`..${sep}`) && child !== ".." && !isAbsolute(child))
-  );
-}
-
 export function isRuntimeHomeRoot(root: string): boolean {
   return [homedir(), userInfo().homedir]
     .map((home) => resolve(home))
@@ -195,13 +188,6 @@ export async function runtimePathDirectories(
   return [...new Set(roots)].sort();
 }
 
-function containsControl(value: string): boolean {
-  return Array.from(value).some(
-    (character) =>
-      character.charCodeAt(0) < 0x20 || character.charCodeAt(0) === 0x7f,
-  );
-}
-
 function requirePathEntry(entry: string): void {
   if (!isAbsolute(entry) || containsControl(entry))
     throw new Error("runtime PATH entries must be absolute and nonempty");

package/src/{runtime-query.ts → runtime/query.ts}

@@ -1,5 +1,6 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import { homedir } from "node:os";
+import { terminateOwnedProcessGroup } from "../process-lifecycle";
 
 export class RuntimeMetadataQueryError extends Error {
   constructor(
@@ -25,11 +26,10 @@ function exitError(
 
 function stopQuery(child: ChildProcess): void {
   if (child.pid === undefined) return;
-  try {
-    process.kill(-child.pid, "SIGKILL");
-  } catch {
-    child.kill("SIGKILL");
-  }
+  terminateOwnedProcessGroup(
+    { pid: child.pid, kill: (signal) => child.kill(signal) },
+    { alwaysGroup: true, fallbackError: "propagate" },
+  );
 }
 
 /** Bound both output streams and stop every descendant of this metadata query. */