tokenmaxxing 1.6.0 → 1.8.0

package/src/entries/mcp.ts

@@ -0,0 +1,288 @@
+// Stdio MCP entry for the portable Agent Plugin (agent-plugin/).
+// Tools wrap existing CLI commands. stdout is reserved for MCP JSON-RPC, so
+// every CLI call captures console.log / console.error and returns the text.
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { cmdLs } from "../cli/ls.ts";
+import { cmdStatus } from "../cli/status.ts";
+import { cmdDoctor } from "../cli/doctor.ts";
+import { cmdConfig } from "../cli/config.ts";
+import { cmdSwitch } from "../cli/switch.ts";
+import { cmdCodexSwitch } from "../cli/codexswitch.ts";
+import { cmdCheck } from "../cli/check.ts";
+
+const MUTATIONS_ENV = "TOKENMAXXING_AGENT_MUTATIONS";
+const PACKAGE_ROOT = join(import.meta.dir, "../..");
+
+function packageVersion(): string {
+  try {
+    const raw = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8")) as { version?: string };
+    return raw.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+/** Refuse ambient Claude store overrides the same way the CLI and SDK do. */
+export function refuseAmbientStoreEnv(): string | null {
+  const nonEmpty = (v: string | undefined) => (v != null && v !== "" ? v : null);
+  return nonEmpty(process.env.CLAUDE_SECURESTORAGE_CONFIG_DIR) ?? nonEmpty(process.env.CLAUDE_CONFIG_DIR);
+}
+
+/** Redact token-shaped spans so tool results never echo credentials. */
+export function scrubSecrets(text: string): string {
+  return text
+    .replace(/\b(Bearer\s+)[A-Za-z0-9._\-+/=]+/gi, "$1[redacted]")
+    .replace(/\b(sk-ant-[A-Za-z0-9_-]+)\b/g, "[redacted]")
+    .replace(/\b(accessToken|refreshToken|claudeAiOauth)\b\s*[:=]\s*["']?[^"'}\s,]+/gi, "$1=[redacted]");
+}
+
+type CaptureResult = { code: number; stdout: string; stderr: string };
+
+/** Serialize captureCli: console.log/error are process-global, so concurrent
+ *  tool calls would interleave stdout into each other and corrupt JSON-RPC. */
+let captureChain: Promise<unknown> = Promise.resolve();
+
+/** Run a CLI cmd while keeping stdout clean for the MCP transport. */
+export async function captureCli(run: () => number | Promise<number>): Promise<CaptureResult> {
+  const job = async (): Promise<CaptureResult> => {
+    const out: string[] = [];
+    const err: string[] = [];
+    const joinArgs = (args: unknown[]) => args.map((a) => (typeof a === "string" ? a : String(a))).join(" ");
+    const log = console.log;
+    const error = console.error;
+    console.log = (...args: unknown[]) => { out.push(joinArgs(args)); };
+    console.error = (...args: unknown[]) => { err.push(joinArgs(args)); };
+    try {
+      const code = await run();
+      return { code, stdout: out.join("\n"), stderr: err.join("\n") };
+    } finally {
+      console.log = log;
+      console.error = error;
+    }
+  };
+  const next = captureChain.then(job, job);
+  captureChain = next.then(
+    () => undefined,
+    () => undefined,
+  );
+  return next;
+}
+
+function textResult(input: { text: string; isError?: boolean }) {
+  return {
+    content: [{ type: "text" as const, text: scrubSecrets(input.text) }],
+    ...(input.isError ? { isError: true } : {}),
+  };
+}
+
+function formatCapture(cap: CaptureResult): string {
+  const parts: string[] = [];
+  if (cap.stdout) parts.push(cap.stdout);
+  if (cap.stderr) parts.push(cap.stderr);
+  parts.push(`exit ${cap.code}`);
+  return parts.join("\n").trimEnd();
+}
+
+export function mutationsEnabled(): boolean {
+  return process.env[MUTATIONS_ENV] === "1";
+}
+
+function mutationDenied(confirm: boolean): string | null {
+  if (!confirm) {
+    return `Mutating tools require confirm=true. Also set ${MUTATIONS_ENV}=1 in the MCP server environment after the user approves.`;
+  }
+  if (!mutationsEnabled()) {
+    return `Mutations are disabled. Set ${MUTATIONS_ENV}=1 in the MCP server environment only after the user explicitly approves a pool mutation.`;
+  }
+  return null;
+}
+
+const HELP_TEXT = `tokenmaxxing agent MCP
+
+Read tools (always available):
+  pool_ls       list pooled Claude and Codex accounts (labels/status only)
+  pool_status   sample usage bars (free /usage path; never --force)
+  doctor        verify install health (labels/status only)
+  config_get    read effective config, or one key when provided
+  help          this catalog
+
+Mutating tools (confirm=true AND ${MUTATIONS_ENV}=1):
+  pool_switch   Claude greedy/forced switch, or Codex when codex=true
+  pool_check    one evaluate-and-maybe-swap pass
+  config_set    write a config.json override
+  config_unset  remove a config.json override
+
+Hard deny (no tools):
+  status --force / metered pings
+  init / add / auth / rm / uninstall
+  credential blobs or token values
+  killing sessions or supervisors
+
+Prefer these tools over raw shell for pool ops. Honor TOKENMAXXING_HOME for hermetic use.
+`;
+
+export function createTokenmaxxingMcpServer(): McpServer {
+  const server = new McpServer({
+    name: "tokenmaxxing",
+    version: packageVersion(),
+  });
+
+  server.registerTool(
+    "help",
+    {
+      description: "Catalog of tokenmaxxing MCP tools and hard safety rules. Use when deciding which pool tool to call.",
+      inputSchema: {},
+    },
+    async () => textResult({ text: HELP_TEXT }),
+  );
+
+  server.registerTool(
+    "pool_ls",
+    {
+      description: "List pooled Claude and Codex accounts with active and needs-reauth flags. Labels and status only; never credential material.",
+      inputSchema: {},
+    },
+    async () => {
+      const cap = await captureCli(() => cmdLs());
+      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
+    },
+  );
+
+  server.registerTool(
+    "pool_status",
+    {
+      description: "Show pool usage bars via the free /usage path. Never opens 5h windows. Do not request --force; that tool does not exist.",
+      inputSchema: {},
+    },
+    async () => {
+      const cap = await captureCli(() => cmdStatus(false));
+      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
+    },
+  );
+
+  server.registerTool(
+    "doctor",
+    {
+      description: "Verify supervisor, hooks, timer, and credential identity health. Reports labels and pass/fail only; never returns credential blobs.",
+      inputSchema: {},
+    },
+    async () => {
+      const cap = await captureCli(() => cmdDoctor());
+      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
+    },
+  );
+
+  server.registerTool(
+    "config_get",
+    {
+      description: "Read effective config with sources, or one dotted key when key is set (e.g. thresholds.session).",
+      inputSchema: {
+        key: z.string().optional().describe("Optional dotted config key; omit for the full effective table"),
+      },
+    },
+    async ({ key }) => {
+      const args = key ? ["get", key] : [];
+      const cap = await captureCli(() => cmdConfig(args));
+      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
+    },
+  );
+
+  server.registerTool(
+    "pool_switch",
+    {
+      description: "Switch the Claude pool (or Codex when codex=true). Requires confirm=true and TOKENMAXXING_AGENT_MUTATIONS=1. Hot-swaps live Claude; Codex takes effect on next start.",
+      inputSchema: {
+        confirm: z.boolean().describe("Must be true after the user approves the mutation"),
+        selector: z.string().optional().describe("Optional account selector; omit for greedy best"),
+        codex: z.boolean().optional().describe("When true, run the Codex pool switch instead"),
+      },
+    },
+    async ({ confirm, selector, codex }) => {
+      const denied = mutationDenied(confirm);
+      if (denied) return textResult({ text: denied, isError: true });
+      const cap = await captureCli(() => (codex ? cmdCodexSwitch(selector) : cmdSwitch(selector)));
+      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
+    },
+  );
+
+  server.registerTool(
+    "pool_check",
+    {
+      description: "Run one evaluate-and-maybe-swap pass (the periodic timer path). Requires confirm=true and TOKENMAXXING_AGENT_MUTATIONS=1.",
+      inputSchema: {
+        confirm: z.boolean().describe("Must be true after the user approves the mutation"),
+      },
+    },
+    async ({ confirm }) => {
+      const denied = mutationDenied(confirm);
+      if (denied) return textResult({ text: denied, isError: true });
+      const cap = await captureCli(() => cmdCheck());
+      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
+    },
+  );
+
+  server.registerTool(
+    "config_set",
+    {
+      description: "Write a config.json override. Requires confirm=true and TOKENMAXXING_AGENT_MUTATIONS=1.",
+      inputSchema: {
+        confirm: z.boolean().describe("Must be true after the user approves the mutation"),
+        key: z.string().describe("Dotted config key"),
+        value: z.string().describe("JSON or literal string value"),
+      },
+    },
+    async ({ confirm, key, value }) => {
+      const denied = mutationDenied(confirm);
+      if (denied) return textResult({ text: denied, isError: true });
+      const cap = await captureCli(() => cmdConfig(["set", key, value]));
+      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
+    },
+  );
+
+  server.registerTool(
+    "config_unset",
+    {
+      description: "Remove a config.json override. Requires confirm=true and TOKENMAXXING_AGENT_MUTATIONS=1.",
+      inputSchema: {
+        confirm: z.boolean().describe("Must be true after the user approves the mutation"),
+        key: z.string().describe("Dotted config key"),
+      },
+    },
+    async ({ confirm, key }) => {
+      const denied = mutationDenied(confirm);
+      if (denied) return textResult({ text: denied, isError: true });
+      const cap = await captureCli(() => cmdConfig(["unset", key]));
+      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
+    },
+  );
+
+  return server;
+}
+
+/** Entrypoint for the Agent Plugin launcher (`agent-plugin/bin/tokenmaxxing-mcp`).
+ *  Exported because that bin imports this module (so `import.meta.main` is false here). */
+export async function main(): Promise<void> {
+  const ambient = refuseAmbientStoreEnv();
+  if (ambient != null) {
+    console.error(
+      `CLAUDE_CONFIG_DIR / CLAUDE_SECURESTORAGE_CONFIG_DIR is set (${ambient}): the pooled MCP surface requires the default Claude Code credential store. Unset it and retry.`,
+    );
+    process.exit(1);
+  }
+  const server = createTokenmaxxingMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("tokenmaxxing MCP server running on stdio");
+}
+
+if (import.meta.main) {
+  main().catch((e) => {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  });
+}

package/src/entries/relaypermission.ts

@@ -0,0 +1,105 @@
+// PermissionRequest hook for relay workers. When TOKENMAXXING_RELAY_SESSION is
+// set, park on a pending marker until `relay decide` writes a decision, then
+// return allow/deny. Under bypassPermissions (or when pings are disabled),
+// auto-allow without surfacing. Never blocks non-relay sessions. Always exits 0
+// with a JSON decision body Claude understands.
+
+import { delay } from "es-toolkit";
+import { z } from "zod";
+import { loadRelayConfig } from "../lib/relay/config.ts";
+import {
+  clearDecision,
+  readDecision,
+  writePendingRequest,
+} from "../lib/relay/markers.ts";
+import { permissionPingsEnabled } from "../lib/relay/modes.ts";
+import { readEntry, registryHas } from "../lib/relay/registry.ts";
+import { RELAY_SESSION_ENV } from "../lib/relay/worker.ts";
+import { log } from "../lib/log.ts";
+
+const StdinSchema = z.looseObject({
+  tool_name: z.string().optional(),
+  tool_input: z.unknown().optional(),
+  request_id: z.string().optional(),
+  permission_suggestions: z.unknown().optional(),
+});
+
+async function readStdin(): Promise<string> {
+  const chunks: Uint8Array[] = [];
+  for await (const c of Bun.stdin.stream()) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function allow(): string {
+  return JSON.stringify({ hookSpecificOutput: { hookEventName: "PermissionRequest", decision: { behavior: "allow" } } });
+}
+
+function deny(): string {
+  return JSON.stringify({ hookSpecificOutput: { hookEventName: "PermissionRequest", decision: { behavior: "deny" } } });
+}
+
+function fallbackAllow(): string {
+  // Unknown Claude envelope shapes: fail open for non-relay; for relay we still
+  // prefer an explicit decision. Default allow keeps the worker unblocked if
+  // the host never answers within timeout only after we already tried.
+  return allow();
+}
+
+export async function handleRelayPermission(input: { rawStdin: string }): Promise<string> {
+  if (process.env.TOKENMAXXING_PROBE) return allow();
+
+  const sessionId = process.env[RELAY_SESSION_ENV];
+  if (sessionId == null || sessionId === "") return allow();
+  if (!registryHas({ sessionId })) return allow();
+
+  const entry = readEntry({ sessionId });
+  if (entry != null && !permissionPingsEnabled({ mode: entry.permissionMode })) {
+    return allow();
+  }
+
+  const parsed = StdinSchema.safeParse((() => {
+    try {
+      return JSON.parse(input.rawStdin);
+    } catch {
+      return {};
+    }
+  })());
+  const requestId = parsed.success && parsed.data.request_id
+    ? parsed.data.request_id
+    : crypto.randomUUID();
+  const toolName = parsed.success ? (parsed.data.tool_name ?? "tool") : "tool";
+  const detail = parsed.success
+    ? JSON.stringify(parsed.data.tool_input ?? parsed.data).slice(0, 500)
+    : input.rawStdin.slice(0, 500);
+
+  writePendingRequest({
+    sessionId,
+    requestId,
+    summary: `Permission needed: ${toolName}`,
+    detail,
+  });
+
+  const cfg = loadRelayConfig();
+  const deadline = Date.now() + cfg.decideTimeoutMs;
+  while (Date.now() < deadline) {
+    const decision = readDecision({ sessionId, requestId });
+    if (decision != null) {
+      clearDecision({ sessionId, requestId });
+      return decision.approve ? allow() : deny();
+    }
+    await delay(50);
+  }
+  log("relay.permission_timeout", { session: sessionId.slice(0, 8), requestId: requestId.slice(0, 8) });
+  return deny();
+}
+
+export async function runRelayPermissionHook(): Promise<number> {
+  try {
+    const out = await handleRelayPermission({ rawStdin: await readStdin() });
+    process.stdout.write(out);
+  } catch (e) {
+    log("relay.permission_error", { err: e instanceof Error ? e.message : String(e) });
+    process.stdout.write(fallbackAllow());
+  }
+  return 0;
+}

package/src/entries/stophook.ts

@@ -11,6 +11,9 @@ import { z } from "zod";
 import { paths } from "../lib/paths.ts";
 import { writeFileAtomic } from "../lib/atomic.ts";
 import { evaluateAndMaybeSwap } from "../lib/decide.ts";
+import { writeTurnDoneMarker } from "../lib/relay/markers.ts";
+import { registryHas } from "../lib/relay/registry.ts";
+import { RELAY_SESSION_ENV } from "../lib/relay/worker.ts";
 import { RespawnMarkerSchema } from "../lib/types.ts";
 import { log } from "../lib/log.ts";
 
@@ -41,6 +44,14 @@ export async function runStopHook(): Promise<number> {
   const pinnedSid = process.env.TOKENMAXXING_SESSION_ID;
 
   try {
+    // Additive relay turn-done marker (never writes into respawn/). Only when
+    // a registry entry exists for this relay session.
+    const relaySid = process.env[RELAY_SESSION_ENV];
+    if (relaySid != null && registryHas({ sessionId: relaySid })) {
+      writeTurnDoneMarker({ sessionId: relaySid, source: "claude-stop" });
+      log("stop.relay_turn_done", { session: relaySid.slice(0, 8) });
+    }
+
     // Anticipatory depleted swaps are only sane when the respawn marker below
     // will actually pause the session until the reset.
     const canPause = process.env.TOKENMAXXING_SUPERVISED === "1" && pinnedSid != null;

package/src/lib/decide.ts

@@ -42,8 +42,7 @@ const SwapDecisionSchema = z.object({
   reason: z.string(),
   /** set when every account is depleted and the soonest recovery is known:
    *  epoch ms that account recovers. The wait target on depleted-wait;
-   *  informational on a bare all-depleted (callers like `xx serve` park on
-   *  it - nothing here waits). */
+   *  informational on a bare all-depleted (nothing here waits). */
   waitUntil: z.number().optional(),
 });
 export type SwapDecision = z.infer<typeof SwapDecisionSchema>;
@@ -318,8 +317,7 @@ export async function evaluateAndMaybeSwap(now = Date.now(), anticipatory = fals
     // truly walled do we fall through to the depleted-wait park below. The wall
     // reading is the statusLine's authoritative rate_limits tee (the same data
     // /rate-limit-options renders); a single-turn overshoot is caught one
-    // boundary later by the check timer or the next Stop hook, and the serve/SDK
-    // path additionally stamps observed limits on errored results.
+    // boundary later by the check timer or the next Stop hook.
     const hardCtx = { now, thresholds: hardBars(cfg), currentAccountUuid: null, switchFamilies };
     const seat = seatOf(loadAccounts());
     if (seat && !seat.needsReauth && !isExhausted(seat, hardCtx)) {

package/src/lib/install.ts

@@ -2,7 +2,7 @@
 // The wrapper is a 2-line `exec ... __supervise "$@"` shim so dispatch never
 // depends on argv0 semantics.
 
-import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
+import { accessSync, appendFileSync, constants, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { escape } from "es-toolkit";
 import { z } from "zod";
@@ -54,6 +54,38 @@ export function skipImperativeTimer(): boolean {
   return EnvFlagSchema.parse(process.env.TOKENMAXXING_SKIP_TIMER) != null;
 }
 
+function isNixStorePath(path: string): boolean {
+  return path === "/nix/store" || path.startsWith("/nix/store/");
+}
+
+function isEacces(e: unknown): boolean {
+  return typeof e === "object" && e != null && "code" in e && e.code === "EACCES";
+}
+
+/** Home Manager (and similar) point ~/.zshrc at a nix-store file. Writing
+ *  through that symlink throws EACCES; soft-skip instead. Still write through
+ *  ordinary writable symlink targets (PR #36). */
+function cannotWriteRcTarget(target: string): boolean {
+  if (EnvFlagSchema.parse(process.env.TOKENMAXXING_SKIP_SHELL_RC) != null) return true;
+  if (isNixStorePath(target)) return true;
+  if (!existsSync(target)) return false;
+  try {
+    accessSync(target, constants.W_OK);
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+/** User-facing lines when ensurePathInRc soft-skips a managed shell rc. */
+export function managedShellRcSkipLines(): { headline: string; detail: string; exportLine: string } {
+  return {
+    headline: "shell rc is managed (Home Manager / nix-store) - PATH was not auto-edited",
+    detail: `put ${paths.binDir} on PATH via home.sessionPath (programs.tokenmaxxing Home Manager module sets this), e.g.`,
+    exportLine: `home.sessionPath = [ "${paths.binDir}" ];`,
+  };
+}
+
 /** Nix supervisor shim: prefer a PATH-stable `tokenmaxxing` (profile /
  *  current-system, excluding this binDir) so upgrades/GC of an old store
  *  generation stay reachable; fall back to bun+entry for the rare
@@ -394,8 +426,11 @@ export function shellRcPath(): string | null {
 const PATH_LINE_MARK = "# tokenmaxxing PATH";
 
 /** Idempotently append the supervisor-bin PATH line to `rc` (created if absent).
- *  A pre-existing hand-added line for the bin dir also counts as present. */
-export function ensurePathInRc(rc: string): "added" | "present" {
+ *  A pre-existing hand-added line for the bin dir also counts as present.
+ *  Returns `"skipped"` when the resolved target is immutable (nix-store /
+ *  non-writable / TOKENMAXXING_SKIP_SHELL_RC) so callers can print guidance
+ *  instead of surfacing EACCES. */
+export function ensurePathInRc(rc: string): "added" | "present" | "skipped" {
   const dir = paths.binDir.startsWith(`${HOME}/`) ? `$HOME${paths.binDir.slice(HOME.length)}` : paths.binDir;
   // Write through a dotfile-managed symlink, never over it: writeFileAtomic
   // renames a sibling temp over its target, which would replace the link with
@@ -413,17 +448,29 @@ export function ensurePathInRc(rc: string): "added" | "present" {
   // relocation.
   const kept = lines.filter((line) => isCurrentExport(line) || !line.includes(PATH_LINE_MARK));
   if (kept.length !== lines.length) {
+    if (cannotWriteRcTarget(target)) return "skipped";
     const body = kept.join("\n");
     const sep0 = body === "" || body.endsWith("\n") ? "" : "\n";
     const addition = kept.some(isCurrentExport) ? "" : `export PATH="${dir}:$PATH" ${PATH_LINE_MARK}\n`;
     // preserve the rc's own mode: writeFileAtomic defaults to 0600, which
     // would silently tighten a normally 0644 shell rc (PR #36 review catch)
-    writeFileAtomic(target, `${body}${sep0}${addition}`, statSync(target).mode & 0o777);
+    try {
+      writeFileAtomic(target, `${body}${sep0}${addition}`, statSync(target).mode & 0o777);
+    } catch (e) {
+      if (isEacces(e)) return "skipped";
+      throw e;
+    }
     return "added";
   }
   if (lines.some(isCurrentExport)) return "present";
+  if (cannotWriteRcTarget(target)) return "skipped";
   const sep = current === "" || current.endsWith("\n") ? "" : "\n";
-  appendFileSync(target, `${sep}export PATH="${dir}:$PATH" ${PATH_LINE_MARK}\n`);
+  try {
+    appendFileSync(target, `${sep}export PATH="${dir}:$PATH" ${PATH_LINE_MARK}\n`);
+  } catch (e) {
+    if (isEacces(e)) return "skipped";
+    throw e;
+  }
   return "added";
 }
 
@@ -468,7 +515,8 @@ export function findClaudeShadowers(rcText: string): ShellShadower[] {
  *  PATH` line pointing at an emptied binDir is exactly how the supervisor
  *  recursion incident started (.memory/supervisor-recursion-guards.md), so
  *  uninstall must not leave one behind (closing-review catch).
- *  Returns true when a line was removed. */
+ *  Returns true when a line was removed. Soft-skips (returns false, no throw)
+ *  when the resolved target is immutable. */
 export function removePathFromRc(rc: string): boolean {
   if (!existsSync(rc)) return false;
   // same symlink + mode treatment as ensurePathInRc: write through a
@@ -477,7 +525,13 @@ export function removePathFromRc(rc: string): boolean {
   const lines = readFileSync(target, "utf8").split("\n");
   const kept = lines.filter((line) => !line.includes(PATH_LINE_MARK));
   if (kept.length === lines.length) return false;
-  writeFileAtomic(target, kept.join("\n"), statSync(target).mode & 0o777);
+  if (cannotWriteRcTarget(target)) return false;
+  try {
+    writeFileAtomic(target, kept.join("\n"), statSync(target).mode & 0o777);
+  } catch (e) {
+    if (isEacces(e)) return false;
+    throw e;
+  }
   return true;
 }
 

package/src/lib/lock.ts

@@ -4,13 +4,9 @@
 // process exit).
 //
 // The acquire is NON-BLOCKING (LOCK_EX|LOCK_NB) with an async retry loop: a
-// blocking LOCK_EX from this runtime freezes the whole event loop, and in
-// `xx serve` (many actors, one process) a second actor's blocking acquire
-// would stop the holder from ever resuming to release - a true single-process
-// deadlock; a cross-process holder would freeze the daemon for its whole
-// critical section (adversarial review catch, 2026-07-19). EWOULDBLOCK is
-// told apart from real failures via errno, so a bad fd still fails fast
-// instead of spinning.
+// blocking LOCK_EX from this runtime freezes the whole event loop.
+// EWOULDBLOCK is told apart from real failures via errno, so a bad fd still
+// fails fast instead of spinning.
 
 import { closeSync, mkdirSync, openSync } from "node:fs";
 import { dirname } from "node:path";

package/src/lib/log.ts

@@ -18,10 +18,9 @@ function redact(s: string): string {
 
 let echo: ((input: { event: string; parts: string }) => void) | null = null;
 
-/** Tee every subsequent log() line to a terminal printer. Only the serve
- *  daemon opts in: hooks and the statusline own their stdout protocol, so the
- *  echo stays off by default. The printer receives the same redacted parts the
- *  file line gets. */
+/** Tee every subsequent log() line to a terminal printer. Off by default
+ *  (hooks and the statusline own their stdout protocol). The printer receives
+ *  the same redacted parts the file line gets. */
 export function setLogEcho(input: { printer: (input: { event: string; parts: string }) => void }): void {
   echo = input.printer;
 }
@@ -36,10 +35,9 @@ export function log(event: string, fields: Record<string, unknown> = {}): void {
       })
       .join(" ");
     mkdirSync(dirname(paths.logFile), { recursive: true });
-    // Rotation cap: the check timer logs every 180s and the serve daemon
-    // echoes every event, so an uncapped append-only file grows forever on a
-    // live install (closing-review critic gap). One .old generation bounds
-    // total disk at ~2x the cap; older history is disposable diagnostics.
+    // Rotation cap: the check timer logs every 180s, so an uncapped
+    // append-only file grows forever on a live install. One .old generation
+    // bounds total disk at ~2x the cap; older history is disposable diagnostics.
     if (existsSync(paths.logFile) && statSync(paths.logFile).size > LOG_MAX_BYTES) {
       renameSync(paths.logFile, `${paths.logFile}.old`);
     }
@@ -47,11 +45,10 @@ export function log(event: string, fields: Record<string, unknown> = {}): void {
   } catch {
     // logging must never throw into a hook / supervisor path
   }
-  // separate from the file sink: an unwritable log file must not also silence
-  // the terminal echo (that is exactly when the daemon needs to stay visible).
+  // separate from the file sink: an unwritable log file must not also silence the echo.
   try {
     echo?.({ event, parts: line });
   } catch {
-    // the echo printer must never throw into the daemon either
+    // the echo printer must never throw into a caller path
   }
 }

package/src/lib/paths.ts

@@ -36,15 +36,9 @@ export const paths = {
   sampleDir: join(TM_HOME, "sample"),
   /** linux only: parked credential .json files (0700 dir, 0600 files). */
   credsDir: join(TM_HOME, "creds"),
-
-  /** `xx serve` slack bridge: tokens + channel->repo links (0600: holds the
-   *  xoxb-/xapp- tokens), per-thread claude session records, and the
-   *  single-instance flock (a new daemon generation blocks on it until the
-   *  previous one - possibly still draining an in-flight turn - fully exits,
-   *  so two generations never act on the same thread records or cwd). */
-  slackJson: join(TM_HOME, "slack.json"),
-  slackThreadsDir: join(TM_HOME, "slack-threads"),
-  serveLockFile: join(TM_HOME, "serve-lock"),
+  /** Durable tmux relay companion: config + per-session state (not respawn/). */
+  relayJson: join(TM_HOME, "relay.json"),
+  relayDir: join(TM_HOME, "relay"),
 
   /** ~/.claude.json - holds the active `oauthAccount` identity object. */
   claudeJson: env("TOKENMAXXING_CLAUDE_JSON", join(HOME, ".claude.json")),