hivecode-mcp 0.12.2 → 0.13.0

package/hive-room-key.js

@@ -0,0 +1,209 @@
+// PERSONAL ROOMS (8 Oct 2026): a room that only the people its host invites can enter.
+//
+// The relay already enforces this for any room whose id is "hs_<fp>_<rand>". fp is a fingerprint of
+// the host's public key, every token for the room carries that key, and only the matching private
+// key can sign one (server.js authorize). So a stranger holding the room's name gets nothing, even
+// on the open public relay. What was missing was a way for an AGENT to make such a room: until now
+// only the VS Code extension could, holding the key in the editor's secret storage.
+//
+// THE KEY NEVER LIVES IN A ROOM FOLDER. It sits in ~/.hivecode/keys/<room>.json, outside every
+// folder the sync engine shares, so no client -- old, new or misconfigured -- can publish it.
+// Whoever holds that file owns the room: lose it and nobody can invite again; copy it and the copy
+// can invite too.
+//
+// INVITES ARE A COMMAND, NOT A TOOL. Every tool definition is paid on every request by every agent
+// (tests/token-budget-test.mjs holds that to 3,500 tokens), so inviting -- something a host does a
+// few times a week -- is `hivecode-mcp invite <name>`, run by the person or by an agent that has a
+// shell. One link per person, carrying a token minted for them alone: an invite IS that person,
+// which is why it is never pasted into the room chat (hive_say refuses tokens).
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+import crypto from 'crypto'
+import { sign, decodeUnsafe, keyFingerprint, roomFingerprint, isSecuredRoom, makeSecuredRoomId } from './token.js'
+import { validateMemberName } from './hive-mailbox.js'
+
+export const keysDir = () => process.env.HIVE_KEYS_DIR || path.join(os.homedir(), '.hivecode', 'keys')
+const keyFile = (room) => path.join(keysDir(), `${room}.json`)
+const DAY = 86400
+const nowSec = () => Math.floor(Date.now() / 1000)
+
+/** A new personal room, in memory only: nothing is written until the join is allowed to go ahead. */
+export function newPersonalRoom() {
+  const kp = crypto.generateKeyPairSync('rsa', { modulusLength: 2048 })
+  const publicKey = kp.publicKey.export({ type: 'spki', format: 'pem' })
+  const privateKey = kp.privateKey.export({ type: 'pkcs8', format: 'pem' })
+  return { room: makeSecuredRoomId(publicKey, crypto.randomBytes(6).toString('hex')), publicKey, privateKey }
+}
+
+export function saveRoomKey(k, { relay, host }) {
+  fs.mkdirSync(keysDir(), { recursive: true, mode: 0o700 })
+  const rec = { room: k.room, relay, host, publicKey: k.publicKey, privateKey: k.privateKey, created: Date.now(), invites: [] }
+  // 'wx': a fresh room never overwrites a key that exists, which would orphan the room it opened.
+  fs.writeFileSync(keyFile(k.room), JSON.stringify(rec, null, 2), { mode: 0o600, flag: 'wx' })
+  return rec
+}
+
+/** The key record for a personal room this machine hosts, or null. A file whose key does not match
+ *  the room's fingerprint is treated as absent: it would only mint tokens the relay refuses. */
+export function loadRoomKey(room) {
+  if (!isSecuredRoom(room)) return null
+  try {
+    const rec = JSON.parse(fs.readFileSync(keyFile(room), 'utf8'))
+    return rec && rec.privateKey && keyFingerprint(rec.publicKey) === roomFingerprint(room) ? rec : null
+  } catch { return null }
+}
+const writeRec = (rec) => fs.writeFileSync(keyFile(rec.room), JSON.stringify(rec, null, 2), { mode: 0o600 })
+
+/** The same claims the extension mints (extension.js mintToken), so either can host and the relay
+ *  cannot tell them apart. paths = what they may SEE; writePaths = the part of it they may EDIT. */
+export function mintRoomToken(rec, { name, kind = 'ai', role = 'writer', paths, writePaths, owner, ttlSec = 7 * DAY }) {
+  const now = nowSec()
+  const jti = 'jti-' + crypto.randomBytes(9).toString('base64url')
+  const payload = {
+    iss: 'hivecode', sub: name, name, kind, ...(owner ? { owner } : {}),
+    pk: rec.publicKey, // self-certifying: the relay binds this key to the room id
+    scopes: [{ room: rec.room, role, ...(paths && paths.length ? { paths } : {}), ...(writePaths && writePaths.length ? { writePaths } : {}) }],
+    iat: now, exp: now + ttlSec, jti,
+  }
+  return { token: sign(payload, { privateKey: rec.privateKey }), jti, exp: payload.exp }
+}
+
+/** The host's own token, minted afresh when it is missing or within an hour of running out: the host
+ *  holds the key, so its own access must never lapse. Only for the name the room was hosted under --
+ *  another participant on this machine, joining with its own invite, keeps its own narrower grant. */
+export function hostToken(room, name, current, { kind = 'ai', owner = '' } = {}) {
+  const rec = loadRoomKey(room)
+  if (!rec || rec.host !== name) return current
+  const p = current ? decodeUnsafe(current) : null
+  const fresh = !!(p && p.sub === name && p.exp > nowSec() + 3600 && p.pk && keyFingerprint(p.pk) === roomFingerprint(room))
+  return fresh ? current : mintRoomToken(rec, { name, kind, role: 'maintainer', owner, ttlSec: 30 * DAY }).token
+}
+
+// A path a token may name: relative, no "..", no drive or root. Globs are fine ("src/**", "!**/*.env").
+function badPath(g) {
+  const s = String(g).replace(/^!/, '')
+  return !s || s.length > 200 || /^([A-Za-z]:|[\\/])/.test(s) || /(^|[\\/])\.\.([\\/]|$)/.test(s) || /[\x00-\x1f]/.test(s)
+}
+const list = (v) => (v == null || v === true ? [] : String(v).split(',').map((s) => s.trim()).filter(Boolean))
+const when = (sec) => new Date(sec * 1000).toISOString().slice(0, 10)
+
+function whatTheyGet(i) {
+  const see = i.paths && i.paths.length ? i.paths.join(', ') : 'every file in the room'
+  const edit = i.role === 'reader' ? 'read only' : i.writePaths && i.writePaths.length ? `may edit ${i.writePaths.join(', ')}` : 'may edit what they see'
+  return `${i.kind}, ${i.role}: sees ${see}; ${edit}`
+}
+
+/** Make one person's invite. Returns { ok, text, link?, jti? }. */
+export function makeInvite({ room, relay, name, kind = 'ai', reader = false, paths = [], writePaths = [], days = 7, owner = '' }) {
+  const rec = loadRoomKey(room)
+  if (!rec) {
+    return { ok: false, text: isSecuredRoom(room)
+      ? `Only the machine that hosted this personal room can invite people to it, and this one does not hold its key (${keysDir()}). Ask the host.`
+      : `Room ${room} is open: anyone with its link can join, so there is nothing to invite into. For a room only invited people can enter, host one with hive_join and private: true.` }
+  }
+  const nc = validateMemberName(name)
+  if (!nc.ok) return { ok: false, text: `${nc.error}\nNothing was minted.` }
+  if (name === rec.host) return { ok: false, text: `"${name}" is the host of this room. Pick the invitee's own name.\nNothing was minted.` }
+  const bad = [...paths, ...writePaths].filter(badPath)
+  if (bad.length) return { ok: false, text: `These paths cannot go in an invite (they must be relative, with no ".."): ${bad.join(', ')}\nNothing was minted.` }
+  const d = Number(days)
+  if (!Number.isFinite(d) || d <= 0 || d > 30) return { ok: false, text: `--days must be between 1 and 30 (got ${days}). A short invite is one you never have to remember to take back.\nNothing was minted.` }
+  const k = kind === 'human' ? 'human' : 'ai'
+  const role = reader ? 'reader' : 'writer'
+  const { token, jti, exp } = mintRoomToken(rec, { name, kind: k, role, paths, writePaths, owner, ttlSec: Math.round(d * DAY) })
+  const inv = { jti, name, kind: k, role, paths: paths.length ? paths : null, writePaths: writePaths.length ? writePaths : null, exp, at: Date.now() }
+  rec.invites = [...(rec.invites || []), inv]
+  writeRec(rec)
+  const link = `${relay || rec.relay}|${room}|${token}`
+  const text = `INVITE for ${name} (${whatTheyGet(inv)}), until ${when(exp)}.
+Send it to ${name} directly, never in the room chat: whoever holds this link joins as ${name}.
+
+  Join my Hivecode room. In a terminal, run this once (needs Node.js 18+), then do what it prints:
+    npx -y hivecode-mcp@latest setup "${link}"
+
+Take it back any time: npx -y hivecode-mcp@latest revoke ${name}`
+  return { ok: true, text, link, jti }
+}
+
+const httpBase = (relay) => String(relay).replace(/^ws(s?):\/\//i, 'http$1://').replace(/\/+$/, '')
+
+/** Take back every live invite for a name. The relay refuses those tokens from then on and closes any
+ *  connection using them. Returns { ok, text }. */
+export async function revokeInvite({ room, relay, name }) {
+  const rec = loadRoomKey(room)
+  if (!rec) return { ok: false, text: `This machine does not host room ${room}, so it cannot take invites back. Only the host can.` }
+  const live = (rec.invites || []).filter((i) => i.name === name && !i.revokedAt)
+  if (!live.length) {
+    const names = [...new Set((rec.invites || []).filter((i) => !i.revokedAt).map((i) => i.name))]
+    return { ok: false, text: `No live invite for "${name}" in this room.${names.length ? ` Invited: ${names.join(', ')}.` : ' Nobody has been invited yet.'}` }
+  }
+  const owner = mintRoomToken(rec, { name: rec.host, role: 'maintainer', ttlSec: 600 }).token
+  let done = 0, dropped = 0
+  const failures = []
+  for (const i of live) {
+    try {
+      const r = await fetch(`${httpBase(relay || rec.relay)}/__hive/revoke`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ room, token: owner, jti: i.jti }) })
+      const body = await r.json().catch(() => ({}))
+      if (r.ok && body.ok) { i.revokedAt = Date.now(); done++; dropped += Number(body.dropped) || 0 }
+      else failures.push(`HTTP ${r.status}${body.error ? ` ${body.error}` : ''}`)
+    } catch (e) { failures.push(e.message) }
+  }
+  writeRec(rec)
+  if (!done) return { ok: false, text: `Could not reach the relay to revoke ${name}'s invite (${failures.join('; ')}). Nothing changed; try again.` }
+  return { ok: true, text: `Revoked ${done} invite(s) for ${name}. The relay refuses them from now on${dropped ? `, and closed ${dropped} connection(s) using them` : ''}.${failures.length ? `\n${failures.length} more could not be revoked (${failures.join('; ')}); run this again.` : ''}` }
+}
+
+// ---- the command line: hivecode-mcp invite <name> ... | hivecode-mcp revoke <name> ----
+
+function parseArgs(argv) {
+  const o = { _: [] }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (!a.startsWith('--')) { o._.push(a); continue }
+    const key = a.slice(2)
+    if (['reader', 'human'].includes(key)) o[key] = true
+    else o[key] = argv[++i]
+  }
+  return o
+}
+
+// Which room: --dir's .hive.json, else this folder's, else the only room this machine hosts.
+function findRoom(o) {
+  const dir = path.resolve(o.dir || '.')
+  try {
+    const c = JSON.parse(fs.readFileSync(path.join(dir, '.hive.json'), 'utf8'))
+    if (c && c.room) return { room: c.room, relay: c.relay || '' }
+  } catch { /* not a room folder */ }
+  let mine = []
+  try { mine = fs.readdirSync(keysDir()).filter((f) => f.endsWith('.json')).map((f) => loadRoomKey(f.slice(0, -5))).filter(Boolean) } catch { /* no keys yet */ }
+  if (mine.length === 1) return { room: mine[0].room, relay: mine[0].relay }
+  return { error: mine.length
+    ? `${dir} is not a room folder, and this machine hosts ${mine.length} personal rooms. Say which with --dir <the room's folder>:\n${mine.map((r) => `  ${r.room}  (host ${r.host}, created ${new Date(r.created).toISOString().slice(0, 10)})`).join('\n')}`
+    : `${dir} is not a room folder, and this machine hosts no personal room. Host one first: hive_join with private: true.` }
+}
+
+const USAGE = `Usage:
+  hivecode-mcp invite <name> [--reader] [--human] [--paths a,b] [--edit a,b] [--days 7] [--owner <their human>] [--dir <room folder>]
+  hivecode-mcp revoke <name> [--dir <room folder>]
+
+  --reader   they can read but not edit       --paths  only these folders/globs are visible to them
+  --human    the invitee is a person, not AI  --edit   of what they see, only these may be edited
+  --days     how long the invite lasts (default 7, at most 30)`
+
+export async function main(argv) {
+  const cmd = argv[0]
+  const o = parseArgs(argv.slice(1))
+  const name = o._[0]
+  if (!name) { console.log(USAGE); return 2 }
+  const where = findRoom(o)
+  if (where.error) { console.log(where.error); return 1 }
+  if (cmd === 'revoke') {
+    const r = await revokeInvite({ room: where.room, relay: where.relay, name })
+    console.log(r.text)
+    return r.ok ? 0 : 1
+  }
+  const r = makeInvite({ room: where.room, relay: where.relay, name, kind: o.human ? 'human' : 'ai', reader: !!o.reader, paths: list(o.paths), writePaths: list(o.edit), days: o.days == null ? 7 : o.days, owner: o.owner || '' })
+  console.log(r.text)
+  return r.ok ? 0 : 1
+}

