@ours.network/fleet 0.17.0 → 0.17.2

package/dist/session/control.js

@@ -2,7 +2,7 @@ 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';
+import { SessionControlError, interruptOutcome } from './types.js';
 const MAX_LINE_BYTES = 64 * 1024;
 /** Commands that require protocol version 3. */
 const V3_COMMANDS = new Set([
@@ -253,10 +253,13 @@ export class RoleControlServer {
                     });
                     return;
                 }
-                case 'interrupt':
-                    await this.session.interrupt('local-console');
-                    this.write(socket, { version: 1, id: request.id, ok: true });
+                case 'interrupt': {
+                    // Forced recovery cancelled the turn just as surely as a cooperative
+                    // stop did. Report HOW, never as a failed operation.
+                    const outcome = interruptOutcome(await this.session.interrupt('local-console'));
+                    this.write(socket, { version: 1, id: request.id, ok: true, result: outcome });
                     return;
+                }
                 case 'loop_status': {
                     if (!this.loopManager)
                         throw new SessionControlError('rejected', 'scheduled loops are unavailable for this role');
@@ -396,8 +399,11 @@ export class RoleControlServer {
                         this.write(socket, { version: 1, id: request.id, ok: true, result: existing });
                         return;
                     }
-                    await this.session.interrupt('local-console');
-                    const receipt = { accepted: true, commandId: request.commandId, at: new Date().toISOString() };
+                    const outcome = interruptOutcome(await this.session.interrupt('local-console'));
+                    const receipt = {
+                        accepted: true, commandId: request.commandId, at: new Date().toISOString(),
+                        ...outcome,
+                    };
                     this.interruptCommands.set(request.commandId, receipt);
                     if (this.interruptCommands.size > 200) {
                         const oldest = this.interruptCommands.keys().next().value;

package/dist/session/event-log.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Crash-safe JSONL primitives for the session event stream.
+ *
+ * The 06:32 disk-full incident showed what an unguarded `appendFileSync` does
+ * under ENOSPC: the kernel short-writes, the already-written prefix stays on
+ * disk, and the next successful append lands directly on it — fusing a partial
+ * record with a valid later one into a single unparseable line. These helpers
+ * make an append all-or-nothing, keep a damaged byte range from ever swallowing
+ * a later record, and describe damage rather than quietly dropping it.
+ *
+ * Single-writer assumption: rollback truncates back to the size observed at the
+ * start of the append, so exactly one process may append to a given path.
+ */
+/** The syscall surface an append needs, injectable so faults can be forced deterministically. */
+export interface LogIo {
+    openSync(path: string, flags: string, mode?: number): number;
+    fstatSync(fd: number): {
+        size: number;
+    };
+    readSync(fd: number, buffer: Buffer, offset: number, length: number, position: number): number;
+    writeSync(fd: number, buffer: Buffer, offset: number, length: number): number;
+    ftruncateSync(fd: number, length: number): void;
+    closeSync(fd: number): void;
+}
+export declare const nodeLogIo: LogIo;
+export declare class AtomicAppendError extends Error {
+    readonly rollbackFailed: boolean;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, rollbackFailed: boolean, cause?: unknown | undefined);
+}
+export interface AppendResult {
+    /** True when a dangling partial record was closed off before this line was written. */
+    repairedBoundary: boolean;
+}
+export interface AppendOptions {
+    io?: LogIo;
+    /** Total attempts, including the first. Bounded so a full disk cannot spin. */
+    maxAttempts?: number;
+    mode?: number;
+}
+/**
+ * Append one line, all or nothing. A failed write is rolled back to the byte
+ * length observed before it started, so a partial record never persists; if the
+ * file already ends mid-record (damage from before this fix), the line is put on
+ * a fresh line so it cannot fuse with the damaged bytes.
+ */
+export declare function appendLineAtomic(path: string, line: string, options?: AppendOptions): AppendResult;
+export type DamageReason = 'truncated_tail' | 'interior_corruption';
+export interface DamagedLine {
+    /** 1-based line number in the file as read. */
+    lineNumber: number;
+    /** True byte length of the damaged line, even when `raw` is capped. */
+    bytes: number;
+    reason: DamageReason;
+    /** The damaged bytes, capped for storage; `truncatedEvidence` says when. */
+    raw: string;
+    truncatedEvidence: boolean;
+}
+/** A run of sequence numbers that is simply gone — never recoverable, only reportable. */
+export interface SequenceGap {
+    afterSeq: number;
+    beforeSeq: number;
+    missing: number;
+}
+export interface LogRecord {
+    version: 1;
+    seq: number;
+    [key: string]: unknown;
+}
+export interface ReadLogResult {
+    /** Records this version understands and can replay. */
+    records: LogRecord[];
+    /**
+     * Sequence numbers claimed by every readable entry in file order, whatever
+     * its version. A record written by a newer version is not replayable here,
+     * but it did occupy its number: counting it is what keeps a forward-compatible
+     * file from looking like it has a hole, and keeps continuation past it.
+     */
+    sequence: number[];
+    /** Highest sequence still readable anywhere in the file, for monotonic continuation. */
+    maxSeq: number;
+    damaged: DamagedLine[];
+    gaps: SequenceGap[];
+}
+/**
+ * Read the log line by line. One bad line costs exactly that line: everything
+ * before and after it is kept, and the damage is described rather than dropped.
+ */
+export declare function readLog(path: string): ReadLogResult;
+/**
+ * Missing sequence numbers between consecutive records. Records that parse
+ * perfectly still leave a hole when the writes between them never landed, so
+ * this is computed over whatever ordered run the caller cares about — including
+ * a rotated stream followed by its live successor, where the hole falls on the
+ * boundary and neither file can see it alone.
+ */
+export declare function findSequenceGaps(sequence: number[]): SequenceGap[];
+export interface QuarantineResult {
+    quarantined: boolean;
+    /** Present when the sidecar could not be written; the source file is untouched either way. */
+    error?: string;
+    sidecar: string;
+}
+/**
+ * Copy damaged bytes to a sidecar for later forensics. The damaged file itself
+ * is never read-modify-written, and a sidecar that cannot be created is reported
+ * rather than retried into the event writer.
+ */
+export declare function quarantineDamage(path: string, damaged: DamagedLine[], source?: string): QuarantineResult;

package/dist/session/event-log.js

@@ -0,0 +1,247 @@
+import { closeSync, existsSync, fstatSync, ftruncateSync, openSync, readFileSync, readSync, writeSync, } from 'node:fs';
+export const nodeLogIo = {
+    openSync: (path, flags, mode) => openSync(path, flags, mode),
+    fstatSync: fd => fstatSync(fd),
+    readSync: (fd, buffer, offset, length, position) => readSync(fd, buffer, offset, length, position),
+    writeSync: (fd, buffer, offset, length) => writeSync(fd, buffer, offset, length),
+    ftruncateSync: (fd, length) => ftruncateSync(fd, length),
+    closeSync: fd => closeSync(fd),
+};
+const NEWLINE = 0x0a;
+/** Enough to hold a whole event line as evidence without letting one record dominate the sidecar. */
+const MAX_RAW_EVIDENCE_BYTES = 8 * 1024;
+const MAX_QUARANTINE_BYTES = 1024 * 1024;
+export class AtomicAppendError extends Error {
+    rollbackFailed;
+    cause;
+    constructor(message, rollbackFailed, cause) {
+        super(message);
+        this.rollbackFailed = rollbackFailed;
+        this.cause = cause;
+        this.name = 'AtomicAppendError';
+    }
+}
+/**
+ * Append one line, all or nothing. A failed write is rolled back to the byte
+ * length observed before it started, so a partial record never persists; if the
+ * file already ends mid-record (damage from before this fix), the line is put on
+ * a fresh line so it cannot fuse with the damaged bytes.
+ */
+export function appendLineAtomic(path, line, options = {}) {
+    const io = options.io ?? nodeLogIo;
+    const maxAttempts = Math.max(1, options.maxAttempts ?? 2);
+    const payload = line.endsWith('\n') ? line : line + '\n';
+    let lastError;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        let fd;
+        let sizeBefore = 0;
+        try {
+            fd = io.openSync(path, 'a+', options.mode ?? 0o600);
+            sizeBefore = io.fstatSync(fd).size;
+            const repairedBoundary = sizeBefore > 0 && !endsWithNewline(io, fd, sizeBefore);
+            const buffer = Buffer.from(repairedBoundary ? '\n' + payload : payload, 'utf8');
+            let written = 0;
+            try {
+                while (written < buffer.length) {
+                    const advanced = io.writeSync(fd, buffer, written, buffer.length - written);
+                    // A write that accepts nothing would spin forever and never reach the
+                    // bounded-retry logic, so it fails here instead.
+                    if (advanced <= 0)
+                        throw new Error(`write made no progress at byte ${written} of ${buffer.length}`);
+                    written += advanced;
+                }
+            }
+            catch (writeError) {
+                throw rollback(io, fd, sizeBefore, writeError);
+            }
+            return { repairedBoundary };
+        }
+        catch (error) {
+            lastError = error;
+            // A failed rollback leaves bytes we cannot account for; retrying would
+            // append on top of them, so stop and let the caller report it.
+            if (error instanceof AtomicAppendError && error.rollbackFailed)
+                break;
+        }
+        finally {
+            if (fd !== undefined) {
+                try {
+                    io.closeSync(fd);
+                }
+                catch { /* the write outcome is what matters */ }
+            }
+        }
+    }
+    throw lastError;
+}
+function endsWithNewline(io, fd, size) {
+    const tail = Buffer.alloc(1);
+    const read = io.readSync(fd, tail, 0, 1, size - 1);
+    // An unreadable tail is treated as damaged: adding a newline is always safe.
+    return read === 1 && tail[0] === NEWLINE;
+}
+function rollback(io, fd, sizeBefore, writeError) {
+    const detail = writeError instanceof Error ? writeError.message : String(writeError);
+    try {
+        io.ftruncateSync(fd, sizeBefore);
+        return new AtomicAppendError(detail, false, writeError);
+    }
+    catch (truncateError) {
+        const reason = truncateError instanceof Error ? truncateError.message : String(truncateError);
+        return new AtomicAppendError(`${detail} (rollback failed: ${reason})`, true, writeError);
+    }
+}
+/**
+ * Read the log line by line. One bad line costs exactly that line: everything
+ * before and after it is kept, and the damage is described rather than dropped.
+ */
+export function readLog(path) {
+    const empty = { records: [], sequence: [], maxSeq: 0, damaged: [], gaps: [] };
+    if (!existsSync(path))
+        return empty;
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return empty;
+    }
+    if (raw === '')
+        return empty;
+    const terminated = raw.endsWith('\n');
+    const segments = raw.split('\n');
+    if (terminated)
+        segments.pop();
+    const records = [];
+    const sequence = [];
+    const damaged = [];
+    let maxSeq = 0;
+    segments.forEach((segment, index) => {
+        if (segment.trim() === '')
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(segment);
+        }
+        catch {
+            const isFinalSegment = index === segments.length - 1;
+            damaged.push({
+                lineNumber: index + 1,
+                bytes: Buffer.byteLength(segment, 'utf8'),
+                // An unterminated final line is a write that never committed; anything
+                // else sits between records that did, so it is interior corruption.
+                reason: isFinalSegment && !terminated ? 'truncated_tail' : 'interior_corruption',
+                raw: segment.slice(0, MAX_RAW_EVIDENCE_BYTES),
+                truncatedEvidence: segment.length > MAX_RAW_EVIDENCE_BYTES,
+            });
+            return;
+        }
+        // Unknown versions are forward compatibility, not damage: they are not
+        // replayed here, but they did claim their sequence number, so they still
+        // count towards ordering and continuation.
+        const seq = sequenceOf(parsed);
+        if (seq === undefined)
+            return;
+        sequence.push(seq);
+        if (seq > maxSeq)
+            maxSeq = seq;
+        if (isLogRecord(parsed))
+            records.push(parsed);
+    });
+    return { records, sequence, maxSeq, damaged, gaps: findSequenceGaps(sequence) };
+}
+/** The sequence a readable entry claims, whatever version wrote it. */
+function sequenceOf(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const seq = value.seq;
+    return typeof seq === 'number' && Number.isFinite(seq) ? seq : undefined;
+}
+function isLogRecord(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return candidate.version === 1 && typeof candidate.seq === 'number';
+}
+/**
+ * Missing sequence numbers between consecutive records. Records that parse
+ * perfectly still leave a hole when the writes between them never landed, so
+ * this is computed over whatever ordered run the caller cares about — including
+ * a rotated stream followed by its live successor, where the hole falls on the
+ * boundary and neither file can see it alone.
+ */
+export function findSequenceGaps(sequence) {
+    const gaps = [];
+    for (let i = 1; i < sequence.length; i++) {
+        const afterSeq = sequence[i - 1];
+        const beforeSeq = sequence[i];
+        if (beforeSeq > afterSeq + 1)
+            gaps.push({ afterSeq, beforeSeq, missing: beforeSeq - afterSeq - 1 });
+    }
+    return gaps;
+}
+/**
+ * Copy damaged bytes to a sidecar for later forensics. The damaged file itself
+ * is never read-modify-written, and a sidecar that cannot be created is reported
+ * rather than retried into the event writer.
+ */
+export function quarantineDamage(path, damaged, source = path) {
+    const sidecar = path + '.corrupt';
+    if (damaged.length === 0)
+        return { quarantined: false, sidecar };
+    let alreadyHeld;
+    try {
+        alreadyHeld = existingEvidence(sidecar);
+    }
+    catch (error) {
+        return { quarantined: false, error: describe(error), sidecar };
+    }
+    const pending = damaged.filter(line => !alreadyHeld.has(evidenceKey(source, line.raw)));
+    if (pending.length === 0)
+        return { quarantined: true, sidecar };
+    for (const line of pending) {
+        try {
+            appendLineAtomic(sidecar, JSON.stringify({
+                quarantinedAt: new Date().toISOString(),
+                source,
+                lineNumber: line.lineNumber,
+                bytes: line.bytes,
+                reason: line.reason,
+                truncatedEvidence: line.truncatedEvidence,
+                raw: line.raw,
+            }));
+        }
+        catch (error) {
+            return { quarantined: false, error: describe(error), sidecar };
+        }
+    }
+    return { quarantined: true, sidecar };
+}
+function existingEvidence(sidecar) {
+    const held = new Set();
+    if (!existsSync(sidecar))
+        return held;
+    const raw = readFileSync(sidecar, 'utf8');
+    if (raw.length > MAX_QUARANTINE_BYTES)
+        throw new Error(`quarantine sidecar is full (${raw.length} bytes)`);
+    for (const line of raw.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        try {
+            const entry = JSON.parse(line);
+            if (typeof entry.raw === 'string' && typeof entry.source === 'string') {
+                held.add(evidenceKey(entry.source, entry.raw));
+            }
+        }
+        catch { /* an unreadable sidecar entry only costs us dedup */ }
+    }
+    return held;
+}
+/** Damage is identified by its bytes and which file they came from, so the live
+ *  stream and its rotated predecessor are never confused for each other. */
+function evidenceKey(source, raw) {
+    return `${source}${raw}`;
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/session/events.d.ts

@@ -1,14 +1,35 @@
+import { type DamagedLine, type SequenceGap } from './event-log.js';
 import type { SessionEvent, SessionEventKind } from './types.js';
+/** What the on-disk stream is known to have lost or mangled. Never optimistic. */
+export interface StreamIntegrity {
+    healthy: boolean;
+    damaged: DamagedLine[];
+    gaps: SequenceGap[];
+    quarantined: boolean;
+    quarantineError?: string;
+    /** Appends that failed outright; their events survive in memory only. */
+    writeFailures: number;
+    lastWriteError?: string;
+    /** Appends that had to close off a dangling partial record first. */
+    boundaryRepairs: number;
+    rotationFailed: boolean;
+}
 /** 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;
+    private readonly integrityState;
+    private readonly rotatedPath;
     constructor(path: string);
     emit(kind: SessionEventKind, fields?: Omit<SessionEvent, 'version' | 'seq' | 'at' | 'kind'>): SessionEvent;
     since(seq: number): SessionEvent[];
     subscribe(listener: (event: SessionEvent) => void): () => void;
+    /** Snapshot of what is known to be wrong with the persisted stream. */
+    integrity(): StreamIntegrity;
+    private persist;
     private restore;
+    private describeLoss;
     private rotateIfNeeded;
 }

