botmux 2.9.0 → 2.9.2

package/dist/services/bridge-rotation-policy.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Pure rotation-policy gate for the Claude bridge watcher.
+ *
+ * Lives outside `worker.ts` so tests can import without dragging worker-level
+ * fs / IPC side-effects.
+ */
+export type PidFollowResult = 'unavailable' | 'same' | 'switched';
+/**
+ * Decide whether `bridgeIngest` should fall through to the directory-mtime
+ * `maybeFollowQuietRotation` heuristic this tick.
+ *
+ * Inputs:
+ *   - `pidFollow`: result of the authoritative pid-state probe
+ *     (`maybeFollowSessionRotationViaPid`). `'switched'` means it already
+ *     moved us; `'same'` means the pid file's `sessionId` matches our
+ *     current path; `'unavailable'` means the pid file was unreadable
+ *     (non-Linux, no `~/.claude/sessions/<pid>.json`, validation failure).
+ *   - `switched`: whether ANY earlier rotation step (pid resolver OR
+ *     fingerprint fallback) already moved the watcher this tick.
+ *
+ * Returns true only when there was no earlier switch AND the pid resolver
+ * gave no opinion.
+ *
+ * Trade-off: pid resolver `'same'` is NOT proof that no rotation happened
+ * — Claude Code 2.1.123 writes `sessionId` ONCE at process start and the
+ * in-pane `/clear` path does not refresh it. We still skip the mtime
+ * heuristic on `'same'` because the alternative is sibling-pane hijack:
+ * any other Claude pane in the same cwd gets a busier jsonl and the
+ * heuristic picks it. The cost is that a pure-local `/clear` with no
+ * pending Lark turn won't auto-follow until the user sends a Lark
+ * message (which arms fingerprint fallback). The Lark-message path is
+ * the dominant /clear recovery flow in practice; sibling-pane
+ * corruption would silently break every multi-pane adopt setup.
+ *
+ * `--resume` is a fresh spawn and rewrites the pid file's sessionId, so
+ * it surfaces here as `'switched'`, not `'same'` — it's not affected by
+ * this gate.
+ */
+export declare function shouldRunQuietRotation(pidFollow: PidFollowResult, switched: boolean): boolean;
+export interface PidResolverPullbackInput {
+    /** sessionId reported by the pid file this tick. */
+    resolvedCliSessionId: string;
+    /** The pid file's full jsonl path (derived from sessionId + cwd). */
+    resolvedPath: string;
+    /** Current bridge jsonl path. */
+    currentBridgeJsonlPath: string | undefined;
+    /** Sid recorded as "stale" by the fingerprint fallback the last time it
+     *  accepted a candidate the pid file disagreed about. Undefined when no
+     *  fingerprint accept has overridden the pid file. */
+    stalePidStateSessionId: string | undefined;
+}
+export interface PidResolverPullbackDecision {
+    /** True ⇒ pid resolver should report 'same' rather than rotate the
+     *  watcher back to `resolvedPath`. */
+    suppress: boolean;
+    /** True ⇒ caller should clear `stalePidStateSessionId`: a fresh sid
+     *  (different from the stale one) appeared in the pid file, meaning a
+     *  real rotation has happened (`--resume` / fresh spawn) and the prior
+     *  fingerprint accept is no longer relevant. */
+    clearStale: boolean;
+}
+/**
+ * Decide whether the pid resolver should pull the watcher back to a path
+ * that disagrees with the current bridgeJsonlPath, given the worker's
+ * staleness bookkeeping.
+ *
+ * Rules:
+ * - No `stalePidStateSessionId` recorded ⇒ honour pid resolver as before.
+ * - Recorded sid matches pid file's current sid ⇒ suppress: this is the
+ *   spawn-time sid that fingerprint fallback already overrode for an
+ *   in-pane /clear that pid file can't see.
+ * - Recorded sid differs from pid file's current sid ⇒ a NEW rotation has
+ *   happened (`--resume` / fresh spawn / Claude restart with new pid file
+ *   contents). Clear the stale flag and let pid resolver switch normally.
+ */
+export declare function evaluatePidResolverPullback(input: PidResolverPullbackInput): PidResolverPullbackDecision;
+/** UUID-shaped Claude jsonl filename (sessionId.jsonl). Duplicated from
+ *  `src/adapters/cli/claude-code.ts:SESSION_UUID_RE` to keep this module
+ *  free of adapter imports. Keep the two patterns in sync; both gate
+ *  trust-set membership and fingerprint-fallback candidate eligibility. */
+export declare const SESSION_ID_FILENAME_RE: RegExp;
+/** Extract the sessionId portion of a `<sid>.jsonl` path (basename minus
+ *  the `.jsonl` extension). Returns the empty string when the path lacks
+ *  the expected suffix; callers should treat that as "untrusted". */
+export declare function sessionIdFromJsonlPath(path: string): string;
+export interface FingerprintSwitchInput {
+    /** Substring fingerprint to feed Phase 1's scanner. Required. */
+    contentFingerprint: string;
+    /** Full normalised content of the Lark turn. Phase 2 (unknown-sid
+     *  exact-content recovery) is skipped when this is missing or empty —
+     *  short content can't anchor a recovery without ambiguity. */
+    contentNormalized?: string;
+    /** Trust set populated from initial attach, pid resolver hits, fd probes. */
+    knownSessionIds: ReadonlySet<string>;
+    /** Phase 1 scanner: substring fingerprint search. Caller wires it to
+     *  `findJsonlContainingFingerprint`; this helper only sees the result. */
+    findSubstring: (acceptCandidate: (path: string) => boolean) => string | null;
+    /** Phase 2 scanner: exact-content search returning ALL matches in
+     *  mtime-descending order. Caller wires it to
+     *  `findJsonlsContainingExactContent`. */
+    findExact: (acceptCandidate: (path: string) => boolean) => string[];
+}
+export type FingerprintSwitchDecision = {
+    action: 'switch';
+    path: string;
+    reason: 'known-sid-substring' | 'unknown-sid-exact';
+} | {
+    action: 'abstain';
+    reason: 'multiple-unknown-exact';
+    candidates: string[];
+} | {
+    action: 'no-match';
+};
+/**
+ * Two-phase candidate selection for the bridge fingerprint fallback.
+ *
+ * Phase 1 (known-sid substring): the cheap path. Run the substring
+ * fingerprint scanner with an acceptCandidate predicate that requires
+ * `(UUID-shaped sid) AND (sid in knownSessionIds)`. Sibling panes are
+ * UUID-shaped but not in our trust set — their fingerprint hits are
+ * rejected. UUID gate also blocks accidental non-Claude jsonls.
+ *
+ * Phase 2 (unknown-sid exact-content recovery): only runs when
+ * `contentNormalized` is non-empty. Fires when Phase 1 found no match,
+ * which is the worst-case in-pane `/clear` scenario where the new sid
+ * never reaches our trust set (pid file lags, fd probe missed the open
+ * window). Run the exact-content scanner with predicate
+ * `(UUID-shaped sid) AND (sid NOT in knownSessionIds)`. Decision:
+ *   - 0 matches → no-match
+ *   - 1 match  → switch (the post-/clear file we couldn't otherwise see)
+ *   - ≥2 matches → abstain; multiple untrusted files normalise to the
+ *     same Lark content, so we cannot pick one without further evidence.
+ *     Caller is expected to log and surface a diagnostic.
+ *
+ * Pure: never touches fs / IPC / module state. Tests inject fakes for
+ * `findSubstring` and `findExact` to exercise every branch.
+ */
+export declare function decideFingerprintSwitch(input: FingerprintSwitchInput): FingerprintSwitchDecision;
+//# sourceMappingURL=bridge-rotation-policy.d.ts.map

