tmux-ide 2.9.4 → 2.9.6

package/packages/daemon/src/lib/runtime-trace-writer.ts

@@ -0,0 +1,132 @@
+import type { Writable } from "node:stream";
+
+const MAX_RECORD_BYTES = 64 * 1024;
+
+/** Opt-in diagnostics: one stream buffer, no additional queue or producer backpressure. */
+export function createRuntimeTraceWriter(
+  stream: Writable,
+  identity: { processId: string; daemonInstanceId: string },
+  closeTimeoutMs = 1000,
+) {
+  const counts = {
+    offeredRecords: 0,
+    acceptedRecords: 0,
+    droppedRecords: 0,
+    saturatedDrops: 0,
+    failedDrops: 0,
+    oversizedRecords: 0,
+    constructionFailures: 0,
+    rejectedWrites: 0,
+    writeFailures: 0,
+  };
+  let saturated = false;
+  let failed = false;
+  let closed = false;
+  let closing: Promise<void> | undefined;
+  let closeFailure: ((error: Error) => void) | undefined;
+  const snapshot = () => ({ ...counts, failed, saturated, writableLength: stream.writableLength });
+  stream.on("drain", () => {
+    if (!failed) saturated = false;
+  });
+  // Retain the error listener through destroy: a late stream error must not escape cleanup.
+  stream.on("error", (error: Error) => {
+    counts.writeFailures++;
+    failed = true;
+    closeFailure?.(error);
+  });
+  return {
+    snapshot,
+    append(build: () => unknown): void {
+      if (closed) return;
+      counts.offeredRecords++;
+      if (failed || stream.destroyed) {
+        counts.failedDrops++;
+        counts.droppedRecords++;
+        return;
+      }
+      if (saturated) {
+        counts.saturatedDrops++;
+        counts.droppedRecords++;
+        return;
+      }
+      let line: string;
+      try {
+        const json = JSON.stringify(build());
+        if (json === undefined) throw new Error("Trace record is not JSON");
+        line = `${json}\n`;
+        if (Buffer.byteLength(line) > MAX_RECORD_BYTES) {
+          counts.oversizedRecords++;
+          counts.droppedRecords++;
+          return;
+        }
+      } catch {
+        counts.constructionFailures++;
+        counts.droppedRecords++;
+        failed = true;
+        return;
+      }
+      try {
+        saturated = !stream.write(line);
+        counts.acceptedRecords++;
+      } catch {
+        counts.rejectedWrites++;
+        counts.droppedRecords++;
+        failed = true;
+      }
+    },
+    close(incomplete = false): Promise<void> {
+      if (closing) return closing;
+      closed = true;
+      if (incomplete) failed = true;
+      closing = new Promise<void>((resolve, reject) => {
+        let settled = false;
+        const finish = (error?: Error) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          stream.off("drain", end);
+          stream.off("close", prematureClose);
+          closeFailure = undefined;
+          if (error) {
+            failed = true;
+            stream.destroy();
+            reject(error);
+          } else resolve();
+        };
+        const prematureClose = () =>
+          finish(new Error("Runtime trace closed before final summary completion"));
+        const end = () => {
+          try {
+            if (stream.destroyed || !stream.writable)
+              throw new Error("Runtime trace stream unavailable");
+            const summary = {
+              version: 1,
+              type: "performance.daemon-trace.summary",
+              ...identity,
+              ...snapshot(),
+              maxRecordBytes: MAX_RECORD_BYTES,
+              acceptedRecordsExcludeSummary: true,
+              shutdownKind: incomplete ? "startup-rollback" : "normal",
+              ringTailOverwrites: "not-file-loss",
+            };
+            stream.end(`${JSON.stringify(summary)}\n`, () =>
+              finish(failed ? new Error("Runtime trace recorded failures") : undefined),
+            );
+          } catch (error) {
+            finish(error instanceof Error ? error : new Error("Runtime trace end failed"));
+          }
+        };
+        const timer = setTimeout(
+          () => finish(new Error("Runtime trace close timed out")),
+          closeTimeoutMs,
+        );
+        closeFailure = finish;
+        stream.on("close", prematureClose);
+        if (stream.destroyed) finish(new Error("Runtime trace stream destroyed"));
+        else if (saturated && stream.writableNeedDrain) stream.once("drain", end);
+        else end();
+      });
+      return closing;
+    },
+  };
+}

