@p10i/create-nestbox 0.1.2 → 0.2.0

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

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+'use strict';
+
+const baseUrl = (process.env.NESTBOX_CONTROL_URL || 'http://control:4088').replace(/\/$/, '');
+const timeoutMs = Number(process.env.NESTBOX_CONTROL_TIMEOUT_MS || '30000');
+const tools = [
+  { name: 'docker_exec', description: 'Run a command in an allowed Compose service.', inputSchema: { type: 'object', properties: { machine: { type: 'string' }, workdir: { type: 'string' }, command: { type: 'array', items: { type: 'string' } }, user: { type: 'string' }, detach: { type: 'boolean' } }, required: ['machine', 'workdir', 'command'], additionalProperties: false } },
+  { name: 'npm_scripts', description: 'List host npm scripts from /workspace/package.json.', inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
+  { name: 'npm_run', description: 'Run an allowed npm script through the active host bridge.', inputSchema: { type: 'object', properties: { script: { type: 'string' }, args: { type: 'array', items: { type: 'string' } }, detach: { type: 'boolean' } }, required: ['script'], additionalProperties: false } },
+  { name: 'npm_script_change_request', description: 'Request an add, edit, or delete of an npm script. The confirmation code is displayed only by the host runner.', inputSchema: { type: 'object', properties: { operation: { type: 'string', enum: ['add', 'edit', 'delete'] }, name: { type: 'string' }, command: { type: 'string' } }, required: ['operation', 'name'], additionalProperties: false } },
+  { name: 'npm_script_change_confirm', description: 'Confirm a pending npm script change with the host-visible code.', inputSchema: { type: 'object', properties: { requestId: { type: 'string' }, code: { type: 'string' } }, required: ['requestId', 'code'], additionalProperties: false } },
+];
+
+function request(method, path, body) {
+  const url = new URL(baseUrl + path);
+  const transport = require(url.protocol === 'https:' ? 'https' : 'http');
+  const payload = body === undefined ? undefined : JSON.stringify(body);
+  return new Promise((resolve, reject) => {
+    const headers = { accept: 'application/json' };
+    if (payload !== undefined) Object.assign(headers, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) });
+    const client = transport.request({ method, hostname: url.hostname, port: url.port || undefined, path: url.pathname + url.search, headers }, response => {
+      const chunks = [];
+      response.setEncoding('utf8');
+      response.on('data', chunk => chunks.push(chunk));
+      response.on('end', () => {
+        const text = chunks.join('');
+        let value = null;
+        try { value = text ? JSON.parse(text) : null; } catch { value = text; }
+        if (response.statusCode >= 400) reject(new Error(`Control API ${method} ${path} returned ${response.statusCode}: ${JSON.stringify(value)}`));
+        else resolve(value);
+      });
+    });
+    client.setTimeout(timeoutMs, () => client.destroy(new Error('Control API request timed out')));
+    client.on('error', reject);
+    if (payload !== undefined) client.write(payload);
+    client.end();
+  });
+}
+
+function object(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Tool arguments must be an object.');
+  return value;
+}
+
+async function call(name, raw) {
+  const args = object(raw || {});
+  if (name === 'docker_exec') {
+    if (typeof args.machine !== 'string' || !args.machine) throw new Error('machine must be a non-empty string.');
+    if (typeof args.workdir !== 'string' || !args.workdir.startsWith('/')) throw new Error('workdir must be an absolute path.');
+    if (!Array.isArray(args.command) || !args.command.length || !args.command.every(value => typeof value === 'string')) throw new Error('command must be a non-empty string array.');
+    const body = { command: args.command, workdir: args.workdir };
+    if (args.user) body.user = String(args.user);
+    if (args.detach !== undefined) body.detach = Boolean(args.detach);
+    return { machine: args.machine, workdir: args.workdir, command: args.command, result: await request('POST', `/containers/${encodeURIComponent(args.machine)}/exec`, body) };
+  }
+  if (name === 'npm_scripts') return request('GET', '/npm/scripts');
+  if (name === 'npm_run') {
+    if (typeof args.script !== 'string' || !args.script) throw new Error('script must be a non-empty string.');
+    if (args.args !== undefined && (!Array.isArray(args.args) || !args.args.every(value => typeof value === 'string'))) throw new Error('args must be a string array.');
+    return request('POST', '/npm/run', { script: args.script, ...(args.args === undefined ? {} : { args: args.args }), ...(args.detach === undefined ? {} : { detach: Boolean(args.detach) }) });
+  }
+  if (name === 'npm_script_change_request') {
+    if (!['add', 'edit', 'delete'].includes(args.operation) || typeof args.name !== 'string' || !args.name) throw new Error('operation and name are required.');
+    if (args.operation !== 'delete' && (typeof args.command !== 'string' || !args.command)) throw new Error('command is required for add and edit.');
+    if (args.operation === 'delete' && args.command !== undefined) throw new Error('command must be omitted for delete.');
+    return request('POST', '/npm/scripts/request', { operation: args.operation, name: args.name, ...(args.command === undefined ? {} : { command: args.command }) });
+  }
+  if (name === 'npm_script_change_confirm') {
+    if (typeof args.requestId !== 'string' || typeof args.code !== 'string') throw new Error('requestId and code are required.');
+    return request('POST', '/npm/scripts/confirm', { requestId: args.requestId, code: args.code });
+  }
+  throw new Error(`Unknown tool: ${name}`);
+}
+
+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 === 'initialized') return;
+  if (message.method === 'tools/list') return emit({ jsonrpc: '2.0', id: message.id, result: { tools } });
+  if (message.method === 'tools/call') {
+    try {
+      const output = await call(message.params?.name, message.params?.arguments);
+      emit({ jsonrpc: '2.0', id: message.id, result: { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] } });
+    } catch (error) {
+      emit({ jsonrpc: '2.0', id: message.id, error: { code: -32603, message: error.message || 'Tool execution failed.' } });
+    }
+    return;
+  }
+  if (message.id !== undefined) emit({ jsonrpc: '2.0', id: message.id, error: { code: -32601, message: `Method not supported: ${message.method}` } });
+}
+
+let input = '';
+process.stdin.on('data', chunk => {
+  input += chunk.toString('utf8');
+  let boundary;
+  while ((boundary = input.indexOf('\n')) >= 0) {
+    const line = input.slice(0, boundary).replace(/\r$/, ''); input = input.slice(boundary + 1);
+    if (!line) continue;
+    try { Promise.resolve(handle(JSON.parse(line))).catch(error => emit({ jsonrpc: '2.0', id: null, error: { code: -32603, message: error.message } })); }
+    catch (error) { emit({ jsonrpc: '2.0', id: null, error: { code: -32700, message: error.message } }); }
+  }
+});