package/dist/services/bridge-rotation-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-rotation-policy.d.ts","sourceRoot":"","sources":["../../src/services/bridge-rotation-policy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,MAAM,GAAG,UAAU,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,eAAe,EAC1B,QAAQ,EAAE,OAAO,GAChB,OAAO,CAGT;AAID,MAAM,WAAW,wBAAwB;IACvC,oDAAoD;IACpD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,qEAAqE;IACrE,YAAY,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,sBAAsB,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C;;0DAEsD;IACtD,sBAAsB,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5C;AAED,MAAM,WAAW,2BAA2B;IAC1C;0CACsC;IACtC,QAAQ,EAAE,OAAO,CAAC;IAClB;;;oDAGgD;IAChD,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,wBAAwB,GAC9B,2BAA2B,CAQ7B;AAID;;;2EAG2E;AAC3E,eAAO,MAAM,sBAAsB,QAAoE,CAAC;AAExG;;qEAEqE;AACrE,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG3D;AAED,MAAM,WAAW,sBAAsB;IACrC,iEAAiE;IACjE,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;mEAE+D;IAC/D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,eAAe,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACrC;8EAC0E;IAC1E,aAAa,EAAE,CAAC,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,KAAK,MAAM,GAAG,IAAI,CAAC;IAC7E;;8CAE0C;IAC1C,SAAS,EAAE,CAAC,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,KAAK,MAAM,EAAE,CAAC;CACrE;AAED,MAAM,MAAM,yBAAyB,GACjC;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,qBAAqB,GAAG,mBAAmB,CAAA;CAAE,GACvF;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,wBAAwB,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,GAC7E;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,sBAAsB,GAC5B,yBAAyB,CAoB3B"}

