borgmcp 5.0.3 → 5.1.1

package/src/regen-format.ts

@@ -23,6 +23,8 @@ import { OPENCODE_WAKE_PATH_GUIDANCE } from './opencode-wake-copy.js';
 import { isBorgSession } from './launch-gate.js';
 import type { AgentKind } from './agent-runtime.js';
 
+export type HandoverMode = 'origin' | 'local';
+
 /**
  * Extract the SessionStart `source` from a Claude Code hook payload (gh#926).
  *
@@ -245,10 +247,16 @@ export function markArrivalAnnouncedThisProcess(): void {
 //   The playbook below points drones to `borg_docs {topic}` for user questions
 //   about how Borg MCP works; this marker pins the param so the #490/#529 guard
 //   verifies borg_docs exposes `topic`.
-export function getDronePlaybook(): string {
+export function getDronePlaybook(handoverMode: HandoverMode = 'origin'): string {
   const arrivalInstruction = arrivalAnnouncedThisProcess
     ? ''
     : `\n**Required one-time startup setup:** If this instruction is visible, immediately call \`borg_log message="ARRIVAL: <your-label> (<your-role>) online on ${osHostname()}" to="broadcast"\` before unread-log triage. This is the sole exception to no-work log silence. Do not infer your startup state from peers' \`ARRIVAL:\` entries. After the post succeeds, the client suppresses this instruction until the MCP process restarts; an explicit \`/mcp\` reconnect may show it again.\n`;
+  const reviewReadyRefs = handoverMode === 'local'
+    ? '["HEAD"]'
+    : '["HEAD","origin/<branch>","origin/main"]';
+  const stagedDiffPurpose = handoverMode === 'local'
+    ? 'Catches deleted files / anomalous -LOC / wrong paths before handover.'
+    : 'Catches deleted files / anomalous -LOC / wrong paths pre-push.';
   return `## How to operate as a Drone
 
 You're a Drone in a Cube. Coordinate with other drones through the activity log.
@@ -262,14 +270,14 @@ You're a Drone in a Cube. Coordinate with other drones through the activity log.
 - \`borg_roster\` — see who else is connected
 - \`borg_read-log unread_only=true [limit]\` — drain unread log entries from your server-side cursor
 - \`borg_read-entry entry_id=<id>\` — read one known complete entry without moving the unread cursor
-- \`borg_log message="<message>" to="broadcast"|["<selector>"] refs=["HEAD","origin/<branch>","origin/main"]\` — append with an explicit audience and optional mechanically resolved Git provenance; REVIEW-READY requires \`refs\`
+- \`borg_log message="<message>" to="broadcast"|["<selector>"] refs=${reviewReadyRefs}\` — append with an explicit audience and optional mechanically resolved Git provenance; REVIEW-READY requires \`refs\`
 - \`borg_assimilate <cube>\` — switch to a different cube
 
 **How coordination works:** the Cube gives primitives, not workflows. Your role's \`detailed_description\` (above) is your playbook — its conventions + signals come from there, not the system. The log is the coordination channel. Different cubes, different conventions. Every \`borg_log\` call must choose its audience with \`to: "broadcast"\` or a non-empty selector array; omission, message text, prefixes, and classes never choose recipients.
 
 **Communication discipline for non-human seats:**
 - **Console:** write nothing except harness-required output. Surface something to the operator only when blocked and needing unblocking; do not narrate plans, progress, method, or results.
-- **Log:** a post must change what another seat does. Otherwise, do not write it. Keep posts short: lifecycle signal + mechanically resolved SHA and nothing else; defect + location/evidence; correction to your live claim; or a genuine blocking question. Post REVIEW-READY with \`refs: ["HEAD","origin/<branch>","origin/main"]\`.
+- **Log:** a post must change what another seat does. Otherwise, do not write it. Keep posts short: lifecycle signal + mechanically resolved SHA and nothing else; defect + location/evidence; correction to your live claim; or a genuine blocking question. Post REVIEW-READY with \`refs: ${reviewReadyRefs}\`.
 - **Do not post:** plans, work-in-progress/progress narration, method or reasoning, restatements/agreement/credit, self-examination, framing phrases, or coordination commentary.
 - **Evidence boundary:** state what a verdict did not exercise and any unavailable control in the same short clause. The human seat is excluded so its dispatches can explain constraints without being misapplied.
 
@@ -313,7 +321,7 @@ ${arrivalInstruction}
 One seat uses one stable worktree. Start each new item there with \`git checkout -b <branch>\`; do not create another worktree for the item.
 A reviewing seat uses \`git checkout --detach <SHA>\` in its own worktree. Keep scratch work under \`~/.borg/scratch/<seat>/\`; load \`borg_playbook\` for the full mechanism.
 
-Any drone that commits code: run \`git diff --staged --stat\` before \`git commit\` to verify file count + LOC direction + paths match your intent. Catches deleted files / anomalous -LOC / wrong paths pre-push. Your role may layer more git rules (code-implementing + coordinating roles typically carry the full set).`;
+Any drone that commits code: run \`git diff --staged --stat\` before \`git commit\` to verify file count + LOC direction + paths match your intent. ${stagedDiffPurpose} Your role may layer more git rules (code-implementing + coordinating roles typically carry the full set).`;
 }
 
 /**
@@ -329,7 +337,31 @@ Any drone that commits code: run \`git diff --staged --stat\` before \`git commi
 //   `borg_decisions {topic}`; this marker pins the param so the #490/#529
 //   copy-guard verifies borg_decisions exposes `topic`
 //   (client/__tests__/copy-mechanism-guard.test.ts).
-export function getDronePlaybookChapter(): string {
+export function getDronePlaybookChapter(handoverMode: HandoverMode = 'origin'): string {
+  const codeStateRef = handoverMode === 'local'
+    ? 'a named local branch or commit'
+    : '`origin/main`, PR head, branch, merge-SHA, or tag';
+  const proposalRef = handoverMode === 'local'
+    ? 'If the proposal cites a named local branch or commit, grep that ref via `git show <ref>:<path> | grep`'
+    : 'If the proposal cites current `origin/main` or a branch/SHA, grep that ref via `git show <ref>:<path> | grep`';
+  const commentRef = handoverMode === 'local'
+    ? 'If the comment describes a named local branch or commit, grep that ref via `git show <ref>:<path> | grep`'
+    : 'If the comment describes a merged/base/PR-head state, grep the named ref via `git show <ref>:<path> | grep`';
+  const worktreeMechanism = handoverMode === 'local'
+    ? `- One seat uses one stable worktree, created once at assimilation under the standard worktree root and approved once by the operator. All seats for a repository use worktrees from the same clone family, sharing its object database and refs.
+- Start each new work item in that stable worktree with \`git checkout -b <branch>\`. Do not create a new worktree or folder for each item.
+- A commit on a named branch is the handover artifact. Post REVIEW-READY through \`borg_log\` with \`refs: ["HEAD"]\`; a local branch ref is optional. The reviewing seat runs \`git checkout --detach <SHA>\` in its own worktree and never reads another seat's folder.
+- Treat branch history as shared: another seat may have the branch checked out, so never rewrite it.
+- A commit is the only checkpoint; repository backup is the operator's concern.
+- Put detached review checkouts, clean-environment rigs, fake HOMEs, unpacked artifacts, and throwaway worktrees under \`~/.borg/scratch/<your-seat-label>/\`. Never use \`/tmp\` or an ad-hoc path. Scratch contents are disposable and must be cleaned up with the work.`
+    : `- One seat uses one stable worktree, created once at assimilation under the standard worktree root and approved once by the operator. All seats for a repository use worktrees from the same clone family, sharing its object database and refs.
+- Start each new work item in that stable worktree with \`git checkout -b <branch>\`. Do not create a new worktree or folder for each item.
+- Hand a branch to another seat only through an explicit log event.
+- Treat branch history as shared: another seat may have the branch checked out or fetched, so never rebase or force-push it.
+- Hand over refs and exact commit SHAs, never a filesystem path. Post REVIEW-READY through \`borg_log\` with \`refs: ["HEAD","origin/<branch>","origin/main"]\`; a reviewing seat checks out the resolved SHA in its own worktree with \`git checkout --detach <SHA>\` and never reads another seat's folder.
+- With no hosted remote, the commit is the durable handover artifact because clone-family worktrees share refs; omit the push step. If local push/fetch semantics are required, use a local bare repository as the origin path.
+- Put detached review checkouts, clean-environment rigs, fake HOMEs, unpacked artifacts, and throwaway worktrees under \`~/.borg/scratch/<your-seat-label>/\`. Never use \`/tmp\` or an ad-hoc path. Scratch contents are disposable and must be cleaned up with the work.
+- When an origin exists, synchronize with merge-only history using \`git fetch origin && git merge origin/main\`.`;
   return `## Operating playbook — full disciplines (borg_playbook chapter)
 
 This is the on-demand detail behind the rule-spine in your regen. Load it ONCE per session; it is static — do not re-fetch on every wake.
@@ -346,7 +378,7 @@ Any time you make a factual claim that could be verified — "this shipped as ve
 - Version attribution → \`git tag --contains <sha>\` or \`git log --oneline <tag>\`
 - Code state → match the grep surface to the claim surface:
   - Local uncommitted claim → \`grep -n "<symbol>" <file>\` or direct file read in the working tree
-  - \`origin/main\`, PR head, branch, merge-SHA, or tag claim → \`git show <ref>:<path>\` followed by a symbol search in the returned source
+  - ${codeStateRef} claim → \`git show <ref>:<path>\` followed by a symbol search in the returned source
 - Prod state → \`curl https://<endpoint>\` or \`wrangler tail --env production\`
 - npm registry state → \`npm view <package>@<version>\` or \`npm view <package>@latest\`
 - DB state → query through the existing \`db\` interface; never trust a doc claim about row counts / column values
@@ -359,8 +391,8 @@ Any time you make a factual claim that could be verified — "this shipped as ve
 
 The discipline applies at FOUR surfaces. Catches at the surface closest to origin are cheapest; catches at later surfaces have already propagated through earlier consumers:
 
-- **Surface 1 (brainstorm-proposal time)**: when a brainstorm contribution names specific code identifiers / API field names / enum values / column names / function signatures, the PROPOSING drone source-grep's the referenced file BEFORE composing the proposal. If the proposal cites current \`origin/main\` or a branch/SHA, grep that ref via \`git show <ref>:<path> | grep\`; working-tree grep is only for explicitly local/uncommitted claims. Cheapest catch surface; one drone catches one error.
-- **Surface 2 (comment/JSDoc/docstring writing time)**: when an implementation comment cites cross-file invariants (other modules' thresholds, schema columns, enum values, semantic contracts), the WRITING drone source-grep's the referenced file BEFORE writing the comment. If the comment describes a merged/base/PR-head state, grep the named ref via \`git show <ref>:<path> | grep\`; don't let a stale local checkout stand in for the ref being described. Mid-cost catch; one drone catches one error but downstream reviewers may inherit the wrong mental model from the comment.
+- **Surface 1 (brainstorm-proposal time)**: when a brainstorm contribution names specific code identifiers / API field names / enum values / column names / function signatures, the PROPOSING drone source-grep's the referenced file BEFORE composing the proposal. ${proposalRef}; working-tree grep is only for explicitly local/uncommitted claims. Cheapest catch surface; one drone catches one error.
+- **Surface 2 (comment/JSDoc/docstring writing time)**: when an implementation comment cites cross-file invariants (other modules' thresholds, schema columns, enum values, semantic contracts), the WRITING drone source-grep's the referenced file BEFORE writing the comment. ${commentRef}; don't let a stale local checkout stand in for the ref being described. Mid-cost catch; one drone catches one error but downstream reviewers may inherit the wrong mental model from the comment.
 - **Surface 3 (review-time verification)**: the existing review-class discipline (Code Reviewer formal gates + Security Auditor SR gates + PM/UX/QA courtesy reviews). Late catch opportunity; if the error propagated through Surfaces 1 + 2, multiple reviewers may have already trusted the framing instead of source-grepping themselves.
 - **Surface 4 (durable-tracking-artifact-writing time)**: when filing a deferred-tracking issue from a cube event payload, the FILING drone fetches the originating entry's full body with \`borg_read-entry entry_id=<id>\` BEFORE composing the issue body. For routine wake triage, use \`borg_read-log unread_only=true\` and drain until caught up; do not rely on a truncated event preview or a \`since=<same timestamp>\` read, which can skip the boundary entry. Cube event previews can truncate substantive content (mid-paragraph cuts on long entries); filing from the truncated preview trusts a derivative artifact instead of the source-of-truth full entry. Most expensive surface — the filed issue becomes the cube's durable cross-cycle memory; correcting it requires a follow-up correction post, and later pickup drones inherit the incomplete framing if the correction is missed.
 
@@ -368,14 +400,7 @@ The discipline applies at FOUR surfaces. Catches at the surface closest to origi
 
 **Worktree and git mechanism:**
 
-- One seat uses one stable worktree, created once at assimilation under the standard worktree root and approved once by the operator. All seats for a repository use worktrees from the same clone family, sharing its object database and refs.
-- Start each new work item in that stable worktree with \`git checkout -b <branch>\`. Do not create a new worktree or folder for each item.
-- Hand a branch to another seat only through an explicit log event.
-- Treat branch history as shared: another seat may have the branch checked out or fetched, so never rebase or force-push it.
-- Hand over refs and exact commit SHAs, never a filesystem path. Post REVIEW-READY through \`borg_log\` with \`refs: ["HEAD","origin/<branch>","origin/main"]\`; a reviewing seat checks out the resolved SHA in its own worktree with \`git checkout --detach <SHA>\` and never reads another seat's folder.
-- With no hosted remote, the commit is the durable handover artifact because clone-family worktrees share refs; omit the push step. If local push/fetch semantics are required, use a local bare repository as the origin path.
-- Put detached review checkouts, clean-environment rigs, fake HOMEs, unpacked artifacts, and throwaway worktrees under \`~/.borg/scratch/<your-seat-label>/\`. Never use \`/tmp\` or an ad-hoc path. Scratch contents are disposable and must be cleaned up with the work.
-- When an origin exists, synchronize with merge-only history using \`git fetch origin && git merge origin/main\`.`;
+${worktreeMechanism}`;
 }
 
 /**
@@ -531,7 +556,7 @@ export function formatRegenMarkdown(
     // mid-session restatement moments. Absent on a pre-gh#740 worker → omitted.
     decisions?: any[];
   },
-  opts: { mode?: RegenMode } = {}
+  opts: { mode?: RegenMode; handoverMode?: HandoverMode } = {}
 ): string {
   const mode = opts.mode ?? 'full';
   const roleOverview = result.roles
@@ -676,7 +701,7 @@ export function formatRegenMarkdown(
   );
 
   if (shouldEmitPlaybook) {
-    lines.push('', getDronePlaybook());
+    lines.push('', getDronePlaybook(opts.handoverMode));
     boilerplateEmittedThisSession = true;
   }
   if (shouldEmitRoleText && roleTextHash != null) {

package/src/reset-local-seat-cmd.ts

@@ -3,8 +3,9 @@
  * seat reset from the ratified client-seat-reset-state-model (Option W).
  *
  * Attach is PURE DIAGNOSIS on a pin-matched SESSION_REJECTED (it mutates
- * nothing and points here). This command is the ONLY writer that intentionally
- * clears a worktree's saved local seat. It performs ZERO network I/O: it never
+ * nothing and points here). This is the ONLY command that explicitly clears a
+ * worktree's saved local seat; a successful consented bind can also retire its
+ * predecessor atomically. The command performs ZERO network I/O: it never
  * contacts the server, so it makes NO server-revocation claim. It clears ONLY
  * this worktree's saved local seat — its credential and cube binding together —
  * from the local seat store (keyed on findProjectRoot()); server, trust anchor,

package/src/seats.ts

@@ -45,6 +45,8 @@ export interface SeatRecord {
   // credential
   credential: string;
   state: 'pending' | 'active';
+  /** Monotonic store-local order assigned when this record is bound active. */
+  bindingOrder?: number;
   // server metadata (active only)
   droneId?: string;
   sessionId?: string;
