tokenmaxxing 1.7.0 → 1.8.0

package/src/entries/codexstophook.ts

@@ -25,6 +25,9 @@ import { loadConfig } from "../lib/state.ts";
 import { effectiveBars } from "../lib/picker.ts";
 import { CODEX_SUPERVISOR_ID_ENV } from "./codexsupervisor.ts";
 import { CodexReconcileMarkerSchema, CodexRespawnMarkerSchema, CodexStopStdinSchema, type CodexAccount } from "../lib/types.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 { log } from "../lib/log.ts";
 
 const SupervisorIdSchema = z.string().min(1).optional().catch(undefined);
@@ -138,6 +141,13 @@ export async function handleCodexStop(input: { rawStdin: string }): Promise<void
   const sessionId = parsed.success ? (parsed.data.session_id ?? null) : null;
 
   try {
+    // Additive relay turn-done marker (never writes into respawn/).
+    const relaySid = process.env[RELAY_SESSION_ENV];
+    if (relaySid != null && registryHas({ sessionId: relaySid })) {
+      writeTurnDoneMarker({ sessionId: relaySid, source: "codex-stop" });
+      log("codexstop.relay_turn_done", { session: relaySid.slice(0, 8) });
+    }
+
     // No supervisor = no decision AT ALL, checked before evaluate can swap:
     // hooks.json is global, so this hook also fires in sessions launched
     // around the PATH shim (IDE extension, absolute path), and a swap with

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/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/paths.ts

@@ -36,6 +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"),
+  /** 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")),

package/src/lib/relay/config.ts

@@ -0,0 +1,84 @@
+// $TOKENMAXXING_HOME/relay.json - sparse overrides merged with defaults.
+
+import { existsSync, readFileSync } from "node:fs";
+import { z } from "zod";
+import { paths } from "../paths.ts";
+import { writeFileAtomic } from "../atomic.ts";
+import { ClaudePermissionModeSchema } from "./modes.ts";
+
+const WorkerSchema = z.enum(["claude", "codex"]);
+export type RelayWorker = z.infer<typeof WorkerSchema>;
+
+const HostsSchema = z.object({
+  cursor: z.object({ model: z.string().min(1).optional() }).default({}),
+  claude: z.object({ model: z.string().min(1).optional() }).default({}),
+}).default({ cursor: {}, claude: {} });
+
+export const RelayConfigFileSchema = z.object({
+  defaultWorker: WorkerSchema.optional(),
+  defaultPermissionMode: ClaudePermissionModeSchema.optional(),
+  turnTimeoutMs: z.number().int().positive().optional(),
+  decideTimeoutMs: z.number().int().positive().optional(),
+  idleTtlMs: z.number().int().positive().optional(),
+  sameSessionBusyMs: z.number().int().positive().optional(),
+  sessionPrefix: z.string().min(1).optional(),
+  hosts: HostsSchema.optional(),
+});
+export type RelayConfigFile = z.infer<typeof RelayConfigFileSchema>;
+
+export const RelayConfigSchema = z.object({
+  defaultWorker: WorkerSchema,
+  defaultPermissionMode: ClaudePermissionModeSchema,
+  turnTimeoutMs: z.number().int().positive(),
+  decideTimeoutMs: z.number().int().positive(),
+  idleTtlMs: z.number().int().positive(),
+  sameSessionBusyMs: z.number().int().positive(),
+  sessionPrefix: z.string().min(1),
+  hosts: z.object({
+    cursor: z.object({ model: z.string().min(1).optional() }),
+    claude: z.object({ model: z.string().min(1).optional() }),
+  }),
+});
+export type RelayConfig = z.infer<typeof RelayConfigSchema>;
+
+export const DEFAULT_RELAY_CONFIG: RelayConfig = {
+  defaultWorker: "claude",
+  defaultPermissionMode: "auto",
+  turnTimeoutMs: 30 * 60 * 1000,
+  decideTimeoutMs: 30 * 60 * 1000,
+  idleTtlMs: 60 * 60 * 1000,
+  sameSessionBusyMs: 50,
+  sessionPrefix: "xx-relay-",
+  hosts: { cursor: {}, claude: {} },
+};
+
+export function loadRelayConfig(): RelayConfig {
+  if (!existsSync(paths.relayJson)) return DEFAULT_RELAY_CONFIG;
+  const raw = RelayConfigFileSchema.parse(JSON.parse(readFileSync(paths.relayJson, "utf8")));
+  return RelayConfigSchema.parse({
+    ...DEFAULT_RELAY_CONFIG,
+    ...raw,
+    hosts: {
+      cursor: { ...DEFAULT_RELAY_CONFIG.hosts.cursor, ...raw.hosts?.cursor },
+      claude: { ...DEFAULT_RELAY_CONFIG.hosts.claude, ...raw.hosts?.claude },
+    },
+    defaultPermissionMode: raw.defaultPermissionMode ?? DEFAULT_RELAY_CONFIG.defaultPermissionMode,
+  });
+}
+
+export function writeRelayConfig(input: { file: RelayConfigFile }): void {
+  const validated = RelayConfigFileSchema.parse(input.file);
+  writeFileAtomic(paths.relayJson, JSON.stringify(validated, null, 2) + "\n");
+}
+
+export function mergeRelayConfigFile(input: { patch: RelayConfigFile }): RelayConfig {
+  const existing = existsSync(paths.relayJson)
+    ? RelayConfigFileSchema.parse(JSON.parse(readFileSync(paths.relayJson, "utf8")))
+    : {};
+  const next = RelayConfigFileSchema.parse({ ...existing, ...input.patch, hosts: {
+    cursor: { ...existing.hosts?.cursor, ...input.patch.hosts?.cursor },
+    claude: { ...existing.hosts?.claude, ...input.patch.hosts?.claude },
+  } });
+  writeRelayConfig({ file: next });
+  return loadRelayConfig();
+}

package/src/lib/relay/decide.ts

@@ -0,0 +1,75 @@
+// relay decide: approve/deny a pending permission ping and resume the wait.
+
+import { delay } from "es-toolkit";
+import { loadRelayConfig } from "./config.ts";
+import {
+  clearPendingRequest,
+  listPendingRequests,
+  readPendingRequest,
+  writeDecision,
+} from "./markers.ts";
+import { runTurn, type TurnResult } from "./turn.ts";
+import { readEntry, touchEntry, withSessionLock } from "./registry.ts";
+
+export type DecideParams = {
+  sessionId: string;
+  requestId?: string;
+  approve: boolean;
+  /** After writing the decision, wait for turn-done or the next ping. */
+  wait?: boolean;
+  cwd?: string;
+  timeoutMs?: number;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+};
+
+export async function runDecide(input: DecideParams): Promise<{
+  decisionWritten: boolean;
+  requestId: string;
+  turn?: TurnResult;
+}> {
+  const entry = readEntry({ sessionId: input.sessionId });
+  if (entry == null) throw new Error(`relay session not found: ${input.sessionId}`);
+
+  let requestId = input.requestId ?? entry.pendingRequestId;
+  if (requestId == null) {
+    const pending = listPendingRequests({ sessionId: input.sessionId });
+    requestId = pending[0]?.requestId;
+  }
+  if (requestId == null) throw new Error(`no pending permission request for session ${input.sessionId}`);
+
+  const pending = readPendingRequest({ sessionId: input.sessionId, requestId });
+  if (pending == null) throw new Error(`pending request not found: ${requestId}`);
+
+  writeDecision({
+    sessionId: input.sessionId,
+    requestId,
+    approve: input.approve,
+    now: (input.now ?? Date.now)(),
+  });
+  clearPendingRequest({ sessionId: input.sessionId, requestId });
+  await withSessionLock({
+    sessionId: input.sessionId,
+    fn: () => touchEntry({
+      sessionId: input.sessionId,
+      state: "running",
+      pendingRequestId: null,
+      now: (input.now ?? Date.now)(),
+    }),
+  });
+
+  if (input.wait === false) {
+    return { decisionWritten: true, requestId };
+  }
+
+  const cfg = loadRelayConfig();
+  const turn = await runTurn({
+    sessionId: input.sessionId,
+    cwd: input.cwd ?? entry.cwd,
+    waitOnly: true,
+    timeoutMs: input.timeoutMs ?? cfg.decideTimeoutMs,
+    now: input.now,
+    sleep: input.sleep ?? delay,
+  });
+  return { decisionWritten: true, requestId, turn };
+}

