@mcoda/mswarm 0.1.133 → 0.1.135-codali.2

package/dist/vendor/codali/tools/shell/IsolatedExecutor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IsolatedExecutor.d.ts","sourceRoot":"","sources":["../../../src/tools/shell/IsolatedExecutor.ts"],"names":[],"mappings":"AAMA,OAAO,EAAsB,KAAK,WAAW,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC/F,OAAO,EAA6C,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjG,MAAM,WAAW,cAAc;IAAG,SAAS,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,YAAY,GAAG,cAAc,GAAG,aAAa,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAAE;AAEhI,mFAAmF;AACnF,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,EAAE,SAAS,MAAM,EAAE,YAAY,MAAM,EAAE,EAAE,UAAU,WAAW,EAAE,EAAE,iBAAe,KAAG,MAyBpI,CAAC;AAQF,eAAO,MAAM,cAAc,QAAO,cAcjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,UAAS;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,cAAc,CAAA;CAAO,KAAG,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAkD3L,CAAC"}

package/dist/vendor/codali/tools/shell/IsolatedExecutor.js

@@ -0,0 +1,134 @@
+import { existsSync, realpathSync, mkdtempSync, rmSync, promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { runProcess } from "./AsyncProcess.js";
+import { resolveShellWorkingDirectory } from "./ShellWorkingDirectory.js";
+import { ToolExecutionError } from "../ToolTypes.js";
+import { discoverHostToolchain, extraRuntimeMounts } from "./HostToolchain.js";
+/** All paths have been canonicalized by the host, before launching the sandbox. */
+export const darwinSandboxProfile = (root, scratch, writePaths, runtimes, network = false) => {
+    const quoted = (value) => JSON.stringify(value);
+    const ancestors = new Set();
+    for (const target of [root, scratch, ...extraRuntimeMounts(runtimes).map(runtime => runtime.readOnlyRoot)]) {
+        for (let parent = path.dirname(target); parent !== path.dirname(parent); parent = path.dirname(parent))
+            ancestors.add(parent);
+    }
+    return [
+        "(version 1)", "(deny default)", "(allow process*)", "(allow sysctl-read)",
+        // dyld opens the root directory when locating its shared cache. This literal
+        // permits the directory itself, never a recursive read of the filesystem.
+        '(allow file-read* (literal "/"))',
+        // realpath/lstat needs ancestor metadata, not directory contents or sibling files.
+        ...[...ancestors].map(parent => `(allow file-read-metadata (literal ${quoted(parent)}))`),
+        '(allow file-read* (subpath "/usr") (subpath "/bin") (subpath "/sbin") (subpath "/System") (subpath "/Library") (subpath "/private/etc") (subpath "/dev"))',
+        // Apple's /bin/sh reads this system selector before starting npm scripts.
+        // Permit only that selector, not other private /var files or directories.
+        '(allow file-read* (literal "/private/var/select/sh") (literal "/var/select/sh"))',
+        '(allow file-read-metadata (literal "/private/var/select") (literal "/var/select"))',
+        `(allow file-read* (subpath ${quoted(root)}))`,
+        ...extraRuntimeMounts(runtimes).map(runtime => `(allow file-read* (${runtime.directory ? "subpath" : "literal"} ${quoted(runtime.readOnlyRoot)}))`),
+        `(allow file-read* file-write* (subpath ${quoted(scratch)}))`,
+        ...writePaths.map(file => `(allow file-write* (subpath ${quoted(file)}))`),
+        ...[".git", ".mcoda"].map(dir => `(deny file-write* (subpath ${quoted(path.join(root, dir))}))`),
+        network ? "(allow network*)" : "(deny network*)",
+    ].join("\n");
+};
+const bubblewrapRoot = () => {
+    const args = ["--die-with-parent", "--new-session", "--unshare-all", "--ro-bind", "/usr", "/usr", "--dev", "/dev", "--proc", "/proc", "--tmpfs", "/tmp"];
+    for (const dir of ["/bin", "/sbin", "/lib", "/lib64"])
+        if (existsSync(dir))
+            args.push("--ro-bind", realpathSync(dir), dir);
+    return args;
+};
+export const executorStatus = () => {
+    if (process.platform === "linux") {
+        if (!existsSync("/usr/bin/bwrap"))
+            return { available: false, backend: "unavailable", reason: "Install bubblewrap to enable isolated shell execution" };
+        const probe = spawnSync("/usr/bin/bwrap", [...bubblewrapRoot(), "--", "/usr/bin/true"], { timeout: 3000, stdio: "ignore" });
+        return probe.status === 0 ? { available: true, backend: "bubblewrap" } : { available: false, backend: "unavailable", reason: "bubblewrap user namespaces are unavailable" };
+    }
+    if (process.platform === "darwin" && existsSync("/usr/bin/sandbox-exec")) {
+        const scratch = realpathSync(mkdtempSync(path.join(os.tmpdir(), "codali-isolation-probe-")));
+        try {
+            const probe = spawnSync("/usr/bin/sandbox-exec", ["-p", darwinSandboxProfile(scratch, scratch, [], []), "/usr/bin/true"], { timeout: 3000, stdio: "ignore" });
+            if (probe.status === 0)
+                return { available: true, backend: "sandbox-exec" };
+        }
+        finally {
+            rmSync(scratch, { recursive: true, force: true });
+        }
+    }
+    return { available: false, backend: "unavailable", reason: "No supported isolation backend on this platform" };
+};
+export const createIsolatedExecutor = (options = {}) => {
+    const status = options.status ?? executorStatus();
+    return async (command, args, context) => {
+        if (!status.available)
+            throw new ToolExecutionError("tool_permission_denied", status.reason ?? "Isolation unavailable");
+        const root = realpathSync(context.workspaceRoot);
+        const cwd = resolveShellWorkingDirectory(root, context.shellWorkingDirectory);
+        if (root === path.parse(root).root)
+            throw new ToolExecutionError("tool_permission_denied", "Filesystem root cannot be an isolated workspace");
+        const runtimes = discoverHostToolchain(root);
+        const writePaths = (context.allowedWritePaths ?? ["."]).map(file => {
+            const requested = path.resolve(root, file);
+            if (requested !== root && !requested.startsWith(`${root}${path.sep}`))
+                throw new ToolExecutionError("tool_permission_denied", "Shell write scope escapes workspace");
+            if (!existsSync(requested))
+                throw new ToolExecutionError("tool_permission_denied", "Create the scoped directory/file with write_file before shell execution");
+            const real = realpathSync(requested);
+            if (real !== root && !real.startsWith(`${root}${path.sep}`))
+                throw new ToolExecutionError("tool_permission_denied", "Shell write scope resolves outside workspace");
+            if ([".git", ".mcoda"].some(dir => real === path.join(root, dir) || real.startsWith(`${root}/${dir}/`)))
+                throw new ToolExecutionError("tool_permission_denied", "Repository control metadata cannot be a write scope");
+            return real;
+        });
+        if (status.backend === "bubblewrap") {
+            const launch = bubblewrapRoot();
+            if (options.network) {
+                launch.push("--share-net");
+                for (const file of ["/etc/resolv.conf", "/etc/hosts", "/etc/nsswitch.conf", "/etc/ssl/certs"])
+                    if (existsSync(file))
+                        launch.push("--ro-bind", realpathSync(file), file);
+            }
+            launch.push("--dir", path.dirname(root), "--ro-bind", root, root);
+            for (const runtime of extraRuntimeMounts(runtimes))
+                launch.push("--dir", path.dirname(runtime.readOnlyRoot), "--ro-bind", runtime.readOnlyRoot, runtime.readOnlyRoot);
+            launch.push("--dir", "/tmp/codali-bin");
+            for (const runtime of runtimes)
+                launch.push("--symlink", runtime.executable, `/tmp/codali-bin/${runtime.name}`);
+            for (const file of writePaths)
+                launch.push("--bind", file, file);
+            launch.push("--chdir", cwd, "--dir", "/tmp/home", "--setenv", "HOME", "/tmp/home", "--setenv", "TMPDIR", "/tmp", "--setenv", "PATH", "/tmp/codali-bin:/usr/local/bin:/usr/bin:/bin");
+            for (const [key, value] of Object.entries({ CARGO_HOME: "/tmp/home/cargo", XDG_CACHE_HOME: "/tmp/home/cache", PYTHONPYCACHEPREFIX: "/tmp/home/pycache", PYTHONUSERBASE: "/tmp/home/python" }))
+                launch.push("--setenv", key, value);
+            // Git hooks/config and private session state are not part of executable workspace access.
+            for (const dir of [".git", ".mcoda"])
+                if (existsSync(path.join(root, dir)))
+                    launch.push("--ro-bind", path.join(root, dir), path.join(root, dir));
+            launch.push("--", command, ...args);
+            return runProcess("/usr/bin/bwrap", launch, context);
+        }
+        const scratch = realpathSync(await fs.mkdtemp(path.join(os.tmpdir(), "codali-shell-")));
+        try {
+            await fs.chmod(scratch, 0o700);
+            const privateHome = path.join(scratch, "home");
+            const privateBin = path.join(scratch, "bin");
+            await fs.mkdir(privateHome, { mode: 0o700 });
+            await fs.mkdir(privateBin, { mode: 0o700 });
+            for (const runtime of runtimes)
+                await fs.symlink(runtime.executable, path.join(privateBin, runtime.name));
+            const profile = darwinSandboxProfile(root, scratch, writePaths, runtimes, options.network);
+            return await runProcess("/usr/bin/sandbox-exec", ["-p", profile, runtimes.find(runtime => runtime.name === command)?.executable ?? command, ...args], context, {
+                ...runtimes.find(runtime => runtime.name === "cc")?.environment,
+                HOME: privateHome, TMPDIR: scratch, PATH: `${privateBin}:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`,
+                CARGO_HOME: path.join(privateHome, "cargo"), XDG_CACHE_HOME: path.join(privateHome, "cache"),
+                PYTHONPYCACHEPREFIX: path.join(privateHome, "pycache"), PYTHONUSERBASE: path.join(privateHome, "python"),
+            });
+        }
+        finally {
+            await fs.rm(scratch, { recursive: true, force: true });
+        }
+    };
+};

package/dist/vendor/codali/tools/shell/ShellTool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShellTool.d.ts","sourceRoot":"","sources":["../../../src/tools/shell/ShellTool.ts"],"names":[],"mappings":"AAEA,OAAO,EAAwC,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AA2C5F,eAAO,MAAM,eAAe,QAAO,cA2EjC,CAAC"}
+{"version":3,"file":"ShellTool.d.ts","sourceRoot":"","sources":["../../../src/tools/shell/ShellTool.ts"],"names":[],"mappings":"AACA,OAAO,EAAwC,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AA6C5F,eAAO,MAAM,eAAe,QAAO,cAmDjC,CAAC"}

package/dist/vendor/codali/tools/shell/ShellTool.js

@@ -1,6 +1,7 @@
-import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { ToolExecutionError } from "../ToolTypes.js";
+import { runProcess } from "./AsyncProcess.js";
+import { resolveShellWorkingDirectory } from "./ShellWorkingDirectory.js";
 const resolveAllowlist = (context) => {
     return context.shellAllowlist ?? [];
 };
@@ -40,15 +41,17 @@ const isDestructiveShellAction = (command, args) => {
 };
 export const createShellTool = () => ({
     name: "run_shell",
-    description: "Run a shell command from the workspace root (allowlist only).",
+    description: 'Run an allowlisted executable. Default cwd is the workspace root; set cwd for a module-local command, e.g. {"command":"npm","args":["test"],"cwd":"packages/app"}. In terminal mode the workspace is read-only unless writePaths names root-relative paths inside the claimed task. Existing source files in those paths require current reads and structural analysis.',
     readOnly: false,
     capability: "shell",
     inputSchema: {
         type: "object",
         required: ["command"],
         properties: {
-            command: { type: "string" },
+            command: { type: "string", description: "One executable name, without arguments or shell syntax." },
             args: { type: "array", items: { type: "string" } },
+            cwd: { type: "string", description: "Existing working directory inside the workspace, relative to its root. Default: workspace root. Does not change the base of writePaths." },
+            writePaths: { type: "array", items: { type: "string" }, description: "Terminal mode: root-relative existing files/directories to make writable, regardless of cwd. Default: no workspace writes. Must fit the claimed task scope." },
         },
     },
     handler: async (args, context) => {
@@ -57,7 +60,7 @@ export const createShellTool = () => ({
                 retryable: false,
             });
         }
-        const { command, args: commandArgs = [] } = args;
+        const { command, args: commandArgs = [], cwd } = args;
         if (!context.allowDestructiveOperations
             && isDestructiveShellAction(command, commandArgs)) {
             throw new ToolExecutionError("tool_permission_denied", "Destructive operation blocked by policy", {
@@ -77,30 +80,7 @@ export const createShellTool = () => ({
                 details: { command },
             });
         }
-        const result = spawnSync(command, commandArgs, {
-            cwd: context.workspaceRoot,
-            encoding: "utf8",
-        });
-        if (result.error) {
-            throw result.error;
-        }
-        const stdout = result.stdout ?? "";
-        const stderr = result.stderr ?? "";
-        const exitCode = result.status ?? 0;
-        if (exitCode !== 0) {
-            const message = stderr || stdout || `Command failed with exit code ${exitCode}`;
-            throw new ToolExecutionError("tool_execution_failed", message, {
-                retryable: false,
-                details: { command, exitCode },
-            });
-        }
-        return {
-            output: stdout || stderr,
-            data: {
-                stdout,
-                stderr,
-                exitCode,
-            },
-        };
+        const shellWorkingDirectory = resolveShellWorkingDirectory(context.workspaceRoot, cwd);
+        return (context.shellExecutor ?? runProcess)(command, commandArgs, { ...context, shellWorkingDirectory });
     },
 });

package/dist/vendor/codali/tools/shell/ShellWorkingDirectory.d.ts

@@ -0,0 +1,3 @@
+/** Resolve only the process directory; write scopes still use workspaceRoot. */
+export declare const resolveShellWorkingDirectory: (workspaceRoot: string, requested?: string) => string;
+//# sourceMappingURL=ShellWorkingDirectory.d.ts.map

package/dist/vendor/codali/tools/shell/ShellWorkingDirectory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShellWorkingDirectory.d.ts","sourceRoot":"","sources":["../../../src/tools/shell/ShellWorkingDirectory.ts"],"names":[],"mappings":"AAIA,gFAAgF;AAChF,eAAO,MAAM,4BAA4B,GAAI,eAAe,MAAM,EAAE,YAAY,MAAM,KAAG,MAoBxF,CAAC"}

package/dist/vendor/codali/tools/shell/ShellWorkingDirectory.js

@@ -0,0 +1,30 @@
+import { realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { ToolExecutionError } from "../ToolTypes.js";
+/** Resolve only the process directory; write scopes still use workspaceRoot. */
+export const resolveShellWorkingDirectory = (workspaceRoot, requested) => {
+    if (requested !== undefined && (typeof requested !== "string" || !requested.trim())) {
+        throw new ToolExecutionError("tool_invalid_args", "cwd must be a non-empty directory path inside the workspace");
+    }
+    const root = realpathSync.native(workspaceRoot);
+    const inside = (candidate) => {
+        const relative = path.relative(root, candidate);
+        return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+    };
+    const candidate = path.resolve(root, requested ?? ".");
+    if (!inside(candidate))
+        throw new ToolExecutionError("tool_permission_denied", "Shell cwd escapes the workspace");
+    try {
+        const resolved = realpathSync.native(candidate);
+        if (!inside(resolved))
+            throw new ToolExecutionError("tool_permission_denied", "Shell cwd resolves outside the workspace");
+        if (!statSync(resolved).isDirectory())
+            throw new ToolExecutionError("tool_invalid_args", "Shell cwd must be an existing directory");
+        return resolved;
+    }
+    catch (error) {
+        if (error instanceof ToolExecutionError)
+            throw error;
+        throw new ToolExecutionError("tool_invalid_args", "Shell cwd is not an accessible existing directory");
+    }
+};

package/package.json

@@ -1,13 +1,21 @@
 {
-  "name": "@mcoda/mswarm",
-  "version": "0.1.133",
-  "description": "Owner-run mswarm node for exposing local mcoda agents through the mswarm self-hosted gateway.",
-  "type": "module",
-  "main": "dist/server.js",
-  "types": "dist/server.d.ts",
+  "author": "bekir dag",
   "bin": {
-    "mswarm-self-hosted-node": "dist/server.js",
-    "mswarm": "dist/server.js"
+    "mswarm": "dist/server.js",
+    "mswarm-self-hosted-node": "dist/server.js"
+  },
+  "bugs": {
+    "url": "https://github.com/bekirdag/mcoda/issues"
+  },
+  "dependencies": {
+    "@mcoda/db": "0.1.135-codali.2",
+    "@mcoda/shared": "0.1.135-codali.2",
+    "fastify": "^5.7.4",
+    "undici": "^6.28.0"
+  },
+  "description": "Owner-run mswarm node for exposing local mcoda agents through the mswarm self-hosted gateway.",
+  "engines": {
+    "node": ">=20"
   },
   "files": [
     "dist",
@@ -16,23 +24,11 @@
     "scripts",
     "!scripts/**/__pycache__/**",
     "!scripts/**/*.pyc",
+    "!scripts/**/*.test.mjs",
     "README.md",
     "LICENSE"
   ],
-  "engines": {
-    "node": ">=20"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/bekirdag/mcoda.git",
-    "directory": "packages/mswarm"
-  },
-  "bugs": {
-    "url": "https://github.com/bekirdag/mcoda/issues"
-  },
   "homepage": "https://github.com/bekirdag/mcoda/tree/main/packages/mswarm#readme",
-  "license": "MIT",
-  "author": "bekir dag",
   "keywords": [
     "mcoda",
     "mswarm",
@@ -42,18 +38,24 @@
     "agents",
     "ollama"
   ],
+  "license": "MIT",
+  "main": "dist/server.js",
+  "name": "@mcoda/mswarm",
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "fastify": "^5.7.4",
-    "undici": "^6.28.0",
-    "@mcoda/db": "0.1.133",
-    "@mcoda/shared": "0.1.133"
+  "repository": {
+    "directory": "packages/mswarm",
+    "type": "git",
+    "url": "git+https://github.com/bekirdag/mcoda.git"
   },
   "scripts": {
     "build": "pnpm --filter @mcoda/shared run build && pnpm --filter @mcoda/codali run build && tsc -p tsconfig.json && node ../../scripts/copy-mswarm-codali-vendor.js",
     "lint": "echo \"lint not configured\"",
-    "test": "pnpm run build && node ../../scripts/run-node-tests.js dist"
-  }
-}
+    "test": "pnpm run build && node ../../scripts/run-node-tests.js dist && pnpm run test:backend-drain",
+    "test:backend-drain": "node --experimental-websocket --test scripts/backend-http-drain.test.mjs"
+  },
+  "type": "module",
+  "types": "dist/server.d.ts",
+  "version": "0.1.135-codali.2"
+}

package/scripts/backend-http-drain.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/**
+ * Operator bootstrap for legacy HTTP services without a shutdown handler.
+ * Run inside the target container against its loopback Node inspector only.
+ * This is not a public administration endpoint. Qualification must pin the
+ * runtime/image and prove both request completion and durable-job quiescence.
+ */
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+
+// Self-contained because the inspector evaluates this function in the target.
+export function controlHttpAdmission({ action, role, port, nonce, expectedPid }) {
+  if (!['gateway', 'proxy'].includes(role) || !Number.isInteger(port) || port < 1 || port > 65535 ||
+      !/^[a-zA-Z0-9-]{16,100}$/.test(nonce) || expectedPid !== process.pid ||
+      !['inspect', 'barrier', 'status', 'close', 'restore'].includes(action)) {
+    throw new Error('Invalid or mismatched deployment target');
+  }
+  const key = Symbol.for('mcoda.backend.http-drain.v1');
+  let state = globalThis[key];
+  if (state?.phase === 'restored' && action === 'barrier') {
+    delete globalThis[key];
+    state = undefined;
+  }
+  const snapshot = () => ({
+    nonce: state.nonce, role: state.role, port: state.port, pid: process.pid,
+    phase: state.phase, blockedRequests: state.blockedRequests,
+    controlRequests: state.controlRequests, installedAt: state.installedAt,
+    closedAt: state.closedAt, closeError: state.closeError,
+    listening: state.server.listening,
+  });
+  if (state && (state.nonce !== nonce || state.port !== port || state.role !== role)) {
+    throw new Error('Another deployment owns this process');
+  }
+  if (!state) {
+    if (!['inspect', 'barrier'].includes(action)) throw new Error('No admission barrier is installed');
+    // Legacy bootstrap only: the inspected runtime's HTTP handle shape must be
+    // qualified before deployment. Fail closed on additional/bypassing handlers.
+    const servers = process._getActiveHandles().filter((handle) =>
+      handle?.constructor?.name === 'Server' && typeof handle.address === 'function' &&
+      handle.address()?.port === port && typeof handle.closeIdleConnections === 'function');
+    if (servers.length !== 1) throw new Error('Expected exactly one qualified HTTP server');
+    const server = servers[0];
+    const listeners = server.listeners('request');
+    if (action === 'inspect') return { nonce, role, port, pid: process.pid, phase: 'unmodified',
+      runtimeVersion: process.version, listening: server.listening, requestListeners: listeners.length,
+      alternateListeners: Object.fromEntries(['checkContinue', 'checkExpectation', 'upgrade'].map((name) => [name, server.listenerCount(name)])) };
+    if (listeners.length !== 1 || ['checkContinue', 'checkExpectation', 'upgrade'].some((name) => server.listenerCount(name))) {
+      throw new Error('Unsupported HTTP request dispatch; no listener changed');
+    }
+    state = { nonce, role, port, server, listeners, address: server.address(),
+      phase: 'barrier', installedAt: Date.now(), blockedRequests: 0, controlRequests: 0 };
+    const controlPath = /^\/v1\/swarm\/self-hosted\/node\/(?:heartbeat|load|models|jobs\/poll|jobs\/[A-Za-z0-9_-]+\/(?:start|events|result))$/;
+    state.listener = function (request, response) {
+      const pathname = (request.url ?? '').split('?')[0];
+      const health = request.method === 'GET' && pathname === '/healthz';
+      if (health || (state.role === 'gateway' && request.method === 'POST' && controlPath.test(pathname))) {
+        state.controlRequests++;
+        for (const listener of state.listeners) listener.call(this, request, response);
+        return;
+      }
+      state.blockedRequests++;
+      response.shouldKeepAlive = false;
+      response.writeHead(503, { 'content-type': 'application/json', 'retry-after': '15', connection: 'close' });
+      response.end(JSON.stringify({ error: { code: 'deployment_draining', message: 'Service deployment is draining; retry shortly.' } }));
+      request.resume();
+    };
+    globalThis[key] = state;
+    server.removeListener('request', listeners[0]);
+    server.on('request', state.listener);
+  }
+  if (action === 'inspect' || action === 'barrier' || action === 'status') return snapshot();
+  if (action === 'close') {
+    if (state.phase === 'barrier') {
+      state.phase = 'closing';
+      // Never close active connections. The callback proves every HTTP request
+      // has finished; the operator separately checks durable queue records.
+      state.server.close((error) => {
+        clearInterval(state.idleReaper);
+        state.closeError = error ? String(error.message) : undefined;
+        state.phase = error ? 'close_failed' : 'closed';
+        state.closedAt = Date.now();
+      });
+      state.server.closeIdleConnections();
+      // A response accepted before the barrier can become idle after close()
+      // starts. Reap only idle sockets as those responses finish.
+      state.idleReaper = setInterval(() => state.server.closeIdleConnections(), 100);
+      state.idleReaper.unref();
+    }
+    return snapshot();
+  }
+  if (state.phase === 'closing' || state.phase === 'close_failed') throw new Error('HTTP close has not completed');
+  if (state.phase === 'closed') {
+    state.phase = 'restoring';
+    state.server.listen({ port: state.port, host: state.address.address }, () => {
+      state.server.removeListener('request', state.listener);
+      for (const listener of state.listeners) state.server.on('request', listener);
+      state.phase = 'restored';
+    });
+  } else if (state.phase === 'barrier') {
+    state.server.removeListener('request', state.listener);
+    for (const listener of state.listeners) state.server.on('request', listener);
+    state.phase = 'restored';
+  }
+  return snapshot();
+}
+
+export async function inspectorControl(options) {
+  const inspectorPort = options.inspectorPort ?? 9229;
+  if (!Number.isInteger(inspectorPort) || inspectorPort < 1 || inspectorPort > 65535) throw new Error('Invalid inspector port');
+  if (typeof WebSocket !== 'function') throw new Error('Use Node20 with --experimental-websocket, or Node22');
+  const response = await fetch(`http://127.0.0.1:${inspectorPort}/json/list`, { signal: AbortSignal.timeout(5000), redirect: 'error' });
+  if (!response.ok) throw new Error(`Inspector discovery failed: ${response.status}`);
+  const targets = await response.json();
+  if (!Array.isArray(targets) || targets.length !== 1) throw new Error('Inspector target is ambiguous');
+  const endpoint = new URL(targets[0].webSocketDebuggerUrl);
+  if (endpoint.protocol !== 'ws:' || endpoint.hostname !== '127.0.0.1' || Number(endpoint.port) !== inspectorPort || endpoint.username || endpoint.password) {
+    throw new Error('Inspector must remain on the selected container loopback port');
+  }
+  const socket = new WebSocket(endpoint.href);
+  return await new Promise((resolveResult, reject) => {
+    const timeout = setTimeout(() => finish(new Error('Inspector operation timed out')), 10_000);
+    let finished = false;
+    function finish(error, value) {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timeout);
+      try { socket.close(); } catch { /* Preserve the original failure. */ }
+      if (error) reject(error); else resolveResult(value);
+    }
+    socket.addEventListener('error', () => finish(new Error('Inspector connection failed')));
+    socket.addEventListener('close', () => { if (!finished) finish(new Error('Inspector disconnected')); });
+    socket.addEventListener('open', () => socket.send(JSON.stringify({ id: 1, method: 'Runtime.evaluate', params: {
+      expression: `(${controlHttpAdmission.toString()})(${JSON.stringify(options)})`, returnByValue: true,
+    } })));
+    socket.addEventListener('message', ({ data }) => {
+      try {
+        const message = JSON.parse(String(data));
+        if (message.id !== 1) return;
+        if (message.error || message.result?.exceptionDetails) return finish(new Error('Target rejected drain operation: ' + JSON.stringify(message.error ?? message.result.exceptionDetails)));
+        const value = message.result?.result?.value;
+        if (!value || value.pid !== options.expectedPid || value.nonce !== options.nonce) return finish(new Error('Invalid target drain receipt'));
+        finish(undefined, value);
+      } catch (error) { finish(error); }
+    });
+  });
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const options = JSON.parse(process.argv[2] ?? '{}');
+  try { console.log(JSON.stringify(await inspectorControl(options))); }
+  catch (error) { console.error(error.message); process.exitCode = 1; }
+}