package/dist/services/bridge-rotation-policy.js

@@ -0,0 +1,125 @@
+/**
+ * Pure rotation-policy gate for the Claude bridge watcher.
+ *
+ * Lives outside `worker.ts` so tests can import without dragging worker-level
+ * fs / IPC side-effects.
+ */
+/**
+ * Decide whether `bridgeIngest` should fall through to the directory-mtime
+ * `maybeFollowQuietRotation` heuristic this tick.
+ *
+ * Inputs:
+ *   - `pidFollow`: result of the authoritative pid-state probe
+ *     (`maybeFollowSessionRotationViaPid`). `'switched'` means it already
+ *     moved us; `'same'` means the pid file's `sessionId` matches our
+ *     current path; `'unavailable'` means the pid file was unreadable
+ *     (non-Linux, no `~/.claude/sessions/<pid>.json`, validation failure).
+ *   - `switched`: whether ANY earlier rotation step (pid resolver OR
+ *     fingerprint fallback) already moved the watcher this tick.
+ *
+ * Returns true only when there was no earlier switch AND the pid resolver
+ * gave no opinion.
+ *
+ * Trade-off: pid resolver `'same'` is NOT proof that no rotation happened
+ * — Claude Code 2.1.123 writes `sessionId` ONCE at process start and the
+ * in-pane `/clear` path does not refresh it. We still skip the mtime
+ * heuristic on `'same'` because the alternative is sibling-pane hijack:
+ * any other Claude pane in the same cwd gets a busier jsonl and the
+ * heuristic picks it. The cost is that a pure-local `/clear` with no
+ * pending Lark turn won't auto-follow until the user sends a Lark
+ * message (which arms fingerprint fallback). The Lark-message path is
+ * the dominant /clear recovery flow in practice; sibling-pane
+ * corruption would silently break every multi-pane adopt setup.
+ *
+ * `--resume` is a fresh spawn and rewrites the pid file's sessionId, so
+ * it surfaces here as `'switched'`, not `'same'` — it's not affected by
+ * this gate.
+ */
+export function shouldRunQuietRotation(pidFollow, switched) {
+    if (switched)
+        return false;
+    return pidFollow === 'unavailable';
+}
+/**
+ * Decide whether the pid resolver should pull the watcher back to a path
+ * that disagrees with the current bridgeJsonlPath, given the worker's
+ * staleness bookkeeping.
+ *
+ * Rules:
+ * - No `stalePidStateSessionId` recorded ⇒ honour pid resolver as before.
+ * - Recorded sid matches pid file's current sid ⇒ suppress: this is the
+ *   spawn-time sid that fingerprint fallback already overrode for an
+ *   in-pane /clear that pid file can't see.
+ * - Recorded sid differs from pid file's current sid ⇒ a NEW rotation has
+ *   happened (`--resume` / fresh spawn / Claude restart with new pid file
+ *   contents). Clear the stale flag and let pid resolver switch normally.
+ */
+export function evaluatePidResolverPullback(input) {
+    if (input.stalePidStateSessionId === undefined) {
+        return { suppress: false, clearStale: false };
+    }
+    if (input.resolvedCliSessionId === input.stalePidStateSessionId) {
+        return { suppress: true, clearStale: false };
+    }
+    return { suppress: false, clearStale: true };
+}
+// ─── Two-phase fingerprint-fallback decision ───────────────────────────────
+/** UUID-shaped Claude jsonl filename (sessionId.jsonl). Duplicated from
+ *  `src/adapters/cli/claude-code.ts:SESSION_UUID_RE` to keep this module
+ *  free of adapter imports. Keep the two patterns in sync; both gate
+ *  trust-set membership and fingerprint-fallback candidate eligibility. */
+export const SESSION_ID_FILENAME_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Extract the sessionId portion of a `<sid>.jsonl` path (basename minus
+ *  the `.jsonl` extension). Returns the empty string when the path lacks
+ *  the expected suffix; callers should treat that as "untrusted". */
+export function sessionIdFromJsonlPath(path) {
+    const base = path.split('/').pop() ?? '';
+    return base.endsWith('.jsonl') ? base.slice(0, -'.jsonl'.length) : '';
+}
+/**
+ * Two-phase candidate selection for the bridge fingerprint fallback.
+ *
+ * Phase 1 (known-sid substring): the cheap path. Run the substring
+ * fingerprint scanner with an acceptCandidate predicate that requires
+ * `(UUID-shaped sid) AND (sid in knownSessionIds)`. Sibling panes are
+ * UUID-shaped but not in our trust set — their fingerprint hits are
+ * rejected. UUID gate also blocks accidental non-Claude jsonls.
+ *
+ * Phase 2 (unknown-sid exact-content recovery): only runs when
+ * `contentNormalized` is non-empty. Fires when Phase 1 found no match,
+ * which is the worst-case in-pane `/clear` scenario where the new sid
+ * never reaches our trust set (pid file lags, fd probe missed the open
+ * window). Run the exact-content scanner with predicate
+ * `(UUID-shaped sid) AND (sid NOT in knownSessionIds)`. Decision:
+ *   - 0 matches → no-match
+ *   - 1 match  → switch (the post-/clear file we couldn't otherwise see)
+ *   - ≥2 matches → abstain; multiple untrusted files normalise to the
+ *     same Lark content, so we cannot pick one without further evidence.
+ *     Caller is expected to log and surface a diagnostic.
+ *
+ * Pure: never touches fs / IPC / module state. Tests inject fakes for
+ * `findSubstring` and `findExact` to exercise every branch.
+ */
+export function decideFingerprintSwitch(input) {
+    const matchedKnown = input.findSubstring((path) => {
+        const sid = sessionIdFromJsonlPath(path);
+        return SESSION_ID_FILENAME_RE.test(sid) && input.knownSessionIds.has(sid);
+    });
+    if (matchedKnown) {
+        return { action: 'switch', path: matchedKnown, reason: 'known-sid-substring' };
+    }
+    if (!input.contentNormalized || input.contentNormalized.length === 0) {
+        return { action: 'no-match' };
+    }
+    const exact = input.findExact((path) => {
+        const sid = sessionIdFromJsonlPath(path);
+        return SESSION_ID_FILENAME_RE.test(sid) && !input.knownSessionIds.has(sid);
+    });
+    if (exact.length === 0)
+        return { action: 'no-match' };
+    if (exact.length > 1) {
+        return { action: 'abstain', reason: 'multiple-unknown-exact', candidates: exact };
+    }
+    return { action: 'switch', path: exact[0], reason: 'unknown-sid-exact' };
+}
+//# sourceMappingURL=bridge-rotation-policy.js.map

