hivecode-mcp 0.13.0 → 0.13.1

package/docs/GITHUB_WORKFLOW.md

@@ -164,6 +164,66 @@ Notifications are optional: one Slack or Discord webhook URL. They are sent when
 
 Nothing is sent for each comment.
 
+## Room mode: multi-agent issues in a shared room
+
+Room Mode hands labelled issues directly to agents already collaborating in a shared room bound to a branch.
+Rather than spinning up isolated single-agent runs, the room's agents claim files, build, and review each other concurrently.
+When work is complete and reviewed, Hivecode runs the project tests and opens or updates a single pull request.
+
+### Setup
+
+1. **Bind a room to a branch:**
+   ```bash
+   npx -y hivecode-mcp@latest branch <branch-name>
+   ```
+   This creates or binds a branch room on the relay and prints its join link (`wss://...|room-...`).
+
+2. **Agents join the room:**
+   Connect your agents (Claude Code, Codex, Antigravity, or human developers) into the room using `hive_join` or the room link. Each agent gets its own workspace folder and display name.
+
+3. **Start the room watcher:**
+   ```bash
+   npx -y hivecode-mcp@latest github start --room "<room link>" [--fallback-agent "<command>"] [--ack-minutes 10]
+   ```
+   The watcher polls GitHub for labelled issues and manages task dispatch and landings for that room.
+
+### What the person sees on GitHub
+
+Every event is posted in order on the issue or the pull request. Room identifiers and relay URLs are never posted on GitHub.
+
+| event | where | what you see |
+|---|---|---|
+| Issue labelled `hivecode` | Issue comment | `Sent to room for branch <name>. In the room now: <agents>` (lists active agents and humans separately; skips passive bots). |
+| Tests fail during landing | Issue comment | `tests failed, sent back to the room (attempt 1 of 2)`. The failing test output is posted as a task into the room. Unchanged code is not re-tested. |
+| Work complete and reviewed | Pull request opened | PR titled after the issue (`<Title> (#1)`), body with `Closes #1`, summary of changed files, test verification (`Tests: npm test passed on <sha>, the exact commit pushed`), and one commit per author. |
+| Issue updated with PR | Issue comment | `landed as PR #N` linking the pull request. |
+| PR review feedback | PR comment & Room task | Comments on the PR become a single room task naming the blamed author (`Sent 1 review comment to the agents`). When fixed and reviewed, fixes are pushed to the same PR (`fixes pushed`). |
+| Unresponsive or stuck | Issue comment & Label | If `--max-minutes` passes or retries exhaust (`--max-runs`), the issue is labelled `hivecode:needs-human` with the last room transcript lines. |
+
+### `/hivecode stop` and `/hivecode retry`
+
+- **/hivecode stop:** A comment starting with `/hivecode stop` on the issue or PR stops work immediately. It works mid-work: the room is notified, the active task is withdrawn, and nothing lands. A stop from someone who cannot push, or from before the run started, is ignored.
+- **/hivecode retry:** A comment starting with `/hivecode retry` re-queues the issue. The watcher increments the attempt number and posts a new task (`Issue #12 (attempt 2): <title>`), matching the updated attempt so the room receives the retry cleanly without duplicate task suppression.
+
+### Fallback agent and token cost
+
+- **Opt-in only:** `--fallback-agent "<command>"` is strictly opt-in. Unattended agents never run unless explicitly configured.
+- **Reachability & engagement gate:** If reachable agents are present in the room when an issue arrives, no fallback starts before `--ack-minutes` (default 10). If any agent engages (claims a file or chats intent), fallback is prevented. If 0 reachable agents exist at post time, fallback spawns immediately.
+- **Budget caps:** Fallback runs are counted against `--max-runs-per-day` (default 20 across the repo) and run at most once per issue. When the daily limit is reached, no fallback spawns, and an issue comment notes that the limit was reached.
+
+### The review rule and lone-agent waiver
+
+- **Non-writer review required:** A task marked done will not land until a non-writer agent submits a passing review (`hive_review({ files, verdict: 'pass' })`). Reviews authored by contributors to the current held files are ignored.
+- **Lone-agent waiver:** If only one agent is present in the room and no second agent arrives before `--ack-minutes` (default 10), Hivecode waives the second-agent requirement and lands the PR.
+- **PR waiver notice:** The PR body explicitly states: `"not reviewed by a second agent"`, making the single-agent status transparent to human reviewers on GitHub. A `VERDICT: FAIL` review is never waived.
+
+### Known limits
+
+- **One issue at a time:** The watcher processes one issue at a time per room; subsequent labelled issues queue and wait for the active PR to be merged or closed.
+- **One open PR:** The room maintains at most one open PR at a time to keep branch history and CRDT file states consistent.
+- **Squash-merge history:** When PRs are squash-merged on GitHub, git commits are condensed to one, but GitHub preserves individual contributor names as `Co-authored-by:` trailers.
+- **Antigravity multi-window MCP session sharing:** In Antigravity IDE, multiple windows on the same machine share a single background MCP server process. Parallel agents must use separate workspace folders and distinct agent names (e.g. `antigravity-2`, `antigravity-4`) or standalone sessions to avoid `.hive-mcp-session.json` identity collisions.
+
 ## Why `gh` and not a GitHub App, for now
 
 - **With `gh`, nothing new is exposed.**

package/docs/TROUBLESHOOTING.md

