hivecode-mcp 0.12.1 → 0.12.4

package/hive-throttle.js

@@ -1,118 +1,118 @@
-// hive-throttle.js — say it again only if they can no longer see it.
-//
-// TWO OPPOSITE WASTES, ONE CAUSE. Hivecode repeats some blocks to an agent that still has them
-// verbatim, and never repeats others to an agent that lost them hours ago. Both are the same
-// missing question: *is this still in their context?*
-//
-//   [GLOBAL PROJECT STATE]   rebuilt and returned on EVERY hive_wait, unchanged, forever.
-//                            An agent waiting in a loop is handed the same JSON hundreds of
-//                            times, and pays for it hundreds of times.
-//
-//   HIVE_RULES.md            6,288 bytes handed over ONCE, in the hive_join tool result. It sits
-//                            in the transcript, so it is exactly what compaction throws away
-//                            first -- and it is the ROOM-specific half of the rules: lanes, gate
-//                            commands, who owns what. Six hours in, it is simply gone.
-//
-// WHAT IS *NOT* IN SCOPE, AND THIS WAS WORTH CHECKING BEFORE WRITING ANYTHING. `INSTRUCTIONS`
-// (2,477 chars) is passed to `new Server(..., { instructions })`, which puts it in the agent's
-// SYSTEM PROMPT. A system prompt is not part of the compactable transcript, so those rules are
-// present on every single turn and re-sending them would be the precise waste this file exists
-// to remove. Half of an earlier draft of this module did exactly that.
-//
-// THE PROXY, AND ITS HONEST LIMIT. There is no way to ask an agent what is still in its context.
-// Agent Relay's broker faces the same wall and answers it with a measurement it *does* have --
-// bytes of PTY output since the last reminder:
-//
-//     "Output volume is the proxy for 'the agent actually worked and may have compacted the
-//      earlier reminder out of its context'. An agent that only sat at the prompt receiving
-//      messages still has the previous reminder verbatim in context, so repeating it only
-//      burns tokens."                     -- crates/broker/src/broker/injection_format.rs
-//
-// There is no PTY here. The equivalent measurement is the one thing this server controls exactly:
-// BYTES IT HAS HANDED THE AGENT since the last send. Every tool result goes out through one
-// `text()`, so the count is precise rather than sampled.
-//
-// This is a proxy and nothing more. It does not detect compaction; it estimates that enough has
-// happened for compaction to be plausible. It will sometimes repeat something still in context,
-// and sometimes stay quiet about something already gone. Both failures are cheap. Pretending the
-// number means more than it does would not be.
-//
-// THREE RULES, IN PRIORITY ORDER, AND THE ORDER IS THE DESIGN:
-//
-//   1. never sent      -> SEND. They have not seen it.
-//   2. content changed -> SEND. Correctness outranks economy: a suppressed state change is a
-//                         wrong answer, while a repeated one is only a cost.
-//   3. otherwise       -> send only if BOTH the cooldown has elapsed AND enough bytes have gone
-//                         out. Either gate alone is wrong. Time alone nags an idle agent that
-//                         still has the text. Bytes alone fires mid-burst on an agent that read
-//                         it ninety seconds ago.
-
-/** Long enough that a burst of work does not trigger a repeat, short enough to catch a stall. */
-export const COOLDOWN_MS = 5 * 60000
-
-/** Agent Relay's number, and a reasonable one: ~16k tokens of traffic since they last saw it. */
-export const OUTPUT_BYTES = 64 * 1024
-
-/** Cheap, order-insensitive change detection. Not a hash -- a hash would be more code for a
- *  comparison that is already exact on the strings these callers pass. */
-const norm = (c) => (typeof c === 'string' ? c : JSON.stringify(c === undefined ? null : c))
-
-export function makeThrottle({ now = Date.now, cooldownMs = COOLDOWN_MS, bytes = OUTPUT_BYTES } = {}) {
-  // key -> { at, content, bytesSince, sends }
-  const seen = new Map()
-  let noted = 0        // total bytes handed to the agent, for reporting only
-
-  /**
-   * Record output handed to the agent.
-   *
-   * Counting for a key starts only once that key has been sent at least once -- the volume only
-   * means anything relative to "since you last saw this". Agent Relay makes the same choice and
-   * for the same reason; a counter running before the first send would make the first repeat fire
-   * immediately on a busy agent.
-   */
-  function note(n) {
-    const add = Math.max(0, Number(n) || 0)
-    noted += add
-    for (const e of seen.values()) e.bytesSince += add
-  }
-
-  function should(key, content) {
-    const e = seen.get(key)
-    if (!e) return { send: true, why: 'first' }
-    if (norm(content) !== e.content) return { send: true, why: 'changed' }
-    const waited = now() - e.at
-    if (waited < cooldownMs) return { send: false, why: 'recent', waited }
-    if (e.bytesSince < bytes) return { send: false, why: 'quiet', bytesSince: e.bytesSince }
-    return { send: true, why: 'likely-compacted', waited, bytesSince: e.bytesSince }
-  }
-
-  function sent(key, content) {
-    const prev = seen.get(key)
-    seen.set(key, { at: now(), content: norm(content), bytesSince: 0, sends: (prev ? prev.sends : 0) + 1 })
-  }
-
-  /** should() and sent() in one call, for the common site: `if (send(k, c)) include(c)`. */
-  function send(key, content) {
-    const d = should(key, content)
-    if (d.send) sent(key, content)
-    return d.send
-  }
-
-  /** What was actually saved, so the claim is measured rather than asserted. */
-  function stats() {
-    const out = { keys: {}, bytesHandled: noted }
-    for (const [k, e] of seen.entries()) out.keys[k] = { sends: e.sends, bytesSince: e.bytesSince }
-    return out
-  }
-
-  return { note, should, sent, send, stats }
-}
-
-/** Cheap enough to be worth repeating; says nothing an agent's system prompt already carries.
- *  Deliberately a POINTER, not a copy: the file is on the agent's own disk, and a second
- *  hand-written summary of it here would be one more description to drift. */
-export const RULES_NUDGE =
-  '[ROOM RULES] You have been working a while — the room rules you were handed when you joined ' +
-  'are probably out of your context by now. They are ROOM-specific (lanes, gate command, who ' +
-  'owns what), so the general rules you still have do not cover them. Re-read HIVE_RULES.md in ' +
-  'your own folder before your next claim.'
+// hive-throttle.js — say it again only if they can no longer see it.
+//
+// TWO OPPOSITE WASTES, ONE CAUSE. Hivecode repeats some blocks to an agent that still has them
+// verbatim, and never repeats others to an agent that lost them hours ago. Both are the same
+// missing question: *is this still in their context?*
+//
+//   [GLOBAL PROJECT STATE]   rebuilt and returned on EVERY hive_wait, unchanged, forever.
+//                            An agent waiting in a loop is handed the same JSON hundreds of
+//                            times, and pays for it hundreds of times.
+//
+//   HIVE_RULES.md            6,288 bytes handed over ONCE, in the hive_join tool result. It sits
+//                            in the transcript, so it is exactly what compaction throws away
+//                            first -- and it is the ROOM-specific half of the rules: lanes, gate
+//                            commands, who owns what. Six hours in, it is simply gone.
+//
+// WHAT IS *NOT* IN SCOPE, AND THIS WAS WORTH CHECKING BEFORE WRITING ANYTHING. `INSTRUCTIONS`
+// (2,477 chars) is passed to `new Server(..., { instructions })`, which puts it in the agent's
+// SYSTEM PROMPT. A system prompt is not part of the compactable transcript, so those rules are
+// present on every single turn and re-sending them would be the precise waste this file exists
+// to remove. Half of an earlier draft of this module did exactly that.
+//
+// THE PROXY, AND ITS HONEST LIMIT. There is no way to ask an agent what is still in its context.
+// Agent Relay's broker faces the same wall and answers it with a measurement it *does* have --
+// bytes of PTY output since the last reminder:
+//
+//     "Output volume is the proxy for 'the agent actually worked and may have compacted the
+//      earlier reminder out of its context'. An agent that only sat at the prompt receiving
+//      messages still has the previous reminder verbatim in context, so repeating it only
+//      burns tokens."                     -- crates/broker/src/broker/injection_format.rs
+//
+// There is no PTY here. The equivalent measurement is the one thing this server controls exactly:
+// BYTES IT HAS HANDED THE AGENT since the last send. Every tool result goes out through one
+// `text()`, so the count is precise rather than sampled.
+//
+// This is a proxy and nothing more. It does not detect compaction; it estimates that enough has
+// happened for compaction to be plausible. It will sometimes repeat something still in context,
+// and sometimes stay quiet about something already gone. Both failures are cheap. Pretending the
+// number means more than it does would not be.
+//
+// THREE RULES, IN PRIORITY ORDER, AND THE ORDER IS THE DESIGN:
+//
+//   1. never sent      -> SEND. They have not seen it.
+//   2. content changed -> SEND. Correctness outranks economy: a suppressed state change is a
+//                         wrong answer, while a repeated one is only a cost.
+//   3. otherwise       -> send only if BOTH the cooldown has elapsed AND enough bytes have gone
+//                         out. Either gate alone is wrong. Time alone nags an idle agent that
+//                         still has the text. Bytes alone fires mid-burst on an agent that read
+//                         it ninety seconds ago.
+
+/** Long enough that a burst of work does not trigger a repeat, short enough to catch a stall. */
+export const COOLDOWN_MS = 5 * 60000
+
+/** Agent Relay's number, and a reasonable one: ~16k tokens of traffic since they last saw it. */
+export const OUTPUT_BYTES = 64 * 1024
+
+/** Cheap, order-insensitive change detection. Not a hash -- a hash would be more code for a
+ *  comparison that is already exact on the strings these callers pass. */
+const norm = (c) => (typeof c === 'string' ? c : JSON.stringify(c === undefined ? null : c))
+
+export function makeThrottle({ now = Date.now, cooldownMs = COOLDOWN_MS, bytes = OUTPUT_BYTES } = {}) {
+  // key -> { at, content, bytesSince, sends }
+  const seen = new Map()
+  let noted = 0        // total bytes handed to the agent, for reporting only
+
+  /**
+   * Record output handed to the agent.
+   *
+   * Counting for a key starts only once that key has been sent at least once -- the volume only
+   * means anything relative to "since you last saw this". Agent Relay makes the same choice and
+   * for the same reason; a counter running before the first send would make the first repeat fire
+   * immediately on a busy agent.
+   */
+  function note(n) {
+    const add = Math.max(0, Number(n) || 0)
+    noted += add
+    for (const e of seen.values()) e.bytesSince += add
+  }
+
+  function should(key, content) {
+    const e = seen.get(key)
+    if (!e) return { send: true, why: 'first' }
+    if (norm(content) !== e.content) return { send: true, why: 'changed' }
+    const waited = now() - e.at
+    if (waited < cooldownMs) return { send: false, why: 'recent', waited }
+    if (e.bytesSince < bytes) return { send: false, why: 'quiet', bytesSince: e.bytesSince }
+    return { send: true, why: 'likely-compacted', waited, bytesSince: e.bytesSince }
+  }
+
+  function sent(key, content) {
+    const prev = seen.get(key)
+    seen.set(key, { at: now(), content: norm(content), bytesSince: 0, sends: (prev ? prev.sends : 0) + 1 })
+  }
+
+  /** should() and sent() in one call, for the common site: `if (send(k, c)) include(c)`. */
+  function send(key, content) {
+    const d = should(key, content)
+    if (d.send) sent(key, content)
+    return d.send
+  }
+
+  /** What was actually saved, so the claim is measured rather than asserted. */
+  function stats() {
+    const out = { keys: {}, bytesHandled: noted }
+    for (const [k, e] of seen.entries()) out.keys[k] = { sends: e.sends, bytesSince: e.bytesSince }
+    return out
+  }
+
+  return { note, should, sent, send, stats }
+}
+
+/** Cheap enough to be worth repeating; says nothing an agent's system prompt already carries.
+ *  Deliberately a POINTER, not a copy: the file is on the agent's own disk, and a second
+ *  hand-written summary of it here would be one more description to drift. */
+export const RULES_NUDGE =
+  '[ROOM RULES] You have been working a while — the room rules you were handed when you joined ' +
+  'are probably out of your context by now. They are ROOM-specific (lanes, gate command, who ' +
+  'owns what), so the general rules you still have do not cover them. Re-read HIVE_RULES.md in ' +
+  'your own folder before your next claim.'

