borgmcp 2.1.0 → 2.2.0

package/docs/LOCAL_SERVER.md

@@ -50,7 +50,7 @@ Options:
   --enroll                         Prompt for a hidden enrollment invitation
   --cube-name <name>               Repository cube name (otherwise edit the proposed name)
   --template software-dev|starter  New-cube template (default: software-dev)
-  --yes, -y                        Skip confirmation prompts
+  --yes, -y                        Accept new-cube defaults; never adopt by name
   --help, -h                       Show this help
 ```
 
@@ -91,14 +91,19 @@ exactly; the credential becomes active only after the versioned response is
 decoded and the authenticated protocol handshake succeeds. A new process
 resumes that pending enrollment before displaying another invitation prompt.
 
-`borg assimilate` and `borg server cube init` share one guided repository-cube
-flow. Borg shows the repository and server, proposes an editable name, offers
-the Software Development and Starter templates, and asks for one confirmation.
-`--cube-name <name>` and `--template software-dev|starter` supply those values
-directly; `--yes` accepts the repository default name and Software Development
-template. `borg server cube init` stops after authoritative cube readback and
-never creates a drone. Existing repository associations use zero prompts and
-report that creation flags were unused. Bare repositories fail closed.
+`borg assimilate` and `borg server cube init` share one repository-cube flow.
+An existing local or server repository association is resolved without prompts.
+Otherwise Borg checks accessible cubes against the exact proposed name. One
+match displays the cube, repository, and server and requires explicit interactive
+confirmation before the server atomically associates it; multiple matches fail
+closed. `--yes` never adopts a cube by name. With no match, an authorized owner
+continues to the creation guide, which shows the repository and server, proposes
+an editable name, offers the Software Development and Starter templates, and
+asks for one confirmation. `--cube-name <name>` and `--template
+software-dev|starter` supply those creation values directly; `--yes` accepts the
+repository default name and Software Development template. `borg server cube
+init` stops after authoritative cube readback and never creates a drone. Bare
+repositories fail closed.
 
 For repositories with a canonical public `origin`, that origin is the stable
 repository identity. Repositories without one receive an invisible UUID stored
@@ -168,8 +173,9 @@ The default discovery endpoint is `https://127.0.0.1:7091`. Explicit `--host` va
 
 ## Release status
 
-This self-hosted path consumes the published `borgmcp-shared@0.6.3` v4 registry
-release. The matching server owner-enrollment, cube-create, attach, restart, log,
-and SSE implementation must also pass the full process-level local dogfood gate.
-Until that gate opens the self-hosted path remains preview-only, and the client
+This self-hosted path pins published `borgmcp-shared@0.6.4` and requires the
+matching published `borgmcp-server@0.1.21` for protocol v5 repository resolve
+and association. The server owner-enrollment, repository resolve/association,
+cube-create, attach, restart, log, and SSE implementation must also pass the full
+process-level local dogfood gate. Until that gate opens the self-hosted path remains preview-only, and the client
 publish is deferred accordingly.

package/docs/RELEASING.md

@@ -104,8 +104,22 @@ The annotated `v2.0.11` tag object
 `0676d93d3e8a64ba583e95f164d122b39687b53a`. Workflow run `30073844074`, attempt 1,
 successfully published that exact source as `borgmcp@2.0.11`; the registry records integrity
 `sha512-429njJ7HVmWhpm8E71RoLzG57Qehy3RSxEzs6fQofVoOIiZXnK4QQDwbQe9MPfhKifbvVN5lGcDKtKAjuC76ww==`.