@@ -85,3 +85,21 @@ This guide explains every error code (`Qxxx`) emitted by Hivecode CLI commands,
 | `Q642` | `hive-notify.js` | Running `notify` | Missing `--for <name>` argument or non-positive `--every` interval. | Specify who to notify with `--for <name>` and positive minutes with `--every <minutes>`. |
 | `Q643` | `hive-notify.js` | Running `notify` | The webhook endpoint refused the initial test post. | Check the webhook URL and ensure the receiving service is accessible. |
 | `Q644` | `hive-notify.js` | Running `notify` | A notifier is already running for this room (lock file held by another process). | Stop the other running notifier process or let it run. |
+| `Q575` | `hive-land.js` | Landing branch changes into a pull request (`hive_land` / `landIssue`) | A file claim is still held by a participant (or appeared during landing). All files must be released before landing. | Release all held files using `hive_release`, or wait for the holder to finish and release their claims. |
+| `Q576` | `hive-land.js` | Running project tests during landing verification (`--test "<command>"`) | The verification tests failed, timed out, or test checkout was not at the exact commit being landed. | Inspect test error output in room task or log. If tests require uncommitted files or dependencies, pass `--test-copy <files>` or `--test-setup <cmd>`, or fix failing test code. |
+| `Q577` | `hive-land.js` | Landing branch changes into a pull request | The room holds no files or landing would delete most branch files (>50% mass deletion). Indicates relay restarted or room was wiped. | Reconnect agents to reseed the room, reseed from branch (`branch <name> --reseed`), or pass `--allow-mass-delete` if intentional. |
+| `Q578` | `hive-land.js` | Pushing landed commits to remote origin (`git push origin <branch>`) | Pre-push checks failed: `origin` remote missing or unreachable, remote branch ahead, workflow files modified without `--allow-workflow-changes`, or secrets detected. | Ensure `origin` is configured and accessible, pull latest branch commits, or remove secrets/workflow changes from landed files. |
+| `Q579` | `hive-land.js` | Starting a landing run for a branch | Another landing run for this branch is currently active (landing lock held). | Wait for the concurrent landing to finish, or remove stale landing lock if the prior process crashed. |
+| `Q582` | `hive-repos.js` | Running `pr` from within a room | The room's repository folder is not located on this local machine. | Run `pr` from the machine where the repository clone resides, or register the repository with `hive-repos`. |
+| `Q583` | `hive-repos.js`, `hive-branch.js` | Running `pr` to land changes from a room | No local git repository is registered or bound to this room on this machine. | In your repository checkout, run `npx hivecode-mcp branch <branch>` to bind the room to your repository. |
+| `Q584` | `hive-repos.js` | Looking up registered repository for room | Repository registration is stale (folder moved/deleted) or multiple local clones are registered for the same room. | Re-bind the correct repository clone using `npx hivecode-mcp branch <branch>`, or remove obsolete entries in `~/.hivecode/repos.json`. |
+| `Q585` | `hive-repos.js` | Calling `hive_pr` | Not currently connected to a room (`hive_join` has not been called). | Join a room first using `hive_join` before calling `hive_pr`. |
+| `Q586` | `hive-repos.js` | Calling `hive_pr` | Room connection is currently offline or disconnected from relay. | Wait for the room connection to reconnect to the relay before running `hive_pr`. |
+| `Q650` | `hive-room-mode.js` | Starting room-mode watcher (`github start --room "<link>"`) | Missing, empty, or malformed room join link. | Provide a valid room join link (`wss://<relay>|room-<id>`) or use `github start --branch <name>`. |
+| `Q651` | `hive-room-mode.js` | Starting room-mode watcher | Target directory is not a git repository root (or is the user's home directory). | Run the watcher from inside a valid git repository checkout. |
+| `Q652` | `hive-room-mode.js` | Starting room-mode watcher | The specified room is not bound to a git branch in this repository, or multiple branches match. | Run `npx hivecode-mcp branch <branch>` to bind the branch, or launch with `github start --branch <branch>`. |
+| `Q653` | `hive-room-mode.js` | Preflight check for room-mode watcher | GitHub CLI (`gh`) is not installed, not in `PATH`, or not authenticated. | Install `gh` and run `gh auth login` with write permissions to the repository. |
+| `Q654` | `hive-room-mode.js` | Preflight member version check for room mode | An active AI agent in the room is running a Hivecode version older than 0.13.0, or has no version declared. | Update all participating AI agent packages to `hivecode-mcp@latest` (>= 0.13.0) and reconnect. |
+| `Q655` | `hive-room-mode.js` | Starting room-mode watcher | Another room-mode watcher is already active for this room (watcher lock held). | Stop the other running watcher process, or remove the stale lock file in `.git/hive-room-watcher.lock` if crashed. |
+| `Q656` | `hive-room-mode.js` | Room-mode watcher connecting to relay | Could not connect to relay at specified URL, or connection timed out. | Verify internet connectivity, check relay status, and ensure the relay URL is correct. |
+| `Q657` | `hive-room-mode.js` | Dispatching an issue task or chat into room | Delivery verification failed: task assignment or chat message was not confirmed in room within timeout. | Check relay stability, ensure room has reachable participants, and retry with `/hivecode retry`. |

package/hive-authors.js

@@ -0,0 +1,44 @@
+// hive-authors.js -- who wrote what the room holds: the ONE authorsOf, shared by sync.js and hive-pr.js. A receipt counts only when verify(r) === true or verify(r).ok === true (a truthy {ok:false} used to count).
+import { contentHash } from './substrate.js'
+
+/**
+ * Check whether a receipt is valid according to the optional verify function.
+ * Handles both boolean returns and { ok: boolean } result objects (verifyReceipt).
+ */
+export function isReceiptValid(verify, r) {
+  if (!verify) return true
+  const v = verify(r)
+  return v === true || Boolean(v && v.ok)
+}
+
+/**
+ * The authors of a file's held content, newest-landed first, from verified receipts only.
+ */
+export function authorsOf(receipts, verify, roomText) {
+  const ok = (receipts || []).filter((r) => r && r.author && isReceiptValid(verify, r))
+  if (!ok.length) return { last: null, contributors: [], first: 0, receipts: [] }
+  const want = typeof roomText === 'string' ? contentHash(roomText) : null
+  let idx = -1
+  if (want) {
+    for (let i = ok.length - 1; i >= 0; i--) {
+      if (ok[i].contentHash === want) {
+        idx = i
+        break
+      }
+    }
+  }
+  const held = idx >= 0 ? ok.slice(0, idx + 1) : ok
+  const last = held[held.length - 1]
+  const seen = new Map()
+  for (const r of held) {
+    if (!seen.has(r.author)) {
+      seen.set(r.author, { author: r.author, name: r.name || 'agent', at: r.at || 0 })
+    }
+  }
+  return {
+    last: last ? { author: last.author, name: last.name || 'agent', at: last.at || 0 } : null,
+    contributors: [...seen.values()],
+    first: Math.min(...ok.map((r) => r.at || 0)),
+    receipts: held,
+  }
+}

package/hive-await.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // hive-await — block until someone speaks to you, then exit. The CLI's `hive_wait`.
 //
-//   npx -y -p hivecode-mcp@latest hivecode-await "<relay|room>" <YourName> [idleMinutes]
+//   npx -y -p hivecode-mcp@latest hivecode-await "<relay|room>" <YourName> [idleMinutes] [app]
 //
 // Run it in the BACKGROUND and let its exit wake you. Exits 0 in both cases; read `reason` on stdout:
 //   {"reason":"mention","messages":[...]}   someone said @YourName or @all -> read, reply, run it again
@@ -37,15 +37,20 @@ import { startSync, parseLink } from './sync.js'
 import * as RC from './hive-receipts.js'
 import { awaitDir, armedFile, BEAT_MS } from './hive-listen.js'
 
-const [, , LINK = '', NAME = '', IDLE_MIN = '10'] = process.argv
+const [, , LINK = '', NAME = '', IDLE_MIN = '10', APP_ARG = ''] = process.argv
 if (!LINK || !NAME) {
-  console.error('usage: npx -y -p hivecode-mcp@latest hivecode-await "<relay|room>" <YourName> [idleMinutes]')
+  console.error('usage: npx -y -p hivecode-mcp@latest hivecode-await "<relay|room>" <YourName> [idleMinutes] [app]')
   process.exit(2)
 }
 const { relay, room } = parseLink(LINK)
 const dir = awaitDir(NAME)
+// Which app will be woken when this listener exits: passed by listenCommand, or inferred from the
+// session environment when the agent ran `node hive-await.js <link> <name> <min>` directly. Without
+// `app` here, a listener running while the MCP connection is closed or restarting leaves `app`
+// undefined in awareness, and hive-activity.js misreports the agent as "not woken by it".
+const APP = APP_ARG || process.env.HIVE_APP || (process.env.CLAUDE_CODE_SESSION_ID ? 'claude-code' : (process.env.ANTIGRAVITY_CONVERSATION_ID || process.env.ANTIGRAVITY_AGENT ? 'antigravity' : ''))
 
-const hive = startSync({ relay, room, dir, name: NAME, kind: 'ai', token: process.env.HIVE_TOKEN || '', syncFiles: false, listener: true, log: () => {} })
+const hive = startSync({ relay, room, dir, name: NAME, kind: 'ai', token: process.env.HIVE_TOKEN || '', syncFiles: false, listener: true, app: APP, log: () => {} })
 
 // ARMED, AND THE NEWEST LISTENER WINS (4 Oct 2026; see hive-listen.js). This file is how the Stop
 // hook and the MCP server know, with no network call, that the agent will hear the room after its
@@ -55,7 +60,7 @@ const hive = startSync({ relay, room, dir, name: NAME, kind: 'ai', token: proces
 // listener that finds the file naming another process leaves: that one was started after it.
 const ARMED = armedFile(NAME, room)
 const SESSION = process.env.CLAUDE_CODE_SESSION_ID || process.env.ANTIGRAVITY_CONVERSATION_ID || ''
-const AGAIN = `"${process.execPath.replace(/\\/g, '/')}" "${path.resolve(process.argv[1]).replace(/\\/g, '/')}" "${LINK}" "${NAME}" ${IDLE_MIN}`
+const AGAIN = `"${process.execPath.replace(/\\/g, '/')}" "${path.resolve(process.argv[1]).replace(/\\/g, '/')}" "${LINK}" "${NAME}" ${IDLE_MIN}${APP_ARG ? ` "${APP_ARG}"` : ''}`
 const startedAt = Date.now()
 let synced = false
 const readArmed = () => { try { return JSON.parse(fs.readFileSync(ARMED, 'utf8')) } catch { return null } }
@@ -77,7 +82,7 @@ const newerThanMe = (rec) => {
 function beat() {
   try {
     fs.mkdirSync(path.dirname(ARMED), { recursive: true })
-    const body = JSON.stringify({ pid: process.pid, name: NAME, room, link: LINK, session: SESSION, at: startedAt, beat: Date.now(), synced })
+    const body = JSON.stringify({ pid: process.pid, name: NAME, room, link: LINK, session: SESSION, ...(APP ? { app: APP } : {}), at: startedAt, beat: Date.now(), synced })
     const part = `${ARMED}.${process.pid}.tmp`
     try { fs.writeFileSync(part, body); fs.renameSync(part, ARMED) } catch {
       try { fs.rmSync(part, { force: true }) } catch {}

package/hive-branch.js

@@ -31,7 +31,6 @@ import os from 'os'
 import path from 'path'
 import crypto from 'crypto'
 import { spawnSync } from 'child_process'
-import { fileURLToPath } from 'url'
 import ignore from 'ignore'
 import { startSync, parseLink, ALWAYS_IGNORE, SKIP } from './sync.js'
 import { PUBLIC_DEFAULT_RELAY, currentRelayFor } from './hive-privacy.js'
@@ -40,6 +39,10 @@ import { validateMemberName, suggestMemberName } from './hive-mailbox.js'
 import { isSafeRelPath } from './token.js'
 
 const TEXT_MAX = 1_000_000 // sync.js MAX_BYTES: a larger file never crosses the relay
+
+// For hive-land.js, the one landing path. Declared below; exported here so the landing reads the
+// binding, the branch and the room with exactly the rules this module binds and seeds with.
+export { projectRoot, validBranch, revParse, coded, safeSegment, isOwnFile, git as gitIn, waitFor }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
 const coded = (code, msg) => Object.assign(new Error(`${code} ${msg}`), { code })
 
@@ -327,6 +330,13 @@ async function seedRoom({ root, branch, commit, link, you, log }) {
       throw coded('Q566', `a fresh joiner did not receive the whole branch: ${missing.length} of ${expected.size} files are missing or different (first: ${missing.slice(0, 5).join(', ')}). Nothing was bound; agents would have built on a partial tree.`)
     }
     const short = commit.slice(0, 7)
+    // Who holds this room's repo, for display only: an agent on another machine asked to open a PR
+    // is told whom to ask. Never a path; what lands is decided on the landing machine alone.
+    try { const R = await import('./hive-repos.js'); R.writeRepoHolder(seeder.doc, { branch, holder: you, host: os.hostname() }) } catch { /* display only */ }
+    // THE COMMIT THE ROOM STARTS FROM, for a teammate's `--join`: without it their clone cannot tell
+    // a file the room deleted from one added to the branch later, and landing from there skipped the
+    // room's deletions -- and the Q572 guard -- without a word (antigravity, 5 Nov 2026).
+    try { seeder.doc.getMap('seed').set('commit', commit); seeder.doc.getMap('seed').set('branch', branch) } catch { /* older relay docs */ }
     seeder.say(`Room for git branch \`${branch}\` @ ${short}, seeded by ${you} with ${expected.size} file(s). Work here lands on \`${branch}\` as one commit per agent via \`npx -y hivecode-mcp@latest pr ${branch}\`. Room folders are not git checkouts on purpose: edit files, do not commit.`)
     await sleep(600) // let the announcement leave before the socket closes
     return { dir, count: expected.size, total: files.length }
@@ -355,6 +365,25 @@ async function roomPaths(link, you) {
 }
 const roomFileCount = async (link, you) => { const p = await roomPaths(link, you); return p ? p.size : null }
 
+/** The commit the room was seeded from, as its seeder recorded it ({ commit, branch }), or null. */
+async function roomSeed(link, you) {
+  const { relay, room } = parseLink(link)
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'hive-peek-'))
+  const peek = startSync({ relay, room, dir, name: `${you}-peek`, kind: 'ai', passive: true, syncFiles: false, log: () => {} })
+  try {
+    let synced = false
+    peek.provider.on('sync', (s) => { if (s) synced = true })
+    if (!(await waitFor(() => synced, 15000))) return null
+    await sleep(300)
+    const m = peek.doc.getMap('seed')
+    const commit = m.get('commit')
+    return typeof commit === 'string' && /^[0-9a-f]{40}$/i.test(commit) ? { commit, branch: String(m.get('branch') || '') } : null
+  } finally {
+    try { peek.stop() } catch { }
+    try { fs.rmSync(dir, { recursive: true, force: true }) } catch { }
+  }
+}
+
 /** The branch a PR from `name` goes into: the checkout's current branch, else origin's default. */
 function defaultBase(root, name) {
   const cur = git(root, ['symbolic-ref', '--quiet', '--short', 'HEAD'])
@@ -383,6 +412,15 @@ export function removeRoomFolder(dir, room) {
   fs.rmSync(abs, { recursive: true, force: true })
 }
 
+const projectRootOrNull = (cwd) => { try { return projectRoot(cwd) } catch { return null } }
+
+// THIS MACHINE'S RECORD OF WHICH REPO HOLDS WHICH ROOM (hive-repos.js), so an agent that joined by
+// link -- not by branch -- can still land from here with hive_pr. Imported late: hive-repos imports
+// this module. Best effort: a registry that cannot be written never fails a bind, and hive_pr then
+// says exactly that the room is not bound on this machine (Q583), with the command that fixes it.
+async function registerLocal(root, branch, link) {
+  try { const R = await import('./hive-repos.js'); return !!R.registerRepo({ root, branch, link }) } catch { return false }
+}
 function youFrom(root, given) {
   const raw = given || git(root, ['config', 'user.name']).out || os.userInfo().username || 'dev'
   return validateMemberName(raw).ok ? raw : suggestMemberName(raw)
@@ -403,14 +441,17 @@ export async function bindBranch({ cwd, branch, from = '', relay = '', you = '',
     const { relay: jr, room } = parseLink(join)
     if (!jr || !room) throw coded('Q567', `"${join}" is not a room link (it looks like wss://relay|room-...).`)
     if (existing && existing.link !== join) throw coded('Q567', `branch "${name}" is already bound to a different room here (${existing.link}). Remove it with: git config --remove-section "hivecode.${name}"`)
-    writeBinding(root, name, { room: join })
-    return { root, branch: name, link: join, you: me, joined: true }
+    const seed = await roomSeed(join, me)
+    writeBinding(root, name, { room: join, base: seed && seed.commit ? seed.commit : '' })
+    await registerLocal(root, name, join)
+    return { root, branch: name, link: join, you: me, joined: true, base: seed && seed.commit ? seed.commit : '' }
   }
 
   if (existing && !reseed) {
     const n = await roomFileCount(existing.link, me)
     // Empty is only news when the seed was not: a branch with nothing a room can carry seeds nothing.
     const lost = n === 0 && Number(existing.files || 1) > 0
+    await registerLocal(root, name, existing.link) // a binding made before the registry existed gets its entry
     return { root, branch: name, link: existing.link, you: me, from: existing.from, existing: true, roomFiles: n, lost }
   }
 
@@ -459,166 +500,27 @@ export async function bindBranch({ cwd, branch, from = '', relay = '', you = '',
     throw e
   }
   writeBinding(root, name, { room: link, from: fromName, base: tip, seed: seeded.dir, files: String(seeded.count) })
+  await registerLocal(root, name, link)
   return { root, branch: name, link, you: me, from: fromName, commit: tip, created, reseeded: reseed, files: seeded.count, total: seeded.total, seedDir: seeded.dir }
 }
 
 // ---- landing: the room's work becomes commits on the branch ---------------------------------
 
-const HIVE_PR = path.join(path.dirname(fileURLToPath(import.meta.url)), 'hive-pr.js')
-const reEsc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-
-/**
- * THE ROOM'S DELETIONS, which hive-pr does not land: it copies the files a room holds, so a file an
- * agent deleted would simply stay on the branch, in a PR that looks complete. A room bound to a
- * branch starts as the whole branch, so "on the branch but no longer in the room" is a deletion --
- * but only when the room provably held THAT version of the file. For each such path:
- *   - last changed on the branch by a landing from this room (its commit says "Room: <id>") -> delete
- *   - unchanged since the seed commit                                                  -> delete
- *   - in the seed, but changed on the branch since by someone else                     -> REFUSE (Q572):
- *     deleting it would erase a change the room never saw
- *   - not in the seed and not landed from this room: added to the branch outside the room -> keep
- */
-async function roomDeletions({ root, link, base, tip }) {
-  if (!base) return []
-  const paths = await roomPaths(link, 'hive-land')
-  if (!paths) throw coded('Q565', `could not reach the relay to read the room's file list, so its deletions cannot be accounted for. Nothing was changed.`)
-  const room = parseLink(link).room
-  const atTip = treeFiles(root, tip)
-  const carries = roomCarries(atTip)
-  const baseSha = new Map(treeFiles(root, base).map((f) => [f.rel, f.sha]))
-  const gone = [], diverged = []
-  for (const f of atTip) {
-    if (!carries(f) || paths.has(f.rel)) continue
-    const last = git(root, ['log', '-1', '--format=%B', tip, '--', f.rel]).out
-    if (new RegExp(`^Room: ${reEsc(room)}$`, 'm').test(last)) gone.push(f.rel)
-    else if (baseSha.get(f.rel) === f.sha) gone.push(f.rel)
-    else if (baseSha.has(f.rel)) diverged.push(f.rel)
-  }
-  if (diverged.length) {
-    const who = (rel) => git(root, ['log', '-1', '--format=%h %an %ad %s', '--date=short', tip, '--', rel]).out
-    throw coded('Q572', `the room deleted ${diverged.length} file(s) that were changed on the branch since it was seeded, by a change the room never saw:\n${diverged.map((r) => `  ${r}   last changed by: ${who(r)}`).join('\n')}\nDeleting them would erase that change. Nothing was changed. Restore the file in the room (or delete it on the branch yourself), then run pr again.`)
-  }
-  return gone
-}
-
-function worktreesOn(root, branch) {
-  const r = git(root, ['worktree', 'list', '--porcelain'])
-  const out = []
-  let cur = null
-  for (const line of r.out.split('\n')) {
-    if (line.startsWith('worktree ')) cur = line.slice(9)
-    else if (line === `branch refs/heads/${branch}` && cur) out.push(path.resolve(cur))
-  }
-  return out
-}
-
 /**
- * `pr <name>`: land the room's work on the bound branch as one commit per agent.
+ * `pr <name>` used to land here. Landing now has ONE path, hive-land.js landAndOpen, shared by the
+ * `pr` command, the hive_pr tool and the GitHub watcher: every check (claims, an empty room, workflow
+ * files, keys, tests, origin ahead, the lock) protects all three. Two copies of the landing had
+ * already drifted once (the deletion accounting lived only here).
  *
- * hive-pr writes the commits (attribution and the staleness check are all its own), but it runs in
- * a TEMPORARY WORKTREE detached at the branch tip, because hive-pr switches the checkout it is given
- * and the developer's must never be switched. The branch then moves by compare-and-swap from the tip
- * the worktree was cut from, so a commit that reached the branch meanwhile is refused, never lost.
+ * landBranch keeps its old contract for the watcher, which still runs its own workflow, key and test
+ * checks after landing, and whose agent has exited by the time it lands (so its claims are moot):
+ * { ok:true, landed, tip, deletions } | { ok:false, code } with the reason on logErr.
  */
 export async function landBranch({ cwd, branch, dry = false, push = false, pr = false, base = '', force = '', only = '', title = '', log = console.log, logErr = console.error }) {
-  const root = projectRoot(cwd)
-  const name = validBranch(root, branch)
-  const b = readBinding(root, name)
-  if (!b) throw coded('Q562', `branch "${name}" has no Hivecode room here. Create one with: npx -y hivecode-mcp@latest branch ${name}`)
-  const tip = revParse(root, `refs/heads/${name}`)
-  if (!tip) throw coded('Q563', `branch "${name}" does not exist in ${root}. Fetch it first: git fetch origin ${name}:${name}`)
-
-  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'hive-land-'))
-  const temp = `hivecode-land/${safeSegment(name)}-${process.pid}-${Date.now()}`
-  const cleanup = () => {
-    git(root, ['worktree', 'remove', '--force', tmp])
-    try { fs.rmSync(tmp, { recursive: true, force: true }) } catch { }
-    git(root, ['worktree', 'prune'])
-    if (revParse(root, `refs/heads/${temp}`)) git(root, ['branch', '-D', temp])
-  }
-  const wt = git(root, noHooks(['worktree', 'add', '--detach', tmp, tip]))
-  if (wt.code !== 0) { cleanup(); throw coded('Q563', `could not make a temporary worktree: ${wt.err}`) }
-
-  try {
-    // Accounted for BEFORE anything is written, so a refusal (Q572) leaves the branch as it was.
-    const deletions = await roomDeletions({ root, link: b.link, base: b.base, tip })
-
-    const args = [HIVE_PR, b.link, 'hive-pr', '--repo', tmp, '--branch', temp, '--base', 'HEAD']
-    if (dry) args.push('--dry-run')
-    if (force) args.push('--force', force)
-    if (only) args.push('--only', only)
-    const r = spawnSync(process.execPath, args, { cwd: tmp, encoding: 'utf8', env: noHooksEnv({ ...process.env, HIVE_PROVENANCE: 'on' }), maxBuffer: 64 * 1024 * 1024, windowsHide: true })
-    if (r.stdout) log(r.stdout.replace(/\s+$/, ''))
-    // Q501 is hive-pr saying no file in the room carries an agent's receipt: nothing was changed or
-    // added. For a branch room that is an answer, not a failure -- and deletions may still land.
-    const nothingChanged = r.status !== 0 && /^Q501 /m.test(r.stderr || '')
-    if (r.stderr && !nothingChanged) logErr(r.stderr.replace(/\s+$/, ''))
-    if (r.status !== 0 && !nothingChanged) return { ok: false, code: r.status || 1 }
-    if (dry) {
-      if (deletions.length) log(`would delete ${deletions.length} file(s) the room deleted: ${deletions.join(', ')}`)
-      return { ok: true, dry: true, deletions }
-    }
-
-    if (deletions.length) {
-      // hive-pr left the temporary worktree on its branch when it committed; when it had nothing to
-      // commit it never made one, so make it here, at the same tip.
-      if (!revParse(root, `refs/heads/${temp}`)) git(tmp, noHooks(['checkout', '-q', '-b', temp]))
-      const rm = git(tmp, ['rm', '-q', '--', ...deletions])
-      if (rm.code !== 0) throw coded('Q563', `could not stage the room's deletions: ${rm.err}`)
-      const msg = [`Room: delete ${deletions.length === 1 ? deletions[0] : `${deletions.length} files`}`, '', ...deletions.map((d) => `  - ${d}`), '', `Room: ${parseLink(b.link).room}`].join('\n')
-      const c = git(tmp, noHooks(['commit', '-q', '-m', msg, '--author', 'hivecode-room <room@agents.hivecode.local>']))
-      if (c.code !== 0) throw coded('Q563', `could not commit the room's deletions: ${c.err || c.out}`)
-    }
-    // NOTHING NEW TO LAND IS NOT "DONE" WHEN A PUSH OR A PR WAS ASKED FOR. The usual sequence is a
-    // plain `pr` to look, then `pr --pr`; the second run lands nothing, and returning here skipped
-    // the push and the PR while printing success (1 Nov 2026). Push and open what is already there.
-    let nothingNew = false
-    if (nothingChanged && !deletions.length) { log(`nothing to land yet: no agent has changed a file in the room for ${name}.`); nothingNew = true }
-    const newTip = nothingNew ? tip : revParse(root, `refs/heads/${temp}`)
-    if (!nothingNew && (!newTip || newTip === tip)) { log(`nothing to land: ${name} already has everything the room holds.`); nothingNew = true }
-    if (nothingNew && !push && !pr) return { ok: true, landed: 0 }
-    if (nothingNew) return finish('')
-
-    // Move the branch. Checked out somewhere: only a clean fast-forward of that checkout, which is
-    // what `git pull` would do; with local changes it is refused, because moving the branch under a
-    // dirty checkout makes its edits look like reversals of the landed work.
-    const on = worktreesOn(root, name).filter((p) => p !== path.resolve(tmp))
-    if (on.length) {
-      const where = on[0]
-      const dirty = git(where, ['status', '--porcelain', '--untracked-files=no'])
-      if (dirty.out) throw coded('Q571', `${name} is checked out in ${where} with uncommitted changes. Commit or stash them there (or switch that checkout to another branch), then run pr again. Nothing was changed.`)
-      const ff = git(where, ['merge', '--ff-only', '--quiet', newTip])
-      if (ff.code !== 0) throw coded('Q570', `could not fast-forward ${name} in ${where}: ${ff.err || 'git refused'}. Nothing was changed; if the branch moved there, run pr again.`)
-    } else {
-      const cas = git(root, ['update-ref', '-m', 'hivecode: land room work', `refs/heads/${name}`, newTip, tip])
-      if (cas.code !== 0) throw coded('Q570', `${name} moved while this was landing (it is no longer ${tip.slice(0, 7)}). Nothing was changed; run pr again so the new commits are accounted for.`)
-    }
-    const made = git(root, ['log', '--format=  %h  %an  %s', `${tip}..${newTip}`]).out
-    log(`\nlanded on ${name}:\n${made}`)
-    return finish(made)
-
-    // `made` is '' when nothing new landed this run: the push and the PR are of what is already on
-    // the branch, and the PR body lists the branch's commits since its base instead.
-    function finish(made) {
-      if (push) {
-        const p = git(root, ['push', '-u', 'origin', name])
-        if (p.code !== 0) throw coded('Q573', `the work ${made ? 'landed' : 'is'} on ${name} locally, but the push failed: ${p.err}`)
-        log(`pushed ${name}`)
-      }
-      if (pr) {
-        const into = base || b.from
-        if (!into) throw coded('Q574', `the work is on ${name}, but there is no branch to open the PR into; pass --base <branch>.`)
-        const listed = made || git(root, ['log', '--format=  %h  %an  %s', `${into}..${name}`]).out
-        const body = [`Opened by Hivecode from the room bound to \`${name}\`.`, '', 'Each commit carries its agent as the git author and the signed author id as a `Hivecode-Author` trailer.', '', '```', listed, '```'].join('\n')
-        const g = spawnSync('gh', ['pr', 'create', '--base', into, '--head', name, '--title', title || `Hivecode: ${name}`, '--body', body], { cwd: root, encoding: 'utf8', windowsHide: true })
-        if (g.status !== 0) throw coded('Q574', `the work is on ${name}, but gh pr create failed: ${(g.stderr || (g.error && g.error.message) || '').toString().trim()}`)
-        log((g.stdout || '').trim())
-      }
-      return { ok: true, landed: made ? made.split('\n').filter(Boolean).length : 0, tip: made ? newTip : tip, deletions }
-    }
-  } finally {
-    cleanup()
-  }
+  const { landAndOpen } = await import('./hive-land.js')
+  const r = await landAndOpen({ cwd, branch, dry: !!dry, push, pr, base, force, only, title, log, logErr, claims: false, checks: false, by: 'the Hivecode GitHub watcher' })
+  if (!r.ok) { logErr(r.why); return { ok: false, code: 1, refused: r.code } }
+  return r.dry ? { ok: true, dry: true, deletions: r.deletions } : { ok: true, landed: r.landed, tip: r.tip, deletions: r.deletions }
 }
 
 // ---- CLI ----------------------------------------------------------------------------------
@@ -630,7 +532,7 @@ function flags(argv) {
     const a = argv[i]
     if (!a.startsWith('--')) { pos.push(a); continue }
     const k = a.slice(2)
-    if (['dry-run', 'push', 'pr', 'reseed'].includes(k)) f[k] = true
+    if (['dry-run', 'push', 'pr', 'reseed', 'allow-workflow-changes', 'allow-mass-delete', 'save'].includes(k)) f[k] = true
     else f[k] = argv[++i] || ''
   }
   return { pos, f }
@@ -640,7 +542,8 @@ const USAGE = `usage:
   npx -y hivecode-mcp@latest branch <name> [--from <ref>] [--name <you>] [--relay <url>]
   npx -y hivecode-mcp@latest branch <name> --join "<link>"
   npx -y hivecode-mcp@latest branch <name> --reseed
-  npx -y hivecode-mcp@latest pr <name> [--dry-run] [--push] [--pr] [--base <branch>] [--force "<reason>"]`
+  npx -y hivecode-mcp@latest pr <name> [--dry-run] [--push] [--pr] [--base <branch>] [--test "<command>" [--test-copy <file,...>] [--test-setup "<cmd>"] [--save]] [--test-minutes <n>]
+                                       [--allow-workflow-changes] [--allow-mass-delete] [--title "<t>"] [--force "<reason>"]`
 
 /** `argv` starts at the subcommand: ['branch', 'fix-x', ...] or ['pr', 'fix-x', ...]. Returns an exit code. */
 export async function main(argv, { cwd = process.cwd(), log = console.log, logErr = console.error } = {}) {
@@ -650,8 +553,26 @@ export async function main(argv, { cwd = process.cwd(), log = console.log, logEr
   if (!name || (cmd !== 'branch' && cmd !== 'pr')) { logErr(USAGE); return 2 }
   try {
     if (cmd === 'pr') {
-      const r = await landBranch({ cwd, branch: name, dry: !!f['dry-run'], push: !!(f.push || f.pr), pr: !!f.pr, base: f.base || '', force: f.force || '', only: f.only || '', title: f.title || '', log, logErr })
-      return r.ok ? 0 : r.code || 1
+      const { landAndOpen, testCommandFor, saveTestCommand } = await import('./hive-land.js')
+      let test = f.test || ''
+      // --test-copy a,b  and  --test-setup "<cmd>": what the tests need beyond git (see hive-land.js).
+      const testCopy = 'test-copy' in f ? String(f['test-copy'] || '').split(',').map((s) => s.trim()).filter(Boolean) : undefined
+      const testSetup = 'test-setup' in f ? String(f['test-setup'] || '') : undefined
+      if (f.save) {
+        if (!test) { logErr(`--save keeps a test command: pass it with --test "<command>"`); return 2 }
+        saveTestCommand(cwd, name, test, { copy: testCopy ?? null, setup: testSetup ?? null })
+        log(`saved: landing ${name} now runs ${testSetup ? `\`${testSetup}\`, then ` : ''}\`${test}\` first${testCopy && testCopy.length ? `, with ${testCopy.join(', ')} copied in` : ''}, from any caller (pr, hive_pr, room mode). Change it the same way.`)
+      }
+      // No --test: the command saved for this branch, if any. (The project's own `npm test` is the
+      // hive_pr tool's fallback; here the developer is present, so nothing runs they did not choose.)
+      if (!test) { const t = testCommandFor(cwd, name); if (t.from === 'saved') { test = t.command; log(`tests: \`${test}\` (saved for ${name})`) } }
+      const r = await landAndOpen({
+        cwd, branch: name, dry: !!f['dry-run'], push: !!(f.push || f.pr), pr: !!f.pr, base: f.base || '', force: f.force || '', only: f.only || '', title: f.title || '',
+        test, testMinutes: Number(f['test-minutes']) || 0, testCopy, testSetup, allowWorkflowChanges: !!f['allow-workflow-changes'], allowMassDelete: !!f['allow-mass-delete'],
+        by: youFrom(projectRootOrNull(cwd) || cwd, ''), log, logErr,
+      })
+      if (!r.ok) { logErr(r.why); return 1 }
+      return 0
     }
     const r = await bindBranch({ cwd, branch: name, from: f.from || '', relay: f.relay || '', you: f.name || '', join: f.join || '', reseed: !!f.reseed })
     const agentLine = `Use hive_join with branch "${r.branch}", repo "${r.root.replace(/\\/g, '/')}", as a name of your own (each agent picks a different one)`

package/hive-github.js

@@ -1632,8 +1632,17 @@ function flags(argv) {
 
 const USAGE = `usage:
   npx -y hivecode-mcp@latest github start --agent "<agent command>" [options]
+  npx -y hivecode-mcp@latest github start --room "<room link>" [--fallback-agent "<command>"] [--ack-minutes 10]
+  npx -y hivecode-mcp@latest github start --branch <name> [--fallback-agent "<command>"] [--ack-minutes 10]
   npx -y hivecode-mcp@latest github status
 
+--room: hand each labelled issue to the agents ALREADY in that room (a room bound to a branch of
+this repo: npx -y hivecode-mcp@latest branch <name>). They split it, build it and review each other;
+Hivecode runs the tests and opens one pull request. One issue at a time.
+  --branch <name>               bind or use the room for this branch, and run room mode
+  --fallback-agent "<command>"  if nobody in the room takes an issue, start this agent in the room
+                                (opt-in: it spends that agent's tokens; capped by --max-runs-per-day)
+
 The agent command reads its task on stdin. For Claude Code:
   --agent "claude -p --output-format json --allowedTools Bash Edit Write Read Glob Grep mcp__hivecode"
 
@@ -1686,6 +1695,16 @@ export async function main(argv, { cwd: here = process.cwd(), log = console.log,
   if (sub === 'status') {
     const s = loadState(file, log, { peek: true })
     log(describe(s, s.config || {}))
+    // ROOM MODE keeps its own state (room-<room>.json, never github.json): describe each one, so
+    // "why isn't it picking up my issue?" has an answer here too.
+    try {
+      const dir = path.join(gitDir, 'hivecode')
+      const rooms = fs.existsSync(dir) ? fs.readdirSync(dir).filter((x) => /^room-.+\.json$/.test(x)) : []
+      if (rooms.length) {
+        const RW = await import('./hive-room-watcher.js')
+        for (const x of rooms) log(`\n${RW.describeRoomState(RW.loadRoomState(path.join(dir, x)))}`)
+      }
+    } catch (e) { log(`(room mode state could not be read: ${e.message})`) }
     return 0
   }
 
@@ -1719,6 +1738,27 @@ export async function main(argv, { cwd: here = process.cwd(), log = console.log,
     return busy ? EXIT_AGAIN : EXIT_FIX
   }
   if (info.permissions && info.permissions.push === false) { logErr(`Q601 the GitHub account gh is logged in as cannot push to ${id.owner}/${id.repo}.`); return EXIT_FIX }
+  // ROOM MODE: issues go to the agents ALREADY in a room (hive-room-watcher.js), and no agent of ours
+  // runs unless --fallback-agent asks for one. Everything below this line is the other mode.
+  if (opt('room') || ('branch' in f)) {
+    if (f['dry-run']) { logErr('Q602 --dry-run does not work with --room yet. Use: npx -y hivecode-mcp@latest github status'); return EXIT_FIX }
+    let roomLink = opt('room')
+    if (!roomLink && ('branch' in f)) {
+      const branchName = String(opt('branch') || '').trim()
+      if (!branchName || branchName === 'true') { logErr('Q602 say which branch to watch, with --branch <name>.'); return EXIT_FIX }
+      const HB = await import('./hive-branch.js')
+      try {
+        const bound = await HB.bindBranch({ cwd: root, branch: branchName, relay: opt('relay') || '', log })
+        roomLink = bound.link
+        f['room'] = roomLink
+      } catch (e) {
+        logErr(isQ(e) ? e.message : `Q603 ${e.message}`)
+        return EXIT_FIX
+      }
+    }
+    const RW = await import('./hive-room-watcher.js')
+    return RW.runRoomMode({ f, opt, gh, id, info, root, gitDir, label: opt('label') || LABEL, log, logErr })
+  }
   const agent = opt('agent')
   if (!agent) { logErr(`Q602 say which agent runs the work, with --agent "<command>".\n\n${USAGE}`); return EXIT_FIX }
   if (!commandExists(agent)) { logErr(`Q602 "${String(agent).split(/\s+/)[0]}" is not installed here (not on PATH).`); return EXIT_FIX }