frizz 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frizz",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "private": false,
   "description": "A local web UI for running many coding agents at once",
   "keywords": [
@@ -38,17 +38,19 @@
     "frizz-dev:uninstall": "nub scripts/install-global-cli.mjs --uninstall",
     "install:global": "nub scripts/install-global-cli.mjs",
     "typecheck": "tsc -b packages/shared packages/rpc packages/server . && pnpm --filter @frizz/web typecheck",
-    "test": "nub --test --test-force-exit 'board/*.test.mjs' 'scripts/**/*.test.mjs' 'src/**/*.test.ts' 'packages/shared/src/**/*.test.ts' 'packages/server/src/**/*.test.ts' 'packages/web/src/**/*.test.ts'",
+    "test": "nub scripts/run-tests.mjs",
     "prepack": "node ./scripts/prepare-package.mjs && node ./scripts/build-package.mjs && node ./scripts/publish-manifest.mjs --strip",
     "postpack": "node ./scripts/publish-manifest.mjs --restore && node ./scripts/prepare-package.mjs --clean"
   },
   "dependencies": {
     "@parcel/watcher": "^2.5",
-    "node-pty": "^1.1"
+    "node-pty": "^1.1",
+    "qrcode-generator": "^2.0.4"
   },
   "devDependencies": {
     "@types/node": "^24",
     "esbuild": "^0.25.0",
+    "jsqr": "^1.4.0",
     "puppeteer": "^25.3.0",
     "typescript": "^5.7"
   },

package/runtime/cc-worker/DECISIONS.md

@@ -125,6 +125,23 @@ decision, not an artifact-portability implementation detail. A future isolation
 which settings/auth surfaces are preserved before adding `--settings`, a config-home override, or a
 global-plugin disable mechanism.
 
