hivecode-mcp 0.12.4 → 0.13.1

package/hive-notify.js

@@ -0,0 +1,233 @@
+// hive-notify -- tell a person, on Slack or Discord, when an agent in a room is waiting on them.
+//
+//   npx -y hivecode-mcp@latest notify "<link>" --webhook <url> --for <name>[,<name>] [--every <minutes>] [--title <text>]
+//
+// WHY. On 10 Oct 2026 a two-agent demo stalled for an hour: one agent waited for its person's OK,
+// the other waited for it, and the person was not looking at the chat. The room knew. Nobody was
+// told. An owner who leaves agents working has to hear about the two things only they can unblock:
+//
+//   - a task waiting for their approval        sent at once: an agent is stopped until they answer
+//   - messages from agents naming them          batched, at most one post per --every minutes
+//
+// Neither is sent while that person is in the room (the Control Room counts): they can see it.
+//
+// WHAT IS NEVER SENT: the room's link or full id. On an open relay the id is the key to the room's
+// files, and a Slack channel is not the place for a key. Messages name the room by --title, or by
+// the first characters of its id.
+//
+// IT MUST NOT LOOK ALIVE AND DELIVER NOTHING. It posts once when it starts and refuses to run if
+// that post fails; it says once when it has lost the room and once when it is back.
+//
+// Error codes Q640-Q649 are this module's.
+
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+import crypto from 'crypto'
+import { startSync, parseLink } from './sync.js'
+import { makeNotifier, scrub } from './hive-webhook.js'
+
+const oneLine = (s, n = 200) => { const t = String(s || '').replace(/\s+/g, ' ').trim(); return t.length > n ? `${t.slice(0, n - 1)}…` : t }
+const esc = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+const LOST_AFTER = 5 * 60000
+
+/** Does `text` address `name` (@Name, not part of a longer word)? @all counts. */
+export function addresses(text, name) {
+  const t = String(text || '')
+  if (/(^|[^\w@])@all\b/i.test(t)) return true
+  return new RegExp(`(^|[^\\w@])@${esc(name)}(?![\\w-])`, 'i').test(t)
+}
+
+/** What has been sent, kept on disk so a restart does not send it again. */
+export function stateFileFor(room, home = os.homedir()) {
+  const h = crypto.createHash('sha256').update(String(room)).digest('hex').slice(0, 16)
+  return path.join(home, '.hivecode', 'notify', `${h}.json`)
+}
+export function lockFileFor(room, home = os.homedir()) {
+  const h = crypto.createHash('sha256').update(String(room)).digest('hex').slice(0, 16)
+  return path.join(home, '.hivecode', 'notify', `${h}.lock`)
+}
+const alive = (pid) => { try { process.kill(pid, 0); return true } catch (e) { return e.code === 'EPERM' } }
+
+/** One notifier per room. Created exclusively so two starting at the same time cannot double-post. */
+export function takeLock(file) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  for (let i = 0; i < 2; i++) {
+    try {
+      const fd = fs.openSync(file, 'wx')
+      fs.writeSync(fd, JSON.stringify({ pid: process.pid, at: new Date().toISOString() }))
+      fs.closeSync(fd)
+      return () => { try { if (JSON.parse(fs.readFileSync(file, 'utf8')).pid === process.pid) fs.unlinkSync(file) } catch { } }
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e
+      let held = null
+      try { held = JSON.parse(fs.readFileSync(file, 'utf8')) } catch { held = null }
+      if (held && held.pid && held.pid !== process.pid && alive(held.pid)) {
+        const err = new Error(`Q644 a notifier is already running for this room (process ${held.pid}, since ${held.at}). Use that one, or stop it first.`)
+        err.code = 'Q644'
+        throw err
+      }
+      try { fs.unlinkSync(file) } catch { }
+    }
+  }
+  const err = new Error(`Q644 could not take ${file}`)
+  err.code = 'Q644'
+  throw err
+}
+function loadSent(file) {
+  try { const j = JSON.parse(fs.readFileSync(file, 'utf8')); if (j && j.tasks) return j } catch { }
+  return { tasks: {} }
+}
+function saveSent(file, s) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    const ids = Object.keys(s.tasks)
+    if (ids.length > 500) for (const id of ids.slice(0, ids.length - 500)) delete s.tasks[id]
+    fs.writeFileSync(file, JSON.stringify(s))
+  } catch { /* a notifier that cannot remember sends twice; it still sends */ }
+}
+
+/**
+ * The watching itself, on a live sync handle. `check()` is one pass; the CLI calls it on a timer,
+ * and tests call it with a clock of their own.
+ */
+export function makeWatch({ hive, forNames, title, send, now = () => Date.now(), every = 5, stateFile, log = () => {} }) {
+  const people = forNames.map((n) => String(n).trim()).filter(Boolean)
+  const lc = new Set(people.map((n) => n.toLowerCase()))
+  const tasks = hive.doc.getMap('tasks')
+  const owners = hive.doc.getMap('owners')
+  const chat = hive.doc.getArray('chat')
+  const sent = loadSent(stateFile)
+  let seenChat = chat.length // what was said before this started is not news
+  const buffer = []
+  let lastFlush = 0
+  let lostSince = 0
+  let toldLost = false
+
+  const here = (name) => (hive.members ? hive.members() : []).some((m) => String(m.name).toLowerCase() === name.toLowerCase() && m.kind === 'human')
+  const ownerOf = (t) => String(owners.get(t.to) || '')
+
+  function waiting() {
+    return [...tasks.values()].filter((t) => t && t.status === 'pending' && lc.has(ownerOf(t).toLowerCase()))
+  }
+
+  async function check() {
+    const t = now()
+    // THE CONNECTION. Lost for five minutes is said once; back is said once.
+    const connected = !!(hive.connection ? hive.connection().connected : hive.provider && hive.provider.wsconnected)
+    if (!connected) {
+      if (!lostSince) lostSince = t
+      if (!toldLost && t - lostSince >= LOST_AFTER) {
+        toldLost = true
+        await send(`Hivecode lost ${title} ${Math.round((t - lostSince) / 60000)} minutes ago, so nothing from it can reach you here. It keeps trying to reconnect.`)
+      }
+      return
+    }
+    if (lostSince) {
+      if (toldLost) await send(`Hivecode is back in ${title}.`)
+      lostSince = 0
+      toldLost = false
+    }
+
+    // A TASK WAITING FOR APPROVAL: at once, once per task.
+    for (const task of waiting()) {
+      const owner = ownerOf(task)
+      if (sent.tasks[task.id] || here(owner)) continue
+      const ok = await send(`Approval needed in ${title}: ${task.by} asked ${task.to} to "${oneLine(task.text, 300)}". ${task.to} waits until ${owner} approves or denies it in the Control Room.`)
+      if (ok) {
+        sent.tasks[task.id] = t
+        saveSent(stateFile, sent)
+      }
+    }
+
+    // MESSAGES NAMING THEM, from agents, while they are away: batched.
+    const all = chat.toArray()
+    if (all.length < seenChat) seenChat = 0 // the relay restarted and the room's history went with it
+    for (const m of all.slice(seenChat)) {
+      if (!m || m.kind !== 'ai') continue
+      for (const p of people) if (addresses(m.text, p) && !here(p)) { buffer.push({ by: m.by, to: p, text: m.text }); break }
+    }
+    seenChat = all.length
+    if (buffer.length && t - lastFlush >= every * 60000) {
+      const shown = buffer.slice()
+      const to = [...new Set(shown.map((b) => b.to))].join(', ')
+      const lines = shown.slice(0, 5).map((b) => `- ${b.by}: ${oneLine(b.text, 220)}`)
+      if (shown.length > 5) lines.push(`- and ${shown.length - 5} more`)
+      const ok = await send(`${shown.length} message${shown.length === 1 ? '' : 's'} for ${to} in ${title}:\n${lines.join('\n')}`)
+      if (ok) {
+        buffer.splice(0, shown.length)
+        lastFlush = t
+      }
+    }
+  }
+
+  return { check, waiting, buffered: () => buffer.length, sent }
+}
+
+// ---- CLI -------------------------------------------------------------------------------------------
+
+const USAGE = `usage:
+  npx -y hivecode-mcp@latest notify "<link>" --webhook <Slack or Discord webhook URL> --for <name>[,<name>]
+
+  --for <names>     whose approvals and mentions to send (the people, not their agents)
+  --every <min>     at most one post of messages per this many minutes (default 5)
+  --title <text>    what to call the room in posts (default: the first characters of its id)
+  --name <name>     the notifier's own name in the room (default Notifier)`
+
+export async function main(argv, { log = console.log, logErr = console.error, fetchImpl = globalThis.fetch, home = os.homedir(), now = () => Date.now(), once = false } = {}) {
+  if (argv.includes('--help') || argv.includes('-h') || argv[0] === 'help') { log(USAGE); return 0 }
+  const SWITCHES = new Set(['dry-run', 'once'])
+  const pos = []
+  const f = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith('--')) {
+      const k = a.slice(2)
+      if (SWITCHES.has(k)) f[k] = true
+      else f[k] = argv[++i] ?? ''
+    } else {
+      pos.push(a)
+    }
+  }
+  const link = pos[0] || ''
+  const { relay, room, token } = parseLink(link)
+  if (!relay || !room) { logErr(`Q640 "${link}" is not a room link (it looks like wss://relay|room-...).\n\n${USAGE}`); return 2 }
+  if (!f.webhook) { logErr(`Q641 say where to post, with --webhook <Slack or Discord incoming-webhook URL>.\n\n${USAGE}`); return 2 }
+  const forNames = String(f.for || '').split(',').map((s) => s.trim()).filter(Boolean)
+  if (!forNames.length) { logErr(`Q642 say whose waits to report, with --for <name> (the person, as they appear in the room).\n\n${USAGE}`); return 2 }
+  const every = Number(f.every || 5)
+  if (!(every > 0)) { logErr('Q642 --every must be a positive number of minutes'); return 2 }
+  const title = f.title ? oneLine(f.title, 60) : `room ${room.slice(0, 8)}…`
+  const send = makeNotifier(f.webhook, { fetchImpl, log })
+
+  // FIRST, PROVE THE WEBHOOK WORKS. A notifier whose posts go nowhere is worse than none: the person
+  // believes they will be told.
+  if (send.kind === 'other' && send.host) log(`posting in Slack format to ${send.host}`)
+  const okSent = await send(`Hivecode will post here when an agent in ${title} is waiting on ${forNames.join(', ')}.`)
+  if (!okSent) { logErr('Q643 the webhook refused the first post (see above). Check the URL, then start again. Nothing is running.'); return 1 }
+
+  const lockFile = lockFileFor(room, home)
+  const releaseLock = (() => { try { return takeLock(lockFile) } catch (e) { logErr(e.message); return null } })()
+  if (!releaseLock) return 2
+
+  const dir = path.join(home, '.hivecode', 'notify', `room-${crypto.createHash('sha256').update(room).digest('hex').slice(0, 12)}`)
+  const hive = startSync({ relay, room, dir, name: f.name || 'Notifier', kind: 'ai', token: token || process.env.HIVE_TOKEN || '', syncFiles: false, passive: true, log: () => { } })
+  const w = makeWatch({ hive, forNames, title, send, now, every, stateFile: stateFileFor(room, home), log })
+  let synced = false
+  await new Promise((res) => { const t = setTimeout(res, 15000); hive.provider.on('sync', (s) => { if (s) { synced = true; clearTimeout(t); res() } }) })
+  if (!synced && !(hive.provider && hive.provider.wsconnected)) {
+    logErr(`NOTE: could not connect to relay at ${relay}. The room may be unreachable or the network down.`)
+  }
+  const members = (hive.members() || []).filter((m) => m.name !== (f.name || 'Notifier')).map((m) => `${m.name} (${m.kind})`)
+  const pending = w.waiting().length
+  log(`watching ${title}: ${members.length ? members.join(', ') : 'nobody here yet'}; ${pending} approval(s) waiting now. Ctrl+C stops it.`)
+  if (!members.length && !hive.doc.getArray('chat').length) log('NOTE: this room is empty -- no members and no chat. Is the link right?')
+  if (once || f['dry-run']) { await w.check(); hive.stop(); releaseLock(); return 0 }
+  const timer = setInterval(() => { w.check().catch((e) => log(`check failed: ${e.message}`)) }, 15000)
+  const quit = () => { clearInterval(timer); try { hive.stop() } catch { } try { releaseLock() } catch { } process.exit(0) }
+  process.on('SIGINT', quit)
+  process.on('SIGTERM', quit)
+  await w.check()
+  return new Promise(() => { }) // runs until stopped
+}
+

