frayui 0.1.0

package/runtime/cc/scripts/fray/notify-shared.mjs

@@ -0,0 +1,90 @@
+// @ts-check
+// Shared storage + rendering for the fray durable notification queue. Imported by both the
+// CLI (`notify.mjs`) and the Stop hook (`fray-notify-surface.mjs`) so the on-disk shape and
+// the human-facing markdown render are defined in ONE place and can't drift.
+//
+// Queue item shape (one JSON object per line in `.fray/notify-queue.jsonl`):
+//   { id, ts, kind, title, body, status: "open"|"dismissed", surfaced: bool }
+// `title` is a short heading; `body` is the prose context the human reads to decide.
+// Legacy items carry a single `text` field instead of title/body — the renderer degrades
+// gracefully (derives a heading from the first clause, keeps the rest as the body).
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+export const KINDS = new Set(['WIN', 'DECISION', 'BLOCKER', 'FYI']);
+
+// Section order is deliberate: what the human must ACT on first (blockers, decisions),
+// then what's purely informational (wins, fyi).
+const SECTIONS = [
+  ['BLOCKER', 'Blockers'],
+  ['DECISION', 'Decisions'],
+  ['WIN', 'Wins'],
+  ['FYI', 'FYI'],
+];
+
+/** @param {string} file @returns {any[]} */
+export function readQueue(file) {
+  if (!existsSync(file)) return [];
+  return readFileSync(file, 'utf8')
+    .split('\n')
+    .filter((l) => l.trim())
+    .map((l) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+/** @param {string} file @param {any[]} items */
+export function writeQueue(file, items) {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, items.map((i) => JSON.stringify(i)).join('\n') + (items.length ? '\n' : ''));
+}
+
+function titleOf(i) {
+  if (i.title) return String(i.title).trim();
+  const t = String(i.text || '').trim();
+  const head = t.split(/ — | – |: |\. /)[0] || t; // legacy: first clause as the heading
+  return head.slice(0, 90).trim();
+}
+
+function bodyOf(i) {
+  if (i.body != null) return String(i.body).trim();
+  if (i.title) return '';
+  const t = String(i.text || '').trim();
+  const ti = titleOf(i);
+  return t.startsWith(ti) ? t.slice(ti.length).replace(/^[\s—–:.-]+/, '').trim() : t;
+}
+
+/**
+ * Render the OPEN items as scannable, sectioned markdown for the human — grouped by kind,
+ * each item a `###` heading + its prose body + a subtle id tag. This is the surface the
+ * human reads to decide; it is NOT a terse log line. (Authors should write each item's
+ * title/body per the prose skill — terse, factual, enough context to decide.)
+ * @param {any[]} open @returns {string}
+ */
+export function renderMarkdown(open) {
+  const n = open.length;
+  const intro =
+    `📌 ${n} item${n === 1 ? '' : 's'} waiting on you — surfaced here so they don't scroll away. ` +
+    `Nothing to run in a terminal: just tell me your call in chat and I'll clear each one.`;
+
+  const parts = [intro];
+  for (const [kind, heading] of SECTIONS) {
+    const rows = open.filter((i) => i.kind === kind);
+    if (!rows.length) continue;
+    parts.push(`\n## ${heading}`);
+    for (const i of rows) {
+      const title = titleOf(i);
+      const body = bodyOf(i);
+      let block = `\n### ${title} · ${i.id}`;
+      if (body) block += `\n\n${body}`;
+      parts.push(block);
+    }
+  }
+  return parts.join('\n');
+}

package/runtime/cc/scripts/fray/notify.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// @ts-check
+// fray notify — a DURABLE, human-facing notification queue for the orchestrator.
+//
+// The problem it fixes: in a long autonomous session, the things the human most needs to
+// see — a headline WIN that landed, a DECISION that's genuinely theirs, a BLOCKER — get
+// buried under per-turn status churn and scroll out of reach. This queue is written the
+// instant something noteworthy happens, persists until DISMISSED, and is re-surfaced when
+// the orchestrator goes idle by the companion Stop hook (`hooks/fray-notify-surface.mjs`).
+//
+// The hook SURFACES each item to the human directly (rich, sectioned markdown via
+// `systemMessage`). The orchestrator does NOT relay or regurgitate the queue in chat — the
+// human already sees it. The orchestrator's only job is to DISMISS an item once the human
+// has addressed it in conversation (the human has no terminal): `fray-notify dismiss <id>`.
+//
+// Each item carries a short `title` (the heading the human scans) and a prose `body` (the
+// context they read to decide) — author BOTH per the prose skill: terse, factual, enough to
+// make the call without opening a file. Storage: the PROJECT's `.fray/notify-queue.jsonl`
+// (resolved from CLAUDE_PROJECT_DIR, or cwd when run by hand), one JSON object per line:
+//   {id, ts, kind, title, body, status: "open"|"dismissed", surfaced: bool}
+// kind ∈ WIN | DECISION | BLOCKER | FYI. `surfaced` is stamped by the Stop hook once it has
+// shown the item, so a new item interrupts idle exactly once, then persists quietly.
+//
+// Usage (bare command on PATH via bin/fray-notify while the plugin is enabled):
+//   fray-notify add <WIN|DECISION|BLOCKER|FYI> "<title>" "<body>"   # body optional; prints the id
+//   fray-notify list [--all]                                        # rendered markdown (open, or all)
+//   fray-notify dismiss <id>[ <id> ...] | --all
+// Robust: a malformed queue line is skipped, never fatal.
+import { join } from 'node:path';
+import { KINDS, readQueue, writeQueue, renderMarkdown } from './notify-shared.mjs';
+
+const PROJECT_DIR = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const QUEUE = join(PROJECT_DIR, '.fray', 'notify-queue.jsonl');
+
+function newId(items) {
+  const n = items.reduce((m, i) => Math.max(m, Number(String(i.id).replace(/\D/g, '')) || 0), 0);
+  return 'n' + (n + 1);
+}
+
+function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const items = readQueue(QUEUE);
+
+  if (cmd === 'add') {
+    const kind = (rest[0] || '').toUpperCase();
+    const title = (rest[1] || '').trim();
+    const body = rest.slice(2).join(' ').trim();
+    if (!KINDS.has(kind) || !title) {
+      console.error('usage: fray-notify add <WIN|DECISION|BLOCKER|FYI> "<title>" "<body>"');
+      process.exit(1);
+    }
+    const id = newId(items);
+    items.push({ id, ts: new Date().toISOString(), kind, title, body, status: 'open', surfaced: false });
+    writeQueue(QUEUE, items);
+    console.log(id);
+  } else if (cmd === 'list') {
+    const all = rest.includes('--all');
+    const rows = items.filter((i) => all || i.status === 'open');
+    console.log(rows.length ? renderMarkdown(rows) : '(no notifications)');
+  } else if (cmd === 'dismiss') {
+    const all = rest.includes('--all');
+    const ids = new Set(rest);
+    let n = 0;
+    for (const i of items) {
+      if (i.status === 'open' && (all || ids.has(i.id))) {
+        i.status = 'dismissed';
+        n++;
+      }
+    }
+    writeQueue(QUEUE, items);
+    console.log(`dismissed ${n}`);
+  } else {
+    console.error('usage: fray-notify <add|list|dismiss> …');
+    process.exit(1);
+  }
+}
+
+// Run the CLI. This module is the command entry point (invoked directly as `node notify.mjs`
+// or via the bin shim's dynamic import); helpers live in notify-shared.mjs, so nothing imports
+// this file for its functions — running unconditionally is correct.
+main();

