@ours.network/fleet 0.9.4 → 0.9.7

package/dist/session/control.js

@@ -0,0 +1,322 @@
+import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { chmodSync, existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { createConnection, createServer } from 'node:net';
+import { join } from 'node:path';
+import { SessionControlError } from './types.js';
+const MAX_LINE_BYTES = 64 * 1024;
+/**
+ * One line saying what a control failure does — and does not — prove about the
+ * agent. Only `offline` is evidence that it is gone; every other kind used to
+ * be rendered as "is not running", which is how a busy agent got restarted.
+ */
+export function livenessNote(kind, name) {
+    switch (kind) {
+        case 'offline':
+            return `'${name}' is confirmed offline.`;
+        case 'control-unavailable':
+            return `this says nothing about whether '${name}' is alive — its control plane did not answer; ` +
+                `check: ours-fleet status ${name}`;
+        case 'timeout':
+            return `'${name}' did not answer in time; a busy agent looks exactly like this. ` +
+                `Check: ours-fleet status ${name}`;
+        case 'rejected':
+            return `'${name}' is running and refused the request.`;
+        case 'backend':
+            return `this is a transport failure, not evidence that '${name}' is gone; ` +
+                `check: ours-fleet status ${name}`;
+    }
+}
+/** The taxonomy, in the order generated guidance presents it. */
+export function oversightTaxonomy(name = '<Name>') {
+    return [
+        {
+            result: 'queued',
+            meaning: `the session accepted the prompt for '${name}'; a turn already running is not a failure.`,
+            action: 'Nothing. Do not resend, and do not read the absence of a reply as a stall — '
+                + `check progress with: ours-fleet peek ${name}`,
+            restartJustified: false,
+        },
+        {
+            result: 'timeout',
+            meaning: livenessNote('timeout', name),
+            action: 'Treat delivery as UNCERTAIN — the request may already have been acted on, so do not '
+                + 'resend it blindly.',
+            restartJustified: false,
+        },
+        {
+            result: 'rejected',
+            meaning: livenessNote('rejected', name),
+            action: 'Fix the request, not the agent. A refusal is proof of life.',
+            restartJustified: false,
+        },
+        {
+            result: 'control-unavailable',
+            meaning: livenessNote('control-unavailable', name),
+            action: 'Read the role logs as well. The control plane and the agent are separate things, '
+                + 'and one being unreachable is not evidence about the other.',
+            restartJustified: false,
+        },
+        {
+            result: 'backend',
+            meaning: livenessNote('backend', name),
+            action: 'Investigate the transport, not the agent.',
+            restartJustified: false,
+        },
+        {
+            result: 'offline',
+            meaning: livenessNote('offline', name),
+            action: `This is the ONLY result that justifies a restart on its own: ours-fleet restart ${name} `
+                + 'for a permanent role. Read the logs first.',
+            restartJustified: true,
+        },
+    ];
+}
+/**
+ * The taxonomy as guidance lines, for a briefing or any generated document.
+ * The shipped oversee-agents skills carry these same lines, and a test holds
+ * them to it — so an overseer reading its briefing and an overseer reading the
+ * skill cannot be given different rules.
+ */
+export function oversightTaxonomyLines(name = '<Name>') {
+    return oversightTaxonomy(name).map(r => `- **${r.result}** — ${r.meaning} → ${r.action}`);
+}
+export const controlSocketPath = (stateDir) => join(stateDir, '.control.sock');
+export const controlTokenPath = (stateDir) => join(stateDir, '.control-token');
+function sameToken(actual, supplied) {
+    const a = Buffer.from(actual);
+    const b = Buffer.from(supplied);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/** Private, versioned JSONL control plane for CLI and future console frontends. */
+export class RoleControlServer {
+    session;
+    log;
+    server;
+    socketPath;
+    token;
+    sockets = new Set();
+    constructor(stateDir, session, log) {
+        this.session = session;
+        this.log = log;
+        this.socketPath = controlSocketPath(stateDir);
+        const tokenPath = controlTokenPath(stateDir);
+        this.token = existsSync(tokenPath)
+            ? readFileSync(tokenPath, 'utf8').trim()
+            : randomBytes(32).toString('hex');
+        writeFileSync(tokenPath, this.token + '\n', { mode: 0o600 });
+        chmodSync(tokenPath, 0o600);
+        rmSync(this.socketPath, { force: true });
+        this.server = createServer(socket => this.accept(socket));
+    }
+    async start() {
+        await new Promise((resolve, reject) => {
+            this.server.once('error', reject);
+            this.server.listen(this.socketPath, () => {
+                this.server.off('error', reject);
+                try {
+                    chmodSync(this.socketPath, 0o600);
+                }
+                catch { /* platform dependent */ }
+                resolve();
+            });
+        });
+    }
+    async close() {
+        for (const socket of this.sockets)
+            socket.destroy();
+        await new Promise(resolve => this.server.close(() => resolve()));
+        rmSync(this.socketPath, { force: true });
+    }
+    accept(socket) {
+        this.sockets.add(socket);
+        socket.setEncoding('utf8');
+        let buffer = '';
+        let unsubscribe;
+        socket.on('data', chunk => {
+            buffer += chunk;
+            if (Buffer.byteLength(buffer) > MAX_LINE_BYTES) {
+                socket.destroy(new Error('control request too large'));
+                return;
+            }
+            for (;;) {
+                const newline = buffer.indexOf('\n');
+                if (newline < 0)
+                    break;
+                const line = buffer.slice(0, newline);
+                buffer = buffer.slice(newline + 1);
+                if (!line.trim())
+                    continue;
+                void this.handle(line, socket).then(stop => {
+                    if (stop) {
+                        if (unsubscribe) {
+                            unsubscribe();
+                            this.session.setControllerAttached(false);
+                        }
+                        unsubscribe = stop;
+                    }
+                });
+            }
+        });
+        socket.on('close', () => {
+            this.sockets.delete(socket);
+            if (unsubscribe) {
+                unsubscribe();
+                this.session.setControllerAttached(false);
+            }
+        });
+        socket.on('error', error => this.log(`control socket: ${error.message}`));
+    }
+    async handle(line, socket) {
+        let request;
+        try {
+            request = JSON.parse(line);
+        }
+        catch {
+            this.write(socket, { version: 1, id: '?', ok: false, error: 'invalid JSON' });
+            return;
+        }
+        if (request.version !== 1 || typeof request.id !== 'string'
+            || !sameToken(this.token, request.token ?? '')) {
+            this.write(socket, { version: 1, id: request.id ?? '?', ok: false, error: 'unauthorized' });
+            return;
+        }
+        try {
+            switch (request.command) {
+                case 'status':
+                case 'snapshot':
+                    this.write(socket, { version: 1, id: request.id, ok: true, result: this.session.snapshot() });
+                    return;
+                case 'submit_prompt': {
+                    if (!request.text?.trim())
+                        throw new SessionControlError('rejected', 'text is required');
+                    // Answer on QUEUE ACCEPTANCE, not on turn completion. A turn can run
+                    // for minutes; blocking here made every `send` into a busy agent time
+                    // out, and the timeout was then reported as a dead agent.
+                    const queued = await this.session.queuePrompt(request.text);
+                    this.write(socket, {
+                        version: 1, id: request.id, ok: true,
+                        result: {
+                            state: 'queued', promptId: queued.promptId, queuedBehind: queued.queuedBehind,
+                        },
+                    });
+                    return;
+                }
+                case 'respond_permission': {
+                    if (!request.permissionId || !request.optionId)
+                        throw new SessionControlError('rejected', 'permissionId and optionId are required');
+                    const accepted = this.session.respondPermission(request.permissionId, request.optionId);
+                    this.write(socket, {
+                        version: 1, id: request.id, ok: accepted,
+                        result: { accepted },
+                        error: accepted ? undefined : 'stale or invalid permission response',
+                        kind: accepted ? undefined : 'rejected',
+                    });
+                    return;
+                }
+                case 'interrupt':
+                    await this.session.interrupt();
+                    this.write(socket, { version: 1, id: request.id, ok: true });
+                    return;
+                case 'follow': {
+                    const since = Number.isFinite(request.since) ? Number(request.since) : 0;
+                    this.write(socket, {
+                        version: 1, id: request.id, ok: true,
+                        result: { events: this.session.eventsSince(since), snapshot: this.session.snapshot() },
+                    });
+                    this.session.setControllerAttached(true);
+                    return this.session.subscribe(event => {
+                        if (!socket.destroyed)
+                            socket.write(JSON.stringify({ version: 1, event }) + '\n');
+                    });
+                }
+            }
+        }
+        catch (error) {
+            // Carry the session's own classification to the caller. Losing it here is
+            // what forced the CLI to invent one.
+            this.write(socket, {
+                version: 1,
+                id: request.id,
+                ok: false,
+                error: error?.message ?? String(error),
+                kind: error instanceof SessionControlError ? error.kind : 'backend',
+            });
+        }
+    }
+    write(socket, response) {
+        if (!socket.destroyed)
+            socket.write(JSON.stringify(response) + '\n');
+    }
+}
+/**
+ * Send one control request. Every failure mode is classified: a missing token
+ * or socket is `control-unavailable`, a silent server is `timeout`, and a
+ * response that is not parseable JSON is `backend`. The caller never has to
+ * infer liveness from an exception message.
+ */
+export async function controlRequest(stateDir, request, timeoutMs = 120_000) {
+    let token;
+    try {
+        token = readFileSync(controlTokenPath(stateDir), 'utf8').trim();
+    }
+    catch (error) {
+        throw new SessionControlError('control-unavailable', `cannot read the role control token: ${error?.message ?? String(error)}`);
+    }
+    const id = randomUUID();
+    const socket = createConnection(controlSocketPath(stateDir));
+    socket.setEncoding('utf8');
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            socket.destroy();
+            reject(new SessionControlError('timeout', `the role control plane did not answer '${request.command}' within ${timeoutMs}ms`));
+        }, timeoutMs);
+        let buffer = '';
+        socket.once('error', error => {
+            clearTimeout(timer);
+            const code = error.code;
+            reject(new SessionControlError(code === 'ENOENT' || code === 'ECONNREFUSED' ? 'control-unavailable' : 'backend', `role control socket: ${error.message}`));
+        });
+        socket.on('data', chunk => {
+            buffer += chunk;
+            const newline = buffer.indexOf('\n');
+            if (newline < 0)
+                return;
+            clearTimeout(timer);
+            try {
+                resolve(JSON.parse(buffer.slice(0, newline)));
+            }
+            catch (error) {
+                reject(new SessionControlError('backend', `malformed control response: ${error?.message ?? String(error)}`));
+            }
+            socket.end();
+        });
+        socket.once('connect', () => socket.write(JSON.stringify({
+            version: 1, id, token, ...request,
+        }) + '\n'));
+    });
+}
+export async function followControl(stateDir, onMessage) {
+    const token = readFileSync(controlTokenPath(stateDir), 'utf8').trim();
+    const socket = createConnection(controlSocketPath(stateDir));
+    socket.setEncoding('utf8');
+    let buffer = '';
+    socket.on('data', chunk => {
+        buffer += chunk;
+        for (;;) {
+            const newline = buffer.indexOf('\n');
+            if (newline < 0)
+                break;
+            const line = buffer.slice(0, newline);
+            buffer = buffer.slice(newline + 1);
+            if (line.trim())
+                onMessage(JSON.parse(line));
+        }
+    });
+    await new Promise((resolve, reject) => {
+        socket.once('connect', resolve);
+        socket.once('error', reject);
+    });
+    const send = (request) => socket.write(JSON.stringify({ version: 1, id: randomUUID(), token, ...request }) + '\n');
+    send({ command: 'follow', since: 0 });
+    return { socket, send };
+}

