feat(tmux): support explicitly configured local sockets (#127)

Owners can now discover and verify a bounded, explicit set of local tmux
-L names or -S socket paths with CHATMUX_TMUX_SOCKETS. Default discovery
is preserved when the option is absent. The P2 contract and
configuration guide define the limits and conservative behavior when any
configured socket is unavailable.

Pane/idle identities include the socket. Fresh actions reject
unconfigured, replaced, symlinked, or incorrectly owned sockets.
Existing terminal leases retain private socket evidence and revalidate
it before replay or reconnect; valid leases can reconnect after
capability expiry, while stale evidence leaves the original PTY
untouched.

Validation: 166 focused discovery/action checks passed, including
isolated real -L/-S servers. Independent Astra review found and fixed a
cached-PTY reconnect gap; 49 focused lease checks, including 13 new
regressions, typecheck and lint passed. Combined verification exposed
four old idle-ID expectations in three real-tmux tests; those
expectations now use the socket-qualified identity contract and are
being rerun before merge. Required Node 22/24/bundle checks must pass on
latest main.

Limit: an unavailable configured socket conservatively retains the whole
discovery lane and delays fresh agent actions. This bounded first
implementation does not scan arbitrary filesystem sockets or terminate
underlying tmux work.

Author: devswha

docs/P2-DISCOVERY-STREAM-RFC.md

@@ -1,6 +1,6 @@
-# P2 Discovery Stream RFC (M4a) — rev.2
+# P2 Discovery Stream RFC (M4a) — rev.3
 
-상태: **승인 대기(approval gate)** — 본 문서는 구현이 아니라 승인 게이트다. 승인 전 B12~B15 제품 소스 착수 금지(승인 계획 §5 B14 «승인 게이트», §9.2 BLOCK).
+상태: rev.2의 역사적 승인 게이트 기록은 아래에 보존한다. **rev.3의 명시적 로컬 tmux socket 지원(§4.1.1)은 2026-09-05 사용자 요청으로 승인되었다.** 이 승인은 해당 범위의 계약 개정과 구현을 함께 허용하며 다른 계약을 확대하지 않는다.
 
 대상 백로그: B12(단일 수집기/권위 스냅샷), B13(epoch + reconnect snapshot→delta), B14(unavailable vs 종료 구분 + 응답 계약 신설), B15(폴링 제거 + 상수 비용 측정).
 
@@ -14,6 +14,7 @@
 
 | rev | 사유 | 반영 내용 | 추적 |
 |---|---|---|---|
+| **rev.3** | 2026-09-05 owner-authorized explicit local socket inventory | §4.1.1: bounded configuration, socket-qualified identity, partial failure and action safety; default unchanged | `docs/TMUX-DISCOVERY.md` |
 | rev.1 | 최초 작성 | §1~§10 + 부록 A/B | — |
 | **rev.2** | critic **ITERATE** 판정, required_changes 6건 | 아래 6행 | 부록 B |
 | rev.2 / RC1 | 4번째 폴링(live roster 5s) 누락 | §2.1에 **C0** 행 신설(절 제목 «폴링 4종(타이머 5개)»), §2.4 유일 호출부 명시, §2.6 `R_live` 재계산, §6.2 grace 근거 재산정(2초→5초, lane별 분리), §7.1 제거 대상 추가, §7.3 assert A/B/G 재작성 + U16, §8 B15-3 확장, §8.1 잔상 상한표, 부록 A #3·#7, 부록 B |
@@ -224,6 +225,57 @@ R'(N) = (2 + S)/C_SCAN + c_live/C_SCAN                        # 수집기 1개,
 
 비책임: HTTP 응답 조립, authorization, tmux 쓰기, pane 캡처.
 
+### 4.1.1 Explicit local tmux socket inventory (rev.3, normative)
+
+- The owner MAY set `CHATMUX_TMUX_SOCKETS` in the existing server environment.
+  Its value MUST be a JSON array of **1–8** objects, each containing exactly one
+  `name` (`tmux -L`) or `path` (`tmux -S`). Names MUST match
+  `[A-Za-z0-9_][A-Za-z0-9_.-]{0,63}`; paths MUST be absolute, normalized, at most
+  4,096 UTF-8 bytes, and contain no control characters. The encoded inventory
+  MUST be at most 32 KiB. Invalid or duplicate entries MUST fail closed as a
+  whole; invalid configuration MUST NOT fall back to the default server.
+- An unset or empty value MUST preserve the existing unqualified `tmux`
+  discovery behavior, including tmux's inherited environment selection. An
+  explicit inventory replaces that implicit selection: the owner MUST include
+  `{"name":"default"}` when that server is wanted. No filesystem enumeration,
+  shell evaluation, glob expansion, automatic server/session/agent creation, or
+  client-supplied inventory is allowed. `-L` uses the service account UID and
+  tmux's `TMUX_TMPDIR` (or `/tmp`), independent of inherited `TMUX`.
+- The host capture MUST inspect at most K configured sockets (`1 <= K <= 8`)
+  and take **one shared `ps` roster** per full capture. A lightweight capture
+  MUST run at most K `list-panes` commands and no `ps`. Each child MUST have a
+  timeout and output bound; cancellation MUST stop only collector children.
+  Filesystem waits MUST have a logical deadline and cancellation; uncancellable
+  underlying work MUST remain globally bounded until completion. Superseded
+  capture generations MUST drain before a new inventory capture starts.
+  Cost is O(K + host processes), independent of browser count N. The original
+  §7 single-socket bounds are the K=1 case; multiply only its `list-panes` term
+  by K. The existing single collector and in-flight sharing remain mandatory.
+- Inventory membership and exact socket-qualified pane identity MUST be reused
+  by collection and fresh actions. Equal session/window/pane IDs on different
+  sockets MUST stay distinct through `tmuxPaneIdentityKey`. A matching cwd,
+  label, pane ID, old display row, or another healthy socket MUST NOT authorize
+  an action. Every explicit socket MUST be an owner-owned Unix socket; symlink
+  leaves, changed filesystem identity during inspection, reported socket
+  mismatches and inaccessible sockets MUST fail closed. Request-time actions
+  MUST recheck that the exact socket remains in the explicit inventory and
+  retain existing pane/process/provider generation checks. Filesystem evidence
+  is server-private and MUST NOT become a browser credential.
+- Capture results MUST keep successful socket evidence separate from failed
+  sockets. Failed sockets yield **no fresh panes**, and unavailable MUST NOT
+  mean confirmed empty. A partial capture MUST report aggregate `ok: false`;
+  current lane adapters MAY conservatively retain the complete prior display
+  snapshot until a complete capture succeeds. This can delay healthy-socket
+  display updates and fresh actions during an outage, but MUST NOT erase their
+  prior rows, manufacture stale action targets, or reset missing-row grace as
+  if failed sockets had succeeded. Fresh captures MUST never contain retained
+  panes. A successful zero-pane capture is distinct from a failed command.
+- Per-socket outcomes, configuration, resolved paths, ownership/inode evidence,
+  and raw command failures MUST remain server-private. Public diagnostics MAY
+  expose bounded counts and closed reason codes only, never socket names,
+  paths, argv, labels, or exception text. Fleet descriptors and host-qualified
+  action routing remain governed by the existing Fleet RFC.
+
 ### 4.2 스냅샷 구조체
 
 ```ts

docs/TMUX-DISCOVERY.md

@@ -0,0 +1,106 @@
+# Explicit local tmux sockets
+
+ChatMux can discover coding-agent panes across a small, owner-configured set of
+local tmux servers. With `CHATMUX_TMUX_SOCKETS` unset or empty, it keeps the existing
+unqualified `tmux list-panes` selection, including inherited tmux environment
+behavior. It does not search socket directories or create tmux servers or agents.
+
+## Configuration
+
+Set `CHATMUX_TMUX_SOCKETS` in the existing server environment: the checkout's `.env`
+for development, or the managed installation's `chatmux.env` selected by
+`CHATMUX_ENV_FILE`. Restart ChatMux to load an edited environment file. Existing
+tmux sessions continue running independently.
+
+```dotenv
+CHATMUX_TMUX_SOCKETS=[{"name":"default"},{"name":"work"},{"path":"/run/user/1000/agents.sock"}]
+```
+
+The example is an environment-file line with an unquoted JSON value, accepted by
+both the managed runtime and Node’s development environment-file loader. For a
+shell `export`, quote the whole JSON value with single quotes.
+
+The value is one JSON array. Every entry has exactly one field:
+
+| Entry | Selection | Requirements |
+|---|---|---|
+| `{"name":"work"}` | `tmux -L work` | 1–64 ASCII letters, digits, `_`, `.`, `-`; first character must be a letter, digit or `_` |
+| `{"path":"/absolute/agents.sock"}` | `tmux -S /absolute/agents.sock` | Absolute, normalized path, at most 4,096 UTF-8 bytes; no control characters |
+
+An explicit list **replaces** the implicit selection. Include `{"name":"default"}`
+if that server should remain visible. There must be 1–8 entries and at most 32 KiB
+of encoded configuration. Empty arrays, malformed JSON, extra fields, duplicate
+entries and names resolving to the same path as another entry are rejected as a
+whole. Invalid configuration does not fall back to another server.
+
+Named sockets use the service account's UID and `TMUX_TMPDIR`, or `/tmp` when that
+variable is unset. `TMUX_TMPDIR` must identify an existing absolute directory;
+path lists, tilde expansion and custom compiled socket-directory layouts are not
+inferred. Use an exact `path` entry for those layouts. Explicit selection ignores
+inherited `TMUX` for choosing a server.
+
+The existing Unix socket must belong to the account running ChatMux. Socket files
+and their paths must be canonical: symlink socket leaves or symlink path aliases
+are refused. A missing socket, permissions failure, unexpected reported socket
+path, or socket replacement during inspection makes that entry unavailable.
+Nothing creates or repairs sockets automatically.
+
+## Identity and failures
+
+The existing `socketPath + sessionId + windowId + paneId` identity is preserved.
+Two servers can both have `$0/@0/%0` and a session named `work`; those are different
+panes. Synthetic idle GJC row IDs use a SHA-256 digest of length-prefixed UTF-8
+fields from that complete identity and retain
+the `idle-gjc:` prefix, so equal labels and pane IDs cannot overwrite each other.
+This changes temporary idle row IDs once on upgrade; provider transcript IDs do
+not change. Working-directory matches never authorize actions.
+
+Each capture records separate, server-private outcomes for the configured sockets.
+A failed socket contributes no fresh panes. If any socket fails, aggregate
+freshness is unavailable. The current external/live adapters conservatively
+retain the previous display rows for the entire lane; the existing lane health
+policy reports sustained failure after 30 failed ticks. Healthy-socket display
+updates and fresh agent actions can therefore be delayed until every configured
+socket is readable again. Missing sockets are not reported as confirmed session
+termination. A successful empty capture is different: normal missing-row grace
+can remove old rows.
+
+Retained rows cannot authorize fresh actions or mint new shell/SSH attach
+capabilities. Actions recheck exact inventory membership and current socket
+ownership/filesystem generation along with the existing pane, process and provider
+checks. Socket evidence follows verified targets, attach capabilities and cached
+terminal leases only in server memory. Reconnecting a leased terminal rechecks its
+original pane generation, socket ownership and inventory membership before replay
+or PTY adoption. A matching lease can outlive the initial capability's expiry;
+missing or changed proof refuses the reconnect without stopping the tmux jobs.
+Replacing a socket at the same path, even with matching pane IDs, invalidates old
+targets and leases. Existing tmux multi-command operations still have their
+documented race between the final check and command execution; this feature does
+not make those operations atomic.
+
+## Cost, privacy and verification
+
+A shared full host capture starts at most K `tmux list-panes` commands and one
+`ps` command, where K is the configured socket count. A lightweight presence
+capture starts at most K tmux commands and no `ps`. The existing collector and
+in-flight sharing keep discovery cost independent of browser count. Each
+observation child has a four-second timeout and an 8 MiB output bound. Cancellation
+terminates only those observation children. Filesystem waits also have a four-second
+logical deadline and support cancellation. At most 16 filesystem operations may
+remain outstanding; timed-out syscalls retain their slots until they actually
+finish. Captures from a changed configuration drain before another generation
+starts, so configuration churn cannot multiply concurrent capture commands.
+
+Configuration, raw selector values, socket outcomes and filesystem evidence are
+server-private. Public diagnostics retain closed codes and counts; command
+metrics count `tmux list-panes` without storing `-L`/`-S` values. Fleet descriptors
+and host routing follow the existing Fleet contract.
+
+The normative contract is [P2 RFC §4.1.1](P2-DISCOVERY-STREAM-RFC.md#411-explicit-local-tmux-socket-inventory-rev3-normative).
+Selector behavior was checked against upstream tmux 3.5a's `tmux(1)` options and
+`tmux.c:make_label`, then exercised with isolated real tmux 3.5a servers. Focused
+regressions live in `host-discovery-snapshot.service.test.ts`,
+`local-tmux-discovery.service.test.ts`, and `explicit-tmux-sockets.test.ts` under
+`server/modules/providers/tests/`. They cover duplicate IDs, partial failure and
+retention, configuration rejection/change, unavailable ownership evidence,
+replacement, fresh-action/capability refusal, bounded output, and cancellation.

server/modules/providers/index.ts

@@ -38,6 +38,7 @@ export {
   attachCapabilityService,
   createAttachCapabilityService,
   type AttachCapabilityService,
+  type TmuxAttachLease,
 } from './services/attach-capability.service.js';
 export {
   getCurrentTmuxPaneIdentity,

server/modules/providers/provider.routes.ts

@@ -925,6 +925,7 @@ router.get(
         connectionIssue: session.connectionIssue,
       };
       if (session.kind === 'ssh' || session.kind === 'shell') {
+        if (!result.ok) return base;
         const attachCapability = await attachCapabilityService.issue(
           String((req as typeof req & { user?: { id?: string | number } }).user?.id),
           session.tmux,

server/modules/providers/services/attach-capability.service.ts

@@ -2,6 +2,7 @@ import { randomBytes } from 'node:crypto';
 
 import type { TmuxPaneIdentity } from '../../../../shared/tmux.js';
 
+import { assertLocalTmuxSocket, copyLocalTmuxSocketEvidence, rememberLocalTmuxSocket, sameLocalTmuxSocket, type LocalTmuxSocketInspector } from './local-tmux-discovery.service.js';
 import { runTmux } from './builtin-relay.service.js';
 
 const ATTACH_CAPABILITY_TTL_MS = 60_000;
@@ -16,20 +17,29 @@ type AttachCapabilityRecord = Readonly<{
   expiresAtMs: number;
 }>;
 
+/** Server-only lease handle. Generation/ownership proof lives in the issuer's WeakMap. */
+export type TmuxAttachLease = Readonly<{
+  principal: string;
+  tmux: Readonly<TmuxPaneIdentity>;
+}>;
+
 export type AttachCapabilityService = Readonly<{
   issue: (principal: string, tmux: TmuxPaneIdentity) => Promise<string | null>;
   verify: (token: unknown, principal: string, tmux: TmuxPaneIdentity) => Promise<boolean>;
+  createLease: (token: unknown, principal: string, tmux: TmuxPaneIdentity) => Promise<TmuxAttachLease | null>;
+  verifyLease: (lease: unknown, principal: string, tmux: TmuxPaneIdentity) => Promise<boolean>;
   size: () => number;
 }>;
 
 export async function readTmuxPaneGeneration(tmux: TmuxPaneIdentity): Promise<string | null> {
   const result = await runTmux([
     '-S', tmux.socketPath,
     'display-message', '-p', '-t', tmux.paneId,
-    '#{pane_pid}',
+    '#{session_id}\t#{window_id}\t#{pane_id}\t#{pane_pid}',
   ]);
-  const generation = result.output.trim();
-  return result.code === 0 && generation ? generation : null;
+  const [sessionId, windowId, paneId, generation] = result.output.trim().split('\t');
+  return result.code === 0 && sessionId === tmux.sessionId && windowId === tmux.windowId
+    && paneId === tmux.paneId && /^\d+$/.test(generation ?? '') ? generation : null;
 }
 
 function samePane(a: TmuxPaneIdentity, b: TmuxPaneIdentity): boolean {
@@ -48,15 +58,27 @@ function paneKey(principal: string, tmux: TmuxPaneIdentity): string {
  * service (including on server restart) intentionally invalidates every token.
  */
 export function createAttachCapabilityService(
-  options: Readonly<{ now?: () => number; ttlMs?: number; maxRecords?: number; readPaneGeneration?: PaneGenerationReader }> = {},
+  options: Readonly<{ now?: () => number; ttlMs?: number; maxRecords?: number; readPaneGeneration?: PaneGenerationReader; socketInspector?: LocalTmuxSocketInspector }> = {},
 ): AttachCapabilityService {
   const records = new Map<string, AttachCapabilityRecord>();
+  // Leases follow cached PTY lifetime, independently of token expiry/eviction.
+  // Copying or deserializing a handle cannot recreate its private authority.
+  const leases = new WeakMap<TmuxAttachLease, AttachCapabilityRecord>();
   const activeTokens = new Map<string, string>();
   const now = options.now ?? Date.now;
   const ttlMs = options.ttlMs ?? ATTACH_CAPABILITY_TTL_MS;
   const maxRecords = options.maxRecords ?? MAX_ATTACH_CAPABILITIES;
   const readPaneGeneration = options.readPaneGeneration ?? readTmuxPaneGeneration;
 
+  const readCheckedGeneration = async (tmux: TmuxPaneIdentity): Promise<string | null> => {
+    const before = await assertLocalTmuxSocket(tmux, process.env, options.socketInspector);
+    const generation = await readPaneGeneration(tmux);
+    const after = await assertLocalTmuxSocket(tmux, process.env, options.socketInspector);
+    if (before && (!after || !sameLocalTmuxSocket(before, after))) return null;
+    if (after) rememberLocalTmuxSocket(tmux, after);
+    return generation && after ? `${generation}\0${after.generation}` : generation;
+  };
+
   const remove = (token: string, record = records.get(token)): void => {
     if (!record) return;
     records.delete(token);
@@ -77,12 +99,31 @@ export function createAttachCapabilityService(
     }
   };
 
+  const verifiedRecord = async (token: unknown, principal: string, tmux: TmuxPaneIdentity): Promise<AttachCapabilityRecord | null> => {
+    pruneExpired();
+    if (typeof token !== 'string') return null;
+    const record = records.get(token);
+    if (!record || record.principal !== principal || !samePane(record.tmux, tmux)) return null;
+    try {
+      const generation = await readCheckedGeneration(record.tmux);
+      if (record.expiresAtMs <= now()) {
+        remove(token, record);
+        return null;
+      }
+      // A concurrent issue() may supersede this token while inspection waits.
+      if (records.get(token) !== record || activeTokens.get(paneKey(principal, tmux)) !== token) return null;
+      return generation === record.generation ? record : null;
+    } catch {
+      return null;
+    }
+  };
+
   return Object.freeze({
     async issue(principal, tmux) {
       pruneExpired();
       let generation: string | null;
       try {
-        generation = await readPaneGeneration(tmux);
+        generation = await readCheckedGeneration(tmux);
       } catch {
         return null;
       }
@@ -95,37 +136,33 @@ export function createAttachCapabilityService(
       if (previous) remove(previous);
       enforceLimit();
       const token = randomBytes(32).toString('base64url');
+      const identity = Object.freeze({ ...tmux });
+      copyLocalTmuxSocketEvidence(tmux, identity);
       records.set(token, Object.freeze({
         principal,
-        tmux: Object.freeze({ ...tmux }),
+        tmux: identity,
         generation,
         expiresAtMs: now() + ttlMs,
       }));
       activeTokens.set(key, token);
       return token;
     },
     async verify(token, principal, tmux) {
-      pruneExpired();
-      if (typeof token !== 'string') return false;
-      const record = records.get(token);
-      if (!record || record.principal !== principal || !samePane(record.tmux, tmux)) {
-        return false;
-      }
-
+      return await verifiedRecord(token, principal, tmux) !== null;
+    },
+    async createLease(token, principal, tmux) {
+      const record = await verifiedRecord(token, principal, tmux);
+      if (!record) return null;
+      const lease = Object.freeze({ principal: record.principal, tmux: record.tmux });
+      leases.set(lease, record);
+      return lease;
+    },
+    async verifyLease(lease, principal, tmux) {
+      if (!lease || typeof lease !== 'object') return false;
+      const record = leases.get(lease as TmuxAttachLease);
+      if (!record || record.principal !== principal || !samePane(record.tmux, tmux)) return false;
       try {
-        const generation = await readPaneGeneration(tmux);
-        if (record.expiresAtMs <= now()) {
-          remove(token, record);
-          return false;
-        }
-        // A concurrent issue() may have observed a newer pane generation and
-        // superseded this token while the read was pending. Accepting the stale
-        // snapshot would revive a revoked capability, so re-assert that this
-        // record is still the active one for its principal and pane.
-        if (records.get(token) !== record || activeTokens.get(paneKey(principal, tmux)) !== token) {
-          return false;
-        }
-        return generation === record.generation;
+        return await readCheckedGeneration(record.tmux) === record.generation;
       } catch {
         return false;
       }