borgmcp 1.1.14 → 2.0.1

package/src/launch-all-discovery.ts

@@ -0,0 +1,118 @@
+// gh#556 Part 2 — drone-worktree discovery for `borg launch-all`.
+//
+// Scheme-agnostic: enumerates `git worktree list --porcelain` (the authoritative
+// source covering BOTH old sibling paths and new ~/.borg/worktrees/<repo>/<name>
+// paths from Part 1) and cross-references ~/.config/borgmcp/cubes.json, keeping
+// only worktrees whose saved identity has cubeId === target.
+
+import type { LaunchAllDeps, RunSyncFn } from './launch-all-deps.js';
+
+export interface DroneCandidate {
+  worktreeDir: string;
+  cubeId: string;
+  droneId: string;
+  droneLabel: string;
+  sessionToken: string;
+  apiUrl: string;
+  serverTrustIdentity?: string;
+}
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function isUuid(s: string): boolean {
+  return UUID_RE.test(s);
+}
+
+/**
+ * --only TIER-1 (local, no server call): exact case-insensitive droneLabel match,
+ * OR droneLabel prefix match (`--only drone` matches `drone-1`, `drone-2`, ...).
+ * Tier-2 (role-name) matching is best-effort in the orchestrator (spec §8.4).
+ */
+export function matchesOnlyLabel(droneLabel: string, only: string): boolean {
+  const l = droneLabel.toLowerCase();
+  const o = only.toLowerCase();
+  return l === o || l.startsWith(o);
+}
+
+/**
+ * Enumerate the LINKED worktree paths from `git worktree list --porcelain`,
+ * dropping the main worktree (always block[0]). Throws a user-readable error if
+ * the command fails (not inside a git repo).
+ */
+export function enumerateLinkedWorktrees(runSync: RunSyncFn): string[] {
+  let raw: string;
+  try {
+    raw = runSync('git', ['worktree', 'list', '--porcelain']);
+  } catch (e) {
+    throw new Error(
+      `launch-all: git worktree list failed — must be run from inside a git repository\n` +
+        `  (inner: ${e instanceof Error ? e.message : String(e)})`
+    );
+  }
+  const blocks = raw.trim().split(/\n\n+/);
+  // blocks[0] is the main worktree — always drop it.
+  return blocks
+    .slice(1)
+    .map((block) => {
+      const m = block.match(/^worktree (.+)$/m);
+      return m ? m[1].trim() : null;
+    })
+    .filter((p): p is string => p !== null);
+}
+
+export interface DiscoverOpts {
+  targetCubeId: string;
+  /** --only filter (tier-1 label match applied here). */
+  only?: string;
+}
+
+/**
+ * Full discovery pipeline (spec §3.5): enumerate → cubes.json lookup → filter
+ * (dir-present / has-entry / cubeId-match / UUID-valid / --only) → candidates in
+ * stable porcelain order.
+ */
+export async function discoverDroneCandidates(
+  opts: DiscoverOpts,
+  deps: LaunchAllDeps
+): Promise<DroneCandidate[]> {
+  const worktreePaths = enumerateLinkedWorktrees((cmd, args) => deps.runSync(cmd, args));
+  const identities = await deps.readAllProjectIdentities();
+  const byPath = new Map(identities.map((e) => [e.projectPath, e.cube]));
+
+  const candidates: DroneCandidate[] = [];
+  for (const worktreeDir of worktreePaths) {
+    // 1. directory not present on disk (orphaned worktree)
+    if (!deps.pathExists(worktreeDir)) {
+      deps.stderr(
+        `skipping ${worktreeDir}: directory not found (orphaned worktree — run \`git worktree prune\`)\n`
+      );
+      continue;
+    }
+    // 2. no cubes.json entry → not a drone worktree; skip silently
+    const cube = byPath.get(worktreeDir);
+    if (!cube) continue;
+    // 3. cubeId mismatch → different cube; skip silently
+    if (cube.cubeId !== opts.targetCubeId) continue;
+    // 4. malformed entry (cubeId/droneId not UUID) → warn + skip
+    if (!isUuid(cube.cubeId) || !isUuid(cube.droneId)) {
+      deps.stderr(
+        `skipping ${worktreeDir}: its saved seat has a malformed cubeId/droneId — re-assimilate to fix\n`
+      );
+      continue;
+    }
+    // 5. --only filter (tier-1 label) → skip silently (counted in the filter report)
+    if (opts.only !== undefined && !matchesOnlyLabel(cube.droneLabel, opts.only)) continue;
+
+    candidates.push({
+      worktreeDir,
+      cubeId: cube.cubeId,
+      droneId: cube.droneId,
+      droneLabel: cube.droneLabel,
+      sessionToken: cube.sessionToken,
+      apiUrl: cube.apiUrl,
+      ...(cube.serverTrustIdentity === undefined
+        ? {}
+        : { serverTrustIdentity: cube.serverTrustIdentity }),
+    });
+  }
+  return candidates;
+}