package/hive-update.js

@@ -1,58 +1,58 @@
-// hive-update.js -- tells an agent, and through it its human, that a newer hivecode is out.
-//
-// WHY THIS EXISTS. `npx -y hivecode-mcp@latest setup` points agent apps at a runtime COPY
-// (~/.hivecode/runtime/<version>), which is what made starting fast, offline and free of npx.
-// It also means nothing updates any more: every start used to fetch @latest, and now an agent
-// stays on the version it was set up with until someone runs setup again. A room with mixed
-// builds is the one condition hive_join itself warns can lose data, so the gap must be visible.
-//
-// IT NEVER GETS IN THE WAY. The check starts with the server, carries a short timeout, and
-// hive_join and hive_status use whatever answer has arrived by then. A failed check says
-// nothing -- no network is not news. HIVE_PRIVATE=1 and HIVE_NO_UPDATE_CHECK=1 both switch it
-// off: a user who asked for privacy did not ask for a request to npm on every start.
-import { VERSION } from './hive-version.js'
-
-const REGISTRY_LATEST = 'https://registry.npmjs.org/hivecode-mcp/latest'
-
-/** True when version `a` is newer than `b` (x.y.z; anything unparseable is never "newer"). */
-export function newer(a, b) {
-  const parse = (v) => String(v).split('-')[0].split('.').map((n) => Number(n))
-  const pa = parse(a)
-  const pb = parse(b)
-  for (let i = 0; i < 3; i++) {
-    const x = pa[i] ?? 0
-    const y = pb[i] ?? 0
-    if (!Number.isFinite(x) || !Number.isFinite(y)) return false
-    if (x !== y) return x > y
-  }
-  return false
-}
-
-let latest = null
-let started = false
-
-export function startUpdateCheck({ fetchImpl = globalThis.fetch, timeoutMs = 4000, env = process.env } = {}) {
-  if (started) return
-  started = true
-  if (env.HIVE_NO_UPDATE_CHECK === '1' || env.HIVE_PRIVATE === '1' || typeof fetchImpl !== 'function') return
-  Promise.resolve()
-    // HIVE_UPDATE_URL exists for tests/update-notice-test.mjs, which serves a fake registry so the
-    // wiring is proven end to end through a real server process.
-    .then(() => fetchImpl(env.HIVE_UPDATE_URL || REGISTRY_LATEST, { signal: AbortSignal.timeout(timeoutMs), headers: { accept: 'application/json' } }))
-    .then((r) => (r && r.ok ? r.json() : null))
-    .then((j) => { if (j && typeof j.version === 'string') latest = j.version })
-    .catch(() => { /* offline, blocked, or slow: say nothing */ })
-}
-
-/** The line to show, or '' when this agent is current (or nobody knows yet). */
-export function updateNotice(current = VERSION, known = latest) {
-  if (!known || !newer(known, current)) return ''
-  return `UPDATE AVAILABLE: hivecode ${known} is out; this agent runs ${current}. Tell your human to run ` +
-    '`npx -y hivecode-mcp@latest setup` and reload this agent. Mixed versions in one room can lose data.'
-}
-
-export const _test = {
-  reset() { latest = null; started = false },
-  setLatest(v) { latest = v; started = true },
-  latest: () => latest,
-}
+// hive-update.js -- tells an agent, and through it its human, that a newer hivecode is out.
+//
+// WHY THIS EXISTS. `npx -y hivecode-mcp@latest setup` points agent apps at a runtime COPY
+// (~/.hivecode/runtime/<version>), which is what made starting fast, offline and free of npx.
+// It also means nothing updates any more: every start used to fetch @latest, and now an agent
+// stays on the version it was set up with until someone runs setup again. A room with mixed
+// builds is the one condition hive_join itself warns can lose data, so the gap must be visible.
+//
+// IT NEVER GETS IN THE WAY. The check starts with the server, carries a short timeout, and
+// hive_join and hive_status use whatever answer has arrived by then. A failed check says
+// nothing -- no network is not news. HIVE_PRIVATE=1 and HIVE_NO_UPDATE_CHECK=1 both switch it
+// off: a user who asked for privacy did not ask for a request to npm on every start.
+import { VERSION } from './hive-version.js'
+
+const REGISTRY_LATEST = 'https://registry.npmjs.org/hivecode-mcp/latest'
+
+/** True when version `a` is newer than `b` (x.y.z; anything unparseable is never "newer"). */
+export function newer(a, b) {
+  const parse = (v) => String(v).split('-')[0].split('.').map((n) => Number(n))
+  const pa = parse(a)
+  const pb = parse(b)
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] ?? 0
+    const y = pb[i] ?? 0
+    if (!Number.isFinite(x) || !Number.isFinite(y)) return false
+    if (x !== y) return x > y
+  }
+  return false
+}
+
+let latest = null
+let started = false
+
+export function startUpdateCheck({ fetchImpl = globalThis.fetch, timeoutMs = 4000, env = process.env } = {}) {
+  if (started) return
+  started = true
+  if (env.HIVE_NO_UPDATE_CHECK === '1' || env.HIVE_PRIVATE === '1' || typeof fetchImpl !== 'function') return
+  Promise.resolve()
+    // HIVE_UPDATE_URL exists for tests/update-notice-test.mjs, which serves a fake registry so the
+    // wiring is proven end to end through a real server process.
+    .then(() => fetchImpl(env.HIVE_UPDATE_URL || REGISTRY_LATEST, { signal: AbortSignal.timeout(timeoutMs), headers: { accept: 'application/json' } }))
+    .then((r) => (r && r.ok ? r.json() : null))
+    .then((j) => { if (j && typeof j.version === 'string') latest = j.version })
+    .catch(() => { /* offline, blocked, or slow: say nothing */ })
+}
+
+/** The line to show, or '' when this agent is current (or nobody knows yet). */
+export function updateNotice(current = VERSION, known = latest) {
+  if (!known || !newer(known, current)) return ''
+  return `UPDATE AVAILABLE: hivecode ${known} is out; this agent runs ${current}. Tell your human to run ` +
+    '`npx -y hivecode-mcp@latest setup` and reload this agent. Mixed versions in one room can lose data.'
+}
+
+export const _test = {
+  reset() { latest = null; started = false },
+  setLatest(v) { latest = v; started = true },
+  latest: () => latest,
+}