package/hive-pr.js

@@ -37,6 +37,7 @@ import { spawnSync } from 'child_process'
 import { fileURLToPath } from 'url'
 import { startSync, parseLink } from './sync.js'
 import { accountFor, verdict, explain, DIVERGED } from './hive-pr-staleness.js'
+import { contentHash } from './substrate.js'
 
 const argv = process.argv.slice(2)
 const [LINK = '', NAME = 'hive-pr'] = argv.filter((a) => !a.startsWith('--'))
@@ -52,6 +53,7 @@ const DRY = has('dry-run')
 const DO_PUSH = has('push') || has('pr')
 const DO_PR = has('pr')
 const ONLY = flag('only') ? flag('only').split(',').map((s) => s.trim()).filter(Boolean) : null
+const PLAN_JSON = flag('plan-json')
 
 function die(code, msg) { console.error(`${code} ${msg}`); process.exit(1) }
 
@@ -74,20 +76,8 @@ function gitRaw(args, opts = {}) {
   return { code: r.status, out: r.stdout == null ? '' : r.stdout, err: (r.stderr || '').trim() }
 }
 
-/** The authors of a file, newest-landed first, from VERIFIED receipts only.
- *  An unverifiable receipt is not evidence of authorship, so it is dropped rather than trusted. */
-export function authorsOf(receipts, verify) {
-  const ok = receipts.filter((r) => r && r.author && (!verify || verify(r)))
-  if (!ok.length) return { last: null, contributors: [], first: 0 }
-  const last = ok[ok.length - 1]
-  const seen = new Map()
-  for (const r of ok) if (!seen.has(r.author)) seen.set(r.author, { author: r.author, name: r.name || 'agent', at: r.at || 0 })
-  return {
-    last: { author: last.author, name: last.name || 'agent', at: last.at || 0 },
-    contributors: [...seen.values()],
-    first: Math.min(...ok.map((r) => r.at || 0)),
-  }
-}
+import { authorsOf } from './hive-authors.js'
+export { authorsOf }
 
 const mailOf = (name) => `${String(name).toLowerCase().replace(/[^a-z0-9._-]+/g, '-') || 'agent'}@agents.hivecode.local`
 
