@p10i/create-nestbox 0.2.0 → 0.3.0

package/.env.example

@@ -8,9 +8,10 @@ COMPOSE_PROJECT_NAME=nestbox-change-me
 # directory, or .. when this installation is <workspace>/.nestbox.
 WORKSPACE_PATH=.
 
-# Absolute host-state directory shared only by the native runner and control.
-# The creator generates this value outside the mounted workspace.
-NESTBOX_HOST_QUEUE_PATH=
+# Loopback-only endpoint used by the native host runner. The creator generates
+# a private token; do not expose this port beyond the local host.
+NESTBOX_CONTROL_HOST_PORT=4089
+NESTBOX_HOST_TOKEN_FILE=
 
 # Override for rootless or nonstandard Docker Engine installations.
 DOCKER_SOCKET_PATH=/var/run/docker.sock

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.3.0
+
+- Replace the filesystem host queue with authenticated HTTP long polling managed by `control`.
+- Publish only the dedicated host-runner endpoint on loopback; keep the container API internal.
+- Remove queue paths, bind mounts, polling files, and stale lock/result state.
+- Generate a per-installation runner token file unavailable to application containers and preserve existing MCP and PHP contracts.
+
 ## 0.2.0
 
 - Add a private, label-gated container control service and OpenCode MCP adapter.

package/INSTALL.md

@@ -12,13 +12,15 @@ npm create @p10i/nestbox@latest
 
 The published npm package is `@p10i/create-nestbox`; npm maps `npm create @p10i/nestbox` to that package. The creator explains and previews one of the two default layouts before writing files. The recommended layout installs at `<workspace>/.nestbox` so Nestbox stays separate from project files. The direct layout writes Nestbox files into an empty selected directory. The creator copies `.env.example` to `.env`, copies `home/configs/opencode/instance.example.md` to `instance.md`, records npm package provenance in the instance policy, and initializes fresh installation Git history when Git is available.
 
-The creator does not start Docker, start the host bridge, or collect secrets. Node.js and npm are required for the bridge. After it finishes, edit `.env`, run `npm run host --` from the workspace in a separate terminal, then run from the installation directory:
+The creator does not start Docker, start the host bridge, or collect secrets. Node.js and npm are required for the bridge. After it finishes, edit `.env`, then run from the installation directory:
 
 ```sh
 docker compose config --quiet
 docker compose up -d --build
 ```
 
+After `control` is healthy, run `npm run host --` from the workspace in a separate terminal.
+
 Then run the host test suite documented in section 7.
 
 ## 1. Choose Language
@@ -42,7 +44,7 @@ Both defaults keep pages, Compose, Dockerfiles, configuration, dependencies, and
 
 Do not present vendoring, a parent-owned engine, a submodule, an external page tree, or another shared-repository arrangement as a default. These are optional adaptations discussed only when the user requests one.
 
-Never overwrite an existing installation. Inspect an existing target and ask whether to update, repair, reuse, or stop.
+Never overwrite an existing installation. Select a different target or stop.
 
 ## 3. Check Requirements And Git
 
@@ -98,9 +100,10 @@ Configure the host bridge in the workspace root before Compose starts:
 
 - For `.nestbox` layout, create `package.json` from `.nestbox/package.host.json` when absent, or merge only its `host` and `test:host` scripts into the existing manifest.
 - For direct layout, use `node host-runner.mjs` and `node tests/host-runner.mjs` for those scripts. A source clone's publisher-oriented `package.json` may be replaced by this installation manifest after preserving any intentional project metadata.
-- Never overwrite a conflicting script. Stop and ask for a different script name or an explicit migration.
-- Create a private host-state queue outside the workspace, record it in the ignored installation `.runtime/host-runner.json`, and set its absolute path as `NESTBOX_HOST_QUEUE_PATH` in `.env`. The npm creator performs this automatically.
-- Start `npm run host --` before Compose so the queue and heartbeat exist. The runner rejects queue locations inside the mounted workspace.
+- Never overwrite a conflicting script. Stop and ask for a different script name.
+- Set `NESTBOX_HOST_TOKEN_FILE` to a private file outside every container-mounted workspace. The npm creator writes a 64-character token there with owner-only permissions. Only `control` mounts the file; never paste the token into chat or expose it through a page.
+- Confirm that `NESTBOX_CONTROL_HOST_PORT`, normally `4089`, is available. Compose publishes this authenticated runner endpoint on host loopback only.
+- Start `npm run host --` after `control` is healthy. The runner authenticates, long-polls for work, sends heartbeats, and posts results without opening a host listener or sharing queue files.
 - The workspace manifest is mounted read-only in runtime containers. Confirmed changes are written only by the native host runner.
 
 Update the new `home/configs/opencode/instance.md` with:
@@ -118,6 +121,7 @@ Then ask about:
 
 - a unique lowercase `COMPOSE_PROJECT_NAME`;
 - whether to use default port `4180`; verify availability and ask before choosing another port;
+- whether host-runner port `4089` is available; keep it loopback-only;
 - loopback-only or network access;
 - OpenCode username and password;
 - AI providers;
@@ -271,4 +275,4 @@ When a super-document intentionally changes files in `/workspace`, follow that w
 
 ## 11. Optional Adaptations
 
-Retaining upstream Git history, adding an upstream remote, external page trees, parent-owned engines, submodules, vendoring, shared repositories, alternate Compose layouts, and operating-system shortcuts are optional. Explain their ownership and update consequences and obtain explicit confirmation before creating them. They must not obscure the two default installation paths.
+Retaining upstream Git history, adding an upstream remote, external page trees, parent-owned engines, submodules, vendoring, shared repositories, alternate Compose layouts, and operating-system shortcuts are optional. Explain their ownership consequences and obtain explicit confirmation before creating them. They must not obscure the two default installation paths.

package/README.md

@@ -12,7 +12,7 @@ Nestbox runs with Docker Compose using Nginx, PHP-FPM, Rollup, OpenCode, and a p
 
 The `control` service is the only container with `/var/run/docker.sock`. Its internal-only API permits exec only when caller, target, project, and root-user labels allow it. OpenCode reaches the API through the bundled control MCP and can target PHP-FPM and Rollup by default. Trusted PHP pages can use `nestbox_control_exec()` and are restricted to PHP-FPM self-exec.
 
-Native host commands are limited to scripts already declared in the workspace `package.json`. Keep `npm run host --` running from the workspace when host scripts are needed. The bridge exchanges typed files through creator-generated host state outside the container-mounted workspace; it opens no network listener. MCP can request script additions, edits, or deletions, but the host runner applies them only after the user supplies a short-lived code displayed exclusively in the host terminal.
+Native host commands are limited to scripts already declared in the workspace `package.json`. Keep `npm run host --` running from the workspace when host scripts are needed. The native runner authenticates with an external token file mounted only into `control`, long-polls a loopback-only endpoint, and posts results; no host server or shared filesystem queue is used. MCP can request script additions, edits, or deletions, but the host runner applies them only after the user supplies a short-lived code displayed exclusively in the host terminal.
 
 Control emits bounded structured events to ordinary container logs. Use `docker compose logs control`; no telemetry collector, database, or observability dependency is installed. Docker socket access is root-equivalent on the host, and host scripts execute in the trusted writable workspace, so neither mechanism is a sandbox.
 
@@ -39,11 +39,3 @@ For agent-guided installation or repair work, copy and send this to an agent wit
 ```text
 Install Nestbox by following https://github.com/piontkovsk11andre1/nestbox/blob/main/INSTALL.md completely. Ask all required questions before making changes, preserve unrelated files and Git history, and do not expose secrets.
 ```
-
-## Update
-
-Run an update request from the workspace containing Nestbox, then copy and send this prompt to an agent with filesystem, Git, Docker, and terminal access:
-
-```text
-Update this Nestbox installation from https://github.com/piontkovsk11andre1/nestbox. Locate the installation, inspect its local Git history and configuration, read the current remote INSTALL.md and internal Nestbox instructions, preserve pages, instance policy, secrets, volumes, and unrelated changes, explain the proposed update, and ask before destructive or system-level operations. Validate Compose and run the Nestbox host tests after applying the update.
-```

package/bin/create-nestbox.js