package/src/launch-all-locks.ts

@@ -0,0 +1,74 @@
+// gh#556 Part 2 — per-worktree launch lock markers (spec §6).
+//
+// Timestamp-based markers (the agent PID is not synchronously available when
+// `borg assimilate --here` is dispatched via tmux send-keys). A marker <5min old
+// means the seat appears live → skip unless --force. Markers are never deleted by
+// launch-all itself; the next invocation sweeps mtime-stale (>5min) markers.
+
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import type { LaunchAllDeps } from './launch-all-deps.js';
+
+export const LOCK_STALE_MS = 5 * 60 * 1000;
+
+/** SHA-1 hex of the worktree abs path → fixed-length collision-safe filename. */
+export function worktreeLockName(absPath: string): string {
+  return createHash('sha1').update(absPath, 'utf8').digest('hex');
+}
+
+export function locksDir(homeDir: string, cubeId: string): string {
+  return join(homeDir, '.config', 'borgmcp', 'locks', cubeId);
+}
+
+export function lockPath(homeDir: string, cubeId: string, absPath: string): string {
+  return join(locksDir(homeDir, cubeId), worktreeLockName(absPath) + '.pid');
+}
+
+export interface LockMarker {
+  launchedAt: string;
+  droneLabel: string;
+  worktreeDir: string;
+}
+
+/** Write the launch marker (mkdir -p the cube's locks dir first). Mode 0o600. */
+export function writeLockMarker(
+  deps: LaunchAllDeps,
+  cubeId: string,
+  droneLabel: string,
+  worktreeDir: string,
+  launchedAtISO: string
+): void {
+  deps.mkdirp(locksDir(deps.homedir(), cubeId));
+  const marker: LockMarker = { launchedAt: launchedAtISO, droneLabel, worktreeDir };
+  deps.writeFile(lockPath(deps.homedir(), cubeId, worktreeDir), JSON.stringify(marker), 0o600);
+}
+
+/** Delete mtime-stale (>5min) `.pid` markers in locks/<cubeId>/ (crash cleanup). */
+export function sweepStaleLocks(deps: LaunchAllDeps, cubeId: string, nowMs: number): void {
+  const dir = locksDir(deps.homedir(), cubeId);
+  for (const name of deps.listDir(dir)) {
+    if (!name.endsWith('.pid')) continue;
+    const p = join(dir, name);
+    const mtime = deps.statMtime(p);
+    if (mtime !== null && nowMs - mtime > LOCK_STALE_MS) deps.unlinkOpt(p);
+  }
+}
+
+/** True iff a fresh (<=5min by its launchedAt content) marker exists for the seat. */
+export function isLockLive(
+  deps: LaunchAllDeps,
+  cubeId: string,
+  worktreeDir: string,
+  nowMs: number
+): { live: boolean; launchedAt?: string } {
+  const raw = deps.readFileOpt(lockPath(deps.homedir(), cubeId, worktreeDir));
+  if (raw === null) return { live: false };
+  try {
+    const marker = JSON.parse(raw) as LockMarker;
+    const t = Date.parse(marker.launchedAt);
+    if (!Number.isFinite(t)) return { live: false };
+    return { live: nowMs - t <= LOCK_STALE_MS, launchedAt: marker.launchedAt };
+  } catch {
+    return { live: false };
+  }
+}

