@huynle/hub 0.6.0 → 0.7.1

package/packages/claude-code/src/launcher.ts

@@ -0,0 +1,265 @@
+// ClaudeLauncher: the Claude Code processes the daemon starts for hub launches (feature "launch", report v0hsdqhm).
+// Each runs headless in the launch's workspace: `claude --plugin-dir <hub plugin> --session-id <uuid> -p
+// --input-format stream-json --output-format stream-json --verbose [--model m] [--agent a]`, so its hooks reach the
+// daemon like any `hub claude` run (HUB_CLAUDE_LAUNCH, HUB_CLAUDE_SOCKET), a turn is a user message written to its
+// stdin, the turn's end is the result line on its stdout, and an interrupt is a control request (Esc has no hook,
+// a control request works). Turns are answered in order (Claude Code runs queued user messages one after another).
+// When claude exits its open turns fail and onExit reports it; stopAll closes stdin (claude ends after the running
+// turn) and kills what lingers.
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process"
+import { realpathSync, statSync } from "node:fs"
+import path from "node:path"
+import type { ModelSelection, PromptImage, TurnResult } from "../../protocol/src/index.ts"
+
+type Env = Readonly<Record<string, string | undefined>>
+
+export interface LauncherOptions {
+  /** The claude executable. */
+  readonly bin: string
+  /** The environment claude starts with (the daemon's), before the hub's variables. */
+  readonly env: Env
+  /** A launched claude exited (its sessions end). */
+  readonly onExit?: (sessionID: string, code: number | null) => void
+  readonly log?: (line: string) => void
+}
+
+export interface LaunchInput {
+  /** The Claude Code session UUID (--session-id). */
+  readonly sessionID: string
+  /** The prepared workspace (claude's cwd). */
+  readonly directory: string
+  /** The launch key its hooks report (HUB_CLAUDE_LAUNCH). */
+  readonly launch: string
+  readonly pluginDir: string
+  readonly socketPath: string
+  readonly model?: string
+  readonly agent?: string
+}
+
+interface Turn {
+  resolve(result: TurnResult): void
+  interrupted: boolean
+}
+
+interface Proc {
+  readonly child: ChildProcessWithoutNullStreams
+  readonly turns: Turn[]
+  readonly controls: Map<string, () => void>
+  readonly exited: Promise<void>
+  stderr: string
+}
+
+const INTERRUPTED = "Interrupted from the hub"
+const CONTROL_WAIT_MS = 5000
+const STOP_GRACE_MS = 2000
+const KILL_GRACE_MS = 1000
+const LINE_MAX = 16 * 1024 * 1024
+const STDERR_KEEP = 2000
+
+const record = (v: unknown): Record<string, any> => (typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Record<string, any>) : {})
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
+
+const AGENT = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/
+const MODEL = /^[A-Za-z0-9][A-Za-z0-9._:@/\[\]-]{0,299}$/
+/** The providers whose models Claude Code runs (its own model IDs or aliases). */
+const PROVIDERS = new Set(["anthropic", "claude-code"])
+
+/**
+ * The real path of a launch's directory: an existing directory under one of the node's workspace roots (both
+ * resolved through symlinks). Throws with the reason otherwise.
+ */
+export function launchDirectory(directory: string, roots: readonly string[]): string {
+  if (typeof directory !== "string" || !path.isAbsolute(directory) || directory.split("/").some((part) => part === "." || part === "..")) {
+    throw new Error(`${JSON.stringify(directory)} is not an absolute path without . or .. segments`)
+  }
+  let real: string
+  try {
+    real = realpathSync(directory)
+  } catch {
+    throw new Error(`${directory} does not exist`)
+  }
+  if (!statSync(real).isDirectory()) throw new Error(`${directory} is not a directory`)
+  for (const root of roots) {
+    let base: string
+    try {
+      base = realpathSync(root)
+    } catch {
+      continue
+    }
+    if (real === base || real.startsWith(base.endsWith(path.sep) ? base : base + path.sep)) return real
+  }
+  throw new Error(`${directory} is not under this machine's node workspace roots (node.json workspaceRoots${roots.length ? `: ${roots.join(", ")}` : ", none set"})`)
+}
+
+/** The --agent value for a launch's agent; throws for a name Claude Code could read as an option. */
+export function launchAgent(agent: string | undefined): string | undefined {
+  if (agent === undefined) return undefined
+  if (!AGENT.test(agent)) throw new Error(`Claude Code cannot take agent ${JSON.stringify(agent)} (letters, digits, ".", "_" and "-")`)
+  return agent
+}
+
+/** The --model value for a launch's model; throws for another provider's model or a name that is not a model ID. */
+export function launchModel(model: ModelSelection | undefined): string | undefined {
+  if (model === undefined) return undefined
+  if (!PROVIDERS.has(model.providerID)) throw new Error(`Claude Code cannot run model ${model.providerID}/${model.modelID} (only anthropic models)`)
+  if (!MODEL.test(model.modelID)) throw new Error(`Claude Code cannot take model ${JSON.stringify(model.modelID)}`)
+  return model.modelID
+}
+
+/** The claude arguments of a headless launch. */
+export function launchArgs(input: LaunchInput): string[] {
+  return [
+    "--plugin-dir",
+    input.pluginDir,
+    "--session-id",
+    input.sessionID,
+    "-p",
+    "--input-format",
+    "stream-json",
+    "--output-format",
+    "stream-json",
+    "--verbose",
+    ...(input.model ? ["--model", input.model] : []),
+    ...(input.agent ? ["--agent", input.agent] : []),
+  ]
+}
+
+/** A stream-json user message. */
+export function userMessage(sessionID: string, text: string, images: readonly PromptImage[] = []): Record<string, unknown> {
+  const content = images.length
+    ? [...(text ? [{ type: "text", text }] : []), ...images.map((image) => ({ type: "image", source: { type: "base64", media_type: image.mime, data: image.data } }))]
+    : text
+  return { type: "user", message: { role: "user", content }, parent_tool_use_id: null, session_id: sessionID }
+}
+
+/** The turn's result for a stream-json result line. */
+export function turnResult(line: Record<string, any>, interrupted: boolean): TurnResult {
+  const reply = typeof line.result === "string" ? line.result : ""
+  if (line.subtype === "success" && line.is_error !== true) return { outcome: "succeeded", reply }
+  if (interrupted) return { outcome: "interrupted", message: INTERRUPTED, reply: "" }
+  const errors = Array.isArray(line.errors) ? line.errors.filter((e: unknown): e is string => typeof e === "string") : []
+  return { outcome: "failed", message: reply || errors.join("; ") || String(line.subtype ?? "the turn failed"), reply: "" }
+}
+
+export class ClaudeLauncher {
+  readonly #options: LauncherOptions
+  readonly #procs = new Map<string, Proc>()
+  #controlID = 0
+
+  constructor(options: LauncherOptions) {
+    this.#options = options
+  }
+
+  /** Starts claude for a launch; rejects when it cannot run (or the session already runs). */
+  async start(input: LaunchInput): Promise<void> {
+    if (this.#procs.has(input.sessionID)) throw new Error(`Session ${input.sessionID} is already running`)
+    const env: Record<string, string | undefined> = { ...this.#options.env, HUB_CLAUDE_LAUNCH: input.launch, HUB_CLAUDE_SOCKET: input.socketPath }
+    delete env.BUN_BE_BUN
+    let child: ChildProcessWithoutNullStreams
+    try {
+      child = spawn(this.#options.bin, launchArgs(input), { cwd: input.directory, env: env as NodeJS.ProcessEnv, stdio: ["pipe", "pipe", "pipe"] })
+    } catch (cause) {
+      throw new Error(`cannot run ${this.#options.bin}: ${(cause as Error).message}`)
+    }
+    await new Promise<void>((resolve, reject) => {
+      child.once("spawn", () => resolve())
+      child.once("error", (cause) => reject(new Error(`cannot run ${this.#options.bin}: ${cause.message}`)))
+    })
+    let exited!: () => void
+    const proc: Proc = { child, turns: [], controls: new Map(), exited: new Promise<void>((resolve) => (exited = resolve)), stderr: "" }
+    this.#procs.set(input.sessionID, proc)
+    child.on("error", () => {})
+    child.stdin.on("error", () => {})
+    child.stderr.setEncoding("utf8")
+    child.stderr.on("data", (chunk: string) => {
+      proc.stderr = (proc.stderr + chunk).slice(-STDERR_KEEP)
+    })
+    let buffer = ""
+    child.stdout.setEncoding("utf8")
+    child.stdout.on("data", (chunk: string) => {
+      buffer += chunk
+      let end: number
+      while ((end = buffer.indexOf("\n")) >= 0) {
+        const text = buffer.slice(0, end)
+        buffer = buffer.slice(end + 1)
+        if (text.trim()) this.#line(proc, text)
+      }
+      if (buffer.length > LINE_MAX) buffer = ""
+    })
+    child.once("exit", (code) => {
+      if (this.#procs.get(input.sessionID) === proc) this.#procs.delete(input.sessionID)
+      const detail = proc.stderr.trim().split("\n").pop()
+      const message = `Claude Code exited (code ${code ?? "none"})${detail ? `: ${detail.slice(0, 300)}` : ""}`
+      for (const turn of proc.turns.splice(0)) turn.resolve(turn.interrupted ? { outcome: "interrupted", message: INTERRUPTED, reply: "" } : { outcome: "failed", message, reply: "" })
+      for (const done of proc.controls.values()) done()
+      proc.controls.clear()
+      this.#options.log?.(`claude for ${input.sessionID} exited (code ${code ?? "none"})`)
+      exited()
+      this.#options.onExit?.(input.sessionID, code)
+    })
+  }
+
+  /** Whether the hub started this session here (and it still runs). */
+  has(sessionID: string): boolean {
+    return this.#procs.has(sessionID)
+  }
+
+  /** Whether a turn is running (or queued) in it. */
+  running(sessionID: string): boolean {
+    return (this.#procs.get(sessionID)?.turns.length ?? 0) > 0
+  }
+
+  /** Writes a user message; resolves with the turn's result. */
+  turn(sessionID: string, text: string, images: readonly PromptImage[] = []): Promise<TurnResult> {
+    const proc = this.#procs.get(sessionID)
+    if (!proc) return Promise.reject(new Error(`Session ${sessionID} was not started by the hub here (turns reach only hub-launched Claude Code sessions)`))
+    return new Promise<TurnResult>((resolve) => {
+      proc.turns.push({ resolve, interrupted: false })
+      proc.child.stdin.write(`${JSON.stringify(userMessage(sessionID, text, images))}\n`)
+    })
+  }
+
+  /** Interrupts the running turn (a control request); false when the hub did not start the session. */
+  async interrupt(sessionID: string): Promise<boolean> {
+    const proc = this.#procs.get(sessionID)
+    if (!proc) return false
+    for (const turn of proc.turns) turn.interrupted = true
+    const id = `hub_int_${++this.#controlID}`
+    const answered = new Promise<void>((resolve) => proc.controls.set(id, resolve))
+    proc.child.stdin.write(`${JSON.stringify({ type: "control_request", request_id: id, request: { subtype: "interrupt" } })}\n`)
+    await Promise.race([answered, sleep(CONTROL_WAIT_MS)])
+    proc.controls.delete(id)
+    return true
+  }
+
+  /** Ends every process: stdin closed, then SIGTERM and SIGKILL for what lingers. */
+  async stopAll(): Promise<void> {
+    const procs = [...this.#procs.values()]
+    for (const proc of procs) proc.child.stdin.end()
+    await Promise.all(
+      procs.map(async (proc) => {
+        if (await Promise.race([proc.exited.then(() => true), sleep(STOP_GRACE_MS).then(() => false)])) return
+        proc.child.kill("SIGTERM")
+        if (await Promise.race([proc.exited.then(() => true), sleep(KILL_GRACE_MS).then(() => false)])) return
+        proc.child.kill("SIGKILL")
+        await proc.exited
+      }),
+    )
+  }
+
+  #line(proc: Proc, text: string): void {
+    let line: Record<string, any>
+    try {
+      line = record(JSON.parse(text))
+    } catch {
+      return
+    }
+    if (line.type === "result") {
+      const turn = proc.turns.shift()
+      turn?.resolve(turnResult(line, turn.interrupted))
+    } else if (line.type === "control_response") {
+      const id = record(line.response).request_id
+      if (typeof id === "string") proc.controls.get(id)?.()
+    }
+  }
+}

package/packages/claude-code/src/main.ts

@@ -0,0 +1,127 @@
+// `hub claude-code <daemon | hook | mcp>`: the Claude Code spoke's own processes, run by `hub claude` (the daemon)
+// and by the plugin (the hook bridge, the MCP pipe), never typed by hand in normal use.
+//   daemon  the per-user daemon until SIGINT/SIGTERM (needs an enrolled machine: the machine token in the spoke's
+//           config.json, read-only); with the Claude Code CLI found it also starts Claude Code for hub launches
+//           (daemonLaunchOptions)
+//   hook    the hook bridge (stdin: the hook's JSON; --rewake, --wait <seconds>)
+//   mcp     the MCP pipe on stdio
+import { spawnSync } from "node:child_process"
+import { realpathSync } from "node:fs"
+import { configPath } from "../../../src/config.ts"
+import { nodeConfigPath, readNodeConfig, readSpokeCredentials } from "../../node/src/config.ts"
+import { findExecutable } from "../../node/src/harnesses.ts"
+import { runHook } from "./bridge.ts"
+import { startDaemon, type DaemonLaunchOptions } from "./daemon.ts"
+import { runMcpPipe } from "./mcp.ts"
+import { socketPath } from "./paths.ts"
+import { hubPlugin, VERSION, type Program } from "./wrapper.ts"
+
+export interface ClaudeCodeIo {
+  readonly env: Readonly<Record<string, string | undefined>>
+  readonly home: string
+  stdout(s: string): void
+  stderr(s: string): void
+  readonly stdin?: () => Promise<string>
+  readonly input?: AsyncIterable<Uint8Array | string>
+  readonly signal?: AbortSignal
+  /** What runs the hub CLI (the plugin's hooks run it); default this process (the runtime and its entry). */
+  readonly program?: Program
+}
+
+export const CLAUDE_CODE_USAGE = "Usage: hub claude-code daemon | hook [--rewake] [--wait <seconds>] | mcp | install [--dry-run] | uninstall [--dry-run] | status"
+
+/** `claude --version` → "2.1.296", or "" when it cannot be told. */
+export function claudeVersion(bin: string, env: ClaudeCodeIo["env"]): string {
+  try {
+    const r = spawnSync(bin, ["--version"], { encoding: "utf8", timeout: 5000, env: env as NodeJS.ProcessEnv })
+    return /\d+\.\d+\.\d+[\w.+-]*/.exec(r.stdout ?? "")?.[0]?.slice(0, 100) ?? ""
+  } catch {
+    return ""
+  }
+}
+
+/**
+ * How the daemon starts Claude Code for hub launches, or undefined when it does not: the Claude Code CLI must be
+ * found (HUB_CLAUDE_BIN, else `claude` on PATH) and node.json must not withhold claude-code (harnesses). Launch
+ * directories must be under node.json's workspaceRoots (read again at each create); launched sessions load the hub
+ * plugin `hub claude` loads (written when the first launch needs it).
+ */
+export function daemonLaunchOptions(io: { readonly env: ClaudeCodeIo["env"]; readonly home: string; readonly program: Program }): DaemonLaunchOptions | undefined {
+  const bin = findExecutable(io.env.HUB_CLAUDE_BIN || "claude", io.env)
+  if (!bin) return undefined
+  const file = nodeConfigPath(io.env, io.home)
+  if (readNodeConfig(file).config.harnesses?.["claude-code"] === false) return undefined
+  return {
+    bin,
+    roots: () => readNodeConfig(file).config.workspaceRoots,
+    pluginDir: () => hubPlugin(io.env, io.home, io.program),
+    env: io.env,
+  }
+}
+
+/** This process as the hub CLI (its runtime and entry, resolved), as `hub claude` started the daemon. */
+function currentProgram(): Program {
+  const entry = process.argv[1] ?? ""
+  try {
+    return { execPath: process.execPath, entry: realpathSync(entry) }
+  } catch {
+    return { execPath: process.execPath, entry }
+  }
+}
+
+async function daemon(io: ClaudeCodeIo): Promise<number> {
+  const credentials = readSpokeCredentials(io.env, io.home)
+  if (!credentials) {
+    io.stderr(`hub claude-code daemon: this machine is not enrolled with a hub (no machine token in ${configPath(io.env, io.home)})\n`)
+    return 1
+  }
+  const log = (line: string) => io.stderr(`[hub claude-code] ${new Date().toISOString()} ${line}\n`)
+  const launch = daemonLaunchOptions({ env: io.env, home: io.home, program: io.program ?? currentProgram() })
+  let running
+  try {
+    running = await startDaemon({
+      socketPath: socketPath(io.env, io.home),
+      server: credentials.server,
+      token: credentials.token,
+      harnessVersion: claudeVersion(io.env.HUB_CLAUDE_BIN || "claude", io.env),
+      pluginVersion: VERSION,
+      directory: io.home,
+      log,
+      ...(launch ? { launch } : {}),
+    })
+  } catch (cause) {
+    io.stderr(`hub claude-code daemon: ${cause instanceof Error ? cause.message : String(cause)}\n`)
+    return 1
+  }
+  log(`listening on ${socketPath(io.env, io.home)}; ${launch ? `starts ${launch.bin} for hub launches` : "no hub launches (Claude Code CLI not found, or node.json withholds claude-code)"}`)
+  await new Promise<void>((resolve) => {
+    if (!io.signal) return
+    if (io.signal.aborted) return resolve()
+    io.signal.addEventListener("abort", () => resolve(), { once: true })
+  })
+  await running.stop()
+  return 0
+}
+
+export async function claudeCodeMain(argv: readonly string[], io: ClaudeCodeIo): Promise<number> {
+  const [command, ...rest] = argv
+  switch (command) {
+    case "hook": {
+      const stdin = io.stdin ? await io.stdin().catch(() => "") : ""
+      return runHook({ argv: rest, stdin, env: io.env, socketPath: socketPath(io.env, io.home), stdout: io.stdout, stderr: io.stderr })
+    }
+    case "mcp":
+      if (!io.input) {
+        io.stderr("hub claude-code mcp: needs stdin\n")
+        return 2
+      }
+      await runMcpPipe({ input: io.input, write: io.stdout, socketPath: socketPath(io.env, io.home), env: io.env, version: VERSION, ...(io.signal ? { signal: io.signal } : {}) })
+      return 0
+    case "daemon":
+      return daemon(io)
+    default:
+      io.stderr(`${CLAUDE_CODE_USAGE}\n`)
+      return 2
+  }
+}
+

package/packages/claude-code/src/mcp.ts

@@ -0,0 +1,109 @@
+// The daemon-backed MCP server (decision fx04e42c point 4): the plugin's .mcp.json runs `hub claude-code mcp`, a pipe
+// between Claude Code's stdio and the daemon. The daemon answers with the hub CLI's MCP tools (packages/cli mcp.ts)
+// as the session the `hub claude` run is in (HUB_CLAUDE_LAUNCH → its current session): act verbs (approve, deny,
+// answer, prompt, stop) with the session's act token, every other verb with its session token. Both tokens stay in
+// the daemon's memory: the MCP process never sees one. Without a daemon the pipe still speaks MCP and answers every
+// tool call with an error, so Claude Code's MCP client does not hang or retry.
+import { Socket } from "node:net"
+import { createMcpServer, serveMcp, type McpServer } from "../../cli/src/mcp.ts"
+import { CliError, EXIT } from "../../cli/src/http.ts"
+import type { Credentials } from "../../cli/src/credentials.ts"
+import { onLines, WIRE_VERSION, type BridgeRequest } from "./wire.ts"
+
+type Token = { readonly token: string; readonly url?: string } | undefined
+
+/** The pipe's last line: stdin ended (not JSON-RPC: it has no jsonrpc field). */
+export const MCP_END = { hub: "end" } as const
+
+/** Tools that act on another session: they need the act token (HUB_TOOL_ACT_VERBS in the OpenCode spoke). */
+export const ACT_TOOLS: ReadonlySet<string> = new Set(["approve", "deny", "answer", "prompt", "stop"])
+
+export interface McpRouterOptions {
+  readonly version: string
+  /** The hub session the MCP client belongs to, when known. */
+  sessionID(): string | undefined
+  sessionToken(sessionID: string): Token
+  actToken(sessionID: string): Token
+}
+
+export interface McpRouter {
+  handle(message: unknown): Promise<unknown>
+  close(): void
+}
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+/** One MCP connection's handler in the daemon: two hub CLI MCP servers, one per credential, picked per tool call. */
+export function createMcpRouter(options: McpRouterOptions): McpRouter {
+  const credentials = (pick: (id: string) => Token, what: string) => (): Credentials => {
+    const sessionID = options.sessionID()
+    const token = sessionID === undefined ? undefined : pick(sessionID)
+    if (!token?.url) throw new CliError(EXIT.unauthorized, `no ${what} for this Claude Code session: it is not a hub session (yet)`, "Start Claude Code with `hub claude` on an enrolled machine")
+    return { url: token.url, token: token.token, source: "env" }
+  }
+  const shell: McpServer = createMcpServer({ version: options.version, credentials: credentials(options.sessionToken, "hub session token") })
+  const act: McpServer = createMcpServer({ version: options.version, credentials: credentials(options.actToken, "hub session act token") })
+  return {
+    async handle(message) {
+      if (isObject(message) && message.method === "tools/call" && isObject(message.params) && ACT_TOOLS.has(message.params.name as string)) return act.handle(message)
+      if (isObject(message) && !("id" in message)) void act.handle(message) // notifications (cancellations) reach both
+      return shell.handle(message)
+    },
+    close() {
+      shell.close()
+      act.close()
+    },
+  }
+}
+
+export interface McpPipeOptions {
+  readonly input: AsyncIterable<Uint8Array | string>
+  write(s: string): void
+  readonly socketPath: string
+  readonly env: Readonly<Record<string, string | undefined>>
+  readonly version: string
+  readonly signal?: AbortSignal
+}
+
+function connectTo(socketPath: string): Promise<Socket | undefined> {
+  return new Promise((resolve) => {
+    const socket = new Socket()
+    socket.once("error", () => resolve(undefined))
+    socket.once("connect", () => resolve(socket))
+    try {
+      socket.connect(socketPath)
+    } catch {
+      resolve(undefined)
+    }
+  })
+}
+
+/** `hub claude-code mcp`: pipes stdio to the daemon until stdin ends (and the daemon answered) or the signal aborts. */
+export async function runMcpPipe(options: McpPipeOptions): Promise<void> {
+  const socket = await connectTo(options.socketPath)
+  if (!socket) {
+    const offline = (): Credentials => {
+      throw new CliError(EXIT.unavailable, "the Claude Code spoke daemon is not running", "Start Claude Code with `hub claude` (it starts the daemon)")
+    }
+    await serveMcp({ input: options.input, write: options.write, log: () => {}, credentials: offline, version: options.version, ...(options.signal ? { signal: options.signal } : {}) })
+    return
+  }
+  const closed = new Promise<void>((resolve) => socket.once("close", () => resolve()))
+  socket.on("error", () => {})
+  const launch = options.env.HUB_CLAUDE_LAUNCH
+  const hello: BridgeRequest = { v: WIRE_VERSION, kind: "mcp", ...(launch ? { launch } : {}) }
+  socket.write(`${JSON.stringify(hello)}\n`)
+  onLines(socket, (line) => options.write(`${line}\n`))
+  options.signal?.addEventListener("abort", () => socket.destroy(), { once: true })
+  const iterator = options.input[Symbol.asyncIterator]()
+  const stopped = new Promise<"stopped">((resolve) => socket.once("close", () => resolve("stopped")))
+  for (;;) {
+    const next = await Promise.race([iterator.next(), stopped])
+    if (next === "stopped" || next.done) break
+    if (!socket.destroyed) socket.write(next.value)
+  }
+  // Bun closes a half-closed Unix socket at once, so the end of stdin is a line of its own: the daemon answers the
+  // calls in flight, then closes.
+  if (!socket.destroyed) socket.write(`${JSON.stringify(MCP_END)}\n`)
+  await closed
+}

package/packages/claude-code/src/paths.ts

@@ -0,0 +1,34 @@
+// Where the Claude Code spoke keeps its files: <hub state dir>/claude-code (the hub state dir is $HUB_STATE_DIR, else
+// ~/.local/state/hub), a private (0700) directory holding the daemon's socket (daemon.sock, 0600), its log and the
+// plugin directories the wrapper loads with --plugin-dir. $HUB_CLAUDE_SOCKET names another socket (tests, or a
+// short path when the state dir is too deep for a Unix socket path).
+import { chmodSync, lstatSync, mkdirSync } from "node:fs"
+import { homedir } from "node:os"
+import path from "node:path"
+import { hubEnv, type Env } from "../../../src/env.ts"
+import { APP_DIR, stateBase } from "../../../src/migrate.ts"
+
+/** Longest Unix socket path (macOS sun_path is 104 bytes with the terminating NUL). */
+export const SOCKET_PATH_MAX = 103
+
+export function claudeStateDir(env: Env = process.env, home: string = homedir()): string {
+  return path.join(hubEnv(env).HUB_STATE_DIR || path.join(stateBase(home), APP_DIR), "claude-code")
+}
+
+export function socketPath(env: Env = process.env, home: string = homedir()): string {
+  return env.HUB_CLAUDE_SOCKET || path.join(claudeStateDir(env, home), "daemon.sock")
+}
+
+/**
+ * Makes `dir` (and its parents) and checks it is a real directory of this user that nobody else can reach: a
+ * symlink or someone else's directory is refused, group or other permissions are removed (0700).
+ */
+export function ensurePrivateDir(dir: string): void {
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const stat = lstatSync(dir)
+  if (stat.isSymbolicLink()) throw new Error(`${dir} is a symlink; the Claude Code spoke needs a real directory there`)
+  if (!stat.isDirectory()) throw new Error(`${dir} is not a directory`)
+  const uid = process.getuid?.()
+  if (uid !== undefined && stat.uid !== uid) throw new Error(`${dir} belongs to another user`)
+  if ((stat.mode & 0o777) !== 0o700) chmodSync(dir, 0o700)
+}

package/packages/claude-code/src/plugin.ts

@@ -0,0 +1,99 @@
+// The plugin directory `hub claude` loads with --plugin-dir (decision fx04e42c point 4: never the user's ~/.claude
+// files). hooks/hooks.json runs the hook bridge (`hub claude-code hook`) for every event the spoke uses, with the
+// absolute runtime and CLI entry quoted for sh and nothing else from outside in the command; PermissionRequest
+// passes the permission wait (--wait <s>) under a hook timeout 2 s above it (the spike: wait ≤ hook timeout − 1 s);
+// Stop also runs an asyncRewake bridge (--rewake) that blocks until the daemon has a message to wake the idle
+// session with (exit 2). .mcp.json runs the daemon-backed MCP pipe. Each configuration gets its own directory
+// (plugin-<hash>), written once.
+import { createHash } from "node:crypto"
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs"
+import path from "node:path"
+import { ensurePrivateDir } from "./paths.ts"
+
+export interface PluginOptions {
+  /** What runs the hub CLI: the runtime and the CLI's entry file (absolute paths). */
+  readonly program: { readonly execPath: string; readonly entry: string }
+  /** How long a PermissionRequest waits for the hub (0: report only, the local dialog decides). */
+  readonly permissionWaitS: number
+  /** How long the asyncRewake Stop hook may wait for a message. */
+  readonly rewakeTimeoutS: number
+  readonly version: string
+}
+
+/** The hook events the spoke registers. */
+export const HOOK_EVENTS: readonly string[] = [
+  "SessionStart",
+  "UserPromptSubmit",
+  "PreToolUse",
+  "PostToolUse",
+  "PostToolUseFailure",
+  "PermissionRequest",
+  "PermissionDenied",
+  "Notification",
+  "Stop",
+  "StopFailure",
+  "SubagentStart",
+  "SubagentStop",
+  "SessionEnd",
+]
+/** Events with a tool matcher. */
+const TOOL_EVENTS: ReadonlySet<string> = new Set(["PreToolUse", "PostToolUse", "PostToolUseFailure", "PermissionRequest", "PermissionDenied"])
+/** Timeout of the hooks that only report (seconds): the daemon answers at once. SessionStart waits for a token. */
+const REPORT_TIMEOUT_S = 10
+const SESSION_START_TIMEOUT_S = 15
+const PERMISSION_SLACK_S = 2
+
+/** An absolute path without quotes or control characters (safe single-quoted for sh); refused otherwise. */
+function checked(p: string): string {
+  if (!path.isAbsolute(p) || /['\u0000-\u001f\u007f]/.test(p)) throw new Error(`Cannot use ${JSON.stringify(p)} in a hook command: it must be an absolute path without quotes or control characters`)
+  return p
+}
+
+const quoted = (p: string) => `'${checked(p)}'`
+
+const json = (value: unknown) => `${JSON.stringify(value, null, 2)}\n`
+
+/** The plugin's files (relative path → content). */
+export function pluginFiles(options: PluginOptions): Record<string, string> {
+  const { execPath, entry } = options.program
+  const bridge = `BUN_BE_BUN=1 ${quoted(execPath)} ${quoted(entry)} claude-code hook`
+  const wait = Math.max(0, Math.round(options.permissionWaitS))
+  const command = (cmd: string, timeout: number, extra: Record<string, unknown> = {}) => ({ type: "command", command: cmd, ...extra, timeout })
+  const hooks: Record<string, unknown[]> = {}
+  for (const event of HOOK_EVENTS) {
+    const list =
+      event === "PermissionRequest"
+        ? [command(`${bridge} --wait ${wait}`, wait > 0 ? wait + PERMISSION_SLACK_S : REPORT_TIMEOUT_S)]
+        : event === "Stop"
+          ? [command(bridge, REPORT_TIMEOUT_S), command(`${bridge} --rewake`, Math.max(1, Math.round(options.rewakeTimeoutS)), { asyncRewake: true })]
+          : [command(bridge, event === "SessionStart" ? SESSION_START_TIMEOUT_S : REPORT_TIMEOUT_S)]
+    hooks[event] = [{ ...(TOOL_EVENTS.has(event) ? { matcher: "*" } : {}), hooks: list }]
+  }
+  return {
+    ".claude-plugin/plugin.json": json({ name: "hub", version: options.version, description: "Hub: follow, message and steer this Claude Code session from the hub (hooks spoke)" }),
+    "hooks/hooks.json": json({ hooks }),
+    ".mcp.json": json({ mcpServers: { hub: { command: checked(execPath), args: [checked(entry), "claude-code", "mcp"], env: { BUN_BE_BUN: "1" } } } }),
+  }
+}
+
+/** Writes the plugin for `options` under `base` (once: plugin-<hash>) and returns its directory. */
+export function writePlugin(base: string, options: PluginOptions): string {
+  const files = pluginFiles(options)
+  const hash = createHash("sha256").update(JSON.stringify(files)).digest("hex").slice(0, 12)
+  ensurePrivateDir(base)
+  const dir = path.join(base, `plugin-${hash}`)
+  if (existsSync(path.join(dir, "hooks", "hooks.json"))) return dir
+  const tmp = `${dir}.tmp-${process.pid}-${Date.now()}`
+  for (const [file, content] of Object.entries(files)) {
+    mkdirSync(path.dirname(path.join(tmp, file)), { recursive: true, mode: 0o700 })
+    writeFileSync(path.join(tmp, file), content, { mode: 0o600 })
+  }
+  try {
+    renameSync(tmp, dir)
+  } catch (cause) {
+    rmSync(tmp, { recursive: true, force: true })
+    if (!existsSync(dir)) throw cause // another run wrote it first otherwise
+  }
+  ensurePrivateDir(dir)
+  return dir
+}