@@ -1,17 +1,22 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
-import { randomUUID } from 'node:crypto';
+import { randomBytes, randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { cp, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { cp, mkdir, readdir, readFile, realpath, stat, writeFile } from 'node:fs/promises';
 import { constants } from 'node:fs';
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const packageJson = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'));
 
+function containsPath(root, target) {
+  const child = relative(resolve(root), resolve(target));
+  return child === '' || (!child.startsWith(`..${sep}`) && child !== '..' && !isAbsolute(child));
+}
+
 const copyEntries = [
   'docker',
   'home',
@@ -147,7 +152,7 @@ async function configureInstance(installDir, workspaceDir, layout) {
   });
   const envPath = join(installDir, '.env');
   const workspaceValue = layout === 'nestbox' ? '..' : '.';
-  const configuredEnv = (await readFile(envPath, 'utf8')).replace(/^WORKSPACE_PATH=.*$/m, `WORKSPACE_PATH=${workspaceValue}`);
+  const configuredEnv = (await readFile(envPath, 'utf8')).replace(/^WORKSPACE_PATH=.*\r?$/m, `WORKSPACE_PATH=${workspaceValue}`);
   await writeFile(envPath, configuredEnv, 'utf8');
 
   const instanceExample = join(installDir, 'home', 'configs', 'opencode', 'instance.example.md');
@@ -222,18 +227,21 @@ async function configureHostPackage(installDir, workspaceDir, layout) {
     private: true,
     scripts
   }, null, 2)}\n`, 'utf8');
+  const envPath = join(installDir, '.env');
+  const token = randomBytes(32).toString('hex');
   const stateBase = process.env.NESTBOX_CREATOR_STATE_ROOT
     || process.env.LOCALAPPDATA
     || process.env.XDG_STATE_HOME
     || (process.platform === 'darwin' ? join(homedir(), 'Library', 'Application Support') : join(homedir(), '.local', 'state'));
-  const queue = join(stateBase, 'nestbox', 'host-runner', randomUUID());
-  await mkdir(queue, { recursive: true });
-  const runtime = join(installDir, '.runtime');
-  await mkdir(runtime, { recursive: true });
-  await writeFile(join(runtime, 'host-runner.json'), `${JSON.stringify({ queue }, null, 2)}\n`, 'utf8');
-  const envPath = join(installDir, '.env');
-  const composeQueue = queue.replaceAll('\\', '/');
-  const configuredEnv = (await readFile(envPath, 'utf8')).replace(/^NESTBOX_HOST_QUEUE_PATH=.*$/m, () => `NESTBOX_HOST_QUEUE_PATH=${composeQueue}`);
+  const tokenDirectory = join(stateBase, 'nestbox', 'host-control');
+  await mkdir(tokenDirectory, { recursive: true });
+  const tokenPath = join(await realpath(tokenDirectory), `${randomUUID()}.token`);
+  const canonicalWorkspace = await realpath(workspaceDir);
+  const canonicalInstall = await realpath(installDir);
+  if (containsPath(canonicalWorkspace, tokenPath) || containsPath(canonicalInstall, tokenPath)) throw new Error('Host token state directory must be outside the workspace and Nestbox installation.');
+  await writeFile(tokenPath, `${token}\n`, { encoding: 'utf8', mode: 0o600 });
+  const composeTokenPath = tokenPath.replaceAll('\\', '/');
+  const configuredEnv = (await readFile(envPath, 'utf8')).replace(/^NESTBOX_HOST_TOKEN_FILE=.*\r?$/m, () => `NESTBOX_HOST_TOKEN_FILE=${composeTokenPath}`);
   await writeFile(envPath, configuredEnv, 'utf8');
 }
 
@@ -286,12 +294,13 @@ async function main() {
     console.log(`Workspace: ${workspaceDir}`);
     console.log(`Git initialized: ${gitInitialized ? 'yes' : 'no'}`);
     console.log('\nNext steps:');
-    console.log(`  cd ${workspaceDir}`);
-    console.log('  npm run host --');
     console.log(`  cd ${installDir}`);
     console.log('  Edit .env and set COMPOSE_PROJECT_NAME, WEB_PORT, OpenCode credentials, and provider keys.');
     console.log('  docker compose config --quiet');
     console.log('  docker compose up -d --build');
+    console.log(`  cd ${workspaceDir}`);
+    console.log('  npm run host --');
+    console.log(`  cd ${installDir}`);
     console.log(process.platform === 'win32' ? '  .\\tests\\nestbox.ps1' : '  bash tests/nestbox.sh');
   } finally {
     rl.close();

package/docker/control/server.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 import http.client
+import hmac
 import json
 import os
 import re
@@ -10,16 +11,24 @@ import time
 import uuid
 from datetime import datetime, timezone
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
-from urllib.parse import quote, unquote, urlparse
+from urllib.parse import parse_qs, quote, unquote, urlparse
 
 DOCKER_SOCKET = os.environ.get("DOCKER_SOCKET", "/var/run/docker.sock")
 WORKSPACE_PATH = os.environ.get("WORKSPACE_PATH", "/workspace")
 PROJECT_NAME = os.environ.get("COMPOSE_PROJECT_NAME", "").strip()
 SERVICE_NAME = os.environ.get("NESTBOX_CONTROL_SERVICE", "control")
-HOST_ROOT = os.environ.get("NESTBOX_HOST_RUNNER_PATH", "/host-runner")
+HOST_TOKEN_FILE = os.environ.get("NESTBOX_HOST_TOKEN_FILE", "/run/secrets/nestbox-host-token")
+try:
+    with open(HOST_TOKEN_FILE, encoding="utf-8") as token_stream:
+        HOST_TOKEN = token_stream.read().strip()
+except OSError:
+    HOST_TOKEN = ""
 HOST_TIMEOUT = int(os.environ.get("NESTBOX_HOST_RUNNER_TIMEOUT", "3600"))
-HOST_HEARTBEAT_TTL = int(os.environ.get("NESTBOX_HOST_RUNNER_HEARTBEAT_TTL", "5"))
+HOST_HEARTBEAT_TTL = int(os.environ.get("NESTBOX_HOST_RUNNER_HEARTBEAT_TTL", "10"))
+HOST_LONG_POLL_TIMEOUT = int(os.environ.get("NESTBOX_HOST_LONG_POLL_TIMEOUT", "25"))
+MAX_HOST_JOBS = int(os.environ.get("NESTBOX_MAX_HOST_JOBS", "100"))
 MAX_BODY_BYTES = 128 * 1024
+MAX_HOST_BODY_BYTES = 64 * 1024 * 1024
 MAX_COMMAND_PARTS = 256
 MAX_COMMAND_BYTES = 64 * 1024
 LOG_OUTPUT = os.environ.get("NESTBOX_CONTROL_LOG_OUTPUT", "text").lower()
@@ -191,51 +200,155 @@ def package_scripts():
     return {str(name): str(command) for name, command in scripts.items()}
 
 
-def host_paths():
-    return {name: os.path.join(HOST_ROOT, name) for name in ("requests", "results", "heartbeat")}
+class HostBroker:
+    def __init__(self):
+        self.condition = threading.Condition()
+        self.pending = []
+        self.jobs = {}
+        self.runner = {}
+
+    def touch(self, runner_id, headers):
+        if not re.fullmatch(r"[A-Za-z0-9._:-]{8,128}", runner_id):
+            raise ValueError("invalid runner ID")
+        now = time.monotonic()
+        with self.condition:
+            active_id = self.runner.get("id")
+            active_age = now - self.runner.get("seen", 0)
+            if active_id and active_id != runner_id and active_age <= HOST_HEARTBEAT_TTL:
+                raise PermissionError("another host runner is active")
+            if active_id and active_id != runner_id:
+                for record in self.jobs.values():
+                    if record.get("runnerId") == active_id and record.get("result") is None:
+                        record["result"] = {
+                            "jobId": record["job"]["jobId"],
+                            "exitCode": 1,
+                            "stdout": "",
+                            "stderr": "The assigned host runner disconnected before returning a result.",
+                            "interrupted": True,
+                        }
+            self.runner = {
+                "id": runner_id,
+                "seen": now,
+                "pid": headers.get("X-Nestbox-Runner-Pid"),
+                "platform": headers.get("X-Nestbox-Runner-Platform"),
+                "hostname": headers.get("X-Nestbox-Runner-Host"),
+            }
+            self.condition.notify_all()
+
+    def status(self):
+        with self.condition:
+            if not self.runner:
+                return {"available": False}
+            age = max(0, time.monotonic() - self.runner["seen"])
+            return {
+                "available": age <= HOST_HEARTBEAT_TTL,
+                "ageSeconds": round(age, 3),
+                "pid": self.runner.get("pid"),
+                "platform": self.runner.get("platform"),
+                "hostname": self.runner.get("hostname"),
+            }
+
+    def enqueue(self, job):
+        with self.condition:
+            if len(self.jobs) >= MAX_HOST_JOBS:
+                raise RuntimeError("too many host jobs are pending")
+            self.jobs[job["jobId"]] = {"job": job, "result": None, "runnerId": None}
+            self.pending.append(job["jobId"])
+            self.condition.notify_all()
+
+    def next(self, runner_id, headers, timeout):
+        deadline = time.monotonic() + timeout
+        with self.condition:
+            while True:
+                if self.runner.get("id") != runner_id:
+                    raise PermissionError("another host runner is active")
+                if time.monotonic() - self.runner.get("seen", 0) > HOST_HEARTBEAT_TTL:
+                    return None
+                if self.pending:
+                    identifier = self.pending.pop(0)
+                    record = self.jobs.get(identifier)
+                    if record:
+                        record["runnerId"] = runner_id
+                        return record["job"]
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    return None
+                self.condition.wait(min(1, remaining))
+
+    def complete(self, runner_id, identifier, result):
+        with self.condition:
+            record = self.jobs.get(identifier)
+            if not record or record.get("runnerId") != runner_id:
+                raise ValueError("host job is unknown or belongs to another runner")
+            if record.get("result") is not None:
+                raise ValueError("host job already has a result")
+            if result.get("jobId") != identifier:
+                raise ValueError("host result contains a mismatched job ID")
+            job = record["job"]
+            if job["type"] == "npm.run":
+                if not isinstance(result.get("exitCode"), int) or not isinstance(result.get("stdout"), str) or not isinstance(result.get("stderr"), str):
+                    raise ValueError("invalid npm run result")
+            elif job["type"] == "npm.scripts.request":
+                if result.get("status") != "confirmation_required" or result.get("requestId") != job.get("requestId") or result.get("operation") != job.get("operation") or result.get("name") != job.get("name"):
+                    if not isinstance(result.get("exitCode"), int):
+                        raise ValueError("invalid script change request result")
+            elif job["type"] == "npm.scripts.confirm":
+                if result.get("status") == "success" and result.get("requestId") != job.get("requestId"):
+                    raise ValueError("invalid script confirmation result")
+                if result.get("status") != "success" and not isinstance(result.get("exitCode"), int):
+                    raise ValueError("invalid script confirmation result")
+            record["result"] = result
+            self.condition.notify_all()
+
+    def wait(self, identifier, timeout=HOST_TIMEOUT):
+        deadline = time.monotonic() + timeout
+        with self.condition:
+            while True:
+                record = self.jobs.get(identifier)
+                if record and record.get("runnerId") and record.get("result") is None:
+                    owner = record["runnerId"]
+                    if self.runner.get("id") != owner or time.monotonic() - self.runner.get("seen", 0) > HOST_HEARTBEAT_TTL:
+                        record["result"] = {
+                            "jobId": identifier,
+                            "exitCode": 1,
+                            "stdout": "",
+                            "stderr": "The assigned host runner disconnected before returning a result.",
+                            "interrupted": True,
+                        }
+                elif record and record.get("result") is None and self.runner and time.monotonic() - self.runner.get("seen", 0) > HOST_HEARTBEAT_TTL:
+                    record["result"] = {
+                        "jobId": identifier,
+                        "exitCode": 1,
+                        "stdout": "",
+                        "stderr": "The host runner disconnected before accepting the job.",
+                        "interrupted": True,
+                    }
+                if record and record.get("result") is not None:
+                    result = record["result"]
+                    del self.jobs[identifier]
+                    return result
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    self.jobs.pop(identifier, None)
+                    if identifier in self.pending:
+                        self.pending.remove(identifier)
+                    raise TimeoutError(f"host runner did not finish within {timeout} seconds")
+                self.condition.wait(min(1, remaining))
+
+
+HOST_BROKER = HostBroker()
 
 
 def host_status():
-    paths = host_paths()
-    try:
-        age = max(0, time.time() - os.path.getmtime(paths["heartbeat"] + ".json"))
-        with open(paths["heartbeat"] + ".json", encoding="utf-8") as stream:
-            heartbeat = json.load(stream)
-        return {"available": age <= HOST_HEARTBEAT_TTL, "ageSeconds": round(age, 3), "pid": heartbeat.get("pid"), "platform": heartbeat.get("platform"), "hostname": heartbeat.get("hostname")}
-    except (OSError, ValueError, TypeError):
-        return {"available": False}
-
-
-def atomic_json(path, value):
-    temporary = f"{path}.{uuid.uuid4().hex}.tmp"
-    with open(temporary, "w", encoding="utf-8") as stream:
-        json.dump(value, stream, sort_keys=True)
-        stream.write("\n")
-    os.replace(temporary, path)
+    return HOST_BROKER.status()
 
 
 def enqueue(job):
-    paths = host_paths()
-    os.makedirs(paths["requests"], exist_ok=True)
-    os.makedirs(paths["results"], exist_ok=True)
-    atomic_json(os.path.join(paths["requests"], f"{job['jobId']}.json"), job)
-    return paths
+    HOST_BROKER.enqueue(job)
 
 
-def wait_result(identifier, paths, timeout=HOST_TIMEOUT):
-    path = os.path.join(paths["results"], f"{identifier}.json")
-    deadline = time.monotonic() + timeout
-    while time.monotonic() < deadline:
-        try:
-            with open(path, encoding="utf-8") as stream:
-                result = json.load(stream)
-            os.unlink(path)
-            if result.get("jobId") != identifier:
-                raise ValueError("host runner returned a mismatched job ID")
-            return result
-        except FileNotFoundError:
-            time.sleep(0.1)
-    raise TimeoutError(f"host runner did not finish within {timeout} seconds")
+def wait_result(identifier, timeout=HOST_TIMEOUT):
+    return HOST_BROKER.wait(identifier, timeout)
 
 
 def record_host_result(identifier, source_name, script, result, detached):
@@ -245,9 +358,9 @@ def record_host_result(identifier, source_name, script, result, detached):
     log_event("npm.complete", runId=identifier, source=source_name, script=script, detached=detached, executor="host", exitCode=result.get("exitCode"), hostPlatform=result.get("hostPlatform"), hostName=result.get("hostName"), stdoutTruncated=bool(result.get("stdoutTruncated")), stderrTruncated=bool(result.get("stderrTruncated")))
 
 
-def wait_detached(identifier, paths, source_name, script):
+def wait_detached(identifier, source_name, script):
     try:
-        record_host_result(identifier, source_name, script, wait_result(identifier, paths), True)
+        record_host_result(identifier, source_name, script, wait_result(identifier), True)
     except Exception as error:
         log_event("npm.error", runId=identifier, source=source_name, script=script, detached=True, error=str(error))
 
@@ -259,7 +372,7 @@ def valid_command(command):
 
 
 class Handler(BaseHTTPRequestHandler):
-    server_version = "nestbox-control/0.2"
+    server_version = "nestbox-control/0.3"
 
     def setup(self):
         super().setup()
@@ -398,11 +511,11 @@ class Handler(BaseHTTPRequestHandler):
         identifier = run_id("npm")
         job = {"schemaVersion": 1, "jobId": identifier, "type": "npm.run", "script": script, "args": args, "source": service(source), "createdAt": now_iso()}
         try:
-            paths = enqueue(job)
+            enqueue(job)
             if body.get("detach"):
-                threading.Thread(target=wait_detached, args=(identifier, paths, service(source), script), daemon=True).start()
+                threading.Thread(target=wait_detached, args=(identifier, service(source), script), daemon=True).start()
                 self.send_json(202, {"runId": identifier, "detached": True, "executor": "host"}); return
-            result = wait_result(identifier, paths)
+            result = wait_result(identifier)
             record_host_result(identifier, service(source), script, result, False)
             self.send_json(200, {"runId": identifier, "exitCode": result.get("exitCode"), "stdout": str(result.get("stdout", "")), "stderr": str(result.get("stderr", "")), "pid": result.get("pid"), "executor": "host"})
         except Exception as error:
@@ -422,7 +535,8 @@ class Handler(BaseHTTPRequestHandler):
         job = {"schemaVersion": 1, "jobId": identifier, "type": "npm.scripts.request", "requestId": identifier, "operation": operation, "name": name, "source": service(source), "createdAt": now_iso()}
         if operation != "delete": job["command"] = command
         try:
-            result = wait_result(identifier, enqueue(job))
+            enqueue(job)
+            result = wait_result(identifier)
             if result.get("status") != "confirmation_required": raise ValueError(result.get("stderr", "host runner rejected the request"))
             self.send_json(202, {"status": "confirmation_required", "requestId": result.get("requestId"), "operation": operation, "name": name, "expiresAt": result.get("expiresAt")})
         except Exception as error:
@@ -437,16 +551,108 @@ class Handler(BaseHTTPRequestHandler):
         identifier = run_id("npm-script-confirm")
         job = {"schemaVersion": 1, "jobId": identifier, "type": "npm.scripts.confirm", "requestId": request_id, "code": code, "source": service(source), "createdAt": now_iso()}
         try:
-            result = wait_result(identifier, enqueue(job))
+            enqueue(job)
+            result = wait_result(identifier)
             if result.get("status") != "success": raise ValueError(result.get("stderr", "host runner rejected the confirmation"))
             self.send_json(200, {"status": "success", "requestId": request_id, "operation": result.get("operation"), "name": result.get("name")})
         except Exception as error:
             self.send_json(400, {"error": str(error)})
 
 
+class HostHandler(BaseHTTPRequestHandler):
+    server_version = "nestbox-host-control/0.3"
+
+    def setup(self):
+        super().setup()
+        self.connection.settimeout(HOST_LONG_POLL_TIMEOUT + 10)
+
+    def log_message(self, fmt, *args):
+        log_event("host.http.access", client=self.address_string(), message=fmt % args)
+
+    def send_json(self, status, value):
+        payload = json.dumps(value, ensure_ascii=False).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def authorized(self):
+        supplied = self.headers.get("Authorization", "")
+        expected = f"Bearer {HOST_TOKEN}"
+        return hmac.compare_digest(supplied.encode(), expected.encode())
+
+    def runner(self):
+        return self.headers.get("X-Nestbox-Runner-Id", "")
+
+    def body(self):
+        if self.headers.get("Transfer-Encoding"):
+            raise ValueError("transfer encoding is not supported")
+        length = int(self.headers.get("Content-Length", "0"))
+        if length < 0 or length > MAX_HOST_BODY_BYTES:
+            raise ValueError("request body is too large")
+        value = json.loads(self.rfile.read(length)) if length else {}
+        if not isinstance(value, dict):
+            raise ValueError("request body must be a JSON object")
+        return value
+
+    def authenticate(self):
+        if not self.authorized():
+            self.send_json(401, {"error": "invalid host runner token"})
+            return False
+        try:
+            HOST_BROKER.touch(self.runner(), self.headers)
+            return True
+        except PermissionError as error:
+            self.send_json(409, {"error": str(error)})
+        except ValueError as error:
+            self.send_json(400, {"error": str(error)})
+        return False
+
+    def do_GET(self):
+        parsed = urlparse(self.path)
+        if parsed.path == "/host/health":
+            if not self.authenticate(): return
+            self.send_json(200, {"ok": True, "hostRunner": host_status()})
+            return
+        if parsed.path == "/host/jobs/next":
+            if not self.authenticate(): return
+            try:
+                requested = int((parse_qs(parsed.query).get("timeout") or [HOST_LONG_POLL_TIMEOUT])[0])
+                timeout = max(1, min(HOST_LONG_POLL_TIMEOUT, requested))
+                job = HOST_BROKER.next(self.runner(), self.headers, timeout)
+                if job is None:
+                    self.send_response(204); self.end_headers(); return
+                self.send_json(200, job)
+            except (TypeError, ValueError) as error:
+                self.send_json(400, {"error": str(error)})
+            return
+        self.send_json(404, {"error": "not found"})
+
+    def do_POST(self):
+        if not self.authenticate(): return
+        path = urlparse(self.path).path
+        if path == "/host/heartbeat":
+            self.send_json(200, {"ok": True})
+            return
+        match = re.fullmatch(r"/host/jobs/([A-Za-z0-9._:-]{1,128})/result", path)
+        if not match:
+            self.send_json(404, {"error": "not found"}); return
+        try:
+            result = self.body()
+            HOST_BROKER.complete(self.runner(), match.group(1), result)
+            self.send_json(202, {"accepted": True})
+        except ValueError as error:
+            self.send_json(400, {"error": str(error)})
+
+
 def main():
     if not re.fullmatch(r"[a-z0-9][a-z0-9_-]*", PROJECT_NAME):
         raise SystemExit("COMPOSE_PROJECT_NAME must be a non-empty lowercase project slug")
+    if len(HOST_TOKEN) < 32:
+        raise SystemExit("NESTBOX_HOST_TOKEN_FILE must contain a token of at least 32 characters")
+    host_server = ThreadingHTTPServer(("0.0.0.0", int(os.environ.get("NESTBOX_CONTROL_HOST_PORT", "4089"))), HostHandler)
+    threading.Thread(target=host_server.serve_forever, daemon=True).start()
     ThreadingHTTPServer(("0.0.0.0", int(os.environ.get("NESTBOX_CONTROL_PORT", "4088"))), Handler).serve_forever()
 
 

package/docker-compose.yaml

@@ -114,6 +114,9 @@ services:
       dockerfile: ./docker/control/Dockerfile
     expose:
       - "4088"
+    ports:
+      # Authenticated native runner transport; never bind beyond loopback.
+      - "127.0.0.1:${NESTBOX_CONTROL_HOST_PORT:-4089}:4089"
     volumes:
       - ${DOCKER_SOCKET_PATH:-/var/run/docker.sock}:/var/run/docker.sock
       - type: bind
@@ -123,14 +126,16 @@ services:
         bind:
           create_host_path: false
       - type: bind
-        source: ${NESTBOX_HOST_QUEUE_PATH:?NESTBOX_HOST_QUEUE_PATH must be configured}
-        target: /host-runner
+        source: ${NESTBOX_HOST_TOKEN_FILE:?NESTBOX_HOST_TOKEN_FILE must be configured}
+        target: /run/secrets/nestbox-host-token
+        read_only: true
         bind:
           create_host_path: false
     environment:
       - COMPOSE_PROJECT_NAME=${COMPOSE_PROJECT_NAME}
       - NESTBOX_CONTROL_SERVICE=control
-      - NESTBOX_HOST_RUNNER_PATH=/host-runner
+      - NESTBOX_CONTROL_HOST_PORT=4089
+      - NESTBOX_HOST_TOKEN_FILE=/run/secrets/nestbox-host-token
       - NESTBOX_CONTROL_LOG_OUTPUT=${NESTBOX_CONTROL_LOG_OUTPUT:-text}
       - NESTBOX_CONTROL_LOG_MAX_BYTES=${NESTBOX_CONTROL_LOG_MAX_BYTES:-262144}
     healthcheck:

package/home/configs/opencode/control-mcp.js

@@ -74,7 +74,7 @@ async function call(name, raw) {
 
 function emit(value) { process.stdout.write(`${JSON.stringify(value)}\n`); }
 async function handle(message) {
-  if (message.method === 'initialize') return emit({ jsonrpc: '2.0', id: message.id, result: { protocolVersion: '2024-11-05', capabilities: { tools: { listChanged: false } }, serverInfo: { name: 'nestbox-control-mcp', version: '0.2.0' } } });
+  if (message.method === 'initialize') return emit({ jsonrpc: '2.0', id: message.id, result: { protocolVersion: '2024-11-05', capabilities: { tools: { listChanged: false } }, serverInfo: { name: 'nestbox-control-mcp', version: '0.3.0' } } });
   if (message.method === 'initialized') return;
   if (message.method === 'tools/list') return emit({ jsonrpc: '2.0', id: message.id, result: { tools } });
   if (message.method === 'tools/call') {

package/home/configs/opencode/instructions.md

@@ -178,15 +178,15 @@ OpenCode has no Docker socket. Use the control MCP as the only path for commands
 - `npm_script_change_request` requests an add, edit, or delete. The confirmation code appears only in the host runner terminal.
 - `npm_script_change_confirm` applies the pending change after the user explicitly supplies that code.
 
-Do not call the control HTTP API directly from OpenCode, write queue files, invoke Docker or SSH as a substitute, or work around a missing MCP capability. PHP cannot invoke MCP, so trusted super-documents may use `nestbox_control_exec()`; default labels restrict PHP-FPM to self-exec. Only OpenCode has `nestbox.npm.allow=true` by default. Root exec requires an explicit target label.
+Do not call the control HTTP API directly from OpenCode, impersonate the native runner, invoke Docker or SSH as a substitute, or work around a missing MCP capability. PHP cannot invoke MCP, so trusted super-documents may use `nestbox_control_exec()`; default labels restrict PHP-FPM to self-exec. Only OpenCode has `nestbox.npm.allow=true` by default. Root exec requires an explicit target label.
 
-The control log is the audit source of truth and requires no observability service. Its host queue stays outside container-mounted workspace paths. Commands still operate in trusted containers and a trusted writable workspace; Docker socket access and editable host-script source mean this is a controlled capability, not a security sandbox.
+The control log is the audit source of truth and requires no observability service. The native runner uses an authenticated, loopback-only long-poll endpoint; no host listener or filesystem queue exists. Commands still operate in trusted containers and a trusted writable workspace; Docker socket access and editable host-script source mean this is a controlled capability, not a security sandbox.
 
 ## Git And Commit Policy
 
 - Resolve the owning Git root before staging any path.
 - Read the separately loaded `instance.md` before committing Nestbox work. It records the installation layout, repository roots, and commit policy without exposing `.env`.
-- Treat the repository as installation history. Do not assume an upstream remote or upstream commit ancestry exists; use the recorded source revision when reasoning about upgrades.
+- Treat the repository as installation history. Do not assume an upstream remote or upstream commit ancestry exists.
 - The policy may allow logical commits after verification, require confirmation before each commit, or require leaving changes uncommitted.
 - Reasonable Nestbox commits include super-documents, Compose, Dockerfiles, configurations, integrations, and dependency files.
 - Keep commits within one Git root. When one feature spans repositories, create separate commits and report their relationship.