borgmcp 4.6.2 → 4.8.0

package/src/cli-help.ts

@@ -172,6 +172,7 @@ export function topLevelHelpText(version: string): string {
     `  borg                     Show the launch menu in a repository root; resume directly in a linked worktree\n` +
     `  borg setup               Set up borg MCP server + agent CLI integration\n` +
     `  borg update              Update the client and installed local server together\n` +
+    `  borg upgrade             Alias for borg update\n` +
     `  borg doctor              Check agent hook commands, OpenCode integration, and startup diagnostics\n` +
     `  borg clone <url> [dir]   Clone a repository, then create and launch its cube\n` +
     `  borg quickstart          Create a cube and a drone for every role, then launch them\n` +

package/src/codex-launch.ts

@@ -1,5 +1,6 @@
 import type { BorgCli } from './cubes.js';
-import { wakePathArming, type AgentKind } from './regen-format.js';
+import type { AgentKind } from './agent-runtime.js';
+import { wakePathArming } from './regen-format.js';
 import { OPENCODE_WAKE_PATH_GUIDANCE } from './opencode-wake-copy.js';
 
 /**

package/src/config.ts

@@ -31,7 +31,8 @@ const SERVER_CREDENTIAL_RECORD_VERSION = 2 as const;
 const SERVER_PENDING_ENROLLMENT_RECORD_VERSION = 3 as const;
 const LEGACY_SERVER_PENDING_ENROLLMENT_RECORD_VERSION = 1 as const;
 const SERVER_ACCEPTED_ENROLLMENT_MARKER_VERSION = 1 as const;
-const SERVER_CUBE_RETRY_RECORD_VERSION = 2 as const;
+const SERVER_CUBE_RETRY_RECORD_VERSION = 3 as const;
+const LEGACY_SERVER_CUBE_RETRY_RECORD_VERSION = 2 as const;
 // The 0600 credential store (Queen rescope: replaces the OS keychain). A single
 // file holds every parent credential/enrollment record; a single flock
 // serializes every mutator + observer that must (SR-seven #4).
@@ -326,7 +327,7 @@ async function writeServerCredentialRecord(
   }
   if (backend.entries) {
     const accounts = await backend.entries();
-    const conflicts = Object.entries(accounts).filter(([account, value]) => {
+    const conflicts = Object.entries(accounts).filter(([, value]) => {
       try {
         const parsed = JSON.parse(value) as { version?: unknown; origin?: unknown };
         return parsed.version === SERVER_CREDENTIAL_RECORD_VERSION && parsed.origin === record.origin;
@@ -1106,39 +1107,74 @@ export async function getOrCreatePendingServerCubeCreation(
   return withCredentialStoreLock(async () => {
     const stored = await backend.get(account);
     if (stored) {
+      let record: Omit<Partial<PendingServerCubeCreationRecord>, 'template'> & {
+        version?: unknown;
+        state?: unknown;
+        template?: unknown;
+      };
       try {
-        const record = JSON.parse(stored) as Partial<PendingServerCubeCreationRecord> & {
-          version?: unknown;
-          state?: unknown;
+        const parsed: unknown = JSON.parse(stored);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('invalid record');
+        record = parsed as typeof record;
+      } catch {
+        throw new Error('pending Borg server cube creation does not match this repository');
+      }
+      const retryKey = typeof record.retryKey === 'string' && UUID_RE.test(record.retryKey)
+        ? record.retryKey
+        : null;
+      const sameOperation =
+        record.state === 'pending' &&
+        record.origin === input.origin &&
+        record.trustIdentity === input.trustIdentity &&
+        record.clientId === input.clientId &&
+        record.repositoryBinding === repositoryBinding &&
+        record.name === input.name &&
+        record.workingRepoName === input.workingRepoName &&
+        retryKey !== null;
+      if (sameOperation && record.version === SERVER_CUBE_RETRY_RECORD_VERSION && record.template === input.template) {
+        return {
+          origin: input.origin,
+          trustIdentity: input.trustIdentity,
+          clientId: input.clientId,
+          repositoryBinding,
+          retryKey,
+          name: input.name,
+          workingRepoName: input.workingRepoName,
+          repository: input.repository,
+          template: input.template,
         };
-        if (
-          record.version !== SERVER_CUBE_RETRY_RECORD_VERSION ||
-          record.state !== 'pending' ||
-          record.origin !== input.origin ||
-          record.trustIdentity !== input.trustIdentity ||
-          record.clientId !== input.clientId ||
-          record.repositoryBinding !== repositoryBinding ||
-          record.name !== input.name ||
-          record.workingRepoName !== input.workingRepoName ||
-          record.template !== input.template ||
-          typeof record.retryKey !== 'string' || !UUID_RE.test(record.retryKey)
-        ) {
-          throw new Error('mismatch');
+      }
+      if (sameOperation && record.version === LEGACY_SERVER_CUBE_RETRY_RECORD_VERSION) {
+        const preserveRetryKey = record.template === input.template;
+        if (!preserveRetryKey && record.template !== 'default') {
+          throw new Error('pending Borg server cube creation does not match this repository');
         }
-        return {
+        const replacement: PendingServerCubeCreationRecord = {
           origin: input.origin,
           trustIdentity: input.trustIdentity,
           clientId: input.clientId,
           repositoryBinding,
-          retryKey: record.retryKey,
+          retryKey: preserveRetryKey ? retryKey : randomUUID(),
           name: input.name,
           workingRepoName: input.workingRepoName,
           repository: input.repository,
           template: input.template,
         };
-      } catch {
-        throw new Error('pending Borg server cube creation does not match this repository');
+        await backend.set(account, JSON.stringify({
+          version: SERVER_CUBE_RETRY_RECORD_VERSION,
+          state: 'pending',
+          origin: replacement.origin,
+          trustIdentity: replacement.trustIdentity,
+          clientId: replacement.clientId,
+          repositoryBinding: replacement.repositoryBinding,
+          retryKey: replacement.retryKey,
+          name: replacement.name,
+          workingRepoName: replacement.workingRepoName,
+          template: replacement.template,
+        }));
+        return replacement;
       }
+      throw new Error('pending Borg server cube creation does not match this repository');
     }
     const record: PendingServerCubeCreationRecord = {
       origin: input.origin,

package/src/cubes.ts

@@ -498,16 +498,6 @@ export async function findRemainingActiveSeatForWorktree(worktree: string): Prom
   return record ? { apiUrl: record.origin, operation: record.operation } : null;
 }
 
-/**
- * Legacy binding-only writer. In the collapsed single-store model an ACTIVE seat is
- * created ONLY by the atomic mint→activate+bind path in seats.ts (driven by the
- * attach FINALIZE); there is no standalone binding write. Retained solely as a
- * fail-closed guard for incomplete session metadata.
- */
-export async function setActiveCube(_active: ActiveCubeInput): Promise<void> {
-  throw new Error('local Borg server session metadata is incomplete');
-}
-
 export function activeCubeWithFreshRegenIdentity(
   active: ActiveCube,
   result: {

package/src/docs-sections.ts

@@ -40,7 +40,7 @@ export const DOCS_SECTIONS: DocsSection[] = [
     title: "Core concepts",
     url: `${SITE_URL}/docs/concepts/`,
     summary: "Cubes, drones, roles, activity-log signals, explicit audiences, claims, and decisions.",
-    keywords: ["cube", "drone", "role", "log", "signal", "claim", "decision", "coordinate", "coordination", "routing", "recipient", "audience", "selector", "direct", "broadcast"],
+    keywords: ["cube", "drone", "role", "log", "signal", "claim", "decision", "coordinate", "coordination", "routing", "recipient", "audience", "selector", "direct", "broadcast", "refs", "sha", "provenance"],
   },
   {
     slug: "install",

package/src/gc-orphan-inboxes.ts

@@ -14,7 +14,7 @@
  * always err toward KEEPING.
  */
 import { spawnSync } from 'node:child_process';
-import { readFileSync, readdirSync, statSync, unlinkSync } from 'node:fs';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import {
   pidfilePathFor,

package/src/index.ts

@@ -67,6 +67,7 @@ import {
   formatDocumentMetadata,
 } from './document-render.js';
 import {
+  NEW_CUBE_TEMPLATE_PRESENTATIONS,
   getTemplate,
   listTemplateNames,
   resolveCubeDirectiveForCreate,
@@ -117,6 +118,13 @@ import {
   renderRuntimeMetadataLines,
 } from './roster-render.js';
 import { resolveWorkingRepo } from './working-repo.js';
+import {
+  auditMessageShas,
+  renderProvenance,
+  requiresRefs,
+  resolveRefs,
+  validateRefs,
+} from './log-provenance.js';
 import {
   CubeDeletedError,
   DroneEvictedError,
@@ -176,27 +184,6 @@ import {
 
 const OPEN_CODE_IDENTITY_HANDSHAKE_TIMEOUT_MS = 5_000;
 
-/**
- * Apply a template's roles + message_taxonomy to a cube.
- *
- * Client-orchestrated through the server's non-clobbering role and taxonomy
- * primitives. New roles are inserted; existing template-named roles get ADD
- * fragments (template sections/classes the cube lacks) auto-applied, but
- * EVOLVED (conflicting) fragments are kept — never silently overwritten. The
- * old per-role blanket `updateRole`/whole-taxonomy `updateCube` overwrite path
- * is removed. Operators who want to take the template version of a conflicting
- * fragment use `borg_sync-roles` with a `decisions` map. Primitive operations
- * are sequential, so a later failure can leave earlier changes committed.
- * Returns `{ created, updated }` for the caller's toast.
- */
-async function applyTemplateToCube(
-  cubeId: string,
-  template: Template,
-  authority?: LocalManageAuthority,
-): Promise<{ created: number; updated: number }> {
-  return await applyTemplate(cubeId, template.name, authority);
-}
-
 export async function runApplyTemplateTool(
   cubeId: string,
   template: Template,
@@ -1039,13 +1026,21 @@ export async function main() {
           const to = normalizeLogAudience(args?.to);
           const active = await getActiveCube();
           if (!active) throw new Error('Not assimilated to a cube. Use borg_assimilate <cube-name> first.');
+          const refs = validateRefs(args?.refs);
+          if (requiresRefs(message) && refs.length === 0) {
+            throw new Error('REVIEW-READY messages require refs. Pass refs: ["HEAD", "origin/<branch>", "origin/main"].');
+          }
+          const repository = active.worktree ?? findProjectRoot();
+          const shaAudit = auditMessageShas(message, repository);
+          if (shaAudit.refusal) throw new Error(shaAudit.refusal);
+          const finalMessage = `${message}${renderProvenance(resolveRefs(refs, repository))}`;
           seedDisplayIdentity(active);
           const displayIdentity = renderDisplayIdentity(active);
-          const lifecycleSignal = lifecycleSignalForMessage(message);
+          const lifecycleSignal = lifecycleSignalForMessage(finalMessage);
           if (lifecycleSignal) {
-            const decision = await shouldSuppressLifecycleLog(active, message);
+            const decision = await shouldSuppressLifecycleLog(active, finalMessage);
             if (decision.suppress) {
-              await recordLifecycleLog(active, message);
+              await recordLifecycleLog(active, finalMessage);
               if (lifecycleSignal === 'arrival') markArrivalAnnouncedThisProcess();
               return {
                 content: [
@@ -1075,8 +1070,8 @@ export async function main() {
             ...(documents ? { documents } : {}),
             serverTrustIdentity: active.serverTrustIdentity,
           };
-          const result = await appendLog(active.sessionToken, active.apiUrl, message, appendOpts);
-          await recordLifecycleLog(active, message);
+          const result = await appendLog(active.sessionToken, active.apiUrl, finalMessage, appendOpts);
+          await recordLifecycleLog(active, finalMessage);
           if (lifecycleSignal === 'arrival') markArrivalAnnouncedThisProcess();
           let recipientDrones: any[] = [];
           if (result.entry.visibility === 'direct' && result.entry.recipient_drone_ids.length > 0) {
@@ -1104,7 +1099,10 @@ export async function main() {
           const advisory = result.advisory?.code === 'STORE_AS_DOCUMENT'
             ? `\nAdvisory: this message exceeded ${result.advisory.threshold_bytes} UTF-8 bytes. Store durable detail with borg_put-document, then cite its full id in borg_log.documents with an explicit borg_log.to audience.`
             : '';
-          const text = `Logged to cube "${displayIdentity.cubeName}" as ${displayIdentity.droneLabel}. (entry id: ${result.entry.id})${routed}${unreachable}${citations}${advisory}`;
+          const shaAdvisory = shaAudit.unverified.length > 0
+            ? `\nAdvisory: unverified Git SHA(s): ${shaAudit.unverified.join(', ')}`
+            : '';
+          const text = `Logged to cube "${displayIdentity.cubeName}" as ${displayIdentity.droneLabel}. (entry id: ${result.entry.id})${routed}${unreachable}${citations}${advisory}${shaAdvisory}`;
           return {
             content: [{ type: 'text', text }],
             structuredContent: {
@@ -1257,18 +1255,15 @@ export async function main() {
         case 'borg_create-cube': {
           const name = args?.name as string;
           const cubeDirective = args?.cube_directive as string;
-          const templateName = args?.template as string | undefined;
+          const templateName = (args?.template as string | undefined) ?? NEW_CUBE_TEMPLATE_PRESENTATIONS[0].name;
           if (!name) throw new Error('name is required');
           if (cubeDirective === undefined) throw new Error('cube_directive is required (pass empty string if none)');
 
           // Resolve template (validates name early so the cube isn't
           // created in a partial state if the template name is wrong).
-          let template = null;
-          if (templateName) {
-            template = getTemplate(templateName);
-            if (!template) {
-              throw new Error(`Unknown template "${templateName}". Available: ${listTemplateNames().join(', ')}`);
-            }
+          const template = getTemplate(templateName);
+          if (!template) {
+            throw new Error(`Unknown template "${templateName}". Available: ${listTemplateNames().join(', ')}`);
           }
 
           // client#499: the cube binds to an EXPLICIT repository (no cwd
@@ -1286,6 +1281,7 @@ export async function main() {
           const resolvedCubeDirective = resolveCubeDirectiveForCreate(cubeDirective, template);
           const resolvedMessageTaxonomy = resolveMessageTaxonomyForCreate(undefined, template);
           const { result, cube } = await createCube(name, resolvedCubeDirective, {
+            template: template.name,
             message_taxonomy: resolvedMessageTaxonomy,
             repository,
             workingRepoName,
@@ -1302,30 +1298,19 @@ export async function main() {
             };
           }
 
-          // Apply template roles if requested. Merges by name: any role the
-          // server auto-seeded (e.g. "Drone") that the template doesn't
-          // also include stays put; templated roles upsert.
-          if (template) {
-            const summary = await applyTemplateToCube(cube.id, template);
-            const cubeDirectiveNote = resolvedCubeDirective !== cubeDirective
-              ? ' Template cube directive applied (operator passed empty).'
-              : '';
-            const text = `Created cube **${cube.name}** (id: ${cube.id}) with template **${templateName}** applied — ${summary.created} role(s) created, ${summary.updated} updated.${cubeDirectiveNote} Use borg_assimilate ${cube.name} to join as a drone.`;
-            return {
-              content: [{ type: 'text', text }],
-              structuredContent: {
-                cube,
-                result: 'created',
-                template: templateName,
-                roles_created: summary.created,
-                roles_updated: summary.updated,
-              },
-            };
-          }
-          const text = `Created cube **${cube.name}** (id: ${cube.id}). A default "Drone" role was seeded — rename or replace it via borg_update-role / borg_create-role / borg_delete-role. Use borg_assimilate ${cube.name} to join as a drone.`;
+          const cubeDirectiveNote = resolvedCubeDirective !== cubeDirective
+            ? ' Template cube directive applied (operator passed empty).'
+            : '';
+          const text = `Created cube **${cube.name}** (id: ${cube.id}) with template **${templateName}** applied atomically — ${cube.roles.length} role(s) created.${cubeDirectiveNote} Use borg_assimilate ${cube.name} to join as a drone.`;
           return {
             content: [{ type: 'text', text }],
-            structuredContent: { cube, result: 'created', template: null, roles_created: null, roles_updated: null },
+            structuredContent: {
+              cube,
+              result: 'created',
+              template: templateName,
+              roles_created: cube.roles.length,
+              roles_updated: 0,
+            },
           };
         }
 

package/src/log-provenance.ts

@@ -0,0 +1,119 @@
+import { spawnSync } from 'node:child_process';
+
+export interface GitResult {
+  status: number | null;
+  stdout?: string | null;
+  stderr?: string | null;
+  error?: Error;
+}
+
+export type RunGit = (cwd: string, args: string[]) => GitResult;
+
+export interface ResolvedRef {
+  ref: string;
+  sha: string;
+}
+
+const FULL_SHA_RE = /^[0-9a-f]{40}$/u;
+const MESSAGE_SHA_RE = /(?<![0-9a-f])[0-9a-f]{40}(?![0-9a-f])/gu;
+
+function defaultRunGit(cwd: string, args: string[]): GitResult {
+  const result = spawnSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    env: { ...process.env, LC_ALL: 'C' },
+  });
+  return {
+    status: result.status,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    error: result.error,
+  };
+}
+
+function gitFailure(result: GitResult, fallback: string): string {
+  if (result.error) {
+    if ((result.error as NodeJS.ErrnoException).code === 'ENOENT') return 'not a git repository';
+    return result.error.message.replace(/[\x00-\x1F\x7F]/gu, ' ').trim() || fallback;
+  }
+  return result.stderr?.replace(/[\x00-\x1F\x7F]/gu, ' ').trim() || fallback;
+}
+
+function resolveCommit(ref: string, cwd: string, runGit: RunGit): GitResult & { sha?: string } {
+  let result: GitResult;
+  try {
+    result = runGit(cwd, ['rev-parse', '--verify', '--quiet', '--end-of-options', `${ref}^{commit}`]);
+  } catch (error) {
+    return { status: null, error: error instanceof Error ? error : new Error(String(error)) };
+  }
+  const sha = result.status === 0 ? result.stdout?.trim() : undefined;
+  return FULL_SHA_RE.test(sha ?? '') ? { ...result, sha } : result;
+}
+
+export function validateRefs(value: unknown): string[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length < 1 || value.length > 8) {
+    throw new Error('refs must be an array of 1-8 unique Git refs');
+  }
+  const refs: string[] = [];
+  for (const valueRef of value) {
+    if (typeof valueRef !== 'string' || valueRef.length === 0) {
+      throw new Error('each refs entry must be a non-empty string');
+    }
+    if (Buffer.byteLength(valueRef, 'utf8') > 200) {
+      throw new Error(`Git ref exceeds 200 UTF-8 bytes: ${valueRef.slice(0, 40)}`);
+    }
+    if (valueRef.startsWith('-')) throw new Error(`Git ref must not start with "-": ${valueRef}`);
+    if (/[\s\x00-\x1F\x7F]/u.test(valueRef)) {
+      throw new Error(`Git ref must not contain whitespace or control characters: ${JSON.stringify(valueRef)}`);
+    }
+    if (refs.includes(valueRef)) throw new Error(`Git ref is duplicated: ${valueRef}`);
+    refs.push(valueRef);
+  }
+  return refs;
+}
+
+export function resolveRefs(
+  refs: string[],
+  cwd: string,
+  runGit: RunGit = defaultRunGit,
+): ResolvedRef[] {
+  return refs.map((ref) => {
+    const result = resolveCommit(ref, cwd, runGit);
+    if (!result.sha) {
+      throw new Error(`Could not resolve Git ref "${ref}": ${gitFailure(result, 'ref did not resolve to a commit')}`);
+    }
+    return { ref, sha: result.sha };
+  });
+}
+
+export function auditMessageShas(
+  message: string,
+  cwd: string,
+  runGit: RunGit = defaultRunGit,
+): { refusal?: string; unverified: string[] } {
+  const shas = [...new Set(message.match(MESSAGE_SHA_RE) ?? [])];
+  const unverified: string[] = [];
+  for (const sha of shas) {
+    if (resolveCommit(sha, cwd, runGit).sha) continue;
+    const prefixResult = resolveCommit(sha.slice(0, 7), cwd, runGit);
+    if (prefixResult.sha && prefixResult.sha !== sha) {
+      return {
+        refusal: `Message SHA ${sha} does not exist, but its 7-character prefix resolves to ${prefixResult.sha}. Pass Git refs through the refs parameter instead of typing a full SHA.`,
+        unverified,
+      };
+    }
+    if (!prefixResult.sha) unverified.push(sha);
+  }
+  return { unverified };
+}
+
+export function renderProvenance(resolved: ResolvedRef[]): string {
+  return resolved.length === 0
+    ? ''
+    : `\n\n${resolved.map(({ ref, sha }) => `${ref} = ${sha}`).join('\n')}`;
+}
+
+export function requiresRefs(message: string): boolean {
+  return /^REVIEW-READY(?:\b|$)/u.test(message);
+}

package/src/log-stream.ts

@@ -34,7 +34,7 @@ import {
   ErrorCode,
   type DocumentCitation,
 } from 'borgmcp-shared/protocol';
-import { getActiveCube, inboxPathForDrone } from './cubes.js';
+import { getActiveCube, inboxPathForDrone, type ActiveCube } from './cubes.js';
 import { assertUuidShape } from './evict-drone.js';
 import { loadBorgServerTrust } from './server-trust.js';
 import {
@@ -56,7 +56,6 @@ import {
   CODEX_HEARTBEAT_CADENCE_MS,
   fireCodexHeartbeatTick,
   formatCodexWakePrompt,
-  resolveSessionAgentKind,
   startCodexHeartbeat,
   wakeCodexViaAppServer,
 } from './codex-app-wake.js';
@@ -420,7 +419,7 @@ export interface StreamDeps {
     isSourcePending?: () => Promise<boolean>,
   ) => Promise<boolean>;
   /** Inspect whether one retry source remains beyond the durable unread cursor. */
-  hasPendingWakeEntry?: (active: ActiveCube, entryId: string) => Promise<boolean>;
+  hasPendingWakeEntry?: (active: StreamActiveCube, entryId: string) => Promise<boolean>;
   /** Clear in-process retry diagnostics after the durable entry is consumed. */
   settleOpenCodeEntry?: (sourceEntryId: string) => void;
 }
@@ -671,21 +670,17 @@ export function __runLoopForTest(testDeps: RunLoopTestDeps): Promise<void> {
 // Single SSE session (exported for tests)
 // ------------------------------------------------------------------
 
-export interface ActiveCube {
-  cubeId: string;
-  droneId: string;
-  sessionToken: string;
-  apiUrl: string;
-  serverTrustIdentity?: string;
-  localSessionCredentialRef?: string;
-  localSessionExpiresAt?: string | null;
-  worktree?: string;
-  droneLabel?: string;
-  name?: string;
-}
+/** Direct stream controls may omit metadata or omit trust to exercise fail-closed validation. */
+export type StreamActiveCube = Pick<
+  ActiveCube,
+  'cubeId' | 'droneId' | 'sessionToken' | 'apiUrl'
+> & Partial<Pick<
+  ActiveCube,
+  'serverTrustIdentity' | 'localSessionCredentialRef' | 'worktree' | 'droneLabel' | 'name'
+>>;
 
 export async function streamOnce(
-  active: ActiveCube,
+  active: StreamActiveCube,
   lastEventId: string | null,
   onEventId: (id: string) => void,
   deps: StreamDeps = {}
@@ -1271,7 +1266,7 @@ export async function streamOnce(
 }
 
 export async function streamOnceIfOwner(
-  active: ActiveCube,
+  active: StreamActiveCube,
   lastEventId: string | null,
   onEventId: (id: string) => void,
   deps: StreamDeps = {}

package/src/quickstart-cmd.ts

@@ -13,6 +13,7 @@ import { LAUNCH_ALL_NO_DISPATCH_EXIT_CODE, runLaunchAll } from './launch-all-cmd
 import type { QuickstartArgs } from './parse-quickstart-args.js';
 import { roleSlug, type Role } from './role-resolver.js';
 import { DEFAULT_LOCAL_SERVER_ORIGIN } from './server-handshake.js';
+import { repositoryDiscoveryFailureMessage } from './repository-identity.js';
 
 interface PlannedRole {
   name: string;
@@ -178,8 +179,15 @@ export async function runQuickstart(
   let context;
   try {
     context = await assimilate.resolveRepositoryContext(assimilate.cwd());
-  } catch {
-    context = null;
+  } catch (error) {
+    if (error instanceof Error && error.message === 'BARE_REPOSITORY') {
+      context = null;
+    } else {
+      deps.stderr(
+        `borg quickstart: could not inspect this Git repository: ${repositoryDiscoveryFailureMessage(error)}\n`,
+      );
+      return 1;
+    }
   }
   if (!context) {
     deps.stderr('borg quickstart: run this command inside a non-bare Git repository.\n');

package/src/regen-format.ts

@@ -21,6 +21,7 @@ import { formatDocumentCitations } from './document-render.js';
 import { shellEscape } from './shell-escape.js';
 import { OPENCODE_WAKE_PATH_GUIDANCE } from './opencode-wake-copy.js';
 import { isBorgSession } from './launch-gate.js';
+import type { AgentKind } from './agent-runtime.js';
 
 /**
  * Extract the SessionStart `source` from a Claude Code hook payload (gh#926).
@@ -72,9 +73,6 @@ export function shouldRelayPlainSessionReminder(args: {
   );
 }
 
-/** The agent runtime a session runs under — drives the wake-path branch. */
-export type AgentKind = 'claude' | 'codex' | 'opencode';
-
 /**
  * The agent-branched WAKE-PATH ARMING sub-block (gh#929/gh#927) — the single
  * shared "re-establish your wake path" instruction reused by the launch
@@ -242,6 +240,7 @@ export function markArrivalAnnouncedThisProcess(): void {
 //   acknowledgement-status query; this marker pins its required entry id.
 // copy-param-claim: borg_read-entry.entry_id
 // copy-param-claim: borg_log.to
+// copy-param-claim: borg_log.refs
 // copy-param-claim: borg_docs.topic
 //   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
@@ -263,14 +262,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>"]\` — append with an explicit audience
+- \`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_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 + SHA and nothing else; defect + location/evidence; correction to your live claim; or a genuine blocking question.
+- **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"]\`.
 - **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.
 
@@ -373,7 +372,7 @@ The discipline applies at FOUR surfaces. Catches at the surface closest to origi
 - 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 a ref and exact commit SHA, never a filesystem path. A reviewing seat checks out the SHA in its own worktree with \`git checkout --detach <SHA>\` and never reads another seat's folder.
+- 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\`.`;

package/src/regen.ts

@@ -24,10 +24,9 @@ import {
   formatLeanOrientation,
   formatPlainSessionReminder,
   shouldRelayPlainSessionReminder,
-  type AgentKind,
 } from './regen-format.js';
 import { resolveSessionAgentKind } from './codex-app-wake.js';
-import { resolveReportableSessionAgentKind } from './agent-runtime.js';
+import { resolveReportableSessionAgentKind, type AgentKind } from './agent-runtime.js';
 import { handleVersionFlag } from './version.js';
 import {
   BORG_LAUNCH_REMINDER_DISABLED_ENV,
@@ -177,7 +176,7 @@ async function emitUnassimilatedNotice(): Promise<void> {
   lines.push('');
   lines.push('## Tools you can call once the user has chosen');
   lines.push('- Join an existing cube: `borg_assimilate cube_name="<their choice>"`');
-  lines.push('- Create a new cube: `borg_create-cube name="<name>" cube_directive="<markdown>"` (optionally `template="software-dev"`)');
+  lines.push('- Create a new cube: `borg_create-cube name="<name>" cube_directive="<markdown>"` (defaults to `template="software-dev"`)');
   lines.push('- See available templates: `borg_list-templates`');
   process.stdout.write(lines.join('\n') + '\n');
 }