@rynx-ai/runtime 0.1.0 → 0.1.10-beta.2

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,23 @@
  */
 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 MAX_MESSAGE_CORRELATION_BACKLOG = 64;
+const MAX_SUBMISSION_OBSERVATIONS = 64;
+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. */
@@ -31,6 +47,27 @@ function userStringContent(rec) {
         return undefined; // tool_result records are arrays
     return content.trim() || undefined;
 }
+function submissionText(value) {
+    if (typeof value !== "string")
+        return undefined;
+    return value.trim() || undefined;
+}
+const COMMAND_NAME_RE = /<command-name>([\s\S]*?)<\/command-name>/;
+const COMMAND_ARGS_RE = /<command-args>([\s\S]*?)<\/command-args>/;
+/** Claude persists slash commands as XML bookkeeping rather than as the text
+ * typed into the TUI. Keep the raw record (for literal XML prompts) and add the
+ * reconstructed command as a submission-confirmation alias. */
+function submissionCandidates(content) {
+    const candidates = [content];
+    const name = COMMAND_NAME_RE.exec(content)?.[1]?.trim();
+    if (!name)
+        return candidates;
+    const args = COMMAND_ARGS_RE.exec(content)?.[1]?.trim();
+    const command = args ? `${name} ${args}` : name;
+    if (!candidates.includes(command))
+        candidates.push(command);
+    return candidates;
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -102,9 +139,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 +160,40 @@ 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();
+    /** Transcript-backed acknowledgements for web→TUI input. A direct idle
+     * submit is recorded as `promptSource:"typed"`; a submit while Claude is busy
+     * is recorded immediately as `queue-operation:enqueue` and only later
+     * promoted to `promptSource:"queued"`. The promotion is intentionally not a
+     * second acknowledgement. */
+    submissionSequence = 0;
+    submissionObservations = [];
+    /** Enqueued type-ahead inputs awaiting their eventual role:user promotion.
+     * Claude has used both `promptSource:"queued"` and `"sdk"` for that later
+     * record, so content correlation is the stable discriminator. */
+    pendingQueuedSubmissions = [];
+    /** 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
@@ -133,11 +203,16 @@ export class ClaudeLiveSession {
      *  a turn's usage on close. undefined until the statusLine hook first fires. */
     latestStatus;
     deltasOffset = 0;
-    /** MessageDisplay message ids in first-seen order, FIFO-mapped onto the
+    /** Finalized MessageDisplay ids in completion order, FIFO-mapped onto the
      *  transcript's assistant-text records so a streamed message and its final
      *  item share an itemId (message_id is absent from the transcript). */
     messageIdQueue = [];
-    seenMessageIds = new Set();
+    finalizedMessageIds = new Set();
+    /** Transcript messages that arrived before their MessageDisplay stream. A
+     *  matching late final consumes both sides so its id cannot shift the FIFO
+     *  used by the next assistant message. */
+    unmatchedTranscriptMessages = [];
+    streamedMessageText = new Map();
     constructor(opts) {
         this.bridgeDir = opts.bridgeDir;
         this.sink = opts.sink;
@@ -145,6 +220,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 +235,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
@@ -192,6 +270,48 @@ export class ClaudeLiveSession {
     isReady() {
         return this.transcriptPath !== undefined;
     }
+    /** Drain records that predate a new injection, then return a monotonic
+     * checkpoint. This prevents a lagging, older identical prompt from
+     * acknowledging the new submit. */
+    beginSubmissionObservation() {
+        this.pollTranscript();
+        return this.submissionSequence;
+    }
+    /** Whether Claude durably accepted `text` after `checkpoint`. Polling the
+     * transcript here makes submit confirmation independent of the background
+     * forwarder interval and covers both idle and type-ahead submissions. */
+    hasObservedSubmissionAfter(checkpoint, text) {
+        this.pollTranscript();
+        const expected = submissionText(text);
+        return expected !== undefined && this.submissionObservations.some((observation) => observation.sequence > checkpoint && observation.text === expected);
+    }
+    rememberSubmission(value) {
+        const text = submissionText(value);
+        if (!text)
+            return;
+        this.submissionSequence += 1;
+        this.submissionObservations.push({ sequence: this.submissionSequence, text });
+        if (this.submissionObservations.length > MAX_SUBMISSION_OBSERVATIONS) {
+            this.submissionObservations.shift();
+        }
+    }
+    rememberQueuedSubmission(value) {
+        const text = submissionText(value);
+        if (!text)
+            return;
+        this.rememberSubmission(text);
+        this.pendingQueuedSubmissions.push(text);
+        if (this.pendingQueuedSubmissions.length > MAX_SUBMISSION_OBSERVATIONS) {
+            this.pendingQueuedSubmissions.shift();
+        }
+    }
+    consumeQueuedPromotion(text) {
+        const index = this.pendingQueuedSubmissions.indexOf(text);
+        if (index < 0)
+            return false;
+        this.pendingQueuedSubmissions.splice(index, 1);
+        return true;
+    }
     start() {
         if (this.started)
             return;
@@ -199,18 +319,47 @@ 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. */
     tick() {
-        // Order matters: pollDeltas PUSHes a message_id onto the FIFO queue before
-        // pollTranscript SHIFTs it for the final item — else a same-tick delta+record
-        // (claude flushing a short message as one chunk) would miss the correlation.
+        // Read the transcript first so a user record opens its Turn before any
+        // same-tick MessageDisplay chunks are handled. The correlation layer
+        // supports either completion order; this also lets pollDeltas safely drain
+        // late chunks while no Turn is open instead of leaking them into the next.
         this.pollHooks();
-        this.pollDeltas();
         this.pollTranscript();
+        this.pollDeltas();
+        this.pollInteractions();
+        this.drainInteractionCommits();
+        this.pollAbandonedInteractions();
+        this.flushTurnFailure();
         this.pollStatus();
+        this.flushStopSignal();
         this.maybeIdleClose();
     }
     async loop() {
@@ -220,16 +369,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 +399,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
@@ -279,6 +451,11 @@ export class ClaudeLiveSession {
             }
             return;
         }
+        // Drain the old transcript before a SessionStart switches paths so a slash
+        // command recorded immediately before /clear or /fork can still
+        // acknowledge the web submission.
+        if (ev.transcriptPath !== this.transcriptPath)
+            this.pollTranscript();
         // Same session id (a plain re-announce) → nothing to do.
         if (!ev.sessionId || ev.sessionId === this.currentClaudeSessionId)
             return;
@@ -306,8 +483,8 @@ export class ClaudeLiveSession {
         this.transcriptOffset = atEof ? fileSize(newPath) : 0;
         this.seenSubagents.clear();
         this.todos.clear();
-        this.seenMessageIds.clear();
-        this.messageIdQueue.length = 0;
+        this.pendingQueuedSubmissions.length = 0;
+        this.resetMessageCorrelation();
         this.latestStatus = undefined;
         // Fresh transcript → drop the old cursor + seen ids (a new session has fresh
         // record uuids, so no collision); the next poll seeds a new forwarder state.
@@ -326,12 +503,301 @@ 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)
+        if (rec.isMeta === true)
+            return; // Claude-generated UI metadata, not a human message
+        // Type-ahead is acknowledged at enqueue time. Its later
+        // `promptSource:"queued"` user record must not count again: another
+        // identical web message may already be awaiting its own acknowledgement.
+        if (rec.type === "queue-operation") {
+            if (rec.operation === "enqueue")
+                this.rememberQueuedSubmission(rec.content);
+            // `dequeue` has no content and is followed by the promoted user record,
+            // so it must retain the correlation. `remove(content)` is cancellation:
+            // remove exactly one matching pending entry so a later identical prompt
+            // cannot be mistaken for that cancelled promotion.
+            else if (rec.operation === "remove") {
+                const removed = submissionText(rec.content);
+                if (removed)
+                    this.consumeQueuedPromotion(removed);
+            }
+            return;
+        }
         // 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) {
@@ -341,6 +807,19 @@ export class ClaudeLiveSession {
         }
         const content = userStringContent(rec);
         if (content !== undefined) {
+            const candidates = submissionCandidates(content);
+            const queuedPromotion = rec.promptSource !== "typed" &&
+                candidates.some((candidate) => this.consumeQueuedPromotion(candidate));
+            // Submission acknowledgement is independent of UI classification. A
+            // legitimate web prompt can begin with "<" (for example HTML) even
+            // though the mirror below treats provider-generated XML markers as
+            // bookkeeping. Exact content + checkpoint matching keeps this safe.
+            if (!queuedPromotion &&
+                rec.promptSource !== "queued" &&
+                rec.promptSource !== "sdk") {
+                for (const candidate of candidates)
+                    this.rememberSubmission(candidate);
+            }
             // A local `!` command records its input+output as `<bash-*>` markers — mirror
             // it as a self-contained terminal_command turn (before the prompt check, as
             // it too is `<`-prefixed).
@@ -351,12 +830,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();
             }
@@ -430,20 +920,43 @@ export class ClaudeLiveSession {
      *  events. Guarded on an open turn — deltas belong to the turn the user record
      *  opened; the offset advances only once processed. */
     pollDeltas() {
-        if (!this.turnOpen)
-            return;
         const { deltas, nextOffset } = readMessageDeltasFrom(this.bridgeDir, this.deltasOffset);
         this.deltasOffset = nextOffset;
+        // MessageDisplay has no Turn id. Chunks observed while idle belong to the
+        // Turn that just closed and must never be replayed into a later Turn.
+        if (!this.turnOpen)
+            return;
         for (const d of deltas) {
-            if (!this.seenMessageIds.has(d.messageId)) {
-                this.seenMessageIds.add(d.messageId);
-                this.messageIdQueue.push(d.messageId);
+            this.streamedMessageText.set(d.messageId, (this.streamedMessageText.get(d.messageId) ?? "") + d.delta);
+            this.sink.onEvent({
+                type: "token",
+                text: d.delta,
+                metadata: {
+                    itemId: d.messageId,
+                    dedupeAgainstCompleted: true,
+                    final: d.final,
+                },
+            });
+            if (d.final && !this.finalizedMessageIds.has(d.messageId)) {
+                this.finalizedMessageIds.add(d.messageId);
+                this.finalizeMessageDisplay(d.messageId);
             }
-            this.sink.onEvent({ type: "token", text: d.delta, metadata: { itemId: d.messageId } });
         }
         if (deltas.length)
             this.lastActivityAt = this.now();
     }
+    finalizeMessageDisplay(messageId) {
+        const text = this.streamedMessageText.get(messageId);
+        this.streamedMessageText.delete(messageId);
+        if (text === undefined)
+            return;
+        const transcriptIndex = this.unmatchedTranscriptMessages.indexOf(text);
+        if (transcriptIndex >= 0) {
+            this.unmatchedTranscriptMessages.splice(transcriptIndex, 1);
+            return;
+        }
+        this.messageIdQueue.push(messageId);
+    }
     /** Refresh the latest statusLine context/cost snapshot (a last-writer-wins file
      *  the statusLine hook overwrites on every TUI render). */
     pollStatus() {
@@ -479,12 +992,19 @@ export class ClaudeLiveSession {
     }
     /** Remap an assistant-text `message_completed` onto the FIFO-matched
      *  MessageDisplay message_id, so its streamed deltas and this final item share
-     *  an itemId. No queued delta (MessageDisplay didn't fire) → keep the transcript id. */
+     *  an itemId. No queued delta yet → keep the transcript id and remember its
+     *  text so a late MessageDisplay final can be reconciled backward. */
     remapMessageItem(event) {
         if (event.type !== "message_completed")
             return event;
         const messageId = this.messageIdQueue.shift();
-        return messageId ? { ...event, itemId: messageId } : event;
+        if (messageId)
+            return { ...event, itemId: messageId };
+        this.unmatchedTranscriptMessages.push(event.text);
+        if (this.unmatchedTranscriptMessages.length > MAX_MESSAGE_CORRELATION_BACKLOG) {
+            this.unmatchedTranscriptMessages.shift();
+        }
+        return event;
     }
     trackTool(event) {
         if (event.type !== "tool")
@@ -501,9 +1021,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 +1051,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 +1066,41 @@ 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.resetMessageCorrelation();
         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.resetMessageCorrelation();
         this.sink.onTurnError(error);
     }
+    resetMessageCorrelation() {
+        this.finalizedMessageIds.clear();
+        this.messageIdQueue.length = 0;
+        this.unmatchedTranscriptMessages.length = 0;
+        this.streamedMessageText.clear();
+    }
     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
@@ -573,20 +1117,15 @@ export class ClaudeLiveSession {
 }
 /** Claude Code renders this glyph once the input box is mounted (ready-gate). */
 const CLAUDE_PROMPT_GLYPH = "❯";
-const DRAFT_NEEDLE_MAX = 24;
-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`. */
-function draftInBox(pane, glyph, needle) {
-    const glyphLines = pane.split("\n").filter((l) => l.includes(glyph));
-    if (glyphLines.length === 0)
-        return false;
-    const tail = glyphLines[glyphLines.length - 1].split(glyph).pop() ?? "";
-    if (tail.includes("[Pasted text"))
-        return true; // claude's large-paste placeholder
-    return needle.length > 0 && tail.includes(needle);
+const CLAUDE_PROMPT_SCAN_TAIL_LINES = 5;
+/** The live composer sits at the bottom of the pane. Restricting readiness to
+ * its trailing non-empty lines prevents an old prompt glyph in scrollback from
+ * accepting input while Claude is still booting or showing another screen. */
+function claudePromptRendered(pane, glyph) {
+    const nonEmpty = pane.split(/\r?\n/).filter((line) => line.trim());
+    return nonEmpty
+        .slice(-CLAUDE_PROMPT_SCAN_TAIL_LINES)
+        .some((line) => line.includes(glyph));
 }
 async function pollUntil(pred, timeoutMs, pollMs, now, sleep, signal) {
     const deadline = now() + timeoutMs;
@@ -600,15 +1139,15 @@ async function pollUntil(pred, timeoutMs, pollMs, now, sleep, signal) {
     return pred();
 }
 /**
- * Deliver `text` into a claude TUI pane, the omnigent 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).
+ * Deliver `text` into a claude TUI pane, the reference implementation recipe:
+ *   ready-gate (poll for `❯`) → clear leftover → bracketed paste the draft
+ *   → settle → submit Enter → confirm from Claude's transcript.
  *
- * 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).
+ * caller reports, NOT a signal to fall through to a second output path. With a
+ * transcript observer, Enter is retried only when Claude has durably recorded
+ * neither a direct user prompt nor a type-ahead enqueue.
  */
 export async function injectViaTerminal(injector, text, opts = {}) {
     const glyph = opts.promptGlyph ?? CLAUDE_PROMPT_GLYPH;
@@ -625,41 +1164,45 @@ 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);
+    const ready = await pollUntil(() => claudePromptRendered(injector.capturePane(), glyph), opts.promptTimeoutMs ?? 20_000, pollMs, now, sleep, signal);
     if (cancelled())
         return false;
     if (!ready) {
         const tail = injector.capturePane().split("\n").slice(-5).join("\n");
         throw new Error(`claude prompt not ready (no "${glyph}" within timeout)\npane tail:\n${tail}`);
     }
-    // 2. Clear leftover, then bracketed-paste the draft (+\n absorbs a trailing "\").
+    // 2. Clear leftover, then bracketed-paste the draft. A final "\" is Claude's
+    // documented soft-newline escape: a bare submit Enter would consume it and
+    // mutate/strand the message. Only that edge gets one sentinel newline inside
+    // the bracketed paste; normal messages must not gain an empty input row.
     injector.clearInputLine();
-    injector.paste(`${text}\n`);
-    // 3. Wait for the draft to visibly land, then a short settle.
-    const needle = submitNeedle(text);
-    const draftSeen = await pollUntil(() => draftInBox(injector.capturePane(), glyph, needle), opts.pasteCommitMs ?? 5_000, pollMs, now, sleep, signal);
-    await sleep(opts.settleMs ?? 100);
+    injector.paste(text.endsWith("\\") ? `${text}\n` : text);
+    // 3. `paste-buffer` returns after tmux wrote the bracketed-paste frame. Give
+    // Claude a short, fixed settle window before the separate submit key; screen
+    // text is not used as an acknowledgement because submitted prompts remain in
+    // scrollback and are indistinguishable from an editable draft.
+    await sleep(opts.settleMs ?? 500);
     if (cancelled())
         return false; // Stop pressed mid-paste → don't submit
-    // 4. Submit.
-    injector.sendEnter();
-    if (!draftSeen)
-        return true; // draft never identifiable → submit blind (omnigent)
-    // 5. Verify the submit took; re-send Enter while the draft is still boxed.
-    const deadline = now() + (opts.submitVerifyMs ?? 10_000);
-    let lastEnter = now();
-    while (now() < deadline) {
-        if (cancelled())
-            return false; // Stop pressed → stop re-submitting, clear the box
-        await sleep(pollMs);
-        if (!draftInBox(injector.capturePane(), glyph, needle))
+    // 4. Submit. Without a transcript observer this remains a one-Enter
+    // best-effort operation. With one, a bounded retry handles an Enter swallowed
+    // by the TUI without ever consulting stale pane text. A direct prompt or
+    // queue enqueue ends the loop immediately.
+    const observed = opts.submissionObserved;
+    const attempts = observed
+        ? Math.max(1, Math.floor(opts.maxSubmitAttempts ?? 2))
+        : 1;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        injector.sendEnter();
+        if (!observed)
+            return true;
+        if (await pollUntil(observed, opts.submitConfirmMs ?? 2_000, pollMs, now, sleep, signal)) {
             return true;
-        if (now() - lastEnter >= (opts.submitRetryMs ?? 1_000)) {
-            injector.sendEnter();
-            lastEnter = now();
         }
+        if (cancelled())
+            return false;
     }
-    return true;
+    return false;
 }