@@ -144,6 +146,8 @@ function isValidSeatRecord(ref: string, value: unknown): value is SeatRecord {
     return false;
   }
   if (r.state !== 'pending' && r.state !== 'active') return false;
+  if (r.bindingOrder !== undefined &&
+      (typeof r.bindingOrder !== 'number' || !Number.isSafeInteger(r.bindingOrder) || r.bindingOrder < 1)) return false;
   // Optional display/typed fields, validated when present.
   if (r.name !== undefined && typeof r.name !== 'string') return false;
   if (r.droneLabel !== undefined && typeof r.droneLabel !== 'string') return false;
@@ -169,7 +173,7 @@ function isValidSeatRecord(ref: string, value: unknown): value is SeatRecord {
     }
   } else {
     // A PENDING record must NOT carry active-only server session fields.
-    if (r.sessionId !== undefined) return false;
+    if (r.sessionId !== undefined || r.bindingOrder !== undefined) return false;
   }
   // The map key must equal the record's derived ref (no cross-key aliasing).
   return seatRef(value as SeatRecord) === ref;
@@ -231,12 +235,56 @@ function parseStore(raw: string): SeatsFile | null {
         }
         if (!isValidSeatRecord(ref, record)) return null;
       }
-      return { version: SEATS_VERSION, seats: seats as Record<string, SeatRecord> };
+      const store = { version: SEATS_VERSION, seats: seats as Record<string, SeatRecord> };
+      repairOrderedDuplicateBindings(store);
+      return store;
     }
   }
   return null;
 }
 
