diff --git a/.coderabbit.yaml b/.coderabbit.yaml
index 0d89e281fe..2a7742140e 100644
--- a/.coderabbit.yaml
+++ b/.coderabbit.yaml
@@ -236,7 +236,7 @@ reviews:
         gh workflow run nightly-e2e.yaml --ref <branch> -f jobs=deployment-services-e2e
         ```
 
-    - path: "src/lib/sandbox-state.ts"
+    - path: "src/lib/state/sandbox.ts"
       instructions: |
         This file manages sandbox state (backup, restore, rebuild,
         snapshot). Changes affect data persistence across sandbox
diff --git a/scripts/check-legacy-migrated-paths.ts b/scripts/check-legacy-migrated-paths.ts
index edc7300528..2368b01a7a 100644
--- a/scripts/check-legacy-migrated-paths.ts
+++ b/scripts/check-legacy-migrated-paths.ts
@@ -25,7 +25,7 @@ type GuardedPath = {
 const RUNTIME_MOVES: Record<string, string> = moveMap.runtimeMoves;
 const REMOVED_SHIM_MOVES: Record<string, string> = {
   "bin/lib/chat-filter.js": "src/lib/chat-filter.ts",
-  "bin/lib/config-io.js": "src/lib/config-io.ts",
+  "bin/lib/config-io.js": "src/lib/state/config-io.ts",
   "bin/lib/debug.js": "src/lib/debug.ts",
   "bin/lib/inference-config.js": "src/lib/inference-config.ts",
   "bin/lib/local-inference.js": "src/lib/local-inference.ts",
@@ -33,7 +33,7 @@ const REMOVED_SHIM_MOVES: Record<string, string> = {
   "bin/lib/onboard-session.js": "src/lib/onboard-session.ts",
   "bin/lib/platform.js": "src/lib/platform.ts",
   "bin/lib/preflight.js": "src/lib/preflight.ts",
-  "bin/lib/registry.js": "src/lib/registry.ts",
+  "bin/lib/registry.js": "src/lib/state/registry.ts",
   "bin/lib/resolve-openshell.js": "src/lib/adapters/openshell/resolve.ts",
   "bin/lib/runtime-recovery.js": "src/lib/runtime-recovery.ts",
   "bin/lib/sandbox-build-context.js": "src/lib/sandbox-build-context.ts",
diff --git a/scripts/dev-tier-selector.js b/scripts/dev-tier-selector.js
index 153ac43591..38b1d01aca 100644
--- a/scripts/dev-tier-selector.js
+++ b/scripts/dev-tier-selector.js
@@ -20,7 +20,7 @@ const readline = require("readline");
 // ── Stubs ──────────────────────────────────────────────────────────────────
 const creds = require("../dist/lib/credentials.js");
 const runner = require("../dist/lib/runner.js");
-const registry = require("../dist/lib/registry.js");
+const registry = require("../dist/lib/state/registry.js");
 
 creds.ensureApiKey = async () => {};
 creds.getCredential = () => null;
diff --git a/scripts/ts-migration-assist.ts b/scripts/ts-migration-assist.ts
index 385d41961d..410283a00d 100644
--- a/scripts/ts-migration-assist.ts
+++ b/scripts/ts-migration-assist.ts
@@ -27,7 +27,7 @@ const SPECIAL_REWRITES: Record<string, Array<[string, string]>> = {
     ['require("./platform")', 'require("../../bin/lib/platform")'],
     ['require("./resolve-openshell")', 'require("../../bin/lib/resolve-openshell")'],
     ['require("./credentials")', 'require("../../bin/lib/credentials")'],
-    ['require("./registry")', 'require("../../bin/lib/registry")'],
+    ['require("./state/registry")', 'require("../../bin/lib/registry")'],
     ['require("./nim")', 'require("../../bin/lib/nim")'],
     ['require("./onboard-session")', 'require("../../bin/lib/onboard-session")'],
     ['require("./policies")', 'require("../../bin/lib/policies")'],
diff --git a/src/lib/actions/maintenance.ts b/src/lib/actions/maintenance.ts
index 3515d5ff7f..a3b1eaba17 100644
--- a/src/lib/actions/maintenance.ts
+++ b/src/lib/actions/maintenance.ts
@@ -11,9 +11,9 @@ import {
 import { dockerListImagesFormat, dockerRmi } from "../docker";
 import { findOrphanedSandboxImages, parseSandboxImageRows } from "../domain/maintenance/images";
 import { captureOpenshell } from "../adapters/openshell/runtime";
-import * as registry from "../registry";
+import * as registry from "../state/registry";
 import { parseLiveSandboxNames } from "../runtime-recovery";
-import * as sandboxState from "../sandbox-state";
+import * as sandboxState from "../state/sandbox";
 
 const useColor = !process.env.NO_COLOR && !!process.stdout.isTTY;
 const trueColor =
diff --git a/src/lib/actions/sandbox/connect.ts b/src/lib/actions/sandbox/connect.ts
index f4c97e2ecc..8876d2071d 100644
--- a/src/lib/actions/sandbox/connect.ts
+++ b/src/lib/actions/sandbox/connect.ts
@@ -15,13 +15,13 @@ import {
   runOpenshell,
 } from "../../adapters/openshell/runtime";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "../../adapters/openshell/timeouts";
-import * as registry from "../../registry";
+import * as registry from "../../state/registry";
 import { ROOT } from "../../runner";
 import { ensureLiveSandboxOrExit } from "./gateway-state";
 import {
   createSystemDeps as createSessionDeps,
   getActiveSandboxSessions,
-} from "../../sandbox-session-state";
+} from "../../state/sandbox-session";
 import { checkAndRecoverSandboxProcesses } from "./process-recovery";
 import * as sandboxVersion from "../../sandbox-version";
 import { D, G, R, YW } from "../../terminal-style";
diff --git a/src/lib/actions/sandbox/destroy.ts b/src/lib/actions/sandbox/destroy.ts
index f2aa110b29..d7ce7fc0e1 100644
--- a/src/lib/actions/sandbox/destroy.ts
+++ b/src/lib/actions/sandbox/destroy.ts
@@ -15,13 +15,13 @@ import * as onboardSession from "../../onboard-session";
 import type { Session } from "../../onboard-session";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "../../adapters/openshell/timeouts";
 import { DASHBOARD_PORT } from "../../ports";
-import * as registry from "../../registry";
+import * as registry from "../../state/registry";
 import { resolveOpenshell } from "../../adapters/openshell/resolve";
 import { parseLiveSandboxNames } from "../../runtime-recovery";
 import {
   createSystemDeps as createSessionDeps,
   getActiveSandboxSessions,
-} from "../../sandbox-session-state";
+} from "../../state/sandbox-session";
 import {
   getSandboxDeleteOutcome,
   shouldCleanupGatewayAfterDestroy,
diff --git a/src/lib/actions/sandbox/doctor.ts b/src/lib/actions/sandbox/doctor.ts
index 9b23a6dee6..83d17aaa08 100644
--- a/src/lib/actions/sandbox/doctor.ts
+++ b/src/lib/actions/sandbox/doctor.ts
@@ -16,8 +16,8 @@ import { stripAnsi } from "../../adapters/openshell/client";
 import { captureOpenshell } from "../../adapters/openshell/runtime";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "../../adapters/openshell/timeouts";
 import { GATEWAY_PORT, OLLAMA_PORT } from "../../ports";
-import * as registry from "../../registry";
-import type { SandboxEntry } from "../../registry";
+import * as registry from "../../state/registry";
+import type { SandboxEntry } from "../../state/registry";
 import { resolveOpenshell } from "../../adapters/openshell/resolve";
 import { ROOT } from "../../runner";
 import { parseLiveSandboxNames } from "../../runtime-recovery";
diff --git a/src/lib/actions/sandbox/gateway-state.ts b/src/lib/actions/sandbox/gateway-state.ts
index 4423994ed5..73226640d1 100644
--- a/src/lib/actions/sandbox/gateway-state.ts
+++ b/src/lib/actions/sandbox/gateway-state.ts
@@ -8,7 +8,7 @@ import os from "node:os";
 import path from "node:path";
 
 import { CLI_DISPLAY_NAME, CLI_NAME } from "../../branding";
-import { parseSandboxPhase } from "../../gateway-state";
+import { parseSandboxPhase } from "../../state/gateway";
 import {
   getNamedGatewayLifecycleState,
   recoverNamedGatewayRuntime,
@@ -30,7 +30,7 @@ import {
   OPENSHELL_OPERATION_TIMEOUT_MS,
   OPENSHELL_PROBE_TIMEOUT_MS,
 } from "../../adapters/openshell/timeouts";
-import * as registry from "../../registry";
+import * as registry from "../../state/registry";
 
 type SandboxGatewayState = {
   state: string;
diff --git a/src/lib/actions/sandbox/policy-channel.ts b/src/lib/actions/sandbox/policy-channel.ts
index 91b392cf1e..a7766bad35 100644
--- a/src/lib/actions/sandbox/policy-channel.ts
+++ b/src/lib/actions/sandbox/policy-channel.ts
@@ -14,7 +14,7 @@ const { isNonInteractive } = require("../../onboard") as { isNonInteractive: ()
 const onboardProviders = require("../../onboard-providers");
 import * as policies from "../../policies";
 import { parsePolicyAddArgs } from "../../domain/policy-channel";
-import * as registry from "../../registry";
+import * as registry from "../../state/registry";
 import { runOpenshell } from "../../adapters/openshell/runtime";
 import { rebuildSandbox } from "./runtime";
 import {
diff --git a/src/lib/actions/sandbox/process-recovery.ts b/src/lib/actions/sandbox/process-recovery.ts
index f207f26689..61f33c15fc 100644
--- a/src/lib/actions/sandbox/process-recovery.ts
+++ b/src/lib/actions/sandbox/process-recovery.ts
@@ -18,7 +18,7 @@ import {
   runOpenshell,
 } from "../../adapters/openshell/runtime";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "../../adapters/openshell/timeouts";
-import { parseForwardList } from "../../sandbox-session-state";
+import { parseForwardList } from "../../state/sandbox-session";
 import { G, R } from "../../terminal-style";
 import { sleepSeconds } from "../../wait";
 
diff --git a/src/lib/actions/sandbox/rebuild.ts b/src/lib/actions/sandbox/rebuild.ts
index 528e47fecf..5313fc2012 100644
--- a/src/lib/actions/sandbox/rebuild.ts
+++ b/src/lib/actions/sandbox/rebuild.ts
@@ -26,7 +26,7 @@ import type { Session } from "../../onboard-session";
 import * as onboardSession from "../../onboard-session";
 import { captureOpenshell, runOpenshell } from "../../adapters/openshell/runtime";
 import * as policies from "../../policies";
-import * as registry from "../../registry";
+import * as registry from "../../state/registry";
 import { resolveOpenshell } from "../../adapters/openshell/resolve";
 import { parseLiveSandboxNames } from "../../runtime-recovery";
 import { removeSandboxRegistryEntry } from "./destroy";
@@ -34,8 +34,8 @@ import { executeSandboxCommand } from "./process-recovery";
 import {
   createSystemDeps as createSessionDeps,
   getActiveSandboxSessions,
-} from "../../sandbox-session-state";
-import * as sandboxState from "../../sandbox-state";
+} from "../../state/sandbox-session";
+import * as sandboxState from "../../state/sandbox";
 import * as sandboxVersion from "../../sandbox-version";
 import { B, D, G, R, RD as _RD, YW } from "../../terminal-style";
 
diff --git a/src/lib/actions/sandbox/snapshot.ts b/src/lib/actions/sandbox/snapshot.ts
index 8bc19aa872..42c85bf81f 100644
--- a/src/lib/actions/sandbox/snapshot.ts
+++ b/src/lib/actions/sandbox/snapshot.ts
@@ -12,9 +12,9 @@ import { parseLiveSandboxNames } from "../../runtime-recovery";
 import { ROOT, run, shellQuote, validateName } from "../../runner";
 import { captureOpenshell, getOpenshellBinary } from "../../adapters/openshell/runtime";
 import * as policies from "../../policies";
-import * as registry from "../../registry";
-import type { SandboxEntry } from "../../registry";
-import * as sandboxState from "../../sandbox-state";
+import * as registry from "../../state/registry";
+import type { SandboxEntry } from "../../state/registry";
+import * as sandboxState from "../../state/sandbox";
 
 const { parseRestoreArgs } = sandboxState;
 
@@ -119,7 +119,7 @@ async function autoCreateSandboxFromSource(
   srcEntry: SandboxEntry | { name: string },
 ): Promise<void> {
   const sandboxCreateStream = require("../../sandbox-create-stream");
-  const { isSandboxReady } = require("../../gateway-state");
+  const { isSandboxReady } = require("../../state/gateway");
   const basePolicy = path.join(ROOT, "nemoclaw-blueprint", "policies", "openclaw-sandbox.yaml");
   const openshellBin = getOpenshellBinary();
 
diff --git a/src/lib/actions/sandbox/status.ts b/src/lib/actions/sandbox/status.ts
index 803c6d4507..9e998b01dd 100644
--- a/src/lib/actions/sandbox/status.ts
+++ b/src/lib/actions/sandbox/status.ts
@@ -4,7 +4,7 @@
 /* v8 ignore start -- exercised through CLI subprocess status tests. */
 
 import { CLI_DISPLAY_NAME, CLI_NAME } from "../../branding";
-import { parseSandboxPhase } from "../../gateway-state";
+import { parseSandboxPhase } from "../../state/gateway";
 import { getNamedGatewayLifecycleState } from "../../gateway-runtime-action";
 import { parseGatewayInference } from "../../inference-config";
 import { probeProviderHealth } from "../../inference-health";
@@ -15,7 +15,7 @@ import {
   captureOpenshellForStatus,
   isCommandTimeout,
 } from "../../adapters/openshell/runtime";
-import * as registry from "../../registry";
+import * as registry from "../../state/registry";
 import { resolveOpenshell } from "../../adapters/openshell/resolve";
 import {
   getReconciledSandboxGatewayState,
@@ -27,7 +27,7 @@ import { isSandboxGatewayRunningForStatus } from "./process-recovery";
 import {
   createSystemDeps as createSessionDeps,
   getActiveSandboxSessions,
-} from "../../sandbox-session-state";
+} from "../../state/sandbox-session";
 import * as sandboxVersion from "../../sandbox-version";
 import * as shields from "../../shields";
 import { D, G, R, RD, YW } from "../../terminal-style";
diff --git a/src/lib/actions/upgrade-sandboxes.ts b/src/lib/actions/upgrade-sandboxes.ts
index 0261a6749f..71993a7cc0 100644
--- a/src/lib/actions/upgrade-sandboxes.ts
+++ b/src/lib/actions/upgrade-sandboxes.ts
@@ -10,7 +10,7 @@ import {
   type UpgradeSandboxesOptions,
 } from "../domain/lifecycle/options";
 import { captureOpenshell } from "../adapters/openshell/runtime";
-import * as registry from "../registry";
+import * as registry from "../state/registry";
 import { parseLiveSandboxNames } from "../runtime-recovery";
 import { rebuildSandbox } from "./sandbox/rebuild";
 import * as sandboxVersion from "../sandbox-version";
diff --git a/src/lib/agent-runtime.ts b/src/lib/agent-runtime.ts
index 270002a653..76ca1a92ec 100644
--- a/src/lib/agent-runtime.ts
+++ b/src/lib/agent-runtime.ts
@@ -7,7 +7,7 @@
 // When the session agent is openclaw (or absent), all functions return
 // defaults that match the hardcoded OpenClaw values on main.
 
-import * as registry from "./registry";
+import * as registry from "./state/registry";
 import { DASHBOARD_PORT } from "./ports";
 import * as onboardSession from "./onboard-session";
 import { loadAgent, type AgentDefinition } from "./agent-defs";
diff --git a/src/lib/commands/debug.ts b/src/lib/commands/debug.ts
index db9aead37b..9b1662050b 100644
--- a/src/lib/commands/debug.ts
+++ b/src/lib/commands/debug.ts
@@ -11,7 +11,7 @@ import { runDebugCommandWithOptions } from "../debug-command";
 import type { CaptureOpenshellResult } from "../adapters/openshell/client";
 import { captureOpenshellCommand } from "../adapters/openshell/client";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "../adapters/openshell/timeouts";
-import * as registry from "../registry";
+import * as registry from "../state/registry";
 import { resolveOpenshell } from "../adapters/openshell/resolve";
 import { parseLiveSandboxNames } from "../runtime-recovery";
 
diff --git a/src/lib/commands/simple-global-oclif-adapters.test.ts b/src/lib/commands/simple-global-oclif-adapters.test.ts
index 8e40bae33e..b2ed49a2cf 100644
--- a/src/lib/commands/simple-global-oclif-adapters.test.ts
+++ b/src/lib/commands/simple-global-oclif-adapters.test.ts
@@ -37,7 +37,7 @@ vi.mock("../actions/global", () => ({
   showVersion: mocks.showVersion,
 }));
 vi.mock("../adapters/openshell/client", () => ({ captureOpenshellCommand: mocks.captureOpenshellCommand }));
-vi.mock("../registry", () => ({ listSandboxes: mocks.listSandboxes }));
+vi.mock("../state/registry", () => ({ listSandboxes: mocks.listSandboxes }));
 vi.mock("../adapters/openshell/resolve", () => ({ resolveOpenshell: mocks.resolveOpenshell }));
 vi.mock("../services", () => ({ startAll: mocks.startAll, stopAll: mocks.stopAll }));
 vi.mock("../services-command", () => ({
diff --git a/src/lib/commands/tunnel/common.ts b/src/lib/commands/tunnel/common.ts
index ffa7f040bb..00671d7df6 100644
--- a/src/lib/commands/tunnel/common.ts
+++ b/src/lib/commands/tunnel/common.ts
@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import * as registry from "../../registry";
+import * as registry from "../../state/registry";
 
 export function serviceDeps() {
   return {
diff --git a/src/lib/credentials.ts b/src/lib/credentials.ts
index dde86d11cb..a3012ad8c5 100644
--- a/src/lib/credentials.ts
+++ b/src/lib/credentials.ts
@@ -14,7 +14,7 @@ import os from "node:os";
 import path from "node:path";
 import readline from "node:readline";
 
-import { rejectSymlinksOnPath } from "./config-io";
+import { rejectSymlinksOnPath } from "./state/config-io";
 import { isErrnoException } from "./errno";
 
 const UNSAFE_HOME_PATHS = new Set(["/tmp", "/var/tmp", "/dev/shm", "/"]);
diff --git a/src/lib/debug.ts b/src/lib/debug.ts
index 6f331b2e23..4a5c95aea2 100644
--- a/src/lib/debug.ts
+++ b/src/lib/debug.ts
@@ -8,7 +8,7 @@ import { platform, tmpdir } from "node:os";
 import { basename, dirname, join } from "node:path";
 
 import { DASHBOARD_PORT } from "./ports";
-import { listSandboxes } from "./registry";
+import { listSandboxes } from "./state/registry";
 
 // ---------------------------------------------------------------------------
 // Types
diff --git a/src/lib/http-probe.ts b/src/lib/http-probe.ts
index 26c5ed7549..05f51c0ea9 100644
--- a/src/lib/http-probe.ts
+++ b/src/lib/http-probe.ts
@@ -11,7 +11,7 @@ import {
 } from "node:child_process";
 
 import type { ProbeResult } from "./onboard-types";
-import { ROOT } from "./paths";
+import { ROOT } from "./state/paths";
 import { compactText } from "./url-utils";
 
 import { isErrnoException } from "./errno";
diff --git a/src/lib/list-command-deps.ts b/src/lib/list-command-deps.ts
index 7bc2792b03..41d74c6d91 100644
--- a/src/lib/list-command-deps.ts
+++ b/src/lib/list-command-deps.ts
@@ -7,7 +7,7 @@ import * as onboardSession from "./onboard-session";
 import type { ListSandboxesCommandDeps } from "./inventory-commands";
 import { parseGatewayInference } from "./inference-config";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "./adapters/openshell/timeouts";
-import { parseSshProcesses, createSystemDeps } from "./sandbox-session-state";
+import { parseSshProcesses, createSystemDeps } from "./state/sandbox-session";
 import { resolveOpenshell } from "./adapters/openshell/resolve";
 import { captureOpenshell } from "./adapters/openshell/runtime";
 import { recoverRegistryEntries } from "./registry-recovery-action";
diff --git a/src/lib/messaging-conflict.test.ts b/src/lib/messaging-conflict.test.ts
index 91f48bc4d7..756ed919ad 100644
--- a/src/lib/messaging-conflict.test.ts
+++ b/src/lib/messaging-conflict.test.ts
@@ -3,7 +3,7 @@
 
 import { describe, expect, it, vi } from "vitest";
 
-import type { SandboxEntry } from "./registry";
+import type { SandboxEntry } from "./state/registry";
 import {
   backfillMessagingChannels,
   findAllOverlaps,
diff --git a/src/lib/messaging-conflict.ts b/src/lib/messaging-conflict.ts
index 1baa494093..8486a8e369 100644
--- a/src/lib/messaging-conflict.ts
+++ b/src/lib/messaging-conflict.ts
@@ -13,7 +13,7 @@
 // added have no record — can optionally backfill the channel field by probing
 // the live OpenShell gateway for known provider names.
 
-import type { SandboxEntry } from "./registry";
+import type { SandboxEntry } from "./state/registry";
 import { getChannelDef, getChannelTokenKeys } from "./sandbox-channels";
 
 type ProbeResult = "present" | "absent" | "error";
diff --git a/src/lib/onboard.ts b/src/lib/onboard.ts
index c4ca1772fc..0642c2f677 100644
--- a/src/lib/onboard.ts
+++ b/src/lib/onboard.ts
@@ -272,7 +272,7 @@ const {
   saveCredential,
 } = credentials;
 const { hashCredential }: typeof import("./credential-hash") = require("./credential-hash");
-const registry: typeof import("./registry") = require("./registry");
+const registry: typeof import("./state/registry") = require("./state/registry");
 const nim: typeof import("./nim") = require("./nim");
 const onboardSession: typeof import("./onboard-session") = require("./onboard-session");
 const policies: typeof import("./policies") = require("./policies");
@@ -293,8 +293,8 @@ const {
 const agentOnboard = require("./agent-onboard");
 const agentDefs = require("./agent-defs");
 
-const gatewayState: typeof import("./gateway-state") = require("./gateway-state");
-const sandboxState: typeof import("./sandbox-state") = require("./sandbox-state");
+const gatewayState: typeof import("./state/gateway") = require("./state/gateway");
+const sandboxState: typeof import("./state/sandbox") = require("./state/sandbox");
 const validation: typeof import("./validation") = require("./validation");
 const urlUtils: typeof import("./url-utils") = require("./url-utils");
 const buildContext = require("./build-context");
@@ -310,6 +310,8 @@ import type { AgentDefinition } from "./agent-defs";
 import type { CurlProbeResult } from "./http-probe";
 import type { GatewayInference, ProviderSelectionConfig } from "./inference-config";
 import type { GpuInfo, ValidationResult } from "./local-inference";
+import type { ContainerRuntime } from "./platform";
+import type { SandboxEntry } from "./state/registry";
 import type { Session, SessionUpdates } from "./onboard-session";
 import type {
   ModelCatalogFetchResult,
@@ -317,11 +319,9 @@ import type {
   ProbeResult,
   ValidationFailureLike,
 } from "./onboard-types";
-import type { ContainerRuntime } from "./platform";
-import type { SandboxEntry } from "./registry";
 import { listChannels } from "./sandbox-channels";
 import type { StreamSandboxCreateResult } from "./sandbox-create-stream";
-import type { BackupResult } from "./sandbox-state";
+import type { BackupResult } from "./state/sandbox";
 import type { TierDefinition, TierPreset } from "./tiers";
 import type { SandboxCreateFailure, ValidationClassification } from "./validation";
 import type { ProbeRecovery } from "./validation-recovery";
@@ -505,7 +505,7 @@ async function promptYesNoOrDefault(
 
 // ── Helpers ──────────────────────────────────────────────────────
 
-// Gateway state functions — delegated to src/lib/gateway-state.ts
+// Gateway state functions — delegated to src/lib/state/gateway.ts
 const {
   isSandboxReady,
   parseSandboxStatus,
diff --git a/src/lib/policies.ts b/src/lib/policies.ts
index e670297505..0bcdf3ad9b 100644
--- a/src/lib/policies.ts
+++ b/src/lib/policies.ts
@@ -11,7 +11,7 @@ const os = require("os");
 const readline = require("readline");
 const YAML = require("yaml");
 const { ROOT, run, runCapture } = require("./runner");
-const registry = require("./registry");
+const registry = require("./state/registry");
 const { loadAgent } = require("./agent-defs");
 
 const PRESETS_DIR = path.join(ROOT, "nemoclaw-blueprint", "policies", "presets");
diff --git a/src/lib/registry-recovery-action.test.ts b/src/lib/registry-recovery-action.test.ts
index 604677954b..d79d7a43f2 100644
--- a/src/lib/registry-recovery-action.test.ts
+++ b/src/lib/registry-recovery-action.test.ts
@@ -3,7 +3,7 @@
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import type { SandboxEntry } from "./registry.js";
+import type { SandboxEntry } from "./state/registry.js";
 
 interface MockRegistryState {
   sandboxes: Record<string, SandboxEntry>;
@@ -12,7 +12,7 @@ interface MockRegistryState {
 
 const mockRegistryState: MockRegistryState = { sandboxes: {}, defaultSandbox: null };
 
-vi.mock("./registry.js", () => ({
+vi.mock("./state/registry.js", () => ({
   listSandboxes: () => ({
     sandboxes: Object.values(mockRegistryState.sandboxes),
     defaultSandbox: mockRegistryState.defaultSandbox,
diff --git a/src/lib/registry-recovery-action.ts b/src/lib/registry-recovery-action.ts
index cc02dfbd16..a753a5f838 100644
--- a/src/lib/registry-recovery-action.ts
+++ b/src/lib/registry-recovery-action.ts
@@ -6,8 +6,8 @@ import type { RecoveryResult } from "./inventory-commands";
 import * as onboardSession from "./onboard-session";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "./adapters/openshell/timeouts";
 import { captureOpenshell } from "./adapters/openshell/runtime";
-import * as registry from "./registry";
-import type { SandboxEntry } from "./registry";
+import * as registry from "./state/registry";
+import type { SandboxEntry } from "./state/registry";
 import { resolveOpenshell } from "./adapters/openshell/resolve";
 import { parseLiveSandboxNames } from "./runtime-recovery";
 import { validateName } from "./runner";
diff --git a/src/lib/sandbox-config.ts b/src/lib/sandbox-config.ts
index 0c1340273a..5762a8428d 100644
--- a/src/lib/sandbox-config.ts
+++ b/src/lib/sandbox-config.ts
@@ -94,7 +94,7 @@ const DEFAULT_AGENT_CONFIG: AgentConfigTarget = {
 
 function resolveAgentConfig(sandboxName: string): AgentConfigTarget {
   try {
-    const registry = require("./registry");
+    const registry = require("./state/registry");
     const entry = registry.getSandbox(sandboxName);
     if (!entry || !entry.agent) return DEFAULT_AGENT_CONFIG;
 
diff --git a/src/lib/sandbox-create-stream.ts b/src/lib/sandbox-create-stream.ts
index fb12c69f30..02c684f3df 100644
--- a/src/lib/sandbox-create-stream.ts
+++ b/src/lib/sandbox-create-stream.ts
@@ -3,7 +3,7 @@
 
 import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process";
 
-import { ROOT } from "./paths";
+import { ROOT } from "./state/paths";
 
 export interface StreamSandboxCreateResult {
   status: number;
diff --git a/src/lib/sandbox-version.test.ts b/src/lib/sandbox-version.test.ts
index 90a844493e..fe1f7f770d 100644
--- a/src/lib/sandbox-version.test.ts
+++ b/src/lib/sandbox-version.test.ts
@@ -48,7 +48,7 @@ vi.mock("child_process", async (importOriginal) => {
 });
 
 import { checkAgentVersion, formatStalenessWarning } from "./sandbox-version.js";
-import * as registry from "./registry.js";
+import * as registry from "./state/registry.js";
 import { captureOpenshellCommand } from "./adapters/openshell/client.js";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "./adapters/openshell/timeouts.js";
 import { spawnSync } from "child_process";
diff --git a/src/lib/sandbox-version.ts b/src/lib/sandbox-version.ts
index 0c76ab5f93..2904f274cc 100644
--- a/src/lib/sandbox-version.ts
+++ b/src/lib/sandbox-version.ts
@@ -14,7 +14,7 @@ import os from "os";
 import path from "path";
 
 import { parseVersionFromText, versionGte } from "./adapters/openshell/client.js";
-import * as registry from "./registry.js";
+import * as registry from "./state/registry.js";
 import { loadAgent } from "./agent-defs.js";
 import { resolveOpenshell } from "./adapters/openshell/resolve.js";
 import { captureOpenshellCommand } from "./adapters/openshell/client.js";
diff --git a/src/lib/shields-audit.ts b/src/lib/shields-audit.ts
index 45e72c8573..cc21cd79be 100644
--- a/src/lib/shields-audit.ts
+++ b/src/lib/shields-audit.ts
@@ -11,7 +11,7 @@
 
 import { appendFileSync } from "node:fs";
 import { join } from "node:path";
-import { ensureConfigDir } from "./config-io";
+import { ensureConfigDir } from "./state/config-io";
 import { redactFull } from "./redact";
 
 const AUDIT_DIR = join(process.env.HOME ?? "/tmp", ".nemoclaw", "state");
diff --git a/src/lib/config-io.test.ts b/src/lib/state/config-io.test.ts
similarity index 99%
rename from src/lib/config-io.test.ts
rename to src/lib/state/config-io.test.ts
index d8bbf6cce7..05e07d35fb 100644
--- a/src/lib/config-io.test.ts
+++ b/src/lib/state/config-io.test.ts
@@ -11,7 +11,7 @@ import {
   ensureConfigDir,
   readConfigFile,
   writeConfigFile,
-} from "../../dist/lib/config-io";
+} from "../../../dist/lib/state/config-io";
 
 const tmpDirs: string[] = [];
 
diff --git a/src/lib/config-io.ts b/src/lib/state/config-io.ts
similarity index 98%
rename from src/lib/config-io.ts
rename to src/lib/state/config-io.ts
index 2dfc8e7c8a..f9bbc5cfd5 100644
--- a/src/lib/config-io.ts
+++ b/src/lib/state/config-io.ts
@@ -7,8 +7,8 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-import { shellQuote } from "./shell-quote";
-import { isErrnoException, isPermissionError } from "./errno";
+import { shellQuote } from "../shell-quote";
+import { isErrnoException, isPermissionError } from "../errno";
 
 // Strict JSON types for file serialization — unlike json-types.ts,
 // these exclude undefined since actual JSON cannot contain it.
diff --git a/src/lib/gateway-state.ts b/src/lib/state/gateway.ts
similarity index 100%
rename from src/lib/gateway-state.ts
rename to src/lib/state/gateway.ts
diff --git a/src/lib/paths.test.ts b/src/lib/state/paths.test.ts
similarity index 91%
rename from src/lib/paths.test.ts
rename to src/lib/state/paths.test.ts
index fb34a0f6ed..268b5ccaef 100644
--- a/src/lib/paths.test.ts
+++ b/src/lib/state/paths.test.ts
@@ -5,7 +5,7 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 
-import { ROOT, SCRIPTS } from "../../dist/lib/paths";
+import { ROOT, SCRIPTS } from "../../../dist/lib/state/paths";
 
 describe("paths", () => {
   it("resolves the repo root", () => {
diff --git a/src/lib/paths.ts b/src/lib/state/paths.ts
similarity index 77%
rename from src/lib/paths.ts
rename to src/lib/state/paths.ts
index 0ea0c2868e..a1d442ffb4 100644
--- a/src/lib/paths.ts
+++ b/src/lib/state/paths.ts
@@ -3,5 +3,5 @@
 
 import path from "node:path";
 
-export const ROOT = path.resolve(__dirname, "..", "..");
+export const ROOT = path.resolve(__dirname, "..", "..", "..");
 export const SCRIPTS = path.join(ROOT, "scripts");
diff --git a/src/lib/registry.ts b/src/lib/state/registry.ts
similarity index 99%
rename from src/lib/registry.ts
rename to src/lib/state/registry.ts
index c5b54d13f8..fa813729ca 100644
--- a/src/lib/registry.ts
+++ b/src/lib/state/registry.ts
@@ -5,7 +5,7 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { ensureConfigDir, readConfigFile, writeConfigFile } from "./config-io";
-import { isErrnoException } from "./errno";
+import { isErrnoException } from "../errno";
 
 export interface CustomPolicyEntry {
   name: string;
diff --git a/src/lib/sandbox-session-state.test.ts b/src/lib/state/sandbox-session.test.ts
similarity index 99%
rename from src/lib/sandbox-session-state.test.ts
rename to src/lib/state/sandbox-session.test.ts
index 7a4fb0b85b..a44d412f32 100644
--- a/src/lib/sandbox-session-state.test.ts
+++ b/src/lib/state/sandbox-session.test.ts
@@ -12,7 +12,7 @@ import {
   type ForwardEntry,
   type SessionClassification,
   type SessionDetectionDeps,
-} from "./sandbox-session-state";
+} from "./sandbox-session";
 
 describe("parseForwardList", () => {
   it("returns empty array for empty/null input", () => {
diff --git a/src/lib/sandbox-session-state.ts b/src/lib/state/sandbox-session.ts
similarity index 100%
rename from src/lib/sandbox-session-state.ts
rename to src/lib/state/sandbox-session.ts
diff --git a/src/lib/sandbox-state.ts b/src/lib/state/sandbox.ts
similarity index 99%
rename from src/lib/sandbox-state.ts
rename to src/lib/state/sandbox.ts
index 9159e7d6c0..ecaefa974c 100644
--- a/src/lib/sandbox-state.ts
+++ b/src/lib/state/sandbox.ts
@@ -26,12 +26,12 @@ import os from "node:os";
 import path from "node:path";
 
 import * as registry from "./registry.js";
-import { loadAgent } from "./agent-defs.js";
-import type { AgentStateFile } from "./agent-defs.js";
-import { resolveOpenshell } from "./adapters/openshell/resolve.js";
-import { captureOpenshellCommand } from "./adapters/openshell/client.js";
-import { sanitizeConfigFile, isSensitiveFile } from "./credential-filter.js";
-import { shellQuote } from "./runner.js";
+import { loadAgent } from "../agent-defs.js";
+import type { AgentStateFile } from "../agent-defs.js";
+import { resolveOpenshell } from "../adapters/openshell/resolve.js";
+import { captureOpenshellCommand } from "../adapters/openshell/client.js";
+import { sanitizeConfigFile, isSensitiveFile } from "../credential-filter.js";
+import { shellQuote } from "../runner.js";
 
 const HOME_DIR = path.resolve(process.env.HOME || os.homedir());
 const REBUILD_BACKUPS_DIR = path.join(HOME_DIR, ".nemoclaw", "rebuild-backups");
diff --git a/src/lib/status-command-deps.ts b/src/lib/status-command-deps.ts
index 3512039b2a..fb239833f9 100644
--- a/src/lib/status-command-deps.ts
+++ b/src/lib/status-command-deps.ts
@@ -11,7 +11,7 @@ import { backfillMessagingChannels, findAllOverlaps } from "./messaging-conflict
 import type { CaptureOpenshellResult } from "./adapters/openshell/client";
 import { captureOpenshellCommand, stripAnsi } from "./adapters/openshell/client";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "./adapters/openshell/timeouts";
-import * as registry from "./registry";
+import * as registry from "./state/registry";
 import { resolveOpenshell } from "./adapters/openshell/resolve";
 import { getServiceStatuses, showStatus as showServiceStatus } from "./services";
 
diff --git a/src/nemoclaw.ts b/src/nemoclaw.ts
index 77062101b1..3e4448a1ed 100644
--- a/src/nemoclaw.ts
+++ b/src/nemoclaw.ts
@@ -36,8 +36,8 @@ const {
 } = require("./lib/docker");
 const { resolveOpenshell } = require("./lib/adapters/openshell/resolve");
 const { hydrateCredentialEnv, isNonInteractive } = require("./lib/onboard");
-const registry = require("./lib/registry");
-import type { SandboxEntry } from "./lib/registry";
+const registry = require("./lib/state/registry");
+import type { SandboxEntry } from "./lib/state/registry";
 const nim = require("./lib/nim");
 const shields = require("./lib/shields");
 const { parseGatewayInference } = require("./lib/inference-config");
@@ -70,13 +70,13 @@ const {
 const { runRegisteredOclifCommand } = require("./lib/cli/oclif-runner");
 const { isErrnoException }: typeof import("./lib/errno") = require("./lib/errno");
 const agentRuntime = require("../bin/lib/agent-runtime");
-const sandboxState = require("./lib/sandbox-state");
+const sandboxState = require("./lib/state/sandbox");
 const { parseRestoreArgs } = sandboxState;
 const {
   getActiveSandboxSessions,
   createSystemDeps: createSessionDeps,
   parseForwardList,
-} = require("./lib/sandbox-session-state");
+} = require("./lib/state/sandbox-session");
 
 const {
   canonicalUsageList,
diff --git a/test/config-set-cli-dispatch.test.ts b/test/config-set-cli-dispatch.test.ts
index 23e4646268..4baba1f0b0 100644
--- a/test/config-set-cli-dispatch.test.ts
+++ b/test/config-set-cli-dispatch.test.ts
@@ -18,7 +18,7 @@ function deferred<T>() {
 describe("config set CLI dispatch", () => {
   it("awaits configSet before completing the dispatcher", async () => {
     const cliPath = require.resolve("../dist/nemoclaw.js");
-    const registryPath = require.resolve("../dist/lib/registry.js");
+    const registryPath = require.resolve("../dist/lib/state/registry.js");
     const sandboxConfigPath = require.resolve("../dist/lib/sandbox-config.js");
     const runnerPath = require.resolve("../dist/lib/runner.js");
 
diff --git a/test/credential-rotation.test.ts b/test/credential-rotation.test.ts
index ce8a6c0dca..6122584059 100644
--- a/test/credential-rotation.test.ts
+++ b/test/credential-rotation.test.ts
@@ -35,7 +35,7 @@ function isCredentialRotationInternals(value: object | null): value is Credentia
   );
 }
 
-function isRegistryModule(value: object | null): value is typeof import("../dist/lib/registry.js") {
+function isRegistryModule(value: object | null): value is typeof import("../dist/lib/state/registry.js") {
   return isRecord(value) && typeof value.getSandbox === "function";
 }
 
@@ -48,8 +48,8 @@ function loadCredentialRotationInternals(): CredentialRotationInternals {
   return record;
 }
 
-function loadRegistryModule(): typeof import("../dist/lib/registry.js") {
-  const loaded = require("../dist/lib/registry.js");
+function loadRegistryModule(): typeof import("../dist/lib/state/registry.js") {
+  const loaded = require("../dist/lib/state/registry.js");
   const record = typeof loaded === "object" && loaded !== null ? loaded : null;
   if (!isRegistryModule(record)) {
     throw new Error("Expected registry module to expose getSandbox");
@@ -60,7 +60,7 @@ function loadRegistryModule(): typeof import("../dist/lib/registry.js") {
 describe("credential rotation detection", () => {
   let hashCredential: CredentialRotationInternals["hashCredential"];
   let detectMessagingCredentialRotation: CredentialRotationInternals["detectMessagingCredentialRotation"];
-  let registry: typeof import("../dist/lib/registry.js");
+  let registry: typeof import("../dist/lib/state/registry.js");
 
   beforeEach(() => {
     // Fresh imports to avoid cross-test contamination
diff --git a/test/e2e/brev-e2e.test.ts b/test/e2e/brev-e2e.test.ts
index f2ab5c5e82..5eca7c3818 100644
--- a/test/e2e/brev-e2e.test.ts
+++ b/test/e2e/brev-e2e.test.ts
@@ -610,7 +610,7 @@ function pollForSandboxReady(elapsed: () => string): void {
  * The onboard hangs on the dashboard port-forward step and never writes
  * sandboxes.json. We kill it and write the registry ourselves.
  *
- * Note: The registry shape matches SandboxRegistry from src/lib/registry.ts
+ * Note: The registry shape matches SandboxRegistry from src/lib/state/registry.ts
  * (sandboxes + defaultSandbox only — no version field).
  */
 function writeManualRegistry(elapsed: () => string): void {
diff --git a/test/gateway-liveness-probe.test.ts b/test/gateway-liveness-probe.test.ts
index b69096bc66..7d6e092163 100644
--- a/test/gateway-liveness-probe.test.ts
+++ b/test/gateway-liveness-probe.test.ts
@@ -72,16 +72,16 @@ describe("gateway liveness probe (#2020)", () => {
     expect(cleanupAfterProbe).toBeTruthy();
   });
 
-  it("does not modify isGatewayHealthy() in gateway-state.ts", () => {
+  it("does not modify isGatewayHealthy() in src/lib/state/gateway.ts", () => {
     // isGatewayHealthy() must remain a pure function — no I/O.
     // Scope the check to the function body so unrelated helpers don't cause false failures.
-    const gsContent = fs.readFileSync(path.join(ROOT, "src/lib/gateway-state.ts"), "utf-8");
+    const gsContent = fs.readFileSync(path.join(ROOT, "src/lib/state/gateway.ts"), "utf-8");
     const fnMatch = gsContent.match(
       /(?:function isGatewayHealthy|const isGatewayHealthy\b)[\s\S]*?\n\}/,
     );
     expect(fnMatch).toBeTruthy();
     if (!fnMatch) {
-      throw new Error("Expected isGatewayHealthy() in src/lib/gateway-state.ts");
+      throw new Error("Expected isGatewayHealthy() in src/lib/state/gateway.ts");
     }
     const fnBody = fnMatch[0];
     expect(fnBody).not.toContain("docker");
diff --git a/test/gateway-state.test.ts b/test/gateway-state.test.ts
index a952f8c3c1..764dd7317b 100644
--- a/test/gateway-state.test.ts
+++ b/test/gateway-state.test.ts
@@ -14,7 +14,7 @@ import {
   hasActiveGatewayInfo,
   getReportedGatewayName,
   parseSandboxPhase,
-} from "../src/lib/gateway-state.js";
+} from "../src/lib/state/gateway.js";
 
 // Realistic CLI outputs
 const STATUS_CONNECTED = `
