@ours.network/fleet 0.17.1 → 0.17.2

package/dist/session/acp.js

@@ -7,8 +7,9 @@ import * as acp from '@agentclientprotocol/sdk';
 import { normalizeSessionUpdate } from './conversation-normalizer.js';
 import { ConversationEventStore } from './conversation-store.js';
 import { SessionEvents } from './events.js';
-import { SessionControlError, classifyChildExit, turnResult } from './types.js';
+import { ACP_CANCEL_DEADLINE_EXCEEDED, SessionControlError, classifyChildExit, turnResult, } from './types.js';
 const CANCEL_SETTLE_GRACE_MS = 15_000;
+const CANCEL_TERMINATE_GRACE_MS = 5_000;
 /** A permission no human answered is eventually a decision nobody made. */
 const PERMISSION_TIMEOUT_MS = 10 * 60_000;
 /** Spec §4.3: 10-15 s before a vanished controller triggers the unattended policy. */
@@ -214,6 +215,15 @@ export class AcpSession {
     /** Armed when the last controller detaches; unattended policy applies on fire. */
     controllerGrace;
     cancelEscalation;
+    cancelForceKill;
+    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.
+     */
+    terminated;
+    terminate;
     /** ACP-authenticated in-flight calls, including independently reserved permissions. */
     activeToolCalls = new Map();
     toolBoundaryWaiters = new Set();
@@ -228,16 +238,29 @@ export class AcpSession {
             roleId: options.name, log: line => options.log(`[${options.name}] ${line}`),
         });
         this.sessionFile = join(options.stateDir, '.acp-session-id');