package/dist/session/events.js

@@ -1,4 +1,6 @@
-import { appendFileSync, existsSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, renameSync, statSync } from 'node:fs';
+import { basename } from 'node:path';
+import { appendLineAtomic, findSequenceGaps, quarantineDamage, readLog, } from './event-log.js';
 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. */
@@ -7,8 +9,14 @@ export class SessionEvents {
     seq = 0;
     events = [];
     listeners = new Set();
+    integrityState = {
+        healthy: true, damaged: [], gaps: [], quarantined: false,
+        writeFailures: 0, boundaryRepairs: 0, rotationFailed: false,
+    };
+    rotatedPath;
     constructor(path) {
         this.path = path;
+        this.rotatedPath = path + '.1';
         this.restore();
     }
     emit(kind, fields = {}) {
@@ -22,16 +30,7 @@ export class SessionEvents {
         this.events.push(event);
         if (this.events.length > MAX_EVENTS)
             this.events.shift();
-        try {
-            this.rotateIfNeeded();
-            // Owner-visible commentary remains live/in-memory for the authenticated
-            // bridge, but its plaintext must not become diagnostic state on disk.
-            const persisted = event.kind === 'agent_text' && event.messagePhase === 'commentary'
-                ? { ...event, text: '[assistant commentary redacted]' }
-                : event;
-            appendFileSync(this.path, JSON.stringify(persisted) + '\n', { mode: 0o600 });
-        }
-        catch { /* diagnostics must never terminate a role */ }
+        this.persist(event);
         for (const listener of this.listeners)
             listener(event);
         return event;
@@ -43,30 +42,110 @@ export class SessionEvents {
         this.listeners.add(listener);
         return () => this.listeners.delete(listener);
     }
-    restore() {
+    /** Snapshot of what is known to be wrong with the persisted stream. */
+    integrity() {
+        return { ...this.integrityState, damaged: [...this.integrityState.damaged], gaps: [...this.integrityState.gaps] };
+    }
+    persist(event) {
+        this.rotateIfNeeded();
+        // Owner-visible commentary remains live/in-memory for the authenticated
+        // bridge, but its plaintext must not become diagnostic state on disk.
+        const persisted = event.kind === 'agent_text' && event.messagePhase === 'commentary'
+            ? { ...event, text: '[assistant commentary redacted]' }
+            : event;
         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);
-                }
+            const { repairedBoundary } = appendLineAtomic(this.path, JSON.stringify(persisted));
+            if (repairedBoundary) {
+                this.integrityState.boundaryRepairs++;
+                this.integrityState.healthy = false;
             }
         }
-        catch { /* begin a fresh projection if the diagnostic file is corrupt */ }
+        catch (error) {
+            // Diagnostics must never terminate a role, but a silent loss is how the
+            // 06:32 incident stayed invisible for an hour — record it instead.
+            this.integrityState.writeFailures++;
+            this.integrityState.lastWriteError = error instanceof Error ? error.message : String(error);
+            this.integrityState.healthy = false;
+        }
+    }
+    restore() {
+        // Rotation renames the live stream to `.1` and only then starts a new one.
+        // A crash in that window leaves no live file at all, so reading only the
+        // live path would restart at seq 1 and re-issue numbers `.1` already holds.
+        const rotated = readLog(this.rotatedPath);
+        const live = readLog(this.path);
+        const records = [...rotated.records, ...live.records];
+        for (const record of records.slice(-MAX_EVENTS))
+            this.events.push(record);
+        // Monotonic even across damage and rotation: a sequence number already on
+        // disk, readable or not, is never handed out again.
+        this.seq = Math.max(this.seq, rotated.maxSeq, live.maxSeq);
+        const damaged = [...rotated.damaged, ...live.damaged];
+        // Records that parse perfectly still leave a hole when the writes between
+        // them never landed, and a hole on the rotated/live boundary is invisible to
+        // either file alone — so gaps are computed over the combined ordered run,
+        // and reported whether or not any bytes were mangled.
+        const gaps = findSequenceGaps([...rotated.sequence, ...live.sequence]);
+        if (damaged.length === 0 && gaps.length === 0)
+            return;
+        this.integrityState.healthy = false;
+        this.integrityState.damaged = damaged;
+        this.integrityState.gaps = gaps;
+        let error;
+        if (damaged.length > 0) {
+            const results = [
+                quarantineDamage(this.path, rotated.damaged, this.rotatedPath),
+                quarantineDamage(this.path, live.damaged, this.path),
+            ].filter(result => result.quarantined || result.error);
+            this.integrityState.quarantined = results.every(result => result.quarantined);
+            error = results.find(result => result.error)?.error;
+            if (error)
+                this.integrityState.quarantineError = error;
+        }
+        // Reported through the ordinary stream so it reaches replay and audit;
+        // never through a second attempt at the writer that just failed.
+        this.emit('error', { text: this.describeLoss(damaged, gaps, error) });
+    }
+    describeLoss(damaged, gaps, error) {
+        const interior = damaged.filter(line => line.reason === 'interior_corruption');
+        const tails = damaged.filter(line => line.reason === 'truncated_tail');
+        const parts = ['event stream integrity'];
+        if (interior.length) {
+            parts.push(`${interior.length} interior corruption at line ${interior.map(l => l.lineNumber).join(', ')}`);
+        }
+        if (tails.length)
+            parts.push(`${tails.length} truncated tail discarded`);
+        const missing = gaps.reduce((total, gap) => total + gap.missing, 0);
+        if (missing) {
+            const span = gaps.map(gap => `${gap.afterSeq}..${gap.beforeSeq}`).join(', ');
+            parts.push(`${missing} record${missing === 1 ? '' : 's'} lost between seq ${span} (irrecoverable)`);
+        }
+        if (damaged.length) {
+            parts.push(this.integrityState.quarantined
+                ? `damaged bytes quarantined to ${basename(this.path)}.corrupt`
+                : `damaged bytes NOT quarantined${error ? ` (${error})` : ''}`);
+        }
+        return parts.join('; ');
     }
     rotateIfNeeded() {
-        if (!existsSync(this.path) || statSync(this.path).size < MAX_EVENT_FILE_BYTES)
+        if (!existsSync(this.path))
+            return;
+        try {
+            if (statSync(this.path).size < MAX_EVENT_FILE_BYTES)
+                return;
+        }
+        catch {
             return;
-        const rotated = this.path + '.1';
+        }
         try {
-            renameSync(this.path, rotated);
+            renameSync(this.path, this.rotatedPath);
+            this.integrityState.rotationFailed = false;
         }
         catch {
-            writeFileSync(this.path, '', { mode: 0o600 });
+            // Fail closed: the previous fallback truncated the live stream, which
+            // destroys exactly the evidence an incident needs.
+            this.integrityState.rotationFailed = true;
+            this.integrityState.healthy = false;
         }
     }
 }

