frizz 0.8.0 → 0.9.0

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

@@ -6,7 +6,7 @@
  *
  *   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
+ *   goal — 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.
  *
@@ -110,30 +110,29 @@ const SPAWN_THREAD = {
   },
 }
 
-const RECURRING_PROMPT = {
-  name: "recurring_prompt",
+const GOAL = {
+  name: "goal",
   description:
-    "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" +
+    "Arm a GOAL 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. The board shows it as the thread's Goal. (This tool was " +
+    "named `goal` until 2026-08-28 — a summary or note that says so means this one.)\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" +
-    "  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" +
+    "  post_compaction    — every time your CONTEXT IS COMPACTED, delivered into the emptied window. If " +
+    "you keep notes in your scratch directory, a prompt that LINKS them 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; any combination is fine.\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, " +
+    "thread has AT MOST ONE goal, 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 " +
@@ -156,7 +155,7 @@ const RECURRING_PROMPT = {
         type: "string",
         enum: ["start", "stop", "get"],
         description:
-          "`start` arms (or replaces) this thread's recurring prompt; `stop` disarms it; `get` reads back " +
+          "`start` arms (or replaces) this thread's goal; `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.",
       },
@@ -183,9 +182,8 @@ const RECURRING_PROMPT = {
       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.",
+          "Also send it every time your context is compacted, into the emptied window — useful when the " +
+          "prompt links notes you keep in your scratch directory.",
       },
     },
     required: ["action"],
@@ -203,16 +201,16 @@ const TIMER = {
   description:
     "Set a ONE-OFF timer on YOUR OWN thread: a piece of text frizz hands back to you at ONE instant, " +
     "ONCE. Your own alarm clock.\n\n" +
-    "It is `recurring_prompt`'s heartbeat with the repetition taken out, and it shares the property that " +
+    "It is `goal`'s heartbeat with the repetition taken out, and it shares the property that " +
     "matters: the delivery reaches you MID-TURN — a queued message you read at your next tool boundary — " +
     "so it arrives when you asked for it whether or not you have stopped, and it never aborts what you " +
-    "are running. Unlike a recurring prompt it fires exactly once and then is gone, so there is nothing " +
+    "are running. Unlike a goal it fires exactly once and then is gone, so there is nothing " +
     "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" +
+    "independent, unlike the single goal this thread can hold.\n\n" +
     "USE IT for anything you want to come back to at a specific time: re-check a deploy in ten minutes, " +
     "re-read a slow log at the top of the hour, revisit a decision after a build finishes. USE " +
-    "`recurring_prompt` instead when the thing must repeat, and remember that Claude Code's own " +
+    "`goal` instead when the thing must repeat, and remember that Claude Code's own " +
     "`CronCreate`/`ScheduleWakeup` cannot fire in the runtime frizz runs you in.\n\n" +
     "IT IS NOT A WAY TO POLL SOMETHING YOU COULD WAIT ON. If a background shell, a sub-agent or a " +
     "monitor can tell you the moment a thing happens, use that — an alarm every N seconds asking \"is it " +
@@ -315,6 +313,328 @@ const WATCH_PR = {
   },
 }
 
+// The registry that replaces a ```awaiting fence's `shells:` line: a wait the worker CREATES rather
+// than one it restates at every rest. Two tools rather than one action-switch, because they are two
+// verbs and a worker reaching for `unwatch` should find `unwatch`. See plans/rest-by-registration.md.
+const WATCH = {
+  name: "watch",
+  description:
+    "REGISTER A WAIT on something this thread already has running — a background shell, a sub-agent — " +
+    "and frizz holds your thread out of the queue until it finishes, then brings you back.\n\n" +
+    "IT IS THE WAIT, NOT A STATEMENT ABOUT ONE. A ```awaiting fence NAMES what you are waiting on and " +
+    "has the lifetime of the message carrying it, so it has to be rewritten at every single rest and is " +
+    "wrong the moment anything changes. This creates a ROW: it survives your turn ending, a compaction " +
+    "and a frizz restart, and it keeps holding your thread whatever you say next.\n\n" +
+    "`for` IS REQUIRED and it is a DURATION, never an instant. When it runs out the row is CANCELLED " +
+    "and you are woken to re-decide — that is deliberate, and it is what stops a wait outliving the " +
+    "reason you made it. Register again if you still mean it.\n\n" +
+    "THE TARGET IS CHECKED AGAINST WHAT IS ACTUALLY RUNNING, not against its shape. A handle nothing " +
+    "live answers to is REFUSED rather than stored, and so is a `kind` that disagrees with what frizz " +
+    "can see — a sub-agent registered as a shell is refused and told what it actually is. If you have " +
+    "lost an id (a compaction, a long turn), call `activity` rather than guessing.\n\n" +
+    "A SUB-AGENT ALREADY HOLDS YOUR THREAD without any registration, so the case this exists for is a " +
+    "background SHELL: frizz cannot tell a build you are waiting on from a dev server you started and " +
+    "moved on from, and only you know which it is.\n\n" +
+    "NEVER WATCH SOMETHING YOU INTEND TO OUTLIVE. A dev server, a log tail, a file watcher — those are " +
+    "things you started, not things you are waiting for, and registering one parks your thread on work " +
+    "that will never finish.\n\n" +
+    "REGISTERING IS IDEMPOTENT per (kind, target): asking twice returns the SAME id, says it was " +
+    "already armed, and leaves the original expiry alone — so re-registering after a compaction is safe " +
+    "and is the right instinct. Use `unwatch` to withdraw one. A PULL REQUEST is `watch_pr`, not this: " +
+    "that one polls GitHub and reports repeatedly.\n\n" +
+    "You can only ever watch work on your OWN thread.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      kind: {
+        type: "string",
+        enum: ["shell", "agent"],
+        description:
+          "What the target IS. Checked against live telemetry, not taken on trust — the two kinds of " +
+          "handle are both opaque runtime strings and look identical, so frizz answers this exactly " +
+          "rather than guessing, and refuses a mismatch by name.",
+      },
+      target: {
+        type: "string",
+        description:
+          "The handle you were shown. For a shell that is the runtime's own background-task id " +
+          "(\"Command running in background with ID: bzvtnt3ig\"); its launch tool_use id and its " +
+          "command label are accepted too. For a sub-agent it is the dispatch id or its description. " +
+          "`activity` prints all of them.",
+      },
+      for: {
+        type: "string",
+        description:
+          "REQUIRED. How long to hold the wait, as a DURATION — `30m`, `2h`, `3d` (max 24h). Never an " +
+          "instant, and there is no default: choose it for THIS wait. When it elapses the row is " +
+          "cancelled and you are woken to re-decide, so an over-long guess costs a wait that outlives " +
+          "its reason and a too-short one costs one extra turn.",
+      },
+    },
+    required: ["kind", "target", "for"],
+  },
+}
+
+const UNWATCH = {
+  name: "unwatch",
+  description:
+    "WITHDRAW A WATCH you registered with `watch`, by its id. It stops holding your thread out of the " +
+    "queue and it will not wake you.\n\n" +
+    "Use it the moment a wait stops mattering — you decided not to wait for that build after all, or " +
+    "you are about to end the thread. A watch you no longer care about still parks you, and a thread " +
+    "parked on a wait nobody is waiting for is invisible to the human.\n\n" +
+    "You do NOT need this when the work simply finishes: frizz settles the row itself and wakes you. " +
+    "`activity` prints the id of everything you hold.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      id: {
+        type: "string",
+        description: "The watch id `watch` returned (or that `activity` lists). Only your own thread's.",
+      },
+    },
+    required: ["id"],
+  },
+}
+
+// ---- `ask` / `unask`: a question the human owes an answer to, as a ROW ------------------------------
+
+// The question tree, generated rather than written three times over. MCP tool schemas are JSON Schema,
+// and a `$ref` cycle is the natural way to express a recursive shape — but client support for one is
+// uneven, and a schema a client silently drops is a tool a worker cannot call. ASK_MAX_DEPTH is 3, so
+// the nesting is INLINED to exactly that depth: `followUps` simply does not exist on the deepest level,
+// which makes the limit visible in the schema instead of being a refusal the worker meets at runtime.
+const ASK_MAX_DEPTH = 3
+/** @param {number} depth 1 = the root question. @returns {Record<string, unknown>} */
+function questionSchema(depth) {
+  const option = {
+    type: "object",
+    properties: {
+      label: { type: "string", description: "The choice itself, short — this is what the answer hands back to you." },
+      description: {
+        type: "string",
+        description:
+          "ONE LINE of trade-off. What this option costs, or why it is the one to take. An option list " +
+          "with no trade-offs asks the human to reconstruct your reasoning before they can choose.",
+      },
+      recommended: {
+        type: "boolean",
+        description:
+          "Mark the ONE option you would take, and put it first. At most one per question — a " +
+          "recommendation on two of three choices says nothing. IF YOU CAN MARK ONE, ASK YOURSELF WHY " +
+          "YOU ARE ASKING: you already know the answer, so implement it and say which way you went. " +
+          "This is for the fork you genuinely cannot take yourself.",
+      },
+      preview: {
+        type: "string",
+        description:
+          "Markdown revealed under this option when the human picks it — the diff it produces, the " +
+          "message that would be posted, the mockup. Use it when SEEING the outcome is what decides the " +
+          "question; skip it when the one-line trade-off already says everything.",
+      },
+      ...(depth < ASK_MAX_DEPTH
+        ? {
+            followUps: {
+              type: "array",
+              maxItems: 4,
+              description:
+                "Questions that become live ONLY if the human picks this option — the conditional " +
+                "branch. A branch nobody takes is never asked and never answered, so this is how you " +
+                "ask \"and if so, which?\" without asking it of somebody who said no. A `multi` " +
+                "question cannot carry these (several picked options would open several branches at " +
+                "once) and neither can a free-text one (there is no answer to branch on).",
+              items: questionSchema(depth + 1),
+            },
+          }
+        : {}),
+    },
+    required: ["label"],
+  }
+  return {
+    type: "object",
+    properties: {
+      question: {
+        type: "string",
+        description:
+          "THE QUESTION, on one line, in the human's own vocabulary. They have their original prompt " +
+          "and nothing else — not your plan, not your notes, not the names you coined while working. " +
+          "Lead with the behaviour, not the identifier. NO \"I\" AND NO \"you\": clicking an option is " +
+          "the HUMAN speaking, so first and second person flip between writer and reader. Name the " +
+          "actor outright instead.",
+      },
+      header: { type: "string", description: "A very short chip label for the card, 12 characters or so — \"Auth method\", \"Storage\"." },
+      kind: {
+        type: "string",
+        enum: ["question", "multi"],
+        description:
+          "`question` = pick ONE. `multi` = pick SEVERAL, for choices that are not mutually exclusive. " +
+          "A question with NO options at all is a free-text box, which is the right shape when you need " +
+          "a name, a value or a sentence rather than a decision between things you have enumerated.",
+      },
+      danger: {
+        type: "boolean",
+        description:
+          "The DESTRUCTIVE gate, and nothing softer: a force-push, a deletion, a history rewrite, a " +
+          "production rollback. It changes two things — the card wears the risk tone, and the human's " +
+          "x cannot dismiss it, because a generic close icon is not consent for something irreversible. " +
+          "Declining must therefore be one of your own options.",
+      },
+      options: {
+        type: "array",
+        maxItems: 8,
+        description: "Two to four is almost always right. Omit entirely for a free-text question.",
+        items: option,
+      },
+    },
+    required: ["question", "kind"],
+  }
+}
+
+const ASK = {
+  name: "ask",
+  description:
+    "ASK THE HUMAN SOMETHING YOU CANNOT DECIDE, as a ROW they still owe an answer to — not a fence in a " +
+    "message. It renders as an answerable card on the board and in the thread, and it STAYS there: it " +
+    "survives your turn ending, a compaction, a restart, and the transcript scrolling past. A fence has " +
+    "the lifetime of the message carrying it, which is why a question written into one is unanswerable " +
+    "an hour later.\n\n" +
+    "YOUR DEFAULT IS TO DECIDE, AND THIS TOOL DOES NOT CHANGE THAT. A reversible call costs minutes to " +
+    "redo; a round-trip to the human costs hours with the whole effort idle. Anything derivable from " +
+    "the code, the conventions or ordinary engineering judgement is yours: make it, say which way you " +
+    "went, and keep moving. THE TEST THAT CATCHES ALMOST EVERY BAD QUESTION: if you are about to mark " +
+    "one option `recommended`, you already know the answer — so implement it instead of asking.\n\n" +
+    "ASK WHEN A WRONG GUESS WOULD BE BOTH COSTLY AND HARD TO UNDO — something destructive or " +
+    "irreversible, an external-facing commitment, a security posture with real exposure, product or UX " +
+    "direction that is genuinely the human's taste to set. And ask when you KNOW the answer but cannot " +
+    "ACT on it: a merge, a publish, a spend, a comment that goes out under their name. Then the " +
+    "recommendation is the point, and it goes first.\n\n" +
+    "ASKING DOES NOT END YOUR TURN. A question waits on a person, so it carries no timeout and expires " +
+    "never — but you keep working. Do everything that does NOT depend on the answer first, and register " +
+    "the question at the moment you find it rather than saving it for the end.\n\n" +
+    "AND WHEN YOU DO STOP, THE OPEN QUESTION IS YOUR SIGN-OFF — rest normally. Frizz draws every open " +
+    "question at the rest you stopped at whether you mention it or not, so nothing you write can hide " +
+    "one. The card draws itself at the rest the question was asked — never write the question into " +
+    "your handoff, because a fence that names or restates a registered question draws nothing (one " +
+    "question, one card).\n\n" +
+    "SEVERAL AT ONCE IS ONE CALL. The card sends every answer as a unit, so a second `ask` for a second " +
+    "question just makes the human send twice. Register them together.\n\n" +
+    "The answer comes back to you as its own wake, restating what was asked. Withdraw one you no longer " +
+    "need with `unask` — a question you have since answered yourself, still sitting on the human's " +
+    "board, is worse than never having asked it.\n\n" +
+    "ON AN AUTONOMOUS THREAD THIS REFUSES, and tells you the standing instruction you are working " +
+    "under. A thread carrying a rest Goal has already been told to keep going and decide for itself, " +
+    "so the refusal is that instruction arriving at the moment it matters. Decide, and say which way " +
+    "you went in your write-up. If the call is genuinely the human's — destructive, irreversible, or " +
+    "an act you are not permitted to take — put it in your FINAL MESSAGE instead of here; autonomous " +
+    "does not mean nobody is reading.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      questions: {
+        type: "array",
+        minItems: 1,
+        maxItems: 4,
+        description: "The questions to register, together. Each becomes its own card and its own row.",
+        items: questionSchema(1),
+      },
+    },
+    required: ["questions"],
+  },
+}
+
+const UNASK = {
+  name: "unask",
+  description:
+    "WITHDRAW A QUESTION you registered with `ask`, by its id. Its card disappears and the human is " +
+    "never asked.\n\n" +
+    "Use it the moment the question stops mattering: you worked out the answer yourself, the code moved " +
+    "and the fork is gone, or you are about to finish. A stale question on someone's board is worse " +
+    "than no question — they answer it, and the answer is about a decision that no longer exists.\n\n" +
+    "You do NOT need this for a question that gets answered; that settles itself and wakes you. " +
+    "Withdrawing is YOUR move and is never reported back to you as news.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      id: { type: "string", description: "The question id `ask` returned, or that `activity` lists. Only your own thread's." },
+    },
+    required: ["id"],
+  },
+}
+
+const DONE = {
+  name: "done",
+  description:
+    "DECLARE THIS EFFORT FINISHED, with the write-up the human reads. Your thread cards as a checked " +
+    "success in their queue and stays there until they archive it — marking done is not dismissal, and " +
+    "it does not close, archive or hide anything.\n\n" +
+    "FRIZZ CAN REFUSE THIS, which is the whole reason it is a tool rather than a fence. An OPEN " +
+    "QUESTION or an ARMED REGISTRATION blocks it, and the refusal names each one by id: a question " +
+    "nobody answered dies with the card, and a live wait means the thing you were waiting for has not " +
+    "happened yet. Resolve them for real — answer it yourself and `unask`, or `unwatch` the wait you no " +
+    "longer need — then call again. There is no force parameter and there will not be one.\n\n" +
+    "IT ONLY COUNTS WHAT IS REGISTERED. A background shell or a sub-agent you never registered does " +
+    "not block this, because frizz cannot tell a build you are waiting on from a dev server you walked " +
+    "away from. That judgement is yours, and registering it is how you make it.\n\n" +
+    "DONE MEANS THE WORK LANDED, NOT THAT YOU STOPPED. Code committed to the project's mainline; a " +
+    "plan, doc or commissioned report written INTO A FILE. An open pull request is not done — the " +
+    "merge is. An investigation headed for a fix is not done — the fix is. And a verdict that ends in " +
+    "SOMEBODY SHOULD NOW DO SOMETHING (merge it, post this, pick one of these) is not done either: " +
+    "that is an `ask`, carrying your recommendation as the first option.\n\n" +
+    "THE TEST IS NEVER \"HAVE I STOPPED WORKING\". It is: WHAT IS LOST IF NOBODY EVER OPENS THIS " +
+    "THREAD AGAIN? Name one thing and you are not done. Uncertain is not done.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      body: {
+        type: "string",
+        description:
+          "THE CARD, as markdown. One to three sentences, then a bullet per deliverable, each opening " +
+          "with a bolded verb phrase naming what shipped and where. Backtick every path, identifier and " +
+          "command, and make file references real links. It is a LEDGER, not a summary: reasoning, " +
+          "caveats and anything the human must do belong in your final message instead, because a " +
+          "sentence that would read the same in both places belongs in exactly one of them. Nothing " +
+          "here may point vaguely forward — no \"a follow-up could…\". Do it, ask about it, or drop it.",
+      },
+    },
+    required: ["body"],
+  },
+}
+
+const TITLE = {
+  name: "title",
+  description:
+    "NAME THIS THREAD on the human's board, once you actually know what the work is.\n\n" +
+    "WHY IT EXISTS: the name your thread is wearing right now was minted the instant you were " +
+    "dispatched, from the raw text of the prompt, before you had read a single file. It can only ever " +
+    "paraphrase what the operator typed — so it inherits their shorthand, their ambiguity and their " +
+    "typos. One zod thread went onto the board as \"Zon4.5 features and z.properties documentation " +
+    "audit\" because the operator typed \"Zon4.5\" and nothing in the session yet knew the product is " +
+    "called Zod. You know. That is the entire point of this tool.\n\n" +
+    "WHEN TO CALL IT: after you have oriented — read the issue, opened the code, found the bug — and " +
+    "can name the actual work in your own words. Not on arrival: a name you register before you " +
+    "understand the task is the same guess the board already has. Once is normally enough; call it " +
+    "again only if the work turns out to be genuinely something else.\n\n" +
+    "NAME THE WORK, NOT THE PROMPT. \"Is this true? We should probably…\" is what the human said, not " +
+    "what you are doing. A good name is the thing a reader picking one card out of thirty needs: the " +
+    "subject and the verb.\n\n" +
+    "A HUMAN RENAME OUTRANKS YOU, always. If the human has already named this thread, frizz refuses " +
+    "this and tells you so — that is a correct answer, not a failure, and you should not retry it.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      title: {
+        type: "string",
+        description:
+          "The thread's name: 3-8 words, SENTENCE case (capitalize only the first word and proper " +
+          "nouns — \"Fix queue focus\", never \"Fix Queue Focus\"). No trailing period, no ticks, no " +
+          "issue-body quoting. Spell every product, file and identifier the way the PROJECT spells it, " +
+          "not the way the prompt did.",
+      },
+    },
+    required: ["title"],
+  },
+}
+
 // 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