@@ -96,22 +86,165 @@ export function planCommits(files) {
   const groups = new Map()
   for (const f of files) {
     if (!f.last) continue
-    const g = groups.get(f.last.author) || { author: f.last.author, name: f.last.name, at: f.first, files: [], others: new Map() }
+    const g = groups.get(f.last.author) || { author: f.last.author, name: f.last.name, at: f.first, files: [], others: new Map(), receipts: [] }
     g.files.push(f)
     g.at = Math.min(g.at, f.first)
+    if (Array.isArray(f.receipts)) g.receipts.push(...f.receipts)
     for (const c of f.contributors) if (c.author !== f.last.author) g.others.set(c.author, c)
     groups.set(f.last.author, g)
   }
   return [...groups.values()]
-    .map((g) => ({ ...g, others: [...g.others.values()] }))
-    .sort((a, b) => a.at - b.at || a.name.localeCompare(b.name))
+  .map((g) => ({ ...g, others: [...g.others.values()] }))
+  .sort((a, b) => a.at - b.at || a.name.localeCompare(b.name))
+}
+
+export function sanitizeIntent(raw) {
+  if (typeof raw !== 'string') return ''
+  // Collapse newlines and control characters to single spaces, and cap each at 200 chars
+  const clean = raw.replace(/[\x00-\x1f\x7f-\x9f\r\n\t]+/g, ' ').replace(/\s+/g, ' ').trim()
+  if (!clean) return ''
+  return clean.length > 200 ? clean.slice(0, 200).trim() : clean
+}
+
+export function truncateSubject(agent, intent, max = 72) {
+  const prefix = `${agent}: `
+  const full = `${prefix}${intent}`
+  if (full.length <= max) return full
+  const available = max - prefix.length - 3 // space for '...'
+  if (available <= 0) return full.slice(0, max)
+  const sliced = intent.slice(0, available)
+  const lastSpace = sliced.lastIndexOf(' ')
+  const cut = (lastSpace > 0) ? sliced.slice(0, lastSpace) : sliced
+  return `${prefix}${cut}...`
+}
+
+export function buildPlanJson({ room, groups = [], orphans = [], identical = [], blocked = [], hashes = {} }) {
+  const skip = new Set(identical)
+  return {
+    room,
+    groups: groups.map((g) => {
+      const gFiles = (g.files || []).map((f) => (typeof f === 'string' ? f : f.rel)).filter((rel) => !skip.has(rel))
+      const allReceipts = []
+      if (Array.isArray(g.receipts)) allReceipts.push(...g.receipts)
+      for (const f of g.files || []) {
+        if (f && Array.isArray(f.receipts)) allReceipts.push(...f.receipts)
+      }
+      const seen = new Set()
+      const intents = []
+      for (const r of allReceipts) {
+        if (!r || typeof r.intent !== 'string') continue
+        const clean = sanitizeIntent(r.intent)
+        if (!clean || clean.toLowerCase() === 'edit') continue
+        if (!r.author || r.author === g.author) {
+          if (!seen.has(clean)) {
+            seen.add(clean)
+            intents.push(clean)
+          }
+        }
+      }
+      return {
+        name: g.name,
+        author: g.author,
+        files: gFiles,
+        intents,
+      }
+    }),
+    orphans: orphans.map((o) => (typeof o === 'string' ? o : o.rel)),
+    identical: [...identical],
+    blocked: [...blocked],
+    // The room's content hash of every file a group would write, as this mirror read it: what a
+    // hive_review must match, and how a watcher tells a changed room from a re-run of the same one.
+    hashes: Object.fromEntries(Object.entries(hashes || {}).filter(([rel]) => !skip.has(rel))),
+  }
+}
+
+export const OWN_FILES = new Set(['.hive.json', '.hive-shadow.json', '.hive-shadow.json.tmp', '.hive-lock.json', '.hive-id.json', '.hive-mcp-session.json', '.hive-stop-hook.json'])
+export const isOwnFile = (rel) => {
+  const b = path.basename(rel)
+  return OWN_FILES.has(b) || /^HIVE_[A-Z0-9_]+\.md$/i.test(b) || b.startsWith('.hive')
+}
+
+export function isOrphan({ rel, last, roomText, branchText }) {
+  if (last) return false
+  if (isOwnFile(rel)) return false
+  if (branchText !== null && branchText !== undefined && branchText === roomText) return false
+  return true
 }
 
 export function commitMessage(g, room) {
   const list = g.files.map((f) => f.rel).sort()
-  const head = list.length === 1 ? `${g.name}: ${list[0]}` : `${g.name}: ${list.length} files`
-  const lines = [head, '', ...list.map((x) => `  - ${x}`), '', `Room: ${room}`, `Hivecode-Author: ${g.author}`]
-  for (const o of g.others) lines.push(`Co-authored-by: ${o.name} <${mailOf(o.name)}>`)
+
+  // Collect receipts up to held content across files in the group
+  const allReceipts = []
+  if (Array.isArray(g.receipts)) allReceipts.push(...g.receipts)
+  for (const f of g.files) {
+    if (Array.isArray(f.receipts)) allReceipts.push(...f.receipts)
+  }
+
+  // Deduplicate and filter non-edit intents for the committing author
+  const seenAuthorIntents = new Set()
+  const authorIntents = []
+
+  // Deduplicate and filter non-edit intents for co-authors
+  const seenCoauthorIntents = new Set()
+  const coauthorIntents = []
+
+  const othersMap = new Map((g.others || []).map((o) => [o.author, o.name]))
+
+  for (const r of allReceipts) {
+    if (!r || typeof r.intent !== 'string') continue
+    const clean = sanitizeIntent(r.intent)
+    if (!clean || clean.toLowerCase() === 'edit') continue
+
+    if (!r.author || r.author === g.author) {
+      if (!seenAuthorIntents.has(clean)) {
+        seenAuthorIntents.add(clean)
+        authorIntents.push(clean)
+      }
+    } else {
+      const coauthorName = r.name || othersMap.get(r.author) || 'co-author'
+      const key = `${coauthorName}: ${clean}`
+      if (!seenCoauthorIntents.has(key)) {
+        seenCoauthorIntents.add(key)
+        coauthorIntents.push({ name: coauthorName, intent: clean })
+      }
+    }
+  }
+
+  // Subject: "<agent>: <first non-edit intent>" up to 72 chars, fallback to today's message
+  let head
+  if (authorIntents.length > 0) {
+    head = truncateSubject(g.name, authorIntents[0], 72)
+  } else {
+    head = list.length === 1 ? `${g.name}: ${list[0]}` : `${g.name}: ${list.length} files`
+  }
+
+  // Body: lists intents and files if non-edit intents exist, fallback to today's message
+  const lines = [head, '']
+  if (authorIntents.length > 0 || coauthorIntents.length > 0) {
+    lines.push('Intents:')
+    for (const intent of authorIntents) {
+      lines.push(`  - ${intent}`)
+    }
+    for (const ci of coauthorIntents) {
+      lines.push(`  - ${ci.name}: ${ci.intent}`)
+    }
+    lines.push('')
+    lines.push('Files:')
+    for (const f of list) {
+      lines.push(`  - ${f}`)
+    }
+  } else {
+    for (const f of list) {
+      lines.push(`  - ${f}`)
+    }
+  }
+  lines.push('')
+  lines.push(`Room: ${room}`)
+  lines.push(`Hivecode-Author: ${g.author}`)
+  for (const o of g.others) {
+    lines.push(`Co-authored-by: ${o.name} <${mailOf(o.name)}>`)
+  }
   return lines.join('\n')
 }
 