package/src/launch-gate.ts

@@ -0,0 +1,80 @@
+/**
+ * gh#673 P1 — the borg-launch ACTIVATION gate (WI-4 + WI-5-claude).
+ *
+ * The `borg` wrapper sets BORG_SESSION=1 in the agent's launch env
+ * (claude.ts / assimilate-cmd.ts launchEnv — same pattern as
+ * BORG_CODEX_REMOTE_WAKE). Claude Code spawns the borg-mcp MCP child and
+ * runs hook commands with that env inherited, so four activation bins
+ * gate on it:
+ *   1. the MCP tool surface (index.ts CallTool top) — a vanilla session
+ *      gets a non-silent re-launch notice per tool, never a half-success;
+ *   2. the borg-regen SessionStart hook bin — exit-0 no-op;
+ *   3. the borg-clear-rewake clear-only hook bin — exit-0 no-op;
+ *   4. the borg-log-audit UserPromptSubmit hook bin — exit-0 no-op.
+ * Result: `claude` launched directly is vanilla Claude Code; `borg`
+ * launches get the full surface.
+ *
+ * Codex (V2/V2b probes): codex does NOT forward parent env to MCP
+ * children — only the pinned [mcp_servers.borg.env] list — so simple
+ * launchEnv inheritance can't deliver the marker there. But a
+ * PER-INVOCATION `-c 'mcp_servers.borg.env.BORG_SESSION="1"'` config
+ * override DOES reach the child (V2b-proven). The borg wrapper appends
+ * `codexBorgSessionConfigArgs()` to every codex launch, so codex rides
+ * the exact same isBorgSession() gate: vanilla codex children lack the
+ * var and gate dormant; borg-launched children carry it. The codex
+ * SessionStart hook bin gates via the codex PROCESS env, which the
+ * wrapper's launchEnv marks directly.
+ *
+ * SR-BINDING (1482e7f9): BORG_SESSION is ACTIVATION-ONLY. It is
+ * user-settable by design (manual BORG_SESSION=1 is a supported override
+ * for power users/tests) and MUST NEVER be consulted for an access or
+ * security decision — server-side drone-session auth is the
+ * security boundary and is unchanged by this gate.
+ */
+
+import { envToggleOn } from './auth-env.js';
+import { debugLog } from './debug.js';
+
+export const BORG_SESSION_ENV = 'BORG_SESSION';
+
+/** True when this process runs inside a borg-launched session. */
+export function isBorgSession(env: NodeJS.ProcessEnv = process.env): boolean {
+  return envToggleOn(env[BORG_SESSION_ENV]);
+}
+
+/**
+ * The non-silent per-tool notice a vanilla (non-borg-launched) session
+ * receives when invoking a borg_* tool. Explains the state — nothing is
+ * wrong with the cube — and points at the borg launch path.
+ */
+export function borgSessionToolNotice(toolName: string): string {
+  return (
+    `◼ ${toolName} is inactive: this session wasn't launched via \`borg\`, so the borg ` +
+    `coordination surface is dormant (vanilla Claude Code). To use cube coordination, ` +
+    `re-launch from a terminal with \`borg\` (or \`borg assimilate\` to set up a seat first). ` +
+    `Power users can opt in manually by launching with BORG_SESSION=1.`
+  );
+}
+
+/**
+ * The per-invocation codex config override that injects BORG_SESSION into
+ * the codex-spawned borg-mcp child's pinned env (V2b-proven mechanism —
+ * inherited env never reaches codex MCP children). Appended to the codex
+ * launch args by both launch sites (claude.ts + assimilate-cmd.ts).
+ * TOML string value, hence the inner quotes.
+ */
+export function codexBorgSessionConfigArgs(): string[] {
+  return ['-c', `mcp_servers.borg.env.${BORG_SESSION_ENV}="1"`];
+}
+
+/**
+ * Gate decision with BORG_DEBUG observability — one funnel so every bin
+ * logs refusals the same way.
+ */
+export function gateAllowsActivation(surface: string, env: NodeJS.ProcessEnv = process.env): boolean {
+  const allowed = isBorgSession(env);
+  if (!allowed) {
+    debugLog(`launch-gate: ${surface} dormant — BORG_SESSION absent (not a borg-launched session; gh#673)`);
+  }
+  return allowed;
+}