+Never move, replace, reuse, or rerun that tag or workflow.
+
+The annotated `v2.1.0` tag object
+`e0b189bb0dd1f1b12369ab81870113925e1afc41` peels to protected-main commit
+`10f18e4010c9c518c0ea2184d42ed5388642a53f`. Workflow run `30166498938`, attempt 1,
+successfully published that exact source as `borgmcp@2.1.0`; the same-run artifact report records integrity
+`sha512-Gm9n69y3C0feNDYRPEOnShLCscQJ/BoylcRMH+sDDQJmdcbjY8+U6dDTcFv3w+uH5P/IVwJydB8TGRHPXL0FQA==`.
+Never move, replace, reuse, or rerun that tag or workflow.
+
+The annotated `v2.1.1` tag object
+`aa8d772c4791b2da16d702d5d78e5b3c365796c4` peels to protected-main commit
+`db0a6a76744928e0067eb03b8a236076c56ae758`. Workflow run `30174878044`, attempt 1,
+successfully published that exact source as `borgmcp@2.1.1`; the same-run artifact report records integrity
+`sha512-nZJ3i6LBIj/4743mqVRJTUH3YGmC8HfC/NuQb7eOv+/K/dyBogDnwZ3opiZiZSe4LE5CXuG72Sip7cPRoCoZrA==`.
 Never move, replace, reuse, or rerun that tag or workflow. The next candidate
-uses the unused `v2.1.0` identity from a fresh reviewed protected-main commit
+uses the unused `v2.2.0` identity from a fresh reviewed protected-main commit
 and requires the complete release gate again.
 
 ## Release Prerequisites
@@ -117,10 +131,12 @@ Before creating the release tag, independently verify all of these conditions:
 - the extraction review confirms no private backend secrets, deployment
   configuration, customer data, local state, or duplicated shared contracts
   entered the public package;
-- the exact audited registry dependency `borgmcp-shared@0.6.3` remains locked to
-  its canonical tarball and integrity;
-- the client and matching published `borgmcp-server@0.1.20`, which pins
-  `borgmcp-shared@0.6.3`, pass the complete local dogfood gate;
+- the exact audited registry dependency `borgmcp-shared@0.6.4` remains locked to
+  its canonical tarball and integrity
+  `sha512-Wm4b0uoOAw9JCz5OTHD0Q2uXKkeWYdkVksdeZvRG8l62XGMY+G8GkNEsZT9L533LbVbQ29GhgF0htjDenQThDg==`;
+- the client and matching published `borgmcp-server@0.1.21`, integrity
+  `sha512-g0QH4cKcsKuDyZs1MvBmvCoCLaZ4wVI04yHCGSvcAeWghWxSBH0IIF8Q5OFi1pLB7TZXOVP6D3QAabUQ2eJTFg==`, which pins
+  `borgmcp-shared@0.6.4`, pass the complete local dogfood gate;
 - the selected stable client version is unused and the exact release commit is
   on protected `main`;
 - the repository and protected npm environment settings pass an operator audit;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Coordinate AI coding agents in shared cubes. Works with Claude Code, Codex, and OpenCode.",
   "type": "module",
   "main": "./dist/index.js",
@@ -68,7 +68,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",
-    "borgmcp-shared": "0.6.3",
+    "borgmcp-shared": "0.6.4",
     "chalk": "^5.3.0",
     "prompts": "^2.4.2",
     "which": "^4.0.0"

package/src/assimilate-cmd.ts

@@ -46,6 +46,9 @@ import {
   CubeCreationConfirmationError,
   CubeCreationOutcomeUnknownError,
   LegacySessionCredentialCollisionError,
+  RepositoryAssociationOperationError,
+  RepositoryAssociationOutcomeUnknownError,
+  RepositoryAssociationResolutionError,
 } from './server-errors.js';
 import type { SeatStatus } from './seat-probe.js';
 import type { ServerSessionOperation } from './config.js';
@@ -54,12 +57,18 @@ import type { SeatBinding, BindPendingSeatOutcome } from './seats.js';
 import { createHash } from 'node:crypto';
 import { buildOpenCodeLaunchArgs, type LaunchApprovalDecision } from './cli-tool-approval.js';
 import { resolveWorkingRepo, type WorkingRepo } from './working-repo.js';
-import type { CreateCubeRepository, CubeTemplate } from 'borgmcp-shared/protocol';
+import type {
+  AssociateRepositoryCubeResponse,
+  CreateCubeRepository,
+  CubeTemplate,
+} from 'borgmcp-shared/protocol';
 import {
   initializeRepositoryCube,
+  RepositoryAssociationConfirmationError,
   RepositoryAssociationSaveError,
   validRepositoryCubeName,
   type RepositoryCubeCreation,
+  type RepositoryCubeResolution,
 } from './repository-cube-init.js';
 import type { GitRepositoryContext, RepositoryAssociation } from './repository-identity.js';
 