package/dist/services/bridge-rotation-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-rotation-policy.js","sourceRoot":"","sources":["../../src/services/bridge-rotation-policy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,sBAAsB,CACpC,SAA0B,EAC1B,QAAiB;IAEjB,IAAI,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC3B,OAAO,SAAS,KAAK,aAAa,CAAC;AACrC,CAAC;AA4BD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,2BAA2B,CACzC,KAA+B;IAE/B,IAAI,KAAK,CAAC,sBAAsB,KAAK,SAAS,EAAE,CAAC;QAC/C,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IAChD,CAAC;IACD,IAAI,KAAK,CAAC,oBAAoB,KAAK,KAAK,CAAC,sBAAsB,EAAE,CAAC;QAChE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IAC/C,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;AAC/C,CAAC;AAED,8EAA8E;AAE9E;;;2EAG2E;AAC3E,MAAM,CAAC,MAAM,sBAAsB,GAAG,iEAAiE,CAAC;AAExG;;qEAEqE;AACrE,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;IACzC,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACxE,CAAC;AAyBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAA6B;IAE7B,MAAM,YAAY,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC,IAAI,EAAE,EAAE;QAChD,MAAM,GAAG,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;QACzC,OAAO,sBAAsB,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5E,CAAC,CAAC,CAAC;IACH,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC;IACjF,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,iBAAiB,IAAI,KAAK,CAAC,iBAAiB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAChC,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE;QACrC,MAAM,GAAG,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;QACzC,OAAO,sBAAsB,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7E,CAAC,CAAC,CAAC;IACH,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IACtD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,wBAAwB,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IACpF,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;AAC3E,CAAC"}

