pi-tmux-bridge 0.1.0

package/README.md

@@ -0,0 +1,26 @@
+# pi-tmux-bridge
+
+A pi extension that feeds this terminal's tmux state from a running pi session — a status line reflecting model and context usage, an attention bell on the pane's own tty, and session-bus (muster) registration — so a pi session presents in tmux the way a harnessed coding session should.
+
+## What it does
+
+- **Status.** On session start and as context fills, writes per-pane state (`src/state.ts`) that a tmux status line can render (model, context %). Removed again on shutdown.
+- **Attention.** Rings the bell (`src/bell.ts`) on *this* pane's tty only — never every same-directory session — lighting tmux's attention banner / window indicator and the terminal's tab bell.
+- **Bus.** Registers the session with a lightweight muster bus (`src/muster.ts`) at start, drains queued messages on settle, and deregisters at end.
+- **tmux resolution.** `src/tmux.ts` resolves the current socket/pane/session and sanitizes the session id before it reaches tmux (it is later used to build file paths).
+
+Every handler is best-effort: it sits directly on a pi lifecycle event, and a harness that fails a session start, a turn, or a shutdown over a status bar or a bus registration is worse than no harness at all.
+
+## Install
+
+```sh
+pi install npm:pi-tmux-bridge
+```
+
+## Tests
+
+```sh
+node --test src/*.test.ts
+```
+
+The pure tmux/state/bell/muster logic is unit-tested against injectable stand-ins for tmux and the shell, and `src/index.test.ts` exercises the wired lifecycle against a fake pi.

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "pi-tmux-bridge",
+  "version": "0.1.0",
+  "description": "A pi coding-agent extension that feeds this terminal's tmux state (status bar, attention bell, session bus) from a pi session.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/schuettc/pi-extensions.git",
+    "directory": "packages/pi-tmux-bridge"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "tmux",
+    "harness",
+    "status-bar"
+  ],
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --test src/*.test.ts"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.3",
+    "typescript": "^5.6.0"
+  }
+}

package/src/bell.test.ts

@@ -0,0 +1,38 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { ringBell, raiseAttention } from "./bell.ts";
+
+const ctx = { socket: "proj-pi", pane: "%47" };
+const BEL = String.fromCharCode(7);
+
+test("the bell is a BEL byte appended to the pane's own tty", () => {
+  const writes: Array<{ path: string; data: string }> = [];
+  ringBell(ctx, { tty: () => "/dev/ttys004", append: (path, data) => writes.push({ path, data }) });
+  assert.deepEqual(writes, [{ path: "/dev/ttys004", data: BEL }]);
+});
+
+test("no tty means no write, and no throw", () => {
+  const writes: string[] = [];
+  ringBell(ctx, { tty: () => undefined, append: (p) => writes.push(p) });
+  assert.deepEqual(writes, []);
+});
+
+test("a failing write is swallowed — a bell must not fail a turn", () => {
+  assert.doesNotThrow(() =>
+    ringBell(ctx, { tty: () => "/dev/ttys004", append: () => { throw new Error("gone"); } }),
+  );
+});
+
+test("attention calls claude-attn raise with the SESSION, not a pid", () => {
+  const calls: Array<{ cmd: string; args: string[] }> = [];
+  raiseAttention(ctx, { session: () => "pi-97", run: (cmd, args) => calls.push({ cmd, args }) });
+  assert.equal(calls.length, 1);
+  assert.match(calls[0].cmd, /claude-attn$/);
+  assert.deepEqual(calls[0].args, ["raise", "pi-97"]);
+});
+
+test("an unresolvable session raises nothing rather than raising the wrong thing", () => {
+  const calls: string[] = [];
+  raiseAttention(ctx, { session: () => undefined, run: (cmd) => calls.push(cmd) });
+  assert.deepEqual(calls, []);
+});

package/src/bell.ts

@@ -0,0 +1,55 @@
+import { appendFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { ttyOfPane, sessionOfPane } from "./tmux.ts";
+import type { TmuxContext } from "./tmux.ts";
+
+const ATTN = join(homedir(), ".local", "bin", "claude-attn");
+const BEL = String.fromCharCode(7);
+
+// The bell lights tmux's status-left attention banner, the window indicator,
+// and Ghostty's tab bell and border. It goes to THIS pane's tty and nowhere
+// else: ringing every same-directory session is worse than ringing none.
+export function ringBell(
+  ctx: TmuxContext,
+  deps: {
+    tty?: (socket: string, pane: string) => string | undefined;
+    append?: (path: string, data: string) => void;
+  } = {},
+): void {
+  const readTty = deps.tty ?? ttyOfPane;
+  const write = deps.append ?? ((path: string, data: string) => appendFileSync(path, data));
+  try {
+    const tty = readTty(ctx.socket, ctx.pane);
+    if (!tty) return;
+    write(tty, BEL);
+  } catch {
+    // Best-effort: a bell must not fail a turn.
+  }
+}
+
+// `claude-attn raise <session>` takes a session directly. raise-pid exists only
+// because a Claude Code hook cannot know its own pane and must walk process
+// ancestry to find it; we know ours. claude-attn is NOT modified.
+export function raiseAttention(
+  ctx: TmuxContext,
+  deps: {
+    session?: (socket: string, pane: string) => string | undefined;
+    run?: (cmd: string, args: string[]) => void;
+  } = {},
+): void {
+  const readSession = deps.session ?? sessionOfPane;
+  const run =
+    deps.run ??
+    ((cmd: string, args: string[]) => {
+      execFileSync(cmd, args, { stdio: "ignore" });
+    });
+  try {
+    const session = readSession(ctx.socket, ctx.pane);
+    if (!session) return;
+    run(ATTN, ["raise", session]);
+  } catch {
+    // Best-effort: an attention flag must not fail a turn.
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,499 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createHarness } from "./index.ts";
+
+type Handler = (event: unknown, ctx: unknown) => unknown;
+
+function fakePi() {
+  const handlers = new Map<string, Handler[]>();
+  const sent: Array<{ message: unknown; options: unknown }> = [];
+  const pi = {
+    on(event: string, handler: Handler) {
+      handlers.set(event, [...(handlers.get(event) ?? []), handler]);
+    },
+    sendMessage(message: unknown, options?: unknown) {
+      sent.push({ message, options });
+    },
+  };
+  const ctx = {
+    mode: "tui",
+    sessionManager: { getSessionId: () => "sess-1" },
+    cwd: "/work/proj",
+    model: { id: "Qwen3.8-27B" },
+    getContextUsage: () => ({ tokens: 12000, contextWindow: 32000, percent: 37 }),
+    ui: { setStatus: () => {} },
+  };
+  async function fire(event: string, payload: unknown = {}, overrideCtx?: unknown) {
+    const out: unknown[] = [];
+    for (const h of handlers.get(event) ?? []) out.push(await h(payload, overrideCtx ?? ctx));
+    return out;
+  }
+  return { pi, ctx, fire, events: () => [...handlers.keys()], sent };
+}
+
+// A tmux address that cannot collide with a real server or pane on the
+// operator's machine: no `-L harness-test` server exists and `%999999` is far
+// past any live pane id. Combined with injecting writeState/ringBell/runTmux in
+// every test that would otherwise reach a default, the suite touches no real
+// tmux server and no real state file.
+const ctxTmux = { socket: "harness-test", pane: "%999999" };
+const noopTmux = (_s: string, _a: string[]) => undefined;
+const noopBell = (_c: unknown) => {};
+
+test("it subscribes to exactly the lifecycle events it needs", async () => {
+  const { pi, events } = fakePi();
+  createHarness(pi as never, { raiseAttention: noopBell, tmux: () => ctxTmux });
+  const subscribed = events().sort();
+  assert.deepEqual(subscribed, [
+    "agent_settled", "session_info_changed", "session_shutdown", "session_start", "turn_end",
+  ].sort());
+});
+
+test("session_start stamps the tmux session option and calls the SessionStart hook", async () => {
+  const { pi, fire } = fakePi();
+  const stamps: string[][] = [];
+  const musterCalls: Array<{ args: string[]; input: string }> = [];
+  createHarness(pi as never, { raiseAttention: noopBell,
+    tmux: () => ctxTmux,
+    runTmux: (_s, args) => { stamps.push(args); return undefined; },
+    runMuster: (_c, args, input) => { musterCalls.push({ args, input }); return ""; },
+  });
+  await fire("session_start", { reason: "startup" });
+  assert.ok(stamps.some((a) => a.includes("@harness_session") && a.includes("sess-1")),
+    `expected a @harness_session stamp, got ${JSON.stringify(stamps)}`);
+  const hookCall = musterCalls.find((c) => c.args[1] === "SessionStart");
+  assert.ok(hookCall, "expected a hook SessionStart pi call");
+  assert.deepEqual(JSON.parse(hookCall.input), { session_id: "sess-1", cwd: "/work/proj", source: "startup" });
+});
+
+test("a resume or fork reason passes source: resume to the SessionStart hook", async () => {
+  for (const reason of ["resume", "fork"]) {
+    const { pi, fire } = fakePi();
+    const musterCalls: Array<{ input: string }> = [];
+    createHarness(pi as never, { raiseAttention: noopBell,
+      tmux: () => ctxTmux,
+      runTmux: noopTmux,
+      runMuster: (_c, _a, input) => { musterCalls.push({ input }); return ""; },
+    });
+    await fire("session_start", { reason });
+    assert.equal(JSON.parse(musterCalls[0].input).source, "resume", `reason ${reason} should map to source: resume`);
+  }
+});
+
+test("session_start injects non-empty SessionStart stdout, triggering a turn only when it mentions unread mail", async () => {
+  const { pi, fire, sent } = fakePi();
+  createHarness(pi as never, { raiseAttention: noopBell,
+    tmux: () => ctxTmux,
+    runTmux: noopTmux,
+    runMuster: () => "muster: reconnected as 'pi-97' (revived) — 2 unread thread(s); call get_inbox with alias 'pi-97'",
+  });
+  await fire("session_start", { reason: "resume" });
+  assert.equal(sent.length, 1);
+  assert.match(String((sent[0].message as { content: string }).content), /unread/);
+  assert.deepEqual(sent[0].options, { triggerTurn: true });
+});
+
+test("session_start does not inject when SessionStart stdout is empty", async () => {
+  const { pi, fire, sent } = fakePi();
+  createHarness(pi as never, { raiseAttention: noopBell, tmux: () => ctxTmux, runTmux: noopTmux, runMuster: () => "" });
+  await fire("session_start", { reason: "startup" });
+  assert.deepEqual(sent, []);
+});
+
+test("session_start injects a plain registration line without triggering a turn", async () => {
+  const { pi, fire, sent } = fakePi();
+  createHarness(pi as never, { raiseAttention: noopBell, tmux: () => ctxTmux, runTmux: noopTmux, runMuster: () => "muster: registered as 'pi-97'" });
+  await fire("session_start", { reason: "startup" });
+  assert.equal(sent.length, 1);
+  assert.deepEqual(sent[0].options, { triggerTurn: false });
+});
+
+test("turn_end writes the state file", async () => {
+  const { pi, fire } = fakePi();
+  const written: Array<{ pct: number; model: string }> = [];
+  createHarness(pi as never, { raiseAttention: noopBell,
+    tmux: () => ctxTmux,
+    writeState: (o) => written.push({ pct: o.contextPct, model: o.model }),
+    ringBell: noopBell,
+  });
+  await fire("turn_end", {});
+  assert.deepEqual(written, [{ pct: 37, model: "Qwen3.8-27B" }]);
+});
+
+test("turn_end skips the write when getContextUsage returns undefined, but still rings the bell path", async () => {
+  const { pi, fire } = fakePi();
+  const written: unknown[] = [];
+  createHarness(pi as never, { raiseAttention: noopBell, tmux: () => ctxTmux, writeState: (o) => written.push(o), ringBell: noopBell });
+  const ctx = {
+    mode: "tui",
+    sessionManager: { getSessionId: () => "sess-1" },
+    cwd: "/work/proj",
+    model: { id: "Qwen3.8-27B" },
+    getContextUsage: () => undefined,
+    ui: { setStatus: () => {} },
+  };
+  await fire("turn_end", {}, ctx);
+  assert.deepEqual(written, [], "an unknown usage must not fabricate a state write");
+});
+
+test("turn_end skips the write when percent is null (fresh post-compaction)", async () => {
+  const { pi, fire } = fakePi();
+  const written: unknown[] = [];
+  createHarness(pi as never, { raiseAttention: noopBell, tmux: () => ctxTmux, writeState: (o) => written.push(o), ringBell: noopBell });
+  const ctx = {
+    mode: "tui",
+    sessionManager: { getSessionId: () => "sess-1" },
+    cwd: "/work/proj",
+    model: { id: "Qwen3.8-27B" },
+    getContextUsage: () => ({ tokens: null, contextWindow: 32000, percent: null }),
+    ui: { setStatus: () => {} },
+  };
+  await fire("turn_end", {}, ctx);
+  assert.deepEqual(written, [], "a null percent must not be written as a fabricated 0");
+});
+
+// The state write and the bell are independent notifications that happen to
+// share turn_end. A throw in getContextUsage/writeState (or a missing
+// ctx.model) must not suppress the bell for that turn.
+test("a throwing writeState does not suppress the bell", async () => {
+  const { pi, fire } = fakePi();
+  const bellCalls: unknown[] = [];
+  createHarness(pi as never, { raiseAttention: noopBell,
+    tmux: () => ctxTmux,
+    writeState: () => { throw new Error("disk full"); },
+    ringBell: (ctx) => bellCalls.push(ctx),
+  });
+  await fire("turn_end", {});
+  assert.equal(bellCalls.length, 1, "the bell must still ring when writeState throws");
+});
+
+test("the drain runs on agent_settled and NOT on turn_end", async () => {
+  const { pi, fire } = fakePi();
+  const musterCalls: Array<{ args: string[] }> = [];
+  createHarness(pi as never, { raiseAttention: noopBell,
+    tmux: () => ctxTmux,
+    runTmux: noopTmux,
+    writeState: () => {},
+    ringBell: noopBell,
+    runMuster: (_c, args) => { musterCalls.push({ args }); return ""; },
+  });
+  await fire("turn_end", {});
+  assert.ok(!musterCalls.some((c) => c.args[1] === "Stop"), "turn_end must not drain");
+  await fire("agent_settled", {});
+  assert.ok(musterCalls.some((c) => c.args[1] === "Stop"), "agent_settled must drain");
+});
+
+test("drain injects the block reason and passes stop_hook_active on the settle", async () => {
+  const { pi, fire, sent } = fakePi();
+  const inputs: string[] = [];
+  createHarness(pi as never, { raiseAttention: noopBell,
+    tmux: () => ctxTmux,
+    runMuster: (_c, _a, input) => {
+      inputs.push(input);
+      return JSON.stringify({ decision: "block", reason: "You have 2 unread threads" });
+    },
+  });
+  await fire("agent_settled", {});
+  assert.equal(JSON.parse(inputs[0]).stop_hook_active, false);
+  assert.equal(sent.length, 1);
+  assert.equal((sent[0].message as { content: string }).content, "You have 2 unread threads");
+  assert.deepEqual(sent[0].options, { triggerTurn: true });
+});
+
+// This is the assertion the drain-loop guard exists for: injecting a reason
+// starts a turn, which produces another settle. Without tracking that WE
+// triggered it, that settle re-drains, sees the same unread mail, and
+// injects again — forever, for as long as mail stays unread. Two consecutive
+// settles with mail waiting must call drain twice, pass stop_hook_active:
+// true on the second, and inject exactly once.
+test("the loop guard: two consecutive settles with mail waiting drain twice but inject only once", async () => {
+  const { pi, fire, sent } = fakePi();
+  const inputs: string[] = [];
+  createHarness(pi as never, { raiseAttention: noopBell,
+    tmux: () => ctxTmux,
+    runMuster: (_c, _a, input) => {
+      inputs.push(input);
+      return JSON.stringify({ decision: "block", reason: "You have 2 unread threads" });
+    },
+  });
+  await fire("agent_settled", {});
+  await fire("agent_settled", {});
+  assert.equal(inputs.length, 2, "drain must be called on every settle");
+  assert.equal(JSON.parse(inputs[0]).stop_hook_active, false, "first settle: we did not just trigger it");
+  assert.equal(JSON.parse(inputs[1]).stop_hook_active, true, "second settle: we triggered it via injection");
+  assert.equal(sent.length, 1, "must inject exactly once, not once per settle");
+});
+
+test("the loop guard resets once mail clears: a third settle with no reason re-arms it", async () => {
+  const { pi, fire, sent } = fakePi();
+  let call = 0;
+  createHarness(pi as never, { raiseAttention: noopBell,
+    tmux: () => ctxTmux,
+    runMuster: () => {
+      call += 1;
+      // Mail waiting for the first two settles, then cleared.
+      if (call <= 2) return JSON.stringify({ decision: "block", reason: "You have 2 unread threads" });
+      return "";
+    },
+  });
+  await fire("agent_settled", {}); // injects, flag -> true
+  await fire("agent_settled", {}); // flag true, still reason present -> skip, flag -> false
+  await fire("agent_settled", {}); // no reason -> nothing to inject regardless
+  assert.equal(sent.length, 1);
+});
+
+test("session_info_changed renames tmux and calls become with --no-inject", async () => {
+  const { pi, fire } = fakePi();
+  const tmuxCalls: string[][] = [];
+  const musterCalls: Array<{ args: string[] }> = [];
+  createHarness(pi as never, { raiseAttention: noopBell,
+    tmux: () => ctxTmux,
+    runTmux: (_s, a) => { tmuxCalls.push(a); return undefined; },
+    runMuster: (_c, args) => { musterCalls.push({ args }); return ""; },
+  });
+  await fire("session_info_changed", { name: "new-name" });
+  assert.ok(tmuxCalls.some((a) => a[0] === "rename-session"), "expected a tmux rename");
+  const becomeCall = musterCalls.find((c) => c.args[0] === "become");
+  assert.deepEqual(becomeCall?.args, ["become", "new-name", "--no-inject"]);
+});
+
+test("a bare /name keeps the session's project prefix, like prefix T", async () => {
+  const { pi, fire } = fakePi();
+  const tmuxCalls: string[][] = [];
+  const musterCalls: Array<{ args: string[] }> = [];
+  createHarness(pi as never, { raiseAttention: noopBell,
+    tmux: () => ctxTmux,
+    runTmux: (_s, a) => {
+      tmuxCalls.push(a);
+      return a[0] === "display-message" ? "proj/old-work" : undefined;
+    },
+    runMuster: (_c, args) => { musterCalls.push({ args }); return ""; },
+  });
+  await fire("session_info_changed", { name: "new-work" });
+  const rename = tmuxCalls.find((a) => a[0] === "rename-session");
+  assert.ok(rename?.includes("proj/new-work"), `expected proj/new-work, got ${JSON.stringify(rename)}`);
+  const becomeCall = musterCalls.find((c) => c.args[0] === "become");
+  assert.deepEqual(becomeCall?.args, ["become", "proj/new-work", "--no-inject"]);
+});
+
+test("a /name carrying '/' is taken verbatim: the re-homing escape hatch", async () => {
+  const { pi, fire } = fakePi();
+  const musterCalls: Array<{ args: string[] }> = [];
+  createHarness(pi as never, { raiseAttention: noopBell,
+    tmux: () => ctxTmux,
+    runTmux: (_s, a) => (a[0] === "display-message" ? "proj/old-work" : undefined),
+    runMuster: (_c, args) => { musterCalls.push({ args }); return ""; },
+  });
+  await fire("session_info_changed", { name: "other/work" });
+  const becomeCall = musterCalls.find((c) => c.args[0] === "become");
+  assert.deepEqual(becomeCall?.args, ["become", "other/work", "--no-inject"]);
+});
+
+test("muster's prefixed /name echo does not round-trip a second become", async () => {
+  const { pi, fire } = fakePi();
+  const musterCalls: Array<{ args: string[] }> = [];
+  createHarness(pi as never, { raiseAttention: noopBell,
+    tmux: () => ctxTmux,
+    runTmux: (_s, a) => (a[0] === "display-message" ? "proj/old-work" : undefined),
+    runMuster: (_c, args) => { musterCalls.push({ args }); return ""; },
+  });
+  await fire("session_info_changed", { name: "new-work" });
+  await fire("session_info_changed", { name: "proj/new-work" });
+  const becomeCalls = musterCalls.filter((c) => c.args[0] === "become");
+  assert.equal(becomeCalls.length, 1, "the composed-name echo must be recognized as our own rename");
+});
+
+test("a cleared name renames nothing rather than claiming an empty alias", async () => {
+  const { pi, fire } = fakePi();
+  const musterCalls: Array<{ args: string[] }> = [];
+  createHarness(pi as never, { raiseAttention: noopBell,
+    tmux: () => ctxTmux,
+    runMuster: (_c, args) => { musterCalls.push({ args }); return ""; },
+  });
+  await fire("session_info_changed", { name: undefined });
+  assert.ok(!musterCalls.some((c) => c.args[0] === "become"), "an empty name must not become");
+});
+
+test("repeating the same name is a no-op: only the first occurrence renames and becomes", async () => {
+  const { pi, fire } = fakePi();
+  const musterCalls: Array<{ args: string[] }> = [];
+  const tmuxCalls: string[][] = [];
+  createHarness(pi as never, { raiseAttention: noopBell,
+    tmux: () => ctxTmux,
+    runTmux: (_s, a) => { tmuxCalls.push(a); return undefined; },
+    runMuster: (_c, args) => { musterCalls.push({ args }); return ""; },
+  });
+  await fire("session_info_changed", { name: "same-name" });
+  await fire("session_info_changed", { name: "same-name" });
+  const becomeCalls = musterCalls.filter((c) => c.args[0] === "become");
+  const renameCalls = tmuxCalls.filter((a) => a[0] === "rename-session");
+  assert.equal(becomeCalls.length, 1, "the outside-in echo must not round-trip a second become");
+  assert.equal(renameCalls.length, 1);
+});
+
+test("a non-tui session is inert on every event: subagents and headless runs are guests, not pane owners", async () => {
+  const { pi, fire } = fakePi();
+  const calls: unknown[] = [];
+  createHarness(pi as never, { raiseAttention: (c) => calls.push(c),
+    tmux: () => ctxTmux,
+    runTmux: (_s, a) => { calls.push(a); return undefined; },
+    runMuster: (_c, a, i) => { calls.push({ a, i }); return ""; },
+    writeState: (o) => calls.push(o),
+    removeState: (c) => calls.push(c),
+    ringBell: (c) => calls.push(c),
+  });
+  const subagentCtx = {
+    mode: "print",
+    sessionManager: { getSessionId: () => "sub-1" },
+    cwd: "/work/proj",
+    model: { id: "m" },
+    getContextUsage: () => ({ tokens: 1, contextWindow: 2, percent: 50 }),
+    ui: { setStatus: () => {} },
+  };
+  for (const e of ["session_start", "turn_end", "agent_settled", "session_info_changed", "session_shutdown"]) {
+    await fire(e, { name: "Explore#deadbeef", reason: "quit" }, subagentCtx);
+  }
+  assert.deepEqual(calls, [], "a print-mode session must not touch the pane's tmux name, bus row, or state file");
+});
+
+test("session_shutdown removes the state file and calls the SessionEnd hook", async () => {
+  const { pi, fire } = fakePi();
+  const removed: unknown[] = [];
+  const musterCalls: Array<{ args: string[]; input: string }> = [];
+  createHarness(pi as never, { raiseAttention: noopBell,
+    tmux: () => ctxTmux,
+    removeState: (c) => removed.push(c),
+    runMuster: (_c, args, input) => { musterCalls.push({ args, input }); return ""; },
+  });
+  await fire("session_shutdown", {});
+  assert.equal(removed.length, 1);
+  const hookCall = musterCalls.find((c) => c.args[1] === "SessionEnd");
+  assert.ok(hookCall, "expected a hook SessionEnd pi call");
+  assert.deepEqual(JSON.parse(hookCall.input), { session_id: "sess-1" });
+});
+
+test("outside tmux every handler is inert and none throws", async () => {
+  const { pi, fire } = fakePi();
+  const calls: unknown[] = [];
+  createHarness(pi as never, { raiseAttention: noopBell,
+    tmux: () => undefined,
+    runTmux: (_s, a) => { calls.push(a); return undefined; },
+    runMuster: (_c, a, i) => { calls.push({ a, i }); return ""; },
+    writeState: (o) => calls.push(o),
+    removeState: (c) => calls.push(c),
+  });
+  for (const e of ["session_start", "turn_end", "agent_settled", "session_info_changed", "session_shutdown"]) {
+    await fire(e, { name: "x" });
+  }
+  assert.deepEqual(calls, [], "nothing pane-scoped may run without a pane");
+});
+
+test("a throwing handler dependency never escapes into pi", async () => {
+  const { pi, fire } = fakePi();
+  createHarness(pi as never, { raiseAttention: noopBell,
+    tmux: () => ctxTmux,
+    runTmux: () => { throw new Error("no tmux"); },
+    writeState: () => { throw new Error("disk full"); },
+    ringBell: () => { throw new Error("no tty"); },
+    removeState: () => { throw new Error("gone"); },
+    runMuster: () => { throw new Error("no muster"); },
+  });
+  for (const e of ["session_start", "turn_end", "agent_settled", "session_info_changed", "session_shutdown"]) {
+    await fire(e, { name: "x" });
+  }
+});
+
+// F1: a settled agent with no queued continuation is a pane waiting on input.
+// Acceptance #4 — waiting on input raises the SwiftBar attention item — is
+// unmet unless agent_settled raises it.
+test("agent_settled raises the SwiftBar attention item with the tmux context", async () => {
+  const { pi, fire } = fakePi();
+  const raised: unknown[] = [];
+  createHarness(pi as never, {
+    tmux: () => ctxTmux,
+    raiseAttention: (c) => raised.push(c),
+    runMuster: () => "",
+  });
+  await fire("agent_settled", {});
+  assert.deepEqual(raised, [ctxTmux], "a settled agent is waiting on input; raise attention");
+});
+
+// F4 (RED-first): the state file is the liveness signal. If the session-id read
+// throws — a torn-down ctx during quit — removeState must already have run, or
+// the bar shows a dead session until the reader's 7-day backstop.
+test("session_shutdown removes the state file even when the session-id read throws", async () => {
+  const { pi, fire } = fakePi();
+  const removed: unknown[] = [];
+  createHarness(pi as never, { raiseAttention: noopBell,
+    tmux: () => ctxTmux,
+    removeState: (c) => removed.push(c),
+    runMuster: () => "",
+  });
+  const brokenCtx = {
+    mode: "tui",
+    sessionManager: { getSessionId: () => { throw new Error("ctx torn down"); } },
+  };
+  await fire("session_shutdown", {}, brokenCtx);
+  assert.equal(removed.length, 1, "removeState must run before the session-id read, not after");
+});
+
+// F5 (RED-first): a resume with unread mail injects on session_start (triggering
+// a turn); the settle that turn produces must NOT re-inject the same mail as a
+// drain block reason. One resume, one post.
+test("a resume with unread mail then a settle injects exactly once, not twice", async () => {
+  const { pi, fire, sent } = fakePi();
+  createHarness(pi as never, { raiseAttention: noopBell,
+    tmux: () => ctxTmux,
+    runTmux: noopTmux,
+    runMuster: (_c, args) => {
+      if (args[1] === "SessionStart") return "muster: reconnected as 'pi-97' — 2 unread thread(s)";
+      if (args[1] === "Stop") return JSON.stringify({ decision: "block", reason: "You have 2 unread threads" });
+      return "";
+    },
+  });
+  await fire("session_start", { reason: "resume" });
+  await fire("agent_settled", {});
+  assert.equal(sent.length, 1, "one resume with mail must post exactly once, not once per turn");
+  assert.deepEqual(sent[0].options, { triggerTurn: true }, "the single post is the session_start injection");
+});
+
+// A rename fires become() to claim the new alias live; if a reload or switch
+// then fires session_shutdown, tombstoning on that non-quit reason races the
+// become and leaves both the old and new aliases departed (live galley
+// trial). Only a real quit ends the conversation on the bus.
+test("session_shutdown tombstones and drops state ONLY on reason quit", async () => {
+  const { pi, fire } = fakePi();
+  const musterCalls: Array<{ args: string[] }> = [];
+  const removed: unknown[] = [];
+  const mk = () =>
+    createHarness(pi as never, {
+      raiseAttention: noopBell,
+      tmux: () => ctxTmux,
+      runTmux: noopTmux,
+      writeState: () => {},
+      ringBell: noopBell,
+      removeState: (ctx) => removed.push(ctx),
+      runMuster: (_c, args) => { musterCalls.push({ args }); return ""; },
+    });
+
+  mk();
+  for (const reason of ["reload", "new", "resume", "fork"]) {
+    musterCalls.length = 0;
+    removed.length = 0;
+    await fire("session_shutdown", { reason });
+    assert.ok(
+      !musterCalls.some((c) => c.args[1] === "SessionEnd"),
+      `reason ${reason} must NOT tombstone`,
+    );
+    assert.equal(removed.length, 0, `reason ${reason} must NOT drop the state file`);
+  }
+
+  musterCalls.length = 0;
+  removed.length = 0;
+  await fire("session_shutdown", { reason: "quit" });
+  assert.ok(
+    musterCalls.some((c) => c.args[1] === "SessionEnd"),
+    "reason quit must tombstone",
+  );
+  assert.equal(removed.length, 1, "reason quit must drop the state file");
+});

package/src/index.ts

@@ -0,0 +1,215 @@
+import { resolveTmux, tmux as runTmuxDefault } from "./tmux.ts";
+import type { TmuxContext } from "./tmux.ts";
+import { writeState as writeStateDefault, removeState as removeStateDefault } from "./state.ts";
+import { ringBell as ringBellDefault, raiseAttention as raiseAttentionDefault } from "./bell.ts";
+import { sessionStart, drain, sessionEnd, become } from "./muster.ts";
+import type { Run } from "./muster.ts";
+
+type Deps = {
+  tmux?: () => TmuxContext | undefined;
+  runTmux?: (socket: string, args: string[]) => string | undefined;
+  runMuster?: Run;
+  writeState?: (opts: { ctx: TmuxContext; contextPct: number; model: string }) => void;
+  removeState?: (ctx: TmuxContext) => void;
+  ringBell?: (ctx: TmuxContext) => void;
+  raiseAttention?: (ctx: TmuxContext) => void;
+};
+
+// The session id reaches tmux as a session option value; sanitize before it
+// gets there. Same character class the Claude Code hook this replaces used,
+// and for the same reason: the id is later used by consumers to build file
+// paths. Only the tmux-bound copy is sanitized — muster's hooks take the raw
+// id in a JSON payload, not a tmux target or a filesystem path.
+function sanitize(id: string): string {
+  return id.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+
+// Every handler is best-effort: it sits directly on a pi lifecycle event, and
+// a harness that fails a session start, a turn, or a shutdown over a status
+// bar or a bus registration is worse than no harness at all.
+function safe(fn: () => void | Promise<void>): void {
+  try {
+    const result = fn();
+    if (result && typeof (result as Promise<void>).catch === "function") {
+      (result as Promise<void>).catch(() => {});
+    }
+  } catch {
+    // Best-effort: nothing here may escape into pi.
+  }
+}
+
+export function createHarness(pi: any, deps: Deps = {}): void {
+  const getTmux = deps.tmux ?? resolveTmux;
+  const runTmux = deps.runTmux ?? runTmuxDefault;
+  const musterDeps = deps.runMuster ? { run: deps.runMuster } : {};
+  const writeState = deps.writeState ?? ((opts) => writeStateDefault({ ...opts }));
+  const removeState = deps.removeState ?? ((ctx) => removeStateDefault(ctx));
+  const ringBell = deps.ringBell ?? ((ctx) => ringBellDefault(ctx));
+  const raiseAttention = deps.raiseAttention ?? ((ctx) => raiseAttentionDefault(ctx));
+
+  // Loop guard for the drain on agent_settled: injecting a block reason
+  // starts a turn, which produces another settle. Without tracking whether
+  // WE triggered the settle we are currently handling, that settle re-drains,
+  // sees the same unread mail, and injects again — forever, for as long as
+  // mail stays unread. Scoped to this createHarness call so each session
+  // (and each test) starts clean.
+  let stopHookActive = false;
+
+  // Guard for session_info_changed: the alias muster last confirmed for this
+  // pane, whether from our own become() or simply the last name we acted on.
+  // Comparing against it (rather than the raw previous event) is what
+  // collapses the outside-in loop: `muster label X` types `/name X` into our
+  // pane, firing this event with a name muster already has — becoming it
+  // again would be a pointless round-trip.
+  let lastAlias: string | undefined;
+
+  // Only an interactive session owns the pane's identity. Subagent sessions
+  // (pi-subagents' createAgentSession) run IN-PROCESS: they load this
+  // extension too, inherit $TMUX/$TMUX_PANE, and their extension mode stays
+  // at the SDK default "print" — only the TUI upgrades it, before extensions
+  // initialize, so a real session always sees "tui" from session_start on.
+  // Without this gate a subagent's auto-name hijacked the host session's
+  // tmux name and bus alias, and its quit tombstoned the pane's row (caught
+  // live 2026-08-27, twice). Headless `pi -p` runs in a pane are excluded
+  // for the same reason — they are guests, not the pane's owner.
+  const ownsPane = (ctx: any): boolean => ctx?.mode === "tui";
+
+  pi.on("session_start", (event: any, ctx: any) => safe(() => {
+    if (!ownsPane(ctx)) return;
+    const t = getTmux();
+    if (!t) return;
+    const rawSessionId = String(ctx.sessionManager.getSessionId());
+    const sanitizedSessionId = sanitize(rawSessionId);
+    runTmux(t.socket, ["set-option", "-t", t.pane, "@harness_session", sanitizedSessionId]);
+
+    const source = event?.reason === "resume" || event?.reason === "fork" ? "resume" : "startup";
+    const out = sessionStart({ sessionId: rawSessionId, cwd: ctx.cwd, source, ...musterDeps });
+    if (out.stdout) {
+      // Require a positive unread count: `/unread/i` also matched a
+      // "— 0 unread thread(s)" line, triggering a turn on every resume with
+      // nothing to do.
+      const triggerTurn = /[1-9]\d* unread/.test(out.stdout);
+      if (triggerTurn) {
+        // The turn we start here ends in agent_settled, which drains and would
+        // get this same unread mail as a block reason and inject it AGAIN —
+        // two prompts for one resume. Arming the loop guard now makes that
+        // following settle skip the re-inject, collapsing it to one.
+        stopHookActive = true;
+      }
+      pi.sendMessage(
+        { customType: "harness", content: out.stdout, display: false },
+        { triggerTurn },
+      );
+    }
+  }));
+
+  pi.on("turn_end", (_event: unknown, ctx: any) => safe(() => {
+    if (!ownsPane(ctx)) return;
+    const t = getTmux();
+    if (!t) return;
+    // The state write and the bell are independent notifications that
+    // happen to share this event: a throw from getContextUsage/writeState
+    // (or a missing ctx.model) must not suppress the bell for this turn.
+    try {
+      const usage = ctx.getContextUsage?.();
+      if (usage != null && usage.percent != null) {
+        writeState({ ctx: t, contextPct: usage.percent, model: ctx.model.id });
+      }
+    } catch {
+      // Best-effort: the meter is not worth losing the bell over.
+    }
+    ringBell(t);
+  }));
+
+  pi.on("agent_settled", (_event: unknown, ctx: any) => safe(() => {
+    if (!ownsPane(ctx)) return;
+    const t = getTmux();
+    if (!t) return;
+    // A settled agent with no queued continuation is a pane waiting on input:
+    // raise the SwiftBar attention item (Acceptance #4). pi has no event
+    // literally named "input waiting"; agent_settled is that boundary. Its own
+    // try/catch keeps it best-effort, and the enclosing safe() is a backstop —
+    // a failed attention flag must not lose this settle's drain.
+    raiseAttention(t);
+    const sessionId = String(ctx.sessionManager.getSessionId());
+    const wasStopHookActive = stopHookActive;
+    const out = drain({ sessionId, stopHookActive: wasStopHookActive, ...musterDeps });
+    if (out.reason && !wasStopHookActive) {
+      pi.sendMessage(
+        { customType: "harness", content: out.reason, display: false },
+        { triggerTurn: true },
+      );
+      stopHookActive = true;
+    } else {
+      stopHookActive = false;
+    }
+  }));
+
+  pi.on("session_info_changed", (event: any, ctx: any) => safe(() => {
+    if (!ownsPane(ctx)) return;
+    const t = getTmux();
+    if (!t) return;
+    const name = event?.name;
+    if (!name) return;
+    if (name === lastAlias) return;
+    // Prefix-T's contract (dotfiles tmux-session-rename.sh): the operator
+    // names the WORK; the <project>/ prefix is a property of where the
+    // session lives. A bare /name gets the current first segment re-attached
+    // so the session never renames out of its project grouping (and the bus
+    // alias — which IS the tmux name — stays grouped too); a name already
+    // carrying '/' is taken verbatim, the same re-homing escape hatch the
+    // script offers. For a home-base session (no '/' in #S) the whole
+    // current name is the project.
+    const cur = runTmux(t.socket, ["display-message", "-p", "-t", t.pane, "#{session_name}"]);
+    const full = name.includes("/") || !cur ? name : `${cur.split("/")[0]}/${name}`;
+    if (full === lastAlias) return;
+    // tmux rejects session names containing `.` or `:`, so the tmux-bound name
+    // is sanitized to `-`; muster's alias takes the raw name. Without this the
+    // rename would fail while become() succeeded and lastAlias recorded the
+    // name as done, leaving the two divergent with no retry. Sanitizing here
+    // keeps both renames landing for any name pi allows.
+    const tmuxName = full.replace(/[.:]/g, "-");
+    runTmux(t.socket, ["rename-session", "-t", t.pane, tmuxName]);
+    become(full, musterDeps);
+    // Record the COMPOSED name: muster label confirms a become by typing
+    // /name <full> back into the pane, so the echo arrives prefixed and must
+    // match what we stored to collapse the loop. The raw-name guard above
+    // still catches a repeat of the operator's own bare /name before the
+    // tmux round-trip.
+    lastAlias = full;
+  }));
+
+  pi.on("session_shutdown", (event: any, ctx: any) => safe(() => {
+    if (!ownsPane(ctx)) return;
+    // Fires on every session SWITCH, not only quit: reason ∈
+    // quit|reload|new|resume|fork. Only a REAL end (quit) may tombstone this
+    // session's bus row and drop its state file; every other reason is a
+    // continuation whose paired session_start re-registers, and tombstoning
+    // there races other events on the same tuple. Live repro (galley
+    // trial): a rename fires become() → the new alias goes live, then a reload
+    // or switch fired session_shutdown → sessionEnd tombstoned it, leaving BOTH
+    // the old and new aliases departed. muster's SessionEnd is "the
+    // conversation ended" (Claude Code fires it once, at the real end); pi's
+    // broader session_shutdown must be filtered to match that contract.
+    if (event?.reason && event.reason !== "quit") return;
+    const t = getTmux();
+    if (!t) return;
+    // Remove the state file FIRST, before touching ctx. A torn-down ctx during
+    // a quit — plausible exactly at shutdown — would otherwise throw on the
+    // session-id read and leak the state file, so the bar shows a dead session
+    // until the reader's 7-day backstop. The state file is the liveness signal;
+    // dropping it must not depend on the bus call succeeding.
+    removeState(t);
+    try {
+      const sessionId = String(ctx.sessionManager.getSessionId());
+      sessionEnd({ sessionId, ...musterDeps });
+    } catch {
+      // Best-effort: a torn-down ctx must not resurrect the state file we just
+      // removed. The tombstone is muster's to miss, not ours to block on.
+    }
+  }));
+}
+
+export default function (pi: any) {
+  createHarness(pi);
+}

package/src/muster.test.ts

@@ -0,0 +1,123 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { register, sessionStart, drain, sessionEnd, become } from "./muster.ts";
+import type { Run } from "./muster.ts";
+
+type Call = { cmd: string; args: string[]; input: string };
+function recorder(returns = "") {
+  const calls: Call[] = [];
+  return {
+    calls,
+    run: (cmd: string, args: string[], input: string) => {
+      calls.push({ cmd, args, input });
+      return returns;
+    },
+  };
+}
+
+test("register passes the model as pi and the alias when given", () => {
+  const r = recorder();
+  register({ alias: "pi-97", run: r.run });
+  assert.equal(r.calls.length, 1);
+  assert.match(r.calls[0].cmd, /muster$/);
+  assert.deepEqual(r.calls[0].args, ["register", "pi-97", "--model", "pi"]);
+});
+
+test("register omits the alias when none is given, letting muster fall back to the tmux session name", () => {
+  const r = recorder();
+  register({ run: r.run });
+  assert.deepEqual(r.calls[0].args, ["register", "--model", "pi"]);
+});
+
+test("become passes --no-inject so a rename cannot type back into its own pane", () => {
+  const r = recorder();
+  become("new-name", { run: r.run });
+  assert.deepEqual(r.calls[0].args, ["become", "new-name", "--no-inject"]);
+});
+
+test("become with an empty name does nothing rather than claiming an empty alias", () => {
+  const r = recorder();
+  become("", { run: r.run });
+  assert.deepEqual(r.calls, []);
+});
+
+test("a failing muster call is swallowed — the bus is not worth failing a turn over", () => {
+  const boom: Run = () => { throw new Error("muster is not installed"); };
+  assert.doesNotThrow(() => register({ run: boom }));
+  assert.doesNotThrow(() => drain({ sessionId: "s", stopHookActive: false, run: boom }));
+  assert.doesNotThrow(() => sessionEnd({ sessionId: "s", run: boom }));
+  assert.doesNotThrow(() => become("x", { run: boom }));
+});
+
+test("sessionStart sends the payload muster expects and returns its stdout", () => {
+  const seen: Array<{ args: string[]; input: string }> = [];
+  const out = sessionStart({
+    sessionId: "sess-1", cwd: "/w", source: "startup",
+    run: (_c, args, input) => { seen.push({ args, input }); return "muster: registered as 'pi-97'\n"; },
+  });
+  assert.deepEqual(seen[0].args, ["hook", "SessionStart", "pi"]);
+  assert.deepEqual(JSON.parse(seen[0].input), { session_id: "sess-1", cwd: "/w", source: "startup" });
+  assert.match(out.stdout, /registered as/);
+});
+
+test("a resume passes source:resume, which is what makes muster reclaim rows", () => {
+  let input = "";
+  sessionStart({ sessionId: "s", cwd: "/w", source: "resume", run: (_c, _a, i) => { input = i; return ""; } });
+  assert.equal(JSON.parse(input).source, "resume");
+});
+
+test("drain passes stop_hook_active and surfaces the block reason", () => {
+  const seen: string[] = [];
+  const out = drain({
+    sessionId: "s", stopHookActive: false,
+    run: (_c, _a, i) => { seen.push(i); return JSON.stringify({ decision: "block", reason: "You have 2 unread threads" }); },
+  });
+  assert.equal(JSON.parse(seen[0]).stop_hook_active, false);
+  assert.equal(out.reason, "You have 2 unread threads");
+});
+
+test("drain with no mail yields no reason rather than an empty one", () => {
+  const out = drain({ sessionId: "s", stopHookActive: false, run: () => "" });
+  assert.equal(out.reason, undefined);
+});
+
+test("drain recovers the reason from JSON that follows a leading warning line", () => {
+  // A hook may log a warning before its JSON. Parsing the whole stdout would
+  // throw on the warning and silently drop the mail notice; the last JSON-object
+  // line is what carries the decision.
+  const out = drain({
+    sessionId: "s", stopHookActive: false,
+    run: () => 'warning: x\n{"decision":"block","reason":"You have 2 unread threads"}',
+  });
+  assert.equal(out.reason, "You have 2 unread threads");
+});
+
+test("drain tolerates stdout that carries no JSON at all", () => {
+  // A warning with no JSON behind it must not throw into a settle handler, and
+  // yields no reason rather than a fabricated one.
+  const out = drain({ sessionId: "s", stopHookActive: false, run: () => "warning: something\n" });
+  assert.equal(out.reason, undefined);
+});
+
+test("a decision that is not block yields no reason", () => {
+  const out = drain({
+    sessionId: "s", stopHookActive: false,
+    run: () => JSON.stringify({ decision: "approve", reason: "ignored" }),
+  });
+  assert.equal(out.reason, undefined);
+});
+
+test("sessionEnd sends the session id so it tombstones this pane's rows only", () => {
+  let input = "";
+  sessionEnd({ sessionId: "s", run: (_c, _a, i) => { input = i; return ""; } });
+  assert.deepEqual(JSON.parse(input), { session_id: "s" });
+});
+
+test("a throwing hook yields an empty outcome rather than propagating", () => {
+  const boom: Run = () => { throw new Error("no muster"); };
+  assert.doesNotThrow(() => {
+    const out = drain({ sessionId: "s", stopHookActive: false, run: boom });
+    assert.equal(out.reason, undefined);
+    assert.equal(out.stdout, "");
+  });
+});

package/src/muster.ts

@@ -0,0 +1,144 @@
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const MUSTER = join(homedir(), ".local", "bin", "muster");
+
+export type Run = (cmd: string, args: string[], input: string) => string;
+
+export type HookOutcome = { stdout: string; reason?: string };
+
+// The default seam. Deliberately NOT passing `env`: muster's hooks resolve
+// the calling pane from $TMUX / $TMUX_PANE, falling back to an ancestry walk
+// when that is unset. Inheriting the child's environment for free is what
+// makes that resolution work — passing an explicit env here (even one that
+// looks like a superset) would break it invisibly. Do not "tidy" this.
+function defaultRun(cmd: string, args: string[], input: string): string {
+  return execFileSync(cmd, args, {
+    input,
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "ignore"],
+  });
+}
+
+// Every hook call is best-effort. A session whose bus call fails is worse off
+// than one that succeeded, but it is still a working session — and a handler
+// that threw would fail a session start, a settle, or a shutdown outright.
+function callHook(event: string, payload: unknown, run: Run): HookOutcome {
+  try {
+    const stdout = run(MUSTER, ["hook", event, "pi"], JSON.stringify(payload));
+    return { stdout };
+  } catch {
+    // Best-effort: the bus is not worth failing a turn, a start, or a shutdown.
+    return { stdout: "" };
+  }
+}
+
+// hook SessionStart pi replaces register() for the pane path: beyond
+// registering, it reclaims this pane's rows on a resume and prints
+// reconnection text to stdout. Claude Code injects hook stdout into context
+// automatically; pi does not, so the caller must inject `stdout` itself or a
+// resumed session silently knows less than it should.
+export function sessionStart(
+  opts: { sessionId: string; cwd: string; source: "startup" | "resume"; run?: Run },
+): HookOutcome {
+  const run = opts.run ?? defaultRun;
+  return callHook(
+    "SessionStart",
+    { session_id: opts.sessionId, cwd: opts.cwd, source: opts.source },
+    run,
+  );
+}
+
+// Drain belongs on agent_settled, NOT on agent_end / turn end. Claude Code
+// wires its drain to the Stop hook because that is the only boundary it can
+// express; pi's agent_end is that same boundary, but after it pi may still
+// auto-retry, auto-compact and retry, or continue with queued follow-up
+// messages. An earlier phase of this program hit exactly that edge with
+// buffered mail: delivering there lands it mid-retry or loses it to
+// compaction. This module only provides drain() — Task 5 wires it to
+// agent_settled, the point where pi will not continue on its own.
+//
+// stopHookActive must be true on the settle immediately following a drain
+// this module triggered, otherwise every settle re-drains for as long as
+// mail is unread — which, with pi-channels also pushing, is a session that
+// talks to itself indefinitely.
+export function drain(
+  opts: { sessionId: string; stopHookActive: boolean; run?: Run },
+): HookOutcome {
+  const run = opts.run ?? defaultRun;
+  const outcome = callHook(
+    "Stop",
+    { session_id: opts.sessionId, stop_hook_active: opts.stopHookActive },
+    run,
+  );
+  try {
+    // The hook may print a warning line before its JSON, so parse the LAST
+    // non-empty line that looks like a JSON object rather than the whole
+    // stdout — parsing the whole thing would throw on the leading warning and
+    // silently drop the mail notice. stdout may still be empty or carry no
+    // JSON at all; a malformed decision must not throw into a settle handler.
+    const jsonLine = outcome.stdout
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l.startsWith("{") && l.endsWith("}"))
+      .pop();
+    if (jsonLine) {
+      const parsed = JSON.parse(jsonLine);
+      if (parsed && parsed.decision === "block" && typeof parsed.reason === "string") {
+        return { stdout: outcome.stdout, reason: parsed.reason };
+      }
+    }
+  } catch {
+    // A line that looked like JSON but was not must not throw into a settle
+    // handler — the mail is best-effort, not worth failing the settle over.
+  }
+  return outcome;
+}
+
+export function sessionEnd(opts: { sessionId: string; run?: Run }): void {
+  const run = opts.run ?? defaultRun;
+  // sessionId is sent so muster tombstones only this pane's rows, not every
+  // row for the alias.
+  callHook("SessionEnd", { session_id: opts.sessionId }, run);
+}
+
+// Adapts a plain arg-list call onto the new (cmd, args, input) => stdout
+// seam for register/become, which carry no payload and ignore any reply.
+function call(args: string[], run: Run): void {
+  try {
+    run(MUSTER, args, "");
+  } catch {
+    // Best-effort: the bus is not worth failing a turn, a start, or a shutdown.
+  }
+}
+
+// --model pi is what puts this session in muster's harness tables. Those
+// tables decide, among other things, whether an outside-in rename can reach
+// this pane at all. Omitting the alias is deliberate when none is given:
+// muster falls back to $MUSTER_ALIAS and then the tmux session name, which is
+// the behaviour every other harness gets.
+//
+// This is no longer the session-start call — `sessionStart` (hook
+// SessionStart pi) is. `register` stays for claiming an explicit alias AFTER
+// the hook has run.
+//
+// NOT currently wired: index.ts calls sessionStart, never register. Exported
+// and retained deliberately, per the amendment, for a future explicit-alias
+// claim after sessionStart — not dead code left by accident.
+export function register(opts: { alias?: string; run?: Run } = {}): void {
+  const run = opts.run ?? defaultRun;
+  const args = opts.alias ? ["register", opts.alias] : ["register"];
+  call([...args, "--model", "pi"], run);
+}
+
+// --no-inject: become normally types the new name into the agent's pane so
+// the harness session name follows. Our caller is a handler already reacting
+// to a rename, so typing it back would loop text into the pane that just
+// renamed itself. muster's own help names this exact case, and Claude Code's
+// statusline passes the same flag for the same reason.
+export function become(name: string, deps: { run?: Run } = {}): void {
+  if (!name) return;
+  const run = deps.run ?? defaultRun;
+  call(["become", name, "--no-inject"], run);
+}

package/src/state.test.ts

@@ -0,0 +1,54 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { stateKey, writeState, removeState } from "./state.ts";
+
+const ctx = { socket: "proj-pi", pane: "%47" };
+
+test("the key is socket plus pane without the percent", () => {
+  assert.equal(stateKey(ctx), "proj-pi_47");
+});
+
+test("characters outside the safe set become underscores", () => {
+  // The key becomes a filename, and a socket name is whatever the operator
+  // called their project.
+  assert.equal(stateKey({ socket: "proj/weird name", pane: "%3" }), "proj_weird_name_3");
+});
+
+test("writeState emits exactly the five keys the reader parses, in order", () => {
+  const dir = mkdtempSync(join(tmpdir(), "harness-state-"));
+  writeState({ ctx, contextPct: 42, model: "Qwen3.8-27B", dir });
+  const body = readFileSync(join(dir, "proj-pi_47"), "utf-8");
+  const keys = body.trim().split("\n").map((l) => l.split("=")[0]);
+  assert.deepEqual(keys, ["context_pct", "model", "updated", "pane", "socket"]);
+  assert.match(body, /^context_pct=42$/m);
+  assert.match(body, /^model=Qwen3\.8-27B$/m);
+  assert.match(body, /^pane=%47$/m);
+  assert.match(body, /^socket=proj-pi$/m);
+  assert.match(body, /^updated=\d{10}$/m);
+});
+
+test("context_pct is written as an integer, never a float", () => {
+  const dir = mkdtempSync(join(tmpdir(), "harness-state-"));
+  writeState({ ctx, contextPct: 42.7, model: "m", dir });
+  assert.match(readFileSync(join(dir, "proj-pi_47"), "utf-8"), /^context_pct=42$/m);
+});
+
+test("a newline in the model name cannot forge a second key", () => {
+  const dir = mkdtempSync(join(tmpdir(), "harness-state-"));
+  writeState({ ctx, contextPct: 1, model: "evil\nupdated=0", dir });
+  const body = readFileSync(join(dir, "proj-pi_47"), "utf-8");
+  assert.equal(body.match(/^updated=/gm)?.length, 1);
+});
+
+test("removeState deletes the file, and is safe when it is already gone", () => {
+  const dir = mkdtempSync(join(tmpdir(), "harness-state-"));
+  writeState({ ctx, contextPct: 1, model: "m", dir });
+  const path = join(dir, "proj-pi_47");
+  assert.ok(existsSync(path));
+  removeState(ctx, dir);
+  assert.ok(!existsSync(path));
+  removeState(ctx, dir); // must not throw
+});

package/src/state.ts

@@ -0,0 +1,55 @@
+import { mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { TmuxContext } from "./tmux.ts";
+
+function defaultDir(): string {
+  const base = process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache");
+  return join(base, "claude-status");
+}
+
+// TWO-SIDED CONTRACT. dotfiles/bin/tmux-claude-context.sh derives the identical
+// key from '#{socket_path}' on the reading side. Change the two together.
+//
+// Keying on the pane alone is what this replaced: pane ids are only unique per
+// server, this machine runs a socket per project, so every server's %NN
+// collided on one file and the bar showed some other socket's context.
+export function stateKey(ctx: TmuxContext): string {
+  const raw = `${ctx.socket}_${ctx.pane.replace(/^%/, "")}`;
+  return raw.replace(/[^A-Za-z0-9_.-]/g, "_");
+}
+
+export function writeState(opts: {
+  ctx: TmuxContext;
+  contextPct: number;
+  model: string;
+  dir?: string;
+}): void {
+  const dir = opts.dir ?? defaultDir();
+  try {
+    mkdirSync(dir, { recursive: true });
+    // The file is line-oriented key=value and the reader splits on the first
+    // '='. A newline in a value would forge a key, so values are flattened.
+    const model = opts.model.replace(/[\r\n]+/g, " ");
+    const body =
+      `context_pct=${Math.trunc(opts.contextPct)}\n` +
+      `model=${model}\n` +
+      `updated=${Math.floor(Date.now() / 1000)}\n` +
+      `pane=${opts.ctx.pane}\n` +
+      `socket=${opts.ctx.socket}\n`;
+    writeFileSync(join(dir, stateKey(opts.ctx)), body);
+  } catch {
+    // Best-effort: a status bar is not worth failing a turn over.
+  }
+}
+
+// Removing this on shutdown is what lets the reader stop guessing. Claude Code
+// has no reliable way to say it is gone, so tmux-claude-context.sh sniffs
+// pane_current_command instead; a pi session cleans up after itself.
+export function removeState(ctx: TmuxContext, dir?: string): void {
+  try {
+    rmSync(join(dir ?? defaultDir(), stateKey(ctx)), { force: true });
+  } catch {
+    // Best-effort.
+  }
+}

package/src/tmux.test.ts

@@ -0,0 +1,28 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { resolveTmux } from "./tmux.ts";
+
+test("resolves socket and pane from a real TMUX value", () => {
+  const ctx = resolveTmux({ TMUX: "/private/tmp/tmux-501/proj-pi,12345,3", TMUX_PANE: "%47" });
+  assert.equal(ctx?.socket, "proj-pi");
+  assert.equal(ctx?.pane, "%47");
+});
+
+test("returns undefined outside tmux", () => {
+  assert.equal(resolveTmux({}), undefined);
+  assert.equal(resolveTmux({ TMUX_PANE: "%1" }), undefined);
+  assert.equal(resolveTmux({ TMUX: "/tmp/sock,1,0" }), undefined);
+});
+
+test("socket is the basename of the first comma field, not the whole path", () => {
+  // Pane ids are only unique per server and this machine runs a socket per
+  // project, so the socket name is half the state-file key. Taking the path
+  // rather than its basename would put slashes in a filename.
+  const ctx = resolveTmux({ TMUX: "/very/long/path/to/default,9,0", TMUX_PANE: "%1" });
+  assert.equal(ctx?.socket, "default");
+});
+
+test("an empty or malformed TMUX yields undefined rather than a junk socket", () => {
+  assert.equal(resolveTmux({ TMUX: "", TMUX_PANE: "%1" }), undefined);
+  assert.equal(resolveTmux({ TMUX: ",,", TMUX_PANE: "%1" }), undefined);
+});

package/src/tmux.ts

@@ -0,0 +1,48 @@
+import { execFileSync } from "node:child_process";
+
+export type TmuxContext = {
+  socket: string;
+  pane: string;
+};
+
+// $TMUX is "<socket-path>,<pid>,<session>". The socket NAME is the basename of
+// the first field — the full path would put slashes into the state-file key,
+// and the bare pane id would collide across servers, since pane ids are only
+// unique per server and this machine runs one socket per project.
+export function resolveTmux(env: NodeJS.ProcessEnv = process.env): TmuxContext | undefined {
+  const tmuxEnv = env.TMUX;
+  const pane = env.TMUX_PANE;
+  if (!tmuxEnv || !pane) return undefined;
+  const socketPath = tmuxEnv.split(",")[0];
+  if (!socketPath) return undefined;
+  const socket = socketPath.slice(socketPath.lastIndexOf("/") + 1);
+  if (!socket) return undefined;
+  return { socket, pane };
+}
+
+// Every tmux call is best-effort: a harness handler must never fail a session
+// start, a turn, or a shutdown because the terminal did something unexpected.
+export function tmux(socket: string, args: string[]): string | undefined {
+  try {
+    return execFileSync("tmux", ["-L", socket, ...args], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return undefined;
+  }
+}
+
+// The tmux SESSION name for a pane. @harness_session is a session option, not a
+// pane one, because the consumer is a sibling pane (`scratch`) which cannot
+// read the agent's environment.
+export function sessionOfPane(socket: string, pane: string): string | undefined {
+  const name = tmux(socket, ["display-message", "-p", "-t", pane, "#{session_name}"]);
+  return name === "" ? undefined : name;
+}
+
+// The pane's tty, for the bell.
+export function ttyOfPane(socket: string, pane: string): string | undefined {
+  const tty = tmux(socket, ["display-message", "-p", "-t", pane, "#{pane_tty}"]);
+  return tty === "" ? undefined : tty;
+}