hivecode-mcp 0.11.5 → 0.12.0

package/hive-obligations.js

@@ -0,0 +1,247 @@
+// hive-obligations.js — a question you asked stays open until YOU say it was answered.
+//
+// THE PROBLEM THIS EXISTS FOR, observed live on 19 Sep 2026.
+//
+// Tester posted one message at 12:29 addressed to @Reviewer, an agent that was never in the
+// room, and then went silent for six hours. Nothing failed. No tool returned an error, no
+// process died, no log line said anything was wrong. The room simply had a question in it that
+// nobody would ever answer, and the only way to find that out was for a human to read the
+// transcript and notice.
+//
+// Hivecode already carries the RULE -- the MCP instructions say "ANSWER EVERY QUESTION AIMED AT
+// YOU: silence is the one thing the asker cannot act on". A rule an agent read once is a rule it
+// forgets the moment its context fills. So the rule moves here, where it is a data structure
+// instead of a paragraph.
+//
+// THE ONE LOAD-BEARING DECISION: ONLY THE ASKER DISCHARGES.
+//
+// The obvious design lets the answerer mark it answered. That design measures nothing. An agent
+// that replies "I'll look into it" would clear its own obligation, and a question answered wrongly
+// clears just as cleanly as one answered well. Both are exactly the failure -- everything green,
+// the result wrong -- that every defect on this project has turned out to be.
+//
+// So: `from` opened it, and only `from` can close it. The debtor cannot mark its own homework.
+// (Agent Relay reached the same conclusion independently in crates/broker/src/obligation.rs:
+// "only the author can discharge an obligation... the broker checks reactor == author". Their
+// broker re-injects a knock on a timer, which costs tokens on every knock. Ours rides hive_wait,
+// which is already blocked and already free.)
+//
+// ESCALATION IS TO AN AUDIENCE, NOT A FREQUENCY. A knock that repeats every minute forever is
+// noise, and a room learns to ignore noise. So the interval backs OFF (10min, 20min, 40min...)
+// while the visibility goes UP: after `STALE_AFTER` knocks the record is stale, and a stale
+// obligation is the room's problem rather than one agent's.
+//
+// PURE ON PURPOSE. Every function here takes the store and the clock. The store needs only
+// get/set/delete/entries, which a Y.Map and a plain Map both satisfy -- so the tests run against
+// a Map with an injected clock and no relay, and the production path passes the Y.Map. That is
+// the same shape as governor.js, and it is what let the governor's 10x minutes bug be caught by
+// a test instead of by a customer.
+
+/** Default time before the first knock. Ten minutes: long enough that an agent mid-task is not
+ *  nagged for thinking, short enough that a stall is caught inside one working stretch. */
+export const DUE_MS = 10 * 60000
+
+/** Each knock doubles the wait, so a genuinely long job is not pestered... */
+export const BACKOFF = 2
+
+/** ...but never past this, or a forgotten question goes quiet for a whole shift. */
+export const MAX_DUE_MS = 60 * 60000
+
+/** Knocks before the room is told. Three because two is a coincidence and four is too late. */
+export const STALE_AFTER = 3
+
+/** Chat text is a whole message; an obligation is an index entry. Keep it short enough that
+ *  `hive_owed` on a busy room stays readable rather than becoming a second transcript. */
+export const TEXT_MAX = 140
+
+const clip = (s) => {
+  const t = String(s == null ? '' : s).replace(/\s+/g, ' ').trim()
+  return t.length > TEXT_MAX ? t.slice(0, TEXT_MAX - 1) + '…' : t
+}
+
+/** Ids must not collide across peers. Two agents opening an obligation in the same millisecond is
+ *  not hypothetical in a CRDT room -- every write lands, and a shared key would silently make one
+ *  of the two questions disappear. Name + time + entropy: the name alone makes it readable in a
+ *  log, which the entropy alone would not.
+ *
+ *  THE TAG IS TWO DRAWS, NOT ONE, and that is not belt-and-braces. A single `rand() * 1e6` gives
+ *  about 2^20 of space, and by the birthday bound 500 ids drawn from it collide roughly 12% of the
+ *  time -- which is exactly how this was found: the suite passed, then failed, then passed again on
+ *  unchanged code. A flaky test here is not test flakiness, it is the defect reporting itself. Two
+ *  draws give ~2^40, where the same 500 ids collide about one run in five million. */
+export function obligationId(from, at, rand = Math.random) {
+  const draw = () => Math.floor(rand() * 1e6).toString(36).padStart(4, '0')
+  return `ob_${String(from || '?').toLowerCase().replace(/[^a-z0-9]+/g, '')}_${at.toString(36)}_${draw()}${draw()}`
+}
+
+/**
+ * Open an obligation: `from` asked `to` something and is owed an answer.
+ *
+ * `absent` is recorded at OPEN time and never recomputed. That is deliberate -- it is the answer
+ * to "was anyone even there when this was asked", which is a fact about the past. Recomputing it
+ * later would let a question asked into an empty room look fine the moment someone walks in.
+ */
+/**
+ * PRESENCE AND PROVENANCE ARE DIFFERENT QUESTIONS, AND `absent` ONLY ANSWERS THE FIRST.
+ *
+ * `absent` is stamped at send time and means "nobody by that name was connected at this instant".
+ * That is the right question for the warning — it is how the 19 Sep stall was caught — and it is
+ * the WRONG question for how long the record should live, because an agent mid-reconnect or
+ * mid-ratelimit is absent and is also a real teammate who really owes an answer.
+ *
+ * Measured in room `night`, 20 Sep 2026: an obligation against @DeepMind-Agent was stamped absent
+ * because it had dropped between turns. It came back ninety minutes later and answered. Expiring
+ * that record on a ten-minute timer would have deleted a genuine debt — and worse, it would have
+ * emptied the ledger precisely while an agent was silent, which is the exact inverse of what the
+ * ledger is for.
+ *
+ * So `neverSeen` is the separate fact: nobody by this name has ever joined or spoken here. That is
+ * the noise — @gmail, @modelcontextprotocol, a name quoted out of a test suite. It is safe to
+ * expire and safe for anyone to dismiss, because there is no debtor whose honesty the author-only
+ * rule exists to protect.
+ */
+export function open(store, { from, to, text, dueMs = DUE_MS, absent = false, neverSeen = false }, now = Date.now, rand = Math.random) {
+  const at = now()
+  const rec = {
+    id: obligationId(from, at, rand),
+    from: String(from),
+    to: String(to),
+    text: clip(text),
+    at,
+    due: at + Math.max(1, dueMs),
+    dueMs: Math.max(1, dueMs),
+    knocks: 0,
+    absent: !!absent,
+    neverSeen: !!neverSeen,
+    done: false,
+  }
+  store.set(rec.id, rec)
+  return rec
+}
+
+const all = (store) => [...store.entries()].map(([, v]) => v).filter(Boolean)
+
+/** Everything still open. */
+/**
+ * Everything still owed — with never-seen records aging out on their own.
+ *
+ * EXPIRY IS MATERIALISED, NOT MERELY FILTERED, and that distinction is load-bearing. Filtering
+ * here would leave `done: false` on the record, and `isStale` reads `r.done` directly rather than
+ * going through this function — so an expired ghost would vanish from one view and linger in
+ * another. Two readers disagreeing about whether a thing is finished is the same defect this whole
+ * file exists to prevent, one level down.
+ *
+ * Written lazily on read, which is the pattern the claim layer already uses (`hive-coord.js`
+ * expires a lease the moment somebody looks). There is no timer to miss and nothing to schedule:
+ * the fact becomes true at `due`, and the first reader after that writes it down.
+ *
+ * NO RESURRECTION. `neverSeen` is stamped when the question is asked and never recomputed, so a
+ * name that finally joins hours later does not revive its expired debt. The question was asked
+ * into an empty room; somebody arriving afterwards does not change what was true then.
+ *
+ * Only never-seen records expire. A known teammate's debt survives any amount of silence, because
+ * silence is the thing it is there to make visible.
+ */
+export const openList = (store, now = Date.now) => {
+  const out = []
+  for (const r of all(store)) {
+    if (r.done) continue
+    if (r.neverSeen && now() >= r.due) {
+      store.set(r.id, { ...r, done: true, doneAt: now(), doneBy: 'auto-expired (never seen here)' })
+      continue
+    }
+    out.push(r)
+  }
+  return out
+}
+
+/** What `name` OWES: questions aimed at them that their asker has not signed off. */
+export const owedBy = (store, name) =>
+  openList(store).filter((r) => String(r.to).toLowerCase() === String(name).toLowerCase())
+
+/** What `name` IS OWED: questions they asked that they have not signed off. */
+export const owedTo = (store, name) =>
+  openList(store).filter((r) => String(r.from).toLowerCase() === String(name).toLowerCase())
+
+/**
+ * Discharge. Returns `{ ok, reason }` and NEVER throws, because the interesting cases are all
+ * refusals and a refusal has to be readable by the agent that hit it.
+ *
+ * The `by !== from` refusal is the whole mechanism. It is phrased as instruction rather than
+ * error, because the agent reading it is usually the debtor trying to close its own ticket and
+ * the useful next action is "answer, then ask them to close it".
+ */
+export function discharge(store, { id, by }, now = Date.now) {
+  const rec = store.get(id)
+  if (!rec) return { ok: false, reason: `no obligation ${id} -- it may already be discharged` }
+  if (rec.done) return { ok: true, already: true, rec }
+  // THE AUTHOR-ONLY RULE PROTECTS A DEBTOR FROM GRADING ITS OWN HOMEWORK. A never-seen record has
+  // no debtor: nobody by that name has ever been here, so there is nobody whose self-assessment
+  // the rule is guarding against. Holding the rule there protects nothing and costs the room an
+  // entry only the original asker can clear -- and tonight the original asker cleared forty of
+  // them by hand. Anyone may tidy these; real debts keep the rule untouched.
+  if (!rec.neverSeen && String(rec.by || rec.from).toLowerCase() !== String(by).toLowerCase()) {
+    return {
+      ok: false,
+      reason: `${by} cannot discharge this: ${rec.from} asked it, and only the asker can say it ` +
+        `was answered. If you are ${rec.to}, answer it in chat and ${rec.from} will close it -- ` +
+        `marking your own answer sufficient is exactly the check this exists to make.`,
+    }
+  }
+  const done = { ...rec, done: true, doneAt: now(), doneBy: String(by) }
+  store.set(id, done)
+  return { ok: true, rec: done }
+}
+
+/** Close everything `by` is owed from one agent. An asker who got a long reply covering four
+ *  questions should not have to look up four ids to say so. */
+export function dischargeFrom(store, { by, to }, now = Date.now) {
+  const hit = owedTo(store, by).filter((r) => String(r.to).toLowerCase() === String(to).toLowerCase())
+  for (const r of hit) discharge(store, { id: r.id, by }, now)
+  return hit
+}
+
+/** Open obligations whose knock time has passed. */
+export const overdue = (store, name, now = Date.now) =>
+  owedBy(store, name).filter((r) => now() >= r.due)
+
+/**
+ * Record that a knock was delivered, and push the next one out.
+ *
+ * Called only when the knock actually reached somebody -- if we advanced `due` on merely NOTICING
+ * an overdue record, a debtor that never calls hive_wait would have its deadline extended forever
+ * by an observer, which is precisely backwards.
+ */
+export function knock(store, id, now = Date.now) {
+  const rec = store.get(id)
+  if (!rec || rec.done) return null
+  const nextDueMs = Math.min(MAX_DUE_MS, Math.max(1, rec.dueMs) * BACKOFF)
+  const next = { ...rec, knocks: rec.knocks + 1, dueMs: nextDueMs, due: now() + nextDueMs, lastKnockAt: now() }
+  store.set(id, next)
+  return next
+}
+
+/** Knocked enough times that this is the room's problem now, not one agent's. */
+export const isStale = (r) => !r.done && r.knocks >= STALE_AFTER
+
+/** Every stale obligation in the room, for the board and for the human. */
+export const stale = (store) => openList(store).filter(isStale)
+
+const mins = (ms) => Math.round(ms / 6000) / 10
+
+/** One line, for chat and for tool output. Age is what makes it actionable: "Tester owes Claude
+ *  an answer" is a fact, "for 361 minutes" is a decision. */
+export function describe(r, now = Date.now) {
+  const age = mins(now() - r.at)
+  const flags = [
+    r.absent ? 'NOBODY BY THAT NAME WAS IN THE ROOM' : '',
+    isStale(r) ? `STALE after ${r.knocks} reminders` : '',
+  ].filter(Boolean)
+  return `${r.id}  ${r.to} owes ${r.from}  (${age}m)  "${r.text}"${flags.length ? '  [' + flags.join('; ') + ']' : ''}`
+}
+
+/** The whole board, newest question last so it reads like a conversation. */
+export function board(store, now = Date.now) {
+  const list = openList(store).sort((a, b) => a.at - b.at)
+  return { open: list.length, stale: list.filter(isStale).length, lines: list.map((r) => describe(r, now)) }
+}

