frizz 0.2.0 → 0.4.0

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

@@ -6,19 +6,29 @@
  *
  *   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.
+ *   recurring_prompt — arm ONE piece of text frizz re-sends the caller, at every rest and/or on a clock
+ *                      and/or after every compaction; and READ BACK what is currently armed.
  *   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.
+ * spawn_thread wraps frizz's own dispatch RPC: it reads the running server's port from a server.lock
+ * and POSTs `/_frizz/<project>/rpc/dispatch`. That 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.
+ * Mounted by the server (dispatch.ts) into the Claude backend via `--mcp-config`, and into codex via
+ * `-c mcp_servers.frizz` (codex-mcp.ts). Both hand this process the same env, built once in
+ * frizzMcpEnv: FRIZZ_SERVER_LOCK, FRIZZ_PROJECT_ID and FRIZZ_STATE_DIR.
+ *
+ * BUT NOTHING HERE DEPENDS ON THAT ENV STAYING TRUE. This process lives inside a DETACHED worker
+ * daemon that outlives frizz restart after restart, so anything frozen into it at spawn is a bug
+ * waiting for the next "Update & Restart" to move the port. Both facts we need are therefore resolved
+ * PER CALL, from files: the server's address (serverLockPort — the env hint, then the machine-wide
+ * `<frizz root>/server.lock`, then any live project lock, skipping any whose pid is gone) and our own
+ * project (projectSegment — the stamp, else `.frizz/.id` walked up from our cwd). The env is a hint
+ * that saves a lookup; the filesystem is the truth.
  *
  * 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-
@@ -27,8 +37,8 @@
  * 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"