+/**
+ * Remove superseded worktree bindings when persisted ordering proves which bind
+ * is newest. The mutation is persisted by the next transaction that commits.
+ * Legacy duplicates without a complete, unique order stay intact and fail
+ * closed when that worktree is resolved.
+ */
+function repairOrderedDuplicateBindings(store: SeatsFile): void {
+  const byWorktree = new Map<string, Array<[string, SeatRecord]>>();
+  for (const entry of Object.entries(store.seats)) {
+    const [, record] = entry;
+    if (record.state !== 'active' || record.worktree === undefined) continue;
+    const candidates = byWorktree.get(record.worktree) ?? [];
+    candidates.push(entry);
+    byWorktree.set(record.worktree, candidates);
+  }
+  for (const candidates of byWorktree.values()) {
+    if (candidates.length < 2) continue;
+    const ordered = candidates.filter(
+      (entry): entry is [string, SeatRecord & { bindingOrder: number }] =>
+        entry[1].bindingOrder !== undefined,
+    );
+    if (ordered.length === 0) continue;
+    const orders = ordered.map(([, record]) => record.bindingOrder);
+    if (new Set(orders).size !== orders.length) continue;
+    const newest = ordered.reduce((left, right) =>
+      left[1].bindingOrder > right[1].bindingOrder ? left : right);
+    for (const [ref] of candidates) {
+      if (ref !== newest[0]) delete store.seats[ref];
+    }
+  }
+}
+
+export class AmbiguousSeatBindingError extends Error {
+  constructor(worktree: string) {
+    super(
+      `Borg found multiple active seats for worktree ${worktree}, but their bind order is unavailable. ` +
+      'No identity or inbox path was selected. Run `borg reset-local-connection` to clear the ambiguous local connection.',
+    );
+    this.name = 'AmbiguousSeatBindingError';
+  }
+}
+
 async function readStore(): Promise<SeatsFile> {
   const raw = await readStoreFile(SEATS_FILE);
   // CR4 fail-closed: ENOENT alone initializes empty. A present-but-malformed /
@@ -498,9 +546,28 @@ export async function activateAndBindSeat(input: {
     const record = txn.data.seats[ref];
     if (!recordMatches(record, ref, binding)) return 'missing';
     if (digestOf(record.credential) !== input.expectedPendingDigest) return 'replaced';
+    const highestOrder = Object.values(txn.data.seats).reduce(
+      (highest, candidate) => Math.max(highest, candidate.bindingOrder ?? 0),
+      0,
+    );
+    const bindingOrder = record.state === 'active' && record.worktree === input.worktree &&
+      record.bindingOrder !== undefined
+      ? record.bindingOrder
+      : highestOrder + 1;
+    if (!Number.isSafeInteger(bindingOrder)) {
+      throw new Error('Borg private seat store bind order is exhausted; refusing to activate a seat');
+    }
+    const retiredRefs: string[] = [];
+    for (const [candidateRef, candidate] of Object.entries(txn.data.seats)) {
+      if (candidateRef !== ref && candidate.state === 'active' && candidate.worktree === input.worktree) {
+        delete txn.data.seats[candidateRef];
+        retiredRefs.push(candidateRef);
+      }
+    }
     txn.data.seats[ref] = {
       ...record,
       state: 'active',
+      bindingOrder,
       droneId: input.droneId,
       sessionId: input.sessionId,
       worktree: input.worktree,
@@ -513,6 +580,7 @@ export async function activateAndBindSeat(input: {
       ...(input.isHumanSeat !== undefined ? { isHumanSeat: input.isHumanSeat } : {}),
     };
     await txn.commit();
+    for (const retiredRef of retiredRefs) rejectedSeatRefs.delete(retiredRef);
     rejectedSeatRefs.delete(ref);
     return 'activated';
   });
@@ -584,25 +652,19 @@ export async function bindPendingSeatToWorktree(input: {
 // ─── Hydration / enumeration (scan by worktree) ──────────────────────────────
 
 /** The preferred ACTIVE seat bound to `worktree`, or null. A pending record (no
- *  worktree, or non-active) is NEVER surfaced as a live binding. Candidates use
- *  one total order across every process: unrejected before rejected, a sibling
- *  finalized into this worktree before an older in-place binding, then seat ref. */
+ *  worktree, or non-active) is NEVER surfaced as a live binding. Persisted bind
+ *  order is authoritative across processes; an unorderable legacy duplicate
+ *  fails closed rather than selecting an identity or inbox path. */
 export async function getActiveSeatForWorktree(worktree: string): Promise<SeatRecord | null> {
   const store = await readStore();
   const candidates = Object.entries(store.seats)
     .filter(([ref, record]) =>
-      record.state === 'active' && record.worktree === worktree && seatRef(record) === ref)
-    .sort(([leftRef, left], [rightRef, right]) => {
-      const rejectionOrder = Number(rejectedSeatRefs.has(leftRef)) - Number(rejectedSeatRefs.has(rightRef));
-      if (rejectionOrder !== 0) return rejectionOrder;
-      const operationOrder = Number(left.operation.kind === 'seat') - Number(right.operation.kind === 'seat');
-      if (operationOrder !== 0) return operationOrder;
-      return leftRef < rightRef ? -1 : leftRef > rightRef ? 1 : 0;
-    });
+      record.state === 'active' && record.worktree === worktree && seatRef(record) === ref);
+  if (candidates.length > 1) throw new AmbiguousSeatBindingError(worktree);
   return candidates[0]?.[1] ?? null;
 }
 
-/** Deprioritize an exact seat after a definitive server auth or eviction verdict. */
+/** Remember a definitive server auth or eviction verdict in this process only. */
 export function markSeatRejected(ref: string): void {
   if (REF_RE.test(ref)) rejectedSeatRefs.add(ref);
 }