package/dist/services/bridge-turn-queue.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Adopt-bridge turn attribution state machine.
+ *
+ * Pure (no fs / IPC / timers) so the worker can wrap it with watchers and
+ * tests can drive it deterministically. The worker feeds it transcript
+ * events (already drained from JSONL) and Lark-message markers; this class
+ * decides which assistant uuids belong to which Lark turn.
+ *
+ * Attribution rule:
+ *   - mark()           — pushes a new pending turn entry (state: not started)
+ *   - ingest(events)   — for each new user/assistant event:
+ *       * user event → the earliest unstarted pending turn whose fingerprint
+ *         matches becomes 'started' (its assistantUuids will collect from
+ *         now on). A user event that does NOT match any pending fingerprint
+ *         (or arrives with no pending Lark turn at all) is treated as
+ *         **local terminal input**: a synthetic local turn is created on
+ *         the spot, started immediately, and inserted ahead of any
+ *         still-unstarted Lark turns so emit ordering reflects when the
+ *         user event actually landed in the transcript. The local turn is
+ *         emitted with `isLocal: true` so the worker can format it with a
+ *         "user typed in the terminal" marker for the Lark thread.
+ *       * assistant text event (non-sidechain) → appended to the
+ *         currently-collecting turn (Lark or local), if any.
+ *   - drainEmittable() — pops any leading turn that has been started AND has
+ *     accumulated at least one visible assistant-text uuid. Started turns with no text
+ *     yet (Claude is mid-tool-use) stay queued for the next idle.
+ *
+ * Baseline (`absorb()`) takes a batch of historical events and registers
+ * their uuids as already-seen so future ingest doesn't double-attribute.
+ */
+import { normaliseForFingerprint, type TranscriptEvent } from './claude-transcript.js';
+export { normaliseForFingerprint };
+export interface BridgePendingTurn {
+    turnId: string;
+    started: boolean;
+    assistantUuids: string[];
+    /** Set when this turn was synthesised from a local-terminal user event
+     *  (no matching Lark fingerprint). Causes the worker emit path to format
+     *  the Lark message with both user text and assistant text under a
+     *  "🖥️ 终端本地对话" header — otherwise the user would see an orphan
+     *  reply with no prompt for context. Lark-driven turns keep this unset. */
+    isLocal?: boolean;
+    /** Transcript uuid of the user event that started this turn. Stored for
+     *  local turns so emit can fetch the user-typed content from the source
+     *  jsonl alongside the assistant uuids. Lark turns don't need it because
+     *  the user content is already known on the daemon side. */
+    userUuid?: string;
+    /** A short substring of the Lark message that we expect to find inside
+     *  the next matching `user` event's content. When set, only a user event
+     *  whose stringified content contains this fingerprint is allowed to
+     *  start the turn. Local-terminal input (whose content won't contain
+     *  the Lark fingerprint) leaves the turn unstarted. */
+    contentFingerprint?: string;
+    /** Full normalised content of the Lark message. Used by the rotation
+     *  fallback's recovery path to gate a switch into an UNKNOWN sessionId
+     *  on exact equality with a user/queue event in that file — much
+     *  stronger than the substring fingerprint check, which can't tell
+     *  "test" from "run tests" across sibling panes. Stored in addition to
+     *  `contentFingerprint` (not instead of) because in-pane known-sid
+     *  candidates still benefit from the cheaper substring path. */
+    contentNormalized?: string;
+    /** JSONL file the turn's user event was first seen in. Stamped by ingest()
+     *  when the turn transitions to started. Lets the emit step re-read text
+     *  from the original transcript even after a sessionId rotation has
+     *  pointed bridgeJsonlPath at a *different* file — without this stamp,
+     *  uuid → text resolution would fail and the reply would be silently
+     *  dropped. */
+    sourceJsonlPath?: string;
+    /** Wall-clock millis when mark() was called. Lets the fingerprint-based
+     *  rotation fallback bound its scan to events written after we marked
+     *  the turn — short fingerprints ("hello", "test") would otherwise risk
+     *  matching pre-existing user lines in unrelated sibling jsonls. */
+    markTimeMs?: number;
+}
+/** Trim a Lark message into a stable fingerprint. Keeps a leading window
+ *  of non-whitespace-collapsed content; long enough to disambiguate, short
+ *  enough that minor formatting differences (newlines, attachment hints
+ *  appended below) don't break the match. */
+export declare function makeFingerprint(message: string, len?: number): string | undefined;
+export declare class BridgeTurnQueue {
+    private seen;
+    private queue;
+    private collecting;
+    /** Register events as historical — their uuids are now considered seen
+     *  but no attribution happens. Used at attach time to baseline. */
+    absorb(events: TranscriptEvent[]): void;
+    /** Push a new pending turn for the next Lark message. `contentFingerprint`
+     *  (when set) restricts which user event can start this turn — only a
+     *  user event whose content contains the fingerprint qualifies. Pass
+     *  `undefined` to start on the next user event regardless (legacy).
+     *
+     *  `markTimeMs` is captured here so the rotation fallback can bound its
+     *  fingerprint scan to events written after this point — protects short
+     *  fingerprints from matching old history in unrelated sibling jsonls. */
+    mark(turnId: string, contentFingerprint?: string, markTimeMs?: number, contentNormalized?: string): string;
+    /** Drop all pending turns. Used when the worker discovers it can't
+     *  reliably attribute future events (e.g. baseline raced with a turn
+     *  already in flight) and wants to clear the slate. */
+    clearPending(): BridgePendingTurn[];
+    /** Drop a specific pending turn by turnId iff it has not yet started
+     *  collecting assistant text. Returns the dropped turn or null if not
+     *  found / already started. Used by the worker when a writeInput's
+     *  deferred recheck conclusively fails — the user has been notified
+     *  the message was lost, so keeping a fingerprint-bearing mark around
+     *  only fuels the per-tick rotation-fallback scan that already
+     *  spammed 99% CPU once (no jsonl line will ever match). */
+    dropPendingTurn(turnId: string): BridgePendingTurn | null;
+    /** Sweep pending (unstarted) turns whose mark is older than `maxAgeMs`.
+     *  Returns the dropped turns for logging. Belt-and-braces backstop for
+     *  any future code path that leaves an unstarted mark stranded — without
+     *  it, `maybeSwitchBridgeJsonl` would keep doing full-directory jsonl
+     *  scans every poll tick until the worker restarts. Started turns are
+     *  never expired here: once Claude actually wrote the user line, the
+     *  turn is collecting assistant text and we want to wait however long
+     *  the model takes. */
+    pruneExpired(maxAgeMs: number, now?: number): BridgePendingTurn[];
+    /** Process newly-appended events. Idempotent on uuid: events with seen
+     *  uuids are skipped, so callers can safely replay.
+     *
+     *  `sourceJsonlPath` (when provided) is stamped onto a turn at the moment
+     *  it transitions from "pending" to "started" — so that emit-time text
+     *  resolution reads the same transcript file the user/assistant uuids
+     *  were originally observed in. Without this, a sessionId rotation
+     *  between ingest and emit would silently drop the reply, since the
+     *  global current jsonl path would no longer contain those uuids. */
+    ingest(events: TranscriptEvent[], sourceJsonlPath?: string): void;
+    /** Shared turn-start handler. Called for both `role:user` and
+     *  `attachment(queued_command)` events once meaningfulness has been
+     *  established by the caller. Encapsulates:
+     *    1. HOL-block drop of the previous collecting turn when it got no
+     *       assistant text (Claude moved on).
+     *    2. Fingerprint-gated start of the earliest unstarted Lark turn,
+     *       falling through to local-turn synthesis on mismatch.
+     *    3. markTimeMs override to the transcript event's own timestamp —
+     *       critical for type-ahead, where the original markTimeMs (set when
+     *       the worker wrote to PTY) can be many seconds earlier than the
+     *       moment Claude actually dequeues and starts processing the turn.
+     *       The bridge-fallback gate's [markTimeMs, nextBoundaryMs) window
+     *       MUST anchor on the latter, otherwise a `botmux send` from the
+     *       previous turn can leak into the next turn's window and the
+     *       suppression decision flips to the wrong turn (real reply
+     *       suppressed, fallback shown — exactly what the type-ahead-disable
+     *       in commit b2d9791 was protecting against). */
+    private handleTurnStart;
+    /** Pop FIFO any leading turn that's started AND has assistant text.
+     *  Returns the popped turns in order; the caller is responsible for
+     *  rebuilding the text payload from the assistant uuids. */
+    drainEmittable(): BridgePendingTurn[];
+    /** Number of queued (not-yet-emitted) Lark turns. */
+    size(): number;
+    /** Test helper — peek the queue without mutating. */
+    peek(): readonly BridgePendingTurn[];
+}
+//# sourceMappingURL=bridge-turn-queue.d.ts.map

