@ours.network/fleet 0.9.5 → 0.9.7

package/dist/session/control.d.ts

@@ -1,5 +1,5 @@
 import { type Socket } from 'node:net';
-import type { SessionHandle } from './types.js';
+import type { ControlFailureKind, SessionHandle } from './types.js';
 export interface ControlRequest {
     version: 1;
     id: string;
@@ -16,7 +16,49 @@ export interface ControlResponse {
     ok: boolean;
     result?: unknown;
     error?: string;
+    /** Why it failed, so the caller does not have to guess from the text. */
+    kind?: ControlFailureKind;
 }
+/**
+ * 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 declare function livenessNote(kind: ControlFailureKind, name: string): string;
+/**
+ * The result taxonomy an overseer judges a role by (7.2).
+ *
+ * One console command is not a liveness verdict. `peek` and `send` can fail for
+ * five distinct reasons and succeed for one, and only ONE of the six says the
+ * agent is gone — collapsing them into "not running" is how busy agents got
+ * restarted. This is the single definition of that vocabulary: the generated
+ * briefing renders it, and the shipped oversee-agents skills quote it. The
+ * per-result wording comes from `livenessNote` rather than being restated, so
+ * the words an overseer reads in its instructions are the words the CLI prints.
+ */
+export interface OversightResult {
+    /** What the command reported: the one success, or the failure kind. */
+    result: 'queued' | ControlFailureKind;
+    /** What it proves about the agent. */
+    meaning: string;
+    /** What the overseer does next. */
+    action: string;
+    /**
+     * Whether this result ALONE justifies restarting the role. True for exactly
+     * one result. Every other one requires corroboration before touching a role
+     * that may simply be working.
+     */
+    restartJustified: boolean;
+}
+/** The taxonomy, in the order generated guidance presents it. */
+export declare function oversightTaxonomy(name?: string): OversightResult[];
+/**
+ * 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 declare function oversightTaxonomyLines(name?: string): string[];
 export declare const controlSocketPath: (stateDir: string) => string;
 export declare const controlTokenPath: (stateDir: string) => string;
 /** Private, versioned JSONL control plane for CLI and future console frontends. */
@@ -34,6 +76,12 @@ export declare class RoleControlServer {
     private handle;
     private write;
 }
+/**
+ * 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 declare function controlRequest(stateDir: string, request: Omit<ControlRequest, 'version' | 'id' | 'token'>, timeoutMs?: number): Promise<ControlResponse>;
 export declare function followControl(stateDir: string, onMessage: (message: Record<string, unknown>) => void): Promise<{
     socket: Socket;

package/dist/session/control.js

@@ -2,7 +2,84 @@ 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) {
@@ -111,19 +188,28 @@ export class RoleControlServer {
                     return;
                 case 'submit_prompt': {
                     if (!request.text?.trim())
-                        throw new Error('text is required');
-                    const result = await this.session.submitPrompt(request.text);
-                    this.write(socket, { version: 1, id: request.id, ok: result.accepted, result,
-                        error: result.accepted ? undefined : result.detail });
+                        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 Error('permissionId and optionId are required');
+                        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',
+                        result: { accepted },
+                        error: accepted ? undefined : 'stale or invalid permission response',
+                        kind: accepted ? undefined : 'rejected',
                     });
                     return;
                 }
@@ -146,11 +232,14 @@ export class RoleControlServer {
             }
         }
         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',
             });
         }
     }
@@ -159,18 +248,34 @@ export class RoleControlServer {
             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) {
-    const token = readFileSync(controlTokenPath(stateDir), 'utf8').trim();
+    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');
-    const response = await new Promise((resolve, reject) => {
+    return new Promise((resolve, reject) => {
         const timer = setTimeout(() => {
             socket.destroy();
-            reject(new Error('role control request timed out'));
+            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); reject(error); });
+        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');
@@ -181,7 +286,7 @@ export async function controlRequest(stateDir, request, timeoutMs = 120_000) {
                 resolve(JSON.parse(buffer.slice(0, newline)));
             }
             catch (error) {
-                reject(error);
+                reject(new SessionControlError('backend', `malformed control response: ${error?.message ?? String(error)}`));
             }
             socket.end();
         });
@@ -189,7 +294,6 @@ export async function controlRequest(stateDir, request, timeoutMs = 120_000) {
             version: 1, id, token, ...request,
         }) + '\n'));
     });
-    return response;
 }
 export async function followControl(stateDir, onMessage) {
     const token = readFileSync(controlTokenPath(stateDir), 'utf8').trim();

package/dist/session/tmux.d.ts

@@ -1,5 +1,5 @@
 import type { Tmux } from '../tmux.js';
-import type { SessionEvent, SessionHandle, SessionSnapshot, TurnResult } from './types.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;
@@ -10,11 +10,18 @@ export declare class TmuxSession implements SessionHandle {
     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

@@ -1,3 +1,5 @@
+import { randomUUID } from 'node:crypto';
+import { SessionControlError, turnResult } from './types.js';
 /** SessionHandle adapter for the existing tmux transport. */
 export class TmuxSession {
     name;
@@ -21,11 +23,31 @@ export class TmuxSession {
             readiness: this.isAlive() ? 'idle' : 'failed',
         };
     }
-    async submitPrompt(text) {
+    async queuePrompt(text) {
         if (!this.isAlive())
-            return { accepted: false, outcome: 'failed', detail: 'tmux pane is offline' };
-        await this.tmux.sendText(this.name, text);
-        return { accepted: true, outcome: 'inconclusive' };
+            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');
@@ -40,6 +62,14 @@ export class TmuxSession {
         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

@@ -1,10 +1,81 @@
 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: 'completed' | 'refused' | 'cancelled' | 'failed' | 'inconclusive';
+    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;
@@ -14,6 +85,8 @@ export interface SessionSnapshot {
     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;
@@ -31,17 +104,35 @@ export interface SessionEvent {
         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

@@ -1 +1,42 @@
-export {};
+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 };
+}

package/dist/spawn.d.ts

@@ -1,5 +1,12 @@
+import type { IsolationConfig } from './isolation/types.js';
 import { type ApprovalMode, type FilesystemMode, type SessionBackendId, type UnattendedMode } from './config.js';
 import { type OpsDeps } from './ops.js';
+import { type CreationDeps, type CreationProvenance } from './creation.js';
+/**
+ * The provenance record written by the most recent spawn in this process, so
+ * the CLI can print the same summary it persisted rather than rebuilding it.
+ */
+export declare let lastProvenance: CreationProvenance | undefined;
 export interface SpawnOpts {
     name: string;
     temp?: boolean;
@@ -23,12 +30,30 @@ export interface SpawnOpts {
     monitor?: boolean;
     bioFile?: string;
     personaFile?: string;
+    /**
+     * Path to a file holding exactly the existing `isolation:` mapping — the same
+     * schema fleet.yaml uses, not a second policy language. The ONE new operator
+     * input in this release (6.3).
+     */
+    isolationFile?: string;
     overseeInterval?: string;
     configPath?: string;
 }
+/**
+ * Read and validate an `--isolation-file`. The file is the existing
+ * `isolation:` mapping and nothing else — the same schema, the same validator
+ * (`validateIsolationConfig`), so a policy written here cannot mean something
+ * different from the identical block in fleet.yaml.
+ *
+ * Called BEFORE the creation transaction reserves anything: an invalid file
+ * must fail before any artifact exists.
+ */
+export declare function readIsolationFile(path: string): IsolationConfig;
+/** The ours identity a spawn will bind: explicit, else the role name. */
+export declare const effectiveIdentity: (o: SpawnOpts) => string;
 /** Permanent spawn: persist to ~/fleet.d/<Name>.yaml, then bring it up. */
-export declare function spawnPermanent(o: SpawnOpts, deps: OpsDeps): Promise<string>;
+export declare function spawnPermanent(o: SpawnOpts, deps: OpsDeps, creation?: CreationDeps): Promise<string>;
 /** Launches the detached temp supervisor (`_run-temp <name>`). Injectable for tests. */
 export type SupervisorLauncher = (binPath: string, args: string[], dir: string) => void;
 /** Temp spawn: state under ~/.ours-fleet/tmp, plain tmux, auto-clean on exit. */
-export declare function spawnTemp(o: SpawnOpts, binPath: string, launch?: SupervisorLauncher): Promise<string>;
+export declare function spawnTemp(o: SpawnOpts, binPath: string, launch?: SupervisorLauncher, creation?: CreationDeps): Promise<string>;