@@ -266,6 +275,18 @@ export interface AssimilateDeps {
     serverCapabilities?: readonly string[];
   } | null>;
 
+  resolveRepositoryCube: (
+    apiUrl: string,
+    token: string,
+    input: { workingRepoName: string; repository: CreateCubeRepository },
+    serverTrustIdentity?: string,
+  ) => Promise<RepositoryCubeResolution>;
+  associateRepositoryCube: (
+    apiUrl: string,
+    token: string,
+    input: { cubeId: string; workingRepoName: string; repository: CreateCubeRepository },
+    serverTrustIdentity?: string,
+  ) => Promise<AssociateRepositoryCubeResponse>;
   listCubes: (apiUrl: string, token: string, serverTrustIdentity?: string) => Promise<CubeSummary[]>;
   getCube: (apiUrl: string, token: string, cubeId: string, serverTrustIdentity?: string) => Promise<CubeDetail>;
   createCube: (
@@ -684,71 +705,12 @@ export async function runAssimilate(
 
   let initialized;
   try {
-    if (!auth.serverCapabilities.includes('create_cube') && !existing) {
-      const repository = await deps.getRepositoryIdentity(repositoryContext);
-      const association = await deps.getRepositoryAssociation(auth.serverTrustIdentity, repository);
-      if (association) {
-        initialized = await initializeRepositoryCube({
-          mode, context: repositoryContext, serverOrigin: auth.apiUrl, flags: args.flags,
-        }, {
-          isTTY: deps.isTTY,
-          prompt: deps.prompt,
-          write: deps.stderr,
-          getIdentity: async () => repository,
-          getAssociation: async () => association,
-          saveAssociation: (identity, saved) =>
-            deps.saveRepositoryAssociation(auth.serverTrustIdentity, identity, saved),
-          getCube: (cubeId) => deps.getCube(auth.apiUrl, auth.token, cubeId, auth.serverTrustIdentity),
-          createCube: (params) => deps.createCube(auth.apiUrl, auth.token, params, auth.serverTrustIdentity),
-        });
-      } else {
-        const candidateName = args.flags.cubeName ?? repositoryContext.derivedName;
-        const accessible = await deps.listCubes(auth.apiUrl, auth.token, auth.serverTrustIdentity);
-        const matches = accessible.filter((cube) => cube.name === candidateName);
-        if (matches.length !== 1) {
-          deps.stderr(matches.length === 0
-            ? `This enrolled client cannot create a cube on ${auth.apiUrl}. Ask the server operator to grant access to a cube, then rerun ${localAssimilateCommand(auth.apiUrl)}.\n`
-            : `More than one accessible cube is named '${candidateName}'. Nothing was changed. Ask the server operator for an unambiguous repository cube grant.\n`);
-          return 1;
-        }
-        const cube = await deps.getCube(auth.apiUrl, auth.token, matches[0].id, auth.serverTrustIdentity);
-        const association = {
-          cubeId: cube.id,
-          name: cube.name,
-          workingRepoName: repositoryContext.derivedName,
-          template: 'default' as const,
-        };
-        try {
-          await deps.saveRepositoryAssociation(auth.serverTrustIdentity, repository, association);
-        } catch {
-          throw new RepositoryAssociationSaveError();
-        }
-        const response = {
-          result: 'resolved' as const,
-          cube_id: cube.id,
-          name: cube.name,
-          working_repo_name: repositoryContext.derivedName,
-          repository,
-          template: 'default' as const,
-          human_seat_role_id: cube.roles.find((role) => role.is_human_seat)?.id ?? '',
-          default_worker_role_id: cube.roles.find((role) => role.is_default)?.id ?? '',
-          access: 'manage' as const,
-        };
-        deps.stderr(
-          `Cube already initialized.\n  Name: ${cube.name}\n  Template: Default (legacy)\n` +
-          `  Repository: ${repositoryContext.root}\n  Server: ${auth.apiUrl}\n` +
-          (mode === 'cube-init'
-            ? `No drone was created.\nNext: borg assimilate --host ${shellEscape(auth.apiUrl)}\n`
-            : 'Continuing with role and seat setup...\n'),
-        );
-        initialized = { kind: 'success' as const, creation: { response, cube }, existing: true };
-      }
-    } else {
     initialized = await initializeRepositoryCube({
       mode,
       context: repositoryContext,
       serverOrigin: auth.apiUrl,
       flags: args.flags,
+      canCreate: auth.serverCapabilities.includes('create_cube'),
     }, {
       isTTY: deps.isTTY,
       prompt: deps.prompt,
@@ -757,11 +719,62 @@ export async function runAssimilate(
       getAssociation: (repository) => deps.getRepositoryAssociation(auth.serverTrustIdentity, repository),
       saveAssociation: (repository, association) =>
         deps.saveRepositoryAssociation(auth.serverTrustIdentity, repository, association),
+      resolveAssociation: (repository, workingRepoName) => deps.resolveRepositoryCube(
+        auth.apiUrl,
+        auth.token,
+        { repository, workingRepoName },
+        auth.serverTrustIdentity,
+      ),
+      listCubes: () => deps.listCubes(auth.apiUrl, auth.token, auth.serverTrustIdentity),
+      associateCube: (params) => deps.associateRepositoryCube(
+        auth.apiUrl,
+        auth.token,
+        params,
+        auth.serverTrustIdentity,
+      ),
       getCube: (cubeId) => deps.getCube(auth.apiUrl, auth.token, cubeId, auth.serverTrustIdentity),
       createCube: (params) => deps.createCube(auth.apiUrl, auth.token, params, auth.serverTrustIdentity),
     });
-    }
   } catch (error) {
+    if (error instanceof RepositoryAssociationOutcomeUnknownError) {
+      deps.stderr(
+        'Repository cube association outcome is unknown.\n' +
+        'The server may have created the repository binding; no local repository association was saved and no drone was created.\n' +
+        'Run the same command again; Borg will first resolve the authoritative server association without creating a cube.\n',
+      );
+      return 1;
+    }
+    if (error instanceof RepositoryAssociationResolutionError) {
+      deps.stderr(
+        'Repository cube association could not be resolved.\n' +
+        'Verify that the server is reachable and the client and server versions match, then run the same command again.\n' +
+        'No cube, repository binding, or drone was created.\n',
+      );
+      return 1;
+    }
+    if (error instanceof RepositoryAssociationOperationError) {
+      const recovery = error.failure === 'repository-already-associated'
+        ? 'This repository is already associated with another cube. Run the same command again to use the existing managed association, or ask the server operator to correct the repository binding.'
+        : error.failure === 'cube-already-associated'
+          ? 'The selected cube is already associated with another repository. Choose a different cube, or run the command from the repository already linked to that cube.'
+          : error.failure === 'access-denied'
+            ? 'This enrolled client does not have permission to manage the selected cube. Ask the server operator to grant this client management access, then run the same command again.'
+            : 'The selected cube does not have valid authoritative roles. Ask the server operator to repair its role configuration, or choose another cube.';
+      deps.stderr(
+        'Repository cube association could not be completed.\n' +
+        `${recovery}\n` +
+        'No cube, repository binding, or drone was created.\n',
+      );
+      return 1;
+    }
+    if (error instanceof RepositoryAssociationConfirmationError) {
+      deps.stderr(
+        'Repository cube association could not be confirmed.\n' +
+        'The server may have created the repository binding; no local repository association was saved and no drone was created.\n' +
+        'Run the same command again; Borg will resolve authoritative server state before creating or associating a cube.\n',
+      );
+      return 1;
+    }
     if (error instanceof RepositoryAssociationSaveError) {
       deps.stderr(
         'The repository cube was confirmed, but Borg could not save its local repository association.\n' +
@@ -772,18 +785,17 @@ export async function runAssimilate(
     }
     if (error instanceof CubeCreationOutcomeUnknownError) {
       deps.stderr(
-        'Cube creation outcome is unknown.\n' +
-        'No local repository association was saved.\n' +
-        'Run the same command again; the server will resolve the original request or return a conflict.\n',
+        'Cube creation outcome is unconfirmed.\n' +
+        'The server may have created the cube and repository binding; no local repository association was saved and no drone was created.\n' +
+        'Run the same command again; Borg will resolve authoritative server state before creating a cube.\n',
       );
       return 1;
     }
     if (error instanceof CubeCreationConfirmationError) {
       deps.stderr(
         'Cube creation could not be confirmed.\n' +
-        `${error.message}\n` +
-        'No local repository association was saved.\n' +
-        'Resolve the conflict, then run the same command again.\n',
+        'The server may have created the cube and repository binding; no local repository association was saved and no drone was created.\n' +
+        'Run the same command again; Borg will resolve authoritative server state before creating a cube.\n',
       );
       return 1;
     }
@@ -797,7 +809,11 @@ export async function runAssimilate(
     if (error instanceof BorgServerError) {
       return reportServerFailure(deps, auth.apiUrl, error);
     }
-    deps.stderr('Could not create cube.\nThe selected Borg server rejected the request.\nNothing was changed.\n');
+    deps.stderr(
+      'Repository cube initialization failed.\n' +
+      'The server may have created or associated a cube; local repository state may be incomplete and no drone was created.\n' +
+      'Run the same command again; Borg will resolve authoritative server state before creating or associating a cube.\n',
+    );
     return 1;
   }
   if (initialized.kind === 'stop') return initialized.code;

package/src/assimilate-deps.ts

@@ -25,10 +25,12 @@ import {
 } from './remote-client.js';
 import {
   DEFAULT_LOCAL_SERVER_ORIGIN,
+  associateLocalBorgServerRepositoryCube,
   connectLocalBorgServer,
   createLocalBorgServerCube,
   enrollLocalBorgServer,
   probeLocalBorgServer,
+  resolveLocalBorgServerRepositoryCube,
   resumeLocalBorgServerEnrollment,
   sendBorgServerAttach,
 } from './server-handshake.js';
@@ -45,7 +47,7 @@ import {
 } from './cubes.js';
 import { loadBorgServerTrust } from './server-trust.js';
 import { defaultProbeSeat } from './seat-probe.js';
-import { BorgServerError } from './server-errors.js';
+import { BorgServerError, CubeCreationConfirmationError } from './server-errors.js';
 import {
   findProjectRoot as cubesFindProjectRoot,
   getActiveCube as cubesGetActive,
@@ -238,6 +240,29 @@ export function buildDefaultAssimilateDeps(
         ...(onPending === undefined ? {} : { onPending }),
       }),
 
+    resolveRepositoryCube: async (apiUrl, token, input, serverTrustIdentity) => {
+      if (serverTrustIdentity === undefined) {
+        throw new Error('Selected Borg server authority state is missing or unreadable');
+      }
+      return resolveLocalBorgServerRepositoryCube(
+        apiUrl,
+        serverTrustIdentity,
+        token,
+        input,
+      );
+    },
+    associateRepositoryCube: async (apiUrl, token, input, serverTrustIdentity) => {
+      if (serverTrustIdentity === undefined) {
+        throw new Error('Selected Borg server authority state is missing or unreadable');
+      }
+      return associateLocalBorgServerRepositoryCube(
+        apiUrl,
+        serverTrustIdentity,
+        token,
+        input,
+      );
+    },
+
     listCubes: async (apiUrl, token, serverTrustIdentity) => {
       if (serverTrustIdentity === undefined) {
         throw new Error('Selected Borg server authority state is missing or unreadable');
@@ -284,18 +309,23 @@ export function buildDefaultAssimilateDeps(
             template: params.template,
           },
         );
-        const cube = await remoteGetCube(created.cube_id, {
-          apiUrl,
-          authToken: token,
-          serverTrustIdentity,
-        });
+        let cube;
+        try {
+          cube = await remoteGetCube(created.cube_id, {
+            apiUrl,
+            authToken: token,
+            serverTrustIdentity,
+          });
+        } catch {
+          throw new CubeCreationConfirmationError('The server returned a cube result that could not be read back.');
+        }
         if (
           cube.id !== created.cube_id ||
           cube.name !== created.name ||
           !Array.isArray(cube.roles) ||
           !cube.roles.some((role: { id?: string }) => role.id === created.default_worker_role_id)
         ) {
-          throw new Error('Borg server returned cube details outside the creation result');
+          throw new CubeCreationConfirmationError('The server returned cube details outside the creation result.');
         }
         return {
           response: created,

package/src/cli-help.ts

@@ -55,6 +55,7 @@ export function serverHelpText(): string {
     `  status   Report verified runtime evidence.\n` +
     `  update   Verify and activate a local server artifact.\n` +
     `  invite   Create a single-use invitation in an interactive terminal.\n` +
+    `  dashboard   View the running local server dashboard.\n` +
     `  cube init   Initialize this Git repository's cube; does not create a drone.\n\n` +
     `Run borg server <command> --help for server command options.\n`
   );
@@ -71,7 +72,7 @@ export function cubeInitHelpText(): string {
     `  --enroll                         Prompt for a hidden enrollment invitation\n` +
     `  --cube-name <name>               Repository cube name (otherwise edit the proposed name)\n` +
     `  --template software-dev|starter  New-cube template (default: software-dev)\n` +
-    `  --yes, -y                        Skip confirmation prompts\n` +
+    `  --yes, -y                        Accept new-cube defaults; never adopt by name\n` +
     `  --help, -h                       Show this help\n`
   );
 }
@@ -101,11 +102,12 @@ export function assimilateHelpText(version: string): string {
     `  --no-template              Unsupported for repository cube creation\n` +
     `  --cli claude|codex|opencode         Agent CLI to launch (default: claude)\n` +
     `  --model claude:<model>   Legacy Claude model override (configure models in the agent CLI)\n` +
-    `  --yes, -y                  Skip confirmation prompts\n\n` +
+    `  --yes, -y                  Accept new-cube defaults; never adopt by name\n\n` +
     `Creation shows repository context, name, template, and one confirmation. An existing\n` +
-    `repository association skips all prompts. An enrolled owner client may create an\n` +
-    `idempotent repository cube; ordinary clients\n` +
-    `require an explicit cube grant. Agent seats begin only after enrollment. Preview only.\n` +
+    `repository association skips all prompts. One accessible exact-name legacy cube requires\n` +
+    `explicit interactive adoption; ambiguous matches fail closed. An enrolled owner client may\n` +
+    `create an idempotent repository cube; ordinary clients require an explicit cube grant.\n` +
+    `Agent seats begin only after enrollment. Preview only.\n` +
     `See docs/LOCAL_SERVER.md for self-hosted setup and current status.\n\n` +
     `For local or provider-specific models, configure the selected agent CLI directly.\n` +
     `OpenCode supports Ollama and other providers through its own model configuration.\n`

package/src/index.ts

@@ -76,6 +76,7 @@ import {
   formatRegenMarkdown,
   getDronePlaybook,
   getDronePlaybookChapter,
+  markArrivalAnnouncedThisProcess,
   nullTaxonomyTip,
   regenWakePathDroneLabel,
 } from './regen-format.js';
@@ -728,10 +729,12 @@ export async function main() {
           if (!message || typeof message !== 'string') throw new Error('message is required');
           const active = await getActiveCube();
           if (!active) throw new Error('Not assimilated to a cube. Use borg_assimilate <cube-name> first.');
-          if (lifecycleSignalForMessage(message)) {
+          const lifecycleSignal = lifecycleSignalForMessage(message);
+          if (lifecycleSignal) {
             const decision = await shouldSuppressLifecycleLog(active, message);
             if (decision.suppress) {
               await recordLifecycleLog(active, message);
+              if (lifecycleSignal === 'arrival') markArrivalAnnouncedThisProcess();
               return {
                 content: [
                   {
@@ -760,6 +763,7 @@ export async function main() {
           };
           const result = await appendLog(active.sessionToken, active.apiUrl, message, appendOpts);
           await recordLifecycleLog(active, message);
+          if (lifecycleSignal === 'arrival') markArrivalAnnouncedThisProcess();
           const echo = result.routing?.message ? `\n${result.routing.message}` : '';
           // gh#534: surface to the SENDER which directed recipients are
           // currently unreachable via the wake path. The message is delivered

package/src/regen-format.ts

@@ -191,6 +191,12 @@ export function formatLeanOrientation(args: {
 // formatLeanOrientation({ ..., source: 'clear' }), so the per-surface
 // /clear block is gone (one place, not three).
 
+let arrivalAnnouncedThisProcess = false;
+
+export function markArrivalAnnouncedThisProcess(): void {
+  arrivalAnnouncedThisProcess = true;
+}
+
 /**
  * Build the universal drone playbook.
  *
@@ -215,6 +221,9 @@ export function formatLeanOrientation(args: {
 //   about how Borg MCP works; this marker pins the param so the #490/#529 guard
 //   verifies borg_docs exposes `topic`.
 export function getDronePlaybook(): string {
+  const arrivalInstruction = arrivalAnnouncedThisProcess
+    ? ''
+    : '\n**When this MCP session first starts:** post one `ARRIVAL: <your-label> (<your-role>) online on <hostname> at <project-path>` (run `hostname`; use cwd for the path). After the post succeeds, the client suppresses this instruction until the MCP process restarts; an explicit `/mcp` reconnect may show it again.\n';
   return `## How to operate as a Drone
 
 You're a Drone in a Cube. Coordinate with other drones through the activity log.
@@ -242,8 +251,7 @@ You're a Drone in a Cube. Coordinate with other drones through the activity log.
 5. Nothing actionable + no prompt → done; wait for next wake.
 
 **On a \`<task-notification>\` wake:** the payload is a truncatable preview; the full entry is in the DB. Drain: \`borg_read-log unread_only=true limit=20\`, repeat until \`behind_by=0\`. Do NOT triage with \`since=<notification timestamp>\` (strict-after — skips the boundary entry) or a bare window (skips older-unread during bursts).
-
-**On first wake this session:** post one \`ARRIVAL: <your-label> (<your-role>) online on <hostname> at <project-path>\` (run \`hostname\`; use cwd for the path). One-time per session — don't repeat on later wakes; skip if already posted this session (e.g. after a \`/mcp\` reconnect).
+${arrivalInstruction}
 
 **When a log entry routes work to you** (a routing/assignment-class entry per your cube's conventions that names your label + asks for action, or a direct \`<your-label>:\` mention): call \`borg_ack entry_id=<id>\` within ~60s. Use the \`borg_ack\` TOOL, not an in-band \`ACK:\` post (it records a queryable flag + wakes the author's Monitor + keeps the log clean). Ack = receipt, not completion (\`STARTING\` / \`DONE\` still apply). Ack only routing-class signals — not every mention.
 
@@ -269,13 +277,6 @@ You're a Drone in a Cube. Coordinate with other drones through the activity log.
 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).`;
 }
 
-/**
- * Eager export of the playbook text. Cheap to compute (string concat);
- * exporting as a constant lets callers splice it directly without a
- * function call site.
- */
-export const DRONE_PLAYBOOK = getDronePlaybook();
-
 /**
  * gh#912: the verbose operating-discipline DETAIL externalized out of the
  * bootstrap regen into an on-demand chapter (fetched via the borg_playbook
@@ -387,6 +388,7 @@ let cachedRoleTextHash: string | null = null;
 export function __resetRegenSessionState(): void {
   boilerplateEmittedThisSession = false;
   cachedRoleTextHash = null;
+  arrivalAnnouncedThisProcess = false;
 }
 
 function safetyDisciplinesForRole(detailedDescription: string | null | undefined): string[] {

package/src/remote-client.ts

@@ -712,7 +712,7 @@ async function authedFetch(
           parsed.error !== null && typeof parsed.error === 'object' &&
           parsed.error.code === ROLE_SECTION_CONFLICT_CODE
         ) {
-          // Shared 0.6.3 intentionally omits this server-local code. Re-validate the whole
+          // The shared protocol intentionally omits this server-local code. Re-validate the whole
           // envelope through the strict shared decoder with only the recognized
           // code substituted; no server-provided diagnostic is ever surfaced.
           decodeProtocolErrorEnvelope({