agent-coord-mcp 0.26.30 → 0.26.32

package/src/server.ts

@@ -18,7 +18,10 @@ import { capabilitiesSchema, capabilitiesTool } from "./capabilities.js";
 import {
   ensureDirs,
   getTokenMap,
+  TOKENS_FILE,
   reloadTokenMapSync,
+  refreshTokenMapIfChanged,
+  type TokenMapRefresh,
   sessionFile,
   listSessionFiles,
   readJson,
@@ -81,6 +84,8 @@ import {
   setRoomTopicTool,
   statusSchema,
   statusTool,
+  readPaneSchema,
+  readPaneTool,
   unregisterSchema,
   unregisterTool,
   quitSchema,
@@ -306,7 +311,10 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
           leakLine +
           ` A live incumbent can only be superseded with ITS OWN TOKEN now (mint one: scripts/coord-token.mjs add ${claimed}, then SIGHUP the bus) — ` +
           `\`force:true\` binds a SECOND session to one identity rather than stopping the first, which is the defect this refusal exists to prevent, not a step past it. ` +
-          `If you ARE '${claimed}' restarting, re-join from its own tmux pane${leaks.length ? " once nothing else holds it" : ""}. ` +
+          `If you ARE '${claimed}' restarting, re-join from its own pane${leaks.length ? " once nothing else holds it" : ""} — ` +
+          `⟨q-f995c3c7⟩ ANY SERVER RESTART REACHES THIS, including ones no operator sees: \`/model\` restarts this MCP server, ` +
+          `and so do a reconnect, a config reload and a crash-restart. The seat is then a NEW process meeting its own leftover ` +
+          `record, which is why this fired on seats nobody had touched. ` +
           `If you are diagnosing, use status/ping (read-only, they never bind) or your own id.`,
       );
     }
@@ -435,6 +443,13 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
     gate("agentId", statusTool as (a: Record<string, unknown>) => Promise<unknown>, { bindOnClaim: false }),
   );
 
