borgmcp 3.17.0 → 4.0.1

package/package.json

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

package/src/cli-help.ts

@@ -164,7 +164,10 @@ export function topLevelHelpText(version: string): string {
     `              They coordinate through a shared log (a "cube"). For Claude Code, Codex & OpenCode.\n\n` +
     `Docs & quickstart: https://github.com/Byte-Ventures/borg-mcp-client#readme\n\n` +
     `Install Claude Code, Codex, or OpenCode first. Type \`borg ...\` in your terminal;\n` +
-    `type \`borg_...\` inside your agent session once you've joined a cube ("assimilate").\n\n` +
+    `type \`borg_...\` inside your agent session once you've joined a cube ("assimilate").\n` +
+    `Inside a cube, every log message requires \`to: "broadcast"\` or a non-empty selector list.\n` +
+    `There is no omitted or taxonomy-selected audience.\n` +
+    `Direct routing controls delivery and wakes, not secrecy from other cube members.\n\n` +
     `Usage:\n` +
     `  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` +

package/src/direct-log.ts

@@ -1,9 +1,26 @@
-export function normalizeDirectLogRecipients(value: unknown): string[] {
-  if (value == null) return [];
-  const raw = Array.isArray(value) ? value : [value];
-  const recipients = raw
-    .filter((item): item is string => typeof item === 'string')
-    .map((item) => item.trim())
-    .filter((item) => item.length > 0);
-  return [...new Set(recipients)];
+import { Buffer } from 'node:buffer';
+
+export type LogAudience = 'broadcast' | string[];
+
+export function normalizeLogAudience(value: unknown): LogAudience {
+  if (value === 'broadcast') return value;
+  if (!Array.isArray(value) || value.length === 0 || value.length > 100) {
+    throw new Error('to is required and must be "broadcast" or contain 1-100 recipient selectors');
+  }
+  for (const selector of value) {
+    if (typeof selector !== 'string') {
+      throw new Error('to recipient selectors must be strings containing 1-120 UTF-8 bytes');
+    }
+    const bytes = Buffer.byteLength(selector, 'utf8');
+    if (bytes < 1 || bytes > 120) {
+      throw new Error('to recipient selectors must be strings containing 1-120 UTF-8 bytes');
+    }
+    if (selector !== selector.trim() || /[\u0000-\u001f\u007f-\u009f]/.test(selector)) {
+      throw new Error('to recipient selectors must be trimmed and control-free');
+    }
+  }
+  if (new Set(value).size !== value.length) {
+    throw new Error('to recipient selectors must be unique');
+  }
+  return [...value];
 }

package/src/docs-sections.ts

@@ -39,8 +39,8 @@ export const DOCS_SECTIONS: DocsSection[] = [
     slug: "concepts",
     title: "Core concepts",
     url: `${SITE_URL}/docs/concepts/`,
-    summary: "Cubes, drones, roles, the activity log + signals, claims, decisions.",
-    keywords: ["cube", "drone", "role", "log", "signal", "claim", "decision", "coordinate", "coordination"],
+    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"],
   },
   {
     slug: "install",
@@ -96,7 +96,7 @@ export const DOCS_SECTIONS: DocsSection[] = [
     title: "Tool reference",
     url: `${SITE_URL}/docs/tools/`,
     summary: "Every borg_* tool — name, description, params.",
-    keywords: ["tool", "tools", "api", "reference", "param", "borg_"],
+    keywords: ["tool", "tools", "api", "reference", "param", "borg_", "borg_read-entry", "entry_id", "exact entry"],
   },
   {
     slug: "faq",

package/src/index.ts

@@ -28,6 +28,7 @@ import {
   getRoleInfoByName,
   getRoster,
   readLog,
+  readLogEntry,
   appendLog,
   ackLogEntry,
   getAckStatus,
@@ -87,6 +88,7 @@ import { addUserPromptSubmitHook } from './config-utils.js';
 import {
   humanAgo,
   formatLogEntryMarkdown,
+  formatLogRecipients,
   formatRegenMarkdown,
   getDronePlaybook,
   getDronePlaybookChapter,
@@ -157,7 +159,7 @@ import {
   shouldSuppressLifecycleLog,
 } from './lifecycle-log-guard.js';
 import {
-  normalizeDirectLogRecipients,
+  normalizeLogAudience,
 } from './direct-log.js';
 import { formatLocalManageToolResult } from './local-manage-tool-result.js';
 import {
@@ -850,6 +852,24 @@ export async function main() {
           return { content: [{ type: 'text', text: lines.join('\n') }] };
         }
 
+        case 'borg_read-entry': {
+          const active = await requireActiveCube();
+          const { entry, drones, roles } = await readLogEntry(
+            active.sessionToken,
+            active.apiUrl,
+            args ?? {},
+            active.serverTrustIdentity,
+          );
+          const droneById = new Map(drones.map((drone) => [drone.id, drone]));
+          const roleById = new Map(roles.map((role) => [role.id, role]));
+          const text = [
+            `# Activity log: ${active.name}`,
+            '',
+            formatLogEntryMarkdown(entry, droneById, roleById),
+          ].join('\n');
+          return { content: [{ type: 'text', text }] };
+        }
+
         case 'borg_put-document': {
           const active = await requireActiveCube();
           const result = await putDocument(active.sessionToken, active.apiUrl, args ?? {}, active.serverTrustIdentity);
@@ -880,6 +900,7 @@ export async function main() {
         case 'borg_log': {
           const message = args?.message as string;
           if (!message || typeof message !== 'string') throw new Error('message is required');
+          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.');
           seedDisplayIdentity(active);
@@ -900,28 +921,33 @@ export async function main() {
               };
             }
           }
-          const hasTo = Object.prototype.hasOwnProperty.call(args ?? {}, 'to');
-          const recipients = hasTo ? normalizeDirectLogRecipients(args?.to) : undefined;
           const explicitClass = typeof args?.class === 'string' ? args.class : undefined;
-          const visibility: 'broadcast' | 'direct' | undefined =
-            args?.visibility === 'broadcast' || args?.visibility === 'direct'
-              ? args.visibility
-              : undefined;
           const documents = args?.documents as string[] | undefined;
           if (!active.serverTrustIdentity) {
             throw new Error('Selected Borg server authority state is missing or unreadable');
           }
           const appendOpts = {
+            to,
             ...(explicitClass ? { class: explicitClass } : {}),
-            ...(hasTo ? { to: recipients ?? [] } : {}),
-            ...(visibility ? { visibility } : {}),
             ...(documents ? { documents } : {}),
             serverTrustIdentity: active.serverTrustIdentity,
           };
           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}` : '';
+          let recipientDrones: any[] = [];
+          if (result.entry.visibility === 'direct' && result.entry.recipient_drone_ids.length > 0) {
+            try {
+              recipientDrones = (await getRoster(active)).drones;
+            } catch {
+              // The log is already persisted; keep success truthful with stable id fallbacks.
+            }
+          }
+          const recipientById = new Map(recipientDrones.map((drone) => [drone.id, drone]));
+          const routedRecipients = formatLogRecipients(result.entry, recipientById);
+          const routed = routedRecipients.length > 0
+            ? `\nRecipients: ${routedRecipients.join(', ')}`
+            : '';
           // gh#534: surface to the SENDER which directed recipients are
           // currently unreachable via the wake path. The message is delivered
           // regardless (persisted server-side); they read it when they return.
@@ -933,9 +959,9 @@ export async function main() {
           const cited = formatDocumentCitations(result.entry.documents);
           const citations = cited.length > 0 ? `\nDocuments: ${cited.join('; ')}` : '';
           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 and cite its full id in borg_log.documents.`
+            ? `\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})${echo}${unreachable}${citations}${advisory}`;
+          const text = `Logged to cube "${displayIdentity.cubeName}" as ${displayIdentity.droneLabel}. (entry id: ${result.entry.id})${routed}${unreachable}${citations}${advisory}`;
           return { content: [{ type: 'text', text }] };
         }
 

package/src/log-audit-core.ts

@@ -1,7 +1,8 @@
 export const LOG_AUDIT_NUDGE = (count: number): string =>
   `Heads up: ${count}+ state-changing tool calls since the last \`borg_log\` post. ` +
   'If that work was a substantive unit (a change that ships, a blocker hit, a finding ' +
-  "worth sharing), post to the cube log per your role's conventions before continuing.";
+  "worth sharing), post to the cube log per your role's conventions before continuing. " +
+  'Choose `to: "broadcast"` or a non-empty selector array; never omit `to`.';
 
 /**
  * Pure transcript scan shared by the Claude hook and the OpenCode plugin.
@@ -12,7 +13,8 @@ export function evaluateLogAudit(
   renderNudge: (count: number) => string = (count) =>
     `Heads up: ${count}+ state-changing tool calls since the last \`borg_log\` post. ` +
     'If that work was a substantive unit (a change that ships, a blocker hit, a finding ' +
-    "worth sharing), post to the cube log per your role's conventions before continuing.",
+    "worth sharing), post to the cube log per your role's conventions before continuing. " +
+    'Choose `to: "broadcast"` or a non-empty selector array; never omit `to`.',
 ): string | null {
   const materialTools = new Set([
     'Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'Bash',

package/src/regen-format.ts

@@ -240,6 +240,8 @@ export function markArrivalAnnouncedThisProcess(): void {
 // copy-param-claim: borg_ack-status.entry_id
 //   The playbook below directs uncertain receipt checks through the read-only
 //   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_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
@@ -247,7 +249,7 @@ export function markArrivalAnnouncedThisProcess(): void {
 export function getDronePlaybook(): string {
   const arrivalInstruction = arrivalAnnouncedThisProcess
     ? ''
-    : `\n**When this MCP session first starts:** post one \`ARRIVAL: <your-label> (<your-role>) online on ${osHostname()}\`. After the post succeeds, the client suppresses this instruction until the MCP process restarts; an explicit \`/mcp\` reconnect may show it again.\n`;
+    : `\n**When this MCP session first starts:** call \`borg_log message="ARRIVAL: <your-label> (<your-role>) online on ${osHostname()}" to="broadcast"\` once. 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.
@@ -260,10 +262,11 @@ You're a Drone in a Cube. Coordinate with other drones through the activity log.
 - \`borg_role\` — re-read your role's detailed playbook
 - \`borg_roster\` — see who else is connected
 - \`borg_read-log unread_only=true [limit]\` — drain unread log entries from your server-side cursor
-- \`borg_log <message>\` — append to the log
+- \`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_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.
+**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.
@@ -282,10 +285,10 @@ You're a Drone in a Cube. Coordinate with other drones through the activity log.
    or a status reply must never be the last action of a turn while work is outstanding.
 6. Nothing actionable, no prompt, and no work of your own outstanding → 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 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\`. If you later need one known entry's complete body, call \`borg_read-entry entry_id=<id>\`. Do NOT triage with \`since=<notification timestamp>\` (strict-after — skips the boundary entry) or a bare window (skips older-unread during bursts).
 ${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.
+**When a log entry asks you to act:** if its explicit \`to\` audience includes your drone and its message assigns you work or directly asks you to act, 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 actionable assignments and direct action requests only — not every addressed entry or mention.
 
 **Claim a work item before you start it (\`borg_ack ... kind=claim\`):** \`borg_ack\` has two kinds — \`ack\` (receipt, the default) and \`claim\` (advisory ownership of a routed work item you are about to take). When a routed entry could be picked up by more than one drone, \`borg_ack entry_id=<id> kind=claim\` BEFORE starting — it announces you are taking it so peers skip the duplicate work, and wakes the rest of the entry's audience. If a live peer already holds the claim, skip it; if the claim is STALE (the claimant went silent past the wake-path SLA), re-claim and proceed. A claim is ADVISORY only — it NEVER substitutes for the completion or approval signal your role's conventions require; a bogus or abandoned claim can at most delay a work item, never bypass its real gate.
 
@@ -303,9 +306,9 @@ ${arrivalInstruction}
 
 **Posting to the log:** post per your role's conventions whenever you start/finish a task, get stuck, answer a drone, or learn something others need — regardless of who initiated (a log signal, your own scan, or a user prompt). Conventions live in your role detail; the system is vocabulary-agnostic.
 
-**Routing posts — widen the directed default:** the taxonomy routes most prefixes DIRECTED to your cube's coordinating role; your \`to:\` / \`visibility:\` overrides it. Widen when a post must reach more than the coordinating role:
-- Posting a verdict / decision / result a specific drone is waiting on: add \`to:[that drone]\` so they're WOKEN — without it they can be left UNAWARE of their own merge or feedback. Directed governs the WAKE; it is NOT read-confidentiality: every member can read every entry — the cube is the trust boundary — so never post secrets relying on \`to:[x]\`.
-- Any drone posting a multi-seat DELIVERABLE (spec / security classification / review artifact 3+ seats build or gate against): pass \`visibility:broadcast\` (or \`to:[the seats]\`) EVEN IF your prefix (\`DONE\` etc.) is a directed status class — else only your coordinating role wakes (taxonomy routes by prefix, not payload) and the building/gating seats miss it.
+**Address every post explicitly:** use \`to: ["<selector>"]\` for one or more intended recipients and \`to: "broadcast"\` for every drone. Prefixes and optional \`class\` values classify and lifecycle-tag entries only; they never route or supply a default audience.
+- Posting a verdict / decision / result a specific drone is waiting on: include that drone in a non-empty \`to\` selector array so they're WOKEN. Direct addressing governs delivery and the WAKE; it is NOT read-confidentiality: every member can read every entry — the cube is the trust boundary, so never post secrets relying on direct routing.
+- Any drone posting a multi-seat DELIVERABLE (spec / security classification / review artifact 3+ seats build or gate against): use \`to: "broadcast"\` or explicitly list every intended selector. Never rely on the signal prefix or class to choose recipients.
 
 **Pre-commit git hygiene (universal):**
 
@@ -361,7 +364,7 @@ The discipline applies at FOUR surfaces. Catches at the surface closest to origi
 - **Surface 1 (brainstorm-proposal time)**: when a brainstorm contribution names specific code identifiers / API field names / enum values / column names / function signatures, the PROPOSING drone source-grep's the referenced file BEFORE composing the proposal. If the proposal cites current \`origin/main\` or a branch/SHA, grep that ref via \`git show <ref>:<path> | grep\`; working-tree grep is only for explicitly local/uncommitted claims. Cheapest catch surface; one drone catches one error.
 - **Surface 2 (comment/JSDoc/docstring writing time)**: when an implementation comment cites cross-file invariants (other modules' thresholds, schema columns, enum values, semantic contracts), the WRITING drone source-grep's the referenced file BEFORE writing the comment. If the comment describes a merged/base/PR-head state, grep the named ref via \`git show <ref>:<path> | grep\`; don't let a stale local checkout stand in for the ref being described. Mid-cost catch; one drone catches one error but downstream reviewers may inherit the wrong mental model from the comment.
 - **Surface 3 (review-time verification)**: the existing review-class discipline (Code Reviewer formal gates + Security Auditor SR gates + PM/UX/QA courtesy reviews). Late catch opportunity; if the error propagated through Surfaces 1 + 2, multiple reviewers may have already trusted the framing instead of source-grepping themselves.
-- **Surface 4 (durable-tracking-artifact-writing time)**: when filing a deferred-tracking issue from a cube event payload, the FILING drone fetches the originating entry's full body from the cube log BEFORE composing the issue body. For routine wake triage, use \`borg_read-log unread_only=true\` and drain until caught up; do not rely on a truncated event preview or a \`since=<same timestamp>\` read, which can skip the boundary entry. Cube event previews can truncate substantive content (mid-paragraph cuts on long entries); filing from the truncated preview trusts a derivative artifact instead of the source-of-truth full entry. Most expensive surface — the filed issue becomes the cube's durable cross-cycle memory; correcting it requires a follow-up correction post, and later pickup drones inherit the incomplete framing if the correction is missed.
+- **Surface 4 (durable-tracking-artifact-writing time)**: when filing a deferred-tracking issue from a cube event payload, the FILING drone fetches the originating entry's full body with \`borg_read-entry entry_id=<id>\` BEFORE composing the issue body. For routine wake triage, use \`borg_read-log unread_only=true\` and drain until caught up; do not rely on a truncated event preview or a \`since=<same timestamp>\` read, which can skip the boundary entry. Cube event previews can truncate substantive content (mid-paragraph cuts on long entries); filing from the truncated preview trusts a derivative artifact instead of the source-of-truth full entry. Most expensive surface — the filed issue becomes the cube's durable cross-cycle memory; correcting it requires a follow-up correction post, and later pickup drones inherit the incomplete framing if the correction is missed.
 
 **Ratified-decision drift is a four-surface drift-class.** A ratified cube decision restated from memory drifts exactly like a code-identifier claim — it propagates dispatch (Surface 1, brainstorm) → copy (Surface 2, comment) → gate (Surface 3, review), and the cheapest catch is at the brainstorm surface. At each surface, a drone restating a ratified decision source-reads \`borg_decisions {topic}\` FIRST: the active registry entry is the source of truth; your memory is a derivative artifact. Core rule — **cite ratified decisions by topic; never restate one from memory.**
 
@@ -403,9 +406,9 @@ export function humanAgo(date: Date | string): string {
  * include — robustness wins.
  */
 /**
- * gh#479 — discoverability tip for intent-based routing (#468). When a
+ * gh#479 — discoverability tip for message classification. When a
  * cube has no `message_taxonomy` declared, borg_regen + borg_cube append
- * this tip so operators discover how to enable smart routing. Self-
+ * this tip so operators discover how to classify signals and lifecycle. Self-
  * removing: returns '' once a taxonomy exists. Copy is UX-locked
  * (design d45098c1) — keep verbatim.
  */
@@ -419,7 +422,7 @@ export function nullTaxonomyTip(messageTaxonomy: unknown): string {
   //   this inline marker pins the real inputSchema param so the #490/#529 guard
   //   (client/__tests__/copy-mechanism-guard.test.ts) verifies the tool actually
   //   exposes it — the #479 miss class, now caught co-located with the copy.
-  return 'Tip: no message taxonomy declared — set one to enable intent-based smart routing (#468). Use borg_update-cube with a taxonomy array, or add classes with borg_patch-taxonomy-class.';
+  return 'Tip: no message taxonomy declared — set one to classify signal prefixes and dispatch/completion lifecycle. Every borg_log call still requires an explicit to audience. Use borg_update-cube with a taxonomy array, or add classes with borg_patch-taxonomy-class.';
 }
 
 export function regenWakePathDroneLabel(
@@ -574,7 +577,7 @@ export function formatRegenMarkdown(
     ? [
         '## Getting started',
         '',
-        '**You (this agent):** post `borg_log message="<task>"`; check `borg_roster`.',
+        '**You (this agent):** post `borg_log message="<task>" to="broadcast"`; check `borg_roster`.',
         '**Your user:** in a new terminal in the repository, add a teammate: `borg assimilate <role>`; optional `--worktree <name>` names its worktree.',
         'For "what do I do next?", use `borg_docs`.',
         '',
@@ -704,8 +707,26 @@ export function formatLogEntryMarkdown(
       ? ` ${formatDroneAddressToken(entry.drone_id)}`
       : '';
   const citations = formatDocumentCitations(entry.documents);
+  const recipients = formatLogRecipients(entry, droneById);
+  const routed = recipients.length > 0
+    ? `\n  Recipients: ${recipients.join(', ')}`
+    : '';
   const documents = citations.length > 0
     ? `\n  Documents:\n${citations.map((citation) => `  - ${citation}`).join('\n')}`
     : '';
-  return `**[${ts}]**${entryId}${addr} ${d?.label ?? '?'} (${r?.name ?? '?'}): ${entry.message}${documents}`;
+  return `**[${ts}]**${entryId}${addr} ${d?.label ?? '?'} (${r?.name ?? '?'}): ${entry.message}${routed}${documents}`;
+}
+
+export function formatLogRecipients(
+  entry: { visibility?: unknown; recipient_drone_ids?: unknown },
+  droneById: Map<string, any>,
+): string[] {
+  if (entry.visibility !== 'direct' || !Array.isArray(entry.recipient_drone_ids)) return [];
+  return entry.recipient_drone_ids.map((droneId) => {
+    if (typeof droneId !== 'string') return '?';
+    const label = droneById.get(droneId)?.label;
+    return typeof label === 'string' && label.length > 0
+      ? label
+      : formatDroneAddressToken(droneId);
+  });
 }

package/src/remote-client.ts

@@ -24,6 +24,8 @@ import {
   decodeDeleteRoleRequest,
   decodeDeleteRoleResult,
   decodeDroneRuntimeMetadataState,
+  decodeEntryQueryRequest,
+  decodeEntryQueryResult,
   decodeEvictDroneResult,
   decodeProtocolEnvelope,
   decodeProtocolErrorEnvelope,
@@ -45,6 +47,7 @@ import {
   type AckStatusResult,
   type AgentKind,
   type DeleteRoleResult,
+  type EntryQueryResult,
   type EvictDroneResult,
   type ReassignDroneResult,
   type RoleRationaleResult,
@@ -89,7 +92,7 @@ import {
   type LocalServerCursor,
 } from './local-server-cursor.js';
 import { readBoundedResponseBody } from './server-response.js';
-import { resolveLocalLogRecipients } from './local-log-routing.js';
+import { normalizeLogAudience, type LogAudience } from './direct-log.js';
 import { RoleSectionConflictError } from './local-manage-tool-result.js';
 
 export interface RemoteConnection {
@@ -1112,6 +1115,32 @@ export async function readLog(
   };
 }
 
+/** Read one complete log entry without consulting or advancing the unread cursor. */
+export async function readLogEntry(
+  sessionToken: string,
+  apiUrl: string,
+  input: unknown,
+  serverTrustIdentity?: string,
+): Promise<{ entry: EntryQueryResult['entry']; drones: any[]; roles: any[] }> {
+  const request = decodeEntryQueryRequest(input);
+  const local = await localAuthorityContext(sessionToken, apiUrl, serverTrustIdentity);
+  const result = await localServerRequest<EntryQueryResult>(
+    local,
+    `/api/cubes/${local.cubeId}/logs/${encodeURIComponent(request.entry_id)}`,
+    'GET',
+    undefined,
+    { decodePayload: decodeEntryQueryResult },
+  );
+  if (!result) throw new Error('Local Borg server returned an empty log-entry response');
+  if (request.entry_id.length === 36
+    ? result.entry.id !== request.entry_id
+    : !result.entry.id.startsWith(request.entry_id)) {
+    throw new ProtocolContractError('Log-entry response id does not match the requested selector.');
+  }
+  const composed = await localCubeComposition(local);
+  return { entry: result.entry, drones: composed.drones, roles: composed.roles };
+}
+
 /**
  * Sprint 25 log substrate refactor: explicit ack on a log entry.
  *
@@ -1445,69 +1474,34 @@ export async function appendLog(
   apiUrl: string,
   message: string,
   opts: {
-    visibility?: 'broadcast' | 'direct';
-    recipientDroneIds?: string[];
+    to: LogAudience;
     class?: string;
-    to?: string[];
     documents?: string[];
     serverTrustIdentity?: 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.',
-    );
-  }
-  if (opts.to?.length === 0) {
-    throw new Error('Direct log recipient list must contain at least one recipient');
-  }
+  const to = normalizeLogAudience(opts?.to);
   const postId = randomUUID();
   const local = await localAuthorityContext(
     sessionToken,
     apiUrl,
     opts.serverTrustIdentity,
   );
-  let visibility = opts.visibility;
-  let recipientDroneIds = opts.recipientDroneIds;
-    if (visibility !== 'broadcast' &&
-        (!recipientDroneIds || recipientDroneIds.length === 0) &&
-        opts.to !== undefined) {
-      const base = `/api/cubes/${local.cubeId}`;
-      const [rolePayload, dronePayload] = await Promise.all([
-        localServerRequest<{ roles: any[] }>(local, `${base}/roles`, 'GET'),
-        localServerRequest<{ drones: any[] }>(local, `${base}/drones`, 'GET'),
-      ]);
-      if (!rolePayload || !dronePayload) {
-        throw new Error('Local Borg server returned an incomplete cube roster');
-      }
-      recipientDroneIds = resolveLocalLogRecipients(
-        opts.to,
-        dronePayload.drones,
-        rolePayload.roles,
-      );
-      visibility = 'direct';
-    } else if (visibility === undefined && recipientDroneIds !== undefined) {
-      visibility = 'direct';
-    }
-    const request = decodeAppendLogRequest({
-      post_id: postId,
-      message,
-      ...(visibility ? { visibility } : {}),
-      ...(visibility === 'direct' && recipientDroneIds
-        ? { recipientDroneIds }
-        : {}),
-      ...(opts.class ? { class: opts.class } : {}),
-      ...(opts.documents ? { documents: opts.documents } : {}),
-    });
-    const payload = await localServerRequest<ReturnType<typeof decodeAppendLogResult>>(
-      local,
-      `/api/cubes/${local.cubeId}/logs`,
-      'POST',
-      { ...request },
-      { retryMode: 'append-log', decodePayload: decodeAppendLogResult },
-    );
-    if (!payload) throw new Error('Local Borg server returned an empty log response');
+  const request = decodeAppendLogRequest({
+    post_id: postId,
+    message,
+    to,
+    ...(opts.class ? { class: opts.class } : {}),
+    ...(opts.documents ? { documents: opts.documents } : {}),
+  });
+  const payload = await localServerRequest<ReturnType<typeof decodeAppendLogResult>>(
+    local,
+    `/api/cubes/${local.cubeId}/logs`,
+    'POST',
+    { ...request },
+    { retryMode: 'append-log', decodePayload: decodeAppendLogResult },
+  );
+  if (!payload) throw new Error('Local Borg server returned an empty log response');
   return payload;
 }
 

package/src/server-handshake.ts

@@ -215,7 +215,7 @@ export interface ServerAttachResult {
 }
 
 /**
- * Attach an enrolled client principal to one granted cube/role over protocol v11.
+ * Attach an enrolled client principal to one granted cube/role over protocol v12.
  * The client CSPRNG-generates the session bearer and persists it PENDING in the
  * local 0600 credential store (keyed by the stable per-seat identity) BEFORE
  * this request, so an interrupted/lost response is recovered by re-sending the