@rynx-ai/runtime 0.1.0 → 0.1.9

package/dist/claude/native-integration.js

@@ -8,7 +8,7 @@
  *    session id (discovery); `Stop`/`StopFailure` CLOSE the turn (authoritative).
  *  - the transcript JSONL — the turn OPENS on a `role:user` prompt record and its
  *    assistant/tool records become {@link AgentEvent}s. (Turn framing is
- *    transcript-open + hook-close, matching the omnigent re-audit; `running` is
+ *    transcript-open + hook-close, matching the reference implementation re-audit; `running` is
  *    implicit between open and close, so no PTY watcher is needed.)
  *
  * The mapped events drive the SAME per-turn {@link SessionNormalizer} sink shape
@@ -19,7 +19,21 @@
  */
 import { statSync } from "node:fs";
 import { parseTerminalCommand, parseTranscriptRecord, readSubagentEvents, subagentTranscriptPath, transcriptHasForkedFrom, } from "./transcript.js";
-import { jsonlCursorFingerprint, readClaudeStatus, readForwardState, readHookEventsFrom, readJsonlFrom, readMessageDeltasFrom, resetForwardState, writeForwardState, } from "./native-bridge.js";
+import { jsonlCursorFingerprint, interactionLeaseUpdatedAt, readClaimedInteractionResult, readClaudeStatus, readForwardState, readInteractionAcksFrom, readHookEventsFrom, readInteractionRequestsFrom, readJsonlFrom, readMessageDeltasFrom, resetForwardState, removeClaimedInteractionResult, removeInteractionLease, removeInteractionResult, scrubClaudeInteractionArtifacts, writeInteractionResult, writeForwardState, } from "./native-bridge.js";
+import { boundInteractionRequest, redactInteractionResolution, validateInteractionResolution, } from "../interactions.js";
+const MAX_SETTLED_INTERACTIONS = 512;
+const INTERACTION_ACK_TIMEOUT_MS = 5_000;
+const INTERACTION_LEASE_TIMEOUT_MS = 30_000;
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // A process that exists but belongs to another user is still alive.
+        return error.code === "EPERM";
+    }
+}
 /** The trimmed string content of a `role:user` record, or undefined for
  *  tool_result (array-content) records. Keeps XML-marker bookkeeping records
  *  (`<command-name>…`, `<bash-input>…`, `<caveat>…`) — the caller classifies each. */