@@ -206,12 +339,27 @@ if (isMain) {
       const receipts = hive.provenanceOf(rel) || []
       const audit = hive.verifyProvenanceOf(rel) || { bad: [] }
       const badIdx = new Set((audit.bad || []).map((b) => b.i))
-      const a = authorsOf(receipts, (r) => !badIdx.has(receipts.indexOf(r)))
+      let roomText = null
+      try { roomText = fs.readFileSync(path.join(dir, rel), 'utf8') } catch { }
+      const a = authorsOf(receipts, (r) => !badIdx.has(receipts.indexOf(r)), roomText)
       files.push({ rel, abs: path.join(dir, rel), ...a })
     }
 
-    const attributed = files.filter((f) => f.last)
-    const orphans = files.filter((f) => !f.last)
+    const base = flag('base') || git(['rev-parse', '--abbrev-ref', 'HEAD']).out || 'HEAD'
+    const attributed = []
+    const orphans = []
+    for (const f of files) {
+      if (f.last) {
+        attributed.push(f)
+      } else {
+        const sha = git(['rev-parse', `${base}:${f.rel}`])
+        const branchText = sha.code === 0 ? gitRaw(['cat-file', 'blob', sha.out]).out : null
+        const roomText = fs.readFileSync(f.abs, 'utf8')
+        if (isOrphan({ rel: f.rel, last: f.last, roomText, branchText })) {
+          orphans.push(f)
+        }
+      }
+    }
     const groups = planCommits(attributed)
 
     console.log(`room ${room}: ${files.length} files, ${attributed.length} attributed, ${groups.length} agent(s)`)
