tmux-ide 2.9.2 → 2.9.4

package/packages/daemon/dist/tui/mirror/runtime/application-terminal-interaction-controller.js

@@ -84,6 +84,64 @@ export function createApplicationTerminalInteractionController(options) {
     let diagnosticWindowFrame = null;
     let diagnosticWindowFrameExpiresAtMicros = 0;
     let inputAuthorityIdentity = null;
+    // Pane selection belongs to the control connection, which can outlive a
+    // terminal renderer rebuild. Never carry selection or input across reconnects.
+    const controlIdentity = (snapshot) => {
+        if (!snapshot ||
+            !["live", "rebinding"].includes(snapshot.status) ||
+            !snapshot.connection ||
+            !snapshot.client ||
+            !snapshot.daemonGeneration)
+            return null;
+        try {
+            const generation = snapshot.client.getSnapshot().generation;
+            if (!Number.isSafeInteger(generation))
+                return null;
+            return {
+                connection: snapshot.connection,
+                client: snapshot.client,
+                daemon: snapshot.daemonGeneration,
+                generation,
+                workspace: snapshot.connection.workspaceName,
+            };
+        }
+        catch {
+            return null;
+        }
+    };
+    const sameControl = (left, right) => left !== null &&
+        right !== null &&
+        left.connection === right.connection &&
+        left.client === right.client &&
+        left.daemon === right.daemon &&
+        left.generation === right.generation &&
+        left.workspace === right.workspace;
+    let selectedControl = null;
+    const waitingInput = new Set();
+    let waitingInputBytes = 0;
+    let releasingInput = null;
+    const awaitInputRuntime = (weight) => {
+        const control = controlIdentity(options.generation());
+        if (!control || waitingInput.size >= 64 || waitingInputBytes + weight > 1024 * 1024)
+            return Promise.resolve(false);
+        return new Promise((resolve) => {
+            const entry = {
+                control,
+                weight,
+                settle: (ready) => {
+                    if (!waitingInput.delete(entry))
+                        return;
+                    waitingInputBytes -= weight;
+                    clearTimeout(timer);
+                    resolve(ready);
+                },
+            };
+            const timer = setTimeout(() => entry.settle(false), 5000);
+            timer.unref?.();
+            waitingInput.add(entry);
+            waitingInputBytes += weight;
+        });
+    };
     const armDiagnosticWindowFrame = (pending) => {
         diagnosticWindowFrame = pending;
         diagnosticWindowFrameExpiresAtMicros = pending.startedAtMicros + 6_000_000;
@@ -356,6 +414,71 @@ export function createApplicationTerminalInteractionController(options) {
             pendingWindowSwitch = null;
         }
     };
+    const beginWindowSwitch = (pane, target, windowLink) => {
+        pendingWindowSwitch = null;
+        if (options.diagnosticsEnabled) {
+            try {
+                const active = options.generation();
+                const identity = active?.adapter?.paneCanonicalIdentity(pane);
+                const clientGeneration = active?.client?.getSnapshot().generation;
+                const startedAtMicros = diagnosticNowMicros();
+                if (active?.status === "live" &&
+                    active.daemonGeneration &&
+                    identity &&
+                    Number.isSafeInteger(clientGeneration) &&
+                    startedAtMicros !== null) {
+                    pendingWindowSwitch = {
+                        selectionKind: windowLink ? "window-link" : "pane",
+                        ...(windowLink ? { windowLink } : {}),
+                        traceId: createTraceId(),
+                        target,
+                        paneId: pane,
+                        startedAtMicros,
+                        daemonGeneration: active.daemonGeneration,
+                        clientGeneration: clientGeneration,
+                        rendererEpoch: active.rendererEpoch,
+                        sourceEpoch: identity.sourceEpoch,
+                        generation: identity.generation,
+                        incarnation: identity.incarnation,
+                        revision: identity.revision,
+                        stateHash: identity.stateHash,
+                        cols: identity.cols,
+                        rows: identity.rows,
+                        layoutPublished: false,
+                        selectionApplied: false,
+                        presentationPublished: false,
+                        followUpRequested: false,
+                        ...(options.detailedWindowSwitchTiming
+                            ? {
+                                timing: {
+                                    receiptAtMicros: null,
+                                    layoutAtMicros: null,
+                                    presentationAtMicros: null,
+                                },
+                            }
+                            : {}),
+                    };
+                    armDiagnosticWindowFrame({ kind: "window-switch", ...pendingWindowSwitch });
+                    diagnose("window-switch-start", { ...pendingWindowSwitch });
+                }
+                else {
+                    diagnose("window-switch-untracked", {
+                        paneId: pane,
+                        target,
+                        status: active?.status ?? null,
+                        daemonGeneration: active?.daemonGeneration ?? null,
+                        rendererEpoch: active?.rendererEpoch ?? null,
+                        clientGeneration: clientGeneration ?? null,
+                        identity: identity ?? null,
+                        laneCounters: active?.fastLane?.lane.counters() ?? null,
+                    });
+                }
+            }
+            catch {
+                pendingWindowSwitch = null;
+            }
+        }
+    };
     let linkSelection = null;
     const finishLinkSelection = (selected) => {
         const pending = linkSelection;
@@ -363,6 +486,20 @@ export function createApplicationTerminalInteractionController(options) {
             return;
         linkSelection = null;
         clearTimeout(pending.timer);
+        const diagnostic = pending.diagnostic;
+        if (diagnostic && pendingWindowSwitch === diagnostic) {
+            if (selected) {
+                diagnostic.selectionApplied = true;
+                maybeRequestWindowSwitchFrame();
+            }
+            else {
+                diagnoseCritical(`window-switch:${diagnostic.traceId}:failed`, "window-switch-failed", {
+                    ...diagnostic,
+                    reason: "window-link-selection-not-applied",
+                });
+                pendingWindowSwitch = null;
+            }
+        }
         pending.resolve(selected);
     };
     const reconcileLinkSelection = (snapshot) => {
@@ -386,11 +523,18 @@ export function createApplicationTerminalInteractionController(options) {
         select: async (paneId) => {
             finishLinkSelection(false);
             const expected = liveSelectionTarget();
+            const selectionControl = controlIdentity(options.generation());
             const selecting = pendingWindowSwitch;
             const operationId = selecting?.traceId;
             const selectionFailure = { current: null };
             const receipt = expected
-                ? await selectTerminalPane(expected, liveSelectionTarget, paneId, operationId, (failure) => {
+                ? await selectTerminalPane(expected, () => {
+                    if (!selectionControl)
+                        return liveSelectionTarget();
+                    return sameControl(selectionControl, controlIdentity(options.generation()))
+                        ? expected
+                        : null;
+                }, paneId, operationId, (failure) => {
                     selectionFailure.current = failure;
                 }, windowLinkForPane(options.layout(), paneId) ?? undefined)
                 : null;
@@ -455,6 +599,16 @@ export function createApplicationTerminalInteractionController(options) {
         },
         send: async (paneId, routed) => {
             const { input, parserOrigin } = routed;
+            const selectionVersion = paneInput.selectionVersion;
+            if (options.generation()?.status === "rebinding") {
+                if (!(await awaitInputRuntime(Buffer.byteLength(input.data, "utf8"))))
+                    return false;
+            }
+            else if (releasingInput) {
+                await releasingInput;
+            }
+            if (paneInput.selectionVersion !== selectionVersion || paneInput.focusedPane !== paneId)
+                return false;
             const active = options.generation();
             if (active?.status !== "live" || !active.fastLane)
                 return false;
@@ -534,7 +688,35 @@ export function createApplicationTerminalInteractionController(options) {
         onFocusedPane: options.setFocusedPane,
     });
     return {
+        cancelPendingInput() {
+            finishLinkSelection(false);
+            paneInput.invalidateSelection();
+            for (const entry of waitingInput)
+                entry.settle(false);
+        },
         adoptGeneration(snapshot) {
+            const control = controlIdentity(snapshot);
+            if (!sameControl(selectedControl, control)) {
+                finishLinkSelection(false);
+                paneInput.invalidateSelection();
+            }
+            selectedControl = control;
+            if (waitingInput.size > 0 && snapshot?.status === "live" && snapshot.fastLane) {
+                // Old waiters resume first; input admitted synchronously by the next
+                // layout publication must not overtake them in this microtask turn.
+                const barrier = Promise.resolve();
+                releasingInput = barrier;
+                queueMicrotask(() => {
+                    if (releasingInput === barrier)
+                        releasingInput = null;
+                });
+            }
+            for (const entry of waitingInput) {
+                if (!sameControl(entry.control, control))
+                    entry.settle(false);
+                else if (snapshot?.status === "live" && snapshot.fastLane)
+                    entry.settle(true);
+            }
             let next = null;
             if (snapshot?.status === "live" &&
                 snapshot.daemonGeneration &&
@@ -570,7 +752,6 @@ export function createApplicationTerminalInteractionController(options) {
                     next.adapter !== inputAuthorityIdentity.adapter);
             if (next === null || replaced) {
                 finishLinkSelection(false);
-                paneInput.invalidateSelection();
                 pendingWindowSwitch = null;
                 pendingWindowRename = null;
                 diagnosticWindowFrame = null;
@@ -715,6 +896,7 @@ export function createApplicationTerminalInteractionController(options) {
                 observed.expectedSemanticWindowId !== target.expectedSemanticWindowId)
                 return;
             finishLinkSelection(false);
+            beginWindowSwitch(paneId, target.expectedSemanticWindowId, target);
             let resolve;
             const settled = new Promise((done) => {
                 resolve = done;
@@ -724,6 +906,7 @@ export function createApplicationTerminalInteractionController(options) {
                 paneId,
                 layout: snapshot,
                 received: false,
+                diagnostic: pendingWindowSwitch,
                 resolve,
                 timer: setTimeout(() => {
                     if (linkSelection === pending)
@@ -751,6 +934,7 @@ export function createApplicationTerminalInteractionController(options) {
                 }
                 const wrapper = (await expected.client.dispatch({
                     kind: "semantic-intent",
+                    ...(pending.diagnostic ? { operationId: pending.diagnostic.traceId } : {}),
                     intent: {
                         verb: "workspace.window.link.select",
                         workspaceName: expected.workspaceName,
@@ -763,6 +947,7 @@ export function createApplicationTerminalInteractionController(options) {
                 if (wrapper.kind !== "semantic-intent" ||
                     !result.success ||
                     result.data.operationId !== wrapper.operationId ||
+                    (pending.diagnostic && wrapper.operationId !== pending.diagnostic.traceId) ||
                     result.data.daemonInstanceId !== expected.daemonGeneration ||
                     result.data.workspaceName !== expected.workspaceName ||
                     result.data.target.linkId !== target.linkId ||
@@ -772,6 +957,18 @@ export function createApplicationTerminalInteractionController(options) {
                     finishLinkSelection(false);
                     return;
                 }
+                if (pending.diagnostic) {
+                    const receiptAtMicros = diagnosticNowMicros();
+                    if (pending.diagnostic.timing)
+                        pending.diagnostic.timing.receiptAtMicros = receiptAtMicros;
+                    diagnose("window-switch-receipt", {
+                        ...pending.diagnostic,
+                        operationId: wrapper.operationId,
+                        selected: true,
+                        applied: true,
+                        ...(options.detailedWindowSwitchTiming ? { phaseAtMicros: receiptAtMicros } : {}),
+                    });
+                }
                 pending.received = true;
                 reconcileLinkSelection(pending.layout);
                 await settled;
@@ -1022,54 +1219,7 @@ export function createApplicationTerminalInteractionController(options) {
             const target = next?.semanticWindowId ?? next?.windowName;
             if (!pane || !target)
                 return;
-            if (options.diagnosticsEnabled) {
-                try {
-                    const active = options.generation();
-                    const identity = active?.adapter?.paneCanonicalIdentity(pane);
-                    const clientGeneration = active?.client?.getSnapshot().generation;
-                    const startedAtMicros = diagnosticNowMicros();
-                    if (active?.status === "live" &&
-                        active.daemonGeneration &&
-                        identity &&
-                        Number.isSafeInteger(clientGeneration) &&
-                        startedAtMicros !== null) {
-                        pendingWindowSwitch = {
-                            traceId: createTraceId(),
-                            target,
-                            paneId: pane,
-                            startedAtMicros,
-                            daemonGeneration: active.daemonGeneration,
-                            clientGeneration: clientGeneration,
-                            rendererEpoch: active.rendererEpoch,
-                            sourceEpoch: identity.sourceEpoch,
-                            generation: identity.generation,
-                            incarnation: identity.incarnation,
-                            revision: identity.revision,
-                            stateHash: identity.stateHash,
-                            cols: identity.cols,
-                            rows: identity.rows,
-                            layoutPublished: false,
-                            selectionApplied: false,
-                            presentationPublished: false,
-                            followUpRequested: false,
-                            ...(options.detailedWindowSwitchTiming
-                                ? {
-                                    timing: {
-                                        receiptAtMicros: null,
-                                        layoutAtMicros: null,
-                                        presentationAtMicros: null,
-                                    },
-                                }
-                                : {}),
-                        };
-                        armDiagnosticWindowFrame({ kind: "window-switch", ...pendingWindowSwitch });
-                        diagnose("window-switch-start", { ...pendingWindowSwitch });
-                    }
-                }
-                catch {
-                    pendingWindowSwitch = null;
-                }
-            }
+            beginWindowSwitch(pane, target);
             paneInput.selectPane(pane, { presentOptimistically: false });
         },
         async zoomPane(targetPane) {
@@ -1265,6 +1415,7 @@ export function createApplicationTerminalInteractionController(options) {
                     ? {}
                     : { phaseAtMicros: pending.timing.presentationAtMicros }),
             });
+            maybeRequestWindowSwitchFrame();
         },
         observeDiagnosticWindowFrame() {
             if (!options.diagnosticsEnabled)

package/packages/daemon/dist/tui/mirror/runtime/bounded-performance-record-writer.js

@@ -2,20 +2,25 @@
 export class BoundedPerformanceRecordWriter {
     #sink;
     #criticalLimit;
-    #pendingCritical = new Map();
+    #pendingCritical = new Set();
+    #pending = [];
+    #pendingByteLimit;
+    #pendingBytes = 0;
+    #flushPromise = null;
+    #resolveFlush = null;
     #saturated = false;
     #failed = false;
     #droppedRecords = 0;
-    constructor(sink, criticalLimit = 16) {
+    constructor(sink, criticalLimit = 16, pendingByteLimit = 64 * 1024) {
         this.#sink = sink;
         this.#criticalLimit = criticalLimit;
+        this.#pendingByteLimit = pendingByteLimit;
     }
     write(record) {
         if (this.#failed)
             return false;
         if (this.#saturated) {
-            this.#droppedRecords += 1;
-            return false;
+            return this.#enqueue(record);
         }
         return this.#writeAccepted(record);
     }
@@ -30,22 +35,57 @@ export class BoundedPerformanceRecordWriter {
             this.#droppedRecords += 1;
             return false;
         }
-        this.#pendingCritical.set(key, record);
-        return true;
+        return this.#enqueue(record, key);
     }
     drain() {
         if (this.#failed)
             return;
         this.#saturated = false;
-        for (const [key, record] of this.#pendingCritical) {
-            this.#pendingCritical.delete(key);
-            if (!this.#writeAccepted(record))
-                break;
+        while (this.#pending.length > 0 && !this.#saturated && !this.#failed) {
+            const next = this.#pending.shift();
+            this.#pendingBytes -= next.bytes;
+            if (next.key !== undefined)
+                this.#pendingCritical.delete(next.key);
+            this.#writeAccepted(next.record);
         }
+        if (this.#pending.length === 0)
+            this.#finishFlush();
+    }
+    /** Wait until retained records reach the stream; its owner then flushes/end()s it. */
+    flush() {
+        if (this.#failed || this.#pending.length === 0)
+            return Promise.resolve();
+        this.#flushPromise ??= new Promise((resolve) => {
+            this.#resolveFlush = resolve;
+        });
+        return this.#flushPromise;
     }
     fail() {
         this.#failed = true;
         this.#pendingCritical.clear();
+        this.#pending.length = 0;
+        this.#pendingBytes = 0;
+        this.#finishFlush();
+    }
+    #enqueue(record, key) {
+        const bytes = Buffer.byteLength(record);
+        // Ordinary bursts get one extra stream-sized buffer. Critical records have
+        // a separate byte reserve as well as their existing key-count limit.
+        const limit = this.#pendingByteLimit + (key === undefined ? 0 : 64 * 1024);
+        if (this.#pending.length >= 1024 || this.#pendingBytes + bytes > limit) {
+            this.#droppedRecords += 1;
+            return false;
+        }
+        if (key !== undefined)
+            this.#pendingCritical.add(key);
+        this.#pending.push({ record, bytes, ...(key === undefined ? {} : { key }) });
+        this.#pendingBytes += bytes;
+        return true;
+    }
+    #finishFlush() {
+        this.#resolveFlush?.();
+        this.#resolveFlush = null;
+        this.#flushPromise = null;
     }
     diagnostics() {
         return Object.freeze({

package/packages/daemon/dist/tui/mirror/runtime/terminal-fast-lane-renderer-adapter.js

@@ -271,12 +271,13 @@ export class TerminalFastLaneRendererAdapter {
             ]);
             if (seen.has(key))
                 continue;
+            // Bound retained de-duplication history, not the renderer's lifetime.
+            // An evicted identity may be reported again only after another real paint.
+            // Pending identities still have their separate per-frame admission limit.
             if (seen.size >= 256)
-                this.#droppedCanonicalHostFrames += 1;
-            else {
-                seen.add(key);
-                identities.push(identity);
-            }
+                seen.delete(seen.values().next().value);
+            seen.add(key);
+            identities.push(identity);
         }
         const dropped = this.#droppedCanonicalHostFrames;
         this.#droppedCanonicalHostFrames = 0;

package/packages/daemon/dist/tui/mirror/runtime/terminal-pane-input-router.js

@@ -13,6 +13,9 @@ export class TerminalPaneInputRouter {
     constructor(options) {
         this.#options = options;
     }
+    get selectionVersion() {
+        return this.#selectionToken;
+    }
     get focusedPane() {
         return this.#focusedPane;
     }

package/packages/daemon/dist/tui/mirror/runtime/workspace-terminal-fast-lane.js

@@ -1,5 +1,7 @@
 import { createTerminalFastLane, createWorkspaceClientTerminalSource, } from "@tmux-ide/daemon-client/terminal-fast-lane";
 import { currentTuiPerformanceEventSink } from "../performance-events.js";
+// Limit outstanding low-water sampling chains, not completed observations over
+// the lifetime of a renderer. Each chain owns at most one pending timeout.
 const TERMINAL_RESOURCE_SAMPLE_LIMIT = 512;
 // The ProductRig idle proof reads after 10.1s. Emit just before that boundary
 // so the operation-scoped sample cannot race the proof read.
@@ -227,7 +229,7 @@ function createOpenTuiTerminalResourceSampler(lane, sink) {
     heartbeatTimer = setTimeout(heartbeat, TERMINAL_RESOURCE_HEARTBEAT_MS);
     heartbeatTimer.unref?.();
     const emit = (operation, identity, expectedAt, sampled) => {
-        if (disposed || resourceEpochIdentity === null || ordinal >= TERMINAL_RESOURCE_SAMPLE_LIMIT)
+        if (disposed || resourceEpochIdentity === null)
             return;
         ordinal += 1;
         const now = readDiagnosticNow();
@@ -373,8 +375,12 @@ function createOpenTuiTerminalResourceSampler(lane, sink) {
     };
     return {
         afterFence(identity) {
-            if (disposed || ordinal >= TERMINAL_RESOURCE_SAMPLE_LIMIT)
+            if (disposed)
+                return;
+            if (pending.size >= TERMINAL_RESOURCE_SAMPLE_LIMIT) {
+                recordSamplingFailure();
                 return;
+            }
             latestIdentity = identity;
             let now;
             if (resourceEpochIdentity === null) {

package/packages/daemon/dist/tui/mirror/terminal-text.js

@@ -50,3 +50,38 @@ function graphemes(text) {
         return [...new Segmenter(undefined, { granularity: "grapheme" }).segment(text)].map((entry) => entry.segment);
     return [...text];
 }
+/** PURE — greedy word-wrap for terminal prose (never returns empty for
+ *  non-empty text; words longer than the width hard-break). */
+export function wrapText(text, width) {
+    if (width <= 0)
+        return [text];
+    const out = [];
+    for (const para of text.split("\n")) {
+        let line = "";
+        for (const word of para.split(/\s+/).filter(Boolean)) {
+            if (line.length === 0) {
+                let w = word;
+                while (w.length > width) {
+                    out.push(w.slice(0, width));
+                    w = w.slice(width);
+                }
+                line = w;
+            }
+            else if (line.length + 1 + word.length <= width) {
+                line += ` ${word}`;
+            }
+            else {
+                out.push(line);
+                let w = word;
+                while (w.length > width) {
+                    out.push(w.slice(0, width));
+                    w = w.slice(width);
+                }
+                line = w;
+            }
+        }
+        if (line.length > 0 || para.length === 0)
+            out.push(line);
+    }
+    return out.length > 0 ? out : [""];
+}

package/packages/daemon/dist/tui/mirror/workspace/connection-feedback.js

@@ -156,9 +156,11 @@ export function createApplicationConnectionFeedback(onPublish = () => undefined)
                     failure,
                     ...(inventory
                         ? {
-                            recovery: missing
-                                ? "A registered session may have been recreated. Choose that session to restore its identity, then retry here. It may be a different session."
-                                : "Terminal identities conflict or cannot be verified. Copy connection details for diagnosis; Retry does not repair identity conflicts.",
+                            recovery: failure.reason === "duplicate-runtime-pane-binding"
+                                ? "A terminal is shared by multiple workspace entries. Unlink shared tmux windows so each belongs to one session, then select Retry."
+                                : missing
+                                    ? "A registered session may have been recreated. Choose that session to restore its identity, then retry here. It may be a different session."
+                                    : "Terminal identities conflict or cannot be verified. Copy connection details for diagnosis; Retry does not repair identity conflicts.",
                         }
                         : {}),
                 };

package/packages/daemon/src/command-center/daemon-fleet-facts-observer.ts

@@ -546,16 +546,7 @@ export function createDefaultFleetFactsReaders(): Pick<
       return null;
     }
   };
-  return {
-    readSessions: async (signal) => {
-      const raw = await execute(SESSION_COMPOSITION_TMUX_ARGS, signal);
-      return raw === null ? null : parseSessionCompositionFacts(raw);
-    },
-    readAgents: async (signal) => {
-      const raw = await execute(AGENT_STATE_TMUX_ARGS, signal);
-      return raw === null ? null : parseAgentStateFacts(raw);
-    },
-  };
+  return createSharedFleetFactsReaders(execute);
 }
 
 export const SESSION_COMPOSITION_TMUX_ARGS = [
@@ -593,3 +584,102 @@ export const AGENT_STATE_TMUX_ARGS = [
 export async function readAgentStateFacts(signal?: AbortSignal): Promise<AgentStateReading | null> {
   return createDefaultFleetFactsReaders().readAgents(signal);
 }
+
+/** Agent columns are excluded from the session topology projection. */
+export const FLEET_FACTS_TMUX_ARGS = [
+  "list-panes",
+  "-a",
+  "-F",
+  `${SESSION_COMPOSITION_TMUX_ARGS[3]}\t#{@agent_state}\t#{pane_current_command}`,
+] as const;
+
+/** Share only an outstanding read; completed snapshots are never cached. */
+export function createSharedFleetFactsReaders(
+  run: (args: readonly string[], signal?: AbortSignal) => string | null | Promise<string | null>,
+  isAbsentServer: (error: unknown) => boolean = () => false,
+): Pick<DaemonFleetFactsObserverOptions, "readSessions" | "readAgents"> {
+  interface Pending {
+    controller: AbortController;
+    result: Promise<string | null>;
+    readers: number;
+  }
+  let pending: Pending | null = null;
+  const read = async (signal?: AbortSignal): Promise<string | null> => {
+    if (signal?.aborted) return null;
+    if (!pending) {
+      const controller = new AbortController();
+      const entry: Pending = {
+        controller,
+        readers: 0,
+        result: Promise.resolve().then(() => run(FLEET_FACTS_TMUX_ARGS, controller.signal)),
+      };
+      entry.result = entry.result.finally(() => {
+        if (pending === entry) pending = null;
+      });
+      pending = entry;
+    }
+    const entry = pending;
+    entry.readers += 1;
+    let released = false;
+    const release = () => {
+      if (released) return;
+      released = true;
+      entry.readers -= 1;
+      if (entry.readers === 0) {
+        if (pending === entry) pending = null;
+        entry.controller.abort();
+      }
+    };
+    signal?.addEventListener("abort", release, { once: true });
+    try {
+      // Keep the promise outstanding for a noncooperative runner so the
+      // observer's per-kind quarantine remains effective after cancellation.
+      const raw = await entry.result;
+      return signal?.aborted ? null : raw;
+    } catch (error) {
+      if (signal?.aborted) return null;
+      throw error;
+    } finally {
+      signal?.removeEventListener("abort", release);
+      release();
+    }
+  };
+  return {
+    readSessions: async (signal) => {
+      try {
+        const raw = await read(signal);
+        return raw === null
+          ? null
+          : parseSessionCompositionFacts(
+              raw
+                .split("\n")
+                .map((line) => line.split("\t").slice(0, 11).join("\t"))
+                .join("\n"),
+            );
+      } catch (error) {
+        // Socket absence is an authoritative empty catalog, but must not
+        // manufacture agent turn completions from a failed agent observation.
+        return isAbsentServer(error) ? parseSessionCompositionFacts("") : null;
+      }
+    },
+    readAgents: async (signal) => {
+      try {
+        const raw = await read(signal);
+        return raw === null
+          ? null
+          : parseAgentStateFacts(
+              raw
+                .split("\n")
+                .map((line) => {
+                  const fields = line.split("\t");
+                  if (fields.length !== 13) return "";
+                  return [fields[0], fields[6], fields[9], fields[11], fields[12]].join("\t");
+                })
+                .join("\n"),
+            );
+      } catch {
+        return null;
+      }
+    },
+  };
+}