@rynx-ai/runtime 0.1.11-beta.20 → 0.1.11-beta.21

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

@@ -1,5 +1,6 @@
 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 {
@@ -21,7 +22,9 @@ export interface ClaudeForwarderSink {
     /** 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
+    /** 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
@@ -105,6 +108,14 @@ export declare class ClaudeLiveSession {
     private lastActivityAt;
     /** When the Stop hook fired (null = not yet) — drives the grace-period close. */
     private stopPendingAt;
+    /** 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
@@ -186,6 +197,11 @@ export declare class ClaudeLiveSession {
     /** One poll cycle (hooks → transcript → 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 loop;
     private pollHooks;
     private handleHook;
@@ -255,6 +271,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. */
@@ -285,6 +303,8 @@ export declare class ClaudeLiveSession {
     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;
@@ -294,6 +314,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;

package/dist/claude/native-integration.js

@@ -5,11 +5,12 @@
  * the Claude Code TUI feeds through its hooks + transcript:
  *
  *  - `hooks.jsonl` (bridge) — `SessionStart` reveals the transcript path + claude
- *    session id (discovery); `Stop`/`StopFailure` CLOSE the turn (authoritative).
+ *    session id; `StopFailure` supplies the failure edge and `Stop` carries the
+ *    legacy fallback boundary.
  *  - 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 reference implementation re-audit; `running` is
- *    implicit between open and close, so no PTY watcher is needed.)
+ *    assistant/tool records become {@link AgentEvent}s.
+ *  - Claude's per-process session file — while readable, it is the source of
+ *    truth for running/idle and supersedes the hook/pane heuristics.
  *
  * The mapped events drive the SAME per-turn {@link SessionNormalizer} sink shape
  * the codex forwarder uses (see the host), so mirroring is identical downstream.
@@ -21,6 +22,7 @@ import { statSync } from "node:fs";
 import { parseTerminalCommand, parseTranscriptRecord, readSubagentEvents, subagentTranscriptPath, transcriptHasForkedFrom, } from "./transcript.js";
 import { jsonlCursorFingerprint, interactionLeaseUpdatedAt, readClaimedInteractionResult, readClaudeStatus, readForwardState, readInteractionAcksFrom, readHookEventsFrom, readInteractionRequestsFrom, readJsonlFrom, readMessageDeltasFrom, resetForwardState, removeClaimedInteractionResult, removeInteractionLease, removeInteractionResult, scrubClaudeInteractionArtifacts, writeInteractionResult, writeForwardState, } from "./native-bridge.js";
 import { boundInteractionRequest, redactInteractionResolution, validateInteractionResolution, } from "../interactions.js";
+import { ClaudeSessionStatusPoller, } from "./session-status.js";
 const MAX_SETTLED_INTERACTIONS = 512;
 const MAX_MESSAGE_CORRELATION_BACKLOG = 64;
 const MAX_SUBMISSION_OBSERVATIONS = 64;
@@ -169,6 +171,14 @@ export class ClaudeLiveSession {
     lastActivityAt = 0;
     /** When the Stop hook fired (null = not yet) — drives the grace-period close. */
     stopPendingAt = null;
+    /** 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. */
+    providerIdleAt = null;
+    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. */
+    providerFailureSticky = false;
     /** 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
@@ -328,6 +338,7 @@ export class ClaudeLiveSession {
         if (this.stopped)
             return;
         this.stopped = true;
+        this.statusPoller?.retire();
         // A hook may have appended its request just before shutdown but not yet
         // reached a scheduled poll. Drain it so the subprocess receives cancellation
         // instead of remaining blocked until Claude's one-day hook timeout.
@@ -365,9 +376,20 @@ export class ClaudeLiveSession {
         this.pollAbandonedInteractions();
         this.flushTurnFailure();
         this.pollStatus();
+        this.pollSessionStatus();
         this.flushStopSignal();
         this.maybeIdleClose();
     }
+    /** Bind Claude's per-process session metadata after the terminal exists. */
+    attachStatusSource({ panePid, configDir, }) {
+        this.statusPoller?.retire();
+        this.statusPoller = new ClaudeSessionStatusPoller({
+            panePid,
+            sessionId: () => this.currentClaudeSessionId,
+            onStatus: (status) => this.handleSessionStatus(status),
+            ...(configDir ? { configDir } : {}),
+        });
+    }
     async loop() {
         while (!this.stopped) {
             try {
@@ -423,6 +445,7 @@ export class ClaudeLiveSession {
         if (!error)
             return;
         this.turnFailurePending = null;
+        this.providerFailureSticky = true;
         this.closeTurnError(error);
     }
     /** Emit the Stop idle signal only after this tick has discovered native
@@ -431,6 +454,8 @@ export class ClaudeLiveSession {
         if (!this.stopSignalPending)
             return;
         this.stopSignalPending = false;
+        if (this.statusPoller?.active)
+            return;
         if (this.pendingInteractions.size === 0)
             this.sink.onIdle();
     }
@@ -866,6 +891,7 @@ export class ClaudeLiveSession {
                     this.currentTurnId = turnId;
                     this.turnOpen = true;
                     this.syntheticTurn = false;
+                    this.providerIdleAt = null;
                     this.openToolIds.clear();
                     this.stopPendingAt = null;
                     this.sink.onTurnStart(this.currentTurnId);
@@ -987,6 +1013,27 @@ export class ClaudeLiveSession {
         if (status)
             this.latestStatus = status;
     }
+    pollSessionStatus() {
+        const poller = this.statusPoller;
+        if (!poller)
+            return;
+        const wasActive = poller.active;
+        poller.tick();
+        if (wasActive && !poller.active)
+            this.providerIdleAt = null;
+    }
+    handleSessionStatus(status) {
+        this.stopSignalPending = false;
+        this.stopPendingAt = null;
+        if (status.runnerStatus === "running") {
+            this.providerFailureSticky = false;
+        }
+        else if (this.providerFailureSticky) {
+            return;
+        }
+        this.sink.onStatus?.(status.runnerStatus, status.blockedOn);
+        this.providerIdleAt = status.runnerStatus === "idle" ? this.now() : null;
+    }
     /** 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. */
@@ -1051,6 +1098,7 @@ export class ClaudeLiveSession {
             this.currentTurnId = provisionalTurnId;
             this.syntheticTurn = true;
         }
+        this.providerIdleAt = null;
         this.turnOpen = true;
         this.sink.onTurnStart(this.currentTurnId);
     }
@@ -1076,6 +1124,8 @@ export class ClaudeLiveSession {
             return;
         this.cancelPendingInteractions("turn_interrupted");
         this.stopSignalPending = false;
+        if (this.statusPoller?.active)
+            return;
         this.sink.onIdle();
         this.stopPendingAt = this.now();
     }
@@ -1093,6 +1143,11 @@ export class ClaudeLiveSession {
         this.closeTurnError(error);
         return true;
     }
+    /** Retire process-scoped metadata before classifying a terminal exit. */
+    noteTerminalExit(error) {
+        this.statusPoller?.retire();
+        return this.failOpenTurn(error);
+    }
     closeTurn() {
         if (!this.turnOpen)
             return;
@@ -1128,6 +1183,14 @@ export class ClaudeLiveSession {
         this.streamedMessageText.clear();
     }
     maybeIdleClose() {
+        if (this.statusPoller?.active) {
+            if (this.turnOpen &&
+                this.providerIdleAt !== null &&
+                this.now() - this.providerIdleAt >= this.stopGraceMs) {
+                this.closeTurn();
+            }
+            return;
+        }
         if (!this.turnOpen ||
             this.openToolIds.size > 0 ||
             this.pendingInteractions.size > 0)
@@ -1151,7 +1214,7 @@ const CLAUDE_PROMPT_SCAN_TAIL_LINES = 5;
 const CLAUDE_BOX_RULE_CHARS = new Set([..."─━╭╮╰╯│┃╌╍"]);
 const CLAUDE_PASTED_PLACEHOLDER_PREFIX = "[Pasted text";
 const CLAUDE_DRAFT_NEEDLE_MAX_CHARS = 24;
-/** Omnigent's Claude-native readiness window: tmux may exist well before the
+/** Claude-native readiness window: tmux may exist well before the
  * first interactive composer mounts on a cold start. */
 const CLAUDE_PROMPT_READY_TIMEOUT_MS = 30_000;
 const CLAUDE_PASTE_COMMIT_TIMEOUT_MS = 5_000;
@@ -1300,7 +1363,7 @@ export async function injectViaTerminal(injector, text, opts = {}) {
     let attempts = 1;
     const maxAttempts = Math.max(1, Math.floor(opts.maxSubmitAttempts ?? Number.MAX_SAFE_INTEGER));
     injector.sendEnter();
-    // Omnigent preserves the old blind-submit fallback when capture-pane cannot
+    // Preserve the old blind-submit fallback when capture-pane cannot
     // identify the draft; its absence would otherwise "prove" success trivially.
     if (!draftSeen)
         return true;

package/dist/claude/session-status.d.ts

@@ -0,0 +1,39 @@
+export type ClaudeRunnerStatus = "running" | "idle";
+export interface ClaudeSessionStatus {
+    runnerStatus: ClaudeRunnerStatus;
+    rawStatus: string;
+    statusUpdatedAt?: number;
+    blockedOn?: string;
+}
+export declare function claudeSessionsDir(configDir?: string): string;
+export declare function resolveClaudeSessionStatusFile({ panePid, expectedSessionId, configDir, now, }: {
+    panePid?: number;
+    expectedSessionId?: string;
+    configDir?: string;
+    now?: number;
+}): string | undefined;
+export declare function readClaudeSessionStatus(path: string): ClaudeSessionStatus | undefined;
+export declare class ClaudeSessionStatusPoller {
+    private readonly options;
+    private path?;
+    private attempts;
+    private exhausted;
+    private lastMtime?;
+    private lastEdge?;
+    private lastStatus?;
+    constructor(options: {
+        onStatus: (status: ClaudeSessionStatus) => void;
+        panePid: () => number | undefined;
+        sessionId: () => string | undefined;
+        configDir?: string;
+        maxResolveAttempts?: number;
+        now?: () => number;
+    });
+    get active(): boolean;
+    get status(): ClaudeSessionStatus | undefined;
+    tick(): void;
+    retire(): void;
+    resync(): void;
+    private tryResolve;
+    private readAndPublish;
+}

package/dist/claude/session-status.js

@@ -0,0 +1,163 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const STATUS_TO_RUNNER = {
+    busy: "running",
+    waiting: "running",
+    idle: "idle",
+    shell: "idle",
+    running: "running",
+    completed: "idle",
+    failed: "idle",
+    error: "idle",
+    done: "idle",
+};
+const SCAN_FRESHNESS_MS = 120_000;
+const DEFAULT_MAX_RESOLVE_ATTEMPTS = 40;
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function readJsonRecord(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function matchesSession(record, expectedSessionId) {
+    if (record.kind !== "interactive")
+        return false;
+    return expectedSessionId === undefined || record.sessionId === expectedSessionId;
+}
+export function claudeSessionsDir(configDir = process.env.CLAUDE_CONFIG_DIR?.trim() || join(homedir(), ".claude")) {
+    return join(configDir, "sessions");
+}
+export function resolveClaudeSessionStatusFile({ panePid, expectedSessionId, configDir, now = Date.now(), }) {
+    const directory = claudeSessionsDir(configDir);
+    if (panePid !== undefined) {
+        const candidate = join(directory, `${panePid}.json`);
+        const record = readJsonRecord(candidate);
+        if (record && matchesSession(record, expectedSessionId))
+            return candidate;
+    }
+    if (!expectedSessionId)
+        return undefined;
+    try {
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            if (!entry.isFile() || !entry.name.endsWith(".json"))
+                continue;
+            const candidate = join(directory, entry.name);
+            let modifiedAt;
+            try {
+                modifiedAt = statSync(candidate).mtimeMs;
+            }
+            catch {
+                continue;
+            }
+            if (now - modifiedAt > SCAN_FRESHNESS_MS)
+                continue;
+            const record = readJsonRecord(candidate);
+            if (record && matchesSession(record, expectedSessionId))
+                return candidate;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+export function readClaudeSessionStatus(path) {
+    const record = readJsonRecord(path);
+    if (!record || typeof record.status !== "string")
+        return undefined;
+    const runnerStatus = STATUS_TO_RUNNER[record.status];
+    if (!runnerStatus)
+        return undefined;
+    const updatedAt = record.statusUpdatedAt;
+    const waitingFor = record.status === "waiting" ? record.waitingFor : undefined;
+    return {
+        runnerStatus,
+        rawStatus: record.status,
+        ...(Number.isSafeInteger(updatedAt) ? { statusUpdatedAt: updatedAt } : {}),
+        ...(typeof waitingFor === "string" && waitingFor ? { blockedOn: waitingFor } : {}),
+    };
+}
+export class ClaudeSessionStatusPoller {
+    options;
+    path;
+    attempts = 0;
+    exhausted = false;
+    lastMtime;
+    lastEdge;
+    lastStatus;
+    constructor(options) {
+        this.options = options;
+    }
+    get active() {
+        return this.path !== undefined && !this.exhausted;
+    }
+    get status() {
+        return this.lastStatus;
+    }
+    tick() {
+        if (this.exhausted)
+            return;
+        if (!this.path) {
+            this.tryResolve();
+            if (!this.path)
+                return;
+        }
+        this.readAndPublish();
+    }
+    retire() {
+        this.exhausted = true;
+    }
+    resync() {
+        if (!this.active)
+            return;
+        this.lastMtime = undefined;
+        this.lastEdge = undefined;
+    }
+    tryResolve() {
+        this.attempts += 1;
+        this.path = resolveClaudeSessionStatusFile({
+            panePid: this.options.panePid(),
+            expectedSessionId: this.options.sessionId(),
+            ...(this.options.configDir ? { configDir: this.options.configDir } : {}),
+            now: this.options.now?.() ?? Date.now(),
+        });
+        if (!this.path &&
+            this.attempts >= (this.options.maxResolveAttempts ?? DEFAULT_MAX_RESOLVE_ATTEMPTS)) {
+            this.exhausted = true;
+        }
+    }
+    readAndPublish() {
+        if (!this.path)
+            return;
+        let mtime;
+        try {
+            mtime = statSync(this.path).mtimeMs;
+        }
+        catch {
+            this.exhausted = true;
+            return;
+        }
+        if (this.lastMtime === mtime)
+            return;
+        this.lastMtime = mtime;
+        const status = readClaudeSessionStatus(this.path);
+        if (!status) {
+            this.lastStatus = undefined;
+            this.lastEdge = undefined;
+            return;
+        }
+        this.lastStatus = status;
+        const edge = `${status.runnerStatus}\0${status.blockedOn ?? ""}`;
+        if (edge === this.lastEdge)
+            return;
+        this.lastEdge = edge;
+        this.options.onStatus(status);
+    }
+}

package/dist/codex-app-server/forwarder.d.ts

@@ -29,13 +29,19 @@ export interface CodexForwarderSink {
     /** A turn began. `turnId` is codex's turn id, used to derive a stable
      *  `responseId`. Start a fresh normalizer/response. */
     onTurnStart(turnId?: string): void;
+    /** The observer received the provider's authoritative `turn/started` edge.
+     * Unlike `onTurnStart`, this is not fired early by turn/start acceptance. */
+    onTurnObserved?(turnId?: string): void;
     /** One mapped event within the current turn. */
     onEvent(event: AgentEvent): void;
     /** Provider startup is session status, not a model item. Hosts that already
      * published the response can forward it without synthesizing another start. */
     onStatus?(note: string | undefined, statusKind?: "startup"): void;
     /** The current turn finished; `usage` is the runtime's raw snapshot if any. */
-    onTurnEnd(usage?: Record<string, unknown>): void;
+    onTurnEnd(usage?: Record<string, unknown>, reason?: "superseded"): void;
+    /** Resume proved that the newest turn is terminal even though its live edge
+     * was missed. This updates session state without replaying historical items. */
+    onRecoveredTurnStatus?(status: "idle" | "failed", turnId: string | undefined, error?: Error): void;
     /** A turn failed on the runtime. */
     onTurnError(error: Error): void;
     /** The user's turn text (sourced from codex's `userMessage` item), so a
@@ -76,6 +82,9 @@ export declare class CodexSessionForwarder {
     private currentThreadIdValue;
     private activeSignaled;
     private completionTimer;
+    /** Turn id retained only for late-item dedup while a terminal response waits
+     * for its bounded output-ordering grace. It is not an active provider turn. */
+    private pendingCompletionTurnId;
     private assistantMessageTimer;
     private deferredAssistantMessage;
     private pendingCompletion;
@@ -94,7 +103,8 @@ export declare class CodexSessionForwarder {
     /** Begin mirroring. Idempotent. */
     start(): void;
     stop(): void;
-    /** True while a turn is open — injection uses `turn/steer` then, else `turn/start`. */
+    /** True while the provider owns an active turn, including the short interval
+     * between injection acceptance and observer confirmation. */
     isTurnOpen(): boolean;
     /** The current turn's codex id (only meaningful while {@link isTurnOpen}). */
     currentTurnId(): string | null;
@@ -112,6 +122,10 @@ export declare class CodexSessionForwarder {
     mcpStartupDetail(): string | null;
     /** The bound codex thread id captured from `thread/started` (null until then). */
     threadId(): string | null;
+    /** Seed an already-persisted/resumed thread binding. The bridge retains this
+     * state even when app-server does not rebroadcast `thread/started`, so
+     * terminal-boundary recovery must know it too. */
+    noteThreadBound(threadId: string): void;
     /**
      * Replay the backlog turns from a `thread/resume` response as if they were live
      * `item/completed` notifications — the fresh-thread first-turn backfill. Each
@@ -123,6 +137,10 @@ export declare class CodexSessionForwarder {
     /** Reconcile only the exact active turn after an observer resume. Historical
      * items are intentionally not replayed on an existing-thread reconnect. */
     reconcileActiveTurn(turn: ResumedTurn | undefined): boolean;
+    /** Reconcile an observer reconnect from the explicit resume snapshot. An
+     * identified active turn must match exactly; with no active turn, only the
+     * newest explicit terminal status is published and no history is replayed. */
+    reconcileResumeTurns(turns: ResumedTurn[]): boolean;
     /** Fail an open response exactly once when its observer or terminal exits. */
     failOpenTurn(error: Error): boolean;
     private handle;
@@ -151,4 +169,17 @@ export declare class CodexSessionForwarder {
     private completedItemKey;
     private advanceAnonCounter;
     private ensureTurn;
+    /** Start (or confirm) the app-server's authoritative active turn. A newer
+     * start supersedes an older response whose terminal edge arrived late; a
+     * pending Traex completion is flushed first so its final item grace remains
+     * intact. */
+    private beginTurn;
+    /** Active-turn clearing contract:
+     *
+     * - an identified active turn is closed only by the same id;
+     * - an id-less boundary cannot close an identified active turn;
+     * - with no observed active turn, an identified boundary may recover a
+     *   missed start only when it carries the currently-bound thread id. */
+    private terminalBoundaryMatchesActiveTurn;
+    private notificationMatchesCurrentThread;
 }