@p10i/create-nestbox 0.2.0 → 0.4.0

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.
@@ -204,7 +204,7 @@ The default Compose application has five services:
 - `opencode`: runs this agent, mounts the engine and workspace, and edits the page tree through `/nestbox/home/code`.
 - `control`: owns the Docker socket and privately brokers label-gated container exec and host-runner jobs.
 
-The default host port is `4180` after installer confirmation. Nginx container port `80` serves both Nestbox and OpenCode through host-based routing. Nginx container port `8080` is only the internal Nchan publisher.
+The default host port is `4180` after installer confirmation. Nginx container port `80` serves Nestbox, OpenCode through host-based routing, and the authenticated `/_nestbox/host/` runner transport. Nginx container port `8080` is only the internal Nchan publisher. No other service publishes a host port.
 
 Important files:
 
@@ -226,6 +226,7 @@ The engine's untracked `/nestbox/.env` controls runtime paths, exposure, authent
 - `COMPOSE_PROJECT_NAME`: unique installation identifier; collisions can mix unrelated containers and networks.
 - `BIND_ADDRESS`: loopback for local use or an explicitly approved network bind.
 - `WEB_PORT`: confirmed host gateway port, normally `4180`.
+- `NESTBOX_HOST_TOKEN_FILE`: creator-managed private runner token outside the mounted workspace; only `control` receives it.
 - `APP_UID` and `APP_GID`: PHP-FPM ownership for writable bind mounts.
 - `NESTBOX_URL_PREFIX`: public path prefix when an outer proxy strips that prefix before forwarding.
 - `NESTBOX_OPENCODE_PUBLIC_URL`: explicit public OpenCode origin when `agent.<nestbox-host>` cannot be derived.

package/home/configs/rollup/package-lock.json