package/runtime/cc/scripts/fray/ownership.mjs

@@ -0,0 +1,120 @@
+// @ts-check
+/**
+ * fray — per-thread SESSION OWNERSHIP. A thread carries an optional `owner_session: <id>`
+ * frontmatter field naming the Claude Code session RESPONSIBLE for it, so multiple fray
+ * sessions can share one repo, each driving its own set of threads without stepping on the
+ * others. This module is the read/write + state-derivation layer; the `fray claim/disown/
+ * owners` subcommands (index.mjs) and the board annotation sit on top.
+ *
+ * TWO HARD DESIGN CHOICES (both deliberate — see the fray thread / report):
+ *
+ *   1. LIVENESS IS DERIVED, ownership is only WRITTEN by an explicit gesture. Whether an owner
+ *      is alive comes from its heartbeat freshness (config.mjs `sessionLive`), NOT a stored
+ *      flag. The `owner_session` STRING is physically written ONLY by `fray claim`/`disown`
+ *      (a human/orchestrator action) and cleared by `fray owners --gc` — NEVER by an automatic
+ *      per-turn hook. That is the safety guarantee: no hook ever rewrites a thread `.md` body,
+ *      so there is no clobber race against a sub-agent editing the same thread. A dead owner's
+ *      lingering `owner_session` string is INERT — derivation reads it as orphaned/claimable,
+ *      and the next `claim` overwrites it.
+ *
+ *   2. OWNERSHIP IS ADVISORY, not a hard lock. It surfaces "another live session is on this,
+ *      don't touch" and "this is orphaned, take it" — it does not physically prevent an edit.
+ *      A hard lock would let a crashed session permanently freeze its threads; advisory +
+ *      heartbeat-staleness + `--force` is the safe shape.
+ */
+import { readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** The frontmatter key that records a thread's owning session id. */
+export const OWNER_KEY = 'owner_session';
+
+/**
+ * A session id is a bare, filesystem-safe token (uuid-ish: word chars, dots, hyphens). Reject
+ * anything else so a stray value can never inject frontmatter or a newline.
+ * @param {string} sid
+ * @returns {boolean}
+ */
+export function isValidSessionId(sid) {
+  return typeof sid === 'string' && /^[\w.-]+$/.test(sid) && sid.length <= 200;
+}
+
+/**
+ * Read a thread's `owner_session` (or null when unset/empty/missing thread). Reads only the
+ * frontmatter block, matching the board's flat `key: value` shape.
+ * @param {string} projectDir
+ * @param {string} slug
+ * @returns {string|null}
+ */
+export function readOwner(projectDir, slug) {
+  try {
+    const src = readFileSync(join(projectDir, '.fray', `${slug}.md`), 'utf8');
+    const fmEnd = src.indexOf('\n---', 4); // frontmatter is `---\n … \n---`
+    const fm = fmEnd === -1 ? src : src.slice(0, fmEnd);
+    const m = fm.match(/^owner_session:[ \t]*(.*)$/m);
+    if (!m) return null;
+    const v = m[1].trim().replace(/^["']|["']$/g, '');
+    return v || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Set (or, with `sid === null`, REMOVE) a thread's `owner_session` frontmatter field, atomically
+ * and byte-for-byte-preserving everything else — the SAME split/rename discipline as the thread
+ * updater. Throws on a missing thread / no frontmatter / an invalid session id (callers report).
+ * @param {string} projectDir
+ * @param {string} slug
+ * @param {string|null} sid  the owning session id, or null to clear ownership
+ */
+export function setOwner(projectDir, slug, sid) {
+  if (sid !== null && !isValidSessionId(sid)) throw new Error(`invalid session id: ${sid}`);
+  const path = join(projectDir, '.fray', `${slug}.md`);
+  const original = readFileSync(path, 'utf8');
+  const lines = original.split('\n');
+  if (lines[0] !== '---') throw new Error(`thread ${slug}.md has no YAML frontmatter block`);
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === '---') { end = i; break; }
+  }
+  if (end === -1) throw new Error(`thread ${slug}.md frontmatter is not closed`);
+
+  // Locate an existing owner_session line within [1, end).
+  let ownerAt = -1;
+  for (let i = 1; i < end; i++) {
+    if (/^owner_session:/.test(lines[i])) { ownerAt = i; break; }
+  }
+  if (sid === null) {
+    if (ownerAt !== -1) lines.splice(ownerAt, 1); // remove the line entirely
+  } else if (ownerAt !== -1) {
+    lines[ownerAt] = `owner_session: ${sid}`; // update in place, preserving order
+  } else {
+    lines.splice(end, 0, `owner_session: ${sid}`); // append as the last frontmatter line
+  }
+
+  const out = lines.join('\n');
+  const tmp = `${path}.tmp.${process.pid}`;
+  writeFileSync(tmp, out);
+  renameSync(tmp, path);
+}
+
+/**
+ * @typedef {'unowned'|'mine'|'other-live'|'orphaned'} OwnershipState
+ */
+
+/**
+ * Derive the EFFECTIVE ownership state of a thread for the current session.
+ *   - no owner            → `unowned`
+ *   - owner === me        → `mine`
+ *   - owner alive (other) → `other-live`   (don't touch; `--force` to take it)
+ *   - owner dead  (other) → `orphaned`     (freely claimable)
+ * @param {string|null} owner        the thread's `owner_session`
+ * @param {string|null} currentSid   this session's id
+ * @param {boolean} ownerLive        whether `owner` is currently live (heartbeat-derived)
+ * @returns {OwnershipState}
+ */
+export function effectiveOwnership(owner, currentSid, ownerLive) {
+  if (!owner) return 'unowned';
+  if (currentSid && owner === currentSid) return 'mine';
+  return ownerLive ? 'other-live' : 'orphaned';
+}

package/runtime/cc/scripts/fray/rest-detect.mjs

@@ -0,0 +1,213 @@
+// @ts-check
+/**
+ * fray — "rest-on-waiter" detection. PURE, dependency-free, and unit-tested
+ * (rest-detect.test.mjs) so the SubagentStop guard (hooks/fray-rest-guard.mjs)
+ * can stay a thin I/O shell around this judgment.
+ *
+ * THE PROBLEM it detects: a background sub-agent backgrounds a long op (a build, a
+ * test run, a CI watch, an install) and then RESTS — going idle and handing control
+ * back — instead of running the op to completion. That strands the task: the
+ * orchestrator must manually resume it. The guard BLOCKS that stop and redirects the
+ * agent to poll the op inline and finish.
+ *
+ * TWO SIGNALS, OR-ed (defense in depth). A stop is blocked if EITHER fires:
+ *
+ *   1. STRUCTURAL (primary, high-confidence) — {@link detectStructuralRest}: keyed on
+ *      what the agent DID, not how it phrased it. The agent's LAST meaningful tool_use
+ *      in the transcript was a BACKGROUND-LAUNCH (a `run_in_background` Bash/Agent/Task,
+ *      or a Monitor/ScheduleWakeup waiter/timer) and nothing substantive ran after it —
+ *      i.e. it kicked off a background op and ended its turn. This keys on the tool name
+ *      + the `run_in_background` param, so it is immune to phrasing drift (the failure
+ *      mode of the prose matcher below). See `isBackgroundLaunch`.
+ *
+ *   2. PROSE (fallback) — {@link detectWaiterRest}: the original phrasing matcher on the
+ *      final assistant TEXT. Catches a waiter-rest the structural signal misses (e.g. the
+ *      bg-launch was an earlier turn, or the harness shape changed). Demoted to secondary
+ *      because string-matching the prose is fragile; kept because it costs nothing and the
+ *      two signals fail in different directions.
+ *
+ * Why structural beats prose: the prose matcher hinges on the agent SAYING "I'll await
+ * the monitor"; an agent that backgrounds-and-rests SILENTLY (no tell) slips it, and a
+ * reworded tell slips it. The structural signal sees the bg-launch tool call regardless.
+ *
+ * (A fully-deterministic "is the launched bg task STILL RUNNING?" signal was investigated
+ * and is NOT feasible from a hook: the harness `tasks/<id>.output` files are raw stdout
+ * streams / jsonl symlinks with no authoritative running-vs-terminal status or exit-code
+ * sidecar, and the SubagentStop stdin carries no task registry. mtime-liveness is
+ * load-dependent and non-deterministic. So we rely on the tool-use structure, which is
+ * deterministic from the transcript the hook already reads.)
+ */
+import { readFileSync } from 'node:fs';
+
+/**
+ * FUTURE/ONGOING parking intent — the agent declaring it will idle and be woken.
+ * Deliberately excludes bare "complete"/"waited for" (past tense = done, not parking).
+ */
+const PARK =
+  /\b(?:await(?:ing)?|waiting for|i'?ll wait|i'?ll await|holding(?: here)?|pausing|paused here|standing by|letting it (?:complete|finish|run)|will notify me|notify me when|re-?invoke(?:s|d)? me|holding until|until then|rather than poll(?:ing)?)\b/i;
+
+/** BACKGROUND-MECHANISM noun — the thing it's resting ON. */
+const MECH =
+  /\b(?:monitor|waiter|watcher|background(?:ed)?|completion notification|notify(?:ing)? me|re-?invoke)\b/i;
+
+/**
+ * High-confidence single phrases that ALONE prove a waiter-rest (so a message that
+ * trips only one of PARK/MECH but contains one of these still blocks). Kept tight.
+ */
+const STRONG = [
+  /\bthe (?:background )?(?:waiter|monitor|watcher)\b[^.]*\b(?:will|to) (?:notify|re-?invoke|wake)\b/i,
+  /\brather than poll(?:ing)?\b/i,
+  /\bstanding by\b/i,
+  /\bwill (?:notify|re-?invoke|ping|wake) me\b/i,
+];
+
+/**
+ * Does this final-assistant text read as RESTING ON A WAITER/MONITOR (a false rest
+ * that should be blocked) rather than a genuine deliverable?
+ * @param {string|null|undefined} text the agent's last assistant message text
+ * @returns {boolean} true ONLY on a high-confidence waiter-rest match
+ */
+export function detectWaiterRest(text) {
+  if (!text || typeof text !== 'string') return false;
+  // Scan a bounded tail — the parking tell is always at the END of the message, and
+  // scanning the whole of a long report risks a stray match in earlier narration.
+  const tail = text.length > 1200 ? text.slice(-1200) : text;
+  if (STRONG.some((re) => re.test(tail))) return true;
+  return PARK.test(tail) && MECH.test(tail);
+}
+
+/**
+ * Extract the LAST assistant message's joined text from a transcript .jsonl.
+ * Each line is a JSON event; an assistant turn has `type:"assistant"` and
+ * `message.content` is an array of blocks; text blocks are `{type:"text", text}`.
+ * Returns the joined text of the latest assistant turn that HAS any text block, or
+ * null if none/unreadable (→ caller fails open).
+ * @param {string|null|undefined} transcriptPath
+ * @returns {string|null}
+ */
+export function lastAssistantText(transcriptPath) {
+  try {
+    if (!transcriptPath || typeof transcriptPath !== 'string') return null;
+    const raw = readFileSync(transcriptPath, 'utf8');
+    const lines = raw.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i].trim();
+      if (!line) continue;
+      let o;
+      try {
+        o = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (!o || o.type !== 'assistant' || !o.message || !Array.isArray(o.message.content)) continue;
+      const texts = o.message.content
+        .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+        .map((b) => b.text);
+      if (texts.length) return texts.join('\n').trim();
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// STRUCTURAL SIGNAL — key on the agent's TOOL-USE history, not its prose.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * BACKGROUND-LAUNCH tool names that are ALWAYS a waiter/timer launch by their very
+ * nature — no parameter check needed. A Monitor (poll-until loop) or a ScheduleWakeup
+ * (timer) IS, definitionally, "kick off a background wait." (Verified against real
+ * transcripts: `{name:"Monitor", input:{command,timeout_ms,persistent}}` and
+ * `{name:"ScheduleWakeup", input:{delaySeconds,reason,prompt}}`.)
+ * @type {ReadonlySet<string>}
+ */
+const ALWAYS_BG_TOOLS = new Set(['Monitor', 'ScheduleWakeup']);
+
+/**
+ * Is this content block a BACKGROUND-LAUNCH tool_use — the structural tell that the
+ * agent kicked off a background op rather than running it to completion inline?
+ *
+ * Two ways a tool_use qualifies:
+ *   - it is an ALWAYS_BG tool (Monitor / ScheduleWakeup), OR
+ *   - it carries `input.run_in_background === true` (the param real Bash/Agent/Task
+ *     background launches set — verified against transcripts: a backgrounded `Bash`
+ *     has `input.run_in_background:true`, and a backgrounded `Agent` dispatch likewise).
+ *
+ * The `run_in_background` check is GENERIC (any tool name) so a future background-capable
+ * tool is covered without a code change; the named set covers the waiter/timer tools that
+ * take no such flag.
+ * @param {any} block a transcript content block
+ * @returns {boolean}
+ */
+export function isBackgroundLaunch(block) {
+  if (!block || block.type !== 'tool_use' || typeof block.name !== 'string') return false;
+  if (ALWAYS_BG_TOOLS.has(block.name)) return true;
+  const input = block && typeof block.input === 'object' && block.input ? block.input : {};
+  return input.run_in_background === true;
+}
+
+/**
+ * The STRUCTURAL waiter-rest judgment, as a PURE function of the agent's ordered
+ * tool_use blocks (so it is unit-testable with synthetic inputs, no transcript file).
+ *
+ * Fires when the LAST tool_use the agent made was a background-launch. Because it is the
+ * LAST tool_use, nothing substantive ran after it — the agent kicked off a background op
+ * and then ended its turn (emitting at most a final text message). That is exactly the
+ * "backgrounded-and-rested" pathology. A genuine finish polls the op inline first, so its
+ * last tool_use is a FOREGROUND read/commit (run_in_background falsy) — not a bg-launch —
+ * and this returns false.
+ *
+ * @param {any[]} toolUseBlocks ordered (transcript-order) list of tool_use content blocks
+ * @returns {boolean} true ONLY when the last tool_use is a background-launch
+ */
+export function detectStructuralRestFromToolUses(toolUseBlocks) {
+  if (!Array.isArray(toolUseBlocks) || toolUseBlocks.length === 0) return false;
+  return isBackgroundLaunch(toolUseBlocks[toolUseBlocks.length - 1]);
+}
+
+/**
+ * Read a transcript .jsonl and return the LAST tool_use content block the agent made
+ * (across the whole transcript), or null when there is none / it is unreadable. Scans
+ * from the END backward for efficiency (we only need the final tool_use) and stops at
+ * the first assistant turn that carries any tool_use, returning that turn's LAST
+ * tool_use block (a turn may batch several). Fail-CLOSED to null on any error so the
+ * caller fails open (no block).
+ * @param {string|null|undefined} transcriptPath
+ * @returns {any|null}
+ */
+export function lastToolUse(transcriptPath) {
+  try {
+    if (!transcriptPath || typeof transcriptPath !== 'string') return null;
+    const raw = readFileSync(transcriptPath, 'utf8');
+    const lines = raw.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i].trim();
+      if (!line) continue;
+      let o;
+      try {
+        o = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (!o || o.type !== 'assistant' || !o.message || !Array.isArray(o.message.content)) continue;
+      const tus = o.message.content.filter((b) => b && b.type === 'tool_use');
+      if (tus.length) return tus[tus.length - 1];
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * STRUCTURAL waiter-rest detection straight from a transcript path: true when the agent's
+ * last tool_use was a background-launch. Fail-open (false) on any read/parse failure.
+ * @param {string|null|undefined} transcriptPath
+ * @returns {boolean}
+ */
+export function detectStructuralRest(transcriptPath) {
+  const last = lastToolUse(transcriptPath);
+  return isBackgroundLaunch(last);
+}

package/runtime/cc/scripts/fray/thread-excerpt.mjs

@@ -0,0 +1,162 @@
+// @ts-check
+/**
+ * fray — thread-excerpt: read a `.fray/<slug>.md` and render a capped, key-section
+ * excerpt for the ORCHESTRATOR to read.
+ *
+ * WHY THIS EXISTS / where it's used. When a dispatched sub-agent FINISHES and the
+ * orchestrator goes idle, the Stop hook (fray-stop-reminder.mjs) rest-reconciliation
+ * guard hands the orchestrator the CONTENTS of that agent's bound thread — so it can
+ * square the agent's REPORTED results (the task return) against what the thread now
+ * SAYS (the agent should have updated its own thread before resting; this is the
+ * orchestrator's verification surface). We surface the thread HERE rather than via a
+ * SubagentStop hook because a SubagentStop hook's additionalContext continues the
+ * SUB-AGENT's turn, not the orchestrator's — the orchestrator's own Stop hook is the
+ * only channel that actually lands thread text in the orchestrator's context.
+ *
+ * WHAT IT EXTRACTS — the at-a-glance current-truth of a thread, not the whole file:
+ * the frontmatter status line (status + status_text + title) plus the `## Status`,
+ * `## Decisions`, and `## Next step` sections (the single-voice current state). The
+ * rest of the file (Steps checklists, long write-ups) stays behind the path pointer.
+ *
+ * CAPPING — a huge thread must never blow up the orchestrator's context: each thread
+ * is capped to PER_THREAD_CAP chars and the combined surface to TOTAL_CAP; on either
+ * cap we truncate and note the `.fray/<slug>.md` path for the full read.
+ *
+ * FAIL-OPEN ABSOLUTELY: a missing/unreadable file, an unresolved slug, or any parse
+ * error yields no excerpt for that thread (the caller degrades to the bare pointer).
+ * Never throws.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const PER_THREAD_CAP = 1200; // max chars of excerpt body per thread
+const TOTAL_CAP = 4000; // max chars across ALL just-finished threads combined
+
+// The body sections that carry a thread's single-voice CURRENT truth — the same set
+// the dispatch epilogue tells an agent to keep current. Order is the surfaced order.
+const KEY_SECTIONS = ['Status', 'Decisions', 'Next step'];
+
+/**
+ * Pull the content under a `## <name>` heading up to the next h1/h2 (h3+ stays in the
+ * section). Case-insensitive on the heading text; trailing blank lines trimmed.
+ * @param {string} src
+ * @param {string} name
+ * @returns {string} the section body (no heading line), or '' if absent/empty
+ */
+function section(src, name) {
+  const lines = src.split('\n');
+  const esc = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const head = new RegExp(`^##\\s+${esc}\\s*$`, 'i');
+  const i = lines.findIndex((l) => head.test(l));
+  if (i === -1) return '';
+  const body = [];
+  for (let j = i + 1; j < lines.length; j++) {
+    if (/^#{1,2}\s/.test(lines[j])) break; // next h1/h2 ends the section
+    body.push(lines[j]);
+  }
+  return body.join('\n').replace(/\s+$/, '').replace(/^\s*\n/, '');
+}
+
+/**
+ * Parse the leading `--- … ---` frontmatter into a flat scalar map (same shape the
+ * board parser reads). Returns {} when there's no frontmatter.
+ * @param {string} src
+ * @returns {Record<string,string>}
+ */
+function frontmatter(src) {
+  /** @type {Record<string,string>} */
+  const out = {};
+  const m = src.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return out;
+  for (const line of m[1].split('\n')) {
+    const kv = line.match(/^(\w[\w-]*):\s*(.*)$/);
+    if (kv) out[kv[1]] = kv[2].trim().replace(/^["']|["']$/g, '');
+  }
+  return out;
+}
+
+/**
+ * Build a capped excerpt of one thread's current truth, or null if the file can't be
+ * read / has no useful content. The returned string is the BODY only (the caller adds
+ * the `--- .fray/<slug>.md ---` banner) so callers can frame it uniformly.
+ * @param {string} projectDir
+ * @param {string} slug
+ * @returns {string|null}
+ */
+export function threadExcerpt(projectDir, slug) {
+  if (!slug || typeof slug !== 'string') return null;
+  const rel = `.fray/${slug}.md`;
+  let src;
+  try {
+    src = readFileSync(join(projectDir, '.fray', `${slug}.md`), 'utf8');
+  } catch {
+    return null; // missing/unreadable → caller degrades to the bare pointer
+  }
+
+  const fm = frontmatter(src);
+  const parts = [];
+  // Compact frontmatter header — the at-a-glance status, never the whole block.
+  const statusLine = [
+    fm.status ? `status: ${fm.status}` : null,
+    fm.status_text ? `status_text: ${fm.status_text}` : null,
+  ]
+    .filter(Boolean)
+    .join('\n');
+  if (statusLine) parts.push(statusLine);
+
+  for (const name of KEY_SECTIONS) {
+    const body = section(src, name);
+    if (body) parts.push(`## ${name}\n${body}`);
+  }
+
+  if (!parts.length) return null; // nothing useful to surface
+
+  let body = parts.join('\n\n');
+  if (body.length > PER_THREAD_CAP) {
+    body = body.slice(0, PER_THREAD_CAP).replace(/\s+\S*$/, '') + `\n… [truncated — full thread at ${rel}]`;
+  }
+  return body;
+}
+
+/**
+ * Render the combined "thread contents for the agent(s) that just finished" block for a
+ * set of just-completed thread slugs — the orchestrator's verification surface. Dedupes
+ * slugs, skips any that can't be excerpted, and caps the COMBINED size at TOTAL_CAP
+ * (threads past the cap are listed by path only). Returns '' when nothing surfaces, so
+ * the caller can append it unconditionally and degrade to the bare rest pointer.
+ * @param {string} projectDir
+ * @param {string[]} slugs
+ * @returns {string}
+ */
+export function threadExcerptsBlock(projectDir, slugs) {
+  try {
+    const seen = new Set();
+    /** @type {string[]} */
+    const blocks = [];
+    /** @type {string[]} */
+    const overflow = [];
+    let used = 0;
+    for (const slug of slugs || []) {
+      if (!slug || seen.has(slug)) continue;
+      seen.add(slug);
+      const ex = threadExcerpt(projectDir, slug);
+      const rel = `.fray/${slug}.md`;
+      if (!ex) continue; // unreadable/empty → silently skip (bare pointer still names the thread)
+      const rendered = `--- ${rel} ---\n${ex}`;
+      if (used + rendered.length > TOTAL_CAP && blocks.length) {
+        overflow.push(rel); // already surfaced at least one; defer the rest to a path list
+        continue;
+      }
+      blocks.push(rendered);
+      used += rendered.length;
+    }
+    if (!blocks.length) return '';
+    let out =
+      '\n\nfray — thread contents for the agent(s) that just finished (the agent should have updated its thread before resting; square its reported results against what the thread now says):\n\n' +
+      blocks.join('\n\n');
+    if (overflow.length) out += `\n\n… also finished (read in full): ${overflow.join(', ')}`;
+    return out;
+  } catch {
+    return ''; // fail-open — never break the Stop hook over an excerpt
+  }
+}