package/src/lib/relay/gc.ts

@@ -0,0 +1,80 @@
+// relay destroy / gc / status. Exact tmux session names only; never pattern-kill.
+
+import { rmSync } from "node:fs";
+import { loadRelayConfig } from "./config.ts";
+import { clearSessionMarkers } from "./markers.ts";
+import {
+  deleteEntry,
+  listEntries,
+  readEntry,
+  sessionLockPath,
+  withSessionLock,
+  type RelayRegistryEntry,
+} from "./registry.ts";
+import { getTmux } from "./tmux.ts";
+
+export async function destroySession(input: { sessionId: string }): Promise<boolean> {
+  const entry = readEntry({ sessionId: input.sessionId });
+  if (entry == null) {
+    // Still try exact tmux name from config prefix in case registry was lost.
+    return false;
+  }
+  await withSessionLock({
+    sessionId: input.sessionId,
+    fn: () => {
+      getTmux().killSession({ name: entry.tmuxName });
+      clearSessionMarkers({ sessionId: input.sessionId });
+      deleteEntry({ sessionId: input.sessionId });
+      rmSync(sessionLockPath({ sessionId: input.sessionId }), { force: true });
+    },
+  });
+  return true;
+}
+
+export type GcResult = {
+  reaped: string[];
+  kept: string[];
+};
+
+/** Reap dead tmux sessions and idle sessions past idleTtlMs. */
+export async function gcSessions(input: { now?: number; idleTtlMs?: number } = {}): Promise<GcResult> {
+  const cfg = loadRelayConfig();
+  const now = input.now ?? Date.now();
+  const idleTtlMs = input.idleTtlMs ?? cfg.idleTtlMs;
+  const reaped: string[] = [];
+  const kept: string[] = [];
+  const tmux = getTmux();
+
+  for (const entry of listEntries()) {
+    const alive = tmux.hasSession({ name: entry.tmuxName });
+    const idleTooLong = now - entry.lastActiveAt > idleTtlMs;
+    if (!alive || idleTooLong || entry.state === "destroyed") {
+      await destroySession({ sessionId: entry.sessionId });
+      reaped.push(entry.sessionId);
+      continue;
+    }
+    kept.push(entry.sessionId);
+  }
+  return { reaped, kept };
+}
+
+export function statusSessions(): RelayRegistryEntry[] {
+  const tmux = getTmux();
+  return listEntries().map((entry) => ({
+    ...entry,
+    // annotate liveness in a non-schema field via spread for printers; keep schema pure
+  })).map((entry) => {
+    void tmux.hasSession({ name: entry.tmuxName });
+    return entry;
+  });
+}
+
+export type StatusRow = RelayRegistryEntry & { tmuxAlive: boolean };
+
+export function statusRows(): StatusRow[] {
+  const tmux = getTmux();
+  return listEntries().map((entry) => ({
+    ...entry,
+    tmuxAlive: tmux.hasSession({ name: entry.tmuxName }),
+  }));
+}

