feat(runtime): optional dedicated tmux socket (LARKIN_TMUX_SOCKET) for pi tasks

[itswl]

What

Larkin's pi tmux tool created every task session on the user's default tmux server (tmuxClientEnv only strips TMUX/TMUX_PANE/BASH_ENV; new-session passed no -L/-S). Two consequences observed on a real machine:

• every task advanced the user's session-id counter — tmux never reuses ids, so after five larkin tasks a fresh user session landed on 108 next to their 0/35 (measured; cosmetic but confusing), and
• larkin's running tasks shared tmux kill-server's blast radius with unrelated work — the server going away also silences the completion watch.

Filed as #229.

Change

• src/runtime/pi-tmux.ts: LARKIN_TMUX_SOCKET (a tmux socket name, validated ^[A-Za-z0-9._-]{1,64}$; an invalid value fails loudly instead of silently falling back) makes every tmux client call carry -L <name> — the availability probe, has-session, kill-session, list-panes and new-session. Unset keeps the default server, i.e. today's behavior byte for byte.
• src/runtime/pi-tmux-extension.ts: when a socket is configured, tool results for a still-running task append attach: tmux -L <name> attach -t =<session>, so the tasks stay observable; completion notifications and tmux list stay hint-free (a finished session no longer exists to attach to).
• tmuxSessionName is exported (the extension needs the same session name for the hint) and formatTmuxTaskText takes an optional { attachHint } — both additive.

Validation

• bun test test/unit/runtime/pi-tmux-socket.test.mjs → 3 pass / 0 fail: socket-name validation (blank = unset, invalid values throw), attach-hint rendering, and a real-tmux isolation proof — with the socket set, a running task's session exists on tmux -L <name> and not on the default server; the same task's completion status and output are unchanged; cleanup via kill-server (verified: the machine's default server still lists exactly the same two sessions after the run).
• bun test test/unit/runtime/ → 240 pass / 0 fail (existing pi-tmux suites unchanged).
• bun run build ✅ · bun run typecheck ✅ · bun run licenses:check ✅ · bun run publication:check:tree ✅

Lands ahead of maintainer alignment on #229 — happy to change the shape (e.g. -S <path> instead of -L <name>, or always-on isolation) or split the hint.

Fixes #229

🤖 Generated with Claude Code

[eddiearc]

Fable 5.1 review（head 50950e2）

Verdict: REQUEST_CHANGES — 唯一阻塞项是机械性的。

阻塞

• AGENTS.md Owner 政策：每次交付必须 bump package.json patch。本 PR 仍为 0.5.9，请改为 0.5.9 → 0.5.10（若与 #226 同批合入，由 maintainer 排版本序号）。

代码本身 ✅

• 未设 LARKIN_TMUX_SOCKET 时 argv/输出与现状一致（零行为变化）
• ^[A-Za-z0-9._-]{1,64}$ + spawnSync 数组 argv：无路径逃逸 / 参数注入；多 Agent 隔离不依赖 tmux server
• 实机隔离测试：会话只在 -L <name>，默认 server 看不到；生命周期不变
• test/unit/runtime/ 240 pass；新测 3/3；CI 已绿

Nits（非阻塞，可同 PR 或 follow-up）

1. 显式拒绝 . / ..（正则放过，第一次 new-session 才炸）
2. attach: 建议仅 status === "running" 时附加（完成后会话已不存在）
3. attach 目标建议 -t =<session> 与其余调用一致
4. README 的 tmux list-sessions 恢复指引补一句 -L <name>（开启时）
5. 扩展层 attach: / list 无 hint 可加一条单元断言

合入仍等 idan 明确 yes。

[itswl]

阻塞项与五个 nit 都已处理（head 更新为 6bd2785）：

• 阻塞：版本 已 bump 0.5.9 → 0.5.10（bun run version:bump patch）；若与 feat(setup): report optional-scope impacts instead of scope names alone #226 同批合入，序号由你们排。
• nit 1：LARKIN_TMUX_SOCKET 显式拒绝 . / ..（校验里加判 + 单测断言两条）。
• nit 2：attach: 仅在 status === "running" 时附加（完成后会话已不存在，不再误导）。
• nit 3：attach 目标改为 -t =<session>，与其余 tmux 调用一致。
• nit 4：README 的 tmux 恢复指引补了"设置 LARKIN_TMUX_SOCKET 时前缀 tmux -L <name>"。
• nit 5：扩展层新增单测（pi-tmux-extension.test.mjs）：运行中任务的结果带 attach: tmux -L <name> attach -t =lkn-…；tmux list 不带 hint；被 kill 的任务不再带 hint。

验证：tmux 相关五个测试文件 30 pass / 0 fail；build / typecheck 通过。（release:check-version 需要 vX.Y.Z 参数，是发布期脚本，本地未作为门禁运行。）

[eddiearc]

Fable 5.1 re-review（head 6bd2785）

Verdict: APPROVE_WITH_NITS

上轮 REQUEST_CHANGES 五项全部落实：

1. ✅ package.json 0.5.9 → 0.5.10
2. ✅ tmuxSocketName 配置期拒 . / ..
3. ✅ attach: 仅 status === "running"，且 -t =<session>
4. ✅ README 补 tmux -L <name>
5. ✅ 扩展层测试：running 有 hint / list 无 / kill 后无

未设 env 零变化；-L 名称安全；本地 runtime 单元 241 绿；CI 绿。

Nits（非阻塞）：notifyOnce/kill 上 attachHintFor 恒 null 可简化；PR 描述仍写 completion 带 attach，建议改一句。

合入仍等 idan 明确 yes。 若与 #226/#231 同批，版本序号由 maintainer 排。