diff --git a/test/image-cleanup.test.ts b/test/image-cleanup.test.ts
index 1b0892c4bc..f1364c6ff7 100644
--- a/test/image-cleanup.test.ts
+++ b/test/image-cleanup.test.ts
@@ -98,7 +98,7 @@ describe("image cleanup: onboard records imageTag in registry (#2086)", () => {
 });
 
 describe("image cleanup: registry stores imageTag (#2086)", () => {
-  const registrySrc = fs.readFileSync(path.join(ROOT, "src/lib/registry.ts"), "utf-8");
+  const registrySrc = fs.readFileSync(path.join(ROOT, "src/lib/state/registry.ts"), "utf-8");
 
   it("SandboxEntry interface includes imageTag field", () => {
     expect(registrySrc).toMatch(/imageTag\?:\s*string\s*\|\s*null/);
@@ -109,7 +109,7 @@ describe("image cleanup: registry stores imageTag (#2086)", () => {
     const registerMatch = registrySrc.match(/function registerSandbox[\s\S]*?^}/m);
     expect(registerMatch).toBeTruthy();
     if (!registerMatch) {
-      throw new Error("Expected registerSandbox() in src/lib/registry.ts");
+      throw new Error("Expected registerSandbox() in src/lib/state/registry.ts");
     }
     expect(registerMatch[0]).toContain("imageTag");
   });
diff --git a/test/onboard-preset-diff.test.ts b/test/onboard-preset-diff.test.ts
index ac168870b1..4319a616ca 100644
--- a/test/onboard-preset-diff.test.ts
+++ b/test/onboard-preset-diff.test.ts
@@ -49,7 +49,7 @@ function buildPreamble({
 } = {}): string {
   const credPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
   const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-  const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+  const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
   const policiesPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "policies.js"));
   const resolveOpenshellPath = JSON.stringify(
     path.join(repoRoot, "dist", "lib", "adapters", "openshell", "resolve.js"),
diff --git a/test/onboard-resume-provider-recovery.test.ts b/test/onboard-resume-provider-recovery.test.ts
index f26927b432..5eb4583f01 100644
--- a/test/onboard-resume-provider-recovery.test.ts
+++ b/test/onboard-resume-provider-recovery.test.ts
@@ -42,7 +42,7 @@ const {
   readRecordedNimContainer,
 } = onboardModule;
 
-const registry: typeof import("../dist/lib/registry") = require("../dist/lib/registry");
+const registry: typeof import("../dist/lib/state/registry") = require("../dist/lib/state/registry");
 const onboardSession: typeof import("../dist/lib/onboard-session") = require("../dist/lib/onboard-session");
 
 // Force readLiveInference's defaultSandbox check to fail so unit tests that
diff --git a/test/onboard-selection.test.ts b/test/onboard-selection.test.ts
index 5a6326eea0..17f9020561 100644
--- a/test/onboard-selection.test.ts
+++ b/test/onboard-selection.test.ts
@@ -106,7 +106,7 @@ describe("onboard provider selection UX", () => {
     const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
     const credentialsPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
 
     fs.mkdirSync(fakeBin, { recursive: true });
     fs.writeFileSync(
@@ -3697,7 +3697,7 @@ const { setupNim } = require(${onboardPath});
     const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
     const credentialsPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
     const platformPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "platform.js"));
 
     // Fake curl binary that returns a successful response — needed because
@@ -3949,7 +3949,7 @@ const { setupNim } = require(${onboardPath});
     const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
     const credentialsPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
     const platformPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "platform.js"));
 
     fs.mkdirSync(fakeBin, { recursive: true });
diff --git a/test/onboard.test.ts b/test/onboard.test.ts
index 589826e476..d9c4d2566d 100644
--- a/test/onboard.test.ts
+++ b/test/onboard.test.ts
@@ -2335,7 +2335,7 @@ startGateway(null).catch(() => {});
     const scriptPath = path.join(tmpDir, "setup-inference-check.js");
     const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
 
     fs.mkdirSync(fakeBin, { recursive: true });
     fs.writeFileSync(path.join(fakeBin, "openshell"), "#!/usr/bin/env bash\nexit 0\n", {
@@ -2413,7 +2413,7 @@ const { setupInference } = require(${onboardPath});
     const scriptPath = path.join(tmpDir, "setup-local-vllm-check.js");
     const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
     const credentialsPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
     const localInferencePath = JSON.stringify(
       path.join(repoRoot, "dist", "lib", "local-inference.js"),
@@ -2673,7 +2673,7 @@ console.log(JSON.stringify({
     const scriptPath = path.join(tmpDir, "setup-anthropic-check.js");
     const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
 
     fs.mkdirSync(fakeBin, { recursive: true });
     fs.writeFileSync(path.join(fakeBin, "openshell"), "#!/usr/bin/env bash\nexit 0\n", {
@@ -2749,7 +2749,7 @@ const { setupInference } = require(${onboardPath});
     const scriptPath = path.join(tmpDir, "setup-openai-update-check.js");
     const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
 
     fs.mkdirSync(fakeBin, { recursive: true });
     fs.writeFileSync(path.join(fakeBin, "openshell"), "#!/usr/bin/env bash\nexit 0\n", {
@@ -2822,7 +2822,7 @@ const { setupInference } = require(${onboardPath});
     const scriptPath = path.join(tmpDir, "setup-inference-auth-retry-check.js");
     const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
     const credentialsPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
 
     fs.mkdirSync(fakeBin, { recursive: true });
@@ -2912,7 +2912,7 @@ const { setupInference } = require(${onboardPath});
     const scriptPath = path.join(tmpDir, "setup-inference-apply-back-check.js");
     const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
     const credentialsPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
 
     fs.mkdirSync(fakeBin, { recursive: true });
@@ -3226,7 +3226,7 @@ const { setupInference } = require(${onboardPath});
     const scriptPath = path.join(tmpDir, "setup-resume-credential-check.js");
     const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
     // Pre-seed a pre-fix plaintext credentials.json. hydrateCredentialEnv
     // stages it non-destructively into process.env via
     // stageLegacyCredentialsToEnv(); the secure unlink only runs from the
@@ -3330,7 +3330,7 @@ const { setupInference } = require(${onboardPath});
     const fakeBin = path.join(tmpDir, "bin");
     const scriptPath = path.join(tmpDir, "stale-sandbox-check.js");
     const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
-    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
 
     fs.mkdirSync(fakeBin, { recursive: true });
@@ -3386,7 +3386,7 @@ console.log(JSON.stringify({ liveExists, sandbox: registry.getSandbox("my-assist
       const scriptPath = path.join(tmpDir, "create-sandbox-check.js");
       const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
       const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
       const preflightPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "preflight.js"));
       const credentialsPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
 
@@ -3526,7 +3526,7 @@ const { createSandbox } = require(${onboardPath});
     const scriptPath = path.join(tmpDir, "create-sandbox-remote-forward.js");
     const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
     const preflightPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "preflight.js"));
     const credentialsPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
 
@@ -3617,7 +3617,7 @@ const { createSandbox } = require(${onboardPath});
     const scriptPath = path.join(tmpDir, "dashboard-port-envargs.js");
     const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
     const preflightPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "preflight.js"));
     const credentialsPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
 
@@ -3749,7 +3749,7 @@ const { createSandbox } = require(${onboardPath});
       const scriptPath = path.join(tmpDir, "messaging-provider-check.js");
       const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
       const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
       const preflightPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "preflight.js"));
       const credentialsPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
 
@@ -3968,7 +3968,7 @@ const { createSandbox } = require(${onboardPath});
       const scriptPath = path.join(tmpDir, "messaging-reuse-provider.js");
       const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
       const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
       const preflightPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "preflight.js"));
       const credentialsPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
 
@@ -4131,7 +4131,7 @@ const { createSandbox } = require(${onboardPath});
     const scriptPath = path.join(tmpDir, "provider-upsert-fail.js");
     const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
     const preflightPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "preflight.js"));
     const credentialsPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
 
@@ -4211,7 +4211,7 @@ const { createSandbox } = require(${onboardPath});
       const scriptPath = path.join(tmpDir, "reuse-with-providers.js");
       const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
       const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
 
       fs.mkdirSync(fakeBin, { recursive: true });
       fs.writeFileSync(path.join(fakeBin, "openshell"), "#!/usr/bin/env bash\nexit 0\n", {
@@ -4316,7 +4316,7 @@ const { createSandbox } = require(${onboardPath});
       const scriptPath = path.join(tmpDir, "noninteractive-notready.js");
       const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
       const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
 
       fs.mkdirSync(fakeBin, { recursive: true });
       fs.writeFileSync(path.join(fakeBin, "openshell"), "#!/usr/bin/env bash\nexit 0\n", {
@@ -4395,7 +4395,7 @@ const { createSandbox } = require(${onboardPath});
       const scriptPath = path.join(tmpDir, "recreate-flag.js");
       const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
       const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
 
       fs.mkdirSync(fakeBin, { recursive: true });
       fs.writeFileSync(path.join(fakeBin, "openshell"), "#!/usr/bin/env bash\nexit 0\n", {
@@ -4498,7 +4498,7 @@ const { createSandbox } = require(${onboardPath});
       const scriptPath = path.join(tmpDir, "recreate-preserves.js");
       const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
       const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
       const sessionModulePath = JSON.stringify(
         path.join(repoRoot, "dist", "lib", "onboard-session.js"),
       );
@@ -4612,7 +4612,7 @@ const { createSandbox } = require(${onboardPath});
       const scriptPath = path.join(tmpDir, "interactive-reuse.js");
       const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
       const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
       const credentialsPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
 
       fs.mkdirSync(fakeBin, { recursive: true });
@@ -4743,7 +4743,7 @@ const { createSandbox } = require(${onboardPath});
       const scriptPath = path.join(tmpDir, "interactive-decline.js");
       const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
       const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
       const credentialsPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
 
       fs.mkdirSync(fakeBin, { recursive: true });
@@ -4885,7 +4885,7 @@ const { createSandbox } = require(${onboardPath});
       const scriptPath = path.join(tmpDir, "interactive-notready.js");
       const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
       const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
       const credentialsPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
 
       fs.mkdirSync(fakeBin, { recursive: true });
@@ -5372,7 +5372,7 @@ console.log(JSON.stringify({ exists: providerExistsInGateway("nonexistent") }));
       const payloadPath = path.join(tmpDir, "payload.json");
       const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
       const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
       const preflightPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "preflight.js"));
       const credentialsPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
 
@@ -5497,7 +5497,7 @@ const { createSandbox } = require(${onboardPath});
     const scriptPath = path.join(tmpDir, "reuse-sandbox-forward.js");
     const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
 
     fs.mkdirSync(fakeBin, { recursive: true });
     fs.writeFileSync(path.join(fakeBin, "openshell"), "#!/usr/bin/env bash\nexit 0\n", {
@@ -5623,7 +5623,7 @@ const { createSandbox } = require(${onboardPath});
     const scriptPath = path.join(tmpDir, "inference-get-check.js");
     const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
 
     fs.mkdirSync(fakeBin, { recursive: true });
     fs.writeFileSync(path.join(fakeBin, "openshell"), "#!/usr/bin/env bash\nexit 0\n", {
@@ -5695,7 +5695,7 @@ const { setupInference } = require(${onboardPath});
     const scriptPath = path.join(tmpDir, "inference-route-check.js");
     const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
 
     fs.mkdirSync(fakeBin, { recursive: true });
     fs.writeFileSync(path.join(fakeBin, "openshell"), "#!/usr/bin/env bash\nexit 0\n", {
@@ -5771,7 +5771,7 @@ const { setupInference } = require(${onboardPath});
       const scriptPath = path.join(tmpDir, "enabled-channels-filter.js");
       const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
       const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
       const preflightPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "preflight.js"));
       const credentialsPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
 
@@ -5905,7 +5905,7 @@ const { createSandbox } = require(${onboardPath});
       const scriptPath = path.join(tmpDir, "enabled-channels-empty.js");
       const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
       const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+      const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
       const preflightPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "preflight.js"));
       const credentialsPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
 
@@ -6471,7 +6471,7 @@ const { setupMessagingChannels, MESSAGING_CHANNELS } = require(${onboardPath});
     const scriptPath = path.join(tmpDir, "create-sandbox-from.js");
     const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
     const preflightPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "preflight.js"));
     const credentialsPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
 
@@ -6651,7 +6651,7 @@ const { createSandbox } = require(${onboardPath});
     const scriptPath = path.join(tmpDir, "create-sandbox-missing.js");
     const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
     const preflightPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "preflight.js"));
     const credentialsPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
 
@@ -6712,7 +6712,7 @@ const { createSandbox } = require(${onboardPath});
     const scriptPath = path.join(tmpDir, "create-sandbox-dir.js");
     const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
     const preflightPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "preflight.js"));
     const credentialsPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
 
@@ -6772,7 +6772,7 @@ const { createSandbox } = require(${onboardPath});
     const scriptPath = path.join(tmpDir, "create-sandbox-ignored.js");
     const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
     const preflightPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "preflight.js"));
     const credentialsPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
     const ignoredDir = path.join(tmpDir, "node_modules", "pkg");
@@ -6835,7 +6835,7 @@ const { createSandbox } = require(${onboardPath});
     const scriptPath = path.join(tmpDir, "create-sandbox-cleanup.js");
     const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
     const preflightPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "preflight.js"));
     const credentialsPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
     const customBuildDir = path.join(tmpDir, "custom-image");