package/src/lifecycle-log-guard.ts

@@ -0,0 +1,144 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+const STATE_FILE = join(homedir(), '.config', 'borgmcp', 'lifecycle-log-state.json');
+const ARRIVAL_DUPLICATE_WINDOW_MS = 10 * 60 * 1000;
+
+export type LifecycleSignal = 'arrival' | 'ready';
+
+export interface LifecycleLogSubject {
+  cubeId: string;
+  droneId: string;
+}
+
+interface LifecycleStateEntry {
+  lastArrival?: {
+    message: string;
+    at: string;
+  };
+  idleReady?: {
+    message: string;
+    open: boolean;
+    at: string;
+  };
+}
+
+interface LifecycleStateFile {
+  entries: Record<string, LifecycleStateEntry>;
+}
+
+export function lifecycleSignalForMessage(message: string): LifecycleSignal | null {
+  if (message.startsWith('ARRIVAL: ')) return 'arrival';
+  if (
+    message.startsWith('READY: ') &&
+    message.includes('capacity clean') &&
+    message.includes('awaiting next dispatch')
+  ) {
+    return 'ready';
+  }
+  return null;
+}
+
+function stateKey(subject: LifecycleLogSubject): string {
+  return `${subject.cubeId}:${subject.droneId}`;
+}
+
+async function readState(): Promise<LifecycleStateFile> {
+  try {
+    const raw = await readFile(STATE_FILE, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (
+      parsed &&
+      typeof parsed === 'object' &&
+      parsed.entries &&
+      typeof parsed.entries === 'object' &&
+      !Array.isArray(parsed.entries)
+    ) {
+      return parsed as LifecycleStateFile;
+    }
+  } catch (err: any) {
+    if (err?.code !== 'ENOENT') throw err;
+  }
+  return { entries: {} };
+}
+
+async function writeState(state: LifecycleStateFile): Promise<void> {
+  await mkdir(dirname(STATE_FILE), { recursive: true });
+  await writeFile(STATE_FILE, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
+}
+
+export function shouldSuppressLifecycleLogFromState(
+  message: string,
+  state: LifecycleStateEntry | undefined,
+  nowMs: number = Date.now()
+): { suppress: boolean; signal: LifecycleSignal | null } {
+  const signal = lifecycleSignalForMessage(message);
+  if (!signal) return { suppress: false, signal: null };
+
+  if (signal === 'arrival') {
+    const lastArrivalAt = state?.lastArrival?.at
+      ? new Date(state.lastArrival.at).getTime()
+      : NaN;
+    const isRecent =
+      Number.isFinite(lastArrivalAt) &&
+      nowMs - lastArrivalAt < ARRIVAL_DUPLICATE_WINDOW_MS;
+    return {
+      suppress: state?.lastArrival?.message === message && isRecent,
+      signal,
+    };
+  }
+
+  return {
+    suppress: state?.idleReady?.open === true && state.idleReady.message === message,
+    signal,
+  };
+}
+
+export async function shouldSuppressLifecycleLog(
+  subject: LifecycleLogSubject,
+  message: string
+): Promise<{ suppress: boolean; signal: LifecycleSignal | null }> {
+  const state = await readState();
+  return shouldSuppressLifecycleLogFromState(
+    message,
+    state.entries[stateKey(subject)]
+  );
+}
+
+export function nextLifecycleStateAfterLog(
+  message: string,
+  current: LifecycleStateEntry | undefined,
+  nowIso: string = new Date().toISOString()
+): LifecycleStateEntry {
+  const signal = lifecycleSignalForMessage(message);
+  if (signal === 'arrival') {
+    return {
+      ...current,
+      lastArrival: { message, at: nowIso },
+    };
+  }
+  if (signal === 'ready') {
+    return {
+      ...current,
+      idleReady: { message, open: true, at: nowIso },
+    };
+  }
+  if (current?.idleReady?.open) {
+    return {
+      ...current,
+      idleReady: { ...current.idleReady, open: false, at: nowIso },
+    };
+  }
+  return current ?? {};
+}
+
+export async function recordLifecycleLog(
+  subject: LifecycleLogSubject,
+  message: string
+): Promise<void> {
+  const state = await readState();
+  const key = stateKey(subject);
+  state.entries[key] = nextLifecycleStateAfterLog(message, state.entries[key]);
+  await writeState(state);
+}

package/src/list-roles-render.ts

@@ -0,0 +1,52 @@
+/**
+ * Sprint 6 / gh#153 — pure render function for `borg_list-roles` MCP tool.
+ *
+ * Extracted from the inline `case 'borg_list-roles'` handler in
+ * `index.ts` per drone-3's QA-FAIL 2026-05-18T13:27:53Z so the render
+ * logic is unit-testable without exercising the full MCP tool dispatch
+ * stack. The handler simply calls `renderRoleList(roles, cubeId)` and
+ * returns its output.
+ */
+
+export interface RoleForRender {
+  id: string;
+  name: string;
+  short_description?: string;
+  is_default?: boolean;
+  is_mandatory?: boolean;
+  is_human_seat?: boolean;
+  can_broadcast?: boolean;
+  receives_all_direct?: boolean;
+  role_class?: string;
+}
+
+/**
+ * Render the role registry for a cube as a markdown list with role IDs
+ * exposed for use with `borg_reassign-drone`. Returns the empty-roles
+ * placeholder when the input array is empty.
+ *
+ * Each role line shape:
+ *   - **<name>**(<tags>) `<uuid>` — <description>
+ *
+ * Tags collected in order: Queen, human-seat, default, mandatory, can-broadcast,
+ * receives-all-direct. Joined with `, `; suffix omitted entirely when no tags apply.
+ */
+export function renderRoleList(roles: RoleForRender[], cubeId: string): string {
+  if (!roles.length) {
+    return 'No roles in this cube yet.';
+  }
+  const lines = roles.map((r) => {
+    const tags = [
+      r.role_class === 'queen' ? 'Queen' : null,
+      r.is_human_seat ? 'human-seat' : null,
+      r.is_default ? 'default' : null,
+      r.is_mandatory ? 'mandatory' : null,
+      r.can_broadcast ? 'can-broadcast' : null,
+      r.receives_all_direct ? 'receives-all-direct' : null,
+    ].filter(Boolean).join(', ');
+    const tagSuffix = tags ? ` (${tags})` : '';
+    const desc = r.short_description || '_(no description)_';
+    return `- **${r.name}**${tagSuffix} \`${r.id}\` — ${desc}`;
+  });
+  return `Roles in cube ${cubeId} (${roles.length}):\n\n${lines.join('\n')}\n\nUse the role IDs above with \`borg_reassign-drone\` to change a drone's role.`;
+}

package/src/local-log-routing.ts

@@ -0,0 +1,106 @@
+import { roleSlug } from './role-resolver.js';
+
+export interface LocalRoutingDrone {
+  id: string;
+  label?: string | null;
+  role_id?: string | null;
+}
+
+export interface LocalRoutingRole {
+  id: string;
+  name: string;
+  is_human_seat?: boolean;
+}
+
+/**
+ * Resolve the public `borg_log to:` addressing forms against the local
+ * server's authoritative cube roster. This intentionally mirrors the hosted
+ * route resolver: exact drone id/label first, then displayed short UUID, then
+ * role name/slug expansion. Every failure is closed before the log POST so a
+ * miss can never degrade into a broadcast.
+ */
+export function resolveLocalLogRecipients(
+  recipients: readonly string[],
+  drones: readonly LocalRoutingDrone[],
+  roles: readonly LocalRoutingRole[],
+): string[] {
+  const ids = new Set<string>();
+
+  for (const recipient of recipients) {
+    if (recipient === '@human-seat') {
+      const roleIds = new Set(
+        roles.filter((role) => role.is_human_seat === true).map((role) => role.id),
+      );
+      const matches = drones.filter((drone) =>
+        drone.role_id !== null && drone.role_id !== undefined && roleIds.has(drone.role_id)
+      );
+      if (roleIds.size === 0 || matches.length === 0) {
+        throw new Error(
+          'Direct-message role recipient has no active drones: @human-seat. ' +
+          'Use borg_roster to find active recipients, or omit to broadcast if your role can broadcast.',
+        );
+      }
+      for (const drone of matches) ids.add(drone.id);
+      continue;
+    }
+
+    const droneMatches = drones.filter(
+      (drone) => drone.id === recipient || drone.label === recipient,
+    );
+    const uniqueDroneIds = [...new Set(droneMatches.map((drone) => drone.id))];
+    if (uniqueDroneIds.length > 1) {
+      throw new Error(
+        `Ambiguous direct-message recipient: ${recipient} matches multiple drones`,
+      );
+    }
+    if (uniqueDroneIds.length === 1) {
+      ids.add(uniqueDroneIds[0]!);
+      continue;
+    }
+
+    const shortUuid = recipient.replace(/`/g, '').replace(/^id:/i, '').toLowerCase();
+    if (/^[0-9a-f]{8,}$/.test(shortUuid)) {
+      const prefixMatches = drones.filter((drone) =>
+        drone.id.toLowerCase().startsWith(shortUuid)
+      );
+      const uniquePrefixIds = [...new Set(prefixMatches.map((drone) => drone.id))];
+      if (uniquePrefixIds.length > 1) {
+        const listed = prefixMatches
+          .map((drone) => `${drone.id} (${drone.label ?? 'unlabeled'})`)
+          .join(', ');
+        throw new Error(
+          `Ambiguous short-uuid recipient: ${recipient} matches multiple drones — ${listed}. ` +
+          'Address by the full drone id.',
+        );
+      }
+      if (uniquePrefixIds.length === 1) {
+        ids.add(uniquePrefixIds[0]!);
+        continue;
+      }
+    }
+
+    const roleMatches = roles.filter((role) => roleSlug(role.name) === roleSlug(recipient));
+    const uniqueRoleIds = [...new Set(roleMatches.map((role) => role.id))];
+    if (uniqueRoleIds.length > 1) {
+      throw new Error(
+        `Ambiguous direct-message recipient: ${recipient} matches multiple roles`,
+      );
+    }
+    if (uniqueRoleIds.length === 0) {
+      throw new Error(
+        `Unknown direct-message recipient: ${recipient}. ` +
+        'Use an exact drone label, drone id, role name, or role slug.',
+      );
+    }
+    const roleDrones = drones.filter((drone) => drone.role_id === uniqueRoleIds[0]);
+    if (roleDrones.length === 0) {
+      throw new Error(
+        `Direct-message role recipient has no active drones: ${recipient}. ` +
+        'Use borg_roster to find active recipients, or omit to broadcast if your role can broadcast.',
+      );
+    }
+    for (const drone of roleDrones) ids.add(drone.id);
+  }
+
+  return [...ids];
+}

package/src/local-manage-tool-result.ts

@@ -0,0 +1,10 @@
+import { LocalManageRequiredError } from './server-errors.js';
+
+export function formatLocalManageToolResult(error: unknown) {
+  if (!(error instanceof LocalManageRequiredError)) return null;
+
+  return {
+    content: [{ type: 'text' as const, text: error.message }],
+    isError: true as const,
+  };
+}