package/hive-version.js

@@ -1,59 +1,110 @@
-// hive-version.js — one place that knows what build this is.
-//
-// WHY THIS FILE EXISTS, and it is not tidiness.
-//
-// VERSION is load-bearing, not cosmetic. hive_join instructs every arriving agent to announce its
-// version in chat, because two clients running different builds in one room corrupt each other's
-// files with no error on either side — both writes succeed, both are green, and the disagreement
-// surfaces only as lost bytes. That announcement is the ONLY channel that makes a mixed build
-// visible from inside the room. So a version string is not a label; it is the input to the one
-// detector we have.
-//
-// On 20 Sep 2026 three entry points were found reporting a version package.json does not contain:
-// remote-mcp.js said '0.11.5' while live on the hosted relay, hive-mcp-http.js and hive-linear.js
-// both said '1.0.0'. hive-mcp.js had already been fixed months earlier, with a comment explaining
-// exactly why hardcoding it is dangerous — and that fix was never carried to the other three.
-// A detector that lies is strictly worse than no detector, because it is trusted.
-//
-// HIV-P7 closed that by giving each of the four files its own runtime read. Which produced the
-// next defect, and it was measured rather than predicted: with the reader duplicated four times,
-// corrupting ONE copy's fallback string to '9.9.9-DRIFTED' left tests/version-truth-test.mjs at
-// 16 passed, 0 failed. The property guards the version that gets REPORTED and says nothing about
-// the mechanism that produces it, so three of four copies could rot in silence.
-//
-// This codebase has watched that happen before. The extension's reconcile() and the engine's were
-// the same function once; they now share 34 lines and behave differently. Eight lines is not too
-// small to drift — it is exactly small enough that nobody feels the need to check.
-//
-// So the fix is DELETION, not another assertion. One definition, imported by all four. The
-// property becomes true by construction instead of by policing, and a fifth entry point written
-// next year gets it right by importing rather than by remembering.
-//
-// TWO DECISIONS WORTH KEEPING:
-//
-// It READS package.json rather than being told. package.json always ships beside these files —
-// in the repo and in the published tarball — so `new URL('./package.json', import.meta.url)`
-// resolves in both. Anything else (a constant, a build step, a generated file) can disagree with
-// the package the moment `npm version` runs, which is precisely the failure being fixed.
-//
-// IT NEVER THROWS. A version read is not worth a server that will not boot, and a server that
-// refuses to start is a worse outcome than one that says it does not know which build it is. So
-// an unreadable or malformed package.json yields '0.0.0-unknown' — a value that is obviously
-// wrong to a human, will never match a real release, and cannot be mistaken for a true answer.
-// Silence or an empty string could be read as "no mixed build here"; this cannot.
-
-import fs from 'fs'
-
-/** Recomputed never: a running process cannot change which build it is. */
-export const VERSION = (() => {
-  try {
-    const v = JSON.parse(fs.readFileSync(new URL('./package.json', import.meta.url), 'utf8')).version
-    if (typeof v === 'string' && v) return v
-  } catch { /* fall through — see IT NEVER THROWS above */ }
-  return '0.0.0-unknown'
-})()
-
-/** The sentinel, exported so callers and tests can name it instead of retyping the literal. */
-export const UNKNOWN_VERSION = '0.0.0-unknown'
-
-export default VERSION
+// hive-version.js — one place that knows what build this is.
+//
+// WHY THIS FILE EXISTS, and it is not tidiness.
+//
+// VERSION is load-bearing, not cosmetic. hive_join instructs every arriving agent to announce its
+// version in chat, because two clients running different builds in one room corrupt each other's
+// files with no error on either side — both writes succeed, both are green, and the disagreement
+// surfaces only as lost bytes. That announcement is the ONLY channel that makes a mixed build
+// visible from inside the room. So a version string is not a label; it is the input to the one
+// detector we have.
+//
+// On 20 Sep 2026 three entry points were found reporting a version package.json does not contain:
+// remote-mcp.js said '0.11.5' while live on the hosted relay, hive-mcp-http.js and hive-linear.js
+// both said '1.0.0'. hive-mcp.js had already been fixed months earlier, with a comment explaining
+// exactly why hardcoding it is dangerous — and that fix was never carried to the other three.
+// A detector that lies is strictly worse than no detector, because it is trusted.
+//
+// HIV-P7 closed that by giving each of the four files its own runtime read. Which produced the
+// next defect, and it was measured rather than predicted: with the reader duplicated four times,
+// corrupting ONE copy's fallback string to '9.9.9-DRIFTED' left tests/version-truth-test.mjs at
+// 16 passed, 0 failed. The property guards the version that gets REPORTED and says nothing about
+// the mechanism that produces it, so three of four copies could rot in silence.
+//
+// This codebase has watched that happen before. The extension's reconcile() and the engine's were
+// the same function once; they now share 34 lines and behave differently. Eight lines is not too
+// small to drift — it is exactly small enough that nobody feels the need to check.
+//
+// So the fix is DELETION, not another assertion. One definition, imported by all four. The
+// property becomes true by construction instead of by policing, and a fifth entry point written
+// next year gets it right by importing rather than by remembering.
+//
+// TWO DECISIONS WORTH KEEPING:
+//
+// It READS package.json rather than being told. package.json always ships beside these files —
+// in the repo and in the published tarball — so `new URL('./package.json', import.meta.url)`
+// resolves in both. Anything else (a constant, a build step, a generated file) can disagree with
+// the package the moment `npm version` runs, which is precisely the failure being fixed.
+//
+// IT NEVER THROWS. A version read is not worth a server that will not boot, and a server that
+// refuses to start is a worse outcome than one that says it does not know which build it is. So
+// an unreadable or malformed package.json yields '0.0.0-unknown' — a value that is obviously
+// wrong to a human, will never match a real release, and cannot be mistaken for a true answer.
+// Silence or an empty string could be read as "no mixed build here"; this cannot.
+
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+/** Recomputed never: a running process cannot change which build it is. */
+export const VERSION = (() => {
+  try {
+    const v = JSON.parse(fs.readFileSync(new URL('./package.json', import.meta.url), 'utf8')).version
+    if (typeof v === 'string' && v) return v
+  } catch { /* fall through — see IT NEVER THROWS above */ }
+  return '0.0.0-unknown'
+})()
+
+/** The sentinel, exported so callers and tests can name it instead of retyping the literal. */
+export const UNKNOWN_VERSION = '0.0.0-unknown'
+
+// BUILD: WHICH COMMIT, not just which version (29 Sep 2026).
+//
+// VERSION alone could not see a mixed build. On 28-29 Sep release-gate HEAD and the published
+// tarball both said "0.12.2" while differing by a night of fixes, and the hosted relay's /health
+// reported no version at all -- "is the fix deployed?" was answered from its uptime. So a build
+// carries its commit when it knows one:
+//   RENDER_GIT_COMMIT  set by Render for a deployed relay (its image has no .git)
+//   a git checkout     .git beside package.json: a folder, or a worktree's `gitdir:` file
+//   otherwise ''       an npm install: VERSION is the whole identity, and it is the true one
+// VERSION itself is untouched -- the update notice compares it with the registry's -- so the
+// commit travels separately, and VERSION_LABEL is what people and agents are shown.
+//
+// It never walks UP. hivecode-mcp installed into someone's repo would otherwise report THAT repo's
+// commit as its own build, which is the lie this exists to prevent. And like VERSION it never throws.
+const HEX = /^[0-9a-f]{7,40}$/
+export function buildOf(root, env = process.env) {
+  try {
+    const rc = String(env.RENDER_GIT_COMMIT || '').trim().toLowerCase()
+    if (HEX.test(rc)) return rc.slice(0, 7)
+    const dotGit = path.join(root, '.git')
+    let gitDir = dotGit
+    if (fs.statSync(dotGit).isFile()) { // a worktree: ".git" is a file holding "gitdir: <path>"
+      const m = /^gitdir:\s*(.+?)\s*$/m.exec(fs.readFileSync(dotGit, 'utf8'))
+      if (!m) return ''
+      gitDir = path.resolve(root, m[1])
+    }
+    const head = fs.readFileSync(path.join(gitDir, 'HEAD'), 'utf8').trim()
+    if (/^[0-9a-f]{40}$/.test(head)) return head.slice(0, 7) // detached
+    const ref = /^ref:\s*(\S+)$/.exec(head)
+    if (!ref) return ''
+    let common = gitDir // a worktree keeps its branches in the main repo's .git
+    try { common = path.resolve(gitDir, fs.readFileSync(path.join(gitDir, 'commondir'), 'utf8').trim()) } catch { }
+    for (const d of [gitDir, common]) {
+      try { const h = fs.readFileSync(path.join(d, ref[1]), 'utf8').trim(); if (/^[0-9a-f]{40}$/.test(h)) return h.slice(0, 7) } catch { }
+    }
+    for (const line of fs.readFileSync(path.join(common, 'packed-refs'), 'utf8').split('\n')) {
+      const [h, r] = line.trim().split(/\s+/)
+      if (r === ref[1] && /^[0-9a-f]{40}$/.test(h)) return h.slice(0, 7)
+    }
+  } catch { /* no .git, unreadable, malformed: no commit to report -- see IT NEVER THROWS */ }
+  return ''
+}
+
+/** This build's commit, or '' when it has none to report (an npm install). */
+export const BUILD = buildOf(fileURLToPath(new URL('.', import.meta.url)))
+
+/** What people and agents are shown: "0.12.2+fe1d89e" from a checkout, "0.12.2" from npm. */
+export const VERSION_LABEL = BUILD ? `${VERSION}+${BUILD}` : VERSION
+
+export default VERSION