frizz 0.0.1 → 0.2.0

package/runtime/cc-worker/bin/frizz-mcp.mjs

@@ -0,0 +1,564 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * frizz-mcp — THE frizz MCP server: one unified, dependency-free MCP stdio server (mounted as `frizz`,
+ * so its tools are `mcp__frizz__<tool>`) carrying every capability frizz hands its own WORKERS:
+ *
+ *   spawn_thread     — dispatch a brand-new TOP-LEVEL frizz board thread (its own session + scratchpad +
+ *                      independent drive — NOT an in-session Agent/Task helper).
+ *   recurring_prompt — arm ONE piece of text frizz re-sends the caller, at every rest and/or on a clock.
+ *   timer            — arm a ONE-OFF prompt for a single instant; a thread may hold many at once.
+ *
+ * Future worker-facing frizz tools join the TOOLS registry below rather than mounting a second server:
+ * one server keeps the worker's tool namespace coherent and the server-level pre-approval single.
+ *
+ * spawn_thread wraps frizz's own dispatch RPC: it reads the running server's port from
+ * `<state-dir>/server.lock` and POSTs `/rpc/dispatch`. The `/rpc` surface has no token auth — only a
+ * loopback-origin CSRF gate — so a headerless local POST with `sec-fetch-site: same-origin` (undici
+ * sends no Origin) satisfies it.
+ *
+ * Mounted by the server (dispatch.ts) into the Claude backend via `--mcp-config`. The server passes
+ * FRIZZ_STATE_DIR in this process's env so we can locate server.lock without recomputing the project id.
+ *
+ * Protocol: MCP over stdio = newline-delimited JSON-RPC 2.0. We implement exactly the four methods a
+ * client drives (initialize, tools/list, tools/call, ping) plus the initialized notification. Hand-
+ * rolled rather than pulling @modelcontextprotocol/sdk: the surface is tiny, it ships as one loose
+ * .mjs next to bin/frizz (no build/bundle/resolution concerns), and it matches this repo's own
+ * hand-rolled-RPC aesthetic. The server NEVER crashes on a bad tool call: failures come back as an
+ * isError tool result so the worker sees a message instead of a dead tool.
+ */
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+const PROTOCOL_FALLBACK = "2025-06-18"
+// Comfortably above a codex dispatch's bounded rollout-discovery wait (~15s) so a legitimate slow
+// dispatch is never aborted client-side (which would make the worker think it failed and retry,
+// double-spawning). The server completes regardless; this is only the client's patience.
+const DISPATCH_TIMEOUT_MS = 30_000
+
+const SPAWN_THREAD = {
+  name: "spawn_thread",
+  description:
+    "Spawn a brand-new, separate top-level frizz thread — its own board card, session, and scratchpad, " +
+    "driving INDEPENDENTLY. This is FIRE-AND-FORGET: the new thread reports to the HUMAN on the board via " +
+    "its own final message, and its results NEVER come back to you, the caller. It is NOT an in-session " +
+    "sub-agent. It returns only the new thread's slug and a ready-to-paste markdown link " +
+    "`[title](/thread/<slug>)` that opens the thread in the frizz drawer — put that link in your handoff. " +
+    "USE IT ONLY for a distinct, self-contained effort that belongs on the board in its own right and whose " +
+    "output you do NOT need to read. Do NOT use it for a helper whose result you must COLLECT and fold into " +
+    "your own work — a self-review, a verification pass, a research prong, a critic, any collect-back helper: " +
+    "those are in-session sub-agents (Claude: the Agent tool with `run_in_background`; Codex: native " +
+    "delegation), which return their findings to you. Spawning such a helper here STRANDS it — its work lands " +
+    "on another card and never reaches you, so you gain nothing. " +
+    "You MUST deliberately choose `model` and `effort` to match the NEW thread's task complexity — they are " +
+    "required, there is NO default. Do not reflexively pick the cheapest; a hard task on a weak model/effort " +
+    "wastes the whole thread.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      prompt: {
+        type: "string",
+        description: "The full task/prompt for the new thread's worker. Be self-contained — the new thread starts with empty context.",
+      },
+      model: {
+        type: "string",
+        description:
+          "REQUIRED — pick by the NEW task's complexity; there is no default. For the `claude` backend: " +
+          "`opus` (the TOP tier — hardest reasoning, architecture, subtle correctness/security, adversarial " +
+          "review, the fix that must land), `sonnet` (ordinary substantive implementation/research), `haiku` " +
+          "(simple, fully-specified mechanical work). Do NOT pick `fable`: Opus 5 is just as good and cheaper, " +
+          "so a high-intensity task takes `opus` at a higher `effort`, not a different model — `fable` only " +
+          "when the human explicitly asks for it. For " +
+          "the `codex` backend use a codex model id instead (e.g. `gpt-5.6-sol`/`gpt-5.6-terra`/`gpt-5.6-luna`). " +
+          "Match the model to the backend you choose. Bias toward Opus/a strong model when the task is " +
+          "non-trivial or its outcome is load-bearing.",
+      },
+      effort: {
+        type: "string",
+        enum: ["low", "medium", "high", "xhigh", "max"],
+        description:
+          "REQUIRED — reasoning effort, pick by complexity; no default. `low` only for trivial tasks; " +
+          "`medium` for routine work; `high` for ordinary substantive work; `xhigh` for hard coding/agentic " +
+          "work; `max` for the single hardest problems. (Codex also accepts `ultra`.)",
+      },
+      backend: {
+        type: "string",
+        enum: ["claude", "codex"],
+        description: "Optional agent backend (default `claude`). If `codex`, `model` must be a codex model id.",
+      },
+      title: { type: "string", description: "Optional short title for the new thread (else derived from the prompt)." },
+    },
+    required: ["prompt", "model", "effort"],
+  },
+}
+
+const RECURRING_PROMPT = {
+  name: "recurring_prompt",
+  description:
+    "Arm a RECURRING PROMPT on YOUR OWN thread: one piece of text that frizz re-sends you, on either or " +
+    "both of two triggers, for as long as it is armed.\n\n" +
+    "  stop_hook          — every time you come to REST. Use it to keep a long autonomous effort moving " +
+    "without the human driving every step, and to rescue yourself from a wait that may never resolve.\n" +
+    "  heartbeat_seconds  — on a CLOCK, whatever you are doing. This one reaches you MID-TURN: it arrives as " +
+    "a queued message you read at your next tool boundary rather than waiting for you to stop, and it " +
+    "never aborts what you are running. Use it for something that must be revisited on a schedule no " +
+    "matter what you happen to believe at the time.\n\n" +
+    "Set at least one. Setting BOTH is the ordinary case for \"keep this moving\": you are prompted " +
+    "whenever you stop, and at least every N seconds even if you never do.\n\n" +
+    "USE THIS RATHER THAN `CronCreate` or `ScheduleWakeup`. Those are Claude Code's own in-session " +
+    "schedulers and they CANNOT fire in the runtime frizz runs you in: their gate stays shut for as long " +
+    "as ANY background task of yours is outstanding, so the moment you are parked behind a background " +
+    "shell or a sub-agent — exactly when you most need waking — they go silent. This one is delivered by " +
+    "frizz itself and is unaffected.\n\n" +
+    "The text arrives VERBATIM as an ordinary user turn, so write it as an instruction to your future " +
+    "self. A thread has AT MOST ONE recurring prompt: calling this again REPLACES it, triggers and all. " +
+    "At most one scheduled delivery is ever outstanding and its clock runs from the last one DELIVERED, " +
+    "so you can never be handed a backlog at once.\n\n" +
+    "STOP IT when the work it drives is done (`action: \"stop\"`) — one left armed on a finished thread " +
+    "wakes it forever. The human sees it in the thread footer and can edit or switch it off there. " +
+    "Replying ALLDONE on its own line also stops it, both triggers at once, but be sure before you do: " +
+    "it permanently stalls the run, and a run nobody is watching does not restart itself.\n\n" +
+    "You can only ever arm your OWN thread — there is no parameter for anyone else's.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      action: {
+        type: "string",
+        enum: ["start", "stop"],
+        description: "`start` arms (or replaces) this thread's recurring prompt; `stop` disarms it.",
+      },
+      prompt: {
+        type: "string",
+        description:
+          "Required for `start`. The text delivered to you on every trigger, verbatim, as a user turn. " +
+          "Make it self-contained and ACTIONABLE — say what to do and what would make it right to stop " +
+          "— because you may receive it with none of the context you have right now.",
+      },
+      stop_hook: {
+        type: "boolean",
+        description:
+          "Send it every time you come to rest. Defaults to true when `heartbeat_seconds` is omitted, so a " +
+          "`start` that names neither mechanism still does the obvious thing.",
+      },
+      heartbeat_seconds: {
+        type: "integer",
+        description:
+          "Also send it on this clock, in seconds (minimum 60, maximum 86400). Omit for no heartbeat. A " +
+          "delivery is read at your next tool boundary, so a sub-minute cadence buys no promptness and " +
+          "only talks over your own work.",
+      },
+    },
+    required: ["action"],
+  },
+}
+
+// The ONE-OFF TIMER's bounds, mirrored from @frizz/shared (this file is dependency-free by design and
+// ships as a loose .mjs, so it cannot import them). The server validates the same numbers; these exist so
+// a wrong delay is refused HERE, with an explanation, instead of coming back as an HTTP 400.
+const TIMER_MIN_DELAY_SECONDS = 10
+const TIMER_MAX_DELAY_SECONDS = 30 * 24 * 60 * 60
+
+const TIMER = {
+  name: "timer",
+  description:
+    "Set a ONE-OFF timer on YOUR OWN thread: a piece of text frizz hands back to you at ONE instant, " +
+    "ONCE. Your own alarm clock.\n\n" +
+    "It is `recurring_prompt`'s heartbeat with the repetition taken out, and it shares the property that " +
+    "matters: the delivery reaches you MID-TURN — a queued message you read at your next tool boundary — " +
+    "so it arrives when you asked for it whether or not you have stopped, and it never aborts what you " +
+    "are running. Unlike a recurring prompt it fires exactly once and then is gone, so there is nothing " +
+    "to switch off afterwards and no ALLDONE involved.\n\n" +
+    "You may have MANY armed at the same time, each with its own instant and its own text — they are " +
+    "independent, unlike the single recurring prompt this thread can hold.\n\n" +
+    "USE IT for anything you want to come back to at a specific time: re-check a deploy in ten minutes, " +
+    "re-read a slow log at the top of the hour, revisit a decision after a build finishes. USE " +
+    "`recurring_prompt` instead when the thing must repeat, and remember that Claude Code's own " +
+    "`CronCreate`/`ScheduleWakeup` cannot fire in the runtime frizz runs you in.\n\n" +
+    "IT IS NOT A WAY TO POLL SOMETHING YOU COULD WAIT ON. If a background shell, a sub-agent or a " +
+    "monitor can tell you the moment a thing happens, use that — an alarm every N seconds asking \"is it " +
+    "done yet\" is strictly worse than being woken when it is.\n\n" +
+    "The text arrives VERBATIM as an ordinary user turn, so write it as an instruction to your future " +
+    "self — self-contained and actionable, because you may receive it with none of the context you have " +
+    "now. Give exactly one of `in_seconds` or `at`. You can only ever set a timer on your OWN thread.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      action: {
+        type: "string",
+        enum: ["set", "cancel", "list"],
+        description:
+          "`set` arms a new one-off timer (it never replaces an existing one); `cancel` withdraws one by " +
+          "`id`; `list` returns the timers currently armed on this thread. Every action answers with the " +
+          "resulting armed list.",
+      },
+      prompt: {
+        type: "string",
+        description: "Required for `set`. The text delivered to you when it fires, verbatim, as a user turn.",
+      },
+      in_seconds: {
+        type: "integer",
+        description:
+          `For \`set\`: fire this many seconds from now (minimum ${TIMER_MIN_DELAY_SECONDS}, maximum ` +
+          `${TIMER_MAX_DELAY_SECONDS} — thirty days). Give this OR \`at\`, not both. Sub-minute precision ` +
+          "is not real: the delivery is read at your next tool boundary.",
+      },
+      at: {
+        type: "string",
+        description:
+          "For `set`: fire at this exact instant, as an ISO-8601 timestamp (e.g. `2026-08-04T15:00:00Z`). " +
+          "Give this OR `in_seconds`, not both. Must be in the future and within thirty days.",
+      },
+      id: {
+        type: "string",
+        description: "Required for `cancel`. The timer id returned by `set` (or listed by `list`).",
+      },
+    },
+    required: ["action"],
+  },
+}
+
+// The unified server's tool registry: `tools/list` returns these and `tools/call` routes by name.
+// Adding a worker-facing frizz tool = one entry here + one handler in `HANDLERS` — never a second
+// MCP server, so every frizz tool stays under the same `mcp__frizz__*` namespace and the same
+// server-level pre-approval the dispatch layer already grants.
+const MIN_INTERVAL_SECONDS = 60
+const MAX_INTERVAL_SECONDS = 24 * 60 * 60
+
+const TOOLS = [SPAWN_THREAD, RECURRING_PROMPT, TIMER]
+
+/** @type {Record<string, (args: Record<string, unknown>) => Promise<string>>} */
+const HANDLERS = {
+  [SPAWN_THREAD.name]: spawnThread,
+  [RECURRING_PROMPT.name]: recurringPrompt,
+  [TIMER.name]: timer,
+}
+
+/** @param {unknown} obj */
+function send(obj) {
+  process.stdout.write(JSON.stringify(obj) + "\n")
+}
+/** @param {string|number} id @param {unknown} result */
+function reply(id, result) {
+  send({ jsonrpc: "2.0", id, result })
+}
+/** @param {string|number} id @param {number} code @param {string} message */
+function replyError(id, code, message) {
+  send({ jsonrpc: "2.0", id, error: { code, message } })
+}
+/** @param {string|number} id @param {string} text @param {boolean} [isError] */
+function replyTool(id, text, isError) {
+  reply(id, { content: [{ type: "text", text }], ...(isError ? { isError: true } : {}) })
+}
+
+function serverLockPort() {
+  const lock = process.env.FRIZZ_SERVER_LOCK
+    || (process.env.FRIZZ_STATE_DIR ? join(process.env.FRIZZ_STATE_DIR, "server.lock") : undefined)
+  if (!lock) throw new Error("FRIZZ_STATE_DIR / FRIZZ_SERVER_LOCK not set — cannot locate the frizz server")
+  let parsed
+  try {
+    parsed = JSON.parse(readFileSync(lock, "utf8"))
+  } catch (err) {
+    throw new Error(`could not read the frizz server lock at ${lock} (is the server running?): ${err instanceof Error ? err.message : err}`)
+  }
+  const port = parsed?.port
+  if (!Number.isInteger(port)) throw new Error(`frizz server lock at ${lock} has no valid port`)
+  return port
+}
+
+/** The `spawn_thread` handler: POST /rpc/dispatch, return the worker-facing result text.
+ * @param {Record<string, unknown>} args @returns {Promise<string>} */
+async function spawnThread(args) {
+  const prompt = typeof args.prompt === "string" ? args.prompt.trim() : ""
+  if (!prompt) throw new Error("`prompt` is required and must be a non-empty string")
+  // model + effort are REQUIRED (no default) so the caller must choose by task complexity — a defaulted
+  // model (e.g. the project's cheap default) is exactly the bug this guards. Enforced server-side too,
+  // not only in the tool schema, so a lenient client can't skip the decision.
+  const model = typeof args.model === "string" ? args.model.trim() : ""
+  if (!model) throw new Error("`model` is required — choose one by the new task's complexity (claude: opus/sonnet/haiku, opus being the top tier; codex: a gpt-5.6 model id). There is no default.")
+  const effort = typeof args.effort === "string" ? args.effort.trim() : ""
+  if (!effort) throw new Error("`effort` is required — choose one by complexity (low/medium/high/xhigh/max). There is no default.")
+
+  /** @type {Record<string, unknown>} */
+  const body = { prompt, model, effort }
+  if (typeof args.title === "string" && args.title.trim()) body.title = args.title.trim()
+  if (args.backend === "claude" || args.backend === "codex") body.backend = args.backend
+
+  const port = serverLockPort()
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), DISPATCH_TIMEOUT_MS)
+  let res
+  try {
+    res = await fetch(`http://127.0.0.1:${port}/rpc/dispatch`, {
+      method: "POST",
+      // No Origin header (undici omits it for non-browser fetch); `sec-fetch-site: same-origin`
+      // satisfies the server's loopback-origin gate (app.ts isTrustedLocalHttpRequest).
+      headers: { "content-type": "application/json", "sec-fetch-site": "same-origin" },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    })
+  } catch (err) {
+    throw new Error(`dispatch request failed: ${err instanceof Error ? err.message : err}`)
+  } finally {
+    clearTimeout(timer)
+  }
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "")
+    throw new Error(`dispatch returned HTTP ${res.status}${detail ? `: ${detail.slice(0, 500)}` : ""}`)
+  }
+  const payload = await res.json().catch(() => null)
+  const slug = payload?.result?.slug
+  if (typeof slug !== "string" || !slug) throw new Error(`dispatch response missing a slug: ${JSON.stringify(payload)?.slice(0, 300)}`)
+  const label = typeof body.title === "string" ? body.title : slug
+  return (
+    `Spawned a new frizz thread \`${slug}\`. It is now on the board driving independently — it reports ` +
+    `to the human via its own final message, NOT back to you, so do not wait on a result from it.\n\n` +
+    `Paste this link to let the human open it in the drawer:\n\n[${label}](/thread/${slug})`
+  )
+}
+
+/** POST a frizz RPC procedure and return its parsed payload. Shares spawn_thread's transport rules:
+ * the port comes from server.lock and `sec-fetch-site: same-origin` satisfies the loopback gate.
+ * @param {string} procedure @param {Record<string, unknown>} body @returns {Promise<any>} */
+async function callRpc(procedure, body) {
+  const port = serverLockPort()
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), DISPATCH_TIMEOUT_MS)
+  let res
+  try {
+    res = await fetch(`http://127.0.0.1:${port}/rpc/${procedure}`, {
+      method: "POST",
+      headers: { "content-type": "application/json", "sec-fetch-site": "same-origin" },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    })
+  } catch (err) {
+    throw new Error(`${procedure} request failed: ${err instanceof Error ? err.message : err}`)
+  } finally {
+    clearTimeout(timer)
+  }
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "")
+    throw new Error(`${procedure} returned HTTP ${res.status}${detail ? `: ${detail.slice(0, 500)}` : ""}`)
+  }
+  return await res.json().catch(() => null)
+}
+
+/** Which thread this MCP server belongs to. Stamped into our env at spawn (dispatch.ts for the tmux
+ * path, the broker bridge for the SDK path) because the MCP protocol carries no caller identity.
+ * FRIZZ_THREAD is the fallback: every frizz worker process is tagged with it, so it is right
+ * whenever the env is inherited — but it is not relied upon, hence the explicit var first.
+ *
+ * This is also the reason a model can never point `recurring_prompt` at someone else's thread: the slug is
+ * read from HERE, never from the tool arguments. */
+function threadSlug() {
+  const slug = process.env.FRIZZ_THREAD_SLUG || process.env.FRIZZ_THREAD
+  if (!slug) {
+    throw new Error(
+      "this frizz MCP server was not told which thread it belongs to (no FRIZZ_THREAD_SLUG), so it cannot " +
+      "arm a recurring prompt for it. This is a frizz bug — report it rather than working around it.",
+    )
+  }
+  return slug
+}
+
+/** The `recurring_prompt` handler: arm or disarm this thread's re-prompt, on either or both triggers.
+ * @param {Record<string, unknown>} args @returns {Promise<string>} */
+async function recurringPrompt(args) {
+  const slug = threadSlug()
+  const action = typeof args.action === "string" ? args.action.trim() : ""
+  if (action !== "start" && action !== "stop") throw new Error("`action` must be either \"start\" or \"stop\"")
+
+  if (action === "stop") {
+    await callRpc("setOwnThreadRecurringPrompt", { slug, prompt: null, stopHook: false, heartbeat: false })
+    return "Recurring prompt disarmed and cleared. Neither the stop hook nor the heartbeat will fire, and the text is gone from the thread footer."
+  }
+
+  const prompt = typeof args.prompt === "string" ? args.prompt.trim() : ""
+  if (!prompt) {
+    throw new Error("`prompt` is required to start a recurring prompt — it is the text you will be sent on every trigger")
+  }
+
+  const hasHeartbeat = args.heartbeat_seconds !== undefined && args.heartbeat_seconds !== null
+  let interval
+  if (hasHeartbeat) {
+    interval = typeof args.heartbeat_seconds === "number" ? Math.round(args.heartbeat_seconds) : NaN
+    if (!Number.isFinite(interval)) throw new Error("`heartbeat_seconds` must be a number of seconds")
+    if (interval < MIN_INTERVAL_SECONDS || interval > MAX_INTERVAL_SECONDS) {
+      throw new Error(`\`heartbeat_seconds\` must be between ${MIN_INTERVAL_SECONDS} and ${MAX_INTERVAL_SECONDS}`)
+    }
+  }
+  // DEFAULTED, not required: a `start` that names no trigger at all is a model asking to be re-prompted
+  // and leaving the mechanism to us, and the rest trigger is the safe reading of that — it cannot talk
+  // over a running turn, and it cannot fire on a thread that has stopped needing it.
+  const stopHook = typeof args.stop_hook === "boolean" ? args.stop_hook : !hasHeartbeat
+  const heartbeat = hasHeartbeat
+  if (!stopHook && !heartbeat) {
+    throw new Error("at least one is required: set `stop_hook: true`, or give `heartbeat_seconds`, or both")
+  }
+
+  await callRpc("setOwnThreadRecurringPrompt", {
+    slug,
+    prompt,
+    stopHook,
+    heartbeat,
+    ...(heartbeat ? { intervalSeconds: interval } : {}),
+  })
+
+  const every = heartbeat ? (interval % 60 === 0 ? `${interval / 60} min` : `${interval}s`) : null
+  const when = stopHook && every
+    ? `every time you come to rest AND every ${every} (the heartbeat reaches you mid-turn)`
+    : stopHook
+      ? "every time you come to rest"
+      : `every ${every}, reaching you mid-turn rather than waiting for you to stop`
+  return (
+    `Recurring prompt armed — frizz will send you this ${when}. It replaces any recurring prompt this ` +
+    "thread had before.\n\n" +
+    "Call this tool again with `action: \"stop\"` once the work it drives is finished — one left armed on " +
+    "a finished thread wakes it forever. The human can also edit or switch it off in the thread footer. " +
+    "Replying ALLDONE stops it too, but only use that when there is genuinely nothing left: it " +
+    "permanently stalls the run."
+  )
+}
+
+/** How a timer reads back to the worker: its id, when it fires, and enough of its text to tell two apart.
+ * @param {{ id: string, fireAt: string, prompt: string }} t */
+function timerLine(t) {
+  const words = t.prompt.replace(/\s+/g, " ").trim()
+  return `  ${t.id} — ${t.fireAt} — ${words.length > 72 ? `${words.slice(0, 72)}…` : words}`
+}
+
+/** @param {{ timers?: { id: string, fireAt: string, prompt: string }[] }|null} payload */
+function armedList(payload) {
+  const timers = payload?.timers ?? []
+  if (!timers.length) return "No timers are armed on this thread."
+  return `Armed timers (${timers.length}):\n${timers.map(timerLine).join("\n")}`
+}
+
+/** The `timer` handler: set / cancel / list this thread's ONE-OFF timers.
+ * @param {Record<string, unknown>} args @returns {Promise<string>} */
+async function timer(args) {
+  const slug = threadSlug()
+  const action = typeof args.action === "string" ? args.action.trim() : ""
+  if (action !== "set" && action !== "cancel" && action !== "list") {
+    throw new Error("`action` must be one of \"set\", \"cancel\" or \"list\"")
+  }
+
+  if (action === "list") {
+    return armedList((await callRpc("listOwnThreadTimers", { slug }))?.result)
+  }
+
+  if (action === "cancel") {
+    const id = typeof args.id === "string" ? args.id.trim() : ""
+    if (!id) throw new Error("`id` is required to cancel a timer — take it from `set`'s reply or from `action: \"list\"`")
+    const result = (await callRpc("cancelOwnThreadTimer", { slug, id }))?.result
+    const head = result?.cancelled
+      ? `Timer ${id} cancelled — it will not fire.`
+      : `No ARMED timer ${id} on this thread (it may have already fired, or already been cancelled).`
+    return `${head}\n\n${armedList(result)}`
+  }
+
+  const prompt = typeof args.prompt === "string" ? args.prompt.trim() : ""
+  if (!prompt) throw new Error("`prompt` is required to set a timer — it is the text you will be sent when it fires")
+
+  // Exactly one of the two ways to name the instant. Accepting both would mean silently preferring one,
+  // and a worker that gave two different times meant something by each of them.
+  const hasIn = args.in_seconds !== undefined && args.in_seconds !== null
+  const hasAt = typeof args.at === "string" && args.at.trim() !== ""
+  if (hasIn && hasAt) throw new Error("give `in_seconds` OR `at`, not both")
+  if (!hasIn && !hasAt) throw new Error("give either `in_seconds` (fire N seconds from now) or `at` (an ISO-8601 instant)")
+
+  const nowMs = Date.now()
+  let fireMs
+  if (hasIn) {
+    const seconds = typeof args.in_seconds === "number" ? Math.round(args.in_seconds) : NaN
+    if (!Number.isFinite(seconds)) throw new Error("`in_seconds` must be a number of seconds")
+    if (seconds < TIMER_MIN_DELAY_SECONDS || seconds > TIMER_MAX_DELAY_SECONDS) {
+      throw new Error(`\`in_seconds\` must be between ${TIMER_MIN_DELAY_SECONDS} and ${TIMER_MAX_DELAY_SECONDS} (thirty days)`)
+    }
+    fireMs = nowMs + seconds * 1000
+  } else {
+    fireMs = Date.parse(String(args.at))
+    if (!Number.isFinite(fireMs)) throw new Error("`at` must be an ISO-8601 instant, e.g. `2026-08-04T15:00:00Z`")
+    const delta = Math.round((fireMs - nowMs) / 1000)
+    if (delta < TIMER_MIN_DELAY_SECONDS) {
+      throw new Error(`\`at\` must be at least ${TIMER_MIN_DELAY_SECONDS}s in the future (it reads as ${delta}s from now)`)
+    }
+    if (delta > TIMER_MAX_DELAY_SECONDS) throw new Error("`at` must be within thirty days")
+  }
+
+  // ONE representation crosses the wire — the exact UTC instant — so the stored row, the trailer on the
+  // delivered message and this reply all name the same string.
+  const fireAt = new Date(fireMs).toISOString()
+  const result = (await callRpc("setOwnThreadTimer", { slug, prompt, fireAt }))?.result
+  const id = result?.id ?? "(unknown)"
+  return (
+    `Timer ${id} set for ${fireAt} (${Math.round((fireMs - nowMs) / 1000)}s from now). It fires ONCE and ` +
+    "then is gone — it may reach you mid-turn, so receiving it does not mean you had stopped. Cancel it " +
+    `with \`action: "cancel", id: "${id}"\` if it stops being useful.\n\n${armedList(result)}`
+  )
+}
+
+/** @param {any} msg */
+async function handle(msg) {
+  const { id, method, params } = msg ?? {}
+  const isNotification = id === undefined || id === null
+
+  switch (method) {
+    case "initialize": {
+      const requested = params?.protocolVersion
+      reply(id, {
+        protocolVersion: typeof requested === "string" ? requested : PROTOCOL_FALLBACK,
+        capabilities: { tools: {} },
+        serverInfo: { name: "frizz", version: "0.1.0" },
+      })
+      return
+    }
+    case "notifications/initialized":
+    case "initialized":
+      return // notification — no reply
+    case "ping":
+      if (!isNotification) reply(id, {})
+      return
+    case "tools/list":
+      reply(id, { tools: TOOLS })
+      return
+    case "tools/call": {
+      const name = typeof params?.name === "string" ? params.name : ""
+      const handler = HANDLERS[name]
+      if (!handler) {
+        replyError(id, -32602, `unknown tool: ${params?.name}`)
+        return
+      }
+      try {
+        replyTool(id, await handler(params?.arguments ?? {}))
+      } catch (err) {
+        replyTool(id, `\`${name}\` failed: ${err instanceof Error ? err.message : String(err)}`, true)
+      }
+      return
+    }
+    default:
+      if (!isNotification) replyError(id, -32601, `method not found: ${method}`)
+      return
+  }
+}
+
+// NDJSON reader: buffer stdin, dispatch each complete line. Messages never contain raw newlines.
+let buf = ""
+process.stdin.setEncoding("utf8")
+process.stdin.on("data", (chunk) => {
+  buf += chunk
+  let nl
+  while ((nl = buf.indexOf("\n")) >= 0) {
+    const line = buf.slice(0, nl).trim()
+    buf = buf.slice(nl + 1)
+    if (!line) continue
+    let msg
+    try {
+      msg = JSON.parse(line)
+    } catch {
+      continue // ignore unparseable lines
+    }
+    void handle(msg)
+  }
+})
+process.stdin.on("end", () => process.exit(0))