package/packages/daemon/src/lib/tmux-client-execution.ts

@@ -1,7 +1,12 @@
+import { fileURLToPath } from "node:url";
 import { accessSync, constants, realpathSync, statSync } from "node:fs";
-import { delimiter, isAbsolute, join } from "node:path";
+import { delimiter, isAbsolute, join, resolve } from "node:path";
 import { resolveRuntimeNamespace } from "./runtime-namespace.ts";
-import { resolveBundledTmux, bundledTmuxResourceEnvironment } from "./bundled-tmux.ts";
+import {
+  resolveBundledTmux,
+  bundledTmuxResourceEnvironment,
+  withBundledTmuxResources,
+} from "./bundled-tmux.ts";
 
 export function resolveTmuxExecutable(): string {
   if (resolveRuntimeNamespace().development) return resolveBundledTmux()!;
@@ -57,3 +62,43 @@ export function tmuxClientEnvironment(
   }
   return { ...environment, ...bundledTmuxResourceEnvironment(executable) };
 }
+
+/** Ordinary CLI commands retain PATH selection; bundled tmux fills a missing system client. */
+export function resolveOrdinaryTmuxClient(
+  environment: NodeJS.ProcessEnv,
+  cwd?: string | URL,
+): {
+  executable: string;
+  environment: NodeJS.ProcessEnv;
+} {
+  const configured = environment.TMUX_IDE_TMUX_BIN;
+  const candidates = configured
+    ? [configured]
+    : (environment.PATH ?? "/usr/bin:/bin")
+        .split(delimiter)
+        .map((entry) =>
+          resolve(cwd instanceof URL ? fileURLToPath(cwd) : (cwd ?? process.cwd()), entry, "tmux"),
+        );
+  let executable: string | undefined;
+  for (const candidate of candidates) {
+    try {
+      if (!isAbsolute(candidate)) continue;
+      accessSync(candidate, constants.X_OK);
+      const canonical = realpathSync(candidate);
+      if (statSync(canonical).isFile()) {
+        executable = canonical;
+        break;
+      }
+    } catch {
+      /* Try the next ordinary PATH candidate. */
+    }
+  }
+  if (!executable && !configured)
+    executable =
+      resolveBundledTmux([
+        ...(environment.TMUX_IDE_CLI ? [environment.TMUX_IDE_CLI] : []),
+        fileURLToPath(import.meta.url),
+      ]) ?? undefined;
+  if (!executable) throw new Error("tmux_executable_unavailable");
+  return { executable, environment: withBundledTmuxResources(executable, environment) };
+}

package/packages/daemon/src/lib/tmux-pane-editor-context.ts