package/dist/session/events.d.ts

@@ -0,0 +1,14 @@
+import type { SessionEvent, SessionEventKind } from './types.js';
+/** Bounded, typed event stream shared by CLI frontends and future ACP/Toad facades. */
+export declare class SessionEvents {
+    private readonly path;
+    private seq;
+    private readonly events;
+    private readonly listeners;
+    constructor(path: string);
+    emit(kind: SessionEventKind, fields?: Omit<SessionEvent, 'version' | 'seq' | 'at' | 'kind'>): SessionEvent;
+    since(seq: number): SessionEvent[];
+    subscribe(listener: (event: SessionEvent) => void): () => void;
+    private restore;
+    private rotateIfNeeded;
+}

package/dist/session/events.js

@@ -0,0 +1,67 @@
+import { appendFileSync, existsSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+const MAX_EVENTS = 1_000;
+const MAX_EVENT_FILE_BYTES = 2 * 1024 * 1024;
+/** Bounded, typed event stream shared by CLI frontends and future ACP/Toad facades. */
+export class SessionEvents {
+    path;
+    seq = 0;
+    events = [];
+    listeners = new Set();
+    constructor(path) {
+        this.path = path;
+        this.restore();
+    }
+    emit(kind, fields = {}) {
+        const event = {
+            version: 1,
+            seq: ++this.seq,
+            at: new Date().toISOString(),
+            kind,
+            ...fields,
+        };
+        this.events.push(event);
+        if (this.events.length > MAX_EVENTS)
+            this.events.shift();
+        try {
+            this.rotateIfNeeded();
+            appendFileSync(this.path, JSON.stringify(event) + '\n', { mode: 0o600 });
+        }
+        catch { /* diagnostics must never terminate a role */ }
+        for (const listener of this.listeners)
+            listener(event);
+        return event;
+    }
+    since(seq) {
+        return this.events.filter(event => event.seq > seq);
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    restore() {
+        try {
+            if (!existsSync(this.path))
+                return;
+            const lines = readFileSync(this.path, 'utf8').trim().split('\n').slice(-MAX_EVENTS);
+            for (const line of lines) {
+                const event = JSON.parse(line);
+                if (event.version === 1 && typeof event.seq === 'number') {
+                    this.events.push(event);
+                    this.seq = Math.max(this.seq, event.seq);
+                }
+            }
+        }
+        catch { /* begin a fresh projection if the diagnostic file is corrupt */ }
+    }
+    rotateIfNeeded() {
+        if (!existsSync(this.path) || statSync(this.path).size < MAX_EVENT_FILE_BYTES)
+            return;
+        const rotated = this.path + '.1';
+        try {
+            renameSync(this.path, rotated);
+        }
+        catch {
+            writeFileSync(this.path, '', { mode: 0o600 });
+        }
+    }
+}

package/dist/session/tmux.d.ts

@@ -0,0 +1,27 @@
+import type { Tmux } from '../tmux.js';
+import type { ExitRecord, QueuedPrompt, SessionEvent, SessionHandle, SessionSnapshot, TurnResult } from './types.js';
+/** SessionHandle adapter for the existing tmux transport. */
+export declare class TmuxSession implements SessionHandle {
+    private readonly name;
+    readonly pid: number;
+    private readonly tmux;
+    private readonly processAlive;
+    readonly backend: "tmux";
+    constructor(name: string, pid: number, tmux: Tmux, processAlive: (pid: number) => boolean);
+    isAlive(): boolean;
+    snapshot(): SessionSnapshot;
+    queuePrompt(text: string): Promise<QueuedPrompt>;
+    submitPrompt(text: string): Promise<TurnResult>;
+    interrupt(): Promise<void>;
+    respondPermission(): boolean;
+    eventsSince(): SessionEvent[];
+    subscribe(): () => void;
+    setControllerAttached(): void;
+    /**
+     * A tmux pane's exit is only visible through the record its shell wrapper
+     * writes; the runner owns that file and classifies it. Nothing observable
+     * from here, so say `null` rather than guess.
+     */
+    exitResult(): ExitRecord | null;
+    close(): Promise<void>;
+}

package/dist/session/tmux.js

@@ -0,0 +1,76 @@
+import { randomUUID } from 'node:crypto';
+import { SessionControlError, turnResult } from './types.js';
+/** SessionHandle adapter for the existing tmux transport. */
+export class TmuxSession {
+    name;
+    pid;
+    tmux;
+    processAlive;
+    backend = 'tmux';
+    constructor(name, pid, tmux, processAlive) {
+        this.name = name;
+        this.pid = pid;
+        this.tmux = tmux;
+        this.processAlive = processAlive;
+    }
+    isAlive() {
+        return this.processAlive(this.pid);
+    }
+    snapshot() {
+        return {
+            backend: 'tmux',
+            alive: this.isAlive(),
+            readiness: this.isAlive() ? 'idle' : 'failed',
+        };
+    }
+    async queuePrompt(text) {
+        if (!this.isAlive())
+            throw new SessionControlError('offline', `tmux pane for '${this.name}' is offline`);
+        try {
+            await this.tmux.sendText(this.name, text);
+        }
+        catch (error) {
+            throw new SessionControlError('backend', error?.message ?? String(error));
+        }
+        // Keystrokes carry no terminal result: tmux cannot tell us how the turn ended.
+        return {
+            promptId: randomUUID(),
+            queuedBehind: 0,
+            completion: Promise.resolve(turnResult(true, 'inconclusive')),
+        };
+    }
+    async submitPrompt(text) {
+        try {
+            return await (await this.queuePrompt(text)).completion;
+        }
+        catch (error) {
+            if (error instanceof SessionControlError)
+                return turnResult(false, 'failed', error.message);
+            throw error;
+        }
+    }
+    async interrupt() {
+        await this.tmux.sendKey(this.name, 'C-c');
+    }
+    respondPermission() {
+        return false;
+    }
+    eventsSince() {
+        return [];
+    }
+    subscribe() {
+        return () => { };
+    }
+    setControllerAttached() { }
+    /**
+     * A tmux pane's exit is only visible through the record its shell wrapper
+     * writes; the runner owns that file and classifies it. Nothing observable
+     * from here, so say `null` rather than guess.
+     */
+    exitResult() {
+        return null;
+    }
+    async close() {
+        await this.tmux.kill(this.name);
+    }
+}

package/dist/session/types.d.ts

@@ -0,0 +1,138 @@
+import type { SessionBackendId } from '../config.js';
+export type SessionReadiness = 'starting' | 'idle' | 'running' | 'awaiting_permission' | 'failed';
+export type TurnOutcome = 'completed' | 'refused' | 'cancelled' | 'failed' | 'inconclusive';
+/**
+ * Two independent facts about one turn, deliberately kept apart:
+ *
+ * - `accepted` — the live session took responsibility for the prompt. It says
+ *   nothing about what the agent then did with it.
+ * - `outcome` / `succeeded` — how the turn TERMINATED. Only `completed` is a
+ *   terminal success. A refusal or a cancellation is a prompt that was
+ *   delivered and then not carried out; every caller that needs the work
+ *   actually done (mail delivery, role startup) must treat it as a failure.
+ *
+ * Collapsing the two is what let a refused wake commit its notification cursor
+ * and a refused startup prompt log the role as up.
+ */
+export interface TurnResult {
+    accepted: boolean;
+    outcome: TurnOutcome;
+    succeeded: boolean;
+    detail?: string;
+}
+/**
+ * Why a control operation failed. The distinctions exist because collapsing
+ * them is what made a busy agent look dead: only `offline` is evidence that the
+ * session is gone, and `timeout` explicitly does NOT say the prompt was lost.
+ */
+export type ControlFailureKind = 'offline' | 'control-unavailable' | 'timeout' | 'rejected' | 'backend';
+export declare class SessionControlError extends Error {
+    readonly kind: ControlFailureKind;
+    constructor(kind: ControlFailureKind, message: string);
+}
+/**
+ * A prompt the live session has taken responsibility for. Interactive callers
+ * stop here: the session has the prompt, and waiting for the turn to finish is
+ * a different question with a different, much longer, timescale.
+ */
+export interface QueuedPrompt {
+    promptId: string;
+    /** Turns already queued ahead of this one. 0 means it starts immediately. */
+    queuedBehind: number;
+    /** The turn's terminal result. Never rejects. */
+    completion: Promise<TurnResult>;
+}
+/**
+ * How a session's process ended.
+ *
+ * `unknown` is the honest answer when no evidence was recorded — the previous
+ * code wrote the word `crash` there, asserting a failure it had not observed.
+ * `session-destroyed` (the console was torn down out from under a live process)
+ * and `program-exit` (the program decided to leave) are different events and
+ * must not collapse into one another, because they imply different next starts.
+ */
+export type ExitClass = 'clean' | 'program-exit' | 'signal' | 'session-destroyed' | 'unknown';
+export interface ExitRecord {
+    version: 1;
+    class: ExitClass;
+    /** Exit code, when the program exited of its own accord. */
+    code?: number;
+    /** Signal that killed it, when one did. */
+    signal?: string;
+    /** Raw wait status as the pane shell saw it (tmux only). */
+    status?: number;
+    at?: string;
+    /** One line an operator can read. */
+    detail: string;
+}
+/**
+ * Classify a shell `$?`. Above 128 the shell is reporting 128+signal — the only
+ * signal evidence a pane wrapper can give us.
+ */
+export declare function classifyShellStatus(status: number): ExitRecord;
+/** Classify a child process exit reported directly by node. */
+export declare function classifyChildExit(code: number | null, signal: string | null): ExitRecord;
+/** The single definition of terminal success. Nothing else may re-derive it. */
+export declare const isTerminalSuccess: (outcome: TurnOutcome) => boolean;
+/** Build a TurnResult with `succeeded` always consistent with `outcome`. */
+export declare function turnResult(accepted: boolean, outcome: TurnOutcome, detail?: string): TurnResult;
+export interface SessionSnapshot {
+    backend: SessionBackendId;
+    alive: boolean;
+    readiness: SessionReadiness;
+    sessionId?: string;
+    lastError?: string;
+    pendingPermissionId?: string;
+}
+export type SessionEventKind = 'state' | 'agent_text' | 'thought' | 'tool_call' | 'tool_update' | 'permission' | 'turn_stop' | 'error';
+/** What a settled permission request resolved to. */
+export type PermissionDecision = 'allowed' | 'denied' | 'cancelled';
+export interface SessionEvent {
+    version: 1;
+    seq: number;
+    at: string;
+    kind: SessionEventKind;
+    turnId?: string;
+    toolCallId?: string;
+    permissionId?: string;
+    text?: string;
+    title?: string;
+    status?: string;
+    stopReason?: string;
+    options?: Array<{
+        optionId: string;
+        name: string;
+        kind: string;
+    }>;
+    /** What was decided. */
+    decision?: PermissionDecision;
+    /** Whether policy decided it, or a human answered the prompt. */
+    decisionSource?: 'automatic' | 'manual';
+    /** The configured policy that produced an automatic decision. */
+    policy?: string;
+    /** Why, in one human-readable line. */
+    reason?: string;
+    /** The option actually selected, when one was. */
+    optionId?: string;
+}
+export interface SessionHandle {
+    readonly backend: SessionBackendId;
+    readonly pid: number;
+    isAlive(): boolean;
+    snapshot(): SessionSnapshot;
+    /**
+     * Hand the session a prompt and return as soon as it has accepted
+     * responsibility for it. Throws `SessionControlError` if it cannot.
+     */
+    queuePrompt(text: string): Promise<QueuedPrompt>;
+    /** Queue a prompt and wait for its terminal result. */
+    submitPrompt(text: string): Promise<TurnResult>;
+    interrupt(): Promise<void>;
+    respondPermission(permissionId: string, optionId: string): boolean;
+    eventsSince(seq: number): SessionEvent[];
+    subscribe(listener: (event: SessionEvent) => void): () => void;
+    setControllerAttached(attached: boolean): void;
+    /** How the backing process ended, or null while it is still running. */
+    exitResult(): ExitRecord | null;
+    close(): Promise<void>;
+}

package/dist/session/types.js

@@ -0,0 +1,42 @@
+export class SessionControlError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = 'SessionControlError';
+    }
+}
+/**
+ * Classify a shell `$?`. Above 128 the shell is reporting 128+signal — the only
+ * signal evidence a pane wrapper can give us.
+ */
+export function classifyShellStatus(status) {
+    if (!Number.isFinite(status))
+        return { version: 1, class: 'unknown', detail: 'pane wrote an unreadable exit status' };
+    if (status === 0)
+        return { version: 1, class: 'clean', code: 0, status, detail: 'exited cleanly (code 0)' };
+    if (status > 128) {
+        const signal = status - 128;
+        return {
+            version: 1, class: 'signal', signal: `SIG${signal}`, status,
+            detail: `killed by signal ${signal} (shell status ${status})`,
+        };
+    }
+    return { version: 1, class: 'program-exit', code: status, status, detail: `exited with code ${status}` };
+}
+/** Classify a child process exit reported directly by node. */
+export function classifyChildExit(code, signal) {
+    if (signal)
+        return { version: 1, class: 'signal', signal, detail: `killed by ${signal}` };
+    if (code === 0)
+        return { version: 1, class: 'clean', code: 0, detail: 'exited cleanly (code 0)' };
+    if (code === null)
+        return { version: 1, class: 'unknown', detail: 'the process ended with neither a code nor a signal' };
+    return { version: 1, class: 'program-exit', code, detail: `exited with code ${code}` };
+}
+/** The single definition of terminal success. Nothing else may re-derive it. */
+export const isTerminalSuccess = (outcome) => outcome === 'completed';
+/** Build a TurnResult with `succeeded` always consistent with `outcome`. */
+export function turnResult(accepted, outcome, detail) {
+    return { accepted, outcome, succeeded: isTerminalSuccess(outcome), detail };
+}