+        this.terminated = new Promise((_resolve, reject) => { this.terminate = reject; });
+        // Nothing awaits this promise until a request races it; an unobserved
+        // rejection here must never take the whole runner down.
+        this.terminated.catch(() => undefined);
         child.stderr.on('data', chunk => options.log(`[${options.name}] acp: ${String(chunk).trimEnd()}`));
         child.once('exit', (code, signal) => {
+            if (this.cancelForceKill)
+                clearTimeout(this.cancelForceKill);
+            this.cancelForceKill = undefined;
             // Record the child's real exit code/signal. The tmux path can only see a
             // shell's `$?`; here the truth is available, so keep it.
-            this.exit = classifyChildExit(code, signal);
+            const classified = classifyChildExit(code, signal);
+            this.exit = this.cancelRecoveryReason
+                ? { ...classified, detail: `${this.cancelRecoveryReason}; ${classified.detail}` }
+                : classified;
             options.log(`[${options.name}] acp: agent exited (${code ?? signal ?? 'unknown'})`);
             if (this.readiness !== 'failed') {
                 this.readiness = 'failed';
                 this.lastError = `ACP agent ${this.exit.detail}`;
             }
+            // A request whose peer no longer exists will never answer. Fail it here
+            // rather than trusting the transport to notice the closed stream.
+            this.terminate(new SessionControlError('offline', `ACP agent ${this.exit.detail}`));
             this.events.emit('state', { status: 'failed', text: this.lastError });
             this.conversation.appendSafe({
                 kind: 'session.state', sessionGeneration: this.sessionGeneration,
@@ -319,7 +342,10 @@ export class AcpSession {
         }
     }
     isAlive() {
-        return this.child.exitCode === null && !this.child.killed;
+        // child.killed only means kill() successfully SENT a signal. A process may
+        // ignore SIGTERM and remain alive. exitCode or signalCode is the actual
+        // terminal fact (signal exits deliberately leave exitCode null).
+        return this.child.exitCode === null && (this.child.signalCode ?? null) === null;
     }
     snapshot() {
         return {
@@ -425,8 +451,28 @@ export class AcpSession {
         });
     }
     /**
-     * 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.
+     */
+    async steerOrQueueWake(text, options) {
+        const steered = await this.steerPrompt(text);
+        if (steered.accepted || steered.detail !== 'ACP steering failed'
+            || this.closing || !this.isAlive())
+            return steered;
+        const queued = await this.submitPrompt(text, { ...options, interrupt: false, steer: false });
+        return {
+            ...queued,
+            detail: `steering rejected; queued delivery ${queued.detail ?? queued.outcome}`,
+        };
+    }
+    /**
+     * 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.
      */
     async submitPromptAfterTool(text, options = {}) {
         if (this.closing || !this.isAlive())
@@ -443,7 +489,7 @@ export class AcpSession {
         }
         if (initialToolCount === 0) {
             this.recordAfterToolDelivery('direct', 0, 0);
-            const result = await this.steerPrompt(text);
+            const result = await this.steerOrQueueWake(text, options);
             return { ...result, safeBoundary: { state: 'direct', waitedMs: 0, activeToolCount: 0 } };
         }
         this.recordAfterToolDelivery('deferred', initialToolCount, 0);
@@ -464,7 +510,7 @@ export class AcpSession {
         const state = atBoundary ? 'after_tool' : 'timeout';
         const remainingToolCount = this.activeToolCalls.size;
         this.recordAfterToolDelivery(state, remainingToolCount, waitedMs);
-        const result = await this.steerPrompt(text);
+        const result = await this.steerOrQueueWake(text, options);
         return {
             ...result,
             safeBoundary: { state, waitedMs, activeToolCount: remainingToolCount },
@@ -476,7 +522,9 @@ export class AcpSession {
      * for it is what turned a busy agent into a timeout and then into "dead".
      */
     async queuePrompt(text, options = {}) {
-        if (!this.sessionId || !this.isAlive())
+        if (this.cancelRecoveryReason)
+            throw new SessionControlError('control-unavailable', 'ACP adapter restart is in progress after the cancellation deadline', ACP_CANCEL_DEADLINE_EXCEEDED);
+        if (this.closing || !this.sessionId || !this.isAlive())
             throw new SessionControlError('offline', this.lastError ?? 'ACP session is offline');
         if (options.interrupt)
             await this.cancelActive(options.interruptSource ?? 'local-console');
@@ -570,8 +618,24 @@ export class AcpSession {
             throw error;
         }
     }
+    /**
+     * 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.
+     */
     async interrupt(source = 'local-console') {
-        await this.cancelActive(source);
+        try {
+            await this.cancelActive(source);
+            return { state: 'settled' };
+        }
+        catch (error) {
+            if (error instanceof SessionControlError
+                && error.reasonCode === ACP_CANCEL_DEADLINE_EXCEEDED)
+                return { state: 'forced', reasonCode: ACP_CANCEL_DEADLINE_EXCEEDED };
+            throw error;
+        }
     }
     async cancelActive(source) {
         if (!this.sessionId)
@@ -594,21 +658,66 @@ export class AcpSession {
                 acpSessionId: this.sessionId, promptId: active.id, turnId: active.id,
                 payload: { cancellationSource: source },
             });
-            if (this.cancelEscalation)
-                clearTimeout(this.cancelEscalation);
-            const turnId = active.id;
+        }
+        for (const [permissionId, pending] of [...this.pendingPermissions])
+            this.settlePendingAutomatically(permissionId, pending, 'cancelled', undefined, 'the turn was cancelled while this request was pending');
+        if (active && this.activeTurn === active) {
+            active.cancellationWait ??= this.awaitCancellationSettlement(active);
+            await active.cancellationWait;
+        }
+    }
+    /**
+     * 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.
+     */
+    awaitCancellationSettlement(active) {
+        const settleMs = this.options.cancelGraceMs ?? CANCEL_SETTLE_GRACE_MS;
+        const deadline = new Promise((resolve, reject) => {
             this.cancelEscalation = setTimeout(() => {
-                if (this.activeTurn?.id !== turnId || !this.isAlive())
+                // Both bail-outs must SETTLE the race. Returning silently once left the
+                // caller — and the arbiter's exclusive tail behind it — awaiting a
+                // promise nothing would ever resolve.
+                if (this.activeTurn !== active) {
+                    resolve();
                     return;
-                this.lastError = 'ACP turn ignored cancellation; restarting adapter';
-                this.options.log(`[${this.options.name}] ${this.lastError}`);
-                this.events.emit('error', { turnId, origin: active.origin, text: this.lastError });
+                }
+                if (!this.isAlive()) {
+                    resolve();
+                    return;
+                }
+                active.cancellationDeadlineExceeded = true;
+                this.cancelRecoveryReason = ACP_CANCEL_DEADLINE_EXCEEDED;
+                this.readiness = 'failed';
+                this.lastError = `${ACP_CANCEL_DEADLINE_EXCEEDED}: ACP turn did not settle within ${settleMs}ms`;
+                this.options.log(`[${this.options.name}] ${this.lastError}; restarting adapter with resume`);
+                this.events.emit('error', {
+                    turnId: active.id, origin: active.origin, status: ACP_CANCEL_DEADLINE_EXCEEDED,
+                    text: this.lastError,
+                });
+                this.conversation.appendSafe({
+                    kind: 'session.state', sessionGeneration: this.sessionGeneration,
+                    acpSessionId: this.sessionId,
+                    promptId: active.id, turnId: active.id,
+                    payload: { status: 'failed', detail: this.lastError },
+                });
                 this.child.kill('SIGTERM');
-            }, this.options.cancelGraceMs ?? CANCEL_SETTLE_GRACE_MS);
+                const terminateMs = this.options.cancelTerminateGraceMs ?? CANCEL_TERMINATE_GRACE_MS;
+                this.cancelForceKill = setTimeout(() => {
+                    if (this.child.exitCode === null) {
+                        this.options.log(`[${this.options.name}] ${ACP_CANCEL_DEADLINE_EXCEEDED}: `
+                            + `adapter ignored SIGTERM for ${terminateMs}ms; sending SIGKILL`);
+                        this.child.kill('SIGKILL');
+                    }
+                }, terminateMs);
+                this.cancelForceKill.unref?.();
+                reject(new SessionControlError('control-unavailable', 'ACP adapter restart is in progress after the cancellation deadline', ACP_CANCEL_DEADLINE_EXCEEDED));
+            }, settleMs);
             this.cancelEscalation.unref?.();
-        }
-        for (const [permissionId, pending] of [...this.pendingPermissions])
-            this.settlePendingAutomatically(permissionId, pending, 'cancelled', undefined, 'the turn was cancelled while this request was pending');
+        });
+        return Promise.race([active.settled, deadline]);
     }
     respondPermission(permissionId, optionId) {
         const pending = this.pendingPermissions.get(permissionId);
@@ -740,6 +849,9 @@ export class AcpSession {
         if (this.cancelEscalation)
             clearTimeout(this.cancelEscalation);
         this.cancelEscalation = undefined;
+        if (this.cancelForceKill)
+            clearTimeout(this.cancelForceKill);
+        this.cancelForceKill = undefined;
         if (this.controllerGrace)
             clearTimeout(this.controllerGrace);
         this.controllerGrace = undefined;
@@ -752,6 +864,8 @@ export class AcpSession {
         this.connection.close();
         if (this.isAlive())
             this.child.kill('SIGTERM');
+        // The transport is gone: nothing still awaiting an ACP answer can get one.
+        this.terminate(new SessionControlError('offline', 'the ACP session was closed'));
         this.conversation.appendSafe({
             kind: 'session.state', sessionGeneration: this.sessionGeneration,
             acpSessionId: this.sessionId, payload: { status: 'offline' },
@@ -839,7 +953,9 @@ export class AcpSession {
         if (!this.sessionId || !this.isAlive())
             return turnResult(false, 'failed', this.lastError ?? 'ACP session is offline');
         this.readiness = 'running';
-        this.activeTurn = { id: turnId, output: '', origin };
+        let settle;
+        const settled = new Promise(resolve => { settle = resolve; });
+        this.activeTurn = { id: turnId, output: '', origin, settled, settle };
         this.events.emit('state', { turnId, status: 'running', origin });
         this.conversation.appendSafe({
             kind: 'prompt.started', sessionGeneration: this.sessionGeneration,
@@ -847,10 +963,13 @@ export class AcpSession {
             source: conversationSource(origin).source, payload: {},
         });
         try {
-            const response = await this.connection.agent.request(acp.methods.agent.session.prompt, {
-                sessionId: this.sessionId,
-                prompt: promptContentBlocks(text, origin),
-            });
+            const response = await Promise.race([
+                this.connection.agent.request(acp.methods.agent.session.prompt, {
+                    sessionId: this.sessionId,
+                    prompt: promptContentBlocks(text, origin),
+                }),
+                this.terminated,
+            ]);
             this.readiness = 'idle';
             const cancellationSource = this.activeTurn?.id === turnId
                 ? this.activeTurn.cancellationSource : undefined;
@@ -872,7 +991,11 @@ export class AcpSession {
             return turnResult(true, classifyStopReason(response.stopReason), response.stopReason, this.activeTurn?.id === turnId ? this.activeTurn.output : undefined, this.activeTurn?.id === turnId ? this.activeTurn.cancellationSource : undefined);
         }
         catch (error) {
-            const detail = error?.message ?? String(error);
+            const escalated = this.activeTurn?.id === turnId
+                && this.activeTurn.cancellationDeadlineExceeded;
+            const detail = escalated
+                ? this.lastError ?? ACP_CANCEL_DEADLINE_EXCEEDED
+                : error?.message ?? String(error);
             this.lastError = origin?.kind === 'scheduled-loop' ? 'scheduled-loop turn failed' : detail;
             this.readiness = this.isAlive() ? 'idle' : 'failed';
             this.events.emit('error', {
@@ -891,6 +1014,7 @@ export class AcpSession {
         finally {
             this.releaseAllTools();
             if (this.activeTurn?.id === turnId) {
+                this.activeTurn.settle();
                 if (this.cancelEscalation)
                     clearTimeout(this.cancelEscalation);
                 this.cancelEscalation = undefined;
@@ -902,10 +1026,13 @@ export class AcpSession {
         if (!this.sessionId || !this.isAlive())
             return turnResult(false, 'failed', this.lastError ?? 'ACP session is offline');
         try {
-            const response = await this.connection.agent.request('_session/steering', {
-                sessionId: this.sessionId,
-                prompt: [{ type: 'text', text }],
-            });
+            const response = await Promise.race([
+                this.connection.agent.request('_session/steering', {
+                    sessionId: this.sessionId,
+                    prompt: [{ type: 'text', text }],
+                }),
+                this.terminated,
+            ]);
             if (response.outcome === 'failed')
                 return turnResult(false, 'failed', 'ACP steering failed');
             return turnResult(true, 'inconclusive', response.outcome);

package/dist/session/arbiter.d.ts

@@ -1,4 +1,4 @@
-import type { ConversationHandlePage, ExitRecord, PromptOrigin, QueuedPrompt, SessionEvent, SessionHandle, SessionSnapshot, SubmitPromptOptions, TurnCancellationSource, TurnResult } from './types.js';
+import type { ConversationHandlePage, ExitRecord, InterruptOutcome, PromptOrigin, QueuedPrompt, SessionEvent, SessionHandle, SessionSnapshot, SubmitPromptOptions, TurnCancellationSource, TurnResult } from './types.js';
 import type { ConversationEventV1, ConversationSnapshot, PromptReceipt, SubmitPromptCommand } from './conversation-types.js';
 export type ScheduledAttempt = {
     state: 'started';
@@ -22,9 +22,35 @@ export declare class RoleTurnArbiter implements SessionHandle {
     private tail;
     private unsettled;
     private stopping;
+    /** Bumped by `retireStalledAdmission`; every claim carries the one it was made under. */
+    private generation;
+    /** Resolves the instant the CURRENT generation is retired. */
+    private retirement;
     constructor(session: SessionHandle);
+    /**
+     * Waiters race the tail against their own generation's retirement, so a
+     * single operation that never settles cannot own the boundary forever. A
+     * woken waiter from a retired generation never runs its operation: the
+     * ordering it was promised no longer exists, and admitting it silently would
+     * be the one thing worse than telling the caller it was not admitted.
+     */
     private exclusive;
     private track;
+    /**
+     * Release the admission boundary after a cancellation that never settled.
+     * Nothing can make a hung ACP call return, so the stuck operation keeps its
+     * own promise — it just stops owning `tail` and stops holding a claim.
+     *
+     * Without this, one unsettled `interrupt` left every later producer queued
+     * behind it forever: a scheduled poll never returned, so the loop was never
+     * rescheduled and reported neither `started` nor `skipped_busy`, and an owner
+     * prompt stayed pending with nothing to resolve it.
+     *
+     * One-active-run safety is unchanged. The arbiter only orders admission;
+     * `tryScheduled` still asks the session itself whether it is idle, and the
+     * session still refuses to run two turns at once.
+     */
+    retireStalledAdmission(): void;
     queuePrompt(text: string, options?: SubmitPromptOptions): Promise<QueuedPrompt>;
     submitPrompt(text: string, options?: SubmitPromptOptions): Promise<TurnResult>;
     /**
@@ -45,7 +71,7 @@ export declare class RoleTurnArbiter implements SessionHandle {
     conversationSnapshot(): ConversationSnapshot;
     subscribeConversation(listener: (event: ConversationEventV1) => void): () => void;
     submitPromptBrowser(command: SubmitPromptCommand): Promise<PromptReceipt>;
-    interrupt(source?: TurnCancellationSource): Promise<void>;
+    interrupt(source?: TurnCancellationSource): Promise<InterruptOutcome>;
     respondPermission(permissionId: string, optionId: string): boolean;
     respondPermissionV2(permissionId: string, optionId: string, sessionGeneration: string): 'accepted' | 'stale';
     eventsSince(seq: number): SessionEvent[];

package/dist/session/arbiter.js

@@ -1,3 +1,20 @@
+import { ACP_CANCEL_DEADLINE_EXCEEDED, SessionControlError, interruptOutcome, } from './types.js';
+/**
+ * Raised for admissions that were still waiting on a generation which had to be
+ * retired. It carries `ACP_CANCEL_DEADLINE_EXCEEDED` because that is the only
+ * thing that ever retires a generation, and because durable owner ingress
+ * already treats that reason as "never delivered — replay it".
+ */
+class AdmissionRetiredError extends SessionControlError {
+    constructor() {
+        super('control-unavailable', 'admission was retired after a cancellation that never settled', ACP_CANCEL_DEADLINE_EXCEEDED);
+    }
+}
+function retirementSignal() {
+    let retire;
+    const promise = new Promise(resolve => { retire = resolve; });
+    return { promise, retire };
+}
 /**
  * One in-process admission boundary for every producer targeting a role.
  * Scheduled callers get an atomic idle recheck plus submission; ordinary
@@ -11,21 +28,64 @@ export class RoleTurnArbiter {
     tail = Promise.resolve();
     unsettled = 0;
     stopping = false;
+    /** Bumped by `retireStalledAdmission`; every claim carries the one it was made under. */
+    generation = 0;
+    /** Resolves the instant the CURRENT generation is retired. */
+    retirement = retirementSignal();
     constructor(session) {
         this.session = session;
         this.backend = session.backend;
         this.pid = session.pid;
     }
+    /**
+     * Waiters race the tail against their own generation's retirement, so a
+     * single operation that never settles cannot own the boundary forever. A
+     * woken waiter from a retired generation never runs its operation: the
+     * ordering it was promised no longer exists, and admitting it silently would
+     * be the one thing worse than telling the caller it was not admitted.
+     */
     exclusive(operation) {
-        const run = this.tail.then(operation);
+        const generation = this.generation;
+        const run = Promise.race([this.tail, this.retirement.promise]).then(() => {
+            if (generation !== this.generation)
+                throw new AdmissionRetiredError();
+            return operation();
+        });
         this.tail = run.then(() => undefined, () => undefined);
         return run;
     }
     track(queued) {
+        const generation = this.generation;
         this.unsettled++;
-        const completion = queued.completion.finally(() => { this.unsettled = Math.max(0, this.unsettled - 1); });
+        const completion = queued.completion.finally(() => {
+            // A retired generation's claims were released in one step already.
+            if (generation === this.generation)
+                this.unsettled = Math.max(0, this.unsettled - 1);
+        });
         return { ...queued, completion };
     }
+    /**
+     * Release the admission boundary after a cancellation that never settled.
+     * Nothing can make a hung ACP call return, so the stuck operation keeps its
+     * own promise — it just stops owning `tail` and stops holding a claim.
+     *
+     * Without this, one unsettled `interrupt` left every later producer queued
+     * behind it forever: a scheduled poll never returned, so the loop was never
+     * rescheduled and reported neither `started` nor `skipped_busy`, and an owner
+     * prompt stayed pending with nothing to resolve it.
+     *
+     * One-active-run safety is unchanged. The arbiter only orders admission;
+     * `tryScheduled` still asks the session itself whether it is idle, and the
+     * session still refuses to run two turns at once.
+     */
+    retireStalledAdmission() {
+        const retired = this.retirement;
+        this.generation++;
+        this.retirement = retirementSignal();
+        this.tail = Promise.resolve();
+        this.unsettled = 0;
+        retired.retire();
+    }
     queuePrompt(text, options = {}) {
         return this.exclusive(async () => this.track(await this.session.queuePrompt(text, options)));
     }
@@ -54,13 +114,24 @@ export class RoleTurnArbiter {
             try {
                 await beforeQueue?.();
                 const queued = await this.session.queuePrompt(text, { interrupt: false, origin });
-                if (queued.queuedBehind > 0)
+                // The race is lost, but the prompt was admitted and WILL run. Keep the
+                // claim so idle accounting matches reality instead of under-counting.
+                if (queued.queuedBehind > 0) {
+                    this.track(queued);
                     return { state: 'unavailable', error: 'scheduled admission race' };
+                }
                 return { state: 'started', queued: this.track(queued) };
             }
             catch (error) {
                 return { state: 'unavailable', error: error?.message ?? String(error) };
             }
+        }).catch(error => {
+            // A retired attempt was never submitted. Reporting that as an outcome
+            // instead of a rejection is what keeps the poll — and with it the loop's
+            // own rescheduling — from being abandoned mid-tick.
+            if (error instanceof AdmissionRetiredError)
+                return { state: 'unavailable', error: error.message };
+            throw error;
         });
     }
     stopScheduledAdmission() { this.stopping = true; }
@@ -87,7 +158,7 @@ export class RoleTurnArbiter {
         return this.exclusive(() => this.session.submitPromptBrowser(command));
     }
     interrupt(source = 'local-console') {
-        return this.exclusive(() => this.session.interrupt(source));
+        return this.exclusive(async () => interruptOutcome(await this.session.interrupt(source)));
     }
     respondPermission(permissionId, optionId) {
         return this.session.respondPermission(permissionId, optionId);

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;