@@ -325,43 +645,92 @@ const MAX_INTERVAL_SECONDS = 24 * 60 * 60
 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" +
+    "EVERYTHING YOU CURRENTLY HAVE OUT, with the id each one is named by — your background shells, your " +
+    "sub-agents, your armed timers, the pull requests you registered, the `wch_…` of every watch holding " +
+    "one of them, and every QUESTION still owed an answer.\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" +
+    "your thread queues. The same goes for the ids `unwatch` and `unask` take, and for the id you put in " +
+    "a ```question fence to PLACE a registered question in your handoff. So if you have lost one (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 — and it is the only way to read your open questions " +
+    "WITHOUT registering or withdrawing one.\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]
+const TOOLS = [SPAWN_THREAD, GOAL, TIMER, WATCH_PR, WATCH, UNWATCH, ASK, UNASK, DONE, TITLE, ACTIVITY]
 
 /** @type {Record<string, (args: Record<string, unknown>) => Promise<string>>} */
 const HANDLERS = {
   [SPAWN_THREAD.name]: spawnThread,
-  [RECURRING_PROMPT.name]: recurringPrompt,
+  [GOAL.name]: goal,
   [TIMER.name]: timer,
   [WATCH_PR.name]: watchPr,
+  [WATCH.name]: watch,
+  [ASK.name]: ask,
+  [UNASK.name]: unask,
+  [DONE.name]: done,
+  [TITLE.name]: title,
+  [UNWATCH.name]: unwatch,
   [ACTIVITY.name]: activity,
 }
 