@@ -0,0 +1,124 @@
+import { isAbsolute, resolve } from "node:path";
+import { z } from "zod";
+import {
+  PaneEditorContextTargetSchemaZ,
+  WorkspacePaneCwdSchemaZ,
+  type PaneEditorContextTarget,
+  type PaneEditorContextObservation,
+} from "@tmux-ide/contracts";
+import type { LiveSessionSummary } from "../command-center/discovery.ts";
+import type {
+  NativeTerminalInventoryPaneSnapshot,
+  WorkspaceTerminalInventoryRuntime,
+} from "../terminal/attachments/native-runtime.ts";
+import type { WorkspaceRegistry } from "./workspace-registry.ts";
+import { materializePaneCwd, normalizePaneCwd } from "./workspace-state.ts";
+
+export type { PaneEditorContextTarget, PaneEditorContextObservation } from "@tmux-ide/contracts";
+
+interface Options {
+  readonly generation: string;
+  readonly assertOpen: () => void;
+  readonly registry: Pick<WorkspaceRegistry, "get">;
+  readonly catalog: () => Promise<LiveSessionSummary[]>;
+  readonly inventory: Pick<WorkspaceTerminalInventoryRuntime, "discoverTerminalInventory">;
+}
+
+/** Constructed only by the direct, generation-fenced local tmux server owner. */
+export function createPaneEditorContextResolver(options: Options) {
+  const generation = z.uuid().parse(options.generation);
+  return async (
+    input: PaneEditorContextTarget,
+    cancellation?: AbortSignal,
+  ): Promise<PaneEditorContextObservation> => {
+    const target = PaneEditorContextTargetSchemaZ.parse(input);
+    // A supplied signal selects a fresh inventory read, not an existing flight.
+    const signal = cancellation
+      ? AbortSignal.any([cancellation, AbortSignal.timeout(5_000)])
+      : AbortSignal.timeout(5_000);
+    const unavailable = (): never => {
+      throw new Error("Selected pane editor context is unavailable");
+    };
+    const assertOwner = () => {
+      options.assertOpen();
+      signal.throwIfAborted();
+      if (target.generation !== generation) unavailable();
+    };
+    assertOwner();
+    const workspace = options.registry.get(target.workspaceName);
+    if (!workspace) return unavailable();
+    const { sessionName, projectDir } = workspace;
+    if (!isAbsolute(projectDir)) return unavailable();
+    const assertScope = () => {
+      assertOwner();
+      const current = options.registry.get(target.workspaceName);
+      if (
+        current !== workspace ||
+        current.sessionName !== sessionName ||
+        current.projectDir !== projectDir
+      )
+        unavailable();
+    };
+    const checkCatalog = async () => {
+      assertScope();
+      const sessions = await options.catalog();
+      assertScope();
+      const matches = sessions.filter((session) => session.liveSessionId === target.liveSessionId);
+      if (matches.length !== 1 || matches[0]!.sessionName !== sessionName) unavailable();
+    };
+    const readPane = async (): Promise<NativeTerminalInventoryPaneSnapshot> => {
+      assertScope();
+      const snapshot = await options.inventory.discoverTerminalInventory(signal);
+      assertScope();
+      const analysis = snapshot.catalog;
+      if (
+        analysis.invalidRuntimeProof ||
+        analysis.duplicateSemanticStamp ||
+        analysis.duplicateRuntimePaneBinding
+      )
+        unavailable();
+      const matches = snapshot.panes.filter(
+        (pane) =>
+          pane.workspaceName === target.workspaceName &&
+          pane.semanticPaneId === target.semanticPaneId,
+      );
+      if (matches.length !== 1) return unavailable();
+      const pane = matches[0]!;
+      if (pane.sessionName !== sessionName || !pane.dir || !isAbsolute(pane.dir)) unavailable();
+      // Detach observations from mutable discovery/test adapters before another await.
+      return { ...pane };
+    };
+    await checkCatalog();
+    assertScope();
+    const before = await readPane();
+    assertScope();
+    await checkCatalog();
+    assertScope();
+    // Discovery already fences topology internally. This second read additionally
+    // refuses a cwd/binding change during resolution; it never retries a selection.
+    const after = await readPane();
+    assertScope();
+    for (const key of [
+      "sessionId",
+      "windowId",
+      "runtimePaneId",
+      "windowStamp",
+      "nativePaneBirthId",
+      "dir",
+    ] as const)
+      if ((before[key] ?? null) !== (after[key] ?? null)) unavailable();
+    // No saved layout fallback: projectDir only expresses the live cwd as a
+    // typed project-relative value when the existing containment policy permits it.
+    const absolute = WorkspacePaneCwdSchemaZ.parse({ kind: "absolute", path: resolve(after.dir) });
+    const relative = WorkspacePaneCwdSchemaZ.safeParse(normalizePaneCwd(after.dir, projectDir));
+    const cwd =
+      relative.success && materializePaneCwd(relative.data, projectDir) === absolute.path
+        ? relative.data
+        : absolute;
+    const directory = materializePaneCwd(cwd, projectDir);
+    // Portable project-relative paths accept both separator styles. A literal
+    // backslash on POSIX must not silently name a different local directory.
+    if (!directory || directory !== absolute.path) return unavailable();
+    return Object.freeze({ ...target, cwd: Object.freeze(cwd), directory });
+  };
+}