package/hive-pr-staleness.js

@@ -0,0 +1,189 @@
+// hive-pr-staleness.js — do not write a file over a branch change you cannot account for.
+//
+// THE INCIDENT, MEASURED 19 Sep 2026. hive-pr generated a PR that looked perfect: three commits,
+// one per agent, each agent as the real git author, signed ids in `Hivecode-Author:` trailers,
+// files with no verified receipt refused rather than committed. A reviewer would have had every
+// reason to trust it.
+//
+// Diffed against the branch it was cut from:
+//
+//     hive-linear.js               -77
+//     tests/hive-linear-test.mjs  -114
+//     tests/hive-mcp-http-test.mjs -49
+//     tests/hive-governor-test.mjs -32
+//     sync.js                      -39
+//
+// It deleted the HIV-27 claim guard, deleted the HIV-14 truncation fix, deleted ~200 lines of
+// tests, and restored the 10x dashboard bug -- the one where thirty minutes of runtime displays
+// as 3.0. Filed HIV-28.
+//
+// THE CAUSE IS ONE LINE. hive-pr.js did `fs.copyFileSync(f.abs, dest)` and then `git add`. It
+// treats the room as truth and writes it over the branch. Grepping that file for `ahead`,
+// `behind`, `stale`, `diverged`, `merge-base` or `rev-list` returned nothing: it never asked
+// whether the branch had moved.
+//
+// This is not an exotic case, it is the NORMAL one. Any commit reaching the branch by another
+// route puts it ahead -- a hotfix, a second developer, CI, or a human doing exactly the
+// review-then-push workflow this tool exists to serve. In the measured incident the other route
+// was me, working in the git checkout instead of my room folder.
+//
+// WHY "AHEAD/BEHIND" IS THE WRONG QUESTION. There is no merge-base between a Yjs room and a git
+// branch; they are not two git histories. `git rev-list --count` cannot answer this, and reaching
+// for it would produce a check that looks rigorous and measures nothing.
+//
+// THE QUESTION THAT IS ANSWERABLE, per file:
+//
+//               has the room ever SEEN what is currently on the branch?
+//
+// It can be answered exactly, from state that already exists. Every landed change appends a
+// receipt carrying `parent` (the contentHash the author built on) and `contentHash` (the result),
+// so a file's ledger IS a hash chain of every state the room has passed through. `provenanceOf()`
+// already returns it -- hive-pr reads it for attribution and then ignores it for safety.
+//
+// If the branch's current bytes hash to something in that chain, the room descends from the
+// branch and writing is continuing the line. If they do not, the branch holds a change the room
+// has never seen, and writing would delete it. That is the whole check.
+
+import { contentHash } from './substrate.js'
+
+/** Nothing to write: the branch already holds exactly this. */
+export const IDENTICAL = 'IDENTICAL'
+/** The file is not on the branch at all, so there is nothing to revert. */
+export const NEW = 'NEW'
+/** The branch's bytes are in the room's chain: the room descends from them. Safe. */
+export const DESCENDS = 'DESCENDS'
+/** The branch holds bytes the room has never seen. REFUSE. */
+export const DIVERGED = 'DIVERGED'
+/** The room has no chain for this file, so nothing can be proved either way. REFUSE. */
+export const UNPROVEN = 'UNPROVEN'
+
+/** The only two states that may be written. A list, so widening it is a visible edit. */
+export const WRITABLE = [NEW, DESCENDS]
+
+/**
+ * LINE ENDINGS ARE PRESENTATION, AND ON THIS REPO THEY DIFFER BY DEFAULT.
+ *
+ * Measured here: `hive-mcp.js` and `sync.js` are CRLF in the working tree and LF in the blob,
+ * because `core.autocrlf` is true. So the bytes git stored and the bytes the room holds are not
+ * equal for most files in this project, while the file is by any useful definition the same file.
+ *
+ * A byte comparison would therefore mark nearly everything DIVERGED and refuse every run. That is
+ * worse than no check: a guard that fires on the HEALTHY path is the one that gets a `--force`
+ * alias in somebody's shell history within a week, and then it is not a guard at all.
+ *
+ * So both the equality test and the chain lookup are done modulo line endings. Three variants, not
+ * a normalisation, because the chain's hashes were computed by substrate.js over whatever text the
+ * room actually held at the time -- there is no single canonical form to normalise TO.
+ */
+const variants = (t) => {
+  const lf = String(t).replace(/\r\n/g, '\n')
+  return [String(t), lf, lf.replace(/\n/g, '\r\n')]
+}
+
+/** Same file, ignoring how the lines end. */
+export const sameText = (a, b) =>
+  a != null && b != null && String(a).replace(/\r\n/g, '\n') === String(b).replace(/\r\n/g, '\n')
+
+/**
+ * Every content state this file has passed through in the room.
+ *
+ * Both fields go in. `parent` is the state an author BUILT ON -- which may be a state no receipt
+ * ever produced, because the first write's parent is the hash of the empty string and a rejoin
+ * can land on a state whose own receipt lives on another peer. Taking only `contentHash` would
+ * miss exactly those, and each miss reads as DIVERGED: a refusal on a healthy file, which is the
+ * failure mode that gets a safety check disabled.
+ */
+export function chainOf(receipts) {
+  const seen = new Set()
+  for (const r of receipts || []) {
+    if (!r) continue
+    if (r.parent) seen.add(r.parent)
+    if (r.contentHash) seen.add(r.contentHash)
+  }
+  return seen
+}
+
+/**
+ * Decide whether the room's copy may be written over the branch's.
+ *
+ * `branchText` is null when the path does not exist on the branch. It must be the RAW blob --
+ * read with `git cat-file blob`, never `git show` through a working tree, or a checkout with
+ * `core.autocrlf` hands back bytes git never stored and every hash misses.
+ */
+export function accountFor({ rel, branchText, roomText, receipts }) {
+  if (branchText == null) return { rel, state: NEW, why: 'not on the branch yet — nothing can be reverted' }
+  // Modulo line endings on purpose. A file that differs ONLY in how its lines end must not be
+  // rewritten: it would produce a diff of every line in the file, for no change anybody made.
+  if (sameText(branchText, roomText)) return { rel, state: IDENTICAL, why: 'the branch already holds this (line endings aside)' }
+
+  const chain = chainOf(receipts)
+  if (!chain.size) {
+    return {
+      rel, state: UNPROVEN,
+      why: 'the room has no provenance chain for this file, so there is no way to tell whether its copy is newer than the branch or older',
+    }
+  }
+
+  const hashes = variants(branchText).map(contentHash)
+  if (hashes.some((h) => chain.has(h))) {
+    return { rel, state: DESCENDS, why: 'the room has passed through the branch\'s current content, so its copy is a descendant' }
+  }
+  return {
+    rel, state: DIVERGED, branchHash: hashes[0],
+    why: 'the branch holds content this room has never seen — writing the room\'s copy would delete it',
+  }
+}
+
+/** May this decision be written? Never inline `state !== DIVERGED` — that admits UNPROVEN. */
+export const writable = (d) => WRITABLE.includes(d.state)
+
+/**
+ * The run-level verdict.
+ *
+ * ALL OR NOTHING, and that is the design. Committing the safe files and skipping the rest produces
+ * a PR that looks complete and is not -- the same false success the tool already produced once,
+ * one level up. A refusal a human can read beats a branch they have to audit.
+ */
+export function verdict(decisions) {
+  const blocked = decisions.filter((d) => !writable(d) && d.state !== IDENTICAL)
+  return {
+    ok: blocked.length === 0,
+    blocked,
+    writable: decisions.filter(writable),
+    identical: decisions.filter((d) => d.state === IDENTICAL),
+  }
+}
+
+/**
+ * What the operator reads. `lastTouch` is supplied by the caller (hive-pr runs the git command)
+ * so this module stays pure and testable without a repository.
+ *
+ * It names the commit and the person, because "diverged" alone sends someone to `git log` to work
+ * out whether this is their own forgotten hotfix or somebody else's live work -- and that lookup
+ * is the moment a tired operator reaches for --force.
+ */
+export function explain(blocked, lastTouch = () => '') {
+  // Q506, the next free code in hive-pr's own Q500-Q505 block. Q443 would have read naturally
+  // here -- it is the other "you are being handed an incomplete picture" refusal -- and it is
+  // already the Linear truncation code. Two meanings behind one code is the duplicated-wire
+  // -contract defect wearing a three-digit hat.
+  const lines = ['Q506 REFUSING TO WRITE — the branch has moved under these files:', '']
+  for (const d of blocked) {
+    const touch = lastTouch(d.rel)
+    lines.push(`  ${d.rel}`)
+    lines.push(`      ${d.why}`)
+    if (touch) lines.push(`      last changed on the branch by: ${touch}`)
+  }
+  lines.push('')
+  lines.push('Nothing was written and no branch was created. Writing the room\'s copy over these')
+  lines.push('would silently revert whatever reached the branch another way — a hotfix, a second')
+  lines.push('developer, CI, or your own work done outside the room. That has happened once on this')
+  lines.push('project and the resulting PR looked perfect.')
+  lines.push('')
+  lines.push('Fix it one of two ways:')
+  lines.push('  - bring the branch\'s version INTO the room (edit it there, or hive_edit it), so the')
+  lines.push('    room\'s copy descends from what is on the branch. Then run this again.')
+  lines.push('  - --force "<reason>" if you have decided the room\'s copy should win. The reason is')
+  lines.push('    recorded in the PR body, because somebody will ask.')
+  return lines.join('\n')
+}