+/** The `title` handler: register this thread's considered name.
+ * @param {Record<string, unknown>} args @returns {Promise<string>} */
+async function title(args) {
+  const slug = threadSlug()
+  const wanted = typeof args.title === "string" ? args.title.trim() : ""
+  if (!wanted) throw new Error("`title` is required — 3-8 words naming the work, in sentence case")
+  const result = (await callRpc("setOwnThreadTitle", { slug, title: wanted }))?.result
+  if (result?.accepted) return `This thread is now named "${result.title}" on the board.`
+  // The refusal is REPORTED, never thrown: a human who renamed the thread owns its name, and a worker
+  // told "error" would retry a call that can only ever fail again.
+  if (result?.lockedByHuman) {
+    return (
+      `Not renamed — the human has named this thread "${result.title}" themselves, and their name ` +
+      "outranks yours. Leave it; do not call this again for this thread."
+    )
+  }
+  return `Not renamed — frizz did not accept the write. This thread still reads "${result?.title ?? slug}".`
+}
+
 /** 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 : []
+  const questions = Array.isArray(result?.questions) ? result.questions : []
+  // THE QUESTIONS ARE NOT PART OF THE FENCE, so they are printed in their own section and never fed to
+  // the fence builder below. A question waits on a person; there is no `questions:` key to write it into.
+  const askedBlock = questions.length === 0 ? "" : (
+    `\n\n${questions.length} question${questions.length === 1 ? "" : "s"} still owed an answer:\n\n` +
+    questions.map((q) => `  question: ${q.id}\n    ${String(q?.spec?.question ?? "").replace(/\s+/g, " ").slice(0, 160)}`).join("\n") +
+    "\n\nEach one blocks `done` until it is answered or withdrawn, and draws its own card at the rest " +
+    "it was asked — never write it into a handoff. `unask` the ones since decided. A question is never " +
+    "named in an ```awaiting fence."
+  )
   if (!items.length) {
+    if (questions.length > 0) {
+      return (
+        "Nothing is RUNNING on this thread — no background shells, no sub-agents, no armed timers, no " +
+        "registered PRs. So an ```awaiting fence would have nothing to name, and a fence naming nothing " +
+        "is not a park." + askedBlock
+      )
+    }
     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."
+      "registered PRs, and no open questions.\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}`
+    // The `wch_…` id of the watch holding this item, where one is armed — this readout exists to hand a
+    // worker back the ids it lost, and that includes the one `unwatch` takes.
+    const held = i.watchId ? `  [watched as ${i.watchId}]` : ""
+    return `  ${i.kind}: ${i.id}${when}${held}\n    ${i.label}`
   })
   // A READY-TO-PASTE FENCE, not a description of one. The frontmatter is YAML since 2026-08-24 and its
   // keys are PLURAL sequences, so an id printed on its own line is no longer something a worker can copy
@@ -378,7 +747,10 @@ async function activity() {
     "PLURAL key per kind, taking a list — plus a required `for:` duration, and your handoff prose BELOW " +
     "the `---` (there is no `reason:` key).\n\nEverything above, as a fence:\n\n```awaiting\n" +
     `${block.join("\n")}\n  for: 2h\n  ---\n  <what you are waiting for, and what you will do when it lands>\n` +
-    "```\n\nDrop the lines you are not actually waiting on — a dev server you left running is not a wait."
+    "```\n\nDrop the lines you are not actually waiting on — a dev server you left running is not a wait." +
+    "\n\nBETTER THAN NAMING A SHELL IN THE FENCE: `watch` REGISTERS the wait, so it survives your turn " +
+    "ending and you never restate it. Anything already marked `[watched as …]` above needs no fence line." +
+    askedBlock
   )
 }
 
@@ -641,34 +1013,40 @@ async function callRpc(procedure, body) {
  * FRIZZ_THREAD is the fallback: every frizz worker process is tagged with it, so it is right
  * whenever the env is inherited — but it is not relied upon, hence the explicit var first.
  *
- * This is also the reason a model can never point `recurring_prompt` at someone else's thread: the slug is
+ * This is also the reason a model can never point `goal` at someone else's thread: the slug is
  * read from HERE, never from the tool arguments. */
 function threadSlug() {
   const slug = process.env.FRIZZ_THREAD_SLUG || process.env.FRIZZ_THREAD
   if (!slug) {
     throw new Error(
       "this frizz MCP server was not told which thread it belongs to (no FRIZZ_THREAD_SLUG), so it cannot " +
-      "arm a recurring prompt for it. This is a frizz bug — report it rather than working around it.",
+      "arm a goal for it. This is a frizz bug — report it rather than working around it.",
     )
   }
   return slug
 }
 
 /** 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.
+ * the same stored number and a worker that saw "every 15m" armed must not read "every 900s" back.
+ *
+ * The house duration grammar (`packages/web/src/lib/durationLabels.ts`), matching the trailer
+ * `formatIntervalLabel` writes into the delivery itself — a worker reads both.
  * @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`
+  if (seconds % 60 !== 0) return `${seconds}s`
+  const minutes = seconds / 60
+  if (minutes < 60) return `${minutes}m`
+  return minutes % 60 ? `${Math.floor(minutes / 60)}h ${minutes % 60}m` : `${Math.floor(minutes / 60)}h`
 }
 
-/** Render an armed recurring prompt for the worker to read: which triggers are live, the cadence, when
+/** Render an armed goal 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) {
+function goalReport(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,
@@ -687,9 +1065,9 @@ function recurringPromptReport(rp) {
   return `${head}\n\nThe text, verbatim:\n\n${rp.prompt}`
 }
 
-/** The `recurring_prompt` handler: arm, disarm, or READ BACK this thread's re-prompt.
+/** The `goal` handler: arm, disarm, or READ BACK this thread's re-prompt.
  * @param {Record<string, unknown>} args @returns {Promise<string>} */