package/packages/daemon/src/lib/tmux-server-agent-admission.ts

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { TerminalAttachmentSemanticPaneIdSchemaZ } from "@tmux-ide/contracts";
+import {
+  agentIdForPaneStamp,
+  fallbackPaneId,
+} from "../command-center/resources/application-shell.ts";
+
+export const observedAgentSchema = z
+  .object({
+    observedPaneId: z.string().min(1).max(512),
+    observedAgentId: z.string().min(1).max(512),
+  })
+  .strict();
+export type ObservedAgent = z.infer<typeof observedAgentSchema>;
+type Binding = { pane: string; birth: string; window: string; stamp: string };
+
+/** Fresh daemon facts only. No label/index fallback and no client-supplied native IDs. */
+export async function captureAgentAdmission(
+  run: (args: readonly string[]) => Promise<string>,
+  session: { id: string; name: string },
+  observed: ObservedAgent,
+) {
+  const scan = async (): Promise<Binding[]> => {
+    const raw = await run([
+      "list-panes",
+      "-s",
+      "-t",
+      session.id,
+      "-F",
+      "#{session_id}\t#{window_id}\t#{pane_id}\t#{pane_birth_id}\t#{@tmux_ide_pane_id}",
+    ]);
+    if (Buffer.byteLength(raw) > 1024 * 1024)
+      throw new Error("Agent inventory exceeds admission bounds");
+    const rows = raw
+      .replace(/\n+$/u, "")
+      .split("\n")
+      .map((line) => {
+        const fields = line.split("\t");
+        const [id, window, pane, birth, stamp] = fields;
+        if (
+          fields.length !== 5 ||
+          id !== session.id ||
+          !/^@\d+$/.test(window!) ||
+          !/^%\d+$/.test(pane!) ||
+          !/^[1-9]\d*$/.test(birth!)
+        )
+          throw new Error("Agent native identity is unavailable");
+        return { window: window!, pane: pane!, birth: birth!, stamp: stamp! };
+      });
+    if (rows.length > 512) throw new Error("Agent inventory exceeds admission bounds");
+    return rows;
+  };
+  const initial = await scan();
+  const candidates = initial.filter((row) => {
+    const id =
+      row.stamp === ""
+        ? fallbackPaneId(
+            { name: session.name, runtimeSessionId: session.id },
+            { runtimePaneId: row.pane },
+          )
+        : row.stamp;
+    return id === observed.observedPaneId && agentIdForPaneStamp(id) === observed.observedAgentId;
+  });
+  if (candidates.length !== 1) throw new Error("Observed agent is no longer unique");
+  const captured = candidates[0]!;
+  if (
+    captured.stamp &&
+    (!TerminalAttachmentSemanticPaneIdSchemaZ.safeParse(captured.stamp).success ||
+      initial.filter((r) => r.stamp === captured.stamp).length !== 1)
+  )
+    throw new Error("Observed agent stamp is ambiguous");
+  return {
+    async verify(promoted: boolean) {
+      const rows = await scan();
+      const matching = rows.filter((row) => row.pane === captured.pane);
+      if (
+        matching.length !== 1 ||
+        matching[0]!.birth !== captured.birth ||
+        matching[0]!.window !== captured.window
+      )
+        throw new Error("Observed agent lifetime changed");
+      const current = matching[0]!;
+      if (captured.stamp && current.stamp !== captured.stamp)
+        throw new Error("Observed agent stamp changed");
+      if (!promoted && current.stamp !== captured.stamp)
+        throw new Error("Observed agent stamp changed");
+      if (
+        promoted &&
+        (!TerminalAttachmentSemanticPaneIdSchemaZ.safeParse(current.stamp).success ||
+          rows.filter((row) => row.stamp === current.stamp).length !== 1)
+      )
+        throw new Error("Promoted agent identity is unavailable");
+      return current.stamp;
+    },
+  };
+}

package/packages/daemon/src/lib/tmux-server-owner.ts