+import { readFileSync, readdirSync } from "node:fs"
+import { dirname, 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
@@ -95,37 +105,52 @@ const SPAWN_THREAD = {
 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" +
+    "Arm a RECURRING PROMPT on YOUR OWN thread: one piece of text that frizz re-sends you, on any or all " +
+    "of three 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" +
+    "matter what you happen to believe at the time.\n" +
+    "  post_compaction    — every time your CONTEXT IS COMPACTED, delivered into the emptied window. This " +
+    "is how you survive compaction: write a doc in your scratch directory as you work, LINK IT in this " +
+    "prompt, and the link comes back at the exact moment you have lost everything else. Also mid-turn — " +
+    "a compaction happens while you are working.\n\n" +
+    "Set at least one. The ordinary shape for a long effort is post_compaction plus stop_hook: you are " +
+    "re-grounded whenever your context is summarized away, and prompted again whenever you stop.\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" +
+    "READ IT BACK WITH `action: \"get\"` — and do that BEFORE any `start` that is not a fresh arming. A " +
+    "thread has AT MOST ONE recurring prompt, so a `start` REPLACES whatever is there, triggers and all, " +
+    "and the text you are about to destroy may not be yours: the HUMAN can edit it in the thread footer, " +
+    "and a compaction can take your own memory of arming it. `get` answers with the exact text currently " +
+    "armed, which triggers are on, the cadence, and when each trigger last fired. Reach for it whenever " +
+    "you are about to change one trigger and keep the rest, whenever you are unsure whether you are armed " +
+    "at all, and after a compaction. (A `start` also reports what it replaced, so a blind overwrite is at " +
+    "least a visible one.)\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" +
+    "self. 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" +
+    "Signing off with a ```done fence stops it too, every trigger at once — but only when the work is " +
+    "genuinely finished, because that files the thread away and a thread 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.",
+        enum: ["start", "stop", "get"],
+        description:
+          "`start` arms (or replaces) this thread's recurring prompt; `stop` disarms it; `get` reads back " +
+          "what is armed right now — the text, the triggers, the cadence and each trigger's last delivery " +
+          "— without changing anything. `get` takes no other argument.",
       },
       prompt: {
         type: "string",
@@ -137,8 +162,8 @@ const RECURRING_PROMPT = {
       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.",
+          "Send it every time you come to rest. Defaults to true when neither `heartbeat_seconds` nor " +
+          "`post_compaction` is given, so a `start` that names no mechanism still does the obvious thing.",
       },
       heartbeat_seconds: {
         type: "integer",
@@ -147,6 +172,13 @@ const RECURRING_PROMPT = {
           "delivery is read at your next tool boundary, so a sub-minute cadence buys no promptness and " +
           "only talks over your own work.",
       },
+      post_compaction: {
+        type: "boolean",
+        description:
+          "Also send it every time your context is compacted. Set this on any effort long enough to be " +
+          "summarized, and make the prompt LINK the doc you are keeping in your scratch directory — that " +
+          "link arriving in the emptied window is what lets you pick the work back up.",
+      },
     },
     required: ["action"],
   },
@@ -167,7 +199,7 @@ const TIMER = {
     "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" +
+    "to switch off afterwards and nothing to sign off from.\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, " +
@@ -217,6 +249,63 @@ const TIMER = {
   },
 }
 
+
+const WATCH_PR = {
+  name: "watch_pr",
+  description:
+    "REGISTER A PULL REQUEST and frizz brings you back whenever something happens on it — CI turning " +
+    "green or red, and every later review, approval or comment, from a human or a bot alike. Register " +
+    "it, come to rest, and you are woken. Drop it when it stops mattering.\n\n" +
+    "IT REPORTS REPEATEDLY, unlike a timer. One registration covers the whole life of the PR: CI goes " +
+    "red, you push a fix, CI goes green, a reviewer comments — that is four wakes from one call, and you " +
+    "never have to re-register between them. It settles itself when the PR merges or closes, because " +
+    "there is then nothing left to report.\n\n" +
+    "REGISTER IT THE MOMENT YOU OPEN OR PUSH A PR. Nothing else watches for you: your runtime knows " +
+    "nothing about GitHub, and an ```awaiting fence STATES what you are waiting on without creating any " +
+    "wait at all. This tool is the wait.\n\n" +
+    "THE ```awaiting FENCE IS STILL WORTH WRITING, and it is a different job: it is how you come to REST " +
+    "without frizz asking you for a handoff, and how the human sees what you are waiting for. Register " +
+    "the watcher with this tool, then name the same PR on a `pr-watch:` line in your fence.\n\n" +
+    "REGISTERING IS IDEMPOTENT per pull request: asking twice returns the SAME id and tells you it was " +
+    "already armed, so re-registering after a compaction is safe and is the right instinct. Use `list` " +
+    "when you want to know what you are holding without changing anything — it answers with each PR's " +
+    "current check state too.\n\n" +
+    "You can only ever watch a PR on your OWN thread — there is no parameter for anyone else's.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      action: {
+        type: "string",
+        enum: ["add", "list", "drop"],
+        description:
+          "`add` registers a watcher (idempotent per PR); `drop` withdraws one by id; `list` reads back " +
+          "everything armed on this thread, with each PR's latest check state, without changing " +
+          "anything. Every action answers with the full armed set.",
+      },
+      target: {
+        type: "string",
+        description:
+          "Required for `add`. The pull request, as `owner/repo#123` or a GitHub PR URL. A ref that " +
+          "cannot be parsed is REFUSED rather than stored — a watcher that can never fire is worse than " +
+          "no watcher, because you would come to rest believing you were covered.",
+      },
+      for: {
+        type: "string",
+        description:
+          "REQUIRED for `add`. How long to watch, as a DURATION — `30m`, `2h`, `3d` (max 24h). Never an " +
+          "instant, and there is no default. A PR nobody ever reviews would otherwise be polled forever " +
+          "and hold your thread with it; the watcher settles itself when this runs out and tells you, " +
+          "and you re-register if you still care.",
+      },
+      id: {
+        type: "string",
+        description: "Required for `drop`. The watcher id returned by `add` (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
@@ -224,13 +313,53 @@ const TIMER = {
 const MIN_INTERVAL_SECONDS = 60
 const MAX_INTERVAL_SECONDS = 24 * 60 * 60
 
-const TOOLS = [SPAWN_THREAD, RECURRING_PROMPT, TIMER]
+const ACTIVITY = {
+  name: "activity",
+  description:
+    "EVERYTHING YOU CURRENTLY HAVE RUNNING, with the id each one is named by — your background shells, " +
+    "your sub-agents, your armed timers, and the pull requests you registered.\n\n" +
+    "WHY YOU NEED IT: an ```awaiting fence names what you are waiting on BY ID, and frizz checks every " +
+    "one against what is actually live. A name that matches nothing is not a park — you are bumped and " +
+    "your thread queues. So if you have lost an id (a compaction, a long turn, a wake you did not " +
+    "expect), call this rather than guessing. Guessing is the failure this tool exists to remove.\n\n" +
+    "It takes nothing and changes nothing. You can only ever read your OWN thread.",
+  inputSchema: { type: "object", properties: {}, required: [] },
+}
+
+const TOOLS = [SPAWN_THREAD, RECURRING_PROMPT, TIMER, WATCH_PR, ACTIVITY]
 
 /** @type {Record<string, (args: Record<string, unknown>) => Promise<string>>} */
 const HANDLERS = {
   [SPAWN_THREAD.name]: spawnThread,
   [RECURRING_PROMPT.name]: recurringPrompt,
   [TIMER.name]: timer,
+  [WATCH_PR.name]: watchPr,
+  [ACTIVITY.name]: activity,
+}
+
+/** Read out every background thing this thread has running, in the shape an awaiting fence names them.
+ * @returns {Promise<string>} */
+async function activity() {
+  const result = (await callRpc("listOwnThreadActivity", { slug: threadSlug() }))?.result
+  const items = Array.isArray(result?.activity) ? result.activity : []
+  if (!items.length) {
+    return (
+      "Nothing is running on this thread — no background shells, no sub-agents, no armed timers, no " +
+      "registered PRs.\n\nSo there is nothing to wait on: an ```awaiting fence would have nothing to " +
+      "name, and a fence naming nothing is not a park. End with ```done, or with a ```question if you " +
+      "need the human."
+    )
+  }
+  const lines = items.map((i) => {
+    const when = i.until ? `  (fires ${i.until})` : i.since ? `  (since ${i.since})` : ""
+    return `  ${i.kind}: ${i.id}${when}\n    ${i.label}`
+  })
+  return (
+    `${items.length} thing${items.length === 1 ? "" : "s"} running on this thread:\n\n${lines.join("\n")}\n\n` +
+    "Name the ones you are ACTUALLY waiting on in your ```awaiting fence, one `<kind>: <id>` line each, " +
+    "plus a required `for:` duration and a one-line `reason:`. Do not name something you are not waiting " +
+    "on — a dev server you left running is not a wait."
+  )
 }
 
 /** @param {unknown} obj */
@@ -250,22 +379,139 @@ 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
+/**
+ * Whether a pid is running. EPERM means someone else's live process, which is still ALIVE.
+ *
+ * A lock with NO pid reads as alive: absence of evidence is not evidence of death, and discarding a
+ * record written by an older or foreign publisher would turn a working server into "none found".
+ */
+function pidAlive(pid) {
+  if (pid === undefined || pid === null) return true
+  if (!Number.isInteger(pid)) return true
   try {
-    parsed = JSON.parse(readFileSync(lock, "utf8"))
+    process.kill(pid, 0)
+    return true
   } catch (err) {
-    throw new Error(`could not read the frizz server lock at ${lock} (is the server running?): ${err instanceof Error ? err.message : err}`)
+    return err?.code === "EPERM"
   }
-  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.
+/** A lock file's `{port, pid}`, or undefined if it is missing, malformed, or names a DEAD process. */
+function liveLock(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"))
+    if (!Number.isInteger(parsed?.port)) return undefined
+    if (!pidAlive(parsed?.pid)) return undefined
+    return { port: parsed.port, path }
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * FIND THE RUNNING FRIZZ — every call, never cached, never frozen at spawn.
+ *
+ * This process is spawned once, inside a DETACHED worker daemon that outlives restart after restart.
+ * An address handed to it in its env is therefore true exactly until the next "Update & Restart", and
+ * a worker whose only address was stale simply lost every frizz tool it had — with no way back short of
+ * restarting the worker itself, which is not what an update button should mean.
+ *
+ * So the env is a HINT and the file is the truth, in this order:
+ *   1. FRIZZ_SERVER_LOCK  — the lock this server published when it spawned us. Right almost always.
+ *   2. `<frizz root>/server.lock` — the MACHINE address (frizz-paths.ts `serverAddressPath`), rewritten
+ *      by every boot whatever project launched it. This is what makes a live worker survive an update.
+ *   3. `<state dir>/server.lock` — our own project's, for a server that only ever serves one project.
+ *   4. any live `<frizz root>/projects/*​/server.lock` — last resort, since one machine runs one frizz.
+ *
+ * A candidate whose PID IS DEAD IS SKIPPED, which is the difference between a legible failure and the
+ * one that cost an afternoon: a stale lock from a long-dead per-project server sent every call at a port
+ * nothing was listening on, and the tool reported only "fetch failed".
+ *
+ * The frizz root is `../..` from the state dir rather than computed: this file is dependency-free and
+ * the real root is platform-dependent (XDG, `~/Library/Application Support`, a legacy `~/.frizz`).
+ */
+function serverLockPort() {
+  const stateDir = process.env.FRIZZ_STATE_DIR
+  const root = stateDir ? dirname(dirname(stateDir)) : undefined
+  const candidates = [
+    process.env.FRIZZ_SERVER_LOCK,
+    root ? join(root, "server.lock") : undefined,
+    stateDir ? join(stateDir, "server.lock") : undefined,
+  ].filter(Boolean)
+  for (const path of candidates) {
+    const live = liveLock(path)
+    if (live) return live.port
+  }
+  // Nothing we were told about is alive. One machine runs one frizz, so any project's live lock names
+  // it — and addressing by project id (rpcPath) means a server that does not serve us answers 404
+  // rather than acting on the wrong board.
+  if (root) {
+    let entries = []
+    try { entries = readdirSync(join(root, "projects")) } catch {}
+    for (const entry of entries) {
+      const live = liveLock(join(root, "projects", entry, "server.lock"))
+      if (live) return live.port
+    }
+  }
+  if (candidates.length === 0) throw new Error("FRIZZ_STATE_DIR / FRIZZ_SERVER_LOCK not set — cannot locate the frizz server")
+  // SAY THAT NOTHING WAS SAVED, and say to retry. A worker reads "is frizz running?" as a fact about the
+  // world rather than as a fact about ITS OWN call, and moves on — so whatever it was arming is silently
+  // gone. Measured 2026-08-17: a worker's `recurring_prompt start` hit a restart window, got this error,
+  // carried on, and its Goal — the thing keeping a long autonomous effort alive — never existed. The
+  // window is ordinary (frizz restarts, and this process outlives every one of them), so the recovery has
+  // to be ordinary too: try again.
+  throw new Error(
+    `no running frizz server found (looked at ${candidates.join(", ")} and every project lock under ` +
+    `${root ? join(root, "projects") : "the frizz root"}; each was missing, malformed, or written by a process that is gone). ` +
+    `NOTHING WAS SAVED — this call had no effect. frizz is probably mid-restart, which is ordinary and ` +
+    `brief; RETRY this exact call before you do anything else, and do not come to rest assuming it took.`,
+  )
+}
+
+/**
+ * The RPC base for OUR project.
+ *
+ * One frizz serves every project on the machine, and an unprefixed `/_frizz/rpc/…` is the project it
+ * was LAUNCHED from — so without the prefix a worker in any other project acted on the launcher's
+ * board (spawn_thread put its new thread there; the thread-scoped tools looked for a slug that lives
+ * in a different registry). FRIZZ_PROJECT_ID is the immutable registry id rather than the slug,
+ * because the value is handed over once at spawn and then held for the life of a detached daemon,
+ * and a project can be renamed under it. Unset ⇒ unprefixed, which is what a server that only ever
+ * serves one project passes, and what the launching project's own workers get.
+ * @param {string} procedure
+ */
+function rpcPath(procedure) {
+  const project = projectSegment()
+  return `${project ? `/_frizz/${encodeURIComponent(project)}` : "/_frizz"}/rpc/${procedure}`
+}
+
+/**
+ * WHICH PROJECT WE ACT ON — always the one this worker is actually running in.
+ *
+ * There is deliberately no tool parameter for it and no way to name another project: the id comes from
+ * the server's stamp, or failing that from the tree we are standing in (`<root>/.frizz/.id`, the same
+ * file project-root.ts treats as identity). Spawning a thread onto somebody else's board is therefore
+ * not something a model can express, rather than something it is asked not to do.
+ *
+ * The walk-up is what makes this work for a worker spawned by a server that predates the stamp, and it
+ * is the honest source anyway: a worker's project is wherever its cwd is, and that cannot go stale.
+ */
+function projectSegment() {
+  const stamped = process.env.FRIZZ_PROJECT_ID
+  if (stamped) return stamped
+  let dir = process.cwd()
+  for (;;) {
+    try {
+      const id = readFileSync(join(dir, ".frizz", ".id"), "utf8").trim()
+      if (id) return id
+    } catch {}
+    const parent = dirname(dir)
+    if (parent === dir) return undefined
+    dir = parent
+  }
+}
+
+/** The `spawn_thread` handler: POST /_frizz/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() : ""
@@ -288,7 +534,7 @@ async function spawnThread(args) {
   const timer = setTimeout(() => controller.abort(), DISPATCH_TIMEOUT_MS)
   let res
   try {
-    res = await fetch(`http://127.0.0.1:${port}/rpc/dispatch`, {
+    res = await fetch(`http://127.0.0.1:${port}${rpcPath("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).
@@ -319,13 +565,40 @@ async function spawnThread(args) {
 /** 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>} */
+// HOW LONG A RESTART WINDOW IS ALLOWED TO BE INVISIBLE. frizz replaces its own server routinely
+// ("Update & Restart", a dev rebuild), and this process is deliberately still here across every one of
+// them — so a call landing in that gap is ORDINARY, and failing it is the shim reporting frizz's
+// housekeeping as the worker's problem. Measured 2026-08-17: a `recurring_prompt start` landed in one,
+// failed, and the Goal that was keeping a long autonomous effort alive silently never existed.
+//
+// Telling the model to retry (which the error also does) is strictly weaker than retrying, because it
+// only works if the model complies. Bounded and short: a genuinely-down frizz still fails, promptly,
+// with the same message — this only covers the seconds where a new server is coming up.
+const LOCK_RETRY_MS = 6_000
+const LOCK_RETRY_INTERVAL_MS = 400
+
+/** The port, waiting out a brief restart window rather than failing into one. Rethrows the real
+ *  "no running frizz server" error once the budget is spent, so a frizz that is actually down still
+ *  says so — and says it with the retry guidance attached. */
+async function serverLockPortWaiting() {
+  const deadline = Date.now() + LOCK_RETRY_MS
+  for (;;) {
+    try {
+      return serverLockPort()
+    } catch (err) {
+      if (Date.now() >= deadline) throw err
+      await new Promise((r) => setTimeout(r, LOCK_RETRY_INTERVAL_MS))
+    }
+  }
+}
+
 async function callRpc(procedure, body) {
-  const port = serverLockPort()
+  const port = await serverLockPortWaiting()
   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}`, {
+    res = await fetch(`http://127.0.0.1:${port}${rpcPath(procedure)}`, {
       method: "POST",
       headers: { "content-type": "application/json", "sec-fetch-site": "same-origin" },
       body: JSON.stringify(body),
@@ -361,16 +634,73 @@ function threadSlug() {
   return slug
 }
 
-/** The `recurring_prompt` handler: arm or disarm this thread's re-prompt, on either or both triggers.
+/** How a heartbeat cadence reads back to the worker. ONE formatter, because `start` and `get` describe
+ * the same stored number and a worker that saw "every 15 min" armed must not read "every 900s" back.
+ * @param {number|undefined} seconds */
+function cadenceLabel(seconds) {
+  if (typeof seconds !== "number" || !Number.isFinite(seconds)) return undefined
+  return seconds % 60 === 0 ? `${seconds / 60} min` : `${seconds}s`
+}
+
+/** Render an armed recurring prompt for the worker to read: which triggers are live, the cadence, when
+ * each last fired, and the text VERBATIM (never truncated — reading back a summary of your own
+ * instruction is exactly as blind as not reading it).
+ * @param {{ prompt: string, stopHook: boolean, heartbeat: boolean, postCompaction: boolean,
+ *           intervalSeconds?: number, armedAt: string, lastRestFiredAt?: string,
+ *           lastScheduleFiredAt?: string, lastCompactFiredAt?: string }} rp */
+function recurringPromptReport(rp) {
+  const fired = (/** @type {string|undefined} */ at) => (at ? `last fired ${at}` : "never fired yet")
+  const triggers = [
+    rp.stopHook ? `  stop_hook — every time you come to rest (${fired(rp.lastRestFiredAt)})` : null,
+    rp.heartbeat
+      // The SAME cadence form `start` reports (cadenceLabel), or the two readings of one row disagree
+      // about the number they are describing — "every 15 min" armed, "every 900s" read back.
+      ? `  heartbeat — every ${cadenceLabel(rp.intervalSeconds) ?? "?"} (${fired(rp.lastScheduleFiredAt)})`
+      : null,
+    rp.postCompaction ? `  post_compaction — every compaction (${fired(rp.lastCompactFiredAt)})` : null,
+  ].filter(Boolean)
+  // EVERY trigger off is a real, reachable state — the human can switch them off in the footer without
+  // clearing the words — and it is the one a worker would otherwise misread as "armed and running".
+  const head = triggers.length
+    ? `Armed since ${rp.armedAt}, on:\n${triggers.join("\n")}`
+    : `Text is parked (armed ${rp.armedAt}) but EVERY TRIGGER IS OFF — nothing will fire until one is switched back on.`
+  return `${head}\n\nThe text, verbatim:\n\n${rp.prompt}`
+}
+
+/** The `recurring_prompt` handler: arm, disarm, or READ BACK this thread's re-prompt.
  * @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 !== "start" && action !== "stop" && action !== "get") {
+    throw new Error("`action` must be one of \"start\", \"stop\" or \"get\"")
+  }
+
+  if (action === "get") {
+    // A frizz server older than this tool has no such procedure and answers 404. Say what that means,
+    // rather than leaving a worker to read a bare HTTP status as "nothing is armed" — the two answers
+    // could not be further apart.
+    let payload
+    try {
+      payload = await callRpc("getOwnThreadRecurringPrompt", { slug })
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      if (/HTTP 404/.test(message)) {
+        throw new Error(
+          "this frizz server predates the read action, so it cannot tell you what is armed. Treat the " +
+          "armed state as UNKNOWN — do not assume it is empty — and check the thread footer instead.",
+        )
+      }
+      throw err
+    }
+    const rp = payload?.result?.recurringPrompt
+    if (!rp) return "No recurring prompt is armed on this thread. Nothing will re-prompt you."
+    return recurringPromptReport(rp)
+  }
 
   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."
+    await callRpc("setOwnThreadRecurringPrompt", { slug, prompt: null, stopHook: false, heartbeat: false, postCompaction: false })
+    return "Recurring prompt disarmed and cleared. No trigger will fire — not the stop hook, not the heartbeat, not the post-compaction one — and the text is gone from the thread footer."
   }
 
   const prompt = typeof args.prompt === "string" ? args.prompt.trim() : ""
@@ -387,36 +717,56 @@ async function recurringPrompt(args) {
       throw new Error(`\`heartbeat_seconds\` must be between ${MIN_INTERVAL_SECONDS} and ${MAX_INTERVAL_SECONDS}`)
     }
   }
+  const postCompaction = args.post_compaction === true
   // 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 stopHook = typeof args.stop_hook === "boolean" ? args.stop_hook : !hasHeartbeat && !postCompaction
   const heartbeat = hasHeartbeat
-  if (!stopHook && !heartbeat) {
-    throw new Error("at least one is required: set `stop_hook: true`, or give `heartbeat_seconds`, or both")
+  if (!stopHook && !heartbeat && !postCompaction) {
+    throw new Error("at least one is required: set `stop_hook: true`, give `heartbeat_seconds`, set `post_compaction: true`, or any combination")
   }
 
-  await callRpc("setOwnThreadRecurringPrompt", {
+  const written = await callRpc("setOwnThreadRecurringPrompt", {
     slug,
     prompt,
     stopHook,
     heartbeat,
+    postCompaction,
     ...(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`
+  // `replaced` is absent against a server that predates it, which is indistinguishable from "there was
+  // nothing" — so the clause only ever appears when the row genuinely carried something.
+  const replaced = written?.result?.replaced
+
+  const every = heartbeat ? cadenceLabel(interval) : null
+  // One clause per armed trigger, joined — with three of them the old nested ternary could no longer say
+  // what was actually armed, and a worker that misreads which trigger it holds waits for a delivery that
+  // is never coming.
+  const clauses = [
+    stopHook ? "every time you come to rest" : null,
+    every ? `every ${every} (the heartbeat reaches you mid-turn)` : null,
+    postCompaction ? "every time your context is compacted, delivered into the emptied window" : null,
+  ].filter(Boolean)
+  const when = clauses.length === 1
+    ? clauses[0]
+    : `${clauses.slice(0, -1).join(", ")} AND ${clauses[clauses.length - 1]}`
+  // Spelled out in full, not summarized: if this overwrote the human's own edit, the words themselves
+  // are the only way the worker can put them back.
+  const superseded = replaced
+    ? `\n\nIT REPLACED an existing recurring prompt — check that discarding it was intended, and restore ` +
+      `it with another \`start\` if it was not:\n\n${recurringPromptReport(replaced)}\n`
+    : ""
+  // NO QUESTION HOLD ANY MORE (2026-08-16). Every trigger fires while you are waiting on the human, and
+  // the at-rest one fires over your own unanswered ```question fence — the delivery says so, and expects
+  // you to decide the question yourself rather than re-ask it. A ```done fence, and an ```awaiting on a
+  // wait frizz itself will deliver, still stop the at-rest trigger.
   return (
-    `Recurring prompt armed — frizz will send you this ${when}. It replaces any recurring prompt this ` +
-    "thread had before.\n\n" +
+    `Recurring prompt armed — frizz will send you this ${when}.${superseded}\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."
+    "Signing off with a ```done fence stops it too, but only when there is genuinely nothing left: it " +
+    "files the thread away until the human sends more work."
   )
 }
 
@@ -498,6 +848,70 @@ async function timer(args) {
   )
 }
 
+
+/** How the armed PR-watcher set reads back, on every action, so a worker never needs a second call.
+ * @param {{ watches?: Array<{id: string, target: string, github?: {checks: string, running: number, passed: number, failed: number, failing: string[], merge: string, state: string}}> }|undefined} result */
+function armedPrWatchList(result) {
+  const watches = Array.isArray(result?.watches) ? result.watches : []
+  if (!watches.length) return "No pull requests are watched on this thread — nothing will wake you."
+  const lines = watches.map((w) => {
+    const g = w.github
+    // The CHECK STATE rides the read-back because it is the reason a worker is listing at all: "where do
+    // my PRs stand" is one call, not one per PR through `gh`.
+    const state = !g
+      ? "not polled yet"
+      : g.state !== "open"
+        ? g.state
+        : g.checks === "passing" ? `checks green (${g.passed})`
+        : g.checks === "failing" ? `checks FAILING${g.failing.length ? `: ${g.failing.join(", ")}` : ""}`
+        : g.checks === "running" ? `checks running (${g.running} left)`
+        : "no checks"
+    return `  ${w.id}  ${w.target}  —  ${state}${g && g.state === "open" && g.merge === "mergeable" ? ", mergeable" : ""}`
+  })
+  return `Watched on this thread now:\n${lines.join("\n")}`
+}
+
+/** The `watch_pr` handler: register, withdraw, or read back this thread's PR watchers.
+ * @param {Record<string, unknown>} args @returns {Promise<string>} */
+async function watchPr(args) {
+  const slug = threadSlug()
+  const action = typeof args.action === "string" ? args.action.trim() : ""
+  if (action !== "add" && action !== "list" && action !== "drop") {
+    throw new Error("`action` must be one of \"add\", \"list\" or \"drop\"")
+  }
+
+  if (action === "list") {
+    return armedPrWatchList((await callRpc("listOwnPrWatches", { slug }))?.result)
+  }
+
+  if (action === "drop") {
+    const id = typeof args.id === "string" ? args.id.trim() : ""
+    if (!id) throw new Error("`id` is required to drop a watcher — take it from `add` or from `list`")
+    const result = (await callRpc("dropOwnPrWatch", { slug, id }))?.result
+    // A drop that matched nothing is reported rather than swallowed: the id was wrong, already settled,
+    // or another thread's — and a worker that believes it withdrew a wait it still holds will rest.
+    const head = result?.dropped
+      ? `Watcher ${id} dropped. It will not wake you.`
+      : `No ARMED watcher ${id} on this thread — it was already settled, or the id is not one of yours.`
+    return `${head}\n\n${armedPrWatchList(result)}`
+  }
+
+  const target = typeof args.target === "string" ? args.target.trim() : ""
+  if (!target) throw new Error("`target` is required — the pull request, as `owner/repo#123` or a PR URL")
+  const result = (await callRpc("addOwnPrWatch", { slug, target, for: typeof args.for === "string" ? args.for.trim() : "" }))?.result
+  const id = result?.id ?? "(unknown)"
+  const ref = result?.target ?? target
+  const head = result?.alreadyArmed
+    ? `Already watching ${ref} as ${id} — nothing new was registered, and you will be woken once per event.`
+    : `Watching ${ref} as ${id}. Frizz wakes you when CI passes or fails and on every later review or ` +
+      "comment, and the registration survives your turn ending, a compaction and a frizz restart."
+  return (
+    `${head}\n\nNAME IT IN YOUR \`\`\`awaiting FENCE TOO (\`pr-watch: ${ref}\`) — the watcher does the ` +
+    `waking, the fence is what lets you come to rest and shows the human what you are waiting for.\n\n` +
+    `DROP IT when it stops mattering (\`action: "drop", id: "${id}"\`).\n\n${armedPrWatchList(result)}`
+  )
+}
+
 /** @param {any} msg */
 async function handle(msg) {
   const { id, method, params } = msg ?? {}