-async function recurringPrompt(args) {
+async function goal(args) {
   const slug = threadSlug()
   const action = typeof args.action === "string" ? args.action.trim() : ""
   if (action !== "start" && action !== "stop" && action !== "get") {
@@ -714,18 +1092,18 @@ async function recurringPrompt(args) {
       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 (!rp) return "No goal is armed on this thread. Nothing will re-prompt you."
+    return goalReport(rp)
   }
 
   if (action === "stop") {
     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."
+    return "Goal 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() : ""
   if (!prompt) {
-    throw new Error("`prompt` is required to start a recurring prompt — it is the text you will be sent on every trigger")
+    throw new Error("`prompt` is required to start a goal — it is the text you will be sent on every trigger")
   }
 
   const hasHeartbeat = args.heartbeat_seconds !== undefined && args.heartbeat_seconds !== null
@@ -774,15 +1152,15 @@ async function recurringPrompt(args) {
   // 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`
+    ? `\n\nIT REPLACED an existing goal — check that discarding it was intended, and restore ` +
+      `it with another \`start\` if it was not:\n\n${goalReport(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}.${superseded}\n\n` +
+    `Goal 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 " +
@@ -891,6 +1269,143 @@ function armedPrWatchList(result) {
   return `Watched on this thread now:\n${lines.join("\n")}`
 }
 
+/** The armed watches on this thread, as the read-back prints them. */
+function armedWatchList(result) {
+  const watches = Array.isArray(result?.watches) ? result.watches : []
+  if (!watches.length) return "No watches are armed on this thread — nothing here is holding it out of the queue."
+  const lines = watches.map((w) => {
+    const what = w.kind === "agent" ? "sub-agent" : "shell"
+    // The LABEL is frizz's live reading, not a copy stored at registration — so it names the work as it
+    // stands, and its ABSENCE means the target no longer resolves to anything running.
+    const name = w.label ? `${w.label} (${w.target})` : w.target
+    return `  ${w.id}  ${what}: ${name}  —  expires ${w.expiresAt}`
+  })
+  return `Armed on this thread now:\n${lines.join("\n")}`
+}
+
+/** The `watch` handler: register a wait on this thread's own running work.
+ * @param {Record<string, unknown>} args @returns {Promise<string>} */
+async function watch(args) {
+  const slug = threadSlug()
+  const kind = typeof args.kind === "string" ? args.kind.trim() : ""
+  if (kind !== "shell" && kind !== "agent") throw new Error("`kind` must be \"shell\" or \"agent\"")
+  const target = typeof args.target === "string" ? args.target.trim() : ""
+  if (!target) throw new Error("`target` is required — the handle you were shown; `activity` prints them all")
+  const forValue = typeof args.for === "string" ? args.for.trim() : ""
+  if (!forValue) throw new Error("`for` is required — a DURATION like `30m`, `2h` or `3d` (max 24h), never an instant")
+  const result = (await callRpc("addOwnWatch", { slug, kind, target, for: forValue }))?.result
+  const id = result?.id ?? "(unknown)"
+  const head = result?.alreadyArmed
+    ? `Already watching \`${target}\` as ${id} — nothing new was registered, and its original expiry stands.`
+    : `Watching \`${target}\` as ${id}. Your thread is held out of the queue until it finishes, and the ` +
+      "registration survives your turn ending, a compaction and a frizz restart."
+  return (
+    `${head}\n\nWHEN \`for\` RUNS OUT the row is CANCELLED and you are woken to re-decide — register ` +
+    `again if you still mean it.\n\nDROP IT the moment it stops mattering (\`unwatch\`, id \`${id}\`); ` +
+    `you do NOT need to when the work simply finishes.\n\n${armedWatchList(result)}`
+  )
+}
+
+/** The `unwatch` handler: withdraw one registered watch by id.
+ * @param {Record<string, unknown>} args @returns {Promise<string>} */
+async function unwatch(args) {
+  const slug = threadSlug()
+  const id = typeof args.id === "string" ? args.id.trim() : ""
+  if (!id) throw new Error("`id` is required — take it from `watch` or from `activity`")
+  const result = (await callRpc("dropOwnWatch", { 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 on it.
+  const head = result?.dropped
+    ? `Watch ${id} dropped. It is no longer holding your thread, and it will not wake you.`
+    : `No ARMED watch ${id} on this thread — it was already settled, or the id is not one of yours.`
+  return `${head}\n\n${armedWatchList(result)}`
+}
+
+/** Read back what the human still owes an answer on, so a worker never needs a second call to find out.
+ * @param {Record<string, unknown> | undefined} result @returns {string} */
+function openQuestionList(result) {
+  const open = Array.isArray(result?.open) ? result.open : []
+  if (!open.length) return "Nothing else is open on this thread — the human owes you no answer."
+  const lines = open.map((q) => `  ${q.id}  ${(q.spec?.question ?? "").split("\n")[0]}`)
+  return `Open on this thread now:\n${lines.join("\n")}`
+}
+
+/** The `ask` handler: register one or more questions the human owes an answer to.
+ * @param {Record<string, unknown>} args @returns {Promise<string>} */
+async function ask(args) {
+  const slug = threadSlug()
+  const questions = Array.isArray(args.questions) ? args.questions : []
+  if (!questions.length) throw new Error("`questions` is required — at least one question to register")
+  const result = (await callRpc("ask", { slug, questions }))?.result
+  const registered = Array.isArray(result?.registered) ? result.registered : []
+  const lines = registered.map((q) => `  ${q.id}  ${(q.spec?.question ?? "").split("\n")[0]}`)
+  const head = registered.length === 1
+    ? `Registered 1 question. It is on the human's board now and it will stay there until they answer it.`
+    : `Registered ${registered.length} questions. They are on the human's board now and they will stay ` +
+      "there until answered — the card sends every answer as one batch."
+  return (
+    `${head}\n${lines.join("\n")}\n\n` +
+    "KEEP WORKING. A question waits on a person, carries no timeout and does not end your turn — do " +
+    "everything that does not depend on the answer while it sits there. The answer arrives as its own " +
+    "wake, restating what was asked.\n\n" +
+    "WITHDRAW ONE THE MOMENT IT STOPS MATTERING (`unask`), above all if you work the answer out " +
+    `yourself.\n\n${openQuestionList(result)}`
+  )
+}
+
+/** The `unask` handler: withdraw one registered question by id.
+ * @param {Record<string, unknown>} args @returns {Promise<string>} */
+async function unask(args) {
+  const slug = threadSlug()
+  const id = typeof args.id === "string" ? args.id.trim() : ""
+  if (!id) throw new Error("`id` is required — take it from `ask`")
+  const result = (await callRpc("unask", { slug, id }))?.result
+  // A withdrawal that matched nothing is reported rather than swallowed: the id was wrong, the human
+  // already answered it, or it is another thread's — and a worker that believes it withdrew a question
+  // the human is still looking at will get an answer it has stopped expecting.
+  const head = result?.withdrawn
+    ? `Question ${id} withdrawn. Its card is gone and the human will not be asked.`
+    : `No OPEN question ${id} on this thread — it was already answered or dismissed, or the id is not one of yours.`
+  return `${head}\n\n${openQuestionList(result)}`
+}
+
+/** The `done` handler: declare the effort finished, or report exactly what refuses to let it.
+ * @param {Record<string, unknown>} args @returns {Promise<string>} */
+async function done(args) {
+  const slug = threadSlug()
+  const body = typeof args.body === "string" ? args.body.trim() : ""
+  if (!body) throw new Error("`body` is required — the write-up the human reads on the card")
+  const result = (await callRpc("markOwnDone", { slug, body }))?.result
+  if (result?.done) {
+    return (
+      "Marked done. Your thread cards as a checked success in the human's queue and stays there until " +
+      "they archive it.\n\nNOTHING WAS CLOSED, HIDDEN OR ARCHIVED — if there is more to say, say it in " +
+      "your final message; if more work appears, keep going and call this again."
+    )
+  }
+  // REFUSED, with everything that refuses it named by id, so the next move is a tool call and not a
+  // guess. Reported as an ordinary result rather than thrown: this is a gate doing its job, not a fault.
+  const questions = (result?.blockingQuestions ?? []).map((q) => `  ${q.id}  ${(q.question ?? "").split("\n")[0]}`)
+  const watches = (result?.blockingWatches ?? []).map((w) => `  ${w.id}  ${w.what}`)
+  const parts = ["NOT marked done. This thread still holds work open."]
+  if (questions.length) {
+    parts.push(
+      `${questions.length} question${questions.length === 1 ? "" : "s"} the human has not answered:\n${questions.join("\n")}\n` +
+      "Each one dies unread with a done card. Decide it yourself and withdraw it (`unask`), or leave it " +
+      "open and keep working until it is answered.",
+    )
+  }
+  if (watches.length) {
+    parts.push(
+      `${watches.length} registration${watches.length === 1 ? "" : "s"} still armed:\n${watches.join("\n")}\n` +
+      "A live wait means the thing you were waiting for has not happened. Wait for it, or drop the ones " +
+      "that stopped mattering (`unwatch`, or `watch_pr` with `action: \"drop\"`, or `timer` cancel).",
+    )
+  }
+  parts.push("There is no force parameter. Resolve them and call `done` again.")
+  return parts.join("\n\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) {