package/dist/session/tmux.d.ts

@@ -1,5 +1,5 @@
 import type { Tmux } from '../tmux.js';
-import type { ExitRecord, QueuedPrompt, SessionEvent, SessionHandle, SessionSnapshot, SubmitPromptOptions, TurnResult } from './types.js';
+import type { ExitRecord, InterruptOutcome, QueuedPrompt, SessionEvent, SessionHandle, SessionSnapshot, SubmitPromptOptions, TurnResult } from './types.js';
 /** SessionHandle adapter for the existing tmux transport. */
 export declare class TmuxSession implements SessionHandle {
     private readonly name;
@@ -12,7 +12,8 @@ export declare class TmuxSession implements SessionHandle {
     snapshot(): SessionSnapshot;
     queuePrompt(text: string, options?: SubmitPromptOptions): Promise<QueuedPrompt>;
     submitPrompt(text: string, options?: SubmitPromptOptions): Promise<TurnResult>;
-    interrupt(): Promise<void>;
+    /** A keystroke is delivered or it throws; tmux offers no forced-recovery path. */
+    interrupt(): Promise<InterruptOutcome>;
     respondPermission(): boolean;
     eventsSince(): SessionEvent[];
     subscribe(): () => void;

package/dist/session/tmux.js

@@ -51,8 +51,10 @@ export class TmuxSession {
             throw error;
         }
     }
+    /** A keystroke is delivered or it throws; tmux offers no forced-recovery path. */
     async interrupt() {
         await this.tmux.sendKey(this.name, 'C-c');
+        return { state: 'settled' };
     }
     respondPermission() {
         return false;