@rynx-ai/runtime 0.1.11-beta.32 → 0.1.11-beta.34

package/dist/claude/native-bridge.d.ts

@@ -4,6 +4,7 @@ export declare const STATE_FILE = "state.json";
 export declare const DELTAS_FILE = "message_deltas.jsonl";
 export declare const STATUS_FILE = "status.json";
 export declare const FORWARDER_STATE_FILE = "transcript_forwarder.json";
+export declare const HOOK_FORWARDER_STATE_FILE = "hook_forwarder.json";
 export declare const INTERACTIONS_FILE = "interactions.jsonl";
 export declare const INTERACTION_ACKS_FILE = "interaction-acks.jsonl";
 export declare const INTERACTION_RESULTS_DIR = "interaction-results";
@@ -104,6 +105,10 @@ export interface JsonlReadResult<T> {
 export declare function readJsonlFrom<T = unknown>(path: string, byteOffset: number): JsonlReadResult<T>;
 /** One parsed Claude hook event (the fields the forwarder acts on + the raw payload). */
 export interface HookEvent {
+    /** One-based record position in the append-only hook stream. */
+    eventCursor: number;
+    /** Byte offset immediately after this complete JSONL record. */
+    byteOffset: number;
     eventName?: string;
     transcriptPath?: string;
     /** Claude's session uuid — subagent hooks report a `subagents/…` transcript path. */
@@ -114,10 +119,20 @@ export interface HookEvent {
     payload: Record<string, unknown>;
 }
 /** Tail `hooks.jsonl` from a byte offset into parsed {@link HookEvent}s. */
-export declare function readHookEventsFrom(bridgeDir: string, byteOffset: number): {
+export declare function readHookEventsFrom(bridgeDir: string, byteOffset: number, startEventCursor?: number): {
     events: HookEvent[];
     nextOffset: number;
 };
+export interface HookForwardState {
+    eventCursor: number;
+    byteOffset: number;
+    cursorFingerprint?: string;
+}
+/** Read and validate the durable hook cursor. A replaced/truncated hook stream
+ * restarts at zero; event handlers provide their own stable deduplication. */
+export declare function readHookForwardState(bridgeDir: string): HookForwardState | undefined;
+/** Persist one consumed hook record before another poll can observe it. */
+export declare function writeHookForwardState(bridgeDir: string, state: HookForwardState): void;
 /** One streamed assistant-text chunk from `message_deltas.jsonl` (MessageDisplay). */
 export interface MessageDelta {
     messageId: string;

package/dist/claude/native-bridge.js

@@ -20,6 +20,7 @@ export const STATE_FILE = "state.json";
 export const DELTAS_FILE = "message_deltas.jsonl";
 export const STATUS_FILE = "status.json";
 export const FORWARDER_STATE_FILE = "transcript_forwarder.json";
+export const HOOK_FORWARDER_STATE_FILE = "hook_forwarder.json";
 export const INTERACTIONS_FILE = "interactions.jsonl";
 export const INTERACTION_ACKS_FILE = "interaction-acks.jsonl";
 export const INTERACTION_RESULTS_DIR = "interaction-results";
@@ -47,6 +48,7 @@ export function prepareClaudeBridgeDir(sessionId) {
         INTERACTIONS_FILE,
         INTERACTION_ACKS_FILE,
         MANAGED_SETTINGS_FILE,
+        HOOK_FORWARDER_STATE_FILE,
     ]) {
         try {
             rmSync(join(dir, file));
@@ -360,27 +362,99 @@ export function readJsonlFrom(path, byteOffset) {
     }
 }
 /** Tail `hooks.jsonl` from a byte offset into parsed {@link HookEvent}s. */
-export function readHookEventsFrom(bridgeDir, byteOffset) {
-    const { records, nextOffset } = readJsonlFrom(join(bridgeDir, HOOKS_FILE), byteOffset);
+export function readHookEventsFrom(bridgeDir, byteOffset, startEventCursor = 0) {
+    const path = join(bridgeDir, HOOKS_FILE);
+    let info;
+    try {
+        info = statSync(path);
+    }
+    catch {
+        return { events: [], nextOffset: byteOffset };
+    }
+    if (info.size <= byteOffset)
+        return { events: [], nextOffset: byteOffset };
+    const fd = openSync(path, "r");
     const events = [];
-    for (const rec of records) {
-        const payload = rec.payload;
-        if (!payload || typeof payload !== "object")
-            continue;
-        const liveBackgroundTasks = backgroundTaskCount(payload);
-        events.push({
-            eventName: asString(payload.hook_event_name),
-            transcriptPath: asString(payload.transcript_path),
-            sessionId: asString(payload.session_id),
-            source: asString(payload.source),
-            ...(liveBackgroundTasks === undefined
-                ? {}
-                : { backgroundTaskCount: liveBackgroundTasks }),
-            payload,
-        });
+    let nextOffset = byteOffset;
+    let eventCursor = startEventCursor;
+    try {
+        const length = info.size - byteOffset;
+        const buf = Buffer.alloc(length);
+        readSync(fd, buf, 0, length, byteOffset);
+        const text = buf.toString("utf8");
+        const lines = text.split("\n");
+        lines.pop(); // retain a partial trailing record for the next poll
+        for (const line of lines) {
+            const lineBytes = Buffer.byteLength(`${line}\n`, "utf8");
+            nextOffset += lineBytes;
+            if (!line.trim())
+                continue;
+            eventCursor += 1;
+            let rec;
+            try {
+                rec = JSON.parse(line);
+            }
+            catch {
+                events.push({ eventCursor, byteOffset: nextOffset, payload: {} });
+                continue;
+            }
+            const payload = rec.payload;
+            if (!payload || typeof payload !== "object") {
+                events.push({ eventCursor, byteOffset: nextOffset, payload: {} });
+                continue;
+            }
+            const liveBackgroundTasks = backgroundTaskCount(payload);
+            events.push({
+                eventCursor,
+                byteOffset: nextOffset,
+                eventName: asString(payload.hook_event_name),
+                transcriptPath: asString(payload.transcript_path),
+                sessionId: asString(payload.session_id),
+                source: asString(payload.source),
+                ...(liveBackgroundTasks === undefined
+                    ? {}
+                    : { backgroundTaskCount: liveBackgroundTasks }),
+                payload,
+            });
+        }
+    }
+    finally {
+        closeSync(fd);
     }
     return { events, nextOffset };
 }
+/** Read and validate the durable hook cursor. A replaced/truncated hook stream
+ * restarts at zero; event handlers provide their own stable deduplication. */
+export function readHookForwardState(bridgeDir) {
+    const raw = readJsonFile(join(bridgeDir, HOOK_FORWARDER_STATE_FILE));
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const state = raw;
+    const eventCursor = asNumber(state.eventCursor);
+    const byteOffset = asNumber(state.byteOffset);
+    const cursorFingerprint = asString(state.cursorFingerprint);
+    if (eventCursor === undefined || eventCursor < 0 || !Number.isInteger(eventCursor) ||
+        byteOffset === undefined || byteOffset < 0 || !Number.isInteger(byteOffset))
+        return undefined;
+    const current = jsonlCursorFingerprint(join(bridgeDir, HOOKS_FILE), byteOffset);
+    if (!cursorFingerprint || current !== cursorFingerprint) {
+        return {
+            eventCursor: 0,
+            byteOffset: 0,
+            ...(jsonlCursorFingerprint(join(bridgeDir, HOOKS_FILE), 0)
+                ? { cursorFingerprint: jsonlCursorFingerprint(join(bridgeDir, HOOKS_FILE), 0) }
+                : {}),
+        };
+    }
+    return { eventCursor, byteOffset, cursorFingerprint };
+}
+/** Persist one consumed hook record before another poll can observe it. */
+export function writeHookForwardState(bridgeDir, state) {
+    mkdirSync(bridgeDir, { recursive: true, mode: 0o700 });
+    const tmp = join(bridgeDir, `${HOOK_FORWARDER_STATE_FILE}.tmp`);
+    writeFileSync(tmp, JSON.stringify(state));
+    renameSync(tmp, join(bridgeDir, HOOK_FORWARDER_STATE_FILE));
+}
 /** Tail `message_deltas.jsonl` from a byte offset into {@link MessageDelta}s. */
 export function readMessageDeltasFrom(bridgeDir, byteOffset) {
     const { records, nextOffset } = readJsonlFrom(join(bridgeDir, DELTAS_FILE), byteOffset);

package/dist/claude/native-integration.d.ts

@@ -88,7 +88,10 @@ export declare class ClaudeLiveSession {
     private readonly leaseUpdatedAt;
     private started;
     private stopped;
+    private supervisorTask?;
+    private releaseSleep?;
     private hooksOffset;
+    private hookEventCursor;
     private interactionsOffset;
     private interactionAcksOffset;
     private transcriptOffset;
@@ -202,6 +205,10 @@ export declare class ClaudeLiveSession {
     private consumeQueuedPromotion;
     start(): void;
     stop(): void;
+    /** Wait for the supervised polling task to retire. Terminal teardown starts
+     * synchronously in {@link stop}; callers use this bounded join before their
+     * runner process exits. */
+    waitForStop(timeoutMs?: number): Promise<void>;
     /** Phase two of runner shutdown. The caller must stop the Claude terminal
      * first so no hook can still be opening an atomically claimed answer. This is
      * synchronous because the runner process exits immediately afterwards. */
@@ -214,8 +221,11 @@ export declare class ClaudeLiveSession {
         panePid: () => number | undefined;
         configDir?: string;
     }): void;
+    private supervise;
     private loop;
+    private sleepUntilWake;
     private pollHooks;
+    private persistHookCursor;
     private handleHook;
     /** Process a provider failure only after this tick has discovered every
      *  blocking request already appended by its hook subprocess. */

package/dist/claude/native-integration.js

@@ -20,7 +20,7 @@
  */
 import { statSync } from "node:fs";
 import { parseTerminalCommand, parseTranscriptRecord, readSubagentEvents, subagentTranscriptPath, transcriptHasForkedFrom, } from "./transcript.js";
-import { jsonlCursorFingerprint, interactionLeaseUpdatedAt, readClaimedInteractionResult, readClaudeStatus, readForwardState, readInteractionAcksFrom, readHookEventsFrom, readInteractionRequestsFrom, readJsonlFrom, readMessageDeltasFrom, resetForwardState, removeClaimedInteractionResult, removeInteractionLease, removeInteractionResult, scrubClaudeInteractionArtifacts, writeInteractionResult, writeForwardState, } from "./native-bridge.js";
+import { HOOKS_FILE, jsonlCursorFingerprint, interactionLeaseUpdatedAt, readClaimedInteractionResult, readClaudeStatus, readForwardState, readHookForwardState, readInteractionAcksFrom, readHookEventsFrom, readInteractionRequestsFrom, readJsonlFrom, readMessageDeltasFrom, resetForwardState, removeClaimedInteractionResult, removeInteractionLease, removeInteractionResult, scrubClaudeInteractionArtifacts, writeInteractionResult, writeForwardState, writeHookForwardState, } from "./native-bridge.js";
 import { boundInteractionRequest, redactInteractionResolution, validateInteractionResolution, } from "../interactions.js";
 import { ClaudeSessionStatusPoller, } from "./session-status.js";
 const MAX_SETTLED_INTERACTIONS = 512;
@@ -32,6 +32,9 @@ const INTERACTION_ACK_TIMEOUT_MS = 5_000;
 // reference implementation's `_CLAUDE_INTERRUPT_RECORD_RE`.
 const CLAUDE_INTERRUPT_RECORD_RE = /^\[Request interrupted by user(?: for tool use)?\]$/;
 const INTERACTION_LEASE_TIMEOUT_MS = 30_000;
+const FORWARDER_RESTART_INITIAL_MS = 1_000;
+const FORWARDER_RESTART_MAX_MS = 30_000;
+const FORWARDER_HEALTHY_UPTIME_MS = 60_000;
 function processIsAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -149,7 +152,10 @@ export class ClaudeLiveSession {
     leaseUpdatedAt;
     started = false;
     stopped = false;
+    supervisorTask;
+    releaseSleep;
     hooksOffset = 0;
+    hookEventCursor = 0;
     interactionsOffset = 0;
     interactionAcksOffset = 0;
     transcriptOffset = 0;
@@ -249,6 +255,11 @@ export class ClaudeLiveSession {
         this.expectedClaudeSessionId = opts.claudeSessionId;
         this.resumeAtEndOnDiscovery = opts.resumeAtEndOnDiscovery ?? false;
         this.transcriptPath = opts.transcriptPath;
+        const hookState = readHookForwardState(this.bridgeDir);
+        if (hookState) {
+            this.hooksOffset = hookState.byteOffset;
+            this.hookEventCursor = hookState.eventCursor;
+        }
         // Resume path: bind the session id + restore the persisted forwarder cursor so
         // we continue from where a prior forwarder left off (no re-mirror on relaunch).
         if (opts.transcriptPath) {
@@ -342,12 +353,13 @@ export class ClaudeLiveSession {
         if (this.started)
             return;
         this.started = true;
-        void this.loop();
+        this.supervisorTask = this.supervise();
     }
     stop() {
         if (this.stopped)
             return;
         this.stopped = true;
+        this.releaseSleep?.();
         this.statusPoller?.retire();
         // A hook may have appended its request just before shutdown but not yet
         // reached a scheduled poll. Drain it so the subprocess receives cancellation
@@ -360,6 +372,24 @@ export class ClaudeLiveSession {
         this.closeTurn();
         this.scheduleClaimedInteractionScrubs();
     }
+    /** Wait for the supervised polling task to retire. Terminal teardown starts
+     * synchronously in {@link stop}; callers use this bounded join before their
+     * runner process exits. */
+    async waitForStop(timeoutMs = 5_000) {
+        const task = this.supervisorTask;
+        if (!task)
+            return;
+        let timer;
+        await Promise.race([
+            task,
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, timeoutMs);
+                timer.unref?.();
+            }),
+        ]);
+        if (timer)
+            clearTimeout(timer);
+    }
     /** Phase two of runner shutdown. The caller must stop the Claude terminal
      * first so no hook can still be opening an atomically claimed answer. This is
      * synchronous because the runner process exits immediately afterwards. */
@@ -400,6 +430,32 @@ export class ClaudeLiveSession {
             ...(configDir ? { configDir } : {}),
         });
     }
+    async supervise() {
+        let backoffMs = FORWARDER_RESTART_INITIAL_MS;
+        while (!this.stopped) {
+            const startedAt = this.now();
+            let crashed;
+            try {
+                await this.loop();
+                if (!this.stopped) {
+                    console.warn("[claude-forwarder] polling loop returned unexpectedly; restarting");
+                }
+            }
+            catch (error) {
+                crashed = error;
+            }
+            if (this.stopped)
+                break;
+            if (this.now() - startedAt >= FORWARDER_HEALTHY_UPTIME_MS) {
+                backoffMs = FORWARDER_RESTART_INITIAL_MS;
+            }
+            if (crashed !== undefined) {
+                console.error(`[claude-forwarder] polling loop crashed; restarting in ${backoffMs}ms:`, crashed);
+            }
+            await this.sleepUntilWake(backoffMs);
+            backoffMs = Math.min(backoffMs * 2, FORWARDER_RESTART_MAX_MS);
+        }
+    }
     async loop() {
         while (!this.stopped) {
             try {
@@ -411,7 +467,7 @@ export class ClaudeLiveSession {
                 // per-iteration `except Exception` in the transcript forwarder loop.
                 console.error("[claude-forwarder] tick failed; continuing:", err);
             }
-            await new Promise((r) => setTimeout(r, this.pollMs));
+            await this.sleepUntilWake(this.pollMs);
         }
         // Catch a request appended while the loop was waking up to observe stopped.
         this.pollInteractions();
@@ -420,11 +476,49 @@ export class ClaudeLiveSession {
         this.closeTurn();
         this.scheduleClaimedInteractionScrubs();
     }
+    sleepUntilWake(delayMs) {
+        if (this.stopped)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const timer = setTimeout(done, delayMs);
+            timer.unref?.();
+            const self = this;
+            function done() {
+                if (self.releaseSleep === done)
+                    self.releaseSleep = undefined;
+                clearTimeout(timer);
+                resolve();
+            }
+            this.releaseSleep = done;
+        });
+    }
     pollHooks() {
-        const { events, nextOffset } = readHookEventsFrom(this.bridgeDir, this.hooksOffset);
-        this.hooksOffset = nextOffset;
-        for (const ev of events)
+        const { events } = readHookEventsFrom(this.bridgeDir, this.hooksOffset, this.hookEventCursor);
+        for (const ev of events) {
+            // Rotation is an exactly-once edge. Persist it before the callback so a
+            // partial publication failure cannot create another replacement session
+            // when this forwarder (or its supervisor) restarts.
+            const rotation = ev.eventName === "SessionStart" && (ev.source === "clear" ||
+                (ev.source === "resume" && Boolean(ev.sessionId &&
+                    ev.transcriptPath &&
+                    !this.seenClaudeSessionIds.has(ev.sessionId) &&
+                    transcriptHasForkedFrom(ev.transcriptPath, ev.sessionId))));
+            if (rotation)
+                this.persistHookCursor(ev);
             this.handleHook(ev);
+            if (!rotation)
+                this.persistHookCursor(ev);
+        }
+    }
+    persistHookCursor(ev) {
+        this.hooksOffset = ev.byteOffset;
+        this.hookEventCursor = ev.eventCursor;
+        const fingerprint = jsonlCursorFingerprint(`${this.bridgeDir}/${HOOKS_FILE}`, ev.byteOffset);
+        writeHookForwardState(this.bridgeDir, {
+            eventCursor: ev.eventCursor,
+            byteOffset: ev.byteOffset,
+            ...(fingerprint ? { cursorFingerprint: fingerprint } : {}),
+        });
     }
     handleHook(ev) {
         if (ev.eventName === "SessionStart") {

package/dist/codex-app-server/forwarder.js

@@ -6,6 +6,13 @@ function threadIdFrom(params) {
     const p = params;
     return p?.threadId ?? p?.thread?.id;
 }
+/** Agent-control children announce their own thread on the shared app-server.
+ * They do not replace the parent TUI thread: only a top-level thread switch is
+ * a Session rotation boundary. */
+function isSubagentThreadStarted(params) {
+    const source = params?.thread?.source?.subAgent?.thread_spawn;
+    return source !== null && typeof source === "object" && !Array.isArray(source);
+}
 function turnIdFrom(params) {
     const p = params;
     return p?.turnId ?? p?.turn?.id;
@@ -108,7 +115,14 @@ export class CodexSessionForwarder {
         if (this.unsubscribe)
             return;
         this.unsubscribe = this.client.onNotification((method, params) => {
-            this.handle(method, params);
+            try {
+                this.handle(method, params);
+            }
+            catch (error) {
+                // One malformed or unsupported notification must not detach the
+                // long-lived observer from every later event in this session.
+                console.error(`[codex-forwarder] notification handler failed for ${method}; continuing:`, error);
+            }
         });
         const startup = this.options.mcpStartup;
         if (startup?.servers.length) {
@@ -247,6 +261,8 @@ export class CodexSessionForwarder {
     }
     handle(method, params) {
         if (method === "thread/started" || method === "thread.started") {
+            if (method === "thread/started" && isSubagentThreadStarted(params))
+                return;
             const tid = threadIdFrom(params);
             if (tid && tid !== this.currentThreadIdValue) {
                 const forkedFromId = params?.thread?.forkedFromId;

package/dist/codex-app-server/process-registry.d.ts

@@ -0,0 +1,36 @@
+export interface RuntimeProcessEntry {
+    pid: number;
+    pgid: number;
+    ownerPid: number;
+    /** OS process-start identity. Unlike a PID, this cannot silently refer to a
+     * later process after the launcher crashes and the PID is recycled. */
+    ownerIdentity?: string;
+    sessionTag: string;
+    stateDir: string;
+}
+export declare function runtimeProcessRegistryPath(): string;
+export declare function runtimeProcessTagArg(sessionTag: string): string;
+export declare function runtimeProcessArgv0(cliPath: string, sessionTag: string): string;
+export declare function withRuntimeProcessStateArg(baseArgs: string[], stateDir: string): string[];
+export declare function registerRuntimeProcess(entry: RuntimeProcessEntry, registryPath?: string): void;
+export declare function unregisterRuntimeProcess(sessionTag: string, registryPath?: string): void;
+export interface RuntimeProcessReconcileOptions {
+    registryPath?: string;
+    ownerAlive?: (pid: number) => boolean;
+    ownerIdentity?: (pid: number) => string;
+    childAlive?: (pid: number) => boolean;
+    commandLine?: (pid: number) => string;
+    terminateGroup?: (pgid: number) => boolean;
+}
+export declare function reconcileRuntimeProcesses(opts?: RuntimeProcessReconcileOptions): number;
+export declare function reapRuntimeProcessesForStateDir(stateDir: string, opts?: RuntimeProcessStateReapOptions): number;
+export interface RuntimeProcessStateReapOptions {
+    processListing?: () => string;
+    currentPgid?: () => number;
+    childAlive?: (pid: number) => boolean;
+    signalGroup?: (pgid: number, signal: NodeJS.Signals) => boolean;
+    graceMs?: number;
+}
+/** Return an OS process-start identity used to distinguish PID reuse. */
+export declare function runtimeProcessOwnerIdentity(pid: number): string;
+export declare function newRuntimeProcessTag(): string;