@@ -1,3 +1,10 @@
+import { shellEscape } from "./shell.ts";
+import {
+  createNativeSplitCapabilityProbe,
+  createNativeSplitReadiness,
+} from "./native-split-capability.ts";
+import { executeCanonicalSplitMutation } from "./canonical-split-mutation.ts";
+import { createGuardedNativeSplitResize } from "./guarded-native-split-resize.ts";
 import { execFileSync } from "node:child_process";
 import { requireSupportedTmuxVersion } from "./tmux-version.ts";
 import { PaneSourceDiscovery } from "./pane-source-discovery.ts";
@@ -19,7 +26,15 @@ import { createNativeTmuxSessionCreator } from "./tmux-server-session-create.ts"
 import type { WorkspacePaneCreateMutationRequest } from "@tmux-ide/contracts";
 import { createTmuxSessionMutationFence } from "./tmux-session-mutation-fence.ts";
 import { createNativeTmuxSessionOpener } from "./tmux-server-session-open.ts";
-import { randomUUID } from "node:crypto";
+import { observedAgentSchema } from "./tmux-server-agent-admission.ts";
+import { createPaneEditorContextResolver } from "./tmux-pane-editor-context.ts";
+import { createHash, randomUUID } from "node:crypto";
+import {
+  WorkspaceIdSchemaZ,
+  WindowLinkTargetSchemaZ,
+  type WindowLinkTarget,
+} from "@tmux-ide/contracts";
+import { WindowSplitLayoutUnavailable } from "../terminal/mirror/window-split-authority.ts";
 import { mkdirSync } from "node:fs";
 import { z } from "zod";
 import type { WorkspaceMultiplexerBackend } from "../command-center/actions/handlers/workspace-multiplexer.ts";
@@ -61,6 +76,22 @@ export interface NativeTmuxServerOwnerOptions {
   readonly nativeServerIdentity?: NativeTmuxServerIdentity;
 }
 