package/home/configs/opencode/instructions.md

@@ -168,6 +168,20 @@ The interactive 404 page demonstrates the intended flow: create a session scoped
 
 Use API-created sessions only for explicit page workflows. The shared header's Open Chat link remains the normal entry point for conversation.
 
+## Container Control API
+
+OpenCode has no Docker socket. Use the control MCP as the only path for commands in other containers or on the native host:
+
+- `docker_exec` accepts an allowed Compose `machine`, absolute `workdir`, positional `command` array, and optional `user` or `detach` value.
+- `npm_scripts` lists scripts from `/workspace/package.json`.
+- `npm_run` executes one declared script through the active native host runner. Prefer `detach: true` for work expected to exceed the MCP request timeout.
+- `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.
+
+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.
+
 ## Git And Commit Policy
 
 - Resolve the owning Git root before staging any path.
@@ -182,12 +196,13 @@ Use API-created sessions only for explicit page workflows. The shared header's O
 
 ## Container Architecture
 
-The default Compose application has four services:
+The default Compose application has five services:
 
 - `nginx`: the only host-published gateway. It serves static page files, routes super-documents to PHP-FPM, proxies the OpenCode virtual host, and hosts Nchan.
 - `php-fpm`: executes HTTP and CLI directions. It mounts the page tree and workspace writable because trusted pages may intentionally modify them.
 - `rollup`: watches `scripts.js` and browser dependencies and writes local JS/CSS bundles into the page tree.
 - `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.
 