+**2026-08-16 — the SDK broker had drifted off this policy, and is back on it.** The tmux transport
+spawned a plain `claude`, which reads all three settings scopes, so the policy above held by default.
+The Agent-SDK broker takes an explicit `settingSources` and the SDK's own default is `[]` — nothing at
+all — so when the broker became the default Claude transport it read no config whatsoever. The
+2026-07-26 fix restored `project` + `local` (the repo's `CLAUDE.md` / `AGENTS.md` / `.claude/skills`)
+and left `user` out, on a rationale written into the code — "the operator's personal `~/.claude` config
+is theirs, not something a dispatched worker should silently inherit" — that this record had already
+rejected. The gap was invisible because everything it withheld fails QUIETLY: the operator's `env`
+block (which is where an API-proxy front-end writes its base-URL/token pair, so a broker session
+authenticates differently from the CLI in the same shell), `autoCompactWindow` (so sessions compacted
+at the default threshold, not the configured one), `permissions`, `hooks` and `enabledPlugins`.
+Measured against the maintainer's real config, one variable, observed through a project-scope hook:
+`--setting-sources=project,local` reported their `env` block UNSET, `user,project,local` reported it
+applied, both sessions exiting 0 with empty stderr. The default is now all three scopes — the same
+thing a plain `claude` in the same cwd reads. A frizz thread is the operator's own session on their own
+machine, so the surprising behavior was the divergence, not the inheritance.
+
 ## 2026-07-02: Stop hook removed
 stop-flush.mjs is no longer wired (script kept for reference). User call: under frizz the
 tailer/board already surface worker state live, and the block-until-file-edited nag forced even

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

@@ -49,6 +49,9 @@ const DISPATCH_TIMEOUT_MS = 30_000
 const SPAWN_THREAD = {
   name: "spawn_thread",
   description:
+    "LAST RESORT — try the two cheaper exits FIRST. Follow-up work you discovered is not a reason to spawn: " +
+    "if you could DO it (dispatching an in-session sub-agent, whose result comes back to you, so the work " +
+    "lands on YOUR card under one review), do that instead; if the human should choose, ASK instead. " +
     "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 " +
@@ -60,6 +63,11 @@ const SPAWN_THREAD = {
     "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. " +
+    "Because nothing it learns ever returns to you OR to its siblings, a chain of spawned threads re-derives " +
+    "the same facts in parallel and nobody notices — measured here: one thread spawned four, three of those " +
+    "spawned more, and three descendants independently rediscovered the same root cause over twenty hours. " +
+    "Spawn only when the work genuinely cannot ride on your own card: a different repo, a different long-lived " +
+    "runtime, an effort that must outlive yours. Never spawn merely to clear your own `done` fence. " +
     "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.",
@@ -179,16 +187,6 @@ const RECURRING_PROMPT = {
           "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"],
   },
@@ -259,32 +257,28 @@ 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",
+const WATCH_PR = {
+  name: "watch_pr",
   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.",
+    "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: {
@@ -292,46 +286,29 @@ const WATCH = {
         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.",
+          "`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.",
       },
-      kind: {
+      target: {
         type: "string",
-        enum: ["shell"],
         description:
-          "Required for `add`. The only kind — a PR wait belongs in an ```awaiting fence, see above.",
+          "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.",
       },
-      target: {
+      for: {
         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.",
+          "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`).",
       },
-      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"],
   },
@@ -344,14 +321,53 @@ const WATCH = {
 const MIN_INTERVAL_SECONDS = 60
 const MAX_INTERVAL_SECONDS = 24 * 60 * 60
 
-const TOOLS = [SPAWN_THREAD, RECURRING_PROMPT, TIMER, WATCH]
+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.name]: watch,
+  [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 */
@@ -446,10 +462,17 @@ function serverLockPort() {
     }
   }
   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). ` +
-    `Is frizz running?`,
+    `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.`,
   )
 }
 
@@ -550,8 +573,35 @@ 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
@@ -604,7 +654,7 @@ function cadenceLabel(seconds) {
  * 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,
+ *           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")
@@ -622,13 +672,7 @@ function recurringPromptReport(rp) {
   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}`
+  return `${head}\n\nThe text, verbatim:\n\n${rp.prompt}`
 }
 
 /** The `recurring_prompt` handler: arm, disarm, or READ BACK this thread's re-prompt.
@@ -663,7 +707,7 @@ async function recurringPrompt(args) {
   }
 
   if (action === "stop") {
-    await callRpc("setOwnThreadRecurringPrompt", { slug, prompt: null, stopHook: false, heartbeat: false, postCompaction: false, pauseOnQuestions: false })
+    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."
   }
 
@@ -682,9 +726,6 @@ async function recurringPrompt(args) {
     }
   }
   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.
@@ -700,7 +741,6 @@ async function recurringPrompt(args) {
     stopHook,
     heartbeat,
     postCompaction,
-    pauseOnQuestions,
     ...(heartbeat ? { intervalSeconds: interval } : {}),
   })
   // `replaced` is absent against a server that predates it, which is indistinguishable from "there was
@@ -725,12 +765,12 @@ async function recurringPrompt(args) {
     ? `\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."
-    : ""
+  // 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}.${held}${superseded}\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. " +
     "Signing off with a ```done fence stops it too, but only when there is genuinely nothing left: it " +
@@ -816,18 +856,32 @@ 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) {
+
+/** 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 "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")}`
+  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` handler: register, withdraw, or read back this thread's waits.
+/** The `watch_pr` handler: register, withdraw, or read back this thread's PR watchers.
  * @param {Record<string, unknown>} args @returns {Promise<string>} */
-async function watch(args) {
+async function watchPr(args) {
   const slug = threadSlug()
   const action = typeof args.action === "string" ? args.action.trim() : ""
   if (action !== "add" && action !== "list" && action !== "drop") {
@@ -835,103 +889,34 @@ async function watch(args) {
   }
 
   if (action === "list") {
-    const result = (await callRpc("listOwnThreadWatches", { slug }))?.result
-    return armedWatchList(result)
+    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("dropOwnThreadWatch", { slug, id }))?.result
+    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${armedWatchList(result)}`
+    return `${head}\n\n${armedPrWatchList(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
+  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)"
-  if (wait) return await blockUntilResolved(slug, id, kind, target, timeoutSeconds)
+  const ref = result?.target ?? target
   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
+    ? `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 (
-    `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."
+    `${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)}`
   )
 }
 

package/runtime/cc-worker/hooks/session-seed.mjs

@@ -67,7 +67,7 @@ const core =
   '⟦frizz worker contract⟧ You are a frizz WORKER driving EXACTLY ONE effort. Your FULL operating contract — the end-of-turn signal fences, scratch-directory rules, sub-agent rules, and the question handback — lives in your SYSTEM PROMPT; follow it there (this is a runtime re-grounding, not a second copy). The human + the frizz app are the ORCHESTRATOR; you drive ONE effort and never scan the board or touch other efforts. There is no orchestrator mode and no fleet to run: doing the work yourself is the default, and you dispatch a sub-agent only when the work genuinely decomposes into independent prongs.\n' +
   'SCRATCH DIRECTORY (OPTIONAL): `' + scratch + '` — a folder kept FOR YOU: any files you like, no format expected, nothing in it read automatically, and never a substitute for doing the work. A single direct task usually needs nothing. On a long effort write the doc you would want if you lost your context — the approach, what you rejected, the human\'s decisions — AS YOU GO, mid-work, then KEEP WORKING, and arm mcp__frizz__recurring_prompt with post_compaction: true and a prompt LINKING that file, because the arming is what brings it back. Give each sub-agent its OWN file rather than a shared one.\n' +
   'DO NOT REST WHILE THE INSTRUCTION HAS PARTS LEFT — finish them in THIS turn; a milestone, a green test run and a long turn are none of them stopping points, and announcing the next step or writing it into a scratch file is not doing it.\n' +
-  'ALWAYS SIGN OFF WITH A FENCE, per the fence rules in your system prompt. A rest with NO fence is not a handoff — it is an item nobody can triage, and frizz will tell you so. ```done only when the effort\'s real work is COMPLETE (code LANDED on the mainline — an open PR is NOT done, park it on ```awaiting until it MERGES) and is a DISMISSAL (its card files the thread away where nobody looks again), so if the thread points at future work AT ALL — a pre-fix investigation, a live code-change discussion — ask a ```question instead, and uncertain is not done; the ONE exception is a planning session whose plan file is fully written and persisted, because that artifact outlives the thread; ```awaiting parks only a human:/timer:/pr-watch: gate, never CI/releases/merge progression (those stay ACTIVE); ```question is the operator ask. Blocked on a PR, CI or your own background shell? REGISTER it with mcp__frizz__watch and rest — it is durable, and you can drop it when it stops mattering. Keep the write-up SHORT: 1-3 sentences, then bullets starting with a **bolded verb phrase**.\n' +
+  'ALWAYS SIGN OFF WITH A FENCE, per the fence rules in your system prompt. A rest with NO fence is not a handoff — it is an item nobody can triage, and frizz will tell you so. ```done only when the effort\'s real work is COMPLETE (code LANDED on the mainline — an open PR is NOT done, park it on ```awaiting until it MERGES) and is a DISMISSAL (its card files the thread away where nobody looks again), so if the thread points at future work AT ALL — a pre-fix investigation, a live code-change discussion, follow-up work you DISCOVERED even when someone else will do it — ask a ```question instead, and uncertain is not done; a verdict that ends in something the HUMAN must now do (post this comment, merge or decline, pick one of these) is a ```question carrying your recommendation as option A, never a done card, because a draft you wrote but did not send is filed away with the thread; when your OWN mandate is complete and what is left is a separable effort, DO it first — dispatch a sub-agent, whose result comes BACK to you, so it lands on YOUR card — and ASK second; mcp__frizz__spawn_thread is the LAST resort, for work that genuinely cannot ride on your card, because a spawned thread reports only to the human and nothing it learns returns to you or its siblings; the ONE exception is a planning session whose plan file is fully written and persisted, because that artifact outlives the thread; ```awaiting parks a human:/timer:/pr-watch: gate or your OWN background work, never CI/releases/merge progression (those stay ACTIVE); ```question is the operator ask. Waiting on your own background shell? Your shells and sub-agents are watched AUTOMATICALLY — frizz wakes you when one finishes, fence or no fence. NAME it on a `watch: <id>` line anyway and rest: that is what lets you stop without frizz asking you for a handoff, and what shows the human what you are waiting for. Frizz checks the name against what you actually have running. Keep the write-up SHORT: 1-3 sentences, then bullets starting with a **bolded verb phrase**. The fence and the prose above it are TWO SURFACES, not one message written twice — the card is the ledger of what shipped, the prose is only what a ledger cannot hold, and a sentence that would read the same in either belongs in exactly one. And a done message says what HAPPENED: delete every dangling "one thing to carry forward" or "a follow-up could" — do it, spawn it onto its own card, ask about it, or DROP it, and if it is not worth a card it is not worth a sentence.\n' +
   'DECIDE rather than ask: anything derivable from the code, the conventions, or ordinary engineering judgment is YOURS to settle — asking permission to do the work you were dispatched to do is not a question, it is the job. Reserve the operator for the irreversible and the genuinely human-owned.';
 
 const grounding =