frayui 0.1.1 → 0.1.3

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "frayui",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": false,
-  "description": "Local orchestration surface for Fray projects — a per-repo web UI over your .fray/ agent threads",
+  "description": "A local dashboard for running many coding agents at once",
   "keywords": [
     "fray",
-    "claude",
-    "claude-code",
     "agents",
+    "claude-code",
+    "codex",
     "orchestration",
-    "tui"
+    "dashboard",
+    "ai"
   ],
   "license": "MIT",
   "author": "Colin McDonnell",
@@ -37,13 +38,13 @@
     "fray-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 @fray-ui/web typecheck",
-    "test": "nub --test --test-force-exit 'scripts/**/*.test.mjs' 'src/**/*.test.ts' 'packages/shared/src/**/*.test.ts' 'packages/server/src/**/*.test.ts' 'packages/web/src/**/*.test.ts'",
+    "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'",
     "prepack": "node ./scripts/prepare-package.mjs && node ./scripts/build-package.mjs && node ./scripts/publish-manifest.mjs --strip",
     "postpack": "node ./scripts/publish-manifest.mjs --restore"
   },
   "dependencies": {
     "@parcel/watcher": "^2.5",
-    "better-sqlite3": "^12",
+    "better-sqlite3": "^13",
     "node-pty": "^1.1"
   },
   "devDependencies": {

package/runtime/cc-worker/DECISIONS.md

@@ -921,3 +921,89 @@ sub-agent should merge its own scoped progress as it works. Deliverable file own
 the Fray scratchpad, and a root must reconcile concurrent scoped updates rather than act as sole
 writer. The existing merge-safety rules remain unchanged: re-read first, preserve all other content,
 and never delete, truncate, reinitialize, move, or replace the pad.
+
+## 2026-07-31: the epilogue teaches a helper how to collect a helper of its OWN
+
+A three-level dispatch tree read, on the board, as one job done three times — root "Improve server
+logging…", child "Researching dev server readouts", grandchild "Survey dev server readouts". The
+topology was actually sound: the root's task had five research prongs, the child kept four (Vite,
+Next and wrangler source, repaint techniques, log-dir conventions, fray's own state-dir convention)
+and delegated only the pure-web prong. The grandchild's prompt was a strict subset, not a copy.
+
+What was broken was COLLECTION. The child backgrounded its helper, then hand-rolled a wait loop over
+`/private/tmp/claude-<uid>/<proj>/<session>/tasks/<agentId>.output`. That path is a **symlink** into
+`~/.claude/projects/<proj>/<session>/subagents/agent-<id>.jsonl`, so `stat -f %z` without `-L`
+returned the LINK's size — 153, the length of its target path — and `stat -f %m` returned the link's
+frozen creation mtime. Its other predicate, `grep -c '"type":"result"'`, is a known false negative
+because that record is not reliably written. Both halves false-negatived at once: a helper that was
+195 records and 413,723 bytes deep read as `size=153 age=325s results=0`. The child concluded "the
+helper's transcript is stale at only 153 bytes", discarded a live agent, and redid its work — which
+is precisely why all three levels appeared to be doing the same thing.
+
+The audience was the root cause. `workerPrompt.ts` does carry the rule ("keep fan-out shallow: a
+rested sub-agent is not reliably re-woken by grandchildren"), but that contract reaches only the ROOT
+worker — the one agent that does not spawn grandchildren — and the contract itself states children
+inherit none of it. Into that silence an inherited user-level `CLAUDE.md` ("the parent stays awake and
+polls the child's transcript inside its own turn") supplied the polling recipe, overriding the Agent
+tool's own result text ("you will be notified automatically when it completes").
+
+`hooks/agent-dispatch.mjs` is the fix's home because it fires at EVERY depth — verified against the
+real transcripts: both the depth-1 and depth-2 children received the epilogue. It is the only seam
+that reaches a nested dispatcher without depending on its parent remembering to restate the norm. The
+new paragraph states that a helper's completion arrives automatically, forbids hand-rolled wait loops
+over a transcript or `.output` path, names the symlink and `"type":"result"` failure modes concretely
+enough that a model cannot rationalize its way back into polling, and asks a dispatcher to give its
+helper a `description` naming the narrower slice so the tree stays readable.
+
+This stays within the universal-coordination boundary set on 2026-07-30: it is agent-lifecycle
+coordination, like the handoff contract and the `SendMessage` upward channel already in the epilogue,
+and imposes no build, test, git, or repo-specific policy. Rejected: denying depth-2 dispatch in the
+hook (too blunt — the decomposition was good, and this hook exists because a worker MAY spin up
+helpers), and rewriting the deliberate "keep fan-out shallow" line in `workerPrompt.ts`.
+
+`packages/server/src/agent-dispatch-hook.test.ts` is new — this hook had no test at all despite being
+load-bearing. It spawns the real hook over the real stdin contract and pins the foreground denial,
+`name`/`team_name` stripping, endsWith-idempotence (including the prompt that merely QUOTES the
+marker), the nested-dispatch paragraph, the retained coordination text, the non-worker inert path,
+and fail-open on bad input.
+
+## 2026-07-31: the fence check at rest — a Stop hook for a decision handed back in prose
+
+`hooks/fence-stop.mjs` is new, wired on `Stop` for both backends (plugin `hooks.json`, and
+`codexScratchpadHookConfig` in `packages/server/src/dispatch.ts`). It blocks ONCE when a worker comes
+to rest with no ` ```question `/` ```done `/` ```awaiting ` fence and its closing text hands a decision
+back to the human, and asks it to classify: fence it as a real question, decide it, or rest again.
+
+MEASURED, then built. A scan of 532 real worker transcripts (session ids cross-referenced against every
+`~/.fray/projects/*/ui.db`), 4,709 rest turns, shows fence use decaying monotonically with session
+depth — ` ```question ` 23% at the first rest against 9% past the twentieth, ` ```done ` 31% against
+2%, fenceless 45% against 83%. The cause is DEPTH, not compaction: turns before a compaction boundary
+are already 82% fenceless, so the decay is complete before any summary is written, and compaction only
+correlates because only long sessions reach it. The contract is in the system prompt and survives
+compaction, so restating it earlier cannot help; something has to read the actual final message.
+
+ASK-ONLY, on the numbers. 9.8% of fenceless rests close by deferring a decision ("your call", "want me
+to …?"), and a prose ask is the expensive miss — it renders as an ordinary handoff card with nothing to
+click and does not break through a Snooze. Only 3% carry a landed claim, and a "that looked done" nudge
+is actively dangerous, since ` ```done ` is a DISMISSAL and "uncertain is not done" is the contract's
+own rule. A done detector was built, measured, and dropped. A trailing-question-mark rule was also
+dropped: over 3,239 fenceless rests it added exactly one hit the deferral phrases had not caught.
+
+NOT the 2026-07-02 blocking-Stop mistake. That gate demanded a FILE EDIT and forced trivial workers
+into Read/Edit dances. This one demands nothing — its third branch is "it was rhetorical, just rest
+again" — and it fires at most once per human turn.
+
+THE PAYLOAD, NOT THE TRANSCRIPT. First cut read the final message off `transcript_path` and fired on
+only two of four live broker workers: the transcript is written asynchronously, so at Stop time the
+message that just ended the turn may not be on disk. The Stop payload carries `last_assistant_message`
+and `prompt_id` (verified on the wire, cli 2.1.220); using those is exact and race-free, and `prompt_id`
+is the natural one-shot key because it is stable across a blocked continuation. Transcript parsing
+remains only as the fallback for a payload that lacks them (codex, or an older shape). After the switch,
+3/3 live workers fired.
+
+VERIFIED END TO END, not just unit-tested: real broker workers on an isolated stack, driven to a
+fenceless prose ask, were blocked and re-emitted answerable cards — two as a ` ```question ` fence, one
+by calling the native `AskUserQuestion` tool (equally answerable on the broker path, where
+`FRAY_NATIVE_ASK=1` renders it as a card). This supersedes the never-built `.fray/fenceless-rest-nudge.md`
+design, whose premise — poke EVERY fenceless rest — is wrong under the current contract, whose bare rest
+is the legitimate ordinary handoff.

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

@@ -6,9 +6,22 @@
 //      foreground agent blocks the worker's turn; a human interjection orphans it).
 //   2) STRIP `name`/`team_name` — setting either strands a nested dispatch (its result routes
 //      wrong and never returns cleanly), so scrub both silently.
-//   3) AUTO-APPEND a repo-neutral ORCHESTRATION EPILOGUE so helpers return a useful handoff
-//      and know how to reach their dispatcher mid-flight without imposing build, test, git,
-//      compilation, or process-lifecycle policy on arbitrary repos.
+//   3) AUTO-APPEND a repo-neutral ORCHESTRATION EPILOGUE so helpers return a useful handoff,
+//      know how to reach their dispatcher mid-flight, and collect a helper of their OWN correctly
+//      — without imposing build, test, git, compilation, or process-lifecycle policy on
+//      arbitrary repos.
+//
+// WHY THE NESTED-DISPATCH PARAGRAPH EXISTS (2026-07-31): this hook fires at EVERY depth, but the
+// fray worker contract reaches only the ROOT worker — so its "keep fan-out shallow / a rested agent
+// is not reliably re-woken by grandchildren" rule was delivered exclusively to the one agent that
+// does not spawn grandchildren, and withheld from the depth-1 child that does. Into that silence a
+// user-level CLAUDE.md ("the parent stays awake and polls the child's transcript") supplied a
+// hand-rolled polling recipe, and it failed: the `.output` path is a SYMLINK, so `stat` without -L
+// returns the LINK's size (= the length of its target path) and its frozen creation mtime, while
+// the `"type":"result"` record is never reliably written. Both halves of the predicate
+// false-negatived at once, a live 413KB helper read as "size=153 age=325s results=0", and the
+// dispatcher discarded it and redid the work itself. This paragraph is the only place that reaches
+// a nested dispatcher without depending on its parent remembering to restate the norm.
 //
 // GATE: inert unless FRAY_UI_THREAD is set (not a fray-ui worker → allow every dispatch unmodified).
 //
@@ -25,7 +38,8 @@ const EPILOGUE = `
 ---
 [ORCHESTRATION EPILOGUE — auto-appended by the fray worker dispatch hook] You are a helper sub-agent for a fray-ui worker. Your final message is the handoff: report your outcome/status; what you did; changed files, artifacts, and commit SHA when applicable; verification or evidence and its result; caveats or unresolved work; and the next action when one remains. A bare "done" or progress-only message is not a complete handoff.
 The worker's scratchpad is shared: merge your own scoped progress into it as you work rather than leaving the root as its sole writer. Re-read before every edit and preserve every other agent's content. This exact scratchpad is Fray coordination state, not a project deliverable or source edit: a scoped merge is an explicit exception to delegated phrases such as "write only <path>" or "do not modify the repo"; never classify it as unauthorized or roll it back. Never delete, truncate, reinitialize, move, or replace the whole file. Other project files, including repository-root files, remain governed by your delegated authority; their location alone neither permits nor forbids editing. Do not edit other \`.fray/\` state unless your prompt explicitly asks you to.
-You have an upward channel while you work: \`SendMessage({to: "main", summary: "<5-10 words>", message: "…"})\` delivers to your dispatcher. Use it when the dispatcher acting before you finish could change the outcome—for example, when you hit an unresolved blocker, complete a milestone another task needs, or discover that your instructions should change. Do not use it for routine progress updates.`;
+You have an upward channel while you work: \`SendMessage({to: "main", summary: "<5-10 words>", message: "…"})\` delivers to your dispatcher. Use it when the dispatcher acting before you finish could change the outcome—for example, when you hit an unresolved blocker, complete a milestone another task needs, or discover that your instructions should change. Do not use it for routine progress updates.
+If you dispatch a helper of your own, its completion is delivered to you automatically. Never hand-roll a wait loop over a helper's transcript or \`.output\` path to decide whether it finished: that path is a SYMLINK, so \`stat\` without \`-L\` reports the link's own size (the length of its target path, ~150 bytes) and its frozen creation mtime, and the \`"type":"result"\` record is not reliably written — so a helper that is working hard reads as tiny, stale, and dead, and you will discard live work and redo it. Judge a helper only by its completion notification or the text it returns. Give it a \`description\` naming its narrower slice rather than restating your own, so the dispatch tree stays readable.`;
 
 /** @param {unknown} obj @returns {never} */
 function emit(obj) {

package/runtime/cc-worker/hooks/fence-stop.mjs

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+// @ts-check
+// Stop hook (fray-worker) — catches a rest that hands a DECISION to the human in prose instead of in
+// a ```question fence. Run directly with node (zero deps, max Node compat), mirroring the other hooks.
+//
+// WHY THIS EXISTS — measured, not felt. Scanning 532 real worker transcripts (session ids
+// cross-referenced against every `~/.fray/projects/*/ui.db`), 4,709 rest turns, fence use decays
+// monotonically with how deep the session is:
+//
+//   rest turn      #1    #2-3   #4-6   #7-10  #11-20  #21+
+//   ```question    23%    22%    20%     20%     16%    9%
+//   ```done        31%    23%    17%     13%     10%    2%
+//   no fence       45%    53%    58%     60%     68%   83%
+//
+// It is DEPTH, not compaction: turns BEFORE a compaction boundary are already 82% fenceless, so the
+// decay is fully present before any summary is written (compaction only correlates because only long
+// sessions compact). The contract lives in the system prompt and does survive compaction — what decays
+// is attention to it. So re-stating the rule earlier in the context cannot fix this; something has to
+// look at the ACTUAL final message at the moment of rest. That is this hook.
+//
+// SCOPE — asks only, never completion. 9.8% of fenceless rests close by deferring a decision to the
+// human ("your call", "want me to …?"); those are the expensive miss, because a prose ask renders as an
+// ordinary handoff card with nothing to click and does not break through a Snooze, so the human has to
+// read the whole message to discover they are blocking. Only 3% of fenceless rests carry a landed
+// claim, and telling a worker "that looked done" is actively dangerous — ```done is a DISMISSAL that
+// files the thread away, and "uncertain is not done" is the contract's own rule. Measured cost/benefit
+// said ask-only; do not add a done detector without re-measuring.
+//
+// NOT COERCIVE, AND ONE-SHOT. A blocking Stop gate was tried and removed once before (2026-07-02: the
+// block-until-file-edited nag forced trivial workers into Read/Edit dances that render as chat noise),
+// so this one never demands work: its third branch is explicitly "this was rhetorical — just rest
+// again". It fires at most ONCE per human turn (keyed on the turn ordinal, not on the message, so the
+// re-emitted message cannot re-trigger it) and additionally stands down when `stop_hook_active` says a
+// Stop hook is already driving the continuation.
+import { readFileSync, writeFileSync, renameSync, rmSync, statSync, openSync, readSync, closeSync } from 'node:fs';
+import { join } from 'node:path';
+import { currentSessionId } from '../scripts/fray/config.mjs';
+
+/** How much of the message's CLOSING is searched for the ask. The deferral lives in the sign-off, and
+ *  a whole-message search fires on a "say the word" from three paragraphs up in a report that then
+ *  ends on a completion note. Tuned on the corpus: 900 chars keeps 316 of the 349 whole-message hits. */
+const TAIL_CHARS = 900;
+
+/** Below this, a message is a greeting or a one-liner, not a handback ("Hi! What would you like to
+ *  work on?" was the only false positive the corpus sample turned up). */
+const MIN_CHARS = 200;
+
+/** Bytes of transcript tail read to find the final assistant message. Transcripts reach tens of
+ *  megabytes; the last few records are all this needs. */
+const TAIL_BYTES = 512 * 1024;
+
+// ---- fence grammar ----------------------------------------------------------------------------
+// Mirrors the server's scanners (packages/server/src/tailer.ts `QUESTION_BLOCK_RE` /
+// `SIGNAL_FENCE_RE`) by hand — a hook cannot import from the app. Kept deliberately SIMPLE: a false
+// "already fenced" reading only costs a missed nudge, which is the safe direction.
+const QUESTION_BLOCK_RE = /^```question(?:[ \t]+[A-Za-z][^\r\n]*?)?[ \t]*\n[\s\S]*?\n```[ \t]*$/m;
+const SIGNAL_FENCE_RE = /^```(done|awaiting)[ \t]*\n[\s\S]*?\n```[ \t]*$/gm;
+
+/** The signal/question fence a final message already carries, or null. @param {string} text */
+export function fenceOf(text) {
+  const norm = String(text ?? '').replace(/\r\n/g, '\n');
+  if (QUESTION_BLOCK_RE.test(norm)) return 'question';
+  SIGNAL_FENCE_RE.lastIndex = 0;
+  let kind = null;
+  let end = 0;
+  for (let m = SIGNAL_FENCE_RE.exec(norm); m !== null; m = SIGNAL_FENCE_RE.exec(norm)) {
+    kind = m[1]; // last-fence-wins, matching the server
+    end = m.index + m[0].length;
+  }
+  // The fence only signals when it CLOSES the message — prose after it means it was quoted.
+  return kind && norm.slice(end).trim() === '' ? kind : null;
+}
+
+// ---- the ask detector -------------------------------------------------------------------------
+// Phrases that hand a decision back. Derived from the corpus, not invented: `say the word` (100),
+// `your call` (100), `want me to` (84), `if you'd rather` (33) are the bulk of real misses. A
+// trailing-question-mark rule was tried and DROPPED — over 3,239 fenceless rests it added exactly one
+// hit these phrases had not already caught, for a whole extra false-positive surface.
+const DEFERRALS = [
+  /\byour call\b/i,
+  /\bup to you\b/i,
+  /\bwant me to\b/i,
+  /\bwould you (?:like|prefer|rather)\b/i,
+  /\bdo you want\b/i,
+  /\bshall I\b/i,
+  /\bsay the word\b/i,
+  /\bif you(?:'d| would)\s+(?:prefer|rather|like)\b/i,
+  /\btell me which\b/i,
+  /\bwhich (?:would you|do you|one would|of these)\b/i,
+  /\byour (?:preference|decision)\b/i,
+  /\blet me know\b/i,
+  /\bshould I\b[^.?!\n]*\?/i,
+];
+
+/** The deferral phrase in a message's closing, or null. @param {string} text */
+export function askPhrase(text) {
+  const norm = String(text ?? '').replace(/\r\n/g, '\n').trim();
+  if (norm.length < MIN_CHARS) return null;
+  const close = norm.length > TAIL_CHARS ? norm.slice(-TAIL_CHARS) : norm;
+  for (const re of DEFERRALS) {
+    const m = close.match(re);
+    if (m) return m[0];
+  }
+  return null;
+}
+
+/** @param {string} phrase */
+function nudge(phrase) {
+  return (
+    '⟦fence check⟧ You are coming to rest with no ```question / ```done / ```awaiting fence, and your ' +
+    'closing text hands a decision back to the human ("' + phrase + '"). A prose ask is INVISIBLE in ' +
+    'the queue: it renders as an ordinary handoff card with nothing to answer, it does not break ' +
+    'through a Snooze, and the human has to read the whole message to discover they are blocking you. ' +
+    'Decide which of these it actually is, then do exactly one:\n' +
+    '1. It is genuinely the human\'s to call (irreversible, external-facing, or their taste to set) — ' +
+    're-send your final message with the ask at the very END in a ```question block: the question on ' +
+    'ONE line, lettered `- A. …` options with a one-line tradeoff each, your recommendation FIRST and ' +
+    'marked `(recommended)`, and enough context to answer cold. One block per independent question.\n' +
+    '2. It was yours to decide all along (reversible, derivable from the code or ordinary engineering ' +
+    'judgment) — make the call, say which way you went, and carry on with the work.\n' +
+    '3. It was a rhetorical aside or an offer of optional extra work, not a real blocker — just rest ' +
+    'again as you were.\n' +
+    'This note fires at most once per turn and will not repeat.'
+  );
+}
+
+// ---- transcript ---------------------------------------------------------------------------------
+/** The tail of a JSONL transcript, parsed, oldest-first. Partial first line is dropped.
+ *  @param {string} path */
+function tailRecords(path) {
+  let fd = null;
+  try {
+    const size = statSync(path).size;
+    const want = Math.min(size, TAIL_BYTES);
+    const buf = Buffer.alloc(want);
+    fd = openSync(path, 'r');
+    readSync(fd, buf, 0, want, size - want);
+    const lines = buf.toString('utf8').split('\n');
+    if (want < size) lines.shift(); // the read may have cut the first line in half
+    const out = [];
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        out.push(JSON.parse(line));
+      } catch {
+        /* a truncated/garbled record is simply skipped */
+      }
+    }
+    return out;
+  } catch {
+    return [];
+  } finally {
+    if (fd !== null) {
+      try {
+        closeSync(fd);
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+}
+
+/** @param {any} rec */
+function assistantText(rec) {
+  // Claude: an assistant record's text blocks. Codex: a rollout `event_msg`/`agent_message`.
+  if (rec?.type === 'event_msg' && rec?.payload?.type === 'agent_message') return String(rec.payload.message ?? '');
+  const c = rec?.message?.content;
+  if (typeof c === 'string') return c;
+  if (!Array.isArray(c)) return '';
+  return c.filter((b) => b?.type === 'text').map((b) => String(b.text ?? '')).join('\n');
+}
+
+/** @param {any} rec */
+function isToolResult(rec) {
+  const c = rec?.message?.content;
+  return Array.isArray(c) && c.some((b) => b?.type === 'tool_result');
+}
+
+/**
+ * The final assistant text of the top-level conversation, plus the ordinal of the human turn it
+ * closes. FALLBACK ONLY — see `evaluateFenceStop`: the transcript is written asynchronously, so at
+ * Stop time the message that just ended the turn may not be on disk yet. Measured live: of four real
+ * broker workers driven to a fenceless prose ask, two had the final message flushed by the time the
+ * hook ran and two did not, which is exactly the flakiness this is no longer the primary source for.
+ * @param {any[]} records
+ */
+export function finalMessage(records) {
+  const conv = records.filter(
+    (r) => (r?.type === 'user' || r?.type === 'assistant' || r?.type === 'event_msg') && !r?.isSidechain
+  );
+  let text = null;
+  for (let i = conv.length - 1; i >= 0; i--) {
+    if (conv[i].type === 'user') break; // a trailing user record means the turn is not at rest
+    const t = assistantText(conv[i]);
+    if (t.trim()) {
+      text = t;
+      break;
+    }
+  }
+  // Human turns in the window read. Tool results are the model's own loop, not a human turn; a
+  // truncated window just yields a smaller (but still monotonic within a session) ordinal.
+  const turn = conv.filter((r) => r.type === 'user' && !isToolResult(r)).length;
+  return { text, turn };
+}
+
+// ---- one-shot state ------------------------------------------------------------------------------
+/** @param {string} statePath */
+function readState(statePath) {
+  try {
+    const s = JSON.parse(readFileSync(statePath, 'utf8'));
+    return s && typeof s === 'object' ? s : {};
+  } catch {
+    return {}; // missing/corrupt state is an unfired guard
+  }
+}
+
+/** Persist BEFORE blocking: if the guard cannot be recorded, fail open rather than build a loop whose
+ *  key can never advance. @param {string} statePath @param {string} key @param {number} now */
+function writeState(statePath, key, now) {
+  const tmp = `${statePath}.${process.pid}.tmp`;
+  try {
+    writeFileSync(tmp, JSON.stringify({ key, firedAt: new Date(now).toISOString() }) + '\n', { mode: 0o600 });
+    renameSync(tmp, statePath);
+    return true;
+  } catch {
+    try {
+      rmSync(tmp, { force: true });
+    } catch {
+      /* best effort */
+    }
+    return false;
+  }
+}
+
+/**
+ * @param {{ transcript_path?: string, stop_hook_active?: boolean, last_assistant_message?: unknown, prompt_id?: unknown }} input
+ * @param {{ projectDir: string, sessionId: string, now?: number }} context
+ * @returns {{ decision?: 'block', reason?: string }}
+ */
+export function evaluateFenceStop(input, context) {
+  if (!input || typeof input !== 'object' || !context.sessionId) return {};
+  // Another Stop hook is already driving the continuation — adding a second instruction on top of it
+  // is how stop loops get built.
+  if (input.stop_hook_active) return {};
+
+  // THE MESSAGE. `last_assistant_message` is the harness's own copy of the text that just ended the
+  // turn (verified on the wire, cli 2.1.220), so it is exact and race-free. The transcript is the
+  // fallback for a payload that lacks it — codex, or a future/older shape.
+  const promptId = typeof input.prompt_id === 'string' ? input.prompt_id : '';
+  const direct = typeof input.last_assistant_message === 'string' ? input.last_assistant_message : '';
+  // Only touch the transcript when something is actually missing from the payload.
+  const fromDisk = direct.trim() && promptId ? null : finalMessage(tailRecords(input.transcript_path ?? ''));
+  const text = direct.trim() ? direct : fromDisk?.text;
+  if (!text) return {};
+  if (fenceOf(text)) return {};
+  const phrase = askPhrase(text);
+  if (!phrase) return {};
+
+  // THE ONE-SHOT KEY — one poke per human turn, so the message the worker re-sends cannot re-trigger
+  // it. `prompt_id` identifies the prompt being answered and is stable across a blocked continuation,
+  // which is exactly the boundary wanted; the transcript's human-turn ordinal is the fallback. Both
+  // are STABLE within a rest, which is what makes a loop impossible — no timed cooldown is needed on
+  // top (and one would silently swallow the poke on a rapid second turn).
+  const key = promptId || `turn:${fromDisk?.turn ?? 0}`;
+
+  const statePath = join(context.projectDir, '.fray', 'threads', context.sessionId, '.fence-stop-state.json');
+  if (readState(statePath).key === key) return {};
+  if (!writeState(statePath, key, context.now ?? Date.now())) return {};
+
+  return { decision: 'block', reason: nudge(phrase) };
+}
+
+if (process.argv[1]?.endsWith('fence-stop.mjs')) {
+  try {
+    const argv = process.argv.slice(2);
+    const explicit = argv.find((a) => a.startsWith('--session='));
+    const input = JSON.parse(readFileSync(0, 'utf8'));
+    // WORKER GATE — inert outside a fray-ui worker. Codex reports its own rollout id, so fray bakes
+    // `--session=<fray sessionId>` into the codex hook command and that always wins.
+    const sessionId = explicit ? explicit.slice('--session='.length) : currentSessionId(input?.session_id);
+    if (!sessionId || !(explicit || (process.env.FRAY_UI_THREAD ?? '').trim())) {
+      process.stdout.write('{}');
+    } else {
+      const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+      process.stdout.write(JSON.stringify(evaluateFenceStop(input, { projectDir, sessionId })));
+    }
+  } catch {
+    process.stdout.write('{}');
+  }
+}

package/runtime/cc-worker/hooks/hooks.json

@@ -43,7 +43,8 @@
     "Stop": [
       {
         "hooks": [
-          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scratchpad-stop.mjs\"" }
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scratchpad-stop.mjs\"" },
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/fence-stop.mjs\"" }
         ]
       }
     ],

package/runtime/cc-worker/hooks/scratchpad.mjs

@@ -403,15 +403,16 @@ if (mode === 'nudge') {
   emitJson(
     mtimeMs
       ? '⟦scratchpad stale⟧ Your context has grown ~' + k + 'k tokens since you last wrote `' +
-          relPath + '`. Bring it up to date now, before a compaction forces the issue — the problem, ' +
-          'the approach and what you rejected, the human\'s decisions, what is verified versus ' +
-          'believed, and the next action. Its head is injected back automatically after a compaction, ' +
-          'so it is the one thing you are guaranteed to still have.'
-      : '⟦scratchpad empty⟧ This session is ~' + k + 'k tokens deep and `' + relPath + '` still has ' +
-          'nothing substantive in it. Write it now: the problem, the approach and the approaches you ' +
-          'rejected, the human\'s decisions, what is verified versus merely believed, and the next ' +
-          'action. Its head is injected back automatically after a compaction, so it is what survives ' +
-          'when the rest of this context does not.',
+          relPath + '`. If this effort is long enough that losing your reasoning would hurt, top it up ' +
+          'in passing — the approach, what you rejected, the human\'s decisions, what is verified ' +
+          'versus believed. Its head is injected back after a compaction. This is a background note, ' +
+          'NOT a task and NOT a reason to pause: do not stop working to service it, and never end a ' +
+          'turn on it while the human\'s instruction still has parts left.'
+      : '⟦scratchpad empty⟧ This session is ~' + k + 'k tokens deep and `' + relPath + '` is empty. ' +
+          'That is fine for a single direct task — the pad is optional and writing in it is not doing ' +
+          'the work. If this effort is long or branching, a few lines on the approach and the human\'s ' +
+          'decisions will survive a compaction. This is a background note, NOT a task and NOT a reason ' +
+          'to pause: keep going with what you were asked to do.',
     event,
   );
 }

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

@@ -64,7 +64,8 @@ const scratch = sid
 // the compaction re-read nudge, gh guidance, and the defensive cc-orchestrator off-sentinel.
 const core =
   '⟦fray worker contract⟧ You are a fray-ui WORKER driving EXACTLY ONE effort. Your FULL operating contract — the end-of-turn signal fences, scratchpad rules, sub-agent rules, and the runtime release gate — lives in your SYSTEM PROMPT; follow it there (this is a runtime re-grounding, not a second copy). The human + the fray-ui 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' +
-  'SCRATCHPAD: `' + scratch + '` — the CANONICAL record of this thread, your compaction-survival mechanism, and your sub-agents\' shared blackboard. Write your task list, the approach and what you rejected, and anything that must outlive your context there AS YOU GO; re-read it after any compaction or resume, and pass its PATH into every sub-agent prompt.\n' +
+  'SCRATCHPAD (OPTIONAL): `' + scratch + '` — a scratch file kept FOR YOU, not a deliverable, and never a substitute for doing the work. A single direct task usually needs nothing in it. On a long effort it is crash insurance and your sub-agents\' shared blackboard: write the approach and what you rejected there AS YOU GO, mid-work, then KEEP WORKING; re-read it after any compaction or resume, and pass its PATH into every sub-agent prompt.\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 recording it in the scratchpad is not doing it.\n' +
   'SIGNAL AT REST through your FINAL MESSAGE, per the fence rules in your system prompt: bare rest is the ordinary handoff and queues for the human; ```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 — bare rest 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. Load `fray:handoff` for the full fence reference.\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.';
 

package/runtime/cc-worker/skills/gh/SKILL.md

@@ -58,6 +58,28 @@ gh pr view N -R OWNER/REPO --comments     # review threads + conversation
 ```
 Read the changed files **in context**, not just the hunks — `gh pr diff` shows what changed, but correctness lives in the surrounding code.
 
+**Reading ONE review (what a `pr-watch` wake hands you)**
+
+A wake permalink ending `#pullrequestreview-<id>` is a **review**, and a review's `body` is routinely
+**empty** — review apps (pullfrog, coderabbit) and humans doing an inline pass put every word in the
+review's *inline comments*. Reading the body and concluding the review is empty is the wrong turn here.
+One endpoint answers it in one call:
+
+```bash
+gh api --paginate repos/OWNER/REPO/pulls/N/reviews/REVIEW_ID/comments \
+  --jq '.[] | "\(.path):\(.line // .original_line // "file")\n\(.body)\n"'
+```
+
+Do **not** sweep `…/pulls/N/comments` and filter by `pull_request_review_id` — it pulls the whole PR's
+history to find a handful of lines. Add the review's own body only if you need it
+(`gh api repos/OWNER/REPO/pulls/N/reviews/REVIEW_ID --jq .body`). A `#issuecomment-<id>` permalink is
+the other shape and *does* carry its substance in its body:
+`gh api repos/OWNER/REPO/issues/comments/ID --jq .body`.
+
+**`--paginate` is the default for any list endpoint.** `gh api` returns **30** items per page and caps
+`per_page` at **100**, silently — a truncated page reads exactly like "that's all there is," so a
+missing `--paginate` becomes a wrong answer rather than an error.
+
 **CI / runs / releases**
 ```bash
 gh run list -R OWNER/REPO --branch BRANCH --limit 10

package/runtime/cc-worker/skills/handoff/SKILL.md

@@ -8,6 +8,12 @@ description: The full fray end-of-turn signal reference for a fray-ui worker (in
 Your system prompt states the fence rules. This is the elaboration: the exact shapes, the tags, and
 worked examples. Nothing here overrides the contract.
 
+**Before you use any of it: is the turn actually over?** Every shape below is for a turn that has
+genuinely ended. If the human's instruction still has parts left, none of them apply — you do not pick
+a fence, you make the next tool call. Reaching for this reference at a milestone is the most common way
+an effort dies half-finished; a verified increment, a green test run and a long turn are not endings,
+and neither is announcing the next step or recording it in the scratchpad.
+
 ## Which fence?
 
 | Situation | Fence |