@@ -1088,16 +1088,15 @@
             "license": "CC0-1.0"
         },
         "node_modules/nanoid": {
-            "version": "3.3.12",
-            "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.12.tgz",
-            "integrity": "sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==",
+            "version": "3.3.18",
+            "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.18.tgz",
+            "integrity": "sha512-DTg4MJbGMWkfi6VZFdNt2/caMbQy4Ou+Op/hJQvGEWcnVfoA1QA+xzRKAzw9jD6+GVOOeYr/mIcuDSdug6F6+w==",
             "funding": [
                 {
                     "type": "github",
                     "url": "https://github.com/sponsors/ai"
                 }
             ],
-            "license": "MIT",
             "peer": true,
             "bin": {
                 "nanoid": "bin/nanoid.cjs"
@@ -1210,9 +1209,9 @@
             }
         },
         "node_modules/postcss": {
-            "version": "8.5.14",
-            "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.14.tgz",
-            "integrity": "sha512-SoSL4+OSEtR99LHFZQiJLkT59C5B1amGO1NzTwj7TT1qCUgUO6hxOvzkOYxD+vMrXBM3XJIKzokoERdqQq/Zmg==",
+            "version": "8.5.26",
+            "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.26.tgz",
+            "integrity": "sha512-u82N74LFzG8ca+dD8puPnplTXoGH4fTPpVGuIbt36G3qvNlkvfD0lEAZSxaly3KX8TS/L1A1gsCEmvKmBcVbkQ==",
             "funding": [
                 {
                     "type": "opencollective",
@@ -1227,10 +1226,9 @@
                     "url": "https://github.com/sponsors/ai"
                 }
             ],
-            "license": "MIT",
             "peer": true,
             "dependencies": {
-                "nanoid": "^3.3.11",
+                "nanoid": "^3.3.17",
                 "picocolors": "^1.1.1",
                 "source-map-js": "^1.2.1"
             },
@@ -2020,10 +2018,9 @@
             }
         },
         "node_modules/svgo": {
-            "version": "2.8.2",
-            "resolved": "https://registry.npmjs.org/svgo/-/svgo-2.8.2.tgz",
-            "integrity": "sha512-TyzE4NVGLUFy+H/Uy4N6c3G0HEeprsVfge6Lmq+0FdQQ/zqoVYB62IsBZORsiL+o96s6ff/V6/3UQo/C0cgCAA==",
-            "license": "MIT",
+            "version": "2.8.3",
+            "resolved": "https://registry.npmjs.org/svgo/-/svgo-2.8.3.tgz",
+            "integrity": "sha512-5EZD0pafXX6PphdwOGCiVLDSaV1xyuQao2blHajHLsPxr07q4mmEjdtXEWgG07ae2mIz8Ex2CDXNCTiXhy3Khw==",
             "dependencies": {
                 "commander": "^7.2.0",
                 "css-select": "^4.1.3",

package/host-runner.mjs

@@ -1,30 +1,52 @@
 import { spawn } from 'node:child_process';
-import { createHash, randomBytes } from 'node:crypto';
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
 import { hostname, platform } from 'node:os';
-import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { mkdir, open, readFile, readdir, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { readFile, realpath, rename, unlink, writeFile } from 'node:fs/promises';
 
 const installDirectory = dirname(fileURLToPath(import.meta.url));
 const defaultWorkspace = basename(installDirectory) === '.nestbox' ? dirname(installDirectory) : installDirectory;
 const workspace = resolve(process.env.NESTBOX_HOST_WORKSPACE || defaultWorkspace);
-const runnerConfig = await readFile(join(installDirectory, '.runtime', 'host-runner.json'), 'utf8')
-  .then(value => JSON.parse(value), error => error?.code === 'ENOENT' ? {} : Promise.reject(error));
-const queueRoot = resolve(process.env.NESTBOX_HOST_QUEUE || runnerConfig.queue || join(installDirectory, '.runtime', 'host-runner'));
-const queueRelative = relative(workspace, queueRoot);
-if (queueRelative === '' || (!queueRelative.startsWith('..') && !isAbsolute(queueRelative))) {
-  throw new Error('NESTBOX host queue must be outside the mounted workspace.');
+const canonicalInstallDirectory = await realpath(installDirectory).catch(() => resolve(installDirectory));
+const canonicalWorkspace = await realpath(workspace).catch(() => workspace);
+
+function parseEnv(contents) {
+  const values = {};
+  for (const line of contents.split(/\r?\n/)) {
+    const match = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+    if (!match) continue;
+    let value = match[2].trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) value = value.slice(1, -1);
+    values[match[1]] = value;
+  }
+  return values;
+}
+
+const fileEnv = await readFile(join(installDirectory, '.env'), 'utf8').then(parseEnv, error => error?.code === 'ENOENT' ? {} : Promise.reject(error));
+const bindAddress = process.env.BIND_ADDRESS || fileEnv.BIND_ADDRESS || '127.0.0.1';
+const gatewayAddress = bindAddress === '0.0.0.0' ? '127.0.0.1' : bindAddress === '::' ? '::1' : bindAddress;
+const gatewayHost = gatewayAddress.includes(':') && !gatewayAddress.startsWith('[') ? `[${gatewayAddress}]` : gatewayAddress;
+const webPort = process.env.WEB_PORT || fileEnv.WEB_PORT || '4180';
+const controlUrl = (process.env.NESTBOX_CONTROL_HOST_URL || fileEnv.NESTBOX_CONTROL_HOST_URL || `http://${gatewayHost}:${webPort}/_nestbox`).replace(/\/$/, '');
+const tokenPath = process.env.NESTBOX_HOST_TOKEN_FILE || fileEnv.NESTBOX_HOST_TOKEN_FILE || '';
+const resolvedTokenPath = tokenPath ? await realpath(resolve(tokenPath)).catch(() => resolve(tokenPath)) : '';
+function containsPath(root, target) {
+  const child = relative(resolve(root), target);
+  return child === '' || (!child.startsWith(`..${sep}`) && child !== '..' && !isAbsolute(child));
+}
+if (resolvedTokenPath && (containsPath(canonicalWorkspace, resolvedTokenPath) || containsPath(canonicalInstallDirectory, resolvedTokenPath))) {
+  throw new Error('NESTBOX_HOST_TOKEN_FILE must be outside the workspace and Nestbox installation.');
 }
-const requestsDirectory = join(queueRoot, 'requests');
-const runningDirectory = join(queueRoot, 'running');
-const resultsDirectory = join(queueRoot, 'results');
-const heartbeatPath = join(queueRoot, 'heartbeat.json');
-const lockPath = join(queueRoot, 'runner.lock');
-const takeoverPath = join(queueRoot, 'takeover.lock');
-const instanceId = `${process.pid}-${Date.now()}`;
+const fileToken = resolvedTokenPath ? await readFile(resolvedTokenPath, 'utf8').then(value => value.trim(), () => '') : '';
+const hostToken = fileToken;
+if (hostToken.length < 32) throw new Error('NESTBOX_HOST_TOKEN_FILE must contain a token of at least 32 characters.');
+
+const runnerId = randomUUID();
 const once = process.argv.slice(2).includes('--once');
 const jsonOutput = process.argv.slice(2).includes('--json');
 const npmExecutable = process.env.NESTBOX_HOST_NPM || 'npm';
+const npmCli = process.env.npm_execpath || (!process.env.NESTBOX_HOST_NPM && process.platform === 'win32' ? join(dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js') : '');
 const maximumOutputBytes = Number(process.env.NESTBOX_HOST_MAX_OUTPUT_BYTES || 4 * 1024 * 1024);
 const approvalTtlMs = Number(process.env.NESTBOX_HOST_APPROVAL_TTL_MS || 5 * 60 * 1000);
 const approvalMaximumAttempts = Number(process.env.NESTBOX_HOST_APPROVAL_ATTEMPTS || 3);
@@ -34,11 +56,13 @@ const hostName = hostname();
 const approvals = new Map();
 const activeChildren = new Set();
 let heartbeatTimer;
+let stopping = false;
+let shutdownDeadline = 0;
 
 function emit(type, fields = {}) {
   const event = { ...fields, type, timestamp: new Date().toISOString() };
   if (jsonOutput) return process.stdout.write(`${JSON.stringify(event)}\n`);
-  if (type === 'runner.ready') console.log(`Nestbox host runner listening in ${workspace}`);
+  if (type === 'runner.ready') console.log(`Nestbox host runner connected to ${controlUrl} for ${workspace}`);
   else if (type === 'npm.scripts.confirmation_required') {
     console.log(`\nApproval ${event.requestId}: ${event.operation} npm script "${event.name}"`);
     if (event.command !== undefined) console.log(`Command: ${event.command}`);
@@ -47,59 +71,71 @@ function emit(type, fields = {}) {
   else if (type === 'runner.error') console.error(event.error);
 }
 
-async function atomicJson(path, value) {
-  const temporary = `${path}.${instanceId}.tmp`;
-  await writeFile(temporary, `${JSON.stringify(value)}\n`, 'utf8');
+function headers(json = false) {
+  return {
+    Authorization: `Bearer ${hostToken}`,
+    'X-Nestbox-Runner-Id': runnerId,
+    'X-Nestbox-Runner-Pid': String(process.pid),
+    'X-Nestbox-Runner-Platform': hostPlatform,
+    'X-Nestbox-Runner-Host': hostName,
+    ...(json ? { 'Content-Type': 'application/json' } : {}),
+  };
+}
+
+async function controlRequest(method, path, body, timeoutMs = 35000) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    await rename(temporary, path);
-  } catch (error) {
-    if (process.platform !== 'win32' || !['EEXIST', 'EPERM'].includes(error?.code)) throw error;
-    await unlink(path).catch(() => {});
-    await rename(temporary, path);
+    const response = await fetch(controlUrl + path, {
+      method,
+      headers: headers(body !== undefined),
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: controller.signal,
+    });
+    const text = await response.text();
+    const value = text ? JSON.parse(text) : null;
+    if (!response.ok) {
+      const error = new Error(`Control ${method} ${path} returned ${response.status}: ${JSON.stringify(value)}`);
+      error.status = response.status;
+      throw error;
+    }
+    return { status: response.status, value };
+  } finally {
+    clearTimeout(timer);
   }
 }
 
-async function packageDocument() {
-  const document = JSON.parse(await readFile(join(workspace, 'package.json'), 'utf8'));
+async function packageText() { return readFile(join(workspace, 'package.json'), 'utf8'); }
+function parsePackageDocument(text) {
+  const document = JSON.parse(text);
   if (!document || typeof document !== 'object' || Array.isArray(document)) throw new Error('package.json must contain a JSON object.');
+  if (document.scripts !== undefined && (!document.scripts || typeof document.scripts !== 'object' || Array.isArray(document.scripts))) throw new Error('package.json scripts must be an object.');
   return document;
 }
-
-async function packageHash() {
-  const contents = await readFile(join(workspace, 'package.json'));
-  return createHash('sha256').update(contents).digest('hex');
-}
-
+async function packageDocument() { return parsePackageDocument(await packageText()); }
+function hash(contents) { return createHash('sha256').update(contents).digest('hex'); }
 async function packageScripts() {
   const document = await packageDocument();
   if (document.scripts === undefined) return {};
-  if (!document.scripts || typeof document.scripts !== 'object' || Array.isArray(document.scripts)) {
-    throw new Error('package.json scripts must be an object.');
-  }
+  if (!document.scripts || typeof document.scripts !== 'object' || Array.isArray(document.scripts)) throw new Error('package.json scripts must be an object.');
   return document.scripts;
 }
 
 async function writePackageJson(document, expectedHash) {
   const path = join(workspace, 'package.json');
-  const temporary = `${path}.${instanceId}.tmp`;
+  const temporary = `${path}.${runnerId}.tmp`;
   await writeFile(temporary, `${JSON.stringify(document, null, 2)}\n`, 'utf8');
-  if (expectedHash && await packageHash() !== expectedHash) {
+  if (hash(await packageText()) !== expectedHash) {
     await unlink(temporary).catch(() => {});
     throw new Error('package.json changed while the approved update was being prepared.');
   }
-  try {
-    await rename(temporary, path);
-  } catch (error) {
+  try { await rename(temporary, path); }
+  catch (error) {
     if (process.platform !== 'win32' || !['EEXIST', 'EPERM'].includes(error?.code)) throw error;
-    const backup = `${path}.${instanceId}.backup`;
+    const backup = `${path}.${runnerId}.backup`;
     await rename(path, backup);
-    try {
-      await rename(temporary, path);
-      await unlink(backup);
-    } catch (replaceError) {
-      await rename(backup, path).catch(() => {});
-      throw replaceError;
-    }
+    try { await rename(temporary, path); await unlink(backup); }
+    catch (replaceError) { await rename(backup, path).catch(() => {}); throw replaceError; }
   }
 }
 
@@ -110,9 +146,7 @@ function validateScriptChange(job, scripts) {
   const exists = Object.hasOwn(scripts, job.name);
   if (job.operation === 'add' && exists) throw new Error(`npm script already exists: ${job.name}`);
   if (job.operation !== 'add' && !exists) throw new Error(`npm script is not defined: ${job.name}`);
-  if (job.operation !== 'delete' && (typeof job.command !== 'string' || !job.command.trim() || job.command.length > 8192)) {
-    throw new Error('A non-empty command of at most 8192 characters is required.');
-  }
+  if (job.operation !== 'delete' && (typeof job.command !== 'string' || !job.command.trim() || job.command.length > 8192)) throw new Error('A non-empty command of at most 8192 characters is required.');
   if (job.operation === 'delete' && job.command !== undefined) throw new Error('Delete does not accept a command.');
 }
 
@@ -126,47 +160,31 @@ async function requestScriptChange(job) {
   pruneApprovals();
   if (approvals.has(job.requestId)) throw new Error('The request ID is already pending.');
   if (approvals.size >= maximumPendingApprovals) throw new Error('Too many npm script approvals are pending.');
-  const scripts = await packageScripts();
+  const text = await packageText();
+  const scripts = parsePackageDocument(text).scripts || {};
   validateScriptChange(job, scripts);
   const code = randomBytes(6).toString('base64url').slice(0, 8).toUpperCase();
   const expiresAtMs = Date.now() + approvalTtlMs;
-  approvals.set(job.requestId, {
-    ...job,
-    expectedCommand: Object.hasOwn(scripts, job.name) ? String(scripts[job.name]) : null,
-    expectedPackageHash: await packageHash(),
-    code,
-    attempts: 0,
-    expiresAtMs,
-  });
+  approvals.set(job.requestId, { ...job, expectedCommand: Object.hasOwn(scripts, job.name) ? String(scripts[job.name]) : null, expectedPackageHash: hash(text), code, attempts: 0, expiresAtMs });
   const expiresAt = new Date(expiresAtMs).toISOString();
   emit('npm.scripts.confirmation_required', { ...job, code, expiresAt });
   return { jobId: job.jobId, status: 'confirmation_required', requestId: job.requestId, operation: job.operation, name: job.name, expiresAt };
 }
 
 async function confirmScriptChange(job) {
-  if (typeof job.requestId !== 'string' || typeof job.code !== 'string') throw new Error('A request ID and confirmation code are required.');
   pruneApprovals();
   const approval = approvals.get(job.requestId);
   if (!approval) throw new Error('The npm script approval was not found or has expired.');
   approval.attempts += 1;
-  if (job.code.trim().toUpperCase() !== approval.code) {
+  if (String(job.code).trim().toUpperCase() !== approval.code) {
     if (approval.attempts >= approvalMaximumAttempts) approvals.delete(job.requestId);
     throw new Error(approval.attempts >= approvalMaximumAttempts ? 'Invalid confirmation code; the approval has been cancelled.' : 'Invalid confirmation code.');
   }
-  const document = await packageDocument();
-  if (await packageHash() !== approval.expectedPackageHash) {
-    approvals.delete(job.requestId);
-    throw new Error('package.json changed after approval was requested; request a new approval.');
-  }
-  const scripts = document.scripts || {};
-  const currentCommand = Object.hasOwn(scripts, approval.name) ? String(scripts[approval.name]) : null;
-  if (currentCommand !== approval.expectedCommand) {
-    approvals.delete(job.requestId);
-    throw new Error('package.json changed after approval was requested; request a new approval.');
-  }
+  const text = await packageText();
+  if (hash(text) !== approval.expectedPackageHash) { approvals.delete(job.requestId); throw new Error('package.json changed after approval was requested; request a new approval.'); }
+  const document = parsePackageDocument(text), scripts = document.scripts || {};
   validateScriptChange(approval, scripts);
-  if (approval.operation === 'delete') delete scripts[approval.name];
-  else scripts[approval.name] = approval.command;
+  if (approval.operation === 'delete') delete scripts[approval.name]; else scripts[approval.name] = approval.command;
   document.scripts = scripts;
   await writePackageJson(document, approval.expectedPackageHash);
   approvals.delete(job.requestId);
@@ -175,12 +193,10 @@ async function confirmScriptChange(job) {
 }
 
 function appendLimited(chunks, chunk, state) {
-  const buffer = Buffer.from(chunk);
-  state.totalBytes += buffer.length;
+  const buffer = Buffer.from(chunk); state.totalBytes += buffer.length;
   const available = Math.max(0, maximumOutputBytes - state.bytes);
   if (available) chunks.push(buffer.subarray(0, available));
-  state.bytes += Math.min(buffer.length, available);
-  if (buffer.length > available) state.truncated = true;
+  state.bytes += Math.min(buffer.length, available); if (buffer.length > available) state.truncated = true;
 }
 
 async function runNpm(job) {
@@ -189,24 +205,17 @@ async function runNpm(job) {
   if (job.script === 'host') throw new Error('The host bridge cannot invoke itself.');
   if (!Object.hasOwn(scripts, job.script)) throw new Error(`npm script is not defined: ${job.script}`);
   const args = ['run', job.script, ...(job.args.length ? ['--', ...job.args] : [])];
-  const executable = process.env.npm_execpath ? process.execPath : npmExecutable;
-  const executableArgs = process.env.npm_execpath ? [process.env.npm_execpath, ...args] : args;
+  const executable = npmCli ? process.execPath : npmExecutable;
+  const executableArgs = npmCli ? [npmCli, ...args] : args;
   const startedAt = new Date().toISOString();
-  return await new Promise(resolveJob => {
+  return new Promise(resolveJob => {
     const child = spawn(executable, executableArgs, { cwd: workspace, env: process.env, shell: false, windowsHide: true, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] });
     activeChildren.add(child);
-    const stdout = [], stderr = [];
-    const out = { bytes: 0, totalBytes: 0, truncated: false }, err = { bytes: 0, totalBytes: 0, truncated: false };
-    child.stdout.on('data', chunk => appendLimited(stdout, chunk, out));
-    child.stderr.on('data', chunk => appendLimited(stderr, chunk, err));
-    const result = (exitCode, message = '') => resolveJob({
-      jobId: job.jobId, exitCode, stdout: Buffer.concat(stdout).toString('utf8'), stderr: message || Buffer.concat(stderr).toString('utf8'),
-      pid: child.pid ?? null, hostPlatform, hostName, stdoutTruncated: out.truncated, stderrTruncated: err.truncated,
-      stdoutTotalBytes: out.totalBytes, stderrTotalBytes: message ? Buffer.byteLength(message) : err.totalBytes,
-      startedAt, completedAt: new Date().toISOString(),
-    });
-    child.on('error', error => { activeChildren.delete(child); result(1, error.message); });
-    child.on('close', code => { activeChildren.delete(child); result(Number.isInteger(code) ? code : 1); });
+    const stdout = [], stderr = [], out = { bytes: 0, totalBytes: 0, truncated: false }, err = { bytes: 0, totalBytes: 0, truncated: false };
+    child.stdout.on('data', chunk => appendLimited(stdout, chunk, out)); child.stderr.on('data', chunk => appendLimited(stderr, chunk, err));
+    const finish = (exitCode, message = '') => resolveJob({ jobId: job.jobId, exitCode, stdout: Buffer.concat(stdout).toString('utf8'), stderr: message || Buffer.concat(stderr).toString('utf8'), pid: child.pid ?? null, hostPlatform, hostName, stdoutTruncated: out.truncated, stderrTruncated: err.truncated, stdoutTotalBytes: out.totalBytes, stderrTotalBytes: message ? Buffer.byteLength(message) : err.totalBytes, startedAt, completedAt: new Date().toISOString() });
+    child.on('error', error => { activeChildren.delete(child); finish(1, error.message); });
+    child.on('close', code => { activeChildren.delete(child); finish(Number.isInteger(code) ? code : 1); });
   });
 }
 
@@ -218,84 +227,66 @@ async function execute(job) {
   throw new Error('Unsupported host job type.');
 }
 
-async function processRequest(path) {
-  const name = basename(path);
-  const runningPath = join(runningDirectory, name);
-  try { await rename(path, runningPath); } catch (error) { if (['ENOENT', 'EACCES', 'EPERM'].includes(error?.code)) return; throw error; }
-  const claimedJobId = name.replace(/\.json$/, '');
-  let result;
-  try {
-    const job = JSON.parse(await readFile(runningPath, 'utf8'));
-    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(claimedJobId) || job?.jobId !== claimedJobId) throw new Error('Host job ID must match its safe queue filename.');
-    result = await execute(job);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    result = { jobId: claimedJobId, exitCode: 1, stdout: '', stderr: message, pid: null, hostPlatform, hostName, stdoutTruncated: false, stderrTruncated: false, stdoutTotalBytes: 0, stderrTotalBytes: Buffer.byteLength(message), startedAt: new Date().toISOString(), completedAt: new Date().toISOString() };
-  }
-  await atomicJson(join(resultsDirectory, `${result.jobId}.json`), result);
-  await unlink(runningPath).catch(() => {});
-}
-
-async function cleanup() {
-  clearInterval(heartbeatTimer);
+async function stopChildren() {
   await Promise.all([...activeChildren].map(child => new Promise(resolveStop => {
     if (!child.pid) return resolveStop();
-    const done = () => resolveStop();
-    child.once('close', done);
-    if (process.platform === 'win32') {
-      const killer = spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { windowsHide: true, stdio: 'ignore' });
-      killer.once('close', done); killer.once('error', done);
-    } else {
-      try { process.kill(-child.pid, 'SIGTERM'); } catch { return done(); }
-      setTimeout(() => { try { process.kill(-child.pid, 'SIGKILL'); } catch {} }, 2000).unref();
-    }
+    const done = () => resolveStop(); child.once('close', done);
+    if (process.platform === 'win32') { const killer = spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { windowsHide: true, stdio: 'ignore' }); killer.once('close', done); killer.once('error', done); }
+    else { try { process.kill(-child.pid, 'SIGTERM'); } catch { return done(); } setTimeout(() => { try { process.kill(-child.pid, 'SIGKILL'); } catch {} }, 2000).unref(); }
   })));
-  try {
-    if ((await readFile(lockPath, 'utf8')).trim() === instanceId) await Promise.all([unlink(lockPath).catch(() => {}), unlink(heartbeatPath).catch(() => {})]);
-  } catch {}
 }
 
 async function main() {
-  await Promise.all([mkdir(requestsDirectory, { recursive: true }), mkdir(runningDirectory, { recursive: true }), mkdir(resultsDirectory, { recursive: true })]);
-  try {
-    const lock = await open(lockPath, 'wx'); await lock.writeFile(`${instanceId}\n`); await lock.close();
-  } catch (error) {
-    const heartbeatStale = await stat(heartbeatPath).then(value => Date.now() - value.mtimeMs > 5000, () => null);
-    const lockOld = await stat(lockPath).then(value => Date.now() - value.mtimeMs > 5000, () => false);
-    const stale = heartbeatStale === true || (heartbeatStale === null && lockOld);
-    if (error?.code !== 'EEXIST' || !stale) throw error;
-    let takeover;
+  let announced = false;
+  let backoffMs = 500;
+  while (!stopping) {
     try {
-      takeover = await open(takeoverPath, 'wx');
-      await takeover.writeFile(`${instanceId}\n`);
-    } catch {
-      throw new Error('Another host runner is recovering the stale lock.');
+      await controlRequest('POST', '/host/heartbeat', {});
+      if (!announced) {
+        announced = true;
+        heartbeatTimer = setInterval(() => controlRequest('POST', '/host/heartbeat', {}).catch(error => emit('runner.error', { error: error.message })), 2000);
+        emit('runner.ready', { workspace, controlUrl, pid: process.pid, platform: hostPlatform, hostname: hostName });
+      }
+      const response = await controlRequest('GET', '/host/jobs/next?timeout=25', undefined, 35000);
+      backoffMs = 500;
+      if (response.status === 204) {
+        if (once) break;
+        continue;
+      }
+      const job = response.value;
+      let result;
+      if (stopping) {
+        const timestamp = new Date().toISOString();
+        result = { jobId: job?.jobId, exitCode: 1, stdout: '', stderr: 'The host runner stopped before executing the assigned job.', pid: null, hostPlatform, hostName, interrupted: true, startedAt: timestamp, completedAt: timestamp };
+      }
+      else try { result = await execute(job); }
+      catch (error) { const message = error instanceof Error ? error.message : String(error); result = { jobId: job?.jobId, exitCode: 1, stdout: '', stderr: message, pid: null, hostPlatform, hostName, startedAt: new Date().toISOString(), completedAt: new Date().toISOString() }; }
+      do {
+        try {
+          await controlRequest('POST', `/host/jobs/${encodeURIComponent(result.jobId)}/result`, result);
+          break;
+        } catch (error) {
+          if (error.status && error.status < 500) { emit('runner.error', { error: error.message }); break; }
+          await new Promise(resolveWait => setTimeout(resolveWait, backoffMs));
+          backoffMs = Math.min(10000, backoffMs * 2);
+        }
+      } while (!stopping || Date.now() < shutdownDeadline);
+      if (once) break;
+    } catch (error) {
+      if (error.status === 401) throw error;
+      emit('runner.error', { error: `${error.message}; reconnecting` });
+      await new Promise(resolveWait => setTimeout(resolveWait, backoffMs));
+      backoffMs = Math.min(10000, backoffMs * 2);
     }
-    try {
-      await unlink(heartbeatPath).catch(() => {});
-      await unlink(lockPath);
-      const lock = await open(lockPath, 'wx'); await lock.writeFile(`${instanceId}\n`); await lock.close();
-    } finally {
-      await takeover.close();
-      await unlink(takeoverPath).catch(() => {});
-    }
-  }
-  for (const name of await readdir(runningDirectory)) {
-    if (!name.endsWith('.json')) continue;
-    const jobId = name.replace(/\.json$/, '');
-    const message = 'Host runner stopped while this job was active; the job was not replayed.';
-    await atomicJson(join(resultsDirectory, name), { jobId, exitCode: 1, stdout: '', stderr: message, pid: null, hostPlatform, hostName, interrupted: true, startedAt: new Date().toISOString(), completedAt: new Date().toISOString() });
-    await unlink(join(runningDirectory, name));
   }
-  const heartbeat = () => atomicJson(heartbeatPath, { schemaVersion: 1, instanceId, pid: process.pid, hostname: hostName, platform: hostPlatform, workspace, updatedAt: new Date().toISOString() });
-  await heartbeat(); heartbeatTimer = setInterval(() => heartbeat().catch(error => emit('runner.error', { error: error.message })), 1000);
-  emit('runner.ready', { workspace, pid: process.pid, platform: hostPlatform, hostname: hostName });
-  do {
-    for (const name of (await readdir(requestsDirectory)).filter(name => name.endsWith('.json')).sort()) await processRequest(join(requestsDirectory, name));
-    if (!once) await new Promise(resolveWait => setTimeout(resolveWait, 100));
-  } while (!once);
-  await cleanup();
+  clearInterval(heartbeatTimer);
 }
 
-for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => cleanup().finally(() => process.exit(0)));
-main().catch(error => { console.error(error instanceof Error ? error.message : String(error)); cleanup().finally(() => process.exit(1)); });
+for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => {
+  if (stopping) return;
+  stopping = true;
+  shutdownDeadline = Date.now() + 5000;
+  clearInterval(heartbeatTimer);
+  stopChildren().catch(error => emit('runner.error', { error: error.message || String(error) }));
+});
+main().catch(error => { emit('runner.error', { error: error.message || String(error) }); clearInterval(heartbeatTimer); stopChildren().finally(() => process.exit(1)); });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@p10i/create-nestbox",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Create Nestbox projects.",
   "license": "MIT",
   "type": "module",
@@ -11,8 +11,6 @@
     "bin/",
     "scripts/",
     "docker/",
-    "!docker/control/__pycache__/",
-    "!**/*.pyc",
     "home/",
     "tests/",
     "host-runner.mjs",
@@ -25,7 +23,12 @@
     "INSTALL.md",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "!docker/control/__pycache__/",
+    "!**/*.pyc",
+    "!**/node_modules/",
+    "!home/code/scripts-bundle.js",
+    "!home/code/scripts-bundle.css"
   ],
   "scripts": {
     "host": "node host-runner.mjs",

package/scripts/check-package.js

@@ -41,4 +41,8 @@ for (const path of ['host-runner.mjs', 'package.host.json']) {
   if (!packageJson.files.includes(path)) throw new Error(`package.json files must include ${path}.`);
 }
 
+for (const path of ['!**/node_modules/', '!home/code/scripts-bundle.js', '!home/code/scripts-bundle.css']) {
+  if (!packageJson.files.includes(path)) throw new Error(`package.json files must include ${path}.`);
+}
+
 console.log('Package checks passed.');

package/tests/control.mjs

@@ -25,6 +25,25 @@ target["Labels"]["com.docker.compose.service"] = "rollup"
 assert "not allowed" in control.policy_error(source, target, "1000")
 source["Labels"].pop("nestbox.exec.targets")
 assert "no allowed" in control.policy_error(source, target, "1000")
+broker = control.HostBroker()
+headers = {"X-Nestbox-Runner-Pid": "123", "X-Nestbox-Runner-Platform": "test", "X-Nestbox-Runner-Host": "host"}
+broker.touch("runner-test-1234", headers)
+assert broker.status()["available"]
+job = {"jobId": "job-test", "type": "npm.run"}
+broker.enqueue(job)
+assert broker.next("runner-test-1234", headers, 1) == job
+broker.complete("runner-test-1234", "job-test", {"jobId": "job-test", "exitCode": 0, "stdout": "", "stderr": ""})
+assert broker.wait("job-test", 1)["exitCode"] == 0
+stale = control.HostBroker()
+stale.touch("runner-stale-1234", headers)
+stale.enqueue({"jobId": "job-stale", "type": "npm.run"})
+assert stale.next("runner-stale-1234", headers, 1)["jobId"] == "job-stale"
+control.HOST_HEARTBEAT_TTL = 0
+assert stale.wait("job-stale", 1)["interrupted"] is True
+pending = control.HostBroker()
+pending.touch("runner-pending-1234", headers)
+pending.enqueue({"jobId": "job-pending", "type": "npm.run"})
+assert pending.wait("job-pending", 1)["interrupted"] is True
 `;
 
 let result = spawnSync(python, ['-c', policyTest], {

package/tests/creator.mjs

@@ -19,7 +19,8 @@ try {
   if (nestedPackage.name !== 'existing' || nestedPackage.scripts.build !== 'node build.mjs') throw new Error('Creator replaced existing package metadata.');
   if (nestedPackage.scripts.host !== 'node .nestbox/host-runner.mjs') throw new Error('Nested host script has the wrong path.');
   const nestedEnv = await readFile(join(nested, '.nestbox', '.env'), 'utf8');
-  if (!/^WORKSPACE_PATH=\.\.$/m.test(nestedEnv) || !/^NESTBOX_HOST_QUEUE_PATH=.+$/m.test(nestedEnv)) throw new Error('Nested runtime paths were not configured.');
+  const tokenPath = nestedEnv.match(/^NESTBOX_HOST_TOKEN_FILE=(.+)$/m)?.[1]?.trim();
+  if (!/^WORKSPACE_PATH=\.\.$/m.test(nestedEnv) || !tokenPath || !/^[a-f0-9]{64}$/.test((await readFile(tokenPath, 'utf8')).trim())) throw new Error('Nested runtime authentication was not configured.');
   const npmCommand = process.env.npm_execpath ? process.execPath : (process.platform === 'win32' ? 'npm.cmd' : 'npm');
   const npmArgs = process.env.npm_execpath ? [process.env.npm_execpath, 'run', 'test:host'] : ['run', 'test:host'];
   const nestedHostTest = spawnSync(npmCommand, npmArgs, { cwd: nested, encoding: 'utf8' });