borgmcp 3.11.1 → 3.13.0

package/src/codex-app-wake.ts

@@ -6,7 +6,7 @@ import {
 } from './cubes.js';
 import { CodexAppServerClient } from './codex-app-server.js';
 import { checkCodexBridgeHealthy } from './codex-remote.js';
-import { hasPendingWakeActivity } from './remote-client.js';
+import { hasPendingWakeActivity, hasPendingWakeEntry } from './remote-client.js';
 import {
   BORG_CODEX_REMOTE_WAKE_ENV,
   resolveSessionAgentKind,
@@ -98,6 +98,7 @@ let wakeInFlight = false;
 const pendingWakeRequests: Array<{
   reason: string;
   deliveryIdentity?: string;
+  sourceEntryId?: string;
   deps: CodexWakeDeps;
 }> = [];
 const deliveredWakeKeys = new Set<string>();
@@ -108,6 +109,8 @@ const DELIVERED_WAKE_KEY_CAP = 100;
 // (mid-turn thread) or missed (transient error) into ONE retried-until-delivered
 // drain. The coalesce gate means a burst collapses to one poller, not N.
 let retryDrainInFlight = false;
+const retryDrainSourceEntryIds = new Set<string>();
+let retryDrainHasUnscopedWork = false;
 
 // gh#857 WI-2: timestamp of the last SUCCESSFUL wake delivery (per-entry OR
 // retry-drain OR heartbeat). The heartbeat reads this (shouldFireHeartbeat) to
@@ -192,6 +195,7 @@ export interface CodexWakeDeps {
   // Per-entry and retry-drain paths do not use this: their pending obligation is
   // already established by a concrete delivered/deferred event.
   hasPendingWork?: (active: ActiveCube) => Promise<boolean>;
+  hasPendingEntry?: (active: ActiveCube, entryId: string) => Promise<boolean>;
   // gh#861 finding 2: lease-ownership gate for the heartbeat tick — a lease-LOSING
   // duplicate child must NOT tick/inject (symmetry with the per-entry path, which
   // only fires inside an SSE session that holds the stream lease). Heartbeat-only;
@@ -280,10 +284,11 @@ export function wakeCodexViaAppServer(
   env: NodeJS.ProcessEnv = process.env,
   deps: CodexWakeDeps = {},
   deliveryIdentity?: string,
+  sourceEntryId?: string,
 ): void {
   const target = resolveCodexWakeTarget(env);
   if (!target.enabled) return;
-  pendingWakeRequests.push({ reason, deliveryIdentity, deps });
+  pendingWakeRequests.push({ reason, deliveryIdentity, sourceEntryId, deps });
   if (wakeInFlight) return;
 
   wakeInFlight = true;
@@ -295,21 +300,30 @@ export function wakeCodexViaAppServer(
 async function drainCodexWakeQueue(): Promise<void> {
   while (pendingWakeRequests.length > 0) {
     const request = pendingWakeRequests.shift()!;
-    await wakeCodexTargeted(request.reason, request.deliveryIdentity, request.deps);
+    await wakeCodexTargeted(
+      request.reason, request.deliveryIdentity, request.sourceEntryId, request.deps,
+    );
   }
 }
 
-async function wakeCodexTargeted(reason: string, deliveryIdentity: string | undefined, deps: CodexWakeDeps): Promise<void> {
+async function wakeCodexTargeted(
+  reason: string,
+  deliveryIdentity: string | undefined,
+  sourceEntryId: string | undefined,
+  deps: CodexWakeDeps,
+): Promise<void> {
   // gh#861 finding 1: another path (heartbeat/retry-drain) is mid-inject into the
   // same thread — defer to the retry-drain so this entry isn't double-injected nor
   // lost (the drain re-syncs the whole burst via the server read-cursor).
   if (!tryAcquireInjectLock()) {
-    scheduleRetryDrain(deps);
+    scheduleRetryDrain(deps, sourceEntryId);
     return;
   }
   try {
     const active = await (deps.getActiveCube ?? getActiveCube)();
     if (!active) return;
+    const pendingEntry = deps.hasPendingEntry ?? hasPendingWakeEntry;
+    if (sourceEntryId && !(await pendingEntry(active, sourceEntryId))) return;
     // gh#855: resolve FRESH (live env socket + re-resolved thread), falling back
     // to the launch-recorded file only when the env socket is absent.
     const resolved = await resolveFreshCodexWakeTarget(active, deps);
@@ -326,9 +340,10 @@ async function wakeCodexTargeted(reason: string, deliveryIdentity: string | unde
         // now. Schedule the retry-drain (coalesced, retried-until-delivered) so
         // the burst's entries are drained once the thread goes idle; codex has no
         // on-disk tail fallback like Claude's borg-inbox-monitor.
-        scheduleRetryDrain(deps);
+        scheduleRetryDrain(deps, sourceEntryId);
         return;
       }
+      if (sourceEntryId && !(await pendingEntry(active, sourceEntryId))) return;
       await client.startTurn(threadId, reason);
       rememberDeliveredWake(wakeKey);
       markDelivered(deps);
@@ -340,7 +355,7 @@ async function wakeCodexTargeted(reason: string, deliveryIdentity: string | unde
     // swallowed (the old best-effort drop let a single blip lose an entry).
     // Schedule the retry-drain so the wake is retried-until-delivered; the SSE
     // stream is never broken (this is fire-and-forget).
-    scheduleRetryDrain(deps);
+    scheduleRetryDrain(deps, sourceEntryId);
   } finally {
     releaseInjectLock();
   }
@@ -357,7 +372,9 @@ async function wakeCodexTargeted(reason: string, deliveryIdentity: string | unde
  * (wakeRetryExpired); the gh#857 WI-2 heartbeat is the backstop beyond that.
  * Never throws into the SSE path (fire-and-forget).
  */
-function scheduleRetryDrain(deps: CodexWakeDeps): void {
+function scheduleRetryDrain(deps: CodexWakeDeps, sourceEntryId?: string): void {
+  if (sourceEntryId) retryDrainSourceEntryIds.add(sourceEntryId);
+  else retryDrainHasUnscopedWork = true;
   if (retryDrainInFlight) return; // coalesce: one loop covers all deferred/missed wakes
   retryDrainInFlight = true;
   void runRetryDrainLoop(deps).finally(() => {
@@ -383,6 +400,15 @@ async function runRetryDrainLoop(deps: CodexWakeDeps): Promise<void> {
     try {
       const active = await (deps.getActiveCube ?? getActiveCube)();
       if (!active) continue; // no active cube yet → keep retrying (until age cap)
+      const pendingEntry = deps.hasPendingEntry ?? hasPendingWakeEntry;
+      for (const entryId of retryDrainSourceEntryIds) {
+        try {
+          if (!(await pendingEntry(active, entryId))) retryDrainSourceEntryIds.delete(entryId);
+        } catch {
+          // Retain the obligation until unread state can be checked.
+        }
+      }
+      if (!retryDrainHasUnscopedWork && retryDrainSourceEntryIds.size === 0) return;
       // gh#855: same FRESH resolution as the per-entry wake, so a stale launch
       // probe can't defeat the retry-drain either.
       const resolved = await resolveFreshCodexWakeTarget(active, deps);
@@ -395,7 +421,13 @@ async function runRetryDrainLoop(deps: CodexWakeDeps): Promise<void> {
         if (thread?.status?.type === 'active') {
           continue; // re-defer: still mid-turn (backoff before next poll)
         }
+        for (const entryId of retryDrainSourceEntryIds) {
+          if (!(await pendingEntry(active, entryId))) retryDrainSourceEntryIds.delete(entryId);
+        }
+        if (!retryDrainHasUnscopedWork && retryDrainSourceEntryIds.size === 0) return;
         await client.startTurn(threadId, CODEX_CATCHUP_PROMPT);
+        retryDrainSourceEntryIds.clear();
+        retryDrainHasUnscopedWork = false;
         markDelivered(deps);
         return; // drain delivered → server read-cursor drains all unread → done
       } finally {
@@ -515,6 +547,8 @@ export function resetCodexWakeForTests(): void {
   deliveredWakeKeys.clear();
   deliveredWakeKeyOrder.length = 0;
   retryDrainInFlight = false;
+  retryDrainSourceEntryIds.clear();
+  retryDrainHasUnscopedWork = false;
   lastDeliveredAt = null;
   heartbeatInFlight = false;
   injectInFlight = false;

package/src/cube-activity-wake-copy.ts

@@ -1,5 +1,5 @@
 export const CUBE_ACTIVITY_RESUME_WAKE_MESSAGE =
-  'Borg cube activity arrived while you were busy. Reading cube messages does not end your current task. Drain `borg_read-log unread_only=true` until caught up, handle actionable entries, then RESUME the interrupted work.';
+  'Borg cube activity arrived while you were busy. Reading cube messages does not end your current task. Drain `borg_read-log unread_only=true` until caught up, handle actionable entries, then RESUME the interrupted work. If the unread drain is empty, resume silently without a liveness post or full regen.';
 
 export function formatCubeActivityWakeMessage(detail: string): string {
   return `${CUBE_ACTIVITY_RESUME_WAKE_MESSAGE}\n${detail}`;

package/src/log-stream.ts

@@ -125,12 +125,14 @@ function isProcessAlive(pid: number): boolean {
  * Used by defaultDeps when no explicit injectOpenCode is supplied.
  */
 let _moduleInjectOpenCode:
-  | ((text: string, entryId: string, allowSubmit: boolean, sourceEntryId?: string) => Promise<boolean>)
+  | ((text: string, entryId: string, allowSubmit: boolean, sourceEntryId?: string,
+      isSourcePending?: () => Promise<boolean>) => Promise<boolean>)
   | undefined;
 let _moduleSettleOpenCodeEntry: ((sourceEntryId: string) => void) | undefined;
 
 export function setModuleInjectOpenCode(
-  fn: (text: string, entryId: string, allowSubmit: boolean, sourceEntryId?: string) => Promise<boolean>,
+  fn: (text: string, entryId: string, allowSubmit: boolean, sourceEntryId?: string,
+    isSourcePending?: () => Promise<boolean>) => Promise<boolean>,
   settle: (sourceEntryId: string) => void,
 ): void {
   _moduleInjectOpenCode = fn;
@@ -392,7 +394,7 @@ export interface StreamDeps {
     renderedLine: string
   ) => Promise<boolean>;
   /** Optional Codex app-server wake sink; tests inject a spy. */
-  wakeCodex?: (reason: string, deliveryIdentity?: string) => void;
+  wakeCodex?: (reason: string, deliveryIdentity?: string, sourceEntryId?: string) => void;
   /** Override the heartbeat watchdog timeout. */
   heartbeatTimeoutMs?: number;
   /** Override HWM divergence grace for focused tests. */
@@ -409,6 +411,7 @@ export interface StreamDeps {
     entryId: string,
     allowSubmit: boolean,
     sourceEntryId?: string,
+    isSourcePending?: () => Promise<boolean>,
   ) => Promise<boolean>;
   /** Inspect whether one retry source remains beyond the durable unread cursor. */
   hasPendingWakeEntry?: (active: ActiveCube, entryId: string) => Promise<boolean>;
@@ -422,16 +425,16 @@ const defaultDeps: Required<StreamDeps> = {
   getCursor: getLocalServerCursor,
   appendLine: defaultAppendLine,
   hasInboxEntryId: defaultHasInboxEntryId,
-  wakeCodex: (reason, deliveryIdentity) =>
-    wakeCodexViaAppServer(reason, process.env, {}, deliveryIdentity),
+  wakeCodex: (reason, deliveryIdentity, sourceEntryId) =>
+    wakeCodexViaAppServer(reason, process.env, {}, deliveryIdentity, sourceEntryId),
   heartbeatTimeoutMs: HEARTBEAT_TIMEOUT_MS,
   hwmDivergenceGraceMs: HWM_DIVERGENCE_GRACE_MS,
   abortSignal: new AbortController().signal,
   ownerDeps: {},
   ownerStaleMs: 70_000,
-  injectOpenCode: (text, entryId, allowSubmit, sourceEntryId) =>
+  injectOpenCode: (text, entryId, allowSubmit, sourceEntryId, isSourcePending) =>
     _moduleInjectOpenCode
-      ? _moduleInjectOpenCode(text, entryId, allowSubmit, sourceEntryId)
+      ? _moduleInjectOpenCode(text, entryId, allowSubmit, sourceEntryId, isSourcePending)
       : Promise.resolve(false),
   hasPendingWakeEntry: (active, entryId) => hasPendingDurableWakeEntry(
     active as Parameters<typeof hasPendingDurableWakeEntry>[0],
@@ -902,7 +905,10 @@ export async function streamOnce(
       // OpenCode queue. A still-unread re-ping may reconcile the prior attempt;
       // its source entry ID prevents a new nonce from resubmitting that prompt.
       if (isReping) {
-        await injectOpenCode(formatOpenCodeWakePrompt(line), deliveryId, true, ev.id);
+        await injectOpenCode(
+          formatOpenCodeWakePrompt(line), deliveryId, true, ev.id,
+          () => hasPendingWakeEntry(active, ev.id),
+        );
       }
       markEventPersisted(ev.id, ev.data?.created_at ?? '');
       return 'persisted-skip';
@@ -910,12 +916,12 @@ export async function streamOnce(
     // The inbox append is the durable record. OpenCode injection is only the
     // wake attempt and may return before the agent finishes processing.
     await appendLine(active.cubeId, active.droneId, line);
-    const openCodeDelivered = isReping
-      ? await injectOpenCode(formatOpenCodeWakePrompt(line), deliveryId, true, ev.id)
-      : await injectOpenCode(formatOpenCodeWakePrompt(line), deliveryId, true);
+    const openCodeDelivered = await injectOpenCode(
+      formatOpenCodeWakePrompt(line), deliveryId, true, ev.id,
+      () => hasPendingWakeEntry(active, ev.id),
+    );
     if (!openCodeDelivered) {
-      if (ev.wake_nonce === undefined) wakeCodex(formatCodexWakePrompt(line));
-      else wakeCodex(formatCodexWakePrompt(line), ev.wake_nonce);
+      wakeCodex(formatCodexWakePrompt(line), ev.wake_nonce, ev.id);
     }
     return 'written';
   };
@@ -1234,9 +1240,12 @@ export async function streamOnce(
           if (
             wakeNonce !== undefined &&
             await shouldDeliverWakeRetry(event.id) &&
-            !(await injectOpenCode(formatOpenCodeWakePrompt(line), wakeNonce, true, event.id))
+            !(await injectOpenCode(
+              formatOpenCodeWakePrompt(line), wakeNonce, true, event.id,
+              () => hasPendingWakeEntry(active, event.id),
+            ))
           ) {
-            wakeCodex(formatCodexWakePrompt(line), wakeNonce);
+            wakeCodex(formatCodexWakePrompt(line), wakeNonce, event.id);
           }
           continue;
         }

package/src/opencode-drone.ts

@@ -89,6 +89,7 @@ interface OpenCodeDelivery {
   acceptedSubmission: boolean;
   sessionId: string | null;
   settled: boolean;
+  isSourcePending?: () => Promise<boolean>;
   state: Exclude<OpenCodeDeliveryState, 'failed'>;
   resolve: (delivered: boolean) => void;
   promise: Promise<boolean>;
@@ -628,6 +629,14 @@ async function deliverOpenCodeEntry(
 ): Promise<OpenCodeDeliveryOutcome> {
   let target: OCSession | null = null;
 
+  const sourcePending = async (): Promise<boolean> => {
+    if (!delivery.isSourcePending) return true;
+    if (await delivery.isSourcePending()) return true;
+    delivery.settled = true;
+    settleOpenCodeEntry(delivery.sourceEntryId);
+    return false;
+  };
+
   // Before the one allowed POST, retries are safe: no submission has happened.
   // OpenCode must generate the message ID: its run loop treats IDs as
   // lexicographically ordered, so arbitrary caller IDs can persist without
@@ -636,6 +645,7 @@ async function deliverOpenCodeEntry(
   for (let attempt = 0; attempt < OPEN_CODE_DELIVERY_RETRY_DELAYS_MS.length; attempt++) {
     if (delivery.settled) return 'delivered';
     if (state !== owner || !owner.connected) return 'failed';
+    if (!(await sourcePending())) return 'delivered';
     if (attempt > 0) {
       delivery.state = 'retried';
       owner.totalEntriesRetried++;
@@ -688,6 +698,7 @@ async function deliverOpenCodeEntry(
       delivery.state = 'delivered-unconfirmed';
     } else {
       if (delivery.settled) return 'delivered';
+      if (!(await sourcePending())) return 'delivered';
       owner.pendingSubmissions.set(delivery.entryId, {
         sourceEntryId: delivery.sourceEntryId,
         sessionId: target.id,
@@ -864,6 +875,7 @@ export function injectOpenCodeEntry(
   entryId: string = createHash('sha256').update(text).digest('hex'),
   allowSubmit: boolean = true,
   sourceEntryId: string = entryId,
+  isSourcePending?: () => Promise<boolean>,
 ): Promise<boolean> {
   const owner = state;
   if (!owner?.connected) {
@@ -882,7 +894,7 @@ export function injectOpenCodeEntry(
   );
   if (pendingSource) {
     log(`entry ${entryId} reconciles pending source ${sourceEntryId}`);
-    return injectOpenCodeEntry(text, pendingSource[0], false, sourceEntryId);
+    return injectOpenCodeEntry(text, pendingSource[0], false, sourceEntryId, isSourcePending);
   }
   for (const [deliveredEntryId, record] of owner.deliveredEntries) {
     if (deliveredEntryId !== entryId && record.sourceEntryId === sourceEntryId) {
@@ -967,6 +979,7 @@ export function injectOpenCodeEntry(
     acceptedSubmission: false,
     sessionId: null,
     settled: false,
+    isSourcePending,
     state: 'queued',
     resolve: resolveDelivery,
     promise,

package/src/parse-clone-args.ts

@@ -1,9 +1,10 @@
 import { redactCloneSecrets } from './clone-security.js';
+import { parseQuickstartArgs, type QuickstartArgs } from './parse-quickstart-args.js';
 
-export interface CloneArgs {
+export interface CloneArgs extends QuickstartArgs {
   repositoryUrl: string;
   destination?: string;
-  noLaunch: boolean;
+  checkoutOnly: boolean;
 }
 
 export type ParseCloneResult =
@@ -13,28 +14,48 @@ export type ParseCloneResult =
 export function parseCloneArgs(rawArgs: readonly string[]): ParseCloneResult {
   let repositoryUrl: string | undefined;
   let destination: string | undefined;
-  let noLaunch = false;
-  for (const arg of rawArgs) {
-    if (arg === '--no-launch') {
-      if (noLaunch) return { ok: false, error: '--no-launch was provided more than once' };
-      noLaunch = true;
+  let checkoutOnly = false;
+  const quickstartArgs: string[] = [];
+  for (let i = 0; i < rawArgs.length; i += 1) {
+    const arg = rawArgs[i];
+    if (arg === '--checkout-only' || arg === '--no-launch') {
+      if (checkoutOnly) return { ok: false, error: 'checkout-only mode was provided more than once' };
+      checkoutOnly = true;
+      continue;
+    }
+    if (arg === '--yes' || arg === '-y') {
+      quickstartArgs.push(arg);
+      continue;
+    }
+    if (arg === '--template' || arg === '--role') {
+      quickstartArgs.push(arg);
+      const value = rawArgs[++i];
+      if (value !== undefined) quickstartArgs.push(value);
       continue;
     }
     if (arg.startsWith('-')) {
-      const option = arg.startsWith('--') ? arg.split('=', 1)[0] : arg.slice(0, 2);
-      return { ok: false, error: `unknown option ${option}; the only option is --no-launch` };
+      return {
+        ok: false,
+        error: `unknown option ${redactCloneSecrets(arg)}; supported: --template, --role, --yes/-y, --checkout-only, --no-launch`,
+      };
     }
     if (repositoryUrl === undefined) repositoryUrl = arg;
     else if (destination === undefined) destination = arg;
     else return { ok: false, error: 'unexpected extra argument' };
   }
   if (!repositoryUrl) return { ok: false, error: 'a repository URL is required' };
+  if (checkoutOnly && quickstartArgs.length > 0) {
+    return { ok: false, error: '--checkout-only/--no-launch cannot be combined with --template, --role, or --yes/-y' };
+  }
+  const parsedQuickstart = parseQuickstartArgs(quickstartArgs);
+  if (!parsedQuickstart.ok) return parsedQuickstart;
   return {
     ok: true,
     args: {
       repositoryUrl,
       ...(destination === undefined ? {} : { destination }),
-      noLaunch,
+      checkoutOnly,
+      ...parsedQuickstart.args,
     },
   };
 }

package/src/quickstart-cmd.ts

@@ -39,6 +39,12 @@ export interface QuickstartDeps {
   runLaunchAll?: typeof runLaunchAll;
 }
 
+export type QuickstartCancellation = 'declined' | 'interrupted';
+
+export interface QuickstartRunOptions {
+  onCancelled?: (kind: QuickstartCancellation) => void;
+}
+
 export function buildDefaultQuickstartDeps(): QuickstartDeps {
   const io = buildDefaultAssimilateDeps();
   return {
@@ -92,7 +98,25 @@ function renderTemplateMenu(): string {
   return `${rows.join('\n')}\n`;
 }
 
-async function selectTemplate(args: QuickstartArgs, deps: QuickstartDeps): Promise<string | null> {
+function reportCancellation(
+  kind: QuickstartCancellation,
+  deps: QuickstartDeps,
+  options: QuickstartRunOptions,
+): void {
+  if (options.onCancelled) {
+    options.onCancelled(kind);
+  } else if (kind === 'interrupted') {
+    deps.stderr('\nborg quickstart: cancelled before anything was created.\n');
+  } else {
+    deps.stdout('Cancelled. Nothing was created.\n');
+  }
+}
+
+async function selectTemplate(
+  args: QuickstartArgs,
+  deps: QuickstartDeps,
+  options: QuickstartRunOptions,
+): Promise<string | null> {
   if (args.template) return args.template;
   if (!deps.isTTY()) return NEW_CUBE_TEMPLATE_PRESENTATIONS[0].name;
   deps.stdout(renderTemplateMenu());
@@ -101,7 +125,7 @@ async function selectTemplate(args: QuickstartArgs, deps: QuickstartDeps): Promi
     try {
       answer = (await deps.prompt('Choose [1]: ')).trim();
     } catch {
-      deps.stderr('\nborg quickstart: cancelled before anything was created.\n');
+      reportCancellation('interrupted', deps, options);
       return null;
     }
     const index = answer === '' ? 0 : /^\d+$/.test(answer) ? Number(answer) - 1 : -1;
@@ -145,7 +169,11 @@ function affirmative(value: string): boolean {
   return answer === '' || answer === 'y' || answer === 'yes';
 }
 
-export async function runQuickstart(args: QuickstartArgs, deps: QuickstartDeps): Promise<number> {
+export async function runQuickstart(
+  args: QuickstartArgs,
+  deps: QuickstartDeps,
+  options: QuickstartRunOptions = {},
+): Promise<number> {
   const assimilate = deps.buildAssimilateDeps();
   let context;
   try {
@@ -207,7 +235,7 @@ export async function runQuickstart(args: QuickstartArgs, deps: QuickstartDeps):
   }
 
   deps.stdout(`Repository  ${context.derivedName}${context.publicRepository ? ` (origin: ${context.publicRepository.value})` : ''}\n`);
-  const template = existing?.template ?? await selectTemplate(args, deps);
+  const template = existing?.template ?? await selectTemplate(args, deps, options);
   if (!template) return 130;
   const availableRoles = existing?.roles ?? plannedTemplateRoles(template);
   const humanSeatRole = availableRoles.find((role) => role.isHumanSeat);
@@ -278,11 +306,11 @@ export async function runQuickstart(args: QuickstartArgs, deps: QuickstartDeps):
     try {
       answer = await deps.prompt(prompt);
     } catch {
-      deps.stderr('\nborg quickstart: cancelled before anything was created.\n');
+      reportCancellation('interrupted', deps, options);
       return 130;
     }
     if (!affirmative(answer)) {
-      deps.stdout('Cancelled. Nothing was created.\n');
+      reportCancellation('declined', deps, options);
       return 0;
     }
   }

package/src/remote-client.ts

@@ -16,6 +16,7 @@ import {
 import { randomUUID } from 'node:crypto';
 import {
   createProtocolEnvelope,
+  decodeAppendLogResult,
   decodeDeleteCubeResponse,
   decodeDeleteRoleRequest,
   decodeDeleteRoleResult,
@@ -90,7 +91,7 @@ const UNREAD_CURSOR_MAX_TRANSPORT_RETRIES = 1;
 // Replay is opt-in: most local requests are mutations or have ambiguous
 // delivery, while unread-log reads carry an explicit cursor and are safe to
 // repeat with the exact same request body.
-type AuthedFetchRetryMode = 'unread-cursor';
+type AuthedFetchRetryMode = 'unread-cursor' | 'append-log';
 export const LOCAL_SERVER_RESPONSE_LIMIT_BYTES = 32 * 1024 * 1024;
 // A typed auth-error envelope is tiny; anything larger is hostile and the
 // bounded read throws → the 401 fails closed to non-destructive CREDENTIAL_REJECTED.
@@ -790,17 +791,17 @@ async function authedFetch(
     return res;
   };
 
-  let transportRetriesRemaining = retryMode === 'unread-cursor'
+  let transportRetriesRemaining = retryMode === 'unread-cursor' || retryMode === 'append-log'
     ? UNREAD_CURSOR_MAX_TRANSPORT_RETRIES
     : 0;
   const requestWithRetry = async (): Promise<Response> => {
     try {
       return await buildRequest(token);
     } catch (error) {
-      if (retryMode !== 'unread-cursor' || !isConnectionReset(error)) throw error;
+      if ((retryMode !== 'unread-cursor' && retryMode !== 'append-log') || !isConnectionReset(error)) throw error;
       if (transportRetriesRemaining === 0) throw unreadLogTransportFailure(error);
       transportRetriesRemaining -= 1;
-      debugLog('↻ retrying unread log read after ECONNRESET');
+      debugLog(`↻ retrying ${retryMode === 'append-log' ? 'log append' : 'unread log read'} after ECONNRESET`);
       try {
         return await buildRequest(token);
       } catch (retryError) {
@@ -1334,31 +1335,14 @@ export async function appendLog(
     to?: string[];
     serverTrustIdentity?: string;
   } = {}
-): Promise<{
-  entry: {
-    id: string;
-    cube_id: string;
-    drone_id: string;
-    message: string;
-    visibility: 'broadcast' | 'direct';
-    created_at: string;
-  };
-  routing?: {
-    class: string | null;
-    recipients: string[];
-    fellOpen: boolean;
-    message: string | null;
-  } | null;
-  // gh#534: directed recipients currently unreachable via the wake path
-  // (wake-path:deaf). Empty/absent for broadcast or all-reachable sends.
-  unreachableRecipients?: { id: string; label: string }[];
-}> {
+): Promise<ReturnType<typeof decodeAppendLogResult>> {
   if (opts.visibility === 'broadcast' && (opts.to?.length ?? 0) > 0) {
     throw new Error(
       "Invalid input: visibility:'broadcast' cannot be combined with non-empty to:. " +
       'Remove visibility to direct to recipients, or remove to: to broadcast.',
     );
   }
+  const postId = randomUUID();
   const local = await localAuthorityContext(
     sessionToken,
     apiUrl,
@@ -1386,11 +1370,12 @@ export async function appendLog(
     } else if (visibility === undefined && recipientDroneIds !== undefined) {
       visibility = 'direct';
     }
-    const payload = await localServerRequest<{ entry: any }>(
+    const payload = await localServerRequest<ReturnType<typeof decodeAppendLogResult>>(
       local,
       `/api/cubes/${local.cubeId}/logs`,
       'POST',
       {
+        post_id: postId,
         message,
         ...(visibility ? { visibility } : {}),
         ...(visibility === 'direct' && recipientDroneIds
@@ -1401,9 +1386,10 @@ export async function appendLog(
         // visibility/recipients override it (server resolveMessageRouting).
         ...(opts.class ? { class: opts.class } : {}),
       },
+      { retryMode: 'append-log', decodePayload: decodeAppendLogResult },
     );
     if (!payload) throw new Error('Local Borg server returned an empty log response');
-  return { entry: payload.entry };
+  return payload;
 }
 
 /**

package/src/server-handshake.ts

@@ -211,10 +211,11 @@ export interface ServerAttachResult {
     sessionId: string;
   };
   result: 'created' | 'reused';
+  initial_log_cursor: { id: string; created_at: string } | null;
 }
 
 /**
- * Attach an enrolled client principal to one granted cube/role over protocol v8.
+ * Attach an enrolled client principal to one granted cube/role over protocol v9.
  * The client CSPRNG-generates the session bearer and persists it PENDING in the
  * OS keychain (keyed by the stable per-seat identity) BEFORE this request, so an
  * interrupted/lost response is recovered by re-sending the exact same bearer —
@@ -237,6 +238,7 @@ export interface PreparedServerAttach {
   drone: ServerAttachResult['drone'];
   session: { sessionId: string };
   result: 'created' | 'reused';
+  initialLogCursor: ServerAttachResult['initial_log_cursor'];
   credentialRef: string;
   pendingBearerDigest: string;
   /** The single-store ATOMIC activate+bind (CR#2 collapse): given the worktree
@@ -391,6 +393,7 @@ export async function sendBorgServerAttach(
         sessionId: decoded.session.id,
       },
       result: decoded.result,
+      initialLogCursor: decoded.initial_log_cursor,
       credentialRef,
       pendingBearerDigest,
       // The single-store ATOMIC activate+bind — invoked by FINALIZE with the decided