firedrill-run 2.2.5 → 3.0.1

package/dist/cli/src/native/supervisor.js

@@ -0,0 +1,831 @@
+/**
+ * Native process supervisor (Plan20 W09).
+ *
+ * Starts the services of an approved local plan as native trusted processes,
+ * in descriptor startup order, with argv only (`shell: false`), a minimal
+ * constructed environment, loopback readiness checks and bounded redacted
+ * output. This is process supervision, not an OS sandbox: approved processes
+ * run with the user's permissions.
+ *
+ * Ownership rules:
+ *  - Only processes this supervisor spawned are ever signalled, and only while
+ *    their leader is still a live child of this process.
+ *  - On POSIX each launched service is its own process group (detached), and
+ *    stop signals the group: SIGTERM, wait, then SIGKILL.
+ *  - On Windows there are no process groups here: only the started pid is
+ *    tracked and stopped; its descendants may keep running (reported by
+ *    `limitations()`).
+ *  - Attached services are never signalled, and nothing is ever stopped by
+ *    name or by port.
+ *  - The service a jsonl-process.v1 driver speaks to is started and owned by
+ *    that driver (it needs the process's stdin/stdout), so it is skipped here.
+ */
+import { spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { request } from 'node:http';
+import { connect } from 'node:net';
+import { constants as osConstants } from 'node:os';
+import { StringDecoder } from 'node:string_decoder';
+import { CliError } from '../http.js';
+import { NATIVE_ID, nativeError } from './contracts.js';
+import { ENV_NAME, assertPlanApproved, loopbackUrl, processControlLimitations } from './plan.js';
+import { allocateLoopbackPort } from './ports.js';
+import { RedactingCapture } from './redaction.js';
+import { insideRoot } from './roots.js';
+import { ownGroup, sweepGroup } from './owned-groups.js';
+const POSIX_GROUPS = process.platform !== 'win32';
+const KILL_WAIT_MS = 5000;
+const PROBE_BODY_MAX_BYTES = 65_536;
+/** An exit code, or minus the signal number for a process ended by a signal; null when it has not ended (or ended unknowably). */
+export function exitCode(exit) {
+    if (!exit)
+        return null;
+    if (typeof exit.code === 'number' && Number.isSafeInteger(exit.code) && exit.code >= -255 && exit.code <= 255)
+        return exit.code;
+    const signals = osConstants.signals;
+    const number = exit.signal ? signals[exit.signal] : undefined;
+    return typeof number === 'number' && number > 0 && number <= 255 ? -number : null;
+}
+// ---------------------------------------------------------------------------
+// Bounded output ring.
+/** Keep the last `limit` UTF-8 bytes of appended text. */
+export class OutputRing {
+    #limit;
+    #chunks = [];
+    #bytes = 0;
+    constructor(limit) { this.#limit = Math.max(0, Math.floor(limit)); }
+    /** Append already-redacted text, dropping the oldest bytes beyond the limit. */
+    append(text) {
+        if (!text || !this.#limit)
+            return;
+        const size = Buffer.byteLength(text, 'utf8');
+        const kept = size > this.#limit ? tailBytes(text, this.#limit) : text;
+        this.#chunks.push(kept);
+        this.#bytes += Buffer.byteLength(kept, 'utf8');
+        while (this.#bytes > this.#limit && this.#chunks.length) {
+            const first = this.#chunks[0];
+            const firstBytes = Buffer.byteLength(first, 'utf8');
+            const excess = this.#bytes - this.#limit;
+            if (excess >= firstBytes) {
+                this.#chunks.shift();
+                this.#bytes -= firstBytes;
+                continue;
+            }
+            const trimmed = tailBytes(first, firstBytes - excess);
+            this.#chunks[0] = trimmed;
+            this.#bytes += Buffer.byteLength(trimmed, 'utf8') - firstBytes;
+        }
+    }
+    /** The retained tail. */
+    text() { return this.#chunks.join(''); }
+}
+function tailBytes(text, bytes) {
+    const buffer = Buffer.from(text, 'utf8');
+    let start = Math.max(0, buffer.length - bytes);
+    while (start < buffer.length && (buffer[start] & 0xc0) === 0x80)
+        start++;
+    return buffer.subarray(start).toString('utf8');
+}
+// ---------------------------------------------------------------------------
+// Environment construction.
+const BASE_POSIX = ['PATH', 'HOME', 'USER', 'LOGNAME', 'LANG', 'LC_ALL', 'LC_CTYPE', 'TMPDIR', 'TZ'];
+const BASE_WINDOWS = ['PATH', 'PATHEXT', 'SYSTEMROOT', 'SYSTEMDRIVE', 'WINDIR', 'TEMP', 'TMP', 'USERPROFILE',
+    'HOMEDRIVE', 'HOMEPATH', 'APPDATA', 'LOCALAPPDATA', 'PROGRAMDATA', 'USERNAME'];
+/**
+ * Build a child environment from empty: platform base names (PATH, HOME, LANG,
+ * TMPDIR and equivalents), then `env_passthrough` names present in the user
+ * environment, `env_static`, dependency ports, binding/identity env and the
+ * allocated port. Descriptor secret names not supplied by a binding are
+ * stripped, so live credentials are never inherited silently. Names are
+ * case-insensitive on Windows.
+ */
+export function buildServiceEnv(input) {
+    const platform = input.platform ?? process.platform;
+    const userEnv = input.userEnv ?? process.env;
+    const windows = platform === 'win32';
+    const keyOf = (name) => windows ? name.toUpperCase() : name;
+    const env = new Map();
+    const set = (name, value) => {
+        if (typeof value !== 'string' || value.includes('\0') || !ENV_NAME.test(name))
+            return;
+        env.set(keyOf(name), [name, value]);
+    };
+    const lookup = (name) => {
+        if (!windows)
+            return userEnv[name];
+        const key = Object.keys(userEnv).find(candidate => candidate.toUpperCase() === name.toUpperCase());
+        return key === undefined ? undefined : userEnv[key];
+    };
+    for (const name of windows ? BASE_WINDOWS : BASE_POSIX)
+        set(name, lookup(name));
+    for (const name of input.service.env_passthrough)
+        set(name, lookup(name));
+    for (const [name, value] of Object.entries(input.service.env_static))
+        set(name, value);
+    for (const [name, port] of input.dependencyPorts ?? [])
+        set(name, String(port));
+    const supplied = new Set();
+    for (const [name, value] of Object.entries(input.bindingEnv)) {
+        set(name, value);
+        supplied.add(keyOf(name));
+    }
+    if (input.service.port_env && input.port !== null)
+        set(input.service.port_env, String(input.port));
+    for (const name of input.secretNames)
+        if (!supplied.has(keyOf(name)))
+            env.delete(keyOf(name));
+    return Object.fromEntries([...env.values()]);
+}
+const startFailed = (label) => new CliError('native_process_start_failed', `The approved process for ${label} could not be started. Check that its executable exists and is runnable.`);
+/** A process this supervisor spawned and therefore may signal. */
+class NoProcessStarted extends CliError {
+    constructor() { super('native_process_start_failed', 'The operating system did not start the approved process.'); }
+}
+class OwnedProcess {
+    child;
+    pid;
+    group;
+    ring;
+    exited;
+    #exit = null;
+    #captures = [];
+    constructor(child, pid, ring, exited, captures) {
+        this.child = child;
+        this.pid = pid;
+        this.group = POSIX_GROUPS;
+        this.ring = ring;
+        this.exited = exited;
+        this.#captures.push(...captures);
+        void exited.then(exit => { this.#exit = exit; });
+    }
+    /** Spawn with argv only and wait for the OS to confirm the start. */
+    static async spawn(label, spec) {
+        let child;
+        try {
+            child = spawn(spec.executable, spec.args, {
+                cwd: spec.cwd, env: spec.env, shell: false, detached: POSIX_GROUPS, windowsHide: true,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+        }
+        catch {
+            throw new NoProcessStarted();
+        }
+        let spawnObserved = false;
+        child.once('spawn', () => { spawnObserved = true; });
+        // Errors after start (for example a failed signal) must not crash the companion.
+        child.on('error', () => undefined);
+        const ring = new OutputRing(spec.outputBytes);
+        const captures = [];
+        let settleExit = () => undefined;
+        const exited = new Promise(resolve => { settleExit = resolve; });
+        if (POSIX_GROUPS)
+            child.once('spawn', () => ownGroup(child.pid));
+        child.once('exit', (code, signal) => {
+            // The service ended when its leader did, whether or not we asked it to.
+            // Members it left in its group are ours and would otherwise outlive the
+            // drill unseen, so they are swept now, while the group id is still ours.
+            if (POSIX_GROUPS)
+                sweepGroup(child.pid);
+            settleExit({ code, signal });
+        });
+        const capture = (stream, observe) => {
+            if (!stream)
+                return;
+            const decoder = new StringDecoder('utf8');
+            const redactor = new RedactingCapture(spec.secrets, text => ring.append(text));
+            captures.push(redactor);
+            stream.on('data', (chunk) => {
+                const text = decoder.write(chunk);
+                if (observe) {
+                    try {
+                        observe(text);
+                    }
+                    catch { /* observer errors never affect capture */ }
+                }
+                redactor.push(text);
+            });
+            stream.once('end', () => { redactor.push(decoder.end()); redactor.flush(); });
+            stream.on('error', () => undefined);
+        };
+        capture(child.stdout, spec.onStdout);
+        capture(child.stderr);
+        try {
+            await new Promise((resolve, reject) => {
+                child.once('spawn', () => resolve());
+                child.once('error', reject);
+            });
+        }
+        catch {
+            settleExit({ code: null, signal: null });
+            if (!spawnObserved && typeof child.pid !== 'number')
+                throw new NoProcessStarted();
+            throw startFailed(label);
+        }
+        if (typeof child.pid !== 'number') {
+            settleExit({ code: null, signal: null });
+            throw startFailed(label);
+        }
+        return new OwnedProcess(child, child.pid, ring, exited, captures);
+    }
+    /** True while the leader has not exited (its pid is still ours). */
+    get alive() { return this.#exit === null && this.child.exitCode === null && this.child.signalCode === null; }
+    get exit() { return this.#exit; }
+    /** Signal the owned group (POSIX) or the owned pid (Windows), only while the leader is alive. */
+    signal(signal) {
+        if (!this.alive || this.child.pid !== this.pid)
+            return;
+        if (this.group) {
+            try {
+                process.kill(-this.pid, signal);
+                return;
+            }
+            catch { /* fall back to the leader itself */ }
+        }
+        try {
+            this.child.kill(signal);
+        }
+        catch { /* already gone */ }
+    }
+    /** Resolve true if the leader exits within `ms`. */
+    async waitExit(ms) {
+        if (!this.alive)
+            return true;
+        let timer;
+        const timeout = new Promise(resolve => { timer = setTimeout(() => resolve(false), Math.max(0, ms)); });
+        try {
+            return await Promise.race([this.exited.then(() => true), timeout]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** SIGTERM, wait `graceMs`, then SIGKILL while still owned. Releases pipes afterwards. */
+    async terminate(graceMs) {
+        if (this.alive) {
+            this.signal('SIGTERM');
+            if (!(await this.waitExit(graceMs))) {
+                this.signal('SIGKILL');
+                await this.waitExit(KILL_WAIT_MS);
+            }
+            // The exit handler normally swept this group already. Never signal its
+            // numeric id again after ownership has been removed from the registry.
+            if (this.group && !this.alive)
+                sweepGroup(this.pid);
+        }
+        for (const capture of this.#captures)
+            capture.flush();
+        // Descendants may hold pipes open; never let them keep the companion alive.
+        for (const stream of [this.child.stdout, this.child.stderr]) {
+            try {
+                stream?.destroy();
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Readiness.
+function sleep(ms, signal, exited) {
+    return new Promise(resolve => {
+        const timer = setTimeout(done, ms);
+        function done() { clearTimeout(timer); signal.removeEventListener('abort', done); resolve(); }
+        signal.addEventListener('abort', done, { once: true });
+        void exited?.then(done);
+    });
+}
+/** The accepted status code and body digest, or null when the check did not pass. */
+function probeHttp(url, expect, timeoutMs) {
+    return new Promise(resolve => {
+        let settled = false;
+        const finish = (result) => { if (!settled) {
+            settled = true;
+            resolve(result);
+        } };
+        try {
+            const req = request({
+                host: url.hostname.replace(/^\[|\]$/g, ''), port: Number(url.port), path: `${url.pathname}${url.search}`,
+                method: 'GET', agent: false, timeout: timeoutMs, headers: { accept: '*/*' },
+            }, response => {
+                const status = response.statusCode ?? 0;
+                if (!expect.includes(status)) {
+                    finish(null);
+                    response.resume();
+                    response.destroy();
+                    return;
+                }
+                const hash = createHash('sha256');
+                let size = 0;
+                const done = () => { if (!settled)
+                    finish({ status, body_sha256: hash.digest('hex') }); };
+                response.on('data', (chunk) => {
+                    if (settled)
+                        return;
+                    size += chunk.length;
+                    // Too large to attest exactly: the check still passed, with no body digest.
+                    if (size > PROBE_BODY_MAX_BYTES) {
+                        finish({ status, body_sha256: null });
+                        response.destroy();
+                        return;
+                    }
+                    hash.update(chunk);
+                });
+                response.once('end', done);
+                response.once('error', () => finish(null));
+            });
+            req.once('timeout', () => { req.destroy(); finish(null); });
+            req.once('error', () => finish(null));
+            req.end();
+        }
+        catch {
+            finish(null);
+        }
+    });
+}
+function probeTcp(port, timeoutMs) {
+    return new Promise(resolve => {
+        let settled = false;
+        const socket = connect({ host: '127.0.0.1', port });
+        const finish = (ready) => { if (!settled) {
+            settled = true;
+            socket.destroy();
+            resolve(ready);
+        } };
+        socket.setTimeout(timeoutMs, () => finish(false));
+        socket.once('connect', () => finish(true));
+        socket.once('error', () => finish(false));
+    });
+}
+/** Wait for readiness within the service bound and return what passed; early exit fails with `native_process_exited`. */
+async function waitReady(target, signal) {
+    const { readiness } = target.service;
+    const deadline = Date.now() + target.service.readiness_timeout_ms;
+    let delay = 100;
+    while (true) {
+        signal.throwIfAborted();
+        if (target.process && !target.process.alive) {
+            throw nativeError('process_exited', `Service ${target.alias} exited before it became ready.`);
+        }
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            break;
+        const attempt = Math.max(100, Math.min(2000, remaining));
+        let ready = null;
+        if (readiness.kind === 'none')
+            ready = { kind: 'none' };
+        else if (readiness.kind === 'stdout')
+            ready = target.stdoutSeen() ? { kind: 'stdout' } : null;
+        else if (readiness.kind === 'http' && target.url) {
+            const probed = await probeHttp(target.url, readiness.expect_status, attempt);
+            ready = probed === null ? null : { kind: 'http', status_code: probed.status, body_sha256: probed.body_sha256 };
+        }
+        else if (readiness.kind === 'tcp' && target.port)
+            ready = await probeTcp(target.port, attempt) ? { kind: 'tcp' } : null;
+        if (ready) {
+            if (target.process && !target.process.alive) {
+                throw nativeError('process_exited', `Service ${target.alias} exited before it became ready.`);
+            }
+            return ready;
+        }
+        await sleep(Math.min(delay, Math.max(0, deadline - Date.now())), signal, target.process?.exited ?? null);
+        delay = Math.min(1000, delay * 2);
+    }
+    throw nativeError('readiness_timeout', `Service ${target.alias} did not become ready within its readiness timeout.`);
+}
+const canceled = () => new CliError('canceled', 'Service startup was canceled. Services started for it were stopped.', 130);
+const closedError = () => new CliError('native_supervisor_closed', 'Local services are shutting down. No new service was started.');
+/**
+ * Starts, tracks and stops the services of one approved plan for a companion
+ * session. Shared services start once and are reused; per-drill services get
+ * one copy (and port) per drill key.
+ */
+export class Supervisor {
+    #plan;
+    #normalized;
+    #approval;
+    #roots;
+    #maxProcesses;
+    #outputBytes;
+    #services;
+    #secretNames;
+    #dependencies;
+    #driverOwnedAlias;
+    #entries = new Map();
+    #pending = new Map();
+    #byHandle = new WeakMap();
+    #order = [];
+    /** Per-drill processes launched for each drill key (ready or not), until the drill's close reads them. */
+    #drillLaunches = new Map();
+    #closing = new AbortController();
+    #runOwned;
+    #runLaunchId;
+    #beforeRunLaunch;
+    #captureRunObserved;
+    #runNotStarted;
+    /** The one launch of each run-owned service, kept after it stops so its end can be reported. */
+    #runLaunched = new Map();
+    #reserved = 0;
+    #stopAll = null;
+    #stopAllDone = false;
+    constructor(options) {
+        if (!Number.isSafeInteger(options.maxProcesses) || options.maxProcesses < 1 || options.maxProcesses > 1024
+            || !Number.isSafeInteger(options.outputBytes) || options.outputBytes < 0 || options.outputBytes > 64 * 1024 * 1024) {
+            throw new CliError('native_supervisor_invalid', 'The local process limits are not valid. Nothing was started.', 2);
+        }
+        assertPlanApproved(options.approval, options.plan, options.approval.plan_sha256);
+        this.#plan = options.plan;
+        this.#normalized = options.normalized;
+        this.#approval = options.approval;
+        this.#roots = options.roots;
+        this.#maxProcesses = options.maxProcesses;
+        this.#outputBytes = options.outputBytes;
+        this.#services = new Map(options.plan.services.map(service => [service.alias, service]));
+        this.#secretNames = new Map(options.normalized.descriptor.services.map(service => [service.alias, new Set(service.configuration.filter(item => item.secret).map(item => item.name))]));
+        this.#dependencies = new Map(options.normalized.descriptor.services.map(service => [service.alias, service.depends_on]));
+        this.#driverOwnedAlias = options.plan.driver.profile === 'jsonl-process.v1' ? options.plan.driver.service_alias : null;
+        this.#runOwned = options.runOwned ?? new Set();
+        this.#runLaunchId = options.runLaunchId ?? (() => null);
+        this.#beforeRunLaunch = options.beforeRunLaunch;
+        this.#captureRunObserved = options.captureRunObserved;
+        this.#runNotStarted = options.runNotStarted;
+        for (const alias of this.#runOwned) {
+            const service = this.#services.get(alias);
+            if (!service || service.mode !== 'launch' || service.per_drill || alias === this.#driverOwnedAlias) {
+                throw new CliError('native_supervisor_invalid', `Service ${alias} cannot belong to a campaign's local run. Nothing was started.`, 2);
+            }
+        }
+    }
+    /**
+     * Each run-owned service as observed now: never launched (`planned`), its one
+     * launch still running, or ended with a known exit (`reaped`). A launch whose
+     * end cannot be attested (still alive after every service was stopped, or an
+     * exit with neither code nor known signal) is `unknown`, never `reaped`.
+     */
+    runStates() {
+        const states = new Map();
+        for (const alias of this.#runOwned) {
+            const handle = this.#runLaunched.get(alias);
+            if (!handle) {
+                states.set(alias, { state: 'planned' });
+                continue;
+            }
+            const exit = handle.exit();
+            const code = exitCode(exit);
+            if (exit === null)
+                states.set(alias, this.#stopAllDone ? { state: 'unknown' } : { state: 'running' });
+            else
+                states.set(alias, code === null ? { state: 'unknown' } : { state: 'reaped', exit_code: code });
+        }
+        return states;
+    }
+    /** Known platform limitations of process control, for status output. */
+    limitations() {
+        return processControlLimitations();
+    }
+    /** Current services, without environment, argv or output. */
+    status() {
+        return this.#order.map(entry => ({
+            alias: entry.alias, mode: entry.handle.mode, drillKey: entry.drillKey, pid: entry.handle.pid, port: entry.handle.port,
+            running: entry.process ? entry.process.alive : entry.stopReason === null, stop_reason: entry.stopReason,
+            exit: entry.process?.exit ?? null,
+        }));
+    }
+    /**
+     * Start (or reuse) the named services and their dependencies in descriptor
+     * startup order, waiting for each to be ready. Returns handles in that order.
+     * The jsonl-process.v1 driver's own service is skipped (the driver starts it).
+     * On failure or cancellation, per-drill services started by this call are
+     * stopped before the error is rethrown.
+     */
+    async start(services, ctx) {
+        if (this.#stopAll)
+            throw closedError();
+        assertPlanApproved(this.#approval, this.#plan, this.#approval.plan_sha256);
+        if (typeof ctx.drillKey !== 'string' || !NATIVE_ID.test(ctx.drillKey)
+            || Object.entries(ctx.env).some(([name, value]) => !ENV_NAME.test(name) || typeof value !== 'string' || value.includes('\0'))) {
+            throw new CliError('native_start_invalid', 'The service start request is not valid. Nothing was started.', 2);
+        }
+        const wanted = new Set();
+        const visit = (alias) => {
+            if (wanted.has(alias))
+                return;
+            if (!this.#services.has(alias))
+                throw new CliError('native_start_invalid', 'A requested service is not part of the approved plan. Nothing was started.', 2);
+            wanted.add(alias);
+            for (const dependency of this.#dependencies.get(alias) ?? [])
+                visit(dependency);
+        };
+        for (const alias of services)
+            visit(alias);
+        const order = this.#normalized.startup_order.filter(alias => wanted.has(alias) && alias !== this.#driverOwnedAlias);
+        const signal = AbortSignal.any([ctx.signal, this.#closing.signal]);
+        const handles = new Map();
+        const createdHere = [];
+        try {
+            for (const alias of order) {
+                if (signal.aborted)
+                    throw this.#stopAll ? closedError() : canceled();
+                const entry = await this.#obtain(alias, ctx, signal, handles, createdHere);
+                handles.set(alias, entry.handle);
+            }
+        }
+        catch (error) {
+            for (const entry of createdHere.reverse()) {
+                if (entry.drillKey !== null)
+                    await this.#stopEntry(entry, 'start_failed').catch(() => undefined);
+            }
+            if (signal.aborted && !(error instanceof CliError && error.code !== 'canceled'))
+                throw this.#stopAll ? closedError() : canceled();
+            throw error;
+        }
+        return order.map(alias => handles.get(alias));
+    }
+    async #obtain(alias, ctx, signal, started, createdHere) {
+        const service = this.#services.get(alias);
+        const key = service.per_drill ? `${alias}\0${ctx.drillKey}` : alias;
+        const existing = this.#entries.get(key);
+        if (existing && existing.stopReason === null && (!existing.process || existing.process.alive))
+            return existing;
+        // A shared service that exited is released (pipes closed) and started afresh as a new handle.
+        if (existing)
+            await this.#stopEntry(existing, existing.stopReason ?? 'exited');
+        // A start already in flight is shared (for a run-owned service, that is its one launch).
+        const pending = this.#pending.get(key);
+        if (pending)
+            return pending;
+        // A run-owned service has one registered launch identity for the whole run: it is never started twice.
+        if (this.#runOwned.has(alias) && this.#runLaunched.has(alias)) {
+            throw new CliError('native_local_run_service_ended', `Shared service ${alias} ended, and this campaign's local run cannot start it again under its registered identity. No drill step was taken.`);
+        }
+        const promise = (service.mode === 'attach'
+            ? this.#attach(key, service, signal)
+            // A shared service outlives any one drill, so it never receives a drill's
+            // binding env or secrets, even when a drill's start (re)launches it.
+            : this.#launch(key, service, service.per_drill ? ctx : { ...ctx, env: {}, secrets: [] }, signal, started))
+            .then(entry => { createdHere.push(entry); return entry; });
+        this.#pending.set(key, promise);
+        try {
+            return await promise;
+        }
+        finally {
+            this.#pending.delete(key);
+        }
+    }
+    #fixedPort(service) {
+        const readiness = service.readiness;
+        if (readiness.kind === 'tcp' && readiness.port > 0)
+            return readiness.port;
+        if (readiness.kind === 'http') {
+            const url = loopbackUrl(readiness.url);
+            if (url && url.port && url.port !== '0')
+                return Number(url.port);
+        }
+        return null;
+    }
+    #readinessUrl(service, port) {
+        if (service.readiness.kind !== 'http')
+            return null;
+        const url = loopbackUrl(service.readiness.url);
+        if (!url)
+            return null;
+        if (url.port === '0' && port !== null)
+            url.port = String(port);
+        return url;
+    }
+    #register(entry) {
+        this.#entries.set(entry.key, entry);
+        this.#byHandle.set(entry.handle, entry);
+        this.#order.push(entry);
+    }
+    #forget(entry) {
+        if (this.#entries.get(entry.key) === entry)
+            this.#entries.delete(entry.key);
+        const index = this.#order.indexOf(entry);
+        if (index >= 0)
+            this.#order.splice(index, 1);
+    }
+    async #attach(key, service, signal) {
+        const port = this.#fixedPort(service);
+        const url = this.#readinessUrl(service, port);
+        let release = () => undefined;
+        const exited = new Promise(resolve => { release = resolve; });
+        let observed = null;
+        const handle = Object.freeze({
+            alias: service.alias, mode: 'attach', launchId: randomUUID(), drillKey: null, pid: null, port,
+            url: url ? `${url.protocol}//${url.host}` : port !== null ? `http://127.0.0.1:${port}` : null,
+            output: () => '', exited, exit: () => null, ready: () => observed,
+        });
+        // Readiness only: an attached service is never started, signalled or stopped here.
+        observed = await waitReady({ alias: service.alias, service, url, port, process: null, stdoutSeen: () => false }, signal);
+        const entry = { key, alias: service.alias, service, drillKey: null, handle, process: null, release, stopReason: null, stopping: null };
+        this.#register(entry);
+        return entry;
+    }
+    async #launch(key, service, ctx, signal, started) {
+        if (this.#reserved >= this.#maxProcesses) {
+            throw new CliError('native_process_limit', `The local process limit is reached, so service ${service.alias} was not started.`);
+        }
+        const runOwned = this.#runOwned.has(service.alias);
+        const registered = runOwned ? this.#runLaunchId(service.alias) : null;
+        if (runOwned && (typeof registered !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(registered))) {
+            throw new CliError('native_local_run_unregistered', `Shared service ${service.alias} was not started: this campaign's local run is not registered with the service yet.`);
+        }
+        this.#reserved++;
+        let reservedReleased = false;
+        const unreserve = () => { if (!reservedReleased) {
+            reservedReleased = true;
+            this.#reserved--;
+        } };
+        let owned = null;
+        let launchIntent = false;
+        let spawnCalled = false;
+        let registeredEntry = null;
+        try {
+            const command = service.command;
+            const root = this.#roots.get(service.root_alias);
+            if (!command || !root)
+                throw new CliError('native_start_invalid', `Service ${service.alias} has no approved command or root in this session.`, 2);
+            const cwd = await insideRoot(root, service.cwd);
+            const port = service.port_env ? await allocateLoopbackPort(signal) : this.#fixedPort(service);
+            const dependencyPorts = [];
+            for (const dependency of this.#dependencies.get(service.alias) ?? []) {
+                const handle = started.get(dependency), plan = this.#services.get(dependency);
+                if (handle?.port && plan?.port_env)
+                    dependencyPorts.push([plan.port_env, handle.port]);
+            }
+            const env = buildServiceEnv({
+                service, secretNames: this.#secretNames.get(service.alias) ?? new Set(), bindingEnv: ctx.env, port, dependencyPorts,
+            });
+            const pattern = service.readiness.kind === 'stdout' ? service.readiness.pattern : null;
+            let window = '', seen = false;
+            const onStdout = pattern === null ? undefined : (text) => {
+                if (seen)
+                    return;
+                window = (window + text).slice(-(pattern.length + 65_536));
+                if (window.includes(pattern))
+                    seen = true;
+                else
+                    window = window.slice(-(pattern.length - 1 || 1));
+            };
+            signal.throwIfAborted();
+            if (runOwned) {
+                if (!this.#beforeRunLaunch || !this.#captureRunObserved || !this.#runNotStarted)
+                    throw new CliError('native_local_run_unregistered', 'Shared services require a durable original launch journal. Nothing was started.');
+                await this.#beforeRunLaunch(service.alias);
+                launchIntent = true;
+                signal.throwIfAborted();
+            }
+            spawnCalled = true;
+            owned = await OwnedProcess.spawn(`service ${service.alias}`, {
+                executable: command.executable, args: command.args, cwd, env, outputBytes: this.#outputBytes,
+                secrets: ctx.secrets, onStdout,
+            });
+            const proc = owned;
+            void proc.exited.then(unreserve);
+            const url = this.#readinessUrl(service, port);
+            let observed = null;
+            const handle = Object.freeze({
+                alias: service.alias, mode: 'launch', launchId: registered ?? randomUUID(), drillKey: service.per_drill ? ctx.drillKey : null,
+                pid: proc.pid, port,
+                url: url ? `${url.protocol}//${url.host}` : port !== null ? `http://127.0.0.1:${port}` : null,
+                output: () => proc.ring.text(), exited: proc.exited, exit: () => proc.exit, ready: () => observed,
+            });
+            // Spawned: from now on this run-owned launch is reported until the session ends, ready or not.
+            if (runOwned)
+                this.#runLaunched.set(service.alias, handle);
+            const entry = {
+                key, alias: service.alias, service, drillKey: handle.drillKey, handle, process: proc, release: () => undefined, stopReason: null, stopping: null,
+            };
+            this.#register(entry);
+            registeredEntry = entry;
+            if (runOwned) {
+                void proc.exited.then(() => this.#captureRunObserved?.()).catch(() => undefined);
+                await this.#captureRunObserved?.();
+            }
+            // Logged before readiness: a per-drill process that never became ready was still launched and is reaped below.
+            if (handle.drillKey !== null)
+                this.#drillLaunches.set(handle.drillKey, [...(this.#drillLaunches.get(handle.drillKey) ?? []), handle]);
+            try {
+                if (this.#stopAll)
+                    throw closedError();
+                observed = await waitReady({ alias: service.alias, service, url, port, process: proc, stdoutSeen: () => seen }, signal);
+                if (this.#stopAll)
+                    throw closedError();
+            }
+            catch (error) {
+                await this.#stopEntry(entry, 'readiness_failed');
+                throw error;
+            }
+            return entry;
+        }
+        catch (error) {
+            if (!owned) {
+                unreserve();
+                if (runOwned && launchIntent && (!spawnCalled || error instanceof NoProcessStarted)) {
+                    await this.#runNotStarted?.(service.alias);
+                }
+            }
+            else {
+                if (registeredEntry)
+                    await this.#stopEntry(registeredEntry, 'launch_failed');
+                else
+                    await owned.terminate(service.stop_timeout_ms);
+                if (runOwned)
+                    await this.#captureRunObserved?.().catch(() => undefined);
+            }
+            throw error;
+        }
+    }
+    async #stopEntry(entry, reason) {
+        if (entry.stopping)
+            return entry.stopping;
+        entry.stopReason ??= reason;
+        entry.stopping = (async () => {
+            if (entry.process)
+                await entry.process.terminate(entry.service.stop_timeout_ms);
+            else
+                entry.release({ code: null, signal: null });
+            this.#forget(entry);
+        })();
+        return entry.stopping;
+    }
+    /**
+     * Stop one service. A launched service gets SIGTERM to its owned group, then
+     * SIGKILL after `stop_timeout_ms` if its leader is still alive. An attached
+     * service is only released (never signalled). Handles from another supervisor
+     * are ignored.
+     */
+    async stop(handle, reason) {
+        const entry = this.#byHandle.get(handle);
+        if (!entry)
+            return;
+        await this.#stopEntry(entry, typeof reason === 'string' && reason ? reason.slice(0, 64) : 'requested');
+    }
+    /**
+     * Every per-drill process launched for `drillKey`, including one stopped
+     * because it never became ready, in launch order; returned once, for the
+     * drill's signed close (call after stopDrill).
+     */
+    takeDrillLaunches(drillKey) {
+        const launches = this.#drillLaunches.get(drillKey) ?? [];
+        this.#drillLaunches.delete(drillKey);
+        return launches;
+    }
+    /** Stop every per-drill service of `drillKey`, in reverse start order. */
+    async stopDrill(drillKey, reason = 'drill_finished') {
+        for (const entry of [...this.#order].reverse()) {
+            if (entry.drillKey === drillKey)
+                await this.#stopEntry(entry, reason).catch(() => undefined);
+        }
+    }
+    /**
+     * Refuse new starts, cancel pending readiness waits and stop every service in
+     * reverse start order. Idempotent: repeated calls return the same promise, so
+     * signal handlers can call it once safely.
+     */
+    stopAll(reason = 'shutdown') {
+        this.#stopAll ??= (async () => {
+            this.#closing.abort();
+            await Promise.allSettled([...this.#pending.values()]);
+            for (const entry of [...this.#order].reverse())
+                await this.#stopEntry(entry, reason).catch(() => undefined);
+            this.#stopAllDone = true;
+        })();
+        return this.#stopAll;
+    }
+}
+/**
+ * Run one approved argv to completion as an owned process (own group on POSIX),
+ * with a constructed environment, a hard timeout and redacted bounded output.
+ * On timeout or abort the owned group gets SIGTERM, then SIGKILL after a short
+ * grace. A zero exit is reported evidence, not proof of any effect.
+ */
+export async function runOwnedCommand(input) {
+    input.signal.throwIfAborted();
+    if (/\.(?:bat|cmd)$/i.test(input.executable.trim()))
+        throw startFailed('the command');
+    const owned = await OwnedProcess.spawn('the command', {
+        executable: input.executable, args: input.args, cwd: input.cwd, env: input.env,
+        outputBytes: input.outputBytes, secrets: input.secrets,
+    });
+    let timedOut = false;
+    const stop = () => { void owned.terminate(2000); };
+    const timer = setTimeout(() => { timedOut = true; stop(); }, Math.max(1, input.timeoutMs));
+    input.signal.addEventListener('abort', stop, { once: true });
+    try {
+        const exit = await owned.exited;
+        // Let buffered output drain briefly before releasing the pipes.
+        if (owned.child.stdout && !owned.child.stdout.readableEnded) {
+            await new Promise(resolve => {
+                const timer = setTimeout(done, 500);
+                function done() { clearTimeout(timer); resolve(); }
+                owned.child.once('close', done);
+            });
+        }
+        await owned.terminate(0);
+        return { code: exit.code, signal: exit.signal, timed_out: timedOut, output: owned.ring.text() };
+    }
+    finally {
+        clearTimeout(timer);
+        input.signal.removeEventListener('abort', stop);
+    }
+}