@@ -102,9 +116,13 @@ export class ClaudeLiveSession {
     idleCloseMs;
     stopGraceMs;
     now;
+    isProcessAlive;
+    leaseUpdatedAt;
     started = false;
     stopped = false;
     hooksOffset = 0;
+    interactionsOffset = 0;
+    interactionAcksOffset = 0;
     transcriptOffset = 0;
     /** Secondary dedup: source ids (record uuids) already forwarded, so a re-read
      *  (fingerprint reset / mid-poll death) doesn't re-emit. Persisted in the
@@ -119,11 +137,29 @@ export class ClaudeLiveSession {
     seenClaudeSessionIds = new Set();
     turnOpen = false;
     currentTurnId;
+    /** The Turn opened from a pre-transcript interaction. Its unique provisional
+     * id keeps responses distinct until the real prompt uuid can be adopted. */
+    syntheticTurn = false;
     lastActivityAt = 0;
     /** When the Stop hook fired (null = not yet) — drives the grace-period close. */
     stopPendingAt = null;
     /** Open tool-call ids (start seen, end not yet) — suppresses the idle backstop. */
     openToolIds = new Set();
+    /** Blocking native questions/permissions. Their hook subprocess is still
+     *  executing, so the Turn remains running and cannot be idle-closed. */
+    pendingInteractions = new Map();
+    settledInteractions = new Set();
+    /** Claimed response files may still contain the provider-bound, unredacted
+     * answer. Keep tracking them after canonical settlement until ACK/hook cleanup. */
+    claimedInteractions = new Map();
+    scheduledClaimScrubs = new Set();
+    /** Stop is flushed after interactions in the same poll, preventing a
+     *  request+Stop race from briefly reporting this executing Turn as idle. */
+    stopSignalPending = false;
+    /** StopFailure is likewise flushed after interactions. A blocking hook can
+     *  append its request immediately before the failure hook lands; closing here
+     *  would let the later interaction poll reopen an already-failed Turn. */
+    turnFailurePending = null;
     /** Sub-agent (Task) ids already forwarded — a Task tool_result is processed once. */
     seenSubagents = new Set();
     /** The agent's task list, keyed by task id in creation order (claude
@@ -145,6 +181,9 @@ export class ClaudeLiveSession {
         this.idleCloseMs = opts.idleCloseMs ?? 30_000;
         this.stopGraceMs = opts.stopGraceMs ?? 4_000;
         this.now = opts.now ?? (() => Date.now());
+        this.isProcessAlive = opts.isProcessAlive ?? processIsAlive;
+        this.leaseUpdatedAt = opts.interactionLeaseUpdatedAt ??
+            ((interactionId) => interactionLeaseUpdatedAt(this.bridgeDir, interactionId));
         this.transcriptPath = opts.transcriptPath;
         // 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).
@@ -157,7 +196,7 @@ export class ClaudeLiveSession {
         }
     }
     /**
-     * Restore the durable forwarder cursor for `transcriptPath` (omnigent's
+     * Restore the durable forwarder cursor for `transcriptPath` (reference implementation's
      * `_validated_transcript_state`). A cursor for a DIFFERENT file is ignored (a new
      * session starts at 0). A matching cursor whose fingerprint still validates
      * resumes at its `byteOffset`; a MISMATCH (the file was truncated/replaced) skips
@@ -199,7 +238,30 @@ export class ClaudeLiveSession {
         void this.loop();
     }
     stop() {
+        if (this.stopped)
+            return;
         this.stopped = true;
+        // A hook may have appended its request just before shutdown but not yet
+        // reached a scheduled poll. Drain it so the subprocess receives cancellation
+        // instead of remaining blocked until Claude's one-day hook timeout.
+        this.pollInteractions();
+        this.drainInteractionCommits();
+        this.cancelPendingInteractions("session_stopped");
+        // Runner shutdown closes its mirror transport immediately after this method
+        // returns, so the terminal event must be emitted synchronously here.
+        this.closeTurn();
+        this.scheduleClaimedInteractionScrubs();
+    }
+    /** 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. */
+    finalizeStop() {
+        if (!this.stopped)
+            this.stop();
+        scrubClaudeInteractionArtifacts(this.bridgeDir);
+        this.pendingInteractions.clear();
+        this.claimedInteractions.clear();
+        this.scheduledClaimScrubs.clear();
     }
     /** One poll cycle (hooks → transcript → idle backstop). Exposed for tests to
      *  drive deterministically; the async {@link loop} just calls it on an interval. */
@@ -210,7 +272,12 @@ export class ClaudeLiveSession {
         this.pollHooks();
         this.pollDeltas();
         this.pollTranscript();
+        this.pollInteractions();
+        this.drainInteractionCommits();
+        this.pollAbandonedInteractions();
+        this.flushTurnFailure();
         this.pollStatus();
+        this.flushStopSignal();
         this.maybeIdleClose();
     }
     async loop() {
@@ -220,16 +287,18 @@ export class ClaudeLiveSession {
             }
             catch (err) {
                 // A single failing poll must NOT kill the whole forwarder — that would
-                // desync chat↔terminal permanently. Log + continue, per omnigent's
+                // desync chat↔terminal permanently. Log + continue, per reference implementation's
                 // 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));
         }
-        if (this.turnOpen) {
-            this.turnOpen = false;
-            this.sink.onTurnEnd(this.statusUsage());
-        }
+        // Catch a request appended while the loop was waking up to observe stopped.
+        this.pollInteractions();
+        this.drainInteractionCommits();
+        this.cancelPendingInteractions("session_stopped");
+        this.closeTurn();
+        this.scheduleClaimedInteractionScrubs();
     }
     pollHooks() {
         const { events, nextOffset } = readHookEventsFrom(this.bridgeDir, this.hooksOffset);
@@ -248,14 +317,35 @@ export class ClaudeLiveSession {
                 return;
             // Stop only signals idle — it does NOT close the turn (see onIdle): closing
             // here would split a late-flushing assistant record into its own turn.
-            if (ev.eventName === "StopFailure")
-                this.closeTurnError(new Error("claude turn failed"));
+            if (ev.eventName === "StopFailure") {
+                this.stopSignalPending = false;
+                this.stopPendingAt = null;
+                this.turnFailurePending = new Error("claude turn failed");
+            }
             else {
-                this.sink.onIdle();
+                this.stopSignalPending = true;
                 this.stopPendingAt = this.now(); // close after a short grace (late assistant flush)
             }
         }
     }
+    /** Process a provider failure only after this tick has discovered every
+     *  blocking request already appended by its hook subprocess. */
+    flushTurnFailure() {
+        const error = this.turnFailurePending;
+        if (!error)
+            return;
+        this.turnFailurePending = null;
+        this.closeTurnError(error);
+    }
+    /** Emit the Stop idle signal only after this tick has discovered native
+     *  interactions. A pending question/permission is active execution, not idle. */
+    flushStopSignal() {
+        if (!this.stopSignalPending)
+            return;
+        this.stopSignalPending = false;
+        if (this.pendingInteractions.size === 0)
+            this.sink.onIdle();
+    }
     /** SessionStart drives discovery (first) and rotation (a later one with a NEW
      *  session id + transcript). `/clear` → source="clear"; `/fork` → source="resume"
      *  into an unseen id with a forkedFrom marker. Any other new-transcript
@@ -326,12 +416,282 @@ export class ClaudeLiveSession {
         if (records.length > 0)
             this.persistForwardState();
     }
+    /** Tail blocking hook requests after transcript records, so an interaction
+     *  emitted in the same poll attaches to the user Turn that caused it. */
+    pollInteractions() {
+        const { requests, nextOffset } = readInteractionRequestsFrom(this.bridgeDir, this.interactionsOffset);
+        this.interactionsOffset = nextOffset;
+        for (const entry of requests) {
+            const interactionId = entry.interactionId;
+            if (this.pendingInteractions.has(interactionId) ||
+                this.settledInteractions.has(interactionId)) {
+                continue;
+            }
+            const bounded = boundInteractionRequest(entry.request);
+            if (!bounded.ok) {
+                writeInteractionResult(this.bridgeDir, interactionId, {
+                    status: "cancelled",
+                    reason: bounded.reason,
+                });
+                this.rememberSettled(interactionId);
+                continue;
+            }
+            this.ensureTurn(`interaction_${interactionId}`);
+            const pending = {
+                request: bounded.request,
+                observedAt: this.now(),
+                ...(entry.waiterPid ? { waiterPid: entry.waiterPid } : {}),
+                ...(this.currentTurnId ? { turnId: this.currentTurnId } : {}),
+            };
+            this.pendingInteractions.set(interactionId, pending);
+            // A native hook is blocked waiting for the answer. Any Stop observed in
+            // this same poll cannot make the Session idle or close its Turn.
+            this.stopSignalPending = false;
+            this.stopPendingAt = null;
+            this.lastActivityAt = this.now();
+            this.sink.onInteraction({
+                type: "requested",
+                request: bounded.request,
+                ...(pending.turnId ? { turnId: pending.turnId } : {}),
+            });
+        }
+    }
+    drainInteractionCommits() {
+        this.pollInteractionAcks();
+        this.pollInteractionClaims();
+        this.pollClaimedInteractionCleanup();
+    }
+    /** A hook acknowledgement is the commit point: it is appended after the hook
+     * consumes the one-shot response and before it returns the native verdict. */
+    pollInteractionAcks() {
+        const { acks, nextOffset } = readInteractionAcksFrom(this.bridgeDir, this.interactionAcksOffset);
+        this.interactionAcksOffset = nextOffset;
+        for (const ack of acks) {
+            removeInteractionResult(this.bridgeDir, ack.interactionId);
+            removeClaimedInteractionResult(this.bridgeDir, ack.interactionId);
+            removeInteractionLease(this.bridgeDir, ack.interactionId);
+            this.claimedInteractions.delete(ack.interactionId);
+            const pending = this.pendingInteractions.get(ack.interactionId);
+            if (!pending || this.settledInteractions.has(ack.interactionId))
+                continue;
+            if (ack.status === "resolved") {
+                const invalid = validateInteractionResolution(pending.request, ack.resolution);
+                if (invalid) {
+                    this.settleCancelledInteraction(ack.interactionId, pending, "native_invalid_acknowledgement");
+                    continue;
+                }
+                this.pendingInteractions.delete(ack.interactionId);
+                this.rememberSettled(ack.interactionId);
+                this.stopSignalPending = false;
+                this.stopPendingAt = null;
+                this.lastActivityAt = this.now();
+                this.sink.onInteraction({
+                    type: "resolved",
+                    interactionId: ack.interactionId,
+                    resolution: redactInteractionResolution(pending.request, ack.resolution),
+                    ...(pending.turnId ? { turnId: pending.turnId } : {}),
+                });
+                continue;
+            }
+            this.pendingInteractions.delete(ack.interactionId);
+            this.rememberSettled(ack.interactionId);
+            this.sink.onInteraction({
+                type: "cancelled",
+                interactionId: ack.interactionId,
+                ...(ack.reason ? { reason: ack.reason } : {}),
+                ...(pending.turnId ? { turnId: pending.turnId } : {}),
+            });
+        }
+    }
+    /** A claimed response is already consumed by the native hook. This fallback
+     * converges the interaction even if the hook exits before appending its
+     * redacted ACK. */
+    pollInteractionClaims() {
+        for (const [interactionId, pending] of [...this.pendingInteractions]) {
+            const claimed = readClaimedInteractionResult(this.bridgeDir, interactionId);
+            if (!claimed)
+                continue;
+            removeInteractionResult(this.bridgeDir, interactionId);
+            this.settleClaimedInteraction(interactionId, pending, claimed);
+        }
+    }
+    /** A request cannot remain actionable after its blocking hook exits. A short
+     * post-submit timeout also converges requests created by older hooks that did
+     * not publish a waiter pid, and scrubs any unacknowledged secret response. */
+    pollAbandonedInteractions() {
+        const now = this.now();
+        for (const [interactionId, pending] of [...this.pendingInteractions]) {
+            const waiterExited = pending.waiterPid !== undefined &&
+                !this.isProcessAlive(pending.waiterPid);
+            const leaseAt = this.leaseUpdatedAt(interactionId) ?? pending.observedAt;
+            const leaseExpired = pending.waiterPid !== undefined &&
+                now - leaseAt >= INTERACTION_LEASE_TIMEOUT_MS;
+            // New hooks publish both a waiter pid and a heartbeat lease. Let their
+            // atomic claim decide delivery; the short ACK timeout is only a convergence
+            // fallback for bridge requests produced by older hook versions.
+            const responseUnacknowledged = pending.waiterPid === undefined &&
+                pending.submittedAt !== undefined &&
+                now - pending.submittedAt >= INTERACTION_ACK_TIMEOUT_MS;
+            if (!waiterExited && !leaseExpired && !responseUnacknowledged)
+                continue;
+            const reason = waiterExited
+                ? "native_waiter_exited"
+                : leaseExpired
+                    ? "native_waiter_lease_expired"
+                    : "native_response_unacknowledged";
+            this.cancelOrSettlePendingInteraction(interactionId, pending, reason, 
+            // A dead process cannot consume a cancellation verdict; scrub its
+            // one-shot result instead of leaving stale response material on disk.
+            !waiterExited);
+        }
+    }
+    /** Deliver an answer to the blocked hook. The bridge file contains the real
+     *  answer; only the canonical resolved event receives a secret-redacted copy. */
+    resolveInteraction(interactionId, resolution) {
+        const pending = this.pendingInteractions.get(interactionId);
+        if (!pending) {
+            return this.settledInteractions.has(interactionId)
+                ? { disposition: "already_resolved" }
+                : { disposition: "not_found" };
+        }
+        if (pending.waiterPid !== undefined) {
+            const waiterExited = !this.isProcessAlive(pending.waiterPid);
+            const leaseAt = this.leaseUpdatedAt(interactionId) ?? pending.observedAt;
+            const leaseExpired = this.now() - leaseAt >= INTERACTION_LEASE_TIMEOUT_MS;
+            if (waiterExited || leaseExpired) {
+                this.cancelOrSettlePendingInteraction(interactionId, pending, waiterExited ? "native_waiter_exited" : "native_waiter_lease_expired");
+                return { disposition: "already_resolved" };
+            }
+        }
+        if (pending.submitted)
+            return { disposition: "already_resolved" };
+        const invalid = validateInteractionResolution(pending.request, resolution);
+        if (invalid)
+            return { disposition: "invalid", message: invalid };
+        if (!writeInteractionResult(this.bridgeDir, interactionId, { status: "resolved", resolution })) {
+            return { disposition: "invalid", message: "invalid interaction id" };
+        }
+        pending.submitted = true;
+        pending.submittedAt = this.now();
+        return { disposition: "applied" };
+    }
+    cancelPendingInteractions(reason) {
+        for (const [interactionId, pending] of [...this.pendingInteractions]) {
+            this.cancelOrSettlePendingInteraction(interactionId, pending, reason);
+        }
+    }
+    /** Terminal cancellation may race the hook's atomic result claim. A claim
+     * always wins; otherwise the cancellation file becomes the hook's verdict. */
+    cancelOrSettlePendingInteraction(interactionId, pending, reason, deliverCancellation = true) {
+        const alreadyClaimed = readClaimedInteractionResult(this.bridgeDir, interactionId);
+        if (alreadyClaimed) {
+            removeInteractionResult(this.bridgeDir, interactionId);
+            this.settleClaimedInteraction(interactionId, pending, alreadyClaimed);
+            return;
+        }
+        if (deliverCancellation) {
+            writeInteractionResult(this.bridgeDir, interactionId, { status: "cancelled", reason });
+        }
+        else {
+            removeInteractionResult(this.bridgeDir, interactionId);
+        }
+        const racedClaim = readClaimedInteractionResult(this.bridgeDir, interactionId);
+        if (racedClaim) {
+            removeInteractionResult(this.bridgeDir, interactionId);
+            this.settleClaimedInteraction(interactionId, pending, racedClaim);
+            return;
+        }
+        this.settleCancelledInteraction(interactionId, pending, reason);
+    }
+    settleClaimedInteraction(interactionId, pending, result) {
+        this.claimedInteractions.set(interactionId, {
+            observedAt: this.now(),
+            ...(pending.waiterPid ? { waiterPid: pending.waiterPid } : {}),
+        });
+        if (result.status === "resolved") {
+            const invalid = validateInteractionResolution(pending.request, result.resolution);
+            if (!invalid) {
+                this.pendingInteractions.delete(interactionId);
+                this.rememberSettled(interactionId);
+                this.stopSignalPending = false;
+                this.stopPendingAt = null;
+                this.lastActivityAt = this.now();
+                this.sink.onInteraction({
+                    type: "resolved",
+                    interactionId,
+                    resolution: redactInteractionResolution(pending.request, result.resolution),
+                    ...(pending.turnId ? { turnId: pending.turnId } : {}),
+                });
+                return;
+            }
+        }
+        this.settleCancelledInteraction(interactionId, pending, result.status === "cancelled"
+            ? result.reason ?? "native_interaction_cancelled"
+            : "native_invalid_claim");
+    }
+    /** A claim is the hook's private handoff file and can contain secret answers.
+     * ACK/finally normally removes it; process death or an expired lease is the
+     * crash fallback after the canonical interaction has already settled. */
+    pollClaimedInteractionCleanup() {
+        const now = this.now();
+        for (const [interactionId, claimed] of [...this.claimedInteractions]) {
+            const result = readClaimedInteractionResult(this.bridgeDir, interactionId);
+            if (!result) {
+                this.claimedInteractions.delete(interactionId);
+                continue;
+            }
+            const waiterExited = claimed.waiterPid !== undefined &&
+                !this.isProcessAlive(claimed.waiterPid);
+            const leaseAt = this.leaseUpdatedAt(interactionId) ?? claimed.observedAt;
+            const leaseExpired = now - leaseAt >= INTERACTION_LEASE_TIMEOUT_MS;
+            if (!waiterExited && !leaseExpired)
+                continue;
+            removeClaimedInteractionResult(this.bridgeDir, interactionId);
+            removeInteractionLease(this.bridgeDir, interactionId);
+            this.claimedInteractions.delete(interactionId);
+        }
+    }
+    /** Once this forwarder stops it can no longer poll a later hook crash. Keep a
+     * short unref'd scrub deadline so unredacted claim material cannot persist for
+     * the lifetime of the daemon. */
+    scheduleClaimedInteractionScrubs() {
+        for (const interactionId of this.claimedInteractions.keys()) {
+            if (this.scheduledClaimScrubs.has(interactionId))
+                continue;
+            this.scheduledClaimScrubs.add(interactionId);
+            const timer = setTimeout(() => {
+                removeClaimedInteractionResult(this.bridgeDir, interactionId);
+                removeInteractionLease(this.bridgeDir, interactionId);
+                this.claimedInteractions.delete(interactionId);
+                this.scheduledClaimScrubs.delete(interactionId);
+            }, INTERACTION_LEASE_TIMEOUT_MS);
+            timer.unref?.();
+        }
+    }
+    settleCancelledInteraction(interactionId, pending, reason) {
+        this.pendingInteractions.delete(interactionId);
+        this.rememberSettled(interactionId);
+        this.sink.onInteraction({
+            type: "cancelled",
+            interactionId,
+            reason,
+            ...(pending.turnId ? { turnId: pending.turnId } : {}),
+        });
+    }
+    rememberSettled(interactionId) {
+        this.settledInteractions.add(interactionId);
+        if (this.settledInteractions.size <= MAX_SETTLED_INTERACTIONS)
+            return;
+        const oldest = this.settledInteractions.values().next().value;
+        if (oldest)
+            this.settledInteractions.delete(oldest);
+    }
     handleRecord(rec) {
         if (rec.isSidechain === true)
             return; // sub-agent turns (Phase 9 forwards them)
         // Secondary dedup: skip a record whose source id was already forwarded (a
         // re-read after a fingerprint reset). rynx emits a record's items atomically,
-        // so the record uuid is the source key (vs omnigent's per-block key for its
+        // so the record uuid is the source key (vs reference implementation's per-block key for its
         // per-item POST). Records without a uuid fall through undeduped (rare).
         const sourceId = typeof rec.uuid === "string" && rec.uuid ? rec.uuid : undefined;
         if (sourceId) {
@@ -351,12 +711,23 @@ export class ClaudeLiveSession {
             }
             // A real prompt (not an XML-marker bookkeeping record) opens a new turn.
             if (!content.startsWith("<")) {
-                this.closeTurn();
-                this.currentTurnId = typeof rec.uuid === "string" ? rec.uuid : undefined;
-                this.turnOpen = true;
-                this.openToolIds.clear();
-                this.stopPendingAt = null;
-                this.sink.onTurnStart(this.currentTurnId);
+                const turnId = typeof rec.uuid === "string" ? rec.uuid : undefined;
+                if (this.turnOpen && this.syntheticTurn) {
+                    // A hook can flush just before the transcript's user record. The
+                    // interaction already opened a unique provisional response; adopt the
+                    // real turn id internally without closing/cancelling that same Turn.
+                    this.currentTurnId = turnId;
+                    this.syntheticTurn = false;
+                }
+                else {
+                    this.closeTurn();
+                    this.currentTurnId = turnId;
+                    this.turnOpen = true;
+                    this.syntheticTurn = false;
+                    this.openToolIds.clear();
+                    this.stopPendingAt = null;
+                    this.sink.onTurnStart(this.currentTurnId);
+                }
                 this.sink.onUserMessage(content);
                 this.lastActivityAt = this.now();
             }
@@ -439,7 +810,11 @@ export class ClaudeLiveSession {
                 this.seenMessageIds.add(d.messageId);
                 this.messageIdQueue.push(d.messageId);
             }
-            this.sink.onEvent({ type: "token", text: d.delta, metadata: { itemId: d.messageId } });
+            this.sink.onEvent({
+                type: "token",
+                text: d.delta,
+                metadata: { itemId: d.messageId, dedupeAgainstCompleted: true },
+            });
         }
         if (deltas.length)
             this.lastActivityAt = this.now();
@@ -501,9 +876,13 @@ export class ClaudeLiveSession {
                 this.openToolIds.delete(id);
         }
     }
-    ensureTurn() {
+    ensureTurn(provisionalTurnId) {
         if (this.turnOpen)
             return;
+        if (!this.currentTurnId && provisionalTurnId) {
+            this.currentTurnId = provisionalTurnId;
+            this.syntheticTurn = true;
+        }
         this.turnOpen = true;
         this.sink.onTurnStart(this.currentTurnId);
     }
@@ -527,6 +906,8 @@ export class ClaudeLiveSession {
     noteInterrupted() {
         if (!this.turnOpen)
             return;
+        this.cancelPendingInteractions("turn_interrupted");
+        this.stopSignalPending = false;
         this.sink.onIdle();
         this.stopPendingAt = this.now();
     }
@@ -540,23 +921,33 @@ export class ClaudeLiveSession {
     closeTurn() {
         if (!this.turnOpen)
             return;
+        this.drainInteractionCommits();
+        this.cancelPendingInteractions("turn_completed");
         this.turnOpen = false;
         this.currentTurnId = undefined;
+        this.syntheticTurn = false;
         this.openToolIds.clear();
+        this.stopSignalPending = false;
         this.stopPendingAt = null;
         this.sink.onTurnEnd(this.statusUsage());
     }
     closeTurnError(error) {
         if (!this.turnOpen)
             return;
+        this.drainInteractionCommits();
+        this.cancelPendingInteractions("turn_failed");
         this.turnOpen = false;
         this.currentTurnId = undefined;
+        this.syntheticTurn = false;
         this.openToolIds.clear();
+        this.stopSignalPending = false;
         this.stopPendingAt = null;
         this.sink.onTurnError(error);
     }
     maybeIdleClose() {
-        if (!this.turnOpen || this.openToolIds.size > 0)
+        if (!this.turnOpen ||
+            this.openToolIds.size > 0 ||
+            this.pendingInteractions.size > 0)
             return;
         const now = this.now();
         // Primary close: a short grace after the Stop hook, so a late assistant record
@@ -578,7 +969,7 @@ function submitNeedle(text) {
     return (text.split("\n")[0] ?? "").slice(0, DRAFT_NEEDLE_MAX);
 }
 /** Whether the pasted draft is visibly sitting in the input box (the last line
- *  carrying the prompt glyph). Mirrors omnigent's `_draft_in_input_box`. */
+ *  carrying the prompt glyph). Mirrors reference implementation's `_draft_in_input_box`. */
 function draftInBox(pane, glyph, needle) {
     const glyphLines = pane.split("\n").filter((l) => l.includes(glyph));
     if (glyphLines.length === 0)
@@ -600,12 +991,12 @@ async function pollUntil(pred, timeoutMs, pollMs, now, sleep, signal) {
     return pred();
 }
 /**
- * Deliver `text` into a claude TUI pane, the omnigent recipe:
+ * Deliver `text` into a claude TUI pane, the reference implementation recipe:
  *   ready-gate (poll for `❯`) → clear leftover → bracketed paste (+ trailing
  *   newline) → wait for the draft to land → settle → submit Enter → verify the
  *   draft left the box (re-send Enter while it hasn't).
  *
- * THROWS if the prompt never appears within the ready-gate window (omnigent
+ * THROWS if the prompt never appears within the ready-gate window (reference implementation
  * `_wait_for_claude_prompt_ready` RAISE) — a not-ready pane is a hard error the
  * caller reports, NOT a signal to fall through to a second output path. Returns
  * `true` once the message is submitted (best-effort even if submit-verify times out).
@@ -625,7 +1016,7 @@ export async function injectViaTerminal(injector, text, opts = {}) {
         injector.clearInputLine();
         return true;
     };
-    // 1. Ready-gate. No prompt within the window → THROW (omnigent RAISE): a
+    // 1. Ready-gate. No prompt within the window → THROW (reference implementation RAISE): a
     //    not-ready pane is a hard error, never a fall-through-to-run signal.
     const ready = await pollUntil(() => injector.capturePane().includes(glyph), opts.promptTimeoutMs ?? 20_000, pollMs, now, sleep, signal);
     if (cancelled())
@@ -646,7 +1037,7 @@ export async function injectViaTerminal(injector, text, opts = {}) {
     // 4. Submit.
     injector.sendEnter();
     if (!draftSeen)
-        return true; // draft never identifiable → submit blind (omnigent)
+        return true; // draft never identifiable → submit blind (reference implementation)
     // 5. Verify the submit took; re-send Enter while the draft is still boxed.
     const deadline = now() + (opts.submitVerifyMs ?? 10_000);
     let lastEnter = now();

package/dist/claude/settings.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Build the single explicit settings document for a rynx-managed Claude
+ * Session. Host/project settings still provide auth, env and permission policy,
+ * but their plugins and hooks are excluded: rynx must be the only owner of
+ * PermissionRequest and AskUserQuestion, and Agent Skills arrive only through
+ * the selected `--plugin-dir`.
+ */
+export declare function buildManagedClaudeSettings(cwd: string, rynxSettings: object, configDir?: string): Record<string, unknown>;