@@ -221,11 +369,6 @@ if (isMain) {
     }
     if (orphans.length) console.log(`  (${orphans.length} file(s) with no verified receipt -- not committed: ${orphans.map((o) => o.rel).join(', ')})`)
 
-    if (DRY) { console.log('\n--dry-run: nothing written'); return finish(0) }
-    if (!groups.length) { console.error('Q501 nothing attributed to commit'); return finish(1) }
-
-    const base = flag('base') || git(['rev-parse', '--abbrev-ref', 'HEAD']).out || 'HEAD'
-
     // ── HIV-28: DO NOT WRITE OVER A BRANCH CHANGE WE CANNOT ACCOUNT FOR ──────────────────
     //
     // Measured 19 Sep 2026: this tool produced a PR with three clean per-agent commits, real git
@@ -251,7 +394,39 @@ if (isMain) {
     const v = verdict(decisions)
     if (v.identical.length) console.log(`  (${v.identical.length} file(s) already identical on ${base} -- nothing to write)`)
 
+    function writePlanJson() {
+      if (!PLAN_JSON) return
+      const identicalRels = (v && v.identical) ? v.identical.map((d) => d.rel) : []
+      const blockedRels = (v && v.blocked) ? v.blocked.map((d) => d.rel) : []
+      const plan = buildPlanJson({
+        room,
+        groups,
+        orphans,
+        identical: identicalRels,
+        blocked: blockedRels,
+        hashes: Object.fromEntries(groups.flatMap((g) => g.files || []).map((x) => { try { return [x.rel, contentHash(fs.readFileSync(x.abs, 'utf8'))] } catch { return null } }).filter(Boolean)),
+      })
+      try {
+        fs.mkdirSync(path.dirname(path.resolve(PLAN_JSON)), { recursive: true })
+        fs.writeFileSync(PLAN_JSON, JSON.stringify(plan, null, 2), 'utf8')
+      } catch (err) {
+        console.error(`warning: could not write --plan-json to ${PLAN_JSON}: ${err.message}`)
+      }
+    }
+
+    if (DRY) {
+      writePlanJson()
+      console.log('\n--dry-run: nothing written')
+      return finish(0)
+    }
+    if (!groups.length) {
+      writePlanJson()
+      console.error('Q501 nothing attributed to commit')
+      return finish(1)
+    }
+
     if (!v.ok) {
+      writePlanJson()
       const lastTouch = (rel) => git(['log', '-1', '--format=%h %an %ad %s', '--date=short', base, '--', rel]).out
       console.error('')
       console.error(explain(v.blocked, lastTouch))
@@ -324,6 +499,7 @@ if (isMain) {
       if (r.status !== 0) { console.error(`Q505 gh pr create failed: ${(r.stderr || '').trim()}`); return finish(1) }
       console.log((r.stdout || '').trim())
     }
+    writePlanJson()
     finish(0)
   }
 
@@ -334,4 +510,4 @@ if (isMain) {
       process.exit(code)
     }, 400)
   }
-}
+}