package/src/lib/relay/install.ts

@@ -0,0 +1,143 @@
+// relay install: write thin host agent templates + optional hook snippets.
+// Merge only tokenmaxxing-owned keys.
+
+import { existsSync, mkdirSync, readFileSync, cpSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { writeFileAtomic } from "../atomic.ts";
+import { paths } from "../paths.ts";
+import { isOurHookCommand } from "../settings.ts";
+
+const pluginRoot = () => join(import.meta.dir, "../../../agent-plugin");
+
+function repoAgentsDir(): string {
+  return join(pluginRoot(), "agents");
+}
+
+function repoSkillDir(): string {
+  return join(pluginRoot(), "skills", "relay-session");
+}
+
+function repoHooksDir(): string {
+  return join(pluginRoot(), "hooks");
+}
+
+export type InstallTarget = "cursor" | "claude" | "all";
+
+export type InstallResult = {
+  agentsWritten: string[];
+  skillWritten: boolean;
+  hooksMerged: string[];
+};
+
+function copyAgent(input: { name: string; destDir: string }): string {
+  mkdirSync(input.destDir, { recursive: true });
+  const src = join(repoAgentsDir(), input.name);
+  const dest = join(input.destDir, input.name);
+  if (!existsSync(src)) throw new Error(`missing agent template: ${src}`);
+  cpSync(src, dest);
+  return dest;
+}
+
+function copySkill(input: { destDir: string }): boolean {
+  const src = repoSkillDir();
+  if (!existsSync(src)) return false;
+  mkdirSync(input.destDir, { recursive: true });
+  cpSync(src, input.destDir, { recursive: true });
+  return true;
+}
+
+const CursorHooksSchema = z.looseObject({
+  version: z.number().optional(),
+  hooks: z.record(z.string(), z.unknown()).optional(),
+});
+
+const TOKENMAXXING_HOOK_KEY = "tokenmaxxingRelay";
+
+/** Merge Cursor hooks.json: only the tokenmaxxingRelay key is ours. */
+export function mergeCursorHooks(input: { hooksPath: string }): boolean {
+  const snippetPath = join(repoHooksDir(), "cursor-relay.json");
+  if (!existsSync(snippetPath)) return false;
+  const snippet = CursorHooksSchema.parse(JSON.parse(readFileSync(snippetPath, "utf8")));
+  let existing: z.infer<typeof CursorHooksSchema> = { version: 1, hooks: {} };
+  if (existsSync(input.hooksPath)) {
+    try {
+      existing = CursorHooksSchema.parse(JSON.parse(readFileSync(input.hooksPath, "utf8")));
+    } catch {
+      existing = { version: 1, hooks: {} };
+    }
+  }
+  existing.hooks ??= {};
+  const ours = snippet.hooks?.[TOKENMAXXING_HOOK_KEY];
+  if (ours === undefined) return false;
+  existing.hooks[TOKENMAXXING_HOOK_KEY] = ours;
+  mkdirSync(dirname(input.hooksPath), { recursive: true });
+  writeFileAtomic(input.hooksPath, JSON.stringify(existing, null, 2) + "\n");
+  return true;
+}
+
+const ClaudeSettingsLoose = z.looseObject({
+  hooks: z.record(z.string(), z.array(z.looseObject({
+    matcher: z.string().optional(),
+    hooks: z.array(z.looseObject({ type: z.string(), command: z.string() })).default([]),
+  }))).optional(),
+});
+
+const RELAY_PERM_SUB = "__relay-permission-hook";
+
+/** Append PermissionRequest hook for relay; never remove foreign hooks. */
+export function mergeClaudeRelayPermissionHook(input: { settingsPath?: string } = {}): boolean {
+  const settingsPath = input.settingsPath ?? paths.claudeSettings;
+  const bin = join(paths.binDir, "tokenmaxxing");
+  const command = `${JSON.stringify(bin)} ${RELAY_PERM_SUB}`;
+  let settings: z.infer<typeof ClaudeSettingsLoose> = {};
+  if (existsSync(settingsPath)) {
+    settings = ClaudeSettingsLoose.parse(JSON.parse(readFileSync(settingsPath, "utf8")));
+  }
+  settings.hooks ??= {};
+  settings.hooks.PermissionRequest ??= [];
+  const arr = settings.hooks.PermissionRequest;
+  const present = arr.some((g) => g.hooks.some((h) => h.command === command || isOurHookCommand(h.command, RELAY_PERM_SUB)));
+  if (!present) {
+    arr.push({ hooks: [{ type: "command", command }] });
+  }
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  const mode = existsSync(settingsPath) ? 0o600 : 0o600;
+  writeFileAtomic(settingsPath, JSON.stringify(settings, null, 2) + "\n", mode);
+  return true;
+}
+
+export function installRelayHosts(input: {
+  target: InstallTarget;
+  cursorAgentsDir?: string;
+  claudeAgentsDir?: string;
+  cursorHooksPath?: string;
+  mergeHooks?: boolean;
+}): InstallResult {
+  const home = process.env.HOME ?? "";
+  const cursorAgents = input.cursorAgentsDir ?? join(home, ".cursor", "agents");
+  const claudeAgents = input.claudeAgentsDir ?? join(home, ".claude", "agents");
+  const agentsWritten: string[] = [];
+  const hooksMerged: string[] = [];
+  let skillWritten = false;
+
+  if (input.target === "cursor" || input.target === "all") {
+    agentsWritten.push(copyAgent({ name: "tokenmaxxing-claude.md", destDir: cursorAgents }));
+    agentsWritten.push(copyAgent({ name: "tokenmaxxing-codex.md", destDir: cursorAgents }));
+    skillWritten = copySkill({ destDir: join(home, ".cursor", "skills", "relay-session") }) || skillWritten;
+    if (input.mergeHooks !== false) {
+      const hooksPath = input.cursorHooksPath ?? join(home, ".cursor", "hooks.json");
+      if (mergeCursorHooks({ hooksPath })) hooksMerged.push(hooksPath);
+    }
+  }
+  if (input.target === "claude" || input.target === "all") {
+    agentsWritten.push(copyAgent({ name: "tokenmaxxing-claude.md", destDir: claudeAgents }));
+    agentsWritten.push(copyAgent({ name: "tokenmaxxing-codex.md", destDir: claudeAgents }));
+    if (input.mergeHooks !== false) {
+      if (mergeClaudeRelayPermissionHook()) hooksMerged.push(paths.claudeSettings);
+    }
+  }
+  return { agentsWritten, skillWritten, hooksMerged };
+}
+
+export { RELAY_PERM_SUB };