@ours.network/fleet 0.17.0 → 0.17.2

package/dist/session/types.d.ts

@@ -62,10 +62,38 @@ export interface TurnResult {
  * session is gone, and `timeout` explicitly does NOT say the prompt was lost.
  */
 export type ControlFailureKind = 'offline' | 'control-unavailable' | 'timeout' | 'rejected' | 'backend';
+/** Stable body-free reason shared by ACP recovery and durable ingress. */
+export declare const ACP_CANCEL_DEADLINE_EXCEEDED = "ACP_CANCEL_DEADLINE_EXCEEDED";
 export declare class SessionControlError extends Error {
     readonly kind: ControlFailureKind;
-    constructor(kind: ControlFailureKind, message: string);
+    /** Stable body-free machine reason for recovery/audit decisions. */
+    readonly reasonCode?: string | undefined;
+    constructor(kind: ControlFailureKind, message: string, 
+    /** Stable body-free machine reason for recovery/audit decisions. */
+    reasonCode?: string | undefined);
 }
+/**
+ * How an explicit cancellation ended. Forced recovery is a SUCCESS: the turn is
+ * over and the session is being reclaimed. Reporting it as a failed interrupt is
+ * what made owners, the control plane and the web console retry an operation
+ * that had already done exactly what was asked.
+ */
+export interface InterruptOutcome {
+    /** `settled` — the turn (or nothing) ended cooperatively. `forced` — the adapter ignored the cancel and was restarted. */
+    state: 'settled' | 'forced';
+    /** Stable body-free reason present only for a forced recovery. */
+    reasonCode?: string;
+}
+/**
+ * What a `SessionHandle.interrupt` implementation may resolve. Before 0.17.1 the
+ * contract was `Promise<void>`, and resolving at all meant the cancellation had
+ * taken effect cooperatively — so an implementation written against that
+ * contract stays valid and keeps its exact meaning. Only in-tree consumers read
+ * the richer outcome, and they normalize through `interruptOutcome` first.
+ */
+export type InterruptResult = InterruptOutcome | void;
+/** The one place the legacy `void` reply is given its meaning: `settled`. */
+export declare function interruptOutcome(result: InterruptResult): InterruptOutcome;
 /**
  * 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
@@ -218,7 +246,16 @@ export interface SessionHandle {
     submitPrompt(text: string, options?: SubmitPromptOptions): Promise<TurnResult>;
     /** Monitor-only ACP safe-boundary delivery. Never implies human/control cancellation. */
     submitPromptAfterTool?(text: string, options?: SubmitPromptOptions): Promise<TurnResult>;
-    interrupt(source?: TurnCancellationSource): Promise<void>;
+    /**
+     * Cancel the active turn. Resolves when the cancellation has taken effect —
+     * cooperatively (`settled`) or through bounded forced recovery (`forced`).
+     * It rejects only when the cancellation itself could not be delivered.
+     *
+     * The return type is widened to `InterruptResult` for one reason: an
+     * implementation written against the pre-0.17.1 `Promise<void>` contract must
+     * keep compiling. Read it through `interruptOutcome`, never directly.
+     */
+    interrupt(source?: TurnCancellationSource): Promise<InterruptResult>;
     respondPermission(permissionId: string, optionId: string): boolean;
     /** Generation-bound browser decision; stale/settled/invalid all fail closed. */
     respondPermissionV2?(permissionId: string, optionId: string, sessionGeneration: string): 'accepted' | 'stale';

package/dist/session/types.js

@@ -1,11 +1,21 @@
+/** Stable body-free reason shared by ACP recovery and durable ingress. */
+export const ACP_CANCEL_DEADLINE_EXCEEDED = 'ACP_CANCEL_DEADLINE_EXCEEDED';
 export class SessionControlError extends Error {
     kind;
-    constructor(kind, message) {
+    reasonCode;
+    constructor(kind, message, 
+    /** Stable body-free machine reason for recovery/audit decisions. */
+    reasonCode) {
         super(message);
         this.kind = kind;
+        this.reasonCode = reasonCode;
         this.name = 'SessionControlError';
     }
 }
+/** The one place the legacy `void` reply is given its meaning: `settled`. */
+export function interruptOutcome(result) {
+    return result ?? { state: 'settled' };
+}
 /**
  * Classify a shell `$?`. Above 128 the shell is reporting 128+signal — the only
  * signal evidence a pane wrapper can give us.

package/dist/spawn.d.ts

@@ -4,6 +4,7 @@ import { type OpsDeps } from './ops.js';
 import { type CreationDeps, type CreationProvenance } from './creation.js';
 import './harness/claude-code.js';
 import './harness/codex.js';
+import { type SupervisorLauncher } from './temp-lifecycle.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.
@@ -94,7 +95,6 @@ export interface SpawnDryRun {
 export declare function spawnDryRun(o: SpawnOpts): SpawnDryRun;
 /** Permanent spawn: persist to ~/fleet.d/<Name>.yaml, then bring it up. */
 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 type { SupervisorLauncher } from './temp-lifecycle.js';
+/** Temp spawn: live state under ~/.ours-fleet/tmp, independent transient supervision. */
 export declare function spawnTemp(o: SpawnOpts, binPath: string, launch?: SupervisorLauncher, creation?: CreationDeps): Promise<string>;

package/dist/spawn.js

@@ -1,5 +1,5 @@
 import { spawn as spawnChild } from 'node:child_process';
-import { existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { parse, stringify } from 'yaml';
 import { agentDir, fleetDDir } from './paths.js';
@@ -12,6 +12,7 @@ import { VERSION } from './version.js';
 import './harness/claude-code.js';
 import './harness/codex.js';
 import { getAdapter } from './harness/registry.js';
+import { archiveTempState, makeTempSupervisorLauncher, prepareTempSupervisor, reclaimStaleTempState, } from './temp-lifecycle.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.
@@ -341,22 +342,37 @@ export async function spawnPermanent(o, deps, creation = {}) {
         return file;
     }, creation);
 }
-const detachedSupervisor = (binPath, args, dir) => {
-    // Log to the temp dir; the fd stays valid even after runTemp removes the dir.
+/** Fallback used only when service-manager supervision is explicitly disabled. */
+const spawnDetached = (binPath, args, dir) => {
+    // Log to the temp dir; the child fd stays valid when retirement moves the
+    // directory into the evidence archive.
     const out = openSync(join(dir, 'supervisor.log'), 'a');
-    const child = spawnChild(process.execPath, [binPath, ...args], {
-        detached: true,
-        stdio: ['ignore', out, out],
-    });
+    let child;
+    try {
+        child = spawnChild(process.execPath, [binPath, ...args], {
+            detached: true,
+            stdio: ['ignore', out, out],
+        });
+    }
+    finally {
+        closeSync(out);
+    }
     child.unref();
+    if (!child.pid)
+        throw new Error('detached temporary supervisor did not report a pid');
+    return child.pid;
 };
-/** Temp spawn: state under ~/.ours-fleet/tmp, plain tmux, auto-clean on exit. */
-export async function spawnTemp(o, binPath, launch = detachedSupervisor, creation = {}) {
+const independentSupervisor = makeTempSupervisorLauncher({ spawnDetached });
+/** Temp spawn: live state under ~/.ours-fleet/tmp, independent transient supervision. */
+export async function spawnTemp(o, binPath, launch = independentSupervisor, creation = {}) {
     validateSpawnOpts(o);
     if (o.isolationFile)
         readIsolationFile(o.isolationFile); // fail before reserving
     if (o.missionFile)
         readMissionFile(o.missionFile); // fail before reserving
+    // Retire only supervisors whose recorded owner is definitively stopped. This
+    // bounded pass keeps the active roster clean without deleting old evidence.
+    await reclaimStaleTempState();
     // Temporary roles go through the SAME reservation boundary as permanent ones
     // (6.4): a temp agent competes for the same names.
     creation.onStage?.('reserving');
@@ -425,19 +441,29 @@ async function spawnTempInner(o, binPath, launch, tx, guarantee, onStage) {
     });
     writeProvenance(dir, provenance);
     lastProvenance = provenance;
-    tx.record({ stage: `temp state dir ${dir}`, undo: () => rmSync(dir, { recursive: true, force: true }) });
+    tx.record({
+        stage: `temp state dir ${dir}`,
+        undo: () => {
+            // A failed launch is still lifecycle evidence: briefing, provenance,
+            // metadata and supervisor output explain what happened. Remove it from
+            // the live roster by atomic archive, never recursive deletion.
+            archiveTempState(o.name, 'startup-failure', 'failed', 'temporary creation rolled back after launch/setup failure; evidence preserved');
+        },
+    });
     writeFileSync(join(dir, 'role.yaml'), stringify(role));
     // Snapshot the fleet start-stagger so the detached temp supervisor (no config path
     // threaded through it) honors the same launch gate — a burst of temp spawns spaces
     // out; a lone temp spawn still waits zero (time-based gate).
     if (cfg.startStaggerMs > 0)
         writeFileSync(join(dir, START_STAGGER_FILE), String(cfg.startStaggerMs));
-    // Run the supervisor DETACHED — NOT inside a tmux session named <name>.
+    prepareTempSupervisor(dir, o.name);
+    // Run the supervisor independently — NOT inside a tmux session named <name>.
     // `_run-temp` -> runOnce() creates AND kills the tmux session <name> for the
     // agent itself; a supervisor sharing that session name would SIGHUP its own
-    // process before the agent ever launches. Detaching mirrors how systemd hosts
-    // the supervisor for permanent roles, leaving runOnce to own the <name> session.
+    // process before the agent ever launches. On a service-managed host the temp
+    // runner gets its own transient unit/job, so stopping the coordinator's unit
+    // cannot kill a live worker in the coordinator's cgroup.
     onStage?.('starting_temp');
-    launch(binPath, ['_run-temp', o.name], dir);
+    await launch(binPath, ['_run-temp', o.name], dir);
     return dir;
 }

package/dist/temp-lifecycle.d.ts

@@ -0,0 +1,62 @@
+import { type Exec } from './exec.js';
+export declare const TEMP_SUPERVISOR_FILE = ".temp-supervisor.json";
+export declare const TEMP_TERMINATION_FILE = "termination.jsonl";
+export declare const TEMP_STOP_REQUEST_FILE = ".temp-stop-request.json";
+export declare const TEMP_RECLAIM_BATCH = 32;
+export declare const TEMP_LAUNCH_GRACE_MS = 60000;
+export type TempSupervisorKind = 'systemd-transient' | 'launchd-transient' | 'detached';
+export type TempTerminationReason = 'identity-closed' | 'session-ended' | 'operator-stop' | 'supervisor-signal' | 'startup-failure' | 'stale-supervisor';
+export interface TempSupervisorRecord {
+    version: 1;
+    role: string;
+    launchId: string;
+    createdAt: string;
+    phase: 'launching' | 'active';
+    kind?: TempSupervisorKind;
+    target?: string;
+    pid?: number;
+    binPath?: string;
+}
+export interface TempTerminationRecord {
+    version: 1;
+    role: string;
+    launchId?: string;
+    at: string;
+    reason: TempTerminationReason;
+    outcome: 'retired' | 'reclaimed' | 'failed';
+    detail: string;
+}
+export type SupervisorLauncher = (binPath: string, args: string[], dir: string) => void | Promise<void>;
+export declare const tempSystemdUnit: (name: string) => string;
+export declare const tempLaunchdLabel: (name: string) => string;
+export declare function prepareTempSupervisor(dir: string, role: string): TempSupervisorRecord;
+export declare function readTempSupervisor(dir: string): TempSupervisorRecord | undefined;
+/**
+ * Launch a temp supervisor outside the caller's service-manager ownership
+ * boundary. `detached: true` creates a new process group but does not escape a
+ * systemd cgroup; a transient unit does, and is not enabled across reboot.
+ */
+export declare function makeTempSupervisorLauncher(options?: {
+    exec?: Exec;
+    platform?: NodeJS.Platform;
+    supervisor?: string;
+    spawnDetached?: (binPath: string, args: string[], dir: string) => number;
+}): SupervisorLauncher;
+export declare function markTempSupervisorActive(dir: string, pid?: number): Promise<void>;
+export declare function requestedTempStopReason(dir: string): 'operator-stop' | undefined;
+/** Move retired state out of the live roster without deleting any evidence. */
+export declare function archiveTempState(role: string, reason: TempTerminationReason, outcome: TempTerminationRecord['outcome'], detail: string, now?: Date): string | undefined;
+interface TempLifecycleDeps {
+    exec?: Exec;
+    now?(): number;
+    kill?(pid: number, signal: NodeJS.Signals | 0): void;
+    log?(line: string): void;
+}
+export declare function tempSupervisorLiveness(dir: string, deps?: TempLifecycleDeps): Promise<'running' | 'stopped' | 'unknown'>;
+export declare function stopTempSupervisor(role: string, deps?: TempLifecycleDeps): Promise<'stopped' | 'already-stopped'>;
+/**
+ * Move a bounded batch of definitely-dead temp state into the evidence archive.
+ * Unknown/legacy/live entries are preserved; absence of proof is never cleanup authority.
+ */
+export declare function reclaimStaleTempState(deps?: TempLifecycleDeps): Promise<string[]>;
+export {};