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

package/dist/claude/native-hook-main.js

@@ -3,7 +3,8 @@
  * interaction hooks rendezvous with the runner through the session bridge. */
 import { createHash, randomUUID } from "node:crypto";
 import { realpathSync } from "node:fs";
-import { claimInteractionResult, recordInteractionAck, recordHookEvent, recordInteractionRequest, removeClaimedInteractionResult, removeInteractionLease, touchInteractionLease, } from "./native-bridge.js";
+import { claimInteractionResult, annotateClaudeResumeContext, recordInteractionAck, recordHookEvent, recordInteractionRequest, removeClaimedInteractionResult, removeInteractionLease, touchInteractionLease, } from "./native-bridge.js";
+import { waitForTranscriptForkSignal, } from "./transcript.js";
 import { boundInteractionRequest, redactInteractionResolution, } from "../interactions.js";
 function argValue(argv, flag) {
     const i = argv.indexOf(flag);
@@ -23,6 +24,21 @@ function asRecord(value) {
 function asString(value) {
     return typeof value === "string" && value ? value : undefined;
 }
+async function annotateClaudeForkSignal(bridgeDir, payload) {
+    annotateClaudeResumeContext(bridgeDir, payload);
+    if (payload.hook_event_name !== "SessionStart" ||
+        payload.source !== "resume" ||
+        payload.rynx_claude_session_was_seen === true)
+        return;
+    const transcriptPath = asString(payload.transcript_path);
+    const sessionId = asString(payload.session_id);
+    const sourceSessionId = asString(payload.rynx_previous_claude_session_id);
+    if (!transcriptPath || !sessionId || !sourceSessionId)
+        return;
+    const recordedAt = Date.now();
+    if (await waitForTranscriptForkSignal(transcriptPath, sessionId, sourceSessionId, recordedAt))
+        payload.rynx_fork_detected = true;
+}
 function interactionId(payload) {
     // PermissionRequest does not carry a tool_use_id. A per-process nonce keeps
     // repeated or concurrent identical prompts from collapsing into one bridge id.
@@ -176,6 +192,43 @@ function permissionRequest(id, payload, toolInput, suggestions) {
     const toolName = asString(payload.tool_name) ?? "tool";
     const command = asString(toolInput.command) ?? asString(toolInput.file_path);
     const cwd = asString(payload.cwd);
+    if (toolName === "ExitPlanMode") {
+        const plan = asString(toolInput.plan) ?? "Plan details were not provided by Claude.";
+        return {
+            interactionId: id,
+            kind: "permission",
+            title: "Plan review",
+            fields: [{
+                    id: "feedback",
+                    type: "text",
+                    label: "What should change about the plan?",
+                    required: false,
+                    multiline: true,
+                    placeholder: "Revision feedback (optional)",
+                }],
+            actions: [
+                {
+                    id: "allow_auto",
+                    label: "Yes, and use auto mode",
+                    style: "primary",
+                    requiresAnswers: false,
+                },
+                {
+                    id: "allow_manual",
+                    label: "Yes, manually approve edits",
+                    requiresAnswers: false,
+                },
+                {
+                    id: "deny_feedback",
+                    label: "Reject with feedback",
+                    style: "danger",
+                    requiresAnswers: false,
+                },
+            ],
+            context: { toolName, summary: plan },
+            createdAt: Date.now(),
+        };
+    }
     return {
         interactionId: id,
         kind: "permission",
@@ -261,6 +314,32 @@ function nativeVerdict(hookKind, payload, result, suggestions) {
                 },
             };
     }
+    if (toolName === "ExitPlanMode") {
+        const feedback = answerText(resolution.answers?.feedback).trim();
+        const behavior = resolution.actionId === "allow_auto" ||
+            resolution.actionId === "allow_manual"
+            ? "allow"
+            : "deny";
+        return {
+            hookSpecificOutput: {
+                hookEventName: "PermissionRequest",
+                decision: {
+                    behavior,
+                    ...(behavior === "deny" && feedback ? { message: feedback } : {}),
+                    ...(behavior === "allow"
+                        ? {
+                            updatedInput: toolInput,
+                            updatedPermissions: [{
+                                    type: "setMode",
+                                    mode: resolution.actionId === "allow_auto" ? "auto" : "default",
+                                    destination: "session",
+                                }],
+                        }
+                        : {}),
+                },
+            },
+        };
+    }
     const suggestionMatch = /^allow_suggestion_(\d+)$/.exec(resolution.actionId);
     const suggestionIndex = suggestionMatch ? Number(suggestionMatch[1]) : -1;
     const selectedSuggestion = Number.isSafeInteger(suggestionIndex)
@@ -301,6 +380,7 @@ async function main() {
     }
     if (!hookKind) {
         try {
+            await annotateClaudeForkSignal(bridgeDir, payload);
             recordHookEvent(bridgeDir, payload);
         }
         catch {

package/dist/claude/native-hooks.js

@@ -48,6 +48,13 @@ export function buildClaudeHookSettings(options) {
         SessionStart: [{ hooks: [observerHook] }],
         Stop: [{ hooks: [observerHook] }],
         StopFailure: [{ hooks: [observerHook] }],
+        TaskCreated: [{ hooks: [observerHook] }],
+        TaskCompleted: [{ hooks: [observerHook] }],
+        PostToolUse: [
+            { matcher: "TodoWrite", hooks: [observerHook] },
+            { matcher: "TaskUpdate", hooks: [observerHook] },
+        ],
+        PreCompact: [{ hooks: [observerHook] }],
     };
     if (options.permissionMode === "bypassPermissions") {
         const ask = shJoin([node, entry, "ask-user-question", "--bridge-dir", options.bridgeDir]);

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

@@ -1,18 +1,49 @@
 import type { AgentEvent, SessionInteractionResolution, TerminalCommandData, TodoItem } from "@rynx-ai/core";
 import type { ResolveInteractionResult, RuntimeInteractionEvent } from "../interactions.js";
+import { type ClaudeRunnerStatus } from "./session-status.js";
 /** Mirror sink — the same shape as `CodexForwarderSink` so the host reuses one
  *  per-turn normalizer wiring for both runtimes. */
 export interface ClaudeForwarderSink {
+    /** Begin one transcript source record. The host derives per-item source keys
+     * from this stable base while still running the normalizer for already-seen
+     * items so later records recover the same turn/tool state. */
+    onTranscriptRecordStart?(sourceBase: string, isHandled: (sourceId: string) => boolean, delivery?: {
+        lane?: string;
+        deadLetterPath?: string;
+        /** Persist an individual handled item before the containing record's
+         * byte cursor is allowed to advance. */
+        onHandled?: (sourceId: string) => void;
+    }): void;
+    /** Resolve only after every newly emitted durable item from the current
+     * record has reached a handled delivery outcome. Returns all per-item keys. */
+    onTranscriptRecordEnd?(): Promise<readonly string[]>;
     /** A turn began; `turnId` (the user record uuid) derives a stable responseId. */
     onTurnStart(turnId?: string): void;
     /** The user's prompt text (a `role:user` conversation message — not identity). */
     onUserMessage(text: string): void;
+    /** Provider-generated task notification persisted as hidden model context.
+     * It owns an independent response identity and never changes the parent Turn. */
+    onMetaUserMessage?(text: string, sourceKey?: string, parentToolCallId?: string): void;
+    /** Claude Code native sub-agent task prompt, nested under the parent Task
+     * tool call instead of opening a parent Session turn. */
+    onSubagentUserMessage?(text: string, parentToolCallId: string): void;
+    /** A native sub-agent's top-level `!cmd`, nested under its parent Task. */
+    onSubagentTerminalCommand?(cmd: TerminalCommandData, parentToolCallId: string): void;
+    /** Resolve/publish the canonical parent Turn for a native sub-agent. This
+     * mapping is persisted beside the independent child cursor. */
+    resolveSubagentParentResponseId?(parentToolCallId: string): string | undefined;
+    onSubagentParentResponse?(parentToolCallId: string, responseId: string): void;
     /** A local shell command the user ran in the TUI (claude `!` bash mode), framed
      *  as its own mini-turn (an `onTurnStart`/`onTurnEnd` pair brackets this call). */
     onTerminalCommand(cmd: TerminalCommandData): void;
     /** The agent's task list changed (claude `TaskCreate`/`TaskUpdate`) — the WHOLE
      *  current list (a session-level snapshot, not tied to a turn). */
     onTodos(todos: TodoItem[]): void;
+    /** Best-effort spinner edges around Claude's native compaction. */
+    onCompactionStatus?(status: "in_progress" | "completed" | "failed"): void;
+    /** Persist one compaction boundary. `true` means confirmed/ambiguous-handled;
+     * `false` means a bounded secondary hook delivery was dropped. */
+    onCompactionBoundary?(summary: string, sequence: number, source: "transcript" | "hook"): boolean | Promise<boolean>;
     /** One mapped event within the current turn. */
     onEvent(event: AgentEvent): void;
     /** A provider-neutral question/permission requested or settled while this
@@ -20,15 +51,23 @@ export interface ClaudeForwarderSink {
     onInteraction(event: RuntimeInteractionEvent): void;
     /** The current turn finished (a new user prompt, or the inactivity backstop).
      *  `usage` carries the latest statusLine context/cost snapshot, when captured. */
-    onTurnEnd(usage?: Record<string, unknown>): void;
-    /** The runtime went idle (Stop hook) — surface idle status WITHOUT finalizing
+    onTurnEnd(usage?: Record<string, unknown>, backgroundTaskCount?: number, reason?: "rotation"): void;
+    /** The current turn ended because the user explicitly interrupted it. */
+    onTurnInterrupted?(usage?: Record<string, unknown>): void;
+    /** Escape was sent for the open Turn. Publish cancelled UI state immediately;
+     *  the final close remains delayed so a late transcript record can join it. */
+    onTurnInterruptRequested?(): void;
+    /** The runtime status changed according to Claude's session metadata. */
+    onStatus?(status: ClaudeRunnerStatus, blockedOn?: string): void;
+    /** The runtime went idle on the legacy hook fallback — surface idle WITHOUT finalizing
      *  the turn. claude fires Stop around the same time it flushes the final
      *  assistant record and the two orderings race; finalizing here would split a
      *  late assistant record into its own turn. The turn is finalized by the next
      *  user prompt or the inactivity backstop, so a late record still joins it. */
-    onIdle(): void;
-    /** The current turn failed on the runtime (StopFailure hook). */
-    onTurnError(error: Error): void;
+    onIdle(backgroundTaskCount?: number, sourceId?: string): void | Promise<void>;
+    /** Claude's current Turn or native runtime failed (StopFailure/pane exit).
+     * May fire between Turns so Session-level failure can retire stale liveness. */
+    onTurnError(error: Error, sourceId?: string): void | Promise<void>;
     /** Fired once SessionStart reveals claude's session id + transcript path, so
      *  the host can persist the id and release its readiness gate. */
     onSessionDiscovered?(claudeSessionId: string, transcriptPath: string): void;
@@ -36,10 +75,10 @@ export interface ClaudeForwarderSink {
      *  binding. The host keeps the original binding and fails readiness. */
     onSessionResumeError?(error: Error): void;
     /** The claude session rotated (`/clear` → fresh, `/fork` → derived): a new
-     *  SessionStart reported a new session id + transcript. The forwarder has
-     *  already re-pointed to the new transcript and reset its per-session state; the
-     *  host mints a fresh rynx session and re-targets the mirror to it. */
-    onSessionRotated?(kind: "clear" | "fork", claudeSessionId: string, transcriptPath: string): void;
+     *  SessionStart reported a new session id + transcript. The old Response is
+     *  closed first; the forwarder re-points only after this publication barrier
+     *  resolves, so the host can mint a fresh rynx session and ACK mirror retarget. */
+    onSessionRotated?(kind: "clear" | "fork", claudeSessionId: string, transcriptPath: string, initialTranscriptOffset: number): void | Promise<void>;
 }
 export interface ClaudeLiveSessionOptions {
     /** The session's bridge dir (`hooks.jsonl` lives here). */
@@ -55,6 +94,10 @@ export interface ClaudeLiveSessionOptions {
      *  matching forwarder cursor exists, follow only records appended after the
      *  SessionStart discovery instead of mirroring native history a second time. */
     resumeAtEndOnDiscovery?: boolean;
+    /** Exact native-rotation boundary persisted by the host. It takes
+     * precedence over resumeAtEndOnDiscovery so a delayed restart cannot skip
+     * target records written after SessionStart. */
+    initialTranscriptOffsetOnDiscovery?: number;
     /** Poll interval (ms). The files are append-only, so polling is simplest. */
     pollMs?: number;
     /** Inactivity (ms) FALLBACK close for a turn whose Stop hook never fired. */
@@ -79,10 +122,28 @@ export declare class ClaudeLiveSession {
     private readonly leaseUpdatedAt;
     private started;
     private stopped;
+    private supervisorTask?;
+    private releaseSleep?;
     private hooksOffset;
+    private hookEventCursor;
+    /** Rotation publication is a checkpoint barrier. No source is polled under
+     * either logical Session until the daemon confirms the new binding. */
+    private rotationPending;
+    /** A non-rotation async hook (currently compaction completion) holds only the
+     * hook cursor and parent transcript. Native sub-agents, deltas, interactions,
+     * and live status continue to converge while its delivery retries. */
+    private compactionHookPending;
+    private pendingCompactionHook?;
     private interactionsOffset;
     private interactionAcksOffset;
     private transcriptOffset;
+    private committedTranscriptOffset;
+    private transcriptLineCursor;
+    private committedTranscriptLineCursor;
+    private transcriptDeliveryPending;
+    /** A transcript isCompactSummary boundary is currently in its durable lane.
+     * The completion-hook fallback must wait so the real summary remains primary. */
+    private transcriptCompactionPending;
     /** Secondary dedup: source ids (record uuids) already forwarded, so a re-read
      *  (fingerprint reset / mid-poll death) doesn't re-emit. Persisted in the
      *  forwarder state; bounded there. */
@@ -94,17 +155,40 @@ export declare class ClaudeLiveSession {
     /** Persisted native id requested through `claude --resume`. */
     private readonly expectedClaudeSessionId?;
     private readonly resumeAtEndOnDiscovery;
+    private readonly initialTranscriptOffsetOnDiscovery;
     /** Every claude session uuid seen — a resume into an UNSEEN id + a forkedFrom
      *  marker signals a `/fork` (vs. resuming a known branch). */
     private readonly seenClaudeSessionIds;
     private turnOpen;
     private currentTurnId?;
+    /** Input half of a split Claude `!cmd`, plus the turn id its later output
+     * must reuse. Kept across a terminal Stop edge like the current terminal
+     * response id. */
+    private activeTerminalCommand?;
+    /** Split-command state at the latest individually handled source boundary.
+     * Parsing may run ahead through later records, so durable state must not use
+     * the mutable live value until those later items are ACKed too. */
+    private committedTerminalCommand?;
+    /** The open turn received an explicit Escape/Stop and must close cancelled. */
+    private turnInterrupted;
     /** The Turn opened from a pre-transcript interaction. Its unique provisional
      * id keeps responses distinct until the real prompt uuid can be adopted. */
     private syntheticTurn;
     private lastActivityAt;
     /** When the Stop hook fired (null = not yet) — drives the grace-period close. */
     private stopPendingAt;
+    /** Authoritative live background-shell count from the pending Stop hook. */
+    private stopBackgroundTaskCount;
+    /** Whether the pending Stop count already rode an immediate idle edge. */
+    private stopBackgroundTaskCountDelivered;
+    /** An idle status from Claude's session metadata. The short delay keeps a
+     * final transcript record in the response without letting stale tool state
+     * override the provider's terminal status. */
+    private providerIdleAt;
+    private statusPoller?;
+    /** A failed hook is authoritative until the next running edge. Claude writes
+     * idle after failures too, so that trailing file update must not erase it. */
+    private providerFailureSticky;
     /** Open tool-call ids (start seen, end not yet) — suppresses the idle backstop. */
     private readonly openToolIds;
     /** Transcript-backed acknowledgements for web→TUI input. A direct idle
@@ -133,8 +217,17 @@ export declare class ClaudeLiveSession {
      *  append its request immediately before the failure hook lands; closing here
      *  would let the later interaction poll reopen an already-failed Turn. */
     private turnFailurePending;
-    /** Sub-agent (Task) ids already forwarded — a Task tool_result is processed once. */
-    private readonly seenSubagents;
+    /** Stop/StopFailure owns the hook cursor until its terminal status reaches a
+     * handled delivery outcome. This preserves replay on runner restart. */
+    private pendingTerminalHook?;
+    private terminalHookDelivery?;
+    private pendingTranscriptCompactions;
+    /** Claude Code native Task/Agent sidechains. Each child owns an independent
+     * cursor/retry lane so one unavailable delivery cannot block its siblings or
+     * the parent transcript. */
+    private readonly nativeSubagents;
+    private readonly nativeSubagentParentResponses;
+    private subagentStateParentPath?;
     /** The agent's task list, keyed by task id in creation order (claude
      *  `TaskCreate`/`TaskUpdate`). Emitted whole as a snapshot on any change. */
     private readonly todos;
@@ -142,6 +235,7 @@ export declare class ClaudeLiveSession {
      *  a turn's usage on close. undefined until the statusLine hook first fires. */
     private latestStatus?;
     private deltasOffset;
+    private readonly seenDeltaKeys;
     /** 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). */
@@ -179,22 +273,54 @@ export declare class ClaudeLiveSession {
     private consumeQueuedPromotion;
     start(): void;
     stop(): void;
+    /** Wait for the supervised polling task to retire. Terminal teardown starts
+     * synchronously in {@link stop}; callers use this bounded join before their
+     * runner process exits. */
+    waitForStop(timeoutMs?: number): Promise<void>;
     /** Phase two of runner shutdown. The caller must stop the Claude terminal
      * first so no hook can still be opening an atomically claimed answer. This is
      * synchronous because the runner process exits immediately afterwards. */
     finalizeStop(): void;
-    /** One poll cycle (hooks → transcript → idle backstop). Exposed for tests to
+    /** One poll cycle (rotation/PreCompact prescan → transcript → hooks → live
+     * lanes → idle backstop). Exposed for tests to
      *  drive deterministically; the async {@link loop} just calls it on an interval. */
     tick(): void;
+    /** Bind Claude's per-process session metadata after the terminal exists. */
+    attachStatusSource({ panePid, configDir, }: {
+        panePid: () => number | undefined;
+        configDir?: string;
+    }): void;
+    private supervise;
     private loop;
+    private sleepUntilWake;
+    /** Rotation is a control edge, not an ordinary hook-stream item. Scan past a
+     * held Stop/compaction cursor so an old retry can never strand the physical
+     * Claude process on a new Session while Rynx still targets the old one. */
+    private prescanSessionRotation;
+    /** Mint compaction tokens before transcript parsing without advancing the
+     * hook cursor. The ordinary hook pass later observes the same cursor-keyed
+     * edge and converges on the already-created token. */
+    private prescanPrecompactEdges;
     private pollHooks;
+    private isSessionRotationHook;
+    private isForkHookRecord;
+    private persistHookCursor;
     private handleHook;
+    private handleTodoHook;
+    private compactionGeneration;
+    private readCompactionState;
+    private notePrecompact;
+    private compactionPendingMatches;
+    private markCompactionPersisted;
+    private claimHookCompaction;
+    private handleCompactionCompletionHook;
     /** Process a provider failure only after this tick has discovered every
      *  blocking request already appended by its hook subprocess. */
     private flushTurnFailure;
     /** Emit the Stop idle signal only after this tick has discovered native
      *  interactions. A pending question/permission is active execution, not idle. */
     private flushStopSignal;
+    private finishTerminalHookDelivery;
     /** 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
@@ -204,7 +330,18 @@ export declare class ClaudeLiveSession {
      *  files — hooks/deltas/status — are shared by the same claude process across a
      *  rotation, so their cursors are NOT reset). */
     private repointTranscript;
+    /** Revalidate the committed cursor every poll, not only after process restart.
+     * Claude may replace/truncate a transcript in place. Treat a stale
+     * nonzero fingerprint as a new file and skips to its current EOF while
+     * preserving the bounded seen set. A temporarily missing file keeps the
+     * cursor unchanged. */
+    private validateLiveTranscriptCursor;
     private pollTranscript;
+    private rememberSourceId;
+    private restoreSubagentForwardStates;
+    private persistSubagentForwardStates;
+    private pollNativeSubagents;
+    private pollNativeSubagent;
     /** Tail blocking hook requests after transcript records, so an interaction
      *  emitted in the same poll attaches to the user Turn that caused it. */
     private pollInteractions;
@@ -238,15 +375,16 @@ export declare class ClaudeLiveSession {
     private scheduleClaimedInteractionScrubs;
     private settleCancelledInteraction;
     private rememberSettled;
+    /** State change represented by this record once its durable terminal item is
+     * handled. Parsing can run through multiple records before their deliveries
+     * settle, so this checkpoint is intentionally separate from the live state. */
+    private terminalCommandCheckpointForRecord;
     private handleRecord;
+    private emitUserMessageRecord;
+    private handleCompactSummary;
     /** Fold a `TaskCreate` (new pending task) or `TaskUpdate` (status/subject/delete)
      *  record into the task list; on any change emit the whole list as a snapshot. */
     private maybeUpdateTodos;
-    /** On a `Task` tool_result, replay the sub-agent's own transcript
-     *  (`subagents/agent-<agentId>.jsonl`) as events tagged with the parent Task
-     *  tool-use id, so the canonical layer nests them under that call. Fired once
-     *  per sub-agent (at tool_result time the file is complete — no live race). */
-    private maybeForwardSubagent;
     /** Tail streamed assistant-text chunks (MessageDisplay) into live `token`
      *  events. Guarded on an open turn — deltas belong to the turn the user record
      *  opened; the offset advances only once processed. */
@@ -255,6 +393,8 @@ export declare class ClaudeLiveSession {
     /** Refresh the latest statusLine context/cost snapshot (a last-writer-wins file
      *  the statusLine hook overwrites on every TUI render). */
     private pollStatus;
+    private pollSessionStatus;
+    private handleSessionStatus;
     /** A usage record from the latest statusLine snapshot (snake_case, the keys the
      *  normalizer's `turn_completed` + the web `readUsageTokens` read), or undefined
      *  if the statusLine hook has not fired yet. */
@@ -265,10 +405,12 @@ export declare class ClaudeLiveSession {
      *  text so a late MessageDisplay final can be reconciled backward. */
     private remapMessageItem;
     private trackTool;
+    private rememberNativeSubagentParentResponse;
     private ensureTurn;
-    /** Mirror a local `!` command as its own mini-turn: close any open turn, then
-     *  open→emit→close so it groups as one response with a stable id (the record
-     *  uuid) and never lingers "running" (input+output are complete in one record). */
+    /** Mirror a Claude `!cmd` as one logical mini-turn even when input and output
+     * are separate transcript records. The output repeats the remembered command
+     * in Rynx's combined terminal item shape; the transcript projection merges
+     * that completion into the preceding command row. */
     private emitTerminalCommand;
     /** The web Stop button interrupted this session (host sent Escape). claude
      *  records the interrupt in its own transcript but may not fire a Stop hook when
@@ -283,6 +425,10 @@ export declare class ClaudeLiveSession {
      *  sent an Escape — an Escape into idle claude submits an empty turn, which
      *  claude answers with a stray "No response requested." bubble. */
     isTurnOpen(): boolean;
+    /** Fail an open turn exactly once when its native terminal/runner disappears. */
+    failOpenTurn(error: Error): boolean;
+    /** Retire process-scoped metadata before classifying a terminal exit. */
+    noteTerminalExit(error: Error): boolean;
     private closeTurn;
     private closeTurnError;
     private resetMessageCorrelation;
@@ -292,6 +438,8 @@ export declare class ClaudeLiveSession {
  *  {@link import("../terminal/tmux.js").TmuxTerminal}). The runner-child hands
  *  this to the host after launching the pane, since the host doesn't own tmux. */
 export interface TerminalInjector {
+    /** PID of the process owning the tmux pane, when available. */
+    panePid?(): number | undefined;
     capturePane(): string;
     clearInputLine(): void;
     paste(text: string): void;
@@ -303,12 +451,16 @@ export interface InjectViaTerminalOptions {
     promptGlyph?: string;
     promptTimeoutMs?: number;
     settleMs?: number;
+    /** Wait for the pasted draft to become visible before the first Enter. */
+    pasteCommitMs?: number;
     /** Transcript-backed proof that Claude accepted this exact input. When
-     * absent, injection keeps the legacy one-Enter best-effort contract. */
+     * present it takes precedence over pane heuristics. */
     submissionObserved?: () => boolean;
-    /** Per-attempt wait for a transcript acknowledgement. */
+    /** Total post-Enter verification budget. */
     submitConfirmMs?: number;
-    /** Total Enter attempts when transcript confirmation is available. */
+    /** Minimum delay between Enter retries while the draft remains visible. */
+    submitRetryMs?: number;
+    /** Optional safety cap for tests/callers; the time budget remains authoritative. */
     maxSubmitAttempts?: number;
     pollMs?: number;
     now?: () => number;
@@ -324,8 +476,8 @@ export interface InjectViaTerminalOptions {
  *
  * 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. With a
- * transcript observer, Enter is retried only when Claude has durably recorded
- * neither a direct user prompt nor a type-ahead enqueue.
+ * caller reports, NOT a signal to fall through to a second output path. Enter
+ * is retried only while the exact draft remains visible and Claude has durably
+ * recorded neither a direct user prompt nor a type-ahead enqueue.
  */
 export declare function injectViaTerminal(injector: TerminalInjector, text: string, opts?: InjectViaTerminalOptions): Promise<boolean>;