@rynx-ai/runtime 0.1.11-beta.4 → 0.1.11-beta.41

package/dist/claude/native-bridge.js

@@ -11,8 +11,8 @@
  * Dependency-light on purpose (node builtins plus erased protocol types) so the
  * standalone hook entrypoints do not pull the whole runtime into every process.
  */
-import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
-import { createHash } from "node:crypto";
+import { appendFileSync, closeSync, fsyncSync, mkdirSync, openSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { adoptLegacyRuntimeDirectory, legacyRuntimeStateRoot, runtimeSessionDigest, runtimeSessionStateDir, } from "../runtime-state-paths.js";
 export const HOOKS_FILE = "hooks.jsonl";
@@ -20,12 +20,42 @@ 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 SUBAGENT_FORWARDER_STATE_FILE = "subagent_forwarder.json";
+export const DELTA_FORWARDER_STATE_FILE = "message_deltas_forwarder.json";
+export const COMPACTION_FORWARDER_STATE_FILE = "compaction_forwarder.json";
 export const INTERACTIONS_FILE = "interactions.jsonl";
 export const INTERACTION_ACKS_FILE = "interaction-acks.jsonl";
 export const INTERACTION_RESULTS_DIR = "interaction-results";
 export const INTERACTION_CLAIMS_DIR = "interaction-claims";
 export const INTERACTION_LEASES_DIR = "interaction-leases";
 export const MANAGED_SETTINGS_FILE = "managed-settings.json";
+/** Reference bridge state uses temp + fsync + replace so a hook crash can
+ * never leave readers with a truncated JSON object. A unique temp name also
+ * keeps concurrent native hook subprocesses from clobbering one another's
+ * staging file. */
+function writeJsonFileAtomic(path, payload) {
+    const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    let fd;
+    try {
+        fd = openSync(tmp, "wx", 0o600);
+        writeFileSync(fd, JSON.stringify(payload));
+        fsyncSync(fd);
+        closeSync(fd);
+        fd = undefined;
+        renameSync(tmp, path);
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+        try {
+            rmSync(tmp);
+        }
+        catch {
+            // rename succeeded, or a competing cleanup already removed the temp.
+        }
+    }
+}
 /** The deterministic bridge directory for a rynx session id. */
 export function claudeBridgeDir(sessionId) {
     return join(runtimeSessionStateDir(sessionId), "claude-bridge");
@@ -47,6 +77,7 @@ export function prepareClaudeBridgeDir(sessionId) {
         INTERACTIONS_FILE,
         INTERACTION_ACKS_FILE,
         MANAGED_SETTINGS_FILE,
+        HOOK_FORWARDER_STATE_FILE,
     ]) {
         try {
             rmSync(join(dir, file));
@@ -267,17 +298,59 @@ function readJsonFile(path) {
 function asString(value) {
     return typeof value === "string" && value ? value : undefined;
 }
+const TERMINAL_BACKGROUND_TASK_STATUSES = new Set([
+    "completed",
+    "failed",
+    "stopped",
+    "killed",
+]);
+function backgroundTaskCount(payload) {
+    if (payload.hook_event_name !== "Stop")
+        return undefined;
+    const tasks = payload.background_tasks;
+    if (!Array.isArray(tasks))
+        return 0;
+    return tasks.filter((task) => {
+        if (!task || typeof task !== "object" || Array.isArray(task))
+            return true;
+        const status = task.status;
+        return typeof status !== "string" || !TERMINAL_BACKGROUND_TASK_STATUSES.has(status);
+    }).length;
+}
 export function readClaudeState(bridgeDir) {
     const raw = readJsonFile(join(bridgeDir, STATE_FILE));
     if (!raw || typeof raw !== "object")
         return {};
     const s = raw;
+    const seen = Array.isArray(s.seenClaudeSessionIds)
+        ? s.seenClaudeSessionIds.filter((value) => typeof value === "string" && value.length > 0)
+        : [];
+    const current = asString(s.claudeSessionId);
+    if (current && !seen.includes(current))
+        seen.push(current);
     return {
         transcriptPath: asString(s.transcriptPath),
-        claudeSessionId: asString(s.claudeSessionId),
+        claudeSessionId: current,
+        ...(seen.length > 0 ? { seenClaudeSessionIds: seen } : {}),
         lastHookEventName: asString(s.lastHookEventName),
     };
 }
+/** Capture the pre-SessionStart identity before state.json is advanced. The
+ * observer hook and forwarder use these stable facts to distinguish a new
+ * branch from a later resume into an already-seen native Session. */
+export function annotateClaudeResumeContext(bridgeDir, payload) {
+    if (payload.hook_event_name !== "SessionStart" || payload.source !== "resume")
+        return;
+    const next = asString(payload.session_id);
+    if (!next)
+        return;
+    const state = readClaudeState(bridgeDir);
+    if (state.claudeSessionId && state.claudeSessionId !== next) {
+        payload.rynx_previous_claude_session_id = state.claudeSessionId;
+    }
+    payload.rynx_claude_session_was_seen =
+        (state.seenClaudeSessionIds ?? []).includes(next);
+}
 /**
  * Append one Claude hook payload to `hooks.jsonl` and fold its key fields into
  * `state.json` (transcript path + claude session id + last event). The payload
@@ -288,31 +361,58 @@ export function readClaudeState(bridgeDir) {
  */
 export function recordHookEvent(bridgeDir, payload) {
     mkdirSync(bridgeDir, { recursive: true, mode: 0o700 });
-    const envelope = { recordedAt: Date.now(), payload };
-    appendFileSync(join(bridgeDir, HOOKS_FILE), `${JSON.stringify(envelope)}\n`);
+    if (payload.rynx_claude_session_was_seen === undefined) {
+        annotateClaudeResumeContext(bridgeDir, payload);
+    }
     const state = readClaudeState(bridgeDir);
     const eventName = asString(payload.hook_event_name);
     if (eventName)
         state.lastHookEventName = eventName;
-    const transcriptPath = asString(payload.transcript_path);
-    if (transcriptPath)
-        state.transcriptPath = transcriptPath;
     const claudeSessionId = asString(payload.session_id);
-    if (claudeSessionId)
-        state.claudeSessionId = claudeSessionId;
-    writeFileSync(join(bridgeDir, STATE_FILE), JSON.stringify(state));
+    const identityAllowed = eventName === "SessionStart" || (claudeSessionId !== undefined &&
+        (!state.claudeSessionId || claudeSessionId === state.claudeSessionId));
+    if (identityAllowed) {
+        const transcriptPath = asString(payload.transcript_path);
+        if (transcriptPath)
+            state.transcriptPath = transcriptPath;
+        if (claudeSessionId) {
+            state.claudeSessionId = claudeSessionId;
+            const seen = new Set(state.seenClaudeSessionIds ?? []);
+            seen.add(claudeSessionId);
+            state.seenClaudeSessionIds = [...seen].sort();
+        }
+    }
+    const envelope = { recordedAt: Date.now(), payload };
+    appendFileSync(join(bridgeDir, HOOKS_FILE), `${JSON.stringify(envelope)}\n`);
+    writeJsonFileAtomic(join(bridgeDir, STATE_FILE), state);
 }
 /** Read complete newline-terminated JSON records appended after `byteOffset`. */
 export function readJsonlFrom(path, byteOffset) {
+    const result = readJsonlEntriesFrom(path, byteOffset);
+    return { records: result.records, nextOffset: result.nextOffset };
+}
+/** Read complete records with their stable byte/line source positions. */
+export function readJsonlEntriesFrom(path, byteOffset, startLineCursor = 0) {
     let info;
     try {
         info = statSync(path);
     }
     catch {
-        return { records: [], nextOffset: byteOffset };
+        return {
+            records: [],
+            entries: [],
+            nextOffset: byteOffset,
+            nextLineCursor: startLineCursor,
+        };
+    }
+    if (info.size <= byteOffset) {
+        return {
+            records: [],
+            entries: [],
+            nextOffset: byteOffset,
+            nextLineCursor: startLineCursor,
+        };
     }
-    if (info.size <= byteOffset)
-        return { records: [], nextOffset: byteOffset };
     const fd = openSync(path, "r");
     try {
         const length = info.size - byteOffset;
@@ -323,41 +423,245 @@ export function readJsonlFrom(path, byteOffset) {
         const trailing = lines.pop() ?? ""; // partial (no trailing newline yet)
         const consumed = length - Buffer.byteLength(trailing, "utf8");
         const records = [];
+        const entries = [];
+        let recordOffset = byteOffset;
+        let lineNumber = startLineCursor;
         for (const line of lines) {
+            const lineOffset = recordOffset;
+            recordOffset += Buffer.byteLength(`${line}\n`, "utf8");
+            lineNumber += 1;
             const trimmed = line.trim();
             if (!trimmed)
                 continue;
             try {
-                records.push(JSON.parse(trimmed));
+                const record = JSON.parse(trimmed);
+                records.push(record);
+                entries.push({ record, byteOffset: lineOffset, lineNumber });
             }
             catch {
                 // Skip a malformed complete line; the offset still advances past it.
             }
         }
-        return { records, nextOffset: byteOffset + consumed };
+        return {
+            records,
+            entries,
+            nextOffset: byteOffset + consumed,
+            nextLineCursor: lineNumber,
+        };
     }
     finally {
         closeSync(fd);
     }
 }
 /** 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;
-        events.push({
-            eventName: asString(payload.hook_event_name),
-            transcriptPath: asString(payload.transcript_path),
-            sessionId: asString(payload.session_id),
-            source: asString(payload.source),
-            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,
+                ...(typeof rec.recordedAt === "number" && Number.isFinite(rec.recordedAt)
+                    ? { recordedAt: rec.recordedAt }
+                    : {}),
+                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));
+}
+export function readCompactionForwardState(bridgeDir, generation) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(join(bridgeDir, COMPACTION_FORWARDER_STATE_FILE), "utf8"));
+    }
+    catch {
+        return {
+            generation,
+            lastSequence: 0,
+            persistedSequences: [],
+            lastPrecompactCursor: 0,
+        };
+    }
+    if (!raw || typeof raw !== "object") {
+        return {
+            generation,
+            lastSequence: 0,
+            persistedSequences: [],
+            lastPrecompactCursor: 0,
+        };
+    }
+    const value = raw;
+    if (asString(value.generation) !== generation) {
+        return {
+            generation,
+            lastSequence: 0,
+            persistedSequences: [],
+            lastPrecompactCursor: 0,
+        };
+    }
+    const lastSequence = asNumber(value.lastSequence);
+    const lastPrecompactCursor = asNumber(value.lastPrecompactCursor);
+    const persistedSequences = Array.isArray(value.persistedSequences)
+        ? value.persistedSequences.filter((entry) => typeof entry === "number" && Number.isInteger(entry) && entry > 0).slice(-16)
+        : [];
+    const pendingRaw = value.pending;
+    let pending;
+    if (pendingRaw && typeof pendingRaw === "object") {
+        const candidate = pendingRaw;
+        const sequence = asNumber(candidate.sequence);
+        if (sequence !== undefined && Number.isInteger(sequence) && sequence > 0) {
+            pending = {
+                sequence,
+                ...(asString(candidate.claudeSessionId)
+                    ? { claudeSessionId: asString(candidate.claudeSessionId) }
+                    : {}),
+                ...(asString(candidate.transcriptPath)
+                    ? { transcriptPath: asString(candidate.transcriptPath) }
+                    : {}),
+            };
+        }
+    }
+    const expectCompletionAckSequence = asNumber(value.expectCompletionAckSequence);
+    return {
+        generation,
+        lastSequence: lastSequence !== undefined && Number.isInteger(lastSequence) && lastSequence >= 0
+            ? lastSequence
+            : 0,
+        persistedSequences,
+        lastPrecompactCursor: lastPrecompactCursor !== undefined && Number.isInteger(lastPrecompactCursor) &&
+            lastPrecompactCursor >= 0
+            ? lastPrecompactCursor
+            : 0,
+        ...(pending ? { pending } : {}),
+        ...(expectCompletionAckSequence !== undefined &&
+            Number.isInteger(expectCompletionAckSequence) && expectCompletionAckSequence > 0
+            ? { expectCompletionAckSequence }
+            : {}),
+    };
+}
+export function writeCompactionForwardState(bridgeDir, state) {
+    mkdirSync(bridgeDir, { recursive: true, mode: 0o700 });
+    const tmp = join(bridgeDir, `${COMPACTION_FORWARDER_STATE_FILE}.tmp`);
+    writeFileSync(tmp, JSON.stringify({
+        ...state,
+        persistedSequences: state.persistedSequences.slice(-16),
+    }));
+    renameSync(tmp, join(bridgeDir, COMPACTION_FORWARDER_STATE_FILE));
+}
+/** Read the process-wide MessageDisplay cursor. It deliberately survives
+ * logical Session rotation; if the append log was truncated by a fresh Claude
+ * process, restart at zero. */
+export function readDeltaForwardState(bridgeDir) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(join(bridgeDir, DELTA_FORWARDER_STATE_FILE), "utf8"));
+    }
+    catch {
+        return { byteOffset: 0 };
+    }
+    const byteOffset = raw && typeof raw === "object"
+        ? asNumber(raw.byteOffset)
+        : undefined;
+    if (byteOffset === undefined || byteOffset < 0 || !Number.isInteger(byteOffset)) {
+        return { byteOffset: 0 };
+    }
+    try {
+        if (statSync(join(bridgeDir, DELTAS_FILE)).size < byteOffset)
+            return { byteOffset: 0 };
+    }
+    catch {
+        if (byteOffset > 0)
+            return { byteOffset: 0 };
+    }
+    return { byteOffset };
+}
+export function writeDeltaForwardState(bridgeDir, state) {
+    mkdirSync(bridgeDir, { recursive: true, mode: 0o700 });
+    const tmp = join(bridgeDir, `${DELTA_FORWARDER_STATE_FILE}.tmp`);
+    writeFileSync(tmp, JSON.stringify({ byteOffset: state.byteOffset }));
+    renameSync(tmp, join(bridgeDir, DELTA_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);
@@ -451,7 +755,36 @@ export function readForwardState(bridgeDir) {
         ? s.seenSourceIds.filter((x) => typeof x === "string")
         : [];
     const cursorFingerprint = asString(s.cursorFingerprint);
-    return { transcriptPath, byteOffset, seenSourceIds, ...(cursorFingerprint ? { cursorFingerprint } : {}) };
+    const lineCursor = asNumber(s.lineCursor);
+    const currentTurnId = asString(s.currentTurnId);
+    const currentResponseId = asString(s.currentResponseId);
+    const activeTerminalCommandRaw = s.activeTerminalCommand;
+    const activeTerminalCommandRecord = activeTerminalCommandRaw &&
+        typeof activeTerminalCommandRaw === "object" &&
+        !Array.isArray(activeTerminalCommandRaw)
+        ? activeTerminalCommandRaw
+        : undefined;
+    const activeTerminalCommandText = asString(activeTerminalCommandRecord?.command);
+    const activeTerminalCommandTurnId = asString(activeTerminalCommandRecord?.turnId);
+    const activeTerminalCommand = activeTerminalCommandText
+        ? {
+            command: activeTerminalCommandText,
+            ...(activeTerminalCommandTurnId ? { turnId: activeTerminalCommandTurnId } : {}),
+        }
+        : undefined;
+    return {
+        transcriptPath,
+        byteOffset,
+        seenSourceIds,
+        ...(lineCursor !== undefined && Number.isInteger(lineCursor) && lineCursor >= 0
+            ? { lineCursor }
+            : {}),
+        ...(cursorFingerprint ? { cursorFingerprint } : {}),
+        ...(currentTurnId ? { currentTurnId } : {}),
+        ...(currentResponseId ? { currentResponseId } : {}),
+        ...(s.turnOpen === true ? { turnOpen: true } : {}),
+        ...(activeTerminalCommand ? { activeTerminalCommand } : {}),
+    };
 }
 /** Drop the forwarder cursor (a `/clear` starts fresh). */
 export function resetForwardState(bridgeDir) {
@@ -462,6 +795,88 @@ export function resetForwardState(bridgeDir) {
         // absent — fine
     }
 }
+/** Parent Task/tool ids already consumed by the main transcript cursor. Kept
+ * independently of concrete child agents because Claude may create the child
+ * meta file only after the parent record was durably acknowledged. */
+export function readSubagentParentResponses(bridgeDir, parentTranscriptPath) {
+    const raw = readJsonFile(join(bridgeDir, SUBAGENT_FORWARDER_STATE_FILE));
+    if (!raw || typeof raw !== "object")
+        return new Map();
+    const file = raw;
+    if (file.parentTranscriptPath !== parentTranscriptPath)
+        return new Map();
+    const responses = file.parentResponses;
+    if (!responses || typeof responses !== "object" || Array.isArray(responses))
+        return new Map();
+    const result = new Map();
+    for (const [parentToolCallId, responseId] of Object.entries(responses)) {
+        if (!parentToolCallId || typeof responseId !== "string" || !responseId)
+            continue;
+        result.set(parentToolCallId, responseId);
+    }
+    return result;
+}
+/** Read independent Claude native sub-agent cursors for one parent transcript. */
+export function readSubagentForwardStates(bridgeDir, parentTranscriptPath) {
+    const raw = readJsonFile(join(bridgeDir, SUBAGENT_FORWARDER_STATE_FILE));
+    if (!raw || typeof raw !== "object")
+        return [];
+    const file = raw;
+    if (file.parentTranscriptPath !== parentTranscriptPath || !Array.isArray(file.agents)) {
+        return [];
+    }
+    const states = [];
+    for (const value of file.agents) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            continue;
+        const state = value;
+        const agentId = asString(state.agentId);
+        const parentToolCallId = asString(state.parentToolCallId);
+        const parentResponseId = asString(state.parentResponseId);
+        const transcriptPath = asString(state.transcriptPath);
+        const byteOffset = asNumber(state.byteOffset);
+        const lineCursor = asNumber(state.lineCursor);
+        const terminalCommand = asString(state.terminalCommand);
+        if (!agentId || !parentToolCallId || !transcriptPath || byteOffset === undefined)
+            continue;
+        states.push({
+            agentId,
+            parentToolCallId,
+            ...(parentResponseId ? { parentResponseId } : {}),
+            transcriptPath,
+            byteOffset,
+            ...(lineCursor !== undefined && Number.isInteger(lineCursor) && lineCursor >= 0
+                ? { lineCursor }
+                : {}),
+            ...(terminalCommand ? { terminalCommand } : {}),
+            seenSourceIds: Array.isArray(state.seenSourceIds)
+                ? state.seenSourceIds
+                    .filter((id) => typeof id === "string")
+                    .slice(-MAX_SEEN_SOURCE_IDS)
+                : [],
+        });
+    }
+    return states;
+}
+/** Atomically persist every native sub-agent's independent delivery cursor. */
+export function writeSubagentForwardStates(bridgeDir, parentTranscriptPath, states, parentResponses = new Map()) {
+    mkdirSync(bridgeDir, { recursive: true, mode: 0o700 });
+    const file = {
+        parentTranscriptPath,
+        parentResponses: Object.fromEntries([...parentResponses].slice(-MAX_SEEN_SOURCE_IDS)),
+        agents: states.map((state) => ({
+            ...state,
+            seenSourceIds: state.seenSourceIds.slice(-MAX_SEEN_SOURCE_IDS),
+        })),
+    };
+    const target = join(bridgeDir, SUBAGENT_FORWARDER_STATE_FILE);
+    const tmp = `${target}.tmp`;
+    writeFileSync(tmp, JSON.stringify(file));
+    renameSync(tmp, target);
+}
+export function resetSubagentForwardStates(bridgeDir) {
+    rmSync(join(bridgeDir, SUBAGENT_FORWARDER_STATE_FILE), { force: true });
+}
 /** Read the latest `status.json` snapshot, or undefined if absent/malformed. */
 export function readClaudeStatus(bridgeDir) {
     const raw = readJsonFile(join(bridgeDir, STATUS_FILE));