+/** Native display names are not necessarily valid shared-contract record identities. */
+function discoveredWorkspaceName(registry: WorkspaceRegistry, sessionName: string): string {
+  if (WorkspaceIdSchemaZ.safeParse(sessionName).success && !registry.has(sessionName))
+    return sessionName;
+  // Existing intent wins even if it occupies a derived ID. Each candidate is
+  // deterministic; repeated refreshes retain the already-adopted session alias.
+  for (let suffix = 0; suffix <= registry.list().length; suffix += 1) {
+    const digest = createHash("sha256")
+      .update(`tmux-ide.discovered-workspace.v1\0${sessionName}\0${suffix}`)
+      .digest("hex");
+    const name = `session-${digest}`;
+    if (!registry.has(name)) return name;
+  }
+  throw new Error("Unable to allocate discovered workspace identity");
+}
+
 /** Refresh discovered live membership without changing durable workspace intent or aliases. */
 export function createNativeTmuxServerCatalog(
   workspaceRegistry: WorkspaceRegistry,
@@ -71,10 +102,19 @@ export function createNativeTmuxServerCatalog(
     assertOpen();
     const raw = await run(
       [
-        "list-panes",
-        "-a",
+        "-N",
+        "if-shell",
         "-F",
-        "#{pid}\t#{session_id}\t#{session_created}\t#{session_name}\t#{pane_id}\t#{session_path}",
+        "#{==:#{server_sessions},0}",
+        "display-message -p 'tmux-ide-empty-catalog-v1'",
+        [
+          "list-panes",
+          "-a",
+          "-F",
+          "#{pid}\t#{session_id}\t#{session_created}\t#{session_name}\t#{pane_id}\t#{session_path}",
+        ]
+          .map(shellEscape)
+          .join(" "),
       ],
       AbortSignal.timeout(2_000),
     );
@@ -83,7 +123,10 @@ export function createNativeTmuxServerCatalog(
       string,
       { summary: LiveSessionSummary; panes: Set<string>; dir: string }
     >();
-    for (const line of raw.trim().split("\n")) {
+    // Only the successful server-side zero-session branch proves emptiness.
+    // Command errors, unsupported formats and unwitnessed blank output stay failures.
+    const lines = raw.trim() === "tmux-ide-empty-catalog-v1" ? [] : raw.trim().split("\n");
+    for (const line of lines) {
       const [pid, id, created, name, pane, dir] = line.split("\t");
       if (
         !pid ||
@@ -114,11 +157,10 @@ export function createNativeTmuxServerCatalog(
         workspaceRegistry.remove(workspace.name);
     for (const { summary, dir } of rows.values())
       if (
-        !workspaceRegistry.has(summary.sessionName) &&
         !workspaceRegistry.list().some((workspace) => workspace.sessionName === summary.sessionName)
       )
         workspaceRegistry.add({
-          name: summary.sessionName,
+          name: discoveredWorkspaceName(workspaceRegistry, summary.sessionName),
           sessionName: summary.sessionName,
           projectDir: dir,
           persistence: "volatile",
@@ -256,8 +298,27 @@ export async function createNativeTmuxServerOwner(options: NativeTmuxServerOwner
           throw new Error("Interaction target lifetime is no longer current");
       },
       resolveSession: (name) => workspaceRegistry.get(name)?.sessionName ?? null,
-      execute: (operationId, intent, timing, execution) => {
+      execute: (operationId, intent, timing, execution, authorizeBeforeEffect) => {
         assertOpen();
+        if (intent.verb === "workspace.window.split.resize")
+          return executeCanonicalSplitMutation(
+            {
+              generation,
+              registry: sessionRuntimeRegistry,
+              resolveSession: (name) => workspaceRegistry.get(name)?.sessionName ?? null,
+              runNative: createGuardedNativeSplitResize({
+                observation: () => observationSelector,
+                runPinnedTmux: generationRun,
+              }),
+            },
+            operationId,
+            intent,
+            () => {
+              assertOpen();
+              if (!authorizeBeforeEffect) throw new Error("Missing execution authorization");
+              authorizeBeforeEffect();
+            },
+          );
         if (intent.verb === "workspace.pane.read")
           return multiplexer.readPane(operationId, intent, execution);
         if (
@@ -290,6 +351,15 @@ export async function createNativeTmuxServerOwner(options: NativeTmuxServerOwner
       traceAuthority: { generation, incarnation: null },
     },
     mirror: {
+      splitLayoutEpoch: () => observationSelector.nativeServerEpoch,
+      splitLayoutPrepare: createNativeSplitReadiness({
+        observation: () => observationSelector ?? null,
+        runPinnedTmux: generationRun,
+      }),
+      splitLayoutCapability: createNativeSplitCapabilityProbe({
+        observation: () => observationSelector ?? null,
+        runPinnedTmux: generationRun,
+      }),
       createOwnedViewerAdapter: createOwnedViewerAdapterFactory({
         environmentId: options.environmentId,
         serverScope: { serverId: options.serverId, generation },
@@ -448,6 +518,13 @@ export async function createNativeTmuxServerOwner(options: NativeTmuxServerOwner
     terminalInventoryRuntime.invalidate();
     return result;
   };
+  const resolvePaneEditorContext = createPaneEditorContextResolver({
+    generation,
+    assertOpen,
+    registry: workspaceRegistry,
+    catalog,
+    inventory: terminalInventoryRuntime,
+  });
   const multiplexerBackend: WorkspaceMultiplexerBackend = {
     mutate: async (...args) => {
       assertOpen();
@@ -519,8 +596,38 @@ export async function createNativeTmuxServerOwner(options: NativeTmuxServerOwner
   return {
     serverId: options.serverId,
     generation,
+    resolvePaneEditorContext,
     catalog,
+    readWindowSplitLayout: async (workspaceName: string, input: WindowLinkTarget) => {
+      assertOpen();
+      const target = WindowLinkTargetSchemaZ.parse(input);
+      const sessions = await catalog();
+      assertOpen();
+      const sessionName = workspaceRegistry.get(workspaceName)?.sessionName;
+      if (
+        !sessionName ||
+        !sessions.some(
+          (row) => row.sessionName === sessionName && row.liveSessionId === target.liveSessionId,
+        )
+      )
+        throw new WindowSplitLayoutUnavailable();
+      const resource = await sessionRuntimeRegistry.readWindowSplitLayout(sessionName, target);
+      assertOpen();
+      return resource;
+    },
     openSession,
+    openAgent: async (
+      liveSessionId: string,
+      observed: Parameters<typeof sessionOpener.openAgent>[1],
+    ) => {
+      const target = observedAgentSchema.parse(observed);
+      await catalog();
+      try {
+        return await sessionOpener.openAgent(liveSessionId, target);
+      } finally {
+        terminalInventoryRuntime.invalidate();
+      }
+    },
     createSession: sessionCreator.createSession,
     createSessionPane: async (
       liveSessionId: string,

package/packages/daemon/src/lib/tmux-server-session-open.ts

@@ -1,3 +1,8 @@
+import {
+  captureAgentAdmission,
+  observedAgentSchema,
+  type ObservedAgent,
+} from "./tmux-server-agent-admission.ts";
 import { randomUUID } from "node:crypto";
 import { WorkspaceCatalogLiveSessionIdSchemaZ } from "@tmux-ide/contracts";
 import { liveSessionIdForNativeIdentity } from "../terminal/protocol/live-session-identity.ts";
@@ -21,15 +26,16 @@ export function createNativeTmuxSessionOpener(options: {
     options.assertOpen();
     if (disposed) throw new Error("Session admission is retired");
   };
-  const open = async (liveSessionId: string) => {
+  const open = async (liveSessionId: string, observed?: ObservedAgent) => {
     assertOpen();
     const records = await options.run([
       "list-sessions",
       "-F",
       "#{pid}\t#{session_id}\t#{session_created}\t#{session_name}",
     ]);
+    // The final field is an exact session identity; spaces are valid name bytes.
     const matches = records
-      .trim()
+      .replace(/\n+$/u, "")
       .split("\n")
       .map((line) => line.split("\t"))
       .filter(
@@ -67,6 +73,10 @@ export function createNativeTmuxSessionOpener(options: {
         throw new Error("Selected live tmux session changed during admission");
       return output;
     };
+    const agent = observed
+      ? await captureAgentAdmission(run, { id: nativeSessionId!, name: name! }, observed)
+      : null;
+    await agent?.verify(false);
     const promotion = new WorkspacePromotionAuthority({
       daemonInstanceId: options.generation,
       registry: options.registry,
@@ -79,7 +89,12 @@ export function createNativeTmuxSessionOpener(options: {
         intent: { sessionId: fleetSessionIdForName(name!) },
       });
       await run(["display-message", "-p", "-t", nativeSessionId!, "#{session_id}"]);
-      return { workspaceName: result.resource.workspaceName, liveSessionId };
+      const semanticPaneId = await agent?.verify(true);
+      return {
+        workspaceName: result.resource.workspaceName,
+        liveSessionId,
+        ...(semanticPaneId ? { semanticPaneId } : {}),
+      };
     } finally {
       await promotion.dispose();
     }
@@ -98,6 +113,26 @@ export function createNativeTmuxSessionOpener(options: {
       tail = operation.catch(() => {});
       return operation;
     },
+    openAgent(
+      liveSessionId: string,
+      input: ObservedAgent,
+    ): Promise<{ workspaceName: string; liveSessionId: string; semanticPaneId: string }> {
+      WorkspaceCatalogLiveSessionIdSchemaZ.parse(liveSessionId);
+      const observed = observedAgentSchema.parse(input);
+      assertOpen();
+      if (pending.size >= 16) throw new Error("Session admission capacity reached");
+      const key = randomUUID();
+      const operation = tail
+        .then(async () => {
+          const result = await open(liveSessionId, observed);
+          if (!result.semanticPaneId) throw new Error("Agent admission returned no target");
+          return { ...result, semanticPaneId: result.semanticPaneId };
+        })
+        .finally(() => pending.delete(key));
+      pending.set(key, operation);
+      tail = operation.catch(() => {});
+      return operation;
+    },
     async dispose() {
       disposed = true;
       await tail;