@ours.network/fleet 0.17.1 → 0.17.2

package/dist/provenance.js

@@ -0,0 +1,283 @@
+/**
+ * Build and install provenance.
+ *
+ * Two installs of this package once served the same host with the same semver
+ * (0.16.0) and different behaviour: one accepted `monitor.interrupt: after_tool`,
+ * the other rejected it. Their `dist/cli.js` were byte-identical, so `--version`
+ * could not tell them apart — the divergence lived in other modules, built from a
+ * commit after the feature landed but before the release commit bumped the
+ * version. Nothing in either artifact recorded which source tree it came from.
+ *
+ * This module gives every build a content-derived identity, exposes the
+ * capabilities it declares, and can enumerate the other installs reachable on
+ * this host so the mismatch is reported instead of guessed at.
+ */
+import { createHash } from 'node:crypto';
+import { accessSync, constants, existsSync, readFileSync, readdirSync, realpathSync, statSync, } from 'node:fs';
+import { delimiter, dirname, join, parse, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CAPABILITIES } from './capabilities.js';
+import { VERSION } from './version.js';
+export const PACKAGE_NAME = '@ours.network/fleet';
+export const BIN_NAME = 'ours-fleet';
+/** Stand-in build id for artifacts built before this module existed. */
+export const UNKNOWN_BUILD = 'unknown';
+function readJson(file) {
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseBuildInfo(value) {
+    if (typeof value?.version !== 'string' || typeof value.buildId !== 'string')
+        return undefined;
+    return {
+        version: value.version,
+        buildId: value.buildId,
+        commit: typeof value.commit === 'string' ? value.commit : undefined,
+        dirty: typeof value.dirty === 'boolean' ? value.dirty : undefined,
+        builtAt: typeof value.builtAt === 'string' ? value.builtAt : undefined,
+        capabilities: Array.isArray(value.capabilities)
+            ? value.capabilities.filter((c) => typeof c === 'string')
+            : [],
+    };
+}
+/** Read the install rooted at `packageRoot`, or undefined if that is not one. */
+export function readInstall(packageRoot) {
+    const pkg = readJson(join(packageRoot, 'package.json'));
+    if (pkg?.name !== PACKAGE_NAME || typeof pkg.version !== 'string')
+        return undefined;
+    return {
+        packageRoot,
+        version: pkg.version,
+        build: parseBuildInfo(readJson(join(packageRoot, 'dist', 'build-info.json'))),
+    };
+}
+/** Walk up from `from` to the @ours.network/fleet package directory containing it. */
+export function findPackageRoot(from) {
+    let dir = from;
+    const { root } = parse(dir);
+    for (;;) {
+        if (readInstall(dir))
+            return dir;
+        if (dir === root)
+            return undefined;
+        const up = dirname(dir);
+        if (up === dir)
+            return undefined;
+        dir = up;
+    }
+}
+const realPathOr = (p) => { try {
+    return realpathSync(p);
+}
+catch {
+    return p;
+} };
+/**
+ * Would a shell run this PATH candidate? A directory that happens to carry the
+ * command's name is not the command, and neither is a regular file without its
+ * execute bit — a half-finished install. Counting either lets something the
+ * operator can never actually invoke shadow the real one in every verdict.
+ *
+ * Windows has no execute bit (PATHEXT decides), but this CLI supervises through
+ * systemd/launchd and does not run there, so the mode check is POSIX-only.
+ */
+function isExecutableFile(path, platform = process.platform) {
+    try {
+        if (!statSync(path).isFile())
+            return false;
+        if (platform === 'win32')
+            return true;
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Every install reachable from PATH, plus the one executing right now.
+ * PATH order is preserved; an install reached by several PATH entries is listed
+ * once, at its earliest position.
+ */
+export function discoverInstalls(opts = {}) {
+    const binName = opts.binName ?? BIN_NAME;
+    const platform = opts.platform ?? process.platform;
+    const entries = (opts.path ?? process.env.PATH ?? '').split(delimiter).filter(Boolean);
+    const records = [];
+    const byRoot = new Map();
+    entries.forEach((entry, pathIndex) => {
+        const bin = join(entry, binName);
+        const realBin = realPathOr(bin);
+        if (!isExecutableFile(realBin, platform))
+            return;
+        const packageRoot = findPackageRoot(dirname(realBin));
+        if (!packageRoot || byRoot.has(packageRoot))
+            return;
+        const install = readInstall(packageRoot);
+        if (!install)
+            return;
+        const record = { ...install, bin, realBin, pathIndex, running: false };
+        byRoot.set(packageRoot, record);
+        records.push(record);
+    });
+    const argv1 = 'argv1' in opts ? opts.argv1 : process.argv[1];
+    const runningRoot = argv1 ? findPackageRoot(dirname(realPathOr(argv1))) : undefined;
+    if (runningRoot) {
+        const known = byRoot.get(runningRoot);
+        if (known)
+            known.running = true;
+        else {
+            const install = readInstall(runningRoot);
+            if (install)
+                records.push({ ...install, realBin: realPathOr(argv1), running: true });
+        }
+    }
+    return records;
+}
+/**
+ * sha256 over an install's dist/ tree, first 12 hex — the same bytes and order
+ * `scripts/build-info.mjs` hashes, so a stamped install's digest equals its
+ * buildId. This is what tells two PRE-provenance installs apart: they both
+ * report `unknown`, but they are not the same artifact, and the host that
+ * motivated this module had exactly that pair.
+ */
+export function contentDigest(packageRoot) {
+    const dist = join(packageRoot, 'dist');
+    if (!existsSync(dist))
+        return undefined;
+    const stamp = join(dist, 'build-info.json');
+    const files = [];
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const p = join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(p);
+            else if (p !== stamp)
+                files.push(relative(dist, p).split(sep).join('/'));
+        }
+    };
+    try {
+        walk(dist);
+    }
+    catch {
+        return undefined;
+    }
+    const hash = createHash('sha256');
+    for (const rel of files.sort()) {
+        const bytes = readFileSync(join(dist, rel));
+        hash.update(rel);
+        hash.update('\0');
+        hash.update(String(bytes.length));
+        hash.update('\0');
+        hash.update(bytes);
+    }
+    return hash.digest('hex').slice(0, 12);
+}
+/** `0.17.0+9f1c2a3b4d5e`, or `…+unknown` for a pre-provenance build. */
+export const buildLabel = (install) => `${install.version}+${install.build?.buildId ?? UNKNOWN_BUILD}`;
+/** What an install says it can do — never guessed from its version. */
+export const capabilitySummary = (install) => !install.build ? 'capabilities unknown'
+    : install.build.capabilities.length
+        ? `capabilities: ${install.build.capabilities.join(', ')}`
+        : 'no declared capabilities';
+const describe = (r, identity) => `${r.packageRoot} (${buildLabel(r)}`
+    + (identity && identity !== r.build?.buildId ? `, content ${identity}` : '')
+    + `${r.running ? ', running' : ''}; ${capabilitySummary(r)})`;
+/**
+ * What an install effectively IS: its stamped build id, or — for an artifact
+ * built before stamps existed — a hash of what it is made of. `unknown` only
+ * when neither can be established.
+ */
+const identityOf = (install, digest) => install.build?.buildId ?? digest(install.packageRoot) ?? UNKNOWN_BUILD;
+/**
+ * Conflicts an operator must know about. `version-build-conflict` is the one
+ * that bit this host: same semver, different artifact, silently different rules.
+ *
+ * `digest` is only consulted inside a version group of two or more, so the
+ * common single-install case never hashes anything.
+ */
+export function analyzeInstalls(records, digest = contentDigest) {
+    const skews = [];
+    const conflicted = new Set();
+    const byVersion = new Map();
+    for (const r of records)
+        byVersion.set(r.version, [...(byVersion.get(r.version) ?? []), r]);
+    for (const [version, group] of byVersion) {
+        if (group.length < 2)
+            continue;
+        // A pre-provenance build has no id to compare, so fall back to what it is
+        // made of. Two installs are the same artifact or they are not.
+        const identity = new Map(group.map(r => [r.packageRoot, identityOf(r, digest)]));
+        if (new Set(identity.values()).size < 2)
+            continue;
+        for (const r of group)
+            conflicted.add(r.packageRoot);
+        skews.push({
+            kind: 'version-build-conflict',
+            severity: 'error',
+            message: `${group.length} installs report ours-fleet ${version} but are different builds: `
+                + `${group.map(r => describe(r, identity.get(r.packageRoot))).join(' vs ')}`
+                + '. They accept different fleet.yaml — compare `ours-fleet version --json` on each '
+                + 'and remove or update the stale one.',
+        });
+    }
+    const running = records.find(r => r.running);
+    const first = records.filter(r => r.pathIndex !== undefined)
+        .sort((a, b) => a.pathIndex - b.pathIndex)[0];
+    // Two prefixes holding the same artifact are not a skew — whichever answers,
+    // the operator gets the same behaviour. Only compare content when the roots
+    // differ, so the ordinary single-install case never hashes anything.
+    const sameArtifact = running && first && first.packageRoot !== running.packageRoot
+        && identityOf(first, digest) === identityOf(running, digest)
+        && first.version === running.version;
+    if (running && first && first.packageRoot !== running.packageRoot && !sameArtifact)
+        skews.push({
+            kind: 'shadowed-runtime',
+            // Same semver on both sides is the trap: nothing an operator can see
+            // distinguishes them. Different semver is merely worth knowing (running a
+            // checkout while a global install exists is an ordinary way to work).
+            severity: first.version === running.version ? 'error' : 'warn',
+            message: `this process runs ${describe(running)} but \`${BIN_NAME}\` on PATH resolves to `
+                + `${first.bin} -> ${first.packageRoot} (${buildLabel(first)}). A command you type and this `
+                + 'runtime are not the same artifact.',
+        });
+    for (const r of records) {
+        if (r.build || conflicted.has(r.packageRoot))
+            continue;
+        skews.push({
+            kind: 'unknown-build-identity',
+            severity: 'warn',
+            message: `${r.packageRoot} (${r.version}) predates build provenance — it ships no `
+                + 'dist/build-info.json, so its source tree and capabilities cannot be verified.',
+        });
+    }
+    return skews;
+}
+let cached;
+/** Identity of the build executing right now. */
+export function buildInfo() {
+    if (cached)
+        return cached;
+    const moduleDir = dirname(fileURLToPath(import.meta.url));
+    const root = findPackageRoot(moduleDir);
+    const candidates = [
+        join(moduleDir, 'build-info.json'),
+        ...(root ? [join(root, 'dist', 'build-info.json')] : []),
+    ];
+    for (const file of candidates) {
+        const info = parseBuildInfo(readJson(file));
+        if (info)
+            return (cached = info);
+    }
+    // Running from a tree that was never built (or a build that predates this).
+    return (cached = { version: VERSION, buildId: UNKNOWN_BUILD, capabilities: [...CAPABILITIES] });
+}
+/** `ours-fleet 0.17.0+9f1c2a3b4d5e` — one line, safe for any operator output. */
+export const runningLabel = () => {
+    const info = buildInfo();
+    return `${BIN_NAME} ${buildLabel({ version: info.version, build: info })}`;
+};

package/dist/runner.d.ts

@@ -100,7 +100,13 @@ export interface AttemptResult {
     rotated: boolean;
     mode: 'fresh' | 'resume';
     modelRecovery?: 'advance' | 'hold';
+    /** Present only when a temporary-role lifecycle signal ended the session. */
+    retirementReason?: 'identity-closed' | 'operator-stop' | 'supervisor-signal';
 }
+/** Continuous authoritative absence required after an identity was observed. */
+export declare const TEMP_IDENTITY_CLOSE_DEBOUNCE_MS = 5000;
+/** Lifecycle polling is deliberately slower than the 500ms stop-signal loop. */
+export declare const TEMP_IDENTITY_POLL_MS = 2000;
 /** One session lifecycle. `runSupervised` (or a one-shot caller) drives it. */
 export declare function runOnce(name: string, opts?: {
     temp?: boolean;
@@ -123,5 +129,5 @@ export declare function runSupervised(name: string, opts?: {
     configPath?: string;
     allowResumeRotation?: boolean;
 }, d: Partial<RunnerDeps>) => Promise<AttemptResult>): Promise<RestartLedger>;
-/** Temp-agent entrypoint: run one session, then remove the temp dir. */
+/** Temp-agent entrypoint: run once, journal why it ended, then archive its evidence. */
 export declare function runTemp(name: string, deps?: Partial<RunnerDeps>): Promise<void>;

package/dist/runner.js

@@ -6,7 +6,7 @@ import { agentDir, stateRoot } from './paths.js';
 import { loadConfig, findRole, isolationContextFor, resolveMonitorConfig, resolvePermissions, } from './config.js';
 import { getAdapter } from './harness/registry.js';
 import { Tmux } from './tmux.js';
-import { createMonitor } from './monitor.js';
+import { createMonitor, probeIdentityPresence, } from './monitor.js';
 import { realExec, shq } from './exec.js';
 import { resolveIsolation } from './isolation/policy.js';
 import { selectIsolationBackend } from './isolation/registry.js';
@@ -24,6 +24,7 @@ import { RoleTurnArbiter } from './session/arbiter.js';
 import { ScheduledLoopManager, } from './loops/manager.js';
 import { FLEET_PROXY_CALLER_ENV, FLEET_PROXY_STATE_DIR_ENV, inheritCallerSpawnDefaults, } from './fleet-proxy.js';
 import { effectivePermissionMode } from './permissions.js';
+import { archiveTempState, markTempSupervisorActive, requestedTempStopReason, } from './temp-lifecycle.js';
 const defaultDeps = () => ({
     tmux: new Tmux(),
     exec: realExec,
@@ -347,6 +348,10 @@ function resolveConfigPath(dir, explicit) {
         return undefined;
     return readFileSync(marker, 'utf8').trim() || undefined;
 }
+/** Continuous authoritative absence required after an identity was observed. */
+export const TEMP_IDENTITY_CLOSE_DEBOUNCE_MS = 5_000;
+/** Lifecycle polling is deliberately slower than the 500ms stop-signal loop. */
+export const TEMP_IDENTITY_POLL_MS = 2_000;
 /** One session lifecycle. `runSupervised` (or a one-shot caller) drives it. */
 export async function runOnce(name, opts = {}, partialDeps = {}) {
     const deps = { ...defaultDeps(), ...partialDeps };
@@ -489,6 +494,7 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
     let unsubscribeRecovery;
     let monitorLoop;
     let acpStartupComplete = false;
+    let sessionClosed = false;
     let ownerChannel;
     let ownerBinder;
     const pendingFleetSpawnNotices = [];
@@ -600,17 +606,24 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
                 const steered = result.accepted
                     && (result.detail === 'injected' || result.detail === 'startedNewTurn');
                 const boundary = result.safeBoundary;
-                const boundaryDetail = boundary
+                const queuedAfterSteeringFailure = result.detail?.startsWith('steering rejected;') === true;
+                const boundaryDetail = boundary && queuedAfterSteeringFailure
                     ? boundary.state === 'timeout'
-                        ? `after_tool timed out after ${boundary.waitedMs}ms; steered without cancellation`
-                        : boundary.state === 'unsupported'
-                            ? 'after_tool unsupported; used non-cancelling queued delivery'
-                            : `after_tool ${boundary.state} delivery after ${boundary.waitedMs}ms`
-                    : result.detail;
+                        ? `after_tool timed out after ${boundary.waitedMs}ms; steering rejected, queued without cancellation`
+                        : `after_tool ${boundary.state} boundary after ${boundary.waitedMs}ms; steering rejected, queued without cancellation`
+                    : boundary
+                        ? boundary.state === 'timeout'
+                            ? `after_tool timed out after ${boundary.waitedMs}ms; steered without cancellation`
+                            : boundary.state === 'unsupported'
+                                ? 'after_tool unsupported; used non-cancelling queued delivery'
+                                : `after_tool ${boundary.state} delivery after ${boundary.waitedMs}ms`
+                        : result.detail;
                 return {
                     succeeded: result.succeeded || steered,
                     outcome: steered ? result.detail : result.outcome,
-                    detail: boundaryDetail,
+                    detail: result.succeeded || steered || !boundary
+                        ? boundaryDetail
+                        : [result.detail, boundaryDetail].filter(Boolean).join('; '),
                     ...(boundary ? { safeBoundary: boundary.state } : {}),
                 };
             },
@@ -753,10 +766,46 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
     monitorLoop ??= monitor?.run(pid);
     const start = deps.now();
     let nextLoopReloadAt = deps.now() + 30_000;
+    let nextIdentityPollAt = deps.now();
     let lastReloadError = '';
+    let identityObserved = false;
+    let identityAbsentSince;
+    let retirementReason;
     while (sessionHandle.isAlive()) {
-        await deps.sleep(2000);
+        await deps.sleep(temp ? 500 : 2000);
         const now = deps.now();
+        if (temp && deps.shouldStop?.()) {
+            retirementReason = requestedTempStopReason(dir) ?? 'supervisor-signal';
+            deps.log(`[${name}] temporary supervisor retirement requested (${retirementReason})`);
+            await sessionHandle.close();
+            sessionClosed = true;
+            break;
+        }
+        if (temp && now >= nextIdentityPollAt) {
+            nextIdentityPollAt = now + TEMP_IDENTITY_POLL_MS;
+            const presence = await probeIdentityPresence(role.identity, deps.fetch, resolvedMonitorDeps.env);
+            if (presence.state === 'present') {
+                identityObserved = true;
+                identityAbsentSince = undefined;
+            }
+            else if (presence.state === 'absent' && identityObserved) {
+                identityAbsentSince ??= now;
+                // Require a continuous, time-bounded run of authoritative absence.
+                // The first positive observation is the readiness gate: cold tmux
+                // starts may spend minutes loading the harness and briefing before the
+                // agent creates/binds its identity, and absence before then is not a
+                // close event. After readiness, debounce a real disappearance.
+                if (now - identityAbsentSince >= TEMP_IDENTITY_CLOSE_DEBOUNCE_MS) {
+                    retirementReason = 'identity-closed';
+                    deps.log(`[${name}] temporary identity '${role.identity}' closed; retiring session and supervisor`);
+                    await sessionHandle.close();
+                    sessionClosed = true;
+                    break;
+                }
+            }
+            else if (presence.state === 'unknown')
+                identityAbsentSince = undefined;
+        }
         if (reloadLoopConfig && now >= nextLoopReloadAt) {
             nextLoopReloadAt = now + 30_000;
             try {
@@ -791,7 +840,7 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
         await monitorLoop;
     }
     unsubscribeRecovery?.();
-    if (acpSession)
+    if (acpSession && !sessionClosed)
         await acpSession.close();
     const elapsed = (deps.now() - start) / 1000;
     // Establish what actually happened before deciding anything. Absence of a
@@ -832,7 +881,10 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
     }
     else
         deps.log(`[${name}] ${exitRecord.detail} (${elapsed.toFixed(0)}s) -> next start RESUMES context`);
-    return { elapsedSecs: elapsed, exit: exitRecord, rotated, mode, modelRecovery };
+    return {
+        elapsedSecs: elapsed, exit: exitRecord, rotated, mode, modelRecovery,
+        ...(retirementReason ? { retirementReason } : {}),
+    };
 }
 /**
  * The persistent supervisor for one permanent role: run child sessions in a
@@ -950,12 +1002,46 @@ function fastFailSecsFor(name, configPath) {
         return 20;
     }
 }
-/** Temp-agent entrypoint: run one session, then remove the temp dir. */
+/** Temp-agent entrypoint: run once, journal why it ended, then archive its evidence. */
 export async function runTemp(name, deps = {}) {
+    const dir = agentDir(name, true);
+    await markTempSupervisorActive(dir);
+    let signal;
+    const onTerm = () => { signal = 'SIGTERM'; };
+    const onInt = () => { signal = 'SIGINT'; };
+    process.on('SIGTERM', onTerm);
+    process.on('SIGINT', onInt);
+    let result;
+    let failure;
     try {
-        await runOnce(name, { temp: true }, deps);
+        result = await runOnce(name, { temp: true }, {
+            ...deps,
+            shouldStop: () => Boolean(signal) || (deps.shouldStop?.() ?? false),
+        });
+    }
+    catch (error) {
+        failure = error;
     }
     finally {
-        rmSync(agentDir(name, true), { recursive: true, force: true });
+        process.off('SIGTERM', onTerm);
+        process.off('SIGINT', onInt);
+        const requested = requestedTempStopReason(dir);
+        const reason = requested
+            ?? result?.retirementReason
+            ?? (signal ? 'supervisor-signal' : failure ? 'startup-failure' : 'session-ended');
+        // A service-manager stop can make the child connection close before the
+        // runner reaches its normal loop. That is still a successful requested
+        // retirement, not a startup failure.
+        const outcome = failure && !requested && !signal ? 'failed' : 'retired';
+        const detail = failure
+            ? (failure instanceof Error ? failure.message : String(failure))
+            : result
+                ? `${result.exit.detail}; elapsed=${result.elapsedSecs.toFixed(1)}s`
+                : 'temporary supervisor ended without an attempt result';
+        const archived = archiveTempState(name, reason, outcome, detail);
+        deps.log?.(`[${name}] temporary lifecycle ${outcome}: ${reason}`
+            + `${archived ? `; evidence archived at ${archived}` : '; state already archived'}`);
     }
+    if (failure)
+        throw failure;
 }

package/dist/session/acp.d.ts

@@ -2,7 +2,7 @@ import * as acp from '@agentclientprotocol/sdk';
 import type { CommonPermissions } from '../config.js';
 import { ConversationEventStore } from './conversation-store.js';
 import type { ConversationSnapshot, PromptOrigin, PromptReceipt, SubmitPromptCommand } from './conversation-types.js';
-import type { ConversationHandlePage, ExitRecord, QueuedPrompt, SessionEvent, RuntimeSelectorMetadata, SessionHandle, SessionSnapshot, SubmitPromptOptions, TurnCancellationSource, TurnOutcome, TurnResult } from './types.js';
+import type { ConversationHandlePage, ExitRecord, InterruptOutcome, QueuedPrompt, SessionEvent, RuntimeSelectorMetadata, SessionHandle, SessionSnapshot, SubmitPromptOptions, TurnCancellationSource, TurnOutcome, TurnResult } from './types.js';
 /** Bound safe-boundary waiting without turning a hung tool into cancellation. */
 export declare const AFTER_TOOL_BOUNDARY_TIMEOUT_MS = 120000;
 /** Server-generated typed provenance followed by the exact human-authored body. */
@@ -23,6 +23,8 @@ export interface AcpSessionOptions {
     log(line: string): void;
     /** Test seam for the cancel-escalation grace period; production uses the default. */
     cancelGraceMs?: number;
+    /** Test seam for SIGTERM -> SIGKILL escalation after an ignored cancellation. */
+    cancelTerminateGraceMs?: number;
     /** How long a pending permission may wait for a human before it expires. */
     permissionTimeoutMs?: number;
     /** Grace after the last controller detaches before the unattended policy applies. */
@@ -69,6 +71,15 @@ export declare class AcpSession implements SessionHandle {
     /** Armed when the last controller detaches; unattended policy applies on fire. */
     private controllerGrace?;
     private cancelEscalation?;
+    private cancelForceKill?;
+    private cancelRecoveryReason?;
+    /**
+     * Rejects the moment the adapter process is gone. Every in-flight ACP request
+     * races it, so a dead adapter can never leave a turn — and therefore a
+     * scheduled run's `activeRunId` or an admission claim — unsettled forever.
+     */
+    private readonly terminated;
+    private terminate;
     /** ACP-authenticated in-flight calls, including independently reserved permissions. */
     private readonly activeToolCalls;
     private readonly toolBoundaryWaiters;
@@ -95,8 +106,18 @@ export declare class AcpSession implements SessionHandle {
     private waitForToolBoundary;
     private recordAfterToolDelivery;
     /**
-     * Monitor-only safe-boundary delivery. Steering is the interruption: this
-     * path never calls session/cancel and never resolves a pending permission.
+     * Steering is an optional admission fast path, not the only safe way to
+     * deliver a wake. Codex can reject `_session/steering` while a long-running
+     * turn is between tools. Queue one ordinary, non-cancelling prompt in that
+     * case and wait for its terminal result. This keeps the monitor's cursor
+     * uncommitted until the wake really runs and, critically, keeps one rejected
+     * steering response from becoming a tight replay loop.
+     */
+    private steerOrQueueWake;
+    /**
+     * Monitor-only safe-boundary delivery. Steering is the preferred live
+     * insertion and rejected steering is queued: this path never calls
+     * session/cancel and never resolves a pending permission.
      */
     submitPromptAfterTool(text: string, options?: SubmitPromptOptions): Promise<TurnResult>;
     /**
@@ -115,8 +136,23 @@ export declare class AcpSession implements SessionHandle {
     /** Idempotent browser prompt admission (control v3 `submit_prompt_v2`). */
     submitPromptBrowser(command: SubmitPromptCommand): Promise<PromptReceipt>;
     submitPrompt(text: string, options?: SubmitPromptOptions): Promise<TurnResult>;
-    interrupt(source?: TurnCancellationSource): Promise<void>;
+    /**
+     * Explicit cancellation on behalf of a human or an operator. Forced recovery
+     * is reported as an outcome, never as a thrown failure: by the time this
+     * resolves the turn is over either way, and only the durable-ingress path
+     * (`queuePrompt({ interrupt: true })`) needs the typed error, because only it
+     * still owes an undelivered message a replay.
+     */
+    interrupt(source?: TurnCancellationSource): Promise<InterruptOutcome>;
     private cancelActive;
+    /**
+     * Do not admit work behind a turn whose adapter may already require restart.
+     * A cooperative adapter settles this promise immediately through runPrompt's
+     * finally block. A stubborn adapter receives SIGTERM at the deadline and
+     * SIGKILL after one more bounded grace; callers get a typed recovery error so
+     * durable ingress can leave the next request replayable for the resumed run.
+     */
+    private awaitCancellationSettlement;
     respondPermission(permissionId: string, optionId: string): boolean;
     /**
      * A v2 decision binds to the session generation it was shown under. A stale