package/hive-secrets.js

@@ -0,0 +1,89 @@
+// LIVE CREDENTIALS ARE NOT SENT TO THE ROOM (3 Oct 2026).
+//
+// A file in a room goes to the relay and to every participant's disk. ALWAYS_IGNORE keeps the
+// files that are secrets by NAME at home (.env, *.pem, id_rsa, ...), but a secret inside an
+// ordinary file went out with it: an agent that pastes an API key into config.js to try
+// something shares that key with everyone in the room, and with whoever runs the relay.
+//
+// So a file whose content holds a credential the room does not already have is held on this
+// machine (see sync.js, withheld) until the credential is moved out. Only formats a provider
+// stamps on its keys are matched -- a fixed prefix plus enough random characters -- and private
+// key blocks. Nothing here guesses from entropy alone: a false match holds back real work, and
+// the people who hit it would be right to switch this off.
+//
+// The matched value never leaves this module's callers in any form: not in a log line, not in
+// the room, not in status. Only its kind and its line number do.
+
+const PATTERNS = [
+  { kind: 'private key', re: /-----BEGIN (?:[A-Z0-9]+ ){0,3}PRIVATE KEY(?: BLOCK)?-----/g },
+  { kind: 'AWS access key', re: /\b(?:AKIA|ASIA|ABIA|ACCA)[A-Z0-9]{16}\b/g },
+  { kind: 'GitHub token', re: /\b(?:gh[pousr]_[A-Za-z0-9]{36}|github_pat_[A-Za-z0-9_]{60,100})\b/g },
+  { kind: 'GitLab token', re: /\bglpat-[A-Za-z0-9_-]{20,}\b/g },
+  { kind: 'Slack token', re: /\bxox[abposr]-[0-9]{6,}-[0-9A-Za-z-]{10,}/g },
+  { kind: 'Slack webhook', re: /hooks\.slack\.com\/services\/T[A-Z0-9]{6,}\/B[A-Z0-9]{6,}\/[A-Za-z0-9]{20,}/g },
+  { kind: 'Stripe live key', re: /\b[rs]k_live_[A-Za-z0-9]{20,}\b/g },
+  { kind: 'OpenAI API key', re: /\bsk-(?:proj-|svcacct-|admin-)?[A-Za-z0-9_-]{16,}T3BlbkFJ[A-Za-z0-9_-]{16,}/g },
+  { kind: 'Anthropic API key', re: /\bsk-ant-(?:api|admin|oat)\d{2}-[A-Za-z0-9_-]{60,}/g },
+  { kind: 'npm token', re: /\bnpm_[A-Za-z0-9]{36}\b/g },
+  { kind: 'Hugging Face token', re: /\bhf_[A-Za-z0-9]{30,40}\b/g },
+  { kind: 'Groq API key', re: /\bgsk_[A-Za-z0-9]{40,60}\b/g },
+  { kind: 'SendGrid API key', re: /\bSG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}\b/g },
+  { kind: 'DigitalOcean token', re: /\bdo[opr]_v1_[a-f0-9]{64}\b/g },
+  // .npmrc and friends: a registry password or token written out literally. `${NPM_TOKEN}` is the
+  // documented way to keep one out of the file, so a reference to the environment is not a secret.
+  { kind: 'registry credential', re: /(?:^|\n)[ \t]*(?:\/\/[^\s=]+:)?_(?:authToken|auth|password)[ \t]*=[ \t]*(?!\$\{)[^\s'"]{8,}/g },
+]
+
+// Documentation and tests are full of keys that look real and are not: AWS's own example id,
+// and placeholders like sk_live_XXXXXXXXXXXXXXXXXXXXXXXX. A provider's key is random, so a match
+// with few distinct characters, or that says it is an example, is a placeholder.
+const PLACEHOLDER = /EXAMPLE|example|XXXX|xxxx|0{8}|1234567890|your[_-]?(?:key|token|secret)/i
+function placeholder(value, kind) {
+  if (kind === 'private key' || kind === 'registry credential') return false
+  if (PLACEHOLDER.test(value)) return true
+  return new Set(value).size < 10
+}
+
+// A SIGNED ACCESS TOKEN -- a JWT, which is what Hivecode's own room tokens are -- is a person: whoever
+// holds it joins as them, with their access. It is kept out of the room's chat and tasks
+// ({ tokens: true }). It is NOT a reason to hold a FILE back: auth code and its tests are full of
+// sample tokens, most of them expired or fake, and holding each such file would stop real work.
+export const TOKEN_PATTERNS = [
+  { kind: 'access token', re: /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{16,}/g },
+]
+
+/** Every credential in `text`: [{ kind, line, value }]. `value` is for comparing, never for showing.
+ *  `tokens: true` adds signed access tokens, for what goes into the room's chat and tasks. */
+export function findSecrets(text, { tokens = false } = {}) {
+  const s = String(text || '')
+  if (!s) return []
+  const out = []
+  for (const { kind, re } of tokens ? [...PATTERNS, ...TOKEN_PATTERNS] : PATTERNS) {
+    re.lastIndex = 0
+    let m
+    while ((m = re.exec(s)) !== null) {
+      const value = m[0].replace(/^\s+/, '')
+      if (!placeholder(value, kind)) {
+        const at = m.index + (m[0].length - m[0].replace(/^\s+/, '').length)
+        out.push({ kind, line: s.slice(0, at).split('\n').length, value })
+      }
+      if (m[0].length === 0) re.lastIndex++
+    }
+  }
+  return out.sort((a, b) => a.line - b.line)
+}
+
+/** Credentials in `local` that `shared` does not already contain: what sharing `local` would leak. */
+export function newSecrets(local, shared) {
+  const found = findSecrets(local)
+  if (!found.length) return []
+  const room = String(shared || '')
+  return found.filter((f) => !room.includes(f.value))
+}
+
+/** "an OpenAI API key (line 12)" -- the only form a finding is ever shown in. */
+export function describeSecret(f) {
+  if (!f) return ''
+  const a = /^(?:[aeiou]|npm\b)/i.test(f.kind) ? 'an' : 'a'
+  return `${a} ${f.kind} (line ${f.line})`
+}

package/hive-session.js

@@ -0,0 +1,114 @@
+// hive-session.js -- which agent this is, on disk, for the folder its app started it in.
+//
+// The MCP server records its session in <launch folder>/.hive-mcp-session.json, so a restart rejoins
+// as the same agent; the Stop hook, which runs in the same launch folder, reads it to learn which
+// agent it is guarding.
+//
+// WHY THIS IS A MODULE. Until 9 Oct 2026 that file held ONE agent. Two agents started from one folder
+// -- two Claude Code sessions in one repo, the obvious way to run a branch room -- overwrote each
+// other, and the last writer was the only agent on record. The other one's Stop hook then steered it
+// as the wrong agent (that agent's mail, a listener under that agent's name), and a restart brought
+// it back as the other one. Found by walking the founder flow end to end (branch -> two agents ->
+// pr), where the file also showed up in the developer's `git status`.
+//
+// Now the file keeps every agent started in that folder, each with the pid of the server that wrote
+// it. Its top level is still the latest writer, which is all a Stop hook from before this reads, so an
+// older hook keeps working exactly as it did. Server and hook read it through this one module, so
+// the two cannot drift apart (the merge logic once lived twice, and the copies did).
+import fs from 'fs'
+import path from 'path'
+import { spawnSync } from 'child_process'
+
+export const SESSION_FILE_NAME = '.hive-mcp-session.json'
+export const HOOK_STATE_NAME = '.hive-stop-hook.json'
+const STALE_MS = 14 * 24 * 3600 * 1000 // a record whose server is gone and that nobody wrote for two weeks
+
+export function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false
+  try { process.kill(pid, 0); return true } catch (e) { return !!e && e.code === 'EPERM' }
+}
+
+/** Every agent on record in a session file, by name. A file from before 9 Oct holds one, at its top level. */
+export function readAgents(file) {
+  let raw
+  try { raw = JSON.parse(fs.readFileSync(file, 'utf8')) } catch { return {} }
+  if (!raw || typeof raw !== 'object') return {}
+  if (raw.agents && typeof raw.agents === 'object') return { ...raw.agents }
+  if (raw.name) { const one = { ...raw }; delete one.agents; return { [raw.name]: one } }
+  return {}
+}
+
+/** Write the records back; the top level is `latest` (or the newest record), for a Stop hook from before 9 Oct. */
+export function writeAgents(file, agents, latest = null) {
+  const now = Date.now()
+  for (const [n, s] of Object.entries(agents)) if (!pidAlive(s.pid) && s.at && now - s.at > STALE_MS) delete agents[n]
+  const names = Object.keys(agents)
+  if (!names.length) { try { fs.rmSync(file) } catch { } return }
+  const top = latest && agents[latest.name] === latest ? latest
+    : agents[names.sort((a, b) => (agents[b].at || 0) - (agents[a].at || 0))[0]]
+  fs.writeFileSync(file, JSON.stringify({ ...top, agents }))
+}
+
+/** The record this server process owns: the one it wrote; else the one for its conversation; else, after
+ *  a restart, the only one whose server is gone. Two gone is a guess, and a guess here is exactly how one
+ *  agent wakes up as another, so it answers null and the agent rejoins by name instead. */
+export function ownRecord(agents, { pid = process.pid, conv = '' } = {}) {
+  const all = Object.values(agents)
+  const mine = all.find((s) => s.pid === pid) || (conv ? all.find((s) => s.conv === conv) : null)
+  if (mine) return mine
+  const gone = all.filter((s) => !pidAlive(s.pid))
+  return gone.length === 1 ? gone[0] : null
+}
+
+/** Which agent a Stop hook is guarding. One on record is that one. With several, the hook's own
+ *  conversation decides: its id, else its transcript (the hive_join that answered "folder: <dir>",
+ *  then that folder anywhere in it), else the only one whose server still runs. If none of that
+ *  tells, null: a hook that speaks as the wrong agent does more harm than one that stays quiet. */
+export function agentForHook(agents, hook = {}, { readTail = tailOf } = {}) {
+  const all = Object.values(agents).filter((s) => s && s.dir && s.name)
+  if (all.length <= 1) return all[0] || null
+  const conv = String(hook.session_id || hook.conversationId || '')
+  if (conv) { const byConv = all.find((s) => s.conv && s.conv === conv); if (byConv) return byConv }
+  const t = hook.transcript_path ? readTail(hook.transcript_path) : ''
+  if (t) {
+    // The folder as a transcript line spells it: escaped once as JSON, twice if the text was nested.
+    const spell = (dir) => { const once = JSON.stringify(String(dir)).slice(1, -1); return [once, JSON.stringify(once).slice(1, -1)] }
+    const where = (s) => {
+      const forms = spell(s.dir)
+      const joined = Math.max(...forms.map((f) => t.lastIndexOf('folder: ' + f)))
+      return joined >= 0 ? [1, joined] : [0, Math.max(...forms.map((f) => t.lastIndexOf(f)))]
+    }
+    const ranked = all.map((s) => ({ s, w: where(s) })).filter((x) => x.w[1] >= 0)
+      .sort((a, b) => b.w[0] - a.w[0] || b.w[1] - a.w[1])
+    if (ranked.length) return ranked[0].s
+  }
+  const live = all.filter((s) => pidAlive(s.pid))
+  return live.length === 1 ? live[0] : null
+}
+
+function tailOf(file, max = 8 * 1024 * 1024) {
+  try {
+    const size = fs.statSync(file).size
+    const n = Math.min(size, max)
+    const fd = fs.openSync(file, 'r')
+    try { const b = Buffer.alloc(n); fs.readSync(fd, b, 0, n, size - n); return b.toString('utf8') } finally { fs.closeSync(fd) }
+  } catch { return '' }
+}
+
+/** Keep our files out of `git status` in the launch folder, which is often the developer's own repo:
+ *  listed in that repo's local exclude file (.git/info/exclude), never in a tracked .gitignore. */
+export function excludeFromGit(dir, names = [SESSION_FILE_NAME, HOOK_STATE_NAME]) {
+  try {
+    const r = spawnSync('git', ['rev-parse', '--git-path', 'info/exclude'], { cwd: dir, encoding: 'utf8', windowsHide: true, timeout: 5000 })
+    if (r.status !== 0 || !String(r.stdout || '').trim()) return false
+    const file = path.resolve(dir, String(r.stdout).trim())
+    let have = ''
+    try { have = fs.readFileSync(file, 'utf8') } catch { }
+    const listed = new Set(have.split(/\r?\n/).map((l) => l.trim()))
+    const add = names.filter((n) => !listed.has(n) && !listed.has('/' + n))
+    if (!add.length) return true
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.appendFileSync(file, `${have && !have.endsWith('\n') ? '\n' : ''}# Hivecode's local session files\n${add.join('\n')}\n`)
+    return true
+  } catch { return false }
+}