package/runtime/cc-worker/bin/frizz-update

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * frizz-update — the structured thread updater, on the worker's Bash PATH while the frizz-worker
+ * plugin is enabled. This is the worker's PRIMARY tool for owning its one thread file: it writes
+ * `.frizz/<slug>.md` through the same code path frizz uses (never hand-rolled markdown edits).
+ * Execs the repo board's bundled updater directly (NOT a copy) — cc-worker never forks updater logic.
+ *
+ * Resolving the script: this file is <plugin>/bin/frizz-update, board/ is a sibling of the plugin root,
+ * so the updater is at ../../board/thread-update.mjs relative to THIS file. Imported via
+ * a file:// URL so argv/process.env flow straight through.
+ */
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const updater = join(here, '..', '..', 'board', 'thread-update.mjs');
+await import(pathToFileURL(updater).href);

package/runtime/cc-worker/hooks/agent-bind.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// @ts-check
+// PostToolUse hook on the `Agent` tool (frizz-worker) — the AUTOMATIC thread↔agent binding, kept
+// COMPATIBLE with cc's board. When a worker dispatches a helper tagged `THREAD: <slug>` at the top
+// of the prompt, this records `agentId → thread` into `.frizz/.agent-bindings.jsonl` in the exact
+// shape cc's board (`bindingsByThread`) reads for per-thread sub-agent liveness — so frizz renders
+// a worker's helper activity the same way the cc board does. An untagged helper writes nothing.
+//
+// GATE: inert unless FRIZZ_THREAD is set. FAIL-OPEN ABSOLUTELY: any error → exit 0, no output.
+// A missed binding just means one helper isn't surfaced; a PostToolUse hook must never disturb the turn.
+import { readFileSync } from 'node:fs';
+import { recordBinding, threadFromPrompt } from '../scripts/frizz/agent-bindings.mjs';
+
+try {
+  // WORKER GATE.
+  if (!(process.env.FRIZZ_THREAD ?? '').trim()) process.exit(0);
+
+  const input = JSON.parse(readFileSync(0, 'utf8'));
+  const dir = process.env.CLAUDE_PROJECT_DIR ?? '.';
+
+  const ti = input.tool_input ?? {};
+  const tr = input.tool_response ?? {};
+  const trInner = tr.toolUseResult ?? tr;
+
+  const agentId = trInner.agentId ?? tr.agentId ?? null;
+  const prompt =
+    (typeof trInner.prompt === 'string' && trInner.prompt) ||
+    (typeof tr.prompt === 'string' && tr.prompt) ||
+    (typeof ti.prompt === 'string' && ti.prompt) ||
+    '';
+  const thread = threadFromPrompt(prompt);
+  const label = (typeof ti.description === 'string' && ti.description) || trInner.description || null;
+
+  if (agentId && thread) {
+    recordBinding(dir, { agentId, thread, label, session: input.session_id ?? null });
+  }
+} catch {
+  /* fail-open — never disturb the turn */
+}
+process.exit(0);