frizz 0.2.0 → 0.3.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,23 @@ 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.",
+      },
+      pause_on_questions: {
+        type: "boolean",
+        description:
+          "Send NOTHING — on any trigger — for as long as you are waiting on the human: an unanswered " +
+          "```question fence, a native ask, or a permission prompt. DEFAULTS TO TRUE, matching the " +
+          "thread footer, because being told \"keep going\" while you are holding a question up is the " +
+          "one delivery that can only make things worse. Pass false only if you genuinely want a beat " +
+          "to reach you mid-question. (The stop hook declines a rest that ends in a question fence " +
+          "always, whatever this says; this is the wider version and it covers the other triggers.)",
+      },
     },
     required: ["action"],
   },
@@ -167,7 +209,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 +259,84 @@ const TIMER = {
   },
 }
 
+// The blocking mode's bounds. The floor is a poll cycle — below it the call is not a wait, it is a
+// round-trip — and the ceiling matches the worker's own foreground Bash ceiling, so one number governs
+// "the longest a worker may block" wherever it blocks.
+const WATCH_MIN_WAIT_SECONDS = 5
+const WATCH_MAX_WAIT_SECONDS = 24 * 60 * 60
+
+const WATCH = {
+  name: "watch",
+  description:
+    "REGISTER something to wait on, so frizz wakes you when it resolves — and DROP it when it stops " +
+    "mattering. Your waits have identities: you can list them, and you can withdraw them.\n\n" +
+    "  kind: \"shell\"  — one of YOUR OWN background shells finishing. `target` is its id or its label.\n\n" +
+    "FOR A PULL REQUEST, use an ```awaiting fence with a `pr-watch: owner/repo#123` line instead. That " +
+    "watcher is durable, it replays whatever review is already sitting on the PR the first time you park " +
+    "on it, and it is where PR watching lives — this registry is for the waits that have nowhere else to " +
+    "go.\n\n" +
+    "WHY THIS RATHER THAN WAITING YOURSELF: a registered watcher is durable. It survives your turn " +
+    "ending, a compaction, a frizz restart, and your own daemon being replaced — none of which a " +
+    "blocking call or a monitor survives. Register it, come to rest, and frizz brings you back.\n\n" +
+    "REGISTERING IS IDEMPOTENT on (kind, target): asking twice for the same thing 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.\n\n" +
+    "DROP WHAT STOPS MATTERING. A watcher you no longer care about is a wake you did not want and a " +
+    "thread that looks parked when it is not — you are the only one who can know, which is why this " +
+    "tool exists (maintainer: \"this way the agent can decide when they're not necessary\").\n\n" +
+    "You can only ever register a wait 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 on kind+target); `drop` withdraws one by id; `list` " +
+          "reads back everything currently armed on this thread without changing anything. Every action " +
+          "answers with the full armed set, so you never need a second call to see where you stand.",
+      },
+      kind: {
+        type: "string",
+        enum: ["shell"],
+        description:
+          "Required for `add`. The only kind — a PR wait belongs in an ```awaiting fence, see above.",
+      },
+      target: {
+        type: "string",
+        description:
+          "Required for `add`. A background shell's id or its label. A target that does not match one " +
+          "of your live shells still registers, but the watcher only fires once frizz has SEEN it " +
+          "alive — so a typo'd label simply never fires rather than reporting a completion that never " +
+          "happened.",
+      },
+      id: {
+        type: "string",
+        description: "Required for `drop`. The watcher id returned by `add` (or listed by `list`).",
+      },
+      wait: {
+        type: "boolean",
+        description:
+          "For `add`: BLOCK here until it resolves, instead of returning immediately. Requires " +
+          "`timeout_seconds`. Use it when the wait is short enough that keeping the work in ONE turn is " +
+          "worth more than the durability of resting — you keep your context and your place in the " +
+          "reasoning, and no wake message interrupts you. For anything long, register it WITHOUT this " +
+          "and rest: a background registration survives your turn ending, a compaction and a frizz " +
+          "restart, none of which a blocking call survives.",
+      },
+      timeout_seconds: {
+        type: "integer",
+        description:
+          `REQUIRED when \`wait\` is true (minimum ${WATCH_MIN_WAIT_SECONDS}, maximum ` +
+          `${WATCH_MAX_WAIT_SECONDS}). When it expires the call RETURNS rather than failing, and the ` +
+          "watcher is handed to frizz to keep — so the wait is never lost by choosing to block on it. " +
+          "You are then free to do something else and be woken.",
+      },
+    },
+    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 +344,14 @@ const TIMER = {
 const MIN_INTERVAL_SECONDS = 60
 const MAX_INTERVAL_SECONDS = 24 * 60 * 60
 
-const TOOLS = [SPAWN_THREAD, RECURRING_PROMPT, TIMER]
+const TOOLS = [SPAWN_THREAD, RECURRING_PROMPT, TIMER, WATCH]
 
 /** @type {Record<string, (args: Record<string, unknown>) => Promise<string>>} */
 const HANDLERS = {
   [SPAWN_THREAD.name]: spawnThread,
   [RECURRING_PROMPT.name]: recurringPrompt,
   [TIMER.name]: timer,
+  [WATCH.name]: watch,
 }
 
 /** @param {unknown} obj */
@@ -250,22 +371,132 @@ 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"
+  }
+}
+
+/** 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")
+  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). ` +
+    `Is frizz running?`,
+  )
+}
+
+/**
+ * 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
   }
-  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.
+/** 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 +519,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).
@@ -325,7 +556,7 @@ async function callRpc(procedure, body) {
   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 +592,79 @@ 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,
+ *           pauseOnQuestions?: 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.`
+  // Reported only when ON, and after the triggers: it is a HOLD over the list above rather than an item
+  // in it, so a worker reading this must already know what would fire before it is told what suspends it.
+  const hold = rp.pauseOnQuestions
+    ? "\n\nHELD while you are waiting on the human — nothing is sent for as long as a question fence, a " +
+      "native ask or a permission prompt is unanswered."
+    : ""
+  return `${head}${hold}\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, pauseOnQuestions: 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 +681,60 @@ 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
+  // ON unless the caller says otherwise — the same default the footer panel seeds, so a worker-armed row
+  // and a human-armed one read identically in the panel. An older frizz server ignores the field.
+  const pauseOnQuestions = typeof args.pause_on_questions === "boolean" ? args.pause_on_questions : 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,
+    pauseOnQuestions,
     ...(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`
+    : ""
+  const held = pauseOnQuestions
+    ? " Nothing is sent while you are waiting on the human — a question fence, a native ask or a " +
+      "permission prompt holds every 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}.${held}${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 +816,125 @@ async function timer(args) {
   )
 }
 
+/** How the armed watcher set reads back, on every action, so a worker never needs a second call.
+ * @param {{ watches?: Array<{id: string, kind: string, target: string}> }|undefined} result */
+function armedWatchList(result) {
+  const watches = Array.isArray(result?.watches) ? result.watches : []
+  if (!watches.length) return "Nothing is armed on this thread now — no watcher will wake you."
+  const lines = watches.map((w) => `  ${w.id}  ${w.kind}  ${w.target}`)
+  return `Armed on this thread now:\n${lines.join("\n")}`
+}
+
+/** The `watch` handler: register, withdraw, or read back this thread's waits.
+ * @param {Record<string, unknown>} args @returns {Promise<string>} */
+async function watch(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") {
+    const result = (await callRpc("listOwnThreadWatches", { slug }))?.result
+    return armedWatchList(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("dropOwnThreadWatch", { 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${armedWatchList(result)}`
+  }
+
+  const kind = typeof args.kind === "string" ? args.kind.trim() : ""
+  if (kind !== "shell") {
+    // REFUSED rather than stored. `pr` and `ci` rows are valid in the registry and the scheduler will
+    // poll them once its PR watcher moves off the fence — but today nothing wakes them, and a tool that
+    // accepts a wait it cannot honour is how a worker comes to rest believing it is covered.
+    throw new Error(
+      kind === "pr" || kind === "ci"
+        ? `a ${kind} wait does not belong here — use an \`\`\`awaiting fence with a \`pr-watch: owner/repo#123\` line, which is durable and replays review that is already on the PR`
+        : "`kind` is required to add a watcher, and the only kind is \"shell\"",
+    )
+  }
+  const target = typeof args.target === "string" ? args.target.trim() : ""
+  if (!target) throw new Error("`target` is required — the id or label of one of your own background shells")
+
+  // THE BLOCKING MODE. `foreground` tells frizz to SETTLE this watcher silently rather than wake us —
+  // we are the ones waiting, and a wake landing mid-turn while this call is still blocked would hand the
+  // worker its own answer twice.
+  const wait = args.wait === true
+  let timeoutSeconds = 0
+  if (wait) {
+    if (typeof args.timeout_seconds !== "number" || !Number.isFinite(args.timeout_seconds)) {
+      throw new Error("`timeout_seconds` is required when `wait` is true — a blocking wait with no deadline is a hang")
+    }
+    timeoutSeconds = Math.round(args.timeout_seconds)
+    if (timeoutSeconds < WATCH_MIN_WAIT_SECONDS || timeoutSeconds > WATCH_MAX_WAIT_SECONDS) {
+      throw new Error(`\`timeout_seconds\` must be between ${WATCH_MIN_WAIT_SECONDS} and ${WATCH_MAX_WAIT_SECONDS}`)
+    }
+  }
+
+  const result = (await callRpc("addOwnThreadWatch", { slug, kind, target, ...(wait ? { foreground: true } : {}) }))?.result
+  const id = result?.id ?? "(unknown)"
+  if (wait) return await blockUntilResolved(slug, id, kind, target, timeoutSeconds)
+  const head = result?.alreadyArmed
+    ? `Already watching ${kind} ${target} as ${id} — nothing new was registered, and you will be woken once.`
+    : `Watching ${kind} ${target} as ${id}. Frizz will wake you when it resolves, and the registration ` +
+      "survives your turn ending, a compaction and a frizz restart."
+  return (
+    `${head}\n\nDROP IT when it stops mattering (\`action: "drop", id: "${id}"\`) — a watcher you no ` +
+    `longer care about is a wake you did not want.\n\n${armedWatchList(result)}`
+  )
+}
+
+/** Block until a foreground watcher settles, or until its deadline — then hand it back to frizz.
+ *
+ * POLLED, not pushed, because the MCP transport has no way to be told. The interval BACKS OFF: a wait
+ * that resolves in ten seconds should not be found thirty seconds late, and a wait that runs for hours
+ * should not cost thousands of round-trips to discover that nothing changed.
+ *
+ * The deadline RETURNS rather than throwing, and promotes the row on the way out. That is the property
+ * that makes choosing this mode safe: the worst case of guessing the timeout too short is that the wait
+ * becomes an ordinary durable one and frizz wakes you, not that the wait is silently lost.
+ *
+ * @param {string} slug @param {string} id @param {string} kind @param {string} target @param {number} timeoutSeconds
+ * @returns {Promise<string>} */
+async function blockUntilResolved(slug, id, kind, target, timeoutSeconds) {
+  const deadline = Date.now() + timeoutSeconds * 1000
+  const started = Date.now()
+  for (;;) {
+    const elapsed = Date.now() - started
+    // 2s for the first minute, then 5s, then 15s — see the back-off note above.
+    const interval = elapsed < 60_000 ? 2_000 : elapsed < 600_000 ? 5_000 : 15_000
+    const remaining = deadline - Date.now()
+    if (remaining <= 0) break
+    await new Promise((r) => setTimeout(r, Math.min(interval, remaining)))
+    const listed = (await callRpc("listOwnThreadWatches", { slug }))?.result
+    const still = Array.isArray(listed?.watches) && listed.watches.some((w) => w.id === id)
+    if (!still) {
+      const waited = Math.round((Date.now() - started) / 1000)
+      return (
+        `${kind === "shell" ? "Your background shell" : target} resolved after ${waited}s — that is what you were ` +
+        `waiting for (${target}). The watcher is spent; you were not interrupted, because you were the one waiting.`
+      )
+    }
+  }
+  // The deadline, not a failure. Hand it to frizz so the wait survives this turn.
+  const promoted = (await callRpc("promoteOwnThreadWatch", { slug, id }))?.result
+  return (
+    `Waited ${timeoutSeconds}s and ${target} has NOT resolved yet. The watcher is still armed and is now ` +
+    `frizz's to keep${promoted?.promoted === false ? " (it had already settled)" : ""} — go do something else ` +
+    `and you will be woken when it fires, or drop it with \`action: "drop", id: "${id}"\` if it has stopped ` +
+    "mattering."
+  )
+}
+
 /** @param {any} msg */
 async function handle(msg) {
   const { id, method, params } = msg ?? {}