diff --git a/test/policies.test.ts b/test/policies.test.ts
index cc51241e84..e3f3797d1b 100644
--- a/test/policies.test.ts
+++ b/test/policies.test.ts
@@ -19,7 +19,7 @@ const REPO_ROOT = path.join(import.meta.dirname, "..");
 const CLI_PATH = JSON.stringify(path.join(REPO_ROOT, "dist", "nemoclaw.js"));
 const CREDENTIALS_PATH = JSON.stringify(path.join(REPO_ROOT, "dist", "lib", "credentials.js"));
 const POLICIES_PATH = JSON.stringify(path.join(REPO_ROOT, "dist", "lib", "policies.js"));
-const REGISTRY_PATH = JSON.stringify(path.join(REPO_ROOT, "dist", "lib", "registry.js"));
+const REGISTRY_PATH = JSON.stringify(path.join(REPO_ROOT, "dist", "lib", "state", "registry.js"));
 const SELECT_FROM_LIST_ITEMS = [
   { name: "npm", description: "npm and Yarn registry access" },
   { name: "pypi", description: "Python Package Index (PyPI) access" },
@@ -1502,7 +1502,7 @@ Promise.resolve(require(${CLI_PATH}).mainPromise).finally(() => {
       const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-policy-external-"));
       const scriptPath = path.join(tmpDir, "policy-add-external.js");
       const script = String.raw`
-const registry = require(${POLICIES_PATH.replace("policies.js", "registry.js")});
+const registry = require(${REGISTRY_PATH});
 const policies = require(${POLICIES_PATH});
 const credentials = require(${CREDENTIALS_PATH});
 const calls = [];
diff --git a/test/policy-tiers-onboard.test.ts b/test/policy-tiers-onboard.test.ts
index 445db85c15..46fad5cd78 100644
--- a/test/policy-tiers-onboard.test.ts
+++ b/test/policy-tiers-onboard.test.ts
@@ -51,7 +51,7 @@ function buildPreamble({
 } = {}): string {
   const credPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
   const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-  const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+  const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
   const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
   const resolveOpenshellPath = JSON.stringify(
     path.join(repoRoot, "dist", "lib", "adapters", "openshell", "resolve.js"),
@@ -380,7 +380,7 @@ describe("selectTierPresetsAndAccess", () => {
   function buildPresetsScript(body: string): string {
     const credPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "credentials.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "runner.js"));
-    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "registry.js"));
+    const registryPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "state", "registry.js"));
     const onboardPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard.js"));
     return String.raw`
 const credentials = require(${credPath});
diff --git a/test/rebuild-policy-presets.test.ts b/test/rebuild-policy-presets.test.ts
index 0c8d49f056..9e363fd378 100644
--- a/test/rebuild-policy-presets.test.ts
+++ b/test/rebuild-policy-presets.test.ts
@@ -29,7 +29,7 @@ type ManifestWithOptionalPresets = {
 };
 
 // Import compiled modules from dist/
-const sandboxState = await import(path.join(REPO_ROOT, "dist", "lib", "sandbox-state.js"));
+const sandboxState = await import(path.join(REPO_ROOT, "dist", "lib", "state", "sandbox.js"));
 
 describe("rebuild policy preset restoration (#1952)", () => {
   describe("RebuildManifest policyPresets field", () => {
diff --git a/test/registry.test.ts b/test/registry.test.ts
index 3f9e9fc9fb..f641274bf7 100644
--- a/test/registry.test.ts
+++ b/test/registry.test.ts
@@ -14,7 +14,7 @@ const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-test-"));
 process.env.HOME = tmpDir;
 
 const require = createRequire(import.meta.url);
-const registry = require("../dist/lib/registry");
+const registry = require("../dist/lib/state/registry");
 
 const regFile = path.join(tmpDir, ".nemoclaw", "sandboxes.json");
 
@@ -402,7 +402,7 @@ describe("advisory file locking", () => {
   it("concurrent writers do not corrupt the registry", () => {
     const { spawnSync } = require("child_process");
     const registryPath = path.resolve(
-      path.join(import.meta.dirname, "..", "dist", "lib", "registry.js"),
+      path.join(import.meta.dirname, "..", "dist", "lib", "state", "registry.js"),
     );
     const homeDir = path.dirname(path.dirname(regFile));
     // Script that spawns 4 workers in parallel, each writing 5 sandboxes
diff --git a/test/repro-2010.test.ts b/test/repro-2010.test.ts
index 572c05cc2f..4f4d976f94 100644
--- a/test/repro-2010.test.ts
+++ b/test/repro-2010.test.ts
@@ -20,7 +20,7 @@ const REPO_ROOT = path.join(import.meta.dirname, "..");
 const POLICIES_PATH = path.join(REPO_ROOT, "dist", "lib", "policies.js");
 const RUNNER_PATH = path.join(REPO_ROOT, "dist", "lib", "runner.js");
 const CLI_PATH = path.join(REPO_ROOT, "bin", "nemoclaw.js");
-const REGISTRY_PATH = path.join(REPO_ROOT, "dist", "lib", "registry.js");
+const REGISTRY_PATH = path.join(REPO_ROOT, "dist", "lib", "state", "registry.js");
 
 /**
  * Run a CJS script in a subprocess and return stdout.
diff --git a/test/security-sandbox-tar-traversal.test.ts b/test/security-sandbox-tar-traversal.test.ts
index e3a99140df..7d3586aef4 100644
--- a/test/security-sandbox-tar-traversal.test.ts
+++ b/test/security-sandbox-tar-traversal.test.ts
@@ -115,13 +115,13 @@ function buildTar(
  * Import the actual validation/extraction functions from the source.
  */
 type SandboxStateModule = Pick<
-  typeof import("../dist/lib/sandbox-state.js"),
+  typeof import("../dist/lib/state/sandbox.js"),
   "validateTarEntries" | "safeTarExtract" | "rejectHardLinks"
 >;
 
 function isSandboxStateModule(
   value: object | null,
-): value is typeof import("../dist/lib/sandbox-state.js") {
+): value is typeof import("../dist/lib/state/sandbox.js") {
   return (
     value !== null &&
     typeof Reflect.get(value, "validateTarEntries") === "function" &&
@@ -133,7 +133,7 @@ function isSandboxStateModule(
 async function loadSandboxState(): Promise<SandboxStateModule> {
   // The CLI compiles to dist/lib/ — import from there
   const loaded = await import(
-    path.join(import.meta.dirname, "..", "dist", "lib", "sandbox-state.js")
+    path.join(import.meta.dirname, "..", "dist", "lib", "state", "sandbox.js")
   );
   const mod = typeof loaded === "object" && loaded !== null ? loaded : null;
   if (!isSandboxStateModule(mod)) {
@@ -533,7 +533,7 @@ describe("Fix: rejectHardLinks blocks hard-link entries at validation time", ()
 describe("Regression: sandbox-state.ts uses validated tar extraction", () => {
   function getSourceCode(): string {
     return fs.readFileSync(
-      path.join(import.meta.dirname, "..", "src", "lib", "sandbox-state.ts"),
+      path.join(import.meta.dirname, "..", "src", "lib", "state", "sandbox.ts"),
       "utf-8",
     );
   }
diff --git a/test/shellquote-sandbox.test.ts b/test/shellquote-sandbox.test.ts
index 525f0adc94..e230198b01 100644
--- a/test/shellquote-sandbox.test.ts
+++ b/test/shellquote-sandbox.test.ts
@@ -39,7 +39,7 @@ describe("sandboxName command hardening in onboard.js", () => {
       pathToFileURL(path.join(repoRoot, "dist", "lib", "runner.js")).href,
     );
     const registryUrl = JSON.stringify(
-      pathToFileURL(path.join(repoRoot, "dist", "lib", "registry.js")).href,
+      pathToFileURL(path.join(repoRoot, "dist", "lib", "state", "registry.js")).href,
     );
     const preflightUrl = JSON.stringify(
       pathToFileURL(path.join(repoRoot, "dist", "lib", "preflight.js")).href,
diff --git a/test/shields.test.ts b/test/shields.test.ts
index 36b982cec1..7c07b265cc 100644
--- a/test/shields.test.ts
+++ b/test/shields.test.ts
@@ -282,7 +282,7 @@ describe("shields — unit logic", () => {
 describe("NC-2227-04: sandbox-state.ts tar commands do not follow symlinks", () => {
   function getSourceCode(): string {
     return fs.readFileSync(
-      path.join(import.meta.dirname, "..", "src", "lib", "sandbox-state.ts"),
+      path.join(import.meta.dirname, "..", "src", "lib", "state", "sandbox.ts"),
       "utf-8",
     );
   }
diff --git a/test/snapshot.test.ts b/test/snapshot.test.ts
index a2a507598a..f98b051412 100644
--- a/test/snapshot.test.ts
+++ b/test/snapshot.test.ts
@@ -25,7 +25,7 @@ const REPO_ROOT = path.join(import.meta.dirname, "..");
 type BackupScalar = string | number | boolean | null | undefined;
 type BackupValue = BackupScalar | BackupManifestOverrides | BackupValue[];
 
-type SandboxStateModule = typeof import("../dist/lib/sandbox-state.js");
+type SandboxStateModule = typeof import("../dist/lib/state/sandbox.js");
 type SandboxStateModuleCandidate = Partial<SandboxStateModule> | null;
 
 function isSandboxStateModule(value: SandboxStateModuleCandidate): value is SandboxStateModule {
@@ -39,7 +39,7 @@ function isSandboxStateModule(value: SandboxStateModuleCandidate): value is Sand
 }
 
 const loadedSandboxState = await import(
-  pathToFileURL(path.join(REPO_ROOT, "dist", "lib", "sandbox-state.js")).href
+  pathToFileURL(path.join(REPO_ROOT, "dist", "lib", "state", "sandbox.js")).href
 );
 if (!isSandboxStateModule(loadedSandboxState)) {
   throw new Error("Expected sandbox-state module exports to be available");