+  addTool(
+    "read_pane",
+    "Read what a seat's pane is showing, THROUGH the seat's transport (⟨q-927e28cd⟩, ADR-023 d4). Read-only: it names no marker field, shells out to nothing, and deletes nothing. Answers `state: \"read\"` with the screen text, or `state: \"unknown\"` with the reason — a pane that is gone, a transport that cannot read panes from this host (tmux-push-remote), or no marker. Never an empty or stale screen. `lines` caps the read (default 200, max 2000); `colors: true` keeps ANSI styling.",
+    readPaneSchema,
+    gate("agentId", readPaneTool as unknown as (a: Record<string, unknown>) => Promise<unknown>, { bindOnClaim: false }),
+  );
+
   addTool(
     "heartbeat",
     "Refresh this agent's lastHeartbeat timestamp.",
@@ -1076,15 +1091,39 @@ async function startHttp(port: number): Promise<void> {
     return transport;
   }
 
+  // ⟨q-54adf191⟩ ONE LINE PER RELOAD, AND ONE PER REFUSAL. A reload nobody can see is
+  // indistinguishable from the bug: the operator reads a 401 and suspects the daemon.
+  function reportTokenRefresh(r: TokenMapRefresh): void {
+    if (r.changed) {
+      console.error(`[agent-coord-mcp] token map reloaded (${r.count} agents) — ${TOKENS_FILE} ${r.reason}`);
+      return;
+    }
+    if (r.refused) {
+      console.error(
+        `[agent-coord-mcp] token map NOT reloaded: ${r.refused} — keeping the previous map (${r.count} agents)`,
+      );
+    }
+  }
+
   // Reverse-lookup: extract bearer from header, map → bound agent. Returns
   // undefined if no map is configured (advisory mode); throws-like return of
   // null if the bearer doesn't match any known agent (caller responds 401).
   function resolveBoundAgent(authHeader: string | undefined): { ok: boolean; agent?: string } {
     if (!authHeader || !authHeader.startsWith("Bearer ")) return { ok: false };
     const bearer = authHeader.slice("Bearer ".length);
+    // ⟨q-54adf191⟩ Pick up a tokens.json that changed while this daemon ran. Rate-limited, so the
+    // steady state is one stat; the file is read only when its stamp moved. Every outcome that is
+    // not "nothing happened" is SAID — a silent reload is the defect this row exists for.
+    reportTokenRefresh(refreshTokenMapIfChanged());
     const tokenMap = getTokenMap();
     if (tokenMap) {
-      const agent = tokenMap.get(bearer);
+      let agent = tokenMap.get(bearer);
+      if (!agent) {
+        // An unknown bearer is exactly the symptom of a token minted since the last check, so it
+        // forces one check past the rate limit. It cannot grant anything the file does not hold.
+        reportTokenRefresh(refreshTokenMapIfChanged({ force: true }));
+        agent = getTokenMap()?.get(bearer);
+      }
       // ⛔ THE ONLY PLACE A PRE-BOUND SEAT CAN GET A TAIL. The `startTailOnBind` sites in the tool
       // path all sit behind `bound === undefined` — the TOFU claim. Here identity arrives already
       // decided by the bearer, that branch is unreachable, and before this line NO tail ever

package/src/store.ts

@@ -1,4 +1,4 @@
-import { promises as fs, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { statSync, promises as fs, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import path from "node:path";
@@ -199,6 +199,10 @@ export function getTokenMap(): Map<string, string> | null {
   if (!tokenMapInitialized) {
     tokenMapCache = readTokenMapSync();
     tokenMapInitialized = true;
+    // Stamp the file we just read, or the first change check would report a map that never
+    // changed as newly "appeared" and re-read a file nobody touched.
+    tokenMapStamp = stampOf();
+    tokenMapCheckedAt = Date.now();
   }
   return tokenMapCache;
 }
@@ -209,9 +213,134 @@ export function getTokenMap(): Map<string, string> | null {
 export function reloadTokenMapSync(): Map<string, string> | null {
   tokenMapCache = readTokenMapSync();
   tokenMapInitialized = true;
+  // Keep the change-detection stamp in step, or the next stat would read the same file again.
+  tokenMapStamp = stampOf();
+  tokenMapCheckedAt = Date.now();
   return tokenMapCache;
 }
 
+// ⟨q-54adf191⟩ RELOAD WHEN THE FILE CHANGES, AND SAY WHAT HAPPENED.
+//
+// The daemon read tokens.json once at startup and had no watcher, so a token minted while it ran
+// was refused with a 401 that looks exactly like a broken daemon — every file on disk correct. The
+// operator had to remember SIGHUP. This weakens nothing: the file is the authority either way, and
+// a reload cannot grant a bearer the file does not contain.
+//
+// THE TRIGGER IS A STAMP CHECK ON THE AUTH PATH, NOT A WATCHER AND NOT A TIMER.
+//   · a watcher (fs.watch) is per-platform and silently unreliable on network and virtualised
+//     filesystems — exactly where a shared bus dir often lives — and it would hold the event loop
+//     of an otherwise idle daemon;
+//   · a poll timer wakes a process that may serve nothing for hours, and still misses a change
+//     that lands between ticks;
+//   · a stat on a request the daemon is already serving costs one syscall, is rate-limited, and
+//     reads the file ONLY when the stamp moved. An unknown bearer forces one extra check, so a
+//     newly minted token authenticates on its first call rather than on the next tick.
+// SIGHUP stays as the explicit path and still forces a read.
+const TOKEN_RELOAD_MIN_MS = (() => {
+  const n = Number(process.env.AGENT_COORD_TOKEN_RELOAD_MS);
+  return Number.isFinite(n) && n >= 0 ? n : 1000;
+})();
+
+/** What a refresh did. `changed` means the in-process map was REPLACED. */
+export type TokenMapRefresh = {
+  changed: boolean;
+  reason: "unbound" | "rate-limited" | "unchanged" | "changed" | "appeared" | "malformed" | "vanished";
+  count: number | null;
+  /** Present only when the reload was REFUSED; the previous map still serves. */
+  refused?: string;
+};
+
+// The file identity we compare against: mtime, size AND inode.
+//
+// ⛔ THE INODE IS LOAD-BEARING, NOT BELT-AND-BRACES. `coord-token` rotates by writing a temp file and
+// renaming it into place, so the replacement is a DIFFERENT INODE that can carry the SAME mtime and
+// the SAME size (a rotated token is the same length as the one it replaces). Without the inode this
+// stamp reads "unchanged" and the daemon keeps serving the REVOKED bearer until someone remembers
+// SIGHUP — the exact defect ⟨q-54adf191⟩ exists to end. Pinned by "a rotation that keeps mtime AND
+// size" below, which goes red the moment the inode leaves this line.
+//
+// ⚠ STATED LIMIT, and the one case this stamp CANNOT see: a rewrite IN PLACE, at equal length, with
+// mtime forced back (`utimes`). Same inode, same size, same mtime is indistinguishable from no write
+// at all, so a bearer revoked that way keeps working until SIGHUP. Measured, and asserted below as a
+// known limit rather than left to be discovered.
+//
+// ⚠⚠ WHY WE ARE SAFE TODAY IS ANOTHER TOOL'S IMPLEMENTATION DETAIL, NOT A PROPERTY OF THIS ONE:
+// `coord-token` never writes this file in place — every write is temp+rename, which moves the inode.
+// The day anything else writes `tokens.json` in place (an editor with a truncating save, a config
+// manager, a hand-rolled script), this comment is the only warning that the reload will not see it.
+// A content hash would close it, at the cost of reading the whole file on every check instead of one
+// stat; that trade was not taken here and is the thing to revisit if that day comes.
+let tokenMapStamp: string | null = null;
+let tokenMapCheckedAt = 0;
+
+function stampOf(): string | null {
+  try {
+    const st = statSync(TOKENS_FILE);
+    return `${st.mtimeMs}:${st.size}:${st.ino}`;
+  } catch {
+    return null;
+  }
+}
+
+/** The state a refresh decides against: what is loaded, the file identity it came from, when it was last checked. */
+export type TokenMapState = { map: Map<string, string> | null; stamp: string | null; checkedAt: number };
+/** The filesystem, as the decision sees it. Injected so the rules can be exercised without a disk. */
+export type TokenMapIo = { stamp: () => string | null; read: () => Map<string, string> | null };
+
+/**
+ * THE WHOLE RULE, IN ONE PURE FUNCTION. The live path and the capability probe both call this, so
+ * there is no second implementation of "did it change, and may the new map replace the old one".
+ */
+export function decideTokenMapRefresh(
+  state: TokenMapState,
+  io: TokenMapIo,
+  opts: { force?: boolean; now?: number } = {},
+): { next: TokenMapState; result: TokenMapRefresh } {
+  const now = opts.now ?? Date.now();
+  const keep = (result: TokenMapRefresh, checkedAt = state.checkedAt) => ({ next: { ...state, checkedAt }, result });
+  // A daemon with no tokens.json is in advisory mode: there is no map to keep fresh, and a file
+  // APPEARING must not silently promote it into bound mode mid-flight.
+  if (state.map === null) return keep({ changed: false, reason: "unbound", count: null });
+  if (!opts.force && now - state.checkedAt < TOKEN_RELOAD_MIN_MS) {
+    return keep({ changed: false, reason: "rate-limited", count: state.map.size });
+  }
+  const size = state.map.size;
+  const stamp = io.stamp();
+  if (stamp === null) {
+    // ⛔ A VANISHED FILE IS A REFUSAL, NEVER A DOWNGRADE. Dropping to advisory mode because the file
+    // is missing would turn `rm tokens.json` into "every bearer is now accepted".
+    return keep({ changed: false, reason: "vanished", count: size, refused: `${TOKENS_FILE} is gone` }, now);
+  }
+  if (stamp === state.stamp) return keep({ changed: false, reason: "unchanged", count: size }, now);
+  try {
+    const next = io.read();
+    if (next === null) {
+      return keep({ changed: false, reason: "vanished", count: size, refused: `${TOKENS_FILE} is gone` }, now);
+    }
+    return {
+      next: { map: next, stamp, checkedAt: now },
+      result: { changed: true, reason: state.stamp === null ? "appeared" : "changed", count: next.size },
+    };
+  } catch (e) {
+    // The stamp is deliberately NOT advanced: a half-written file that is fixed in place, with no
+    // further change to mtime or size, must still be picked up on the next check.
+    return keep({ changed: false, reason: "malformed", count: size, refused: (e as Error).message }, now);
+  }
+}
+
+export function refreshTokenMapIfChanged(opts: { force?: boolean; now?: number } = {}): TokenMapRefresh {
+  if (!tokenMapInitialized) getTokenMap();
+  const { next, result } = decideTokenMapRefresh(
+    { map: tokenMapCache, stamp: tokenMapStamp, checkedAt: tokenMapCheckedAt },
+    { stamp: stampOf, read: readTokenMapSync },
+    opts,
+  );
+  tokenMapCache = next.map;
+  tokenMapStamp = next.stamp;
+  tokenMapCheckedAt = next.checkedAt;
+  return result;
+}
+
 // Atomically rotate the token entry for an agent rename (used by
 // rename_agent so the same bearer continues to authenticate the renamed
 // identity). No-op if the file is absent or the old id isn't in the map.

package/src/tools/index.ts

@@ -11,3 +11,4 @@ export * from "./worktrees.js";
 export * from "./stall.js";
 export * from "./events.js";
 export * from "./record-events.js";
+export * from "./pane.js";

package/src/tools/pane.ts

@@ -0,0 +1,49 @@
+/**
+ * ⟨q-927e28cd⟩ ADR-023 d4, NARROW SLICE — A CONSUMER READS A SEAT'S PANE THROUGH THE BUS.
+ *
+ * The console showed every herdr seat's pane as `410 "pane not found (session gone?)"` for a
+ * live seat, because it captured panes itself through tmux and a herdr pane is not a tmux
+ * pane. ADR-023 d4 says a consumer asks the bus rather than learning each transport; this is
+ * the one question it could not ask, because no bus verb returned what a pane shows.
+ *
+ * ⛔ READ THROUGH THE TRANSPORT, NEVER AROUND IT (the coordinator's GO, and ADR-023 d1). This
+ * module names no field of the marker: it hands the whole marker to `Transport.readPane`,
+ * which decides which pane it is, whether it is its own kind, and whether it is still there.
+ * qa counted 47 marker-internal reads across 5 modules outside src/transports/; this is not
+ * the 48th, and a test says so by reading this file.
+ *
+ * ⛔ READ-ONLY, INCLUDING OF THE STATE DIR. `loadLiveTransports` deletes markers it judges
+ * dead, which is a write; this reads the one marker file and deletes nothing. Whether the
+ * pane is gone is the transport's answer, and it answers UNKNOWN, never an empty screen.
+ */
+import { z } from "zod";
+import type { PaneRead, Transport, TransportMarker } from "../transports/types.js";
+import { activeTransport } from "../transports/index.js";
+import { readJson, transportFile } from "../store.js";
+
+export const readPaneSchema = {
+  agentId: z.string().min(1),
+  /** The seat whose pane to read. */
+  targetAgentId: z.string().min(1),
+  lines: z.number().int().positive().max(2000).optional(),
+  /** Keep the terminal's styling (ANSI escapes) rather than plain text. */
+  colors: z.boolean().optional(),
+};
+
+export type ReadPaneResult = { ok: true; agentId: string } & PaneRead;
+
+export async function readPaneTool(
+  args: { agentId: string; targetAgentId: string; lines?: number; colors?: boolean },
+  transport: Transport | null | undefined = activeTransport(),
+): Promise<ReadPaneResult> {
+  const agentId = args.targetAgentId;
+  const marker = await readJson<TransportMarker | null>(transportFile(agentId), null);
+  if (!marker) return { ok: true, agentId, state: "unknown", why: "no transport marker — the seat is not attached, so there is no pane on record to read" };
+  if (!transport) return { ok: true, agentId, state: "unknown", why: "no transport is wired in this server process, so nothing can read a pane" };
+  if (typeof transport.readPane !== "function") return { ok: true, agentId, state: "unknown", why: `the ${transport.kind} transport cannot read a pane from this host` };
+  try {
+    return { ok: true, agentId, ...(await transport.readPane(marker, { lines: args.lines, format: args.colors ? "ansi" : "text" })) };
+  } catch (e) {
+    return { ok: true, agentId, state: "unknown", why: `the transport threw while reading the pane: ${(e as Error).message}` };
+  }
+}

package/src/tools/registry.ts

@@ -1,5 +1,5 @@
 import { detachAgentTool } from "./transport.js";
-import { isLocallyProbeable, isRemoteTmuxKind, targetOf, HERDR, HerdrTransport, activeTransport } from "../transports/index.js";
+import { isLocallyProbeable, isRemoteTmuxKind, ownPaneTarget, targetOf, HERDR, HerdrTransport, activeTransport } from "../transports/index.js";
 import { readAway, secondCoordinatorRefusal } from "./away.js";
 import { randomUUID } from "node:crypto";
 import { existsSync, openSync, statSync, watch } from "node:fs";
@@ -655,13 +655,14 @@ export async function liveClaimEvidence(agentId: string, now: number): Promise<C
     reasons.push(
       `live ${marker.transport} transport (pid ${marker.pid}${targetOf(marker) ? `, pane ${targetOf(marker)}` : ""})`,
     );
-    if (
-      isLocallyProbeable(marker.transport) &&
-      targetOf(marker) &&
-      process.env.TMUX_PANE &&
-      targetOf(marker) === process.env.TMUX_PANE
-    ) {
+    // ⟨q-f995c3c7⟩ THE SAME SEAT RESTARTING INTO ITS OWN PANE, for herdr as well as tmux. This read
+    // `process.env.TMUX_PANE` alone, which a herdr seat never has, so the exception could not fire
+    // for the fleet that runs on herdr: every seat was refused by its own leftover marker (6 of 6 on
+    // 2026-09-23). The pane comes from THIS process's environment, never from the caller's argument.
+    const ownPane = ownPaneTarget(marker.transport);
+    if (targetOf(marker) && ownPane && targetOf(marker) === ownPane) {
       samePane = true;
+      reasons.push(`the marker names THIS process's own pane (${ownPane})`);
     }
   }
 

package/src/transports/herdr.ts

@@ -34,7 +34,7 @@
  *     same reason (identical evidence for a typo and a default).
  */
 import { spawnSync } from "node:child_process";
-import type { ControlCommand, Liveness, Transport, TransportKind, TransportMarker, TickReading, TickState } from "./types.js";
+import type { ControlCommand, Liveness, PaneRead, Transport, TransportKind, TransportMarker, TickReading, TickState } from "./types.js";
 import { HERDR, TICK_READS_AS, TICK_STORED_AS, targetOf } from "./types.js";
 // ⟨q-dc83023a⟩ The chip grammar and the pane-unsafe byte class are single-sourced in hooks/, shared
 // with both pushers. `hooks/` ships beside `dist/`, so these resolve the same when installed.
@@ -587,6 +587,33 @@ export class HerdrTransport implements Transport {
     return { readable: false, why: `herdr reports agent_status "${status}" for pane ${target} — no agent state is published there, which is a MISSING signal, not a calm seat` };
   }
 
+  /**
+   * ⟨q-927e28cd⟩ THE SCREEN, FOR A CONSUMER — herdr's own `pane read`, the same read `push`
+   * verifies with. Same guards, in the same order, as `readTick`: a marker that is not herdr's,
+   * one with no target, or herdr absent answers UNKNOWN naming which; a pane herdr cannot find
+   * is UNKNOWN too — it is gone, and a gone pane has no screen, not an empty one.
+   */
+  async readPane(marker: TransportMarker, opts: { lines?: number; format?: "text" | "ansi" } = {}): Promise<PaneRead> {
+    return this.readPaneNow(marker, opts);
+  }
+
+  /** The whole rule, synchronous — `readPane` and the capabilities probe both call THIS, so the probe cannot pass while the verb behaves differently. */
+  readPaneNow(marker: TransportMarker, opts: { lines?: number; format?: "text" | "ansi" } = {}): PaneRead {
+    if (marker.transport !== HERDR) return { state: "unknown", why: `transport "${marker.transport}" is not herdr — this transport reads only its own panes` };
+    const target = targetOf(marker);
+    if (!target) return { state: "unknown", why: "no target recorded on the marker" };
+    const avail = this.availability();
+    if (!avail.available) return { state: "unknown", why: avail.reason };
+    const lines = Math.min(Math.max(Math.trunc(opts.lines ?? 200), 1), 2000);
+    const format = opts.format === "ansi" ? "ansi" : "text";
+    const read = this.#run(["pane", "read", target, "--source", "visible", "--lines", String(lines), "--format", format]);
+    if (!read.ok) {
+      if (read.error?.code === "pane_not_found") return { state: "unknown", why: `herdr reports pane ${target} not found — a gone pane has no screen to read` };
+      return { state: "unknown", why: `herdr could not read pane ${target}: ${read.error?.message ?? read.stderr}` };
+    }
+    return { state: "read", text: read.stdout, lines, format, source: `herdr pane ${target}` };
+  }
+
   /**
    * ⟨q-1c95f7d4⟩ Task 1's open question — PUBLISH, and it needs a receipt it does not get.
    *

package/src/transports/types.ts

@@ -76,6 +76,21 @@ export function isLocallyProbeable(transport: string | undefined): boolean {
   return transport === TMUX_PUSH;
 }
 
+/**
+ * ⟨q-f995c3c7⟩ THE PANE THIS PROCESS IS RUNNING IN, read from ITS OWN ENVIRONMENT — never from a
+ * caller's argument, which is what would make it spoofable.
+ *
+ * The first-claim guard's same-pane exception asked `process.env.TMUX_PANE` only, and a herdr seat
+ * has no TMUX_PANE: it has HERDR_PANE_ID. So a herdr seat restarting into its OWN pane could never
+ * satisfy the exception, and every one of them was refused against its own leftover marker. Measured
+ * 2026-09-23: 6 of 6 seats, cleared only by moving the markers aside by hand.
+ */
+export function ownPaneTarget(transport: string | undefined, env: NodeJS.ProcessEnv = process.env): string | undefined {
+  if (transport === HERDR) return env.HERDR_PANE_ID || undefined;
+  if (isLocallyProbeable(transport)) return env.TMUX_PANE || undefined;
+  return undefined;
+}
+
 /**
  * Is liveness for this marker decided by the registry heartbeat rather than by a
  * local pid? True only for the remote kind, whose pid is 0 on a foreign host.
@@ -137,6 +152,19 @@ export type TransportMarker = {
    * unasked question as full capability is the defect this field removes.
    */
   rooms?: boolean;
+  /**
+   * ⟨q-ec020f6a⟩(A) herdr ONLY: the `agent_session.value` herdr itself reported for this
+   * marker's pane at ATTACH TIME (`herdr pane get <target>` — populated from the pane's own
+   * live process, e.g. a Claude Code resume-session-id; never asserted by the attaching
+   * caller). This is what makes the pane a checkable identity rather than a trusted claim:
+   * `resolveBoundAgent`'s pane path re-reads the pane's CURRENT `agent_session.value` on
+   * every request and refuses if it no longer matches what was recorded here — the same
+   * pane_id with a DIFFERENT live session behind it (a restart, a reused pane, a swap) is
+   * exactly the class ⟨q-e439e4ad⟩/⟨q-8c23e5a3⟩ named. Absent means unknown (herdr had no
+   * session for that pane at attach time, or this marker predates the field) — never treated
+   * as a match.
+   */
+  herdrAgentSession?: string;
 };
 
 /**
@@ -221,6 +249,18 @@ export type TickReading =
   | { readable: true; state: TickState; source: string }
   | { readable: false; why: string };
 
+/**
+ * ⟨q-927e28cd⟩ ADR-023 d4, narrow slice — WHAT A PANE SHOWS, READ THROUGH THE TRANSPORT.
+ *
+ * Two answers and no third: the screen, or UNKNOWN with the reason. A pane that is gone, a
+ * binary that is absent, a marker of another kind — each is `unknown`, never an empty screen
+ * and never a stale one: an empty string would read as "the seat is showing nothing", which
+ * is a claim about the seat that nothing measured.
+ */
+export type PaneRead =
+  | { state: "read"; text: string; lines: number; format: "text" | "ansi"; source: string }
+  | { state: "unknown"; why: string };
+
 /** Keystroke-shaped commands a transport must deliver to an interactive pane. */
 export const CONTROL_COMMANDS = ["clear", "compact", "reload-skills"] as const;
 export type ControlCommand = (typeof CONTROL_COMMANDS)[number];
@@ -284,4 +324,24 @@ export interface Transport {
    * that can PUBLISH state to its external observer exposes it here.
    */
   publishTick?(marker: TransportMarker, state: TickState, opts?: { message?: string; source?: string }): Promise<{ ok: boolean; error?: string }>;
+
+  /**
+   * ⟨q-927e28cd⟩ OPTIONAL, AND ITS ABSENCE IS AN ANSWER: a transport that cannot see the
+   * seat's screen from this host (tmux-push-remote: the pane is on another machine) does not
+   * implement it, and every caller reports `unknown` for it rather than guessing.
+   *
+   * ⛔ THE ONE PLACE A PANE IS READ FOR A CONSUMER. Callers pass the WHOLE marker and read no
+   * field of it — which pane, which kind, whether it is this transport's to read are all
+   * decided in here (ADR-023 d1). A caller that needed `target` to use this would be the
+   * forty-eighth marker-internal read qa counted outside src/transports/.
+   */
+  readPane?(marker: TransportMarker, opts?: { lines?: number; format?: "text" | "ansi" }): Promise<PaneRead>;
+
+  /**
+   * ⟨q-ec020f6a⟩(A) — OPTIONAL, and its absence is the honest answer for tmux (a pane's live
+   * "session" concept is a herdr feature; tmux has no equivalent to re-check). Declaring the
+   * method optional is what keeps a pane-identity caller from inventing a match for a
+   * transport that has no way of asking one. See `HerdrTransport.verifyPaneSession`.
+   */
+  verifyPaneSession?(target: string, expectedSession: string | undefined): boolean | null;
 }