package/dist/services/bridge-turn-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-turn-queue.d.ts","sourceRoot":"","sources":["../../src/services/bridge-turn-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,uBAAuB,EAA0E,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAI/J,OAAO,EAAE,uBAAuB,EAAE,CAAC;AAEnC,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB;;;;+EAI2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;gEAG4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;2DAIuD;IACvD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;oEAMgE;IAChE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;mBAKe;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;wEAGoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAQD;;;6CAG6C;AAC7C,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,SAAK,GAAG,MAAM,GAAG,SAAS,CAK7E;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,UAAU,CAAkC;IAEpD;uEACmE;IACnE,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,IAAI;IAMvC;;;;;;;8EAO0E;IAC1E,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,kBAAkB,CAAC,EAAE,MAAM,EAAE,UAAU,GAAE,MAAmB,EAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,MAAM;IAYtH;;2DAEuD;IACvD,YAAY,IAAI,iBAAiB,EAAE;IAMnC;;;;;;gEAM4D;IAC5D,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI;IAOzD;;;;;;;2BAOuB;IACvB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,iBAAiB,EAAE;IAY7E;;;;;;;;yEAQqE;IACrE,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI;IAgEjE;;;;;;;;;;;;;;;;0DAgBsD;IACtD,OAAO,CAAC,eAAe;IA0DvB;;gEAE4D;IAC5D,cAAc,IAAI,iBAAiB,EAAE;IAYrC,qDAAqD;IACrD,IAAI,IAAI,MAAM;IAId,qDAAqD;IACrD,IAAI,IAAI,SAAS,iBAAiB,EAAE;CAGrC"}