hivecode-mcp 0.14.0 → 0.14.2

package/hive-secrets.js

@@ -1,89 +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})`
-}
+// 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

@@ -1,114 +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 }
-}
+// 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 }
+}