@@ -214,6 +229,7 @@ The engine's untracked `/nestbox/.env` controls runtime paths, exposure, authent
 - `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.
+- `NESTBOX_CONTROL_URL`: internal control API URL, normally `http://control:4088`.
 - `OPENCODE_SERVER_USERNAME` and `OPENCODE_SERVER_PASSWORD`: OpenCode HTTP authentication shared with PHP's internal API client.
 
 Nginx publishes one host port and distinguishes two browser origins:
@@ -271,13 +287,13 @@ Mount every directory needed by both PHP and OpenCode at the same container path
 
 ## Container Boundary And Host Handoff
 
-This OpenCode container deliberately has no Docker socket and may not be able to run Docker CLI commands. Never claim to build, pull, start, stop, restart, recreate, inspect, or remove host containers from this session.
+This OpenCode container deliberately has no Docker socket. Use control MCP only for its declared, label-gated operations. Never claim a broader Docker or operating-system capability.
 
 You may edit Compose files, Dockerfiles, Nginx configuration, PHP configuration, dependency files, mount definitions, and OpenCode configuration. After an infrastructure edit:
 
 1. Validate every part that can be checked inside this container.
 2. Identify the exact affected services.
-3. Give the user the narrowest host-side command to run from the engine directory.
+3. Use a declared host npm script through MCP when one exists; otherwise give the user the narrowest host-side command.
 4. State that activation and host health checks remain pending.
 5. Tell the user to reconnect if OpenCode itself must restart.
 

package/home/configs/opencode/opencode.json

@@ -5,6 +5,17 @@
     "port": 4096
   },
   "instructions": ["instructions.md", "instance.md"],
+  "mcp": {
+    "control": {
+      "type": "local",
+      "command": ["node", "/etc/opencode/control-mcp.js"],
+      "enabled": true,
+      "environment": {
+        "NESTBOX_CONTROL_URL": "{env:NESTBOX_CONTROL_URL}",
+        "NESTBOX_CONTROL_TIMEOUT_MS": "30000"
+      }
+    }
+  },
   "permission": {
     "external_directory": {
       "*": "ask",

package/host-runner.mjs

@@ -0,0 +1,301 @@
+import { spawn } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { hostname, platform } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mkdir, open, readFile, readdir, rename, stat, 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 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 once = process.argv.slice(2).includes('--once');
+const jsonOutput = process.argv.slice(2).includes('--json');
+const npmExecutable = process.env.NESTBOX_HOST_NPM || 'npm';
+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);
+const maximumPendingApprovals = Number(process.env.NESTBOX_HOST_APPROVAL_MAX_PENDING || 20);
+const hostPlatform = platform();
+const hostName = hostname();
+const approvals = new Map();
+const activeChildren = new Set();
+let heartbeatTimer;
+
+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}`);
+  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}`);
+    console.log(`Confirmation code: ${event.code} (expires ${event.expiresAt})\n`);
+  } else if (type === 'npm.scripts.changed') console.log(`Approved ${event.operation} for npm script "${event.name}".`);
+  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');
+  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);
+  }
+}
+
+async function packageDocument() {
+  const document = JSON.parse(await readFile(join(workspace, 'package.json'), 'utf8'));
+  if (!document || typeof document !== 'object' || Array.isArray(document)) throw new Error('package.json must contain a JSON object.');
+  return document;
+}
+
+async function packageHash() {
+  const contents = await readFile(join(workspace, 'package.json'));
+  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.');
+  }
+  return document.scripts;
+}
+
+async function writePackageJson(document, expectedHash) {
+  const path = join(workspace, 'package.json');
+  const temporary = `${path}.${instanceId}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(document, null, 2)}\n`, 'utf8');
+  if (expectedHash && await packageHash() !== 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) {
+    if (process.platform !== 'win32' || !['EEXIST', 'EPERM'].includes(error?.code)) throw error;
+    const backup = `${path}.${instanceId}.backup`;
+    await rename(path, backup);
+    try {
+      await rename(temporary, path);
+      await unlink(backup);
+    } catch (replaceError) {
+      await rename(backup, path).catch(() => {});
+      throw replaceError;
+    }
+  }
+}
+
+function validateScriptChange(job, scripts) {
+  if (!['add', 'edit', 'delete'].includes(job.operation)) throw new Error('Unsupported npm script operation.');
+  if (typeof job.name !== 'string' || !/^[A-Za-z0-9:_@./ -]{1,128}$/.test(job.name)) throw new Error('Invalid npm script name.');
+  if (job.name === 'host') throw new Error('The core host script cannot be changed.');
+  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' && job.command !== undefined) throw new Error('Delete does not accept a command.');
+}
+
+function pruneApprovals() {
+  const now = Date.now();
+  for (const [requestId, approval] of approvals) if (approval.expiresAtMs <= now) approvals.delete(requestId);
+}
+
+async function requestScriptChange(job) {
+  if (typeof job.requestId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$/.test(job.requestId)) throw new Error('A valid request ID is required.');
+  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();
+  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,
+  });
+  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 (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.');
+  }
+  validateScriptChange(approval, scripts);
+  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);
+  emit('npm.scripts.changed', approval);
+  return { jobId: job.jobId, status: 'success', requestId: approval.requestId, operation: approval.operation, name: approval.name };
+}
+
+function appendLimited(chunks, chunk, state) {
+  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;
+}
+
+async function runNpm(job) {
+  const scripts = await packageScripts();
+  if (typeof job.script !== 'string' || !Array.isArray(job.args) || !job.args.every(value => typeof value === 'string')) throw new Error('Invalid host npm 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 startedAt = new Date().toISOString();
+  return await 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); });
+  });
+}
+
+async function execute(job) {
+  if (job?.schemaVersion !== 1 || typeof job?.jobId !== 'string') throw new Error('Unsupported host job schema.');
+  if (job.type === 'npm.scripts.request') return requestScriptChange(job);
+  if (job.type === 'npm.scripts.confirm') return confirmScriptChange(job);
+  if (job.type === 'npm.run') return runNpm(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);
+  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();
+    }
+  })));
+  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;
+    try {
+      takeover = await open(takeoverPath, 'wx');
+      await takeover.writeFile(`${instanceId}\n`);
+    } catch {
+      throw new Error('Another host runner is recovering the stale lock.');
+    }
+    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();
+}
+
+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)); });

package/package.host.json

@@ -0,0 +1,8 @@
+{
+  "name": "nestbox-workspace",
+  "private": true,
+  "scripts": {
+    "host": "node .nestbox/host-runner.mjs",
+    "test:host": "node .nestbox/tests/host-runner.mjs"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@p10i/create-nestbox",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Create Nestbox projects.",
   "license": "MIT",
   "type": "module",
@@ -11,8 +11,12 @@
     "bin/",
     "scripts/",
     "docker/",
+    "!docker/control/__pycache__/",
+    "!**/*.pyc",
     "home/",
     "tests/",
+    "host-runner.mjs",
+    "package.host.json",
     "docker-compose.yaml",
     ".dockerignore",
     ".env.example",
@@ -20,9 +24,13 @@
     "template.gitignore",
     "INSTALL.md",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
+    "host": "node host-runner.mjs",
+    "test:host": "node tests/host-runner.mjs",
+    "test": "node tests/control.mjs && node tests/host-runner.mjs && node tests/creator.mjs",
     "prepack": "node scripts/check-package.js"
   },
   "engines": {

package/scripts/check-package.js

@@ -9,10 +9,19 @@ const requiredPaths = [
   'docker/php-fpm/Dockerfile',
   'docker/opencode/Dockerfile',
   'docker/rollup/Dockerfile',
+  'docker/control/Dockerfile',
+  'docker/control/server.py',
+  'host-runner.mjs',
+  'package.host.json',
+  'CHANGELOG.md',
+  'home/configs/opencode/control-mcp.js',
   'home/configs/opencode/instance.example.md',
   'home/code/404.php',
   'tests/nestbox.sh',
-  'tests/nestbox.ps1'
+  'tests/nestbox.ps1',
+  'tests/control.mjs',
+  'tests/host-runner.mjs',
+  'tests/creator.mjs'
 ];
 
 for (const path of requiredPaths) {
@@ -28,4 +37,8 @@ if (!packageJson.files || packageJson.files.includes('.env')) {
   throw new Error('package.json files must not include .env.');
 }
 
+for (const path of ['host-runner.mjs', 'package.host.json']) {
+  if (!packageJson.files.includes(path)) throw new Error(`package.json files must include ${path}.`);
+}
+
 console.log('Package checks passed.');

package/template.gitignore

@@ -6,6 +6,7 @@
 .vscode/
 node_modules/
 vendor/
+.runtime/
 
 # Generated by the Rollup watcher.
 home/code/scripts-bundle.js

package/tests/control.mjs

@@ -0,0 +1,51 @@
+import { spawnSync } from 'node:child_process';
+import { resolve } from 'node:path';
+
+const python = process.env.PYTHON || (process.platform === 'win32' ? 'python' : 'python3');
+const server = resolve('docker/control/server.py');
+const policyTest = String.raw`
+import importlib.util
+spec = importlib.util.spec_from_file_location("control", r"${server}")
+control = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(control)
+assert control.is_root_user("root")
+assert control.is_root_user("root:root")
+assert control.is_root_user("0:0")
+assert control.is_root_user("00:0")
+assert control.is_root_user("+0")
+assert not control.is_root_user("1000:1000")
+source = {"Labels": {"com.docker.compose.service": "opencode", "nestbox.exec.allow-source": "true", "nestbox.exec.targets": "php-fpm"}}
+target = {"Id": "abc", "Names": ["/project-php-fpm-1"], "Labels": {"com.docker.compose.service": "php-fpm", "nestbox.exec.allow-target": "true"}}
+assert control.policy_error(source, target, "1000") == ""
+assert "root" in control.policy_error(source, target, "0:0")
+assert "named user" in control.policy_error(source, target, "root-alias", "nestbox")
+target["Labels"]["nestbox.exec.allow-root"] = "true"
+assert control.policy_error(source, target, "root:root") == ""
+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")
+`;
+
+let result = spawnSync(python, ['-c', policyTest], {
+  encoding: 'utf8',
+  env: { ...process.env, COMPOSE_PROJECT_NAME: 'nestbox-test', PYTHONDONTWRITEBYTECODE: '1' },
+});
+if (result.status !== 0) throw new Error(`Control policy test failed: ${result.stderr || result.stdout}`);
+
+result = spawnSync(python, [server], { encoding: 'utf8', env: { ...process.env, COMPOSE_PROJECT_NAME: '', PYTHONDONTWRITEBYTECODE: '1' } });
+if (result.status === 0 || !result.stderr.includes('COMPOSE_PROJECT_NAME')) throw new Error('Control did not fail closed without a project name.');
+
+const messages = [
+  { jsonrpc: '2.0', id: 1, method: 'initialize', params: {} },
+  { jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} },
+].map(value => JSON.stringify(value)).join('\n') + '\n';
+result = spawnSync(process.execPath, [resolve('home/configs/opencode/control-mcp.js')], { input: messages, encoding: 'utf8' });
+if (result.status !== 0) throw new Error(`Control MCP test failed: ${result.stderr}`);
+const responses = result.stdout.trim().split(/\r?\n/).map(line => JSON.parse(line));
+const names = responses.find(value => value.id === 2)?.result?.tools?.map(tool => tool.name) || [];
+for (const name of ['docker_exec', 'npm_scripts', 'npm_run', 'npm_script_change_request', 'npm_script_change_confirm']) {
+  if (!names.includes(name)) throw new Error(`Control MCP does not expose ${name}.`);
+}
+
+console.log('Control tests passed.');