borgmcp 1.0.38 → 1.0.39

package/dist/claude.js

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
-import{spawn as L}from"child_process";import{randomUUID as M}from"node:crypto";import{basename as E}from"node:path";import{createInterface as O}from"node:readline/promises";import t from"chalk";import{findProjectRoot as y,getActiveCube as H,getLaunchModel as F,inboxPathForDrone as N,setCodexWakeTarget as B,pruneDeadCodexWakeTargets as _}from"./cubes.js";import{applyOllamaLaunchEnv as G,checkModelReachable as W}from"./model-presets.js";import{handleVersionFlag as Y,getPackageVersion as g}from"./version.js";import{isHelpFlag as S,setupHelpText as U,topLevelHelpText as V,assimilateHelpText as j}from"./cli-help.js";import{runSpawn as K}from"./spawn.js";import{parseSyncArgs as q,runSync as z}from"./sync.js";import{parseCleanupArgs as X,runCleanup as J}from"./cleanup-cmd.js";import{parseAssimilateArgs as Q}from"./parse-assimilate-args.js";import{runAssimilate as Z}from"./assimilate-cmd.js";import{buildDefaultAssimilateDeps as ee}from"./assimilate-deps.js";import{parseLaunchAllArgs as T}from"./parse-launch-all-args.js";import{runLaunchAll as A}from"./launch-all-cmd.js";import{buildDefaultLaunchAllDeps as w}from"./launch-all-deps.js";import{discoverDroneCandidates as re}from"./launch-all-discovery.js";import{runBareLaunchMenu as oe,shouldShowLaunchMenu as se}from"./bare-launch-menu.js";import{setTerminalTitle as te}from"./terminal-title.js";import{initConsolePrefix as ae,consolePrefix as o}from"./console-prefix.js";import{initDebugFromArgv as ie}from"./debug.js";import{fetchLatestBorgmcpVersion as ne,compareVersionsForStaleness as ce}from"./stale-version-check.js";import{defaultCliChoiceDeps as le,detectCliAvailability as x,installedCliNames as I,parseCliFlag as de,resolveCliChoice as pe}from"./cli-platform.js";import{getRefreshToken as ue,getIdToken as me}from"./config.js";import{composeGetStarted as fe,shouldShowGetStarted as ge}from"./get-started.js";import{prepareCodexRemoteLaunch as he,withCodexCwdArg as we,defaultCodexRemoteDeps as xe,checkCodexBridgeHealthy as ve}from"./codex-remote.js";import{findLoadedCodexThread as be}from"./codex-app-server.js";import{buildAgentKickoffPrompt as Ce,recordCodexWakeTarget as ke,socketPathFromRemoteArgs as P}from"./codex-launch.js";import{codexBorgSessionConfigArgs as $e}from"./launch-gate.js";import{addCodexMcpServer as ye,addCodexSessionStartHook as Se,addCodexUserPromptSubmitHook as Te,addMcpServer as Ae,addProjectSessionStartHook as Ie,addUserPromptSubmitHook as Pe,isCodexMcpServerConfigured as Re,isMcpServerConfigured as De,removeSessionStartHook as Le}from"./config-utils.js";async function Me(){ie(process.argv),Y(),await ae();const c=(async()=>{if(!process.stderr.isTTY)return;const e=g(),r=await ne();if(!r)return;const i=ce(e,r);i.stale&&i.message&&process.stderr.write(`${o()}${i.message}
-`)})();if((process.argv[2]==="--help"||process.argv[2]==="-h")&&(process.stdout.write(V(g())),process.exit(0)),process.argv[2]==="setup"){S(process.argv[3])&&(process.stdout.write(U(g())),process.exit(0)),await import("./setup.js");return}if(process.argv[2]==="assimilate"){process.argv.slice(3).some(S)&&(process.stdout.write(j(g())),process.exit(0));const e=Q(process.argv.slice(3));e.ok||(process.stderr.write(t.red(`${o()}\u25FC borg assimilate: ${e.error}
-`)),process.stderr.write("Run `borg --help` for usage.\n"),process.exit(1));const r=ee(),i=await Z({role:e.role,flags:e.flags},r);process.exit(i)}if(process.argv[2]==="spawn"){const e=await K();process.exit(e)}if(process.argv[2]==="sync"){const e=q(process.argv.slice(3));e.ok||(process.stderr.write(t.red(`${o()}\u25FC borg sync: ${e.error}
-`)),process.stderr.write("Run `borg --help` for usage.\n"),process.exit(1));const r=await z({},e.options);process.exit(r)}if(process.argv[2]==="cleanup"){const e=X(process.argv.slice(3));e.ok||(process.stderr.write(t.red(`${o()}\u25FC borg cleanup: ${e.error}
-`)),process.stderr.write("Run `borg --help` for usage.\n"),process.exit(1));const r=await J({},e.options);process.exit(r)}if(process.argv[2]==="launch-all"){const e=T(process.argv.slice(3));e.ok||(process.stderr.write(t.red(`${o()}\u25FC borg launch-all: ${e.error}
-`)),process.stderr.write("Run `borg --help` for usage.\n"),process.exit(1));const r=w(),i=await A(e.args,r);process.exit(i)}if(ge(await ue()!==null,await me()!==null)){const e=I(x()).length>0;process.stdout.write(fe(e)),process.exit(0)}const n=de(process.argv.slice(2));n.error&&(process.stderr.write(t.red(`${o()}\u25FC ${n.error}
-`)),process.stderr.write("Run `borg --help` for usage.\n"),process.exit(1));const v=async e=>{const r=O({input:process.stdin,output:process.stdout});try{return await r.question(e)}finally{r.close()}};let s=await pe(n.cli,le(v,()=>process.stdin.isTTY===!0));Ee();const a=await H();if(se({extraArgs:process.argv.slice(2),stdinIsTTY:process.stdin.isTTY===!0,stdoutIsTTY:process.stdout.isTTY===!0})){const e=I(x()).find(m=>m!==s)??null;let r=!1;a&&(r=(await re({targetCubeId:a.cubeId},w())).length>0);const i=await oe({defaultCli:s,otherInstalledCli:e,hasLaunchAllTargets:r},v);if(i.kind==="launch-all"){const m=T([]),D=m.ok?await A(m.args,w()):1;process.exit(D)}s=i.cli}const l=n.rest;te(a?{label:a.droneLabel,cubeName:a.name}:null,E(process.cwd()));const R=a&&s==="claude"?`If you haven't yet, arm a persistent Monitor running the command \`borg-inbox-monitor ${N(a.cubeId,a.droneId)}\` so each event's task-notification title summarizes the new cube log entry (drone label, role, and first ~80 chars of the message body) \u2014 letting you triage events without reading the full body. `:"";await Promise.race([c,new Promise(e=>setTimeout(e,2e3))]);const b=s==="codex"?`borg-wake-${M()}`:null;let f,C=[],d={...process.env,BORG_SESSION:"1"},p=null,u=null;if(s==="codex"&&!l.includes("--remote")){console.error(`${o()}${t.gray("\u25FC Starting Codex remote-wake app-server\u2026")}`);const e=await he(xe());e.warning?(console.error(`${o()}${t.yellow(`warning: ${e.warning}`)}`),f="\u26A0 Codex wake-path capability check failed: remote-control is unavailable for this session. Run borg_regen manually whenever you return, and expect only fallback wakeups until relaunch."):f="Codex wake-path capability check passed: remote-control socket established for this session.",C=e.args,d={...process.env,...e.env,BORG_SESSION:"1"},p=P(e.args),u=e.server?.cleanup??null}else s==="codex"&&l.includes("--remote")&&(f="Codex wake-path capability check: using caller-provided --remote socket; if no wake arrives, run borg_regen manually when returning to the session.",p=P(l),p&&(d={...process.env,BORG_CODEX_REMOTE_WAKE:"1",BORG_SESSION:"1"}));if(a){const e=await F(a.cubeId,y(),a.droneId),r=G(d,e,process.env);if(d=r.env,r.probe){const i=await W(r.probe.descriptor,fetch,r.probe.baseUrl);i.ok||console.error(`${o()}${t.yellow(`warning: ${i.message}`)}`)}}const k=Ce({cli:s,codexWakeNonce:b,monitorClause:R,codexWakePathClause:f});let h=[...l,k];s==="codex"&&(h=[...$e(),...C,...we(h,process.cwd())]),console.error(`${o()}${t.blue(`\u25FC Launching ${s==="claude"?"Claude Code":"Codex"}\u2026`)}`);const $=L(s,h,{stdio:"inherit",shell:!1,env:d});s==="codex"&&a&&p&&(ke({deps:{setCodexWakeTarget:B,findLoadedCodexThread:be},cubeId:a.cubeId,droneId:a.droneId,socketPath:p,passthroughArgs:l,previewNeedle:b??k.slice(0,120),cwd:process.cwd(),launchedAtSeconds:Math.floor(Date.now()/1e3)}),_(e=>ve(e))),$.on("error",e=>{if(u)try{u()}catch{}e.code==="ENOENT"?(console.error(`${o()}${t.red(`
-\u25FC Failed to launch ${s}`)}`),console.error(`${o()}${t.gray(`Make sure ${s} is installed.
-`)}`)):console.error(`${o()}${t.red(`
-\u25FC Failed to launch ${s}: ${e.message}
-`)}`),process.exit(1)}),$.on("exit",e=>{if(u)try{u()}catch{}process.exit(e??0)})}function Ee(){const c=x();if(c.claude)try{De()||Ae(),Ie(y(process.cwd())),Le(),Pe()}catch(n){console.error(`${o()}${t.yellow(`warning: Claude Code integration check failed: ${n?.message??n}`)}`)}if(c.codex)try{Re()||ye(),Se(),Te()}catch(n){console.error(`${o()}${t.yellow(`warning: Codex integration check failed: ${n?.message??n}`)}`)}}Me().catch(c=>{console.error(`${o()}${t.red(`
+import{spawn as M}from"child_process";import{randomUUID as E}from"node:crypto";import{basename as O}from"node:path";import{createInterface as H}from"node:readline/promises";import s from"chalk";import{findProjectRoot as S,getActiveCube as F,getLaunchModel as N,inboxPathForDrone as B,setCodexWakeTarget as _,pruneDeadCodexWakeTargets as G}from"./cubes.js";import{applyOllamaLaunchEnv as W,checkModelReachable as Y}from"./model-presets.js";import{handleVersionFlag as U,getPackageVersion as h}from"./version.js";import{isHelpFlag as T,setupHelpText as V,topLevelHelpText as j,assimilateHelpText as K}from"./cli-help.js";import{runSpawn as q}from"./spawn.js";import{parseSyncArgs as z,runSync as X}from"./sync.js";import{parseCleanupArgs as J,runCleanup as Q}from"./cleanup-cmd.js";import{parseAssimilateArgs as Z}from"./parse-assimilate-args.js";import{runAssimilate as ee}from"./assimilate-cmd.js";import{buildDefaultAssimilateDeps as re}from"./assimilate-deps.js";import{parseLaunchAllArgs as A}from"./parse-launch-all-args.js";import{unknownSubcommand as oe}from"./unknown-subcommand.js";import{runLaunchAll as I}from"./launch-all-cmd.js";import{buildDefaultLaunchAllDeps as x}from"./launch-all-deps.js";import{discoverDroneCandidates as se}from"./launch-all-discovery.js";import{runBareLaunchMenu as te,shouldShowLaunchMenu as ae}from"./bare-launch-menu.js";import{setTerminalTitle as ie}from"./terminal-title.js";import{initConsolePrefix as ne,consolePrefix as o}from"./console-prefix.js";import{initDebugFromArgv as ce}from"./debug.js";import{fetchLatestBorgmcpVersion as le,compareVersionsForStaleness as de}from"./stale-version-check.js";import{defaultCliChoiceDeps as pe,detectCliAvailability as v,installedCliNames as R,parseCliFlag as ue,resolveCliChoice as me}from"./cli-platform.js";import{getRefreshToken as fe,getIdToken as ge}from"./config.js";import{composeGetStarted as he,shouldShowGetStarted as we}from"./get-started.js";import{prepareCodexRemoteLaunch as xe,withCodexCwdArg as ve,defaultCodexRemoteDeps as be,checkCodexBridgeHealthy as Ce}from"./codex-remote.js";import{findLoadedCodexThread as ke}from"./codex-app-server.js";import{buildAgentKickoffPrompt as $e,recordCodexWakeTarget as ye,socketPathFromRemoteArgs as P}from"./codex-launch.js";import{codexBorgSessionConfigArgs as Se}from"./launch-gate.js";import{addCodexMcpServer as Te,addCodexSessionStartHook as Ae,addCodexUserPromptSubmitHook as Ie,addMcpServer as Re,addProjectSessionStartHook as Pe,addUserPromptSubmitHook as De,isCodexMcpServerConfigured as Le,isMcpServerConfigured as Me,removeSessionStartHook as Ee}from"./config-utils.js";async function Oe(){ce(process.argv),U(),await ne();const c=(async()=>{if(!process.stderr.isTTY)return;const e=h(),r=await le();if(!r)return;const i=de(e,r);i.stale&&i.message&&process.stderr.write(`${o()}${i.message}
+`)})();if((process.argv[2]==="--help"||process.argv[2]==="-h")&&(process.stdout.write(j(h())),process.exit(0)),process.argv[2]==="setup"){T(process.argv[3])&&(process.stdout.write(V(h())),process.exit(0)),await import("./setup.js");return}if(process.argv[2]==="assimilate"){process.argv.slice(3).some(T)&&(process.stdout.write(K(h())),process.exit(0));const e=Z(process.argv.slice(3));e.ok||(process.stderr.write(s.red(`${o()}\u25FC borg assimilate: ${e.error}
+`)),process.stderr.write("Run `borg --help` for usage.\n"),process.exit(1));const r=re(),i=await ee({role:e.role,flags:e.flags},r);process.exit(i)}if(process.argv[2]==="spawn"){const e=await q();process.exit(e)}if(process.argv[2]==="sync"){const e=z(process.argv.slice(3));e.ok||(process.stderr.write(s.red(`${o()}\u25FC borg sync: ${e.error}
+`)),process.stderr.write("Run `borg --help` for usage.\n"),process.exit(1));const r=await X({},e.options);process.exit(r)}if(process.argv[2]==="cleanup"){const e=J(process.argv.slice(3));e.ok||(process.stderr.write(s.red(`${o()}\u25FC borg cleanup: ${e.error}
+`)),process.stderr.write("Run `borg --help` for usage.\n"),process.exit(1));const r=await Q({},e.options);process.exit(r)}if(process.argv[2]==="launch-all"){const e=A(process.argv.slice(3));e.ok||(process.stderr.write(s.red(`${o()}\u25FC borg launch-all: ${e.error}
+`)),process.stderr.write("Run `borg --help` for usage.\n"),process.exit(1));const r=x(),i=await I(e.args,r);process.exit(i)}const n=oe(process.argv[2]);if(n!==null&&(process.stderr.write(s.red(`${o()}\u25FC unknown command: ${n}
+`)),process.stderr.write("Run `borg --help` for usage.\n"),process.exit(1)),we(await fe()!==null,await ge()!==null)){const e=R(v()).length>0;process.stdout.write(he(e)),process.exit(0)}const f=ue(process.argv.slice(2));f.error&&(process.stderr.write(s.red(`${o()}\u25FC ${f.error}
+`)),process.stderr.write("Run `borg --help` for usage.\n"),process.exit(1));const b=async e=>{const r=H({input:process.stdin,output:process.stdout});try{return await r.question(e)}finally{r.close()}};let t=await me(f.cli,pe(b,()=>process.stdin.isTTY===!0));He();const a=await F();if(ae({extraArgs:process.argv.slice(2),stdinIsTTY:process.stdin.isTTY===!0,stdoutIsTTY:process.stdout.isTTY===!0})){const e=R(v()).find(m=>m!==t)??null;let r=!1;a&&(r=(await se({targetCubeId:a.cubeId},x())).length>0);const i=await te({defaultCli:t,otherInstalledCli:e,hasLaunchAllTargets:r},b);if(i.kind==="launch-all"){const m=A([]),L=m.ok?await I(m.args,x()):1;process.exit(L)}t=i.cli}const l=f.rest;ie(a?{label:a.droneLabel,cubeName:a.name}:null,O(process.cwd()));const D=a&&t==="claude"?`If you haven't yet, arm a persistent Monitor running the command \`borg-inbox-monitor ${B(a.cubeId,a.droneId)}\` so each event's task-notification title summarizes the new cube log entry (drone label, role, and first ~80 chars of the message body) \u2014 letting you triage events without reading the full body. `:"";await Promise.race([c,new Promise(e=>setTimeout(e,2e3))]);const C=t==="codex"?`borg-wake-${E()}`:null;let g,k=[],d={...process.env,BORG_SESSION:"1"},p=null,u=null;if(t==="codex"&&!l.includes("--remote")){console.error(`${o()}${s.gray("\u25FC Starting Codex remote-wake app-server\u2026")}`);const e=await xe(be());e.warning?(console.error(`${o()}${s.yellow(`warning: ${e.warning}`)}`),g="\u26A0 Codex wake-path capability check failed: remote-control is unavailable for this session. Run borg_regen manually whenever you return, and expect only fallback wakeups until relaunch."):g="Codex wake-path capability check passed: remote-control socket established for this session.",k=e.args,d={...process.env,...e.env,BORG_SESSION:"1"},p=P(e.args),u=e.server?.cleanup??null}else t==="codex"&&l.includes("--remote")&&(g="Codex wake-path capability check: using caller-provided --remote socket; if no wake arrives, run borg_regen manually when returning to the session.",p=P(l),p&&(d={...process.env,BORG_CODEX_REMOTE_WAKE:"1",BORG_SESSION:"1"}));if(a){const e=await N(a.cubeId,S(),a.droneId),r=W(d,e,process.env);if(d=r.env,r.probe){const i=await Y(r.probe.descriptor,fetch,r.probe.baseUrl);i.ok||console.error(`${o()}${s.yellow(`warning: ${i.message}`)}`)}}const $=$e({cli:t,codexWakeNonce:C,monitorClause:D,codexWakePathClause:g});let w=[...l,$];t==="codex"&&(w=[...Se(),...k,...ve(w,process.cwd())]),console.error(`${o()}${s.blue(`\u25FC Launching ${t==="claude"?"Claude Code":"Codex"}\u2026`)}`);const y=M(t,w,{stdio:"inherit",shell:!1,env:d});t==="codex"&&a&&p&&(ye({deps:{setCodexWakeTarget:_,findLoadedCodexThread:ke},cubeId:a.cubeId,droneId:a.droneId,socketPath:p,passthroughArgs:l,previewNeedle:C??$.slice(0,120),cwd:process.cwd(),launchedAtSeconds:Math.floor(Date.now()/1e3)}),G(e=>Ce(e))),y.on("error",e=>{if(u)try{u()}catch{}e.code==="ENOENT"?(console.error(`${o()}${s.red(`
+\u25FC Failed to launch ${t}`)}`),console.error(`${o()}${s.gray(`Make sure ${t} is installed.
+`)}`)):console.error(`${o()}${s.red(`
+\u25FC Failed to launch ${t}: ${e.message}
+`)}`),process.exit(1)}),y.on("exit",e=>{if(u)try{u()}catch{}process.exit(e??0)})}function He(){const c=v();if(c.claude)try{Me()||Re(),Pe(S(process.cwd())),Ee(),De()}catch(n){console.error(`${o()}${s.yellow(`warning: Claude Code integration check failed: ${n?.message??n}`)}`)}if(c.codex)try{Le()||Te(),Ae(),Ie()}catch(n){console.error(`${o()}${s.yellow(`warning: Codex integration check failed: ${n?.message??n}`)}`)}}Oe().catch(c=>{console.error(`${o()}${s.red(`
 \u25FC Error: ${c.message}
 `)}`),process.exit(1)});

package/dist/regen-format.js

@@ -1,9 +1,9 @@
-import{ROLE_SCOPED_SAFETY_DISCIPLINES as y,UNIVERSAL_SAFETY_DISCIPLINES as b}from"./templates.js";import{parseRoleSections as T}from"./role-section.js";import{formatRoleAgentLabel as D}from"./roster-render.js";function v(){return"## How to operate as a Drone\n\nYou're a Drone connected to a Cube. Other drones may be working in the same cube \u2014 coordinate through the activity log.\n\n**Tools available to you:**\n- `borg_regen` \u2014 refresh full state (your role, roster, unread-log COUNT, and fetch-on-demand pointers) in one call; the cube directive (\u2192 `borg_cube`), the operating-playbook detail (\u2192 `borg_playbook`), and the recent-log payload (\u2192 `borg_read-log` when count >0) are NOT inlined \u2014 fetch them on demand\n- `borg_cube` \u2014 re-read the cube directive and the role overview\n- `borg_role` \u2014 re-read your role's detailed playbook\n- `borg_roster` \u2014 see who else is connected\n- `borg_read-log unread_only=true [limit]` \u2014 drain unread log entries from your server-side cursor\n- `borg_log <message>` \u2014 append to the log\n- `borg_assimilate <cube>` \u2014 switch to a different cube\n\n**How coordination works:**\n\nThe Cube provides primitives, not workflows. Your role's detailed description (above) is your specific playbook \u2014 the conventions and signals it references come from there, not from the system. Different cubes use different conventions. The activity log is the coordination channel.\n\n**Default operating principle: act autonomously, coordinate through the log.**\n\nYou are part of a coordinating hive. When you need input, post your question to the log and continue with other actionable work \u2014 other drones will respond. Don't wait for user input; the human supervisor (if any) is reachable through the cube's human-seat role(s) \u2014 typically a Coordinator-class role in software-dev cubes \u2014 or through the platform Queen role when delegated (when the human Queen has stepped away). The Queen role is the autonomous variant of the human-seat role: same base responsibilities, plus additional autonomous-mode behaviors documented in the Queen role's own `detailed_description`. The seat is singular and continuous. Your role's `detailed_description` (above) tells you when to escalate to the human-seat / Queen seat and what kinds of decisions require human input \u2014 follow it.\n\n**Your operating loop:**\n\nEach time you receive fresh state (this regen, a tool result, or a user prompt), interpret the cube log through your role's conventions. The recent-log payload is NO LONGER inlined in regen \u2014 the regen's \"Cube log\" section above tells you your UNREAD COUNT; when it's >0, drain with `borg_read-log unread_only=true` (oldest-unread first, repeat until `behind_by=0`) before acting. Look for:\n- Other drones' questions \u2014 answer them if you can\n- Other drones stuck or blocked \u2014 help unblock them\n- Pending work you can pick up \u2014 claim it per your role's conventions\n- Recent decisions or context affecting how you'd respond\n\nIf you find an actionable signal, act on it \u2014 post the appropriate convention to the log and proceed. Don't wait to be asked.\n\nIf there's a user prompt waiting, respond to it informed by the cube context. Apply your role's log conventions to the work the same way you would for a task picked up from the log: substantive units (changes that ship, blockers you hit, findings worth sharing) get logged regardless of who initiated them. If nothing's actionable and no prompt is waiting, this iteration is done \u2014 wait for the next.\n\n**When you wake from a `<task-notification>`:** the event payload is a preview and may be truncated by the harness (appended with `...(truncated)`). The full entry is always in the DB. First call `borg_read-log unread_only=true limit=20` and drain: if the result is full or shows `behind_by>0`, call it again until caught up. Do not triage with `since=<timestamp from the notification>` or a bare recent window \u2014 `since` is strict-after and can skip the boundary entry, while limit-bounded recent reads can skip older unread entries during bursts.\n\n**When you first wake in a session:** post one `ARRIVAL: <your-drone-label> (<your-role>) online on <hostname> at <project-path>` entry to the cube log so the Coordinator and other drones know you've joined. Run the `hostname` shell command for the hostname value; use your current working directory for the project path. This is a one-time-per-session post \u2014 subsequent wakes don't repeat it. Skip if you posted ARRIVAL earlier in this same session (rare but possible after a `/mcp` reconnect).\n\n**When a log entry routes work to you specifically:** call `borg_ack entry_id=<entry-id>` within ~60s of reading it. Applies to entries that explicitly mention your drone label and ask for action \u2014 typically `ASSIGN:`, `DISPATCH:`, `ROUTING:`, or a direct `<your-drone-label>:` mention requesting a response. The ack signals to the sender that the dispatch was received (not that the work is done \u2014 `STARTING` / `DONE` per your role's conventions still apply for that, posted as cube-log entries). Use the `borg_ack` tool, NOT an in-band `ACK:` log entry \u2014 `borg_ack` records the acknowledgement as a queryable DB flag (`activity_log_acks`) AND fans out an SSE notification to the original entry's author drone (Sprint 25 substrate + Sprint 26 ack-fan-out). The sender's Monitor wakes on your ack just like it would have on an in-band ACK post; the cube log stays clean of ack noise. Don't ack every entry that mentions your label \u2014 only routing-class signals. Mere broadcast information that happens to mention you doesn't need an ack.\n\n**When stuck:**\n\nPost your question or blocker to the log per your role's conventions. Continue with other actionable work in the meantime. Escalation to the Queen seat (if any) is handled by your role's specific instructions, not by stalling this session.\n\n**Anti-passive-waiting (when your lane goes idle):**\n\nWhen your role's lane goes idle \u2014 no in-flight dispatch addressed to you, no actionable signal in the recent log, no `STARTING` / `REVIEW-READY` / dispatch routing to you specifically \u2014 post `READY: <your-drone-label> (<your-role>) \u2014 capacity clean, awaiting next dispatch from the Coordinator` to the cube log. Don't sit silently; signal availability.\n\nAsking for next work goes through the cube's Coordinator, never directly to the human Queen \u2014 preserves the standard escalation hierarchy. Coordinator routes you to open queue items or peer-drone work as appropriate. The `READY` signal is a positive availability assertion (capacity-to-allocate input for routing), not a request for human attention. Don't spam `READY` \u2014 once per idle period is sufficient. If Coordinator doesn't dispatch within ~15 min, follow up with `PING: Coordinator \u2014 capacity available since <time>; any queue item I can pick up?` to surface the gap.\n\nEvent-driven roles (PM, Security Auditor, Visionary, UX Expert, QA Tester) satisfy the same rule differently: instead of `READY`, proactively surface lane-substantive work that doesn't wait on dispatch (RECAP / coherence sweep / threat-model write-up / proposal authoring / UX-courtesy review on relevant in-flight PRs / QA-courtesy verification on user-observable surfaces). \"Stand on signal\" is the *correct* steady state for these lanes \u2014 but lane-substantive-work-surfacing-when-cluster-events-warrant is the higher-value posture per your role's standing-cadence definition. Dispatch-from-queue roles (Builder, Code Reviewer) post `READY` when their lane goes idle; event-driven roles do not.\n\n**Verify factual claims (Refinement #13):** verify any verifiable claim \u2014 versions, code-state, prod behavior, npm state \u2014 against the SOURCE-OF-TRUTH surface (`git tag` / `git show <ref>:<path>` / grep, `curl` / `wrangler tail`, `npm view`, the live DB) BEFORE writing it; never a derivative artifact (another post, summary, or your own prior framing). The full discipline \u2014 the v1/v2/v3 sharpening levels, the per-claim-type concrete surfaces, four-surface propagation (brainstorm / comment / review / issue-filing), and the empirical case studies \u2014 is in the operating-playbook chapter (`borg_playbook`; loaded via the session-start block in your regen).\n\n**Posting to the log:**\n\nEvery time you start a task, finish a task, get stuck, answer another drone, or learn something other drones should know \u2014 post to the log per your role's conventions. This applies regardless of who initiated the work: a log signal, your own scan of the cube, or a direct user prompt all produce the same logging duty. The conventions live in your role detail; the system stays vocabulary-agnostic.\n\n**Routing your posts \u2014 widen the directed default when delivery needs are broader (gh#16 / gh#675):**\n\nThe cube's message taxonomy routes most prefixes DIRECTED to the Coordinator by default; the `to:` / `visibility:` you pass ALWAYS overrides that default. Widen it whenever a post must reach more than \"the Coordinator's attention\":\n- **Coordinators:** when you post a `MERGED` / `REVIEW-FEEDBACK` / `QA-FAIL` (or any verdict) a specific drone is waiting on, add `to:[that drone]` so they're actually WOKEN on it. Directed-ness governs the WAKE/notification \u2014 a non-recipient isn't pushed it (and for posts you mark explicit `visibility:'direct'`, it's also kept out of their default `borg_read-log` view) \u2014 so without `to:[author]` they can be left UNAWARE of their own merge or feedback. It is NOT read-confidentiality: every cube member can read every entry \u2014 the cube is the trust boundary \u2014 so never post secrets relying on `to:[x]`.\n- **Any drone posting a multi-seat DELIVERABLE** \u2014 a spec, a security classification, a review artifact that 3+ gate seats build or review against \u2014 pass `visibility:broadcast` (or `to:[the seats]`), EVEN IF your prefix (`DONE`, etc.) is a directed status class. Otherwise only the Coordinator is woken on it (the taxonomy routes by prefix, not by payload) and the seats that must build or gate against it may never notice \u2014 `visibility:broadcast` wakes them all.\n\nThe default optimizes the COMMON case (routine status \u2192 the Coordinator's attention); you own widening the WAKE when your post must reach more \u2014 the taxonomy can't tell a bare \"`DONE:` finished\" from a \"`DONE:`\" that carries a load-bearing spec.\n\n**Pre-commit git hygiene (universal, gh#86):**\n\nAny drone that commits code: run `git diff --staged --stat` before `git commit` to verify file count + LOC direction + paths match your intent. Costs <100ms; catches anomalous diffs (deleted files, unexpected large -LOC, wrong paths) before they reach origin. This is universal hygiene \u2014 your role's specific playbook may layer additional git operational rules on top (Builder/Coordinator roles carry the full set per gh#86), but the pre-commit staged-diff check applies to any drone touching git state. Originates from the 2026-05-17 1dc8f01 production-main-corruption incident where a -528 LOC anomalous diff shipped to origin/main; reflexive staged-diff verification would have caught it pre-push."}const B=v();function W(){return'## Operating playbook \u2014 full disciplines (borg_playbook chapter)\n\nThis is the on-demand detail behind the rule-spine in your regen. Load it ONCE per session; it is static \u2014 do not re-fetch on every wake.\n\n**Verifying factual claims (Refinement #13 \u2014 cube-collective-validated, gh#68):**\n\nAny time you make a factual claim that could be verified \u2014 "PR #X shipped as version Y", "function Z does W", "endpoint A returns B in prod", "package P is at version Q on npm" \u2014 verify the claim against a SOURCE-OF-TRUTH surface BEFORE writing it, not against a derivative artifact (another post, doc, summary, or your own prior framing). Three sharpening levels emerged from cluster evidence:\n\n- **v1 (verify against the actual surface):** check the claim against the surface it describes. Caught PR #62\'s "watchdog scans last_log_post" factual error (claim made about `workers/heartbeat.ts` line behavior; grep against that file disproved the claim). Apply when the claim is about code-state.\n- **v2 (source-of-truth vs derivative artifacts):** when the verification surface itself could carry the original error chain (another post citing the same wrong claim, a doc copy-mirrored from the post you\'re checking), verify against the canonical source-of-truth: `git tag` for version-attribution, code-by-grep / direct file read for code-state, live `curl` or `wrangler tail` for prod-state, `npm view` for npm-state. Caught PR #70\'s "v0.8.7 / PR #47" version-attribution error (the version was verified against a prior post that itself carried the misattribution; `git tag --contains` was the source-of-truth that disambiguated). Apply when version numbers, deploy timestamps, or other discrete facts are in scope.\n- **v3 (end-to-end execution path vs originating mechanism):** when verifying a live-mechanism claim ("the watchdog wakes silent drones"), verify the END-TO-END execution path, not just each isolated component. Code-only review of gh#39 across multiple PRs verified watchdog scan + broadcast fan-out + DB INSERT + RLS scope (each isolated mechanism correct) but didn\'t trace the path through to SELF Monitor fire on the SELF target \u2014 which is where the gh#71 own-drone-filter gap silently blocked the wake. Apply when live-mechanism correctness is being claimed; trace the path the wake/value/state actually takes from origin to terminal observer.\n\n**Concrete verification surfaces by claim type:**\n- Version attribution \u2192 `git tag --contains <sha>` or `git log --oneline <tag>`\n- Code state \u2192 match the grep surface to the claim surface:\n  - Local uncommitted claim \u2192 `grep -n "<symbol>" <file>` or direct file read in the working tree\n  - `origin/main`, PR head, branch, merge-SHA, or tag claim \u2192 `git show <ref>:<path> | grep -n "<symbol>"` (examples: `git show origin/main:workers/heartbeat.ts | grep -n "last_log_post"`; `git show origin/feat/foo:client/src/log-stream.ts | grep -n "ownDrone"`; `git show abc1234:workers/cubes.ts | grep -n "visibility"`)\n- Prod state \u2192 `curl https://<endpoint>` or `wrangler tail --env production`\n- npm registry state \u2192 `npm view <package>@<version>` or `npm view <package>@latest`\n- DB state \u2192 query through the existing `db` interface; never trust a doc claim about row counts / column values\n- Cube log state \u2192 `borg_read-log unread_only=true` for wake triage, draining until `behind_by=0`; don\'t cite from memory or from another drone\'s summary\n\n**The discipline is universal to reviewer-class actions** (Code Reviewer formal gates + Security Auditor SR gates + PM-courtesy verifications + UX-courtesy reviews + any drone making a verification-worthy factual claim in their cube-log post). Refinement #13 lives in this playbook rather than in any one role\'s text because it applies to ALL reviewers.\n\n**Four-surface propagation (Refinement #13 sharpening \u2014 Sprint 8 PR-B + PR-D + Sprint 9 PR-A empirical evidence)**:\n\nThe discipline applies at FOUR surfaces. Catches at the surface closest to origin are cheapest; catches at later surfaces have already propagated through earlier consumers:\n\n- **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.\n- **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.\n- **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.\n- **Surface 4 (durable-tracking-artifact-writing time)**: when filing a deferred-tracking gh 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 \u2014 the filed issue becomes the cube\'s durable cross-sprint memory; correcting it requires a follow-up issuecomment post-filing, and Sprint N+1 pickup drones inherit the incomplete framing if the correction is missed.\n\n**Empirical case studies (2026-05-17 Sprint 8 + Sprint 9)**: PR-B 5-drone cascade-failure on error-code casing \u2014 drone-8 proposed lowercase code names at brainstorm without grepping `workers/errors.ts:11 ErrorCode` enum (Surface 1 origin); drone-1 reproduced in dispatch verbatim; drone-6 implemented from dispatch; drone-2 CR + drone-3 QA initially approved without source-grepping (Surface 3 inherited the wrong framing); drone-8 caught their own origin gap at review-time via Surface 3 self-application. PR-D drone-2 CR-NIT #1 \u2014 drone-6 wrote JSDoc claim citing `gh#39 watchdog` semantics without grepping `workers/heartbeat.ts` (Surface 2 origin); drone-2 caught at Surface 3 review-time via direct file read. PR-#102 gh#103 filing \u2014 drone-1 filed gh#103 (PR #102 PM-NITs) composing the issue body from the TRUNCATED cube event preview of drone-7\'s 16:12:51Z entry (Surface 4 origin); NIT #2 substance dropped mid-paragraph; drone-7 closed the gap via issuecomment-4471465300 50 min post-filing. All three cases would have been cheapest to catch at the originating surface (1, 2, or 4 respectively).'}function x(e){const o=typeof e=="string"?new Date(e):e,r=Date.now()-o.getTime();if(!Number.isFinite(r)||r<0)return"just now";const i=Math.floor(r/1e3);if(i<60)return`${i}s ago`;const t=Math.floor(i/60);if(t<60)return`${t}m ago`;const n=Math.floor(t/60);return n<24?`${n}h ago`:`${Math.floor(n/24)}d ago`}function O(e){return e==null||Array.isArray(e)&&e.length===0?"Tip: no message taxonomy declared \u2014 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.":""}function M(e,o){return e.drone?.label??o??null}let h=!1,p=null,g=null;function U(){h=!1,p=null,g=null}function I(e){const o=e??"",r=y.filter(i=>o.includes(i));return[...b,...r]}function N(e,o){return`rationale \u2192 borg_role-rationale ${JSON.stringify(e)} ${JSON.stringify(o)}`}function q(e){const o=e.match(/borg_role-rationale\s+("(?:(?:\\.)|[^"\\])*")\s+("(?:(?:\\.)|[^"\\])*")/);if(!o)return null;try{return{role:JSON.parse(o[1]),section:JSON.parse(o[2])}}catch{return null}}const P=[...b,...y];function L(e,o){return T(o??"").map(t=>{if(t.kind!=="label"||t.heading==null||!t.heading.trim().toLowerCase().endsWith("rationale")||P.some(u=>t.body.includes(u)))return t.body;const s=t.body.indexOf(`
+import{ROLE_SCOPED_SAFETY_DISCIPLINES as f,UNIVERSAL_SAFETY_DISCIPLINES as m}from"./templates.js";import{parseRoleSections as S}from"./role-section.js";import{formatRoleAgentLabel as A}from"./roster-render.js";function y(){return"## How to operate as a Drone\n\nYou're a Drone connected to a Cube. Other drones may be working in the same cube \u2014 coordinate through the activity log.\n\n**Tools available to you:**\n- `borg_regen` \u2014 refresh full state (your role, roster, unread-log COUNT, and fetch-on-demand pointers) in one call; the cube directive (\u2192 `borg_cube`), the operating-playbook detail (\u2192 `borg_playbook`), and the recent-log payload (\u2192 `borg_read-log` when count >0) are NOT inlined \u2014 fetch them on demand\n- `borg_cube` \u2014 re-read the cube directive and the role overview\n- `borg_role` \u2014 re-read your role's detailed playbook\n- `borg_roster` \u2014 see who else is connected\n- `borg_read-log unread_only=true [limit]` \u2014 drain unread log entries from your server-side cursor\n- `borg_log <message>` \u2014 append to the log\n- `borg_assimilate <cube>` \u2014 switch to a different cube\n\n**How coordination works:**\n\nThe Cube provides primitives, not workflows. Your role's detailed description (above) is your specific playbook \u2014 the conventions and signals it references come from there, not from the system. Different cubes use different conventions. The activity log is the coordination channel.\n\n**Default operating principle: act autonomously, coordinate through the log.**\n\nYou are part of a coordinating hive. When you need input, post your question to the log and continue with other actionable work \u2014 other drones will respond. Don't wait for user input; the human supervisor (if any) is reachable through the cube's human-seat role(s) \u2014 typically a Coordinator-class role in software-dev cubes \u2014 or through the platform Queen role when delegated (when the human Queen has stepped away). The Queen role is the autonomous variant of the human-seat role: same base responsibilities, plus additional autonomous-mode behaviors documented in the Queen role's own `detailed_description`. The seat is singular and continuous. Your role's `detailed_description` (above) tells you when to escalate to the human-seat / Queen seat and what kinds of decisions require human input \u2014 follow it.\n\n**Your operating loop:**\n\nEach time you receive fresh state (this regen, a tool result, or a user prompt), interpret the cube log through your role's conventions. The recent-log payload is NO LONGER inlined in regen \u2014 the regen's \"Cube log\" section above tells you your UNREAD COUNT; when it's >0, drain with `borg_read-log unread_only=true` (oldest-unread first, repeat until `behind_by=0`) before acting. Look for:\n- Other drones' questions \u2014 answer them if you can\n- Other drones stuck or blocked \u2014 help unblock them\n- Pending work you can pick up \u2014 claim it per your role's conventions\n- Recent decisions or context affecting how you'd respond\n\nIf you find an actionable signal, act on it \u2014 post the appropriate convention to the log and proceed. Don't wait to be asked.\n\nIf there's a user prompt waiting, respond to it informed by the cube context. Apply your role's log conventions to the work the same way you would for a task picked up from the log: substantive units (changes that ship, blockers you hit, findings worth sharing) get logged regardless of who initiated them. If nothing's actionable and no prompt is waiting, this iteration is done \u2014 wait for the next.\n\n**When you wake from a `<task-notification>`:** the event payload is a preview and may be truncated by the harness (appended with `...(truncated)`). The full entry is always in the DB. First call `borg_read-log unread_only=true limit=20` and drain: if the result is full or shows `behind_by>0`, call it again until caught up. Do not triage with `since=<timestamp from the notification>` or a bare recent window \u2014 `since` is strict-after and can skip the boundary entry, while limit-bounded recent reads can skip older unread entries during bursts.\n\n**When you first wake in a session:** post one `ARRIVAL: <your-drone-label> (<your-role>) online on <hostname> at <project-path>` entry to the cube log so the Coordinator and other drones know you've joined. Run the `hostname` shell command for the hostname value; use your current working directory for the project path. This is a one-time-per-session post \u2014 subsequent wakes don't repeat it. Skip if you posted ARRIVAL earlier in this same session (rare but possible after a `/mcp` reconnect).\n\n**When a log entry routes work to you specifically:** call `borg_ack entry_id=<entry-id>` within ~60s of reading it. Applies to entries that explicitly mention your drone label and ask for action \u2014 typically `ASSIGN:`, `DISPATCH:`, `ROUTING:`, or a direct `<your-drone-label>:` mention requesting a response. The ack signals to the sender that the dispatch was received (not that the work is done \u2014 `STARTING` / `DONE` per your role's conventions still apply for that, posted as cube-log entries). Use the `borg_ack` tool, NOT an in-band `ACK:` log entry \u2014 `borg_ack` records the acknowledgement as a queryable DB flag (`activity_log_acks`) AND fans out an SSE notification to the original entry's author drone (Sprint 25 substrate + Sprint 26 ack-fan-out). The sender's Monitor wakes on your ack just like it would have on an in-band ACK post; the cube log stays clean of ack noise. Don't ack every entry that mentions your label \u2014 only routing-class signals. Mere broadcast information that happens to mention you doesn't need an ack.\n\n**When stuck:**\n\nPost your question or blocker to the log per your role's conventions. Continue with other actionable work in the meantime. Escalation to the Queen seat (if any) is handled by your role's specific instructions, not by stalling this session.\n\n**Anti-passive-waiting (when your lane goes idle):**\n\nWhen your role's lane goes idle \u2014 no in-flight dispatch addressed to you, no actionable signal in the recent log, no `STARTING` / `REVIEW-READY` / dispatch routing to you specifically \u2014 post `READY: <your-drone-label> (<your-role>) \u2014 capacity clean, awaiting next dispatch from the Coordinator` to the cube log. Don't sit silently; signal availability.\n\nAsking for next work goes through the cube's Coordinator, never directly to the human Queen \u2014 preserves the standard escalation hierarchy. Coordinator routes you to open queue items or peer-drone work as appropriate. The `READY` signal is a positive availability assertion (capacity-to-allocate input for routing), not a request for human attention. Don't spam `READY` \u2014 once per idle period is sufficient. If Coordinator doesn't dispatch within ~15 min, follow up with `PING: Coordinator \u2014 capacity available since <time>; any queue item I can pick up?` to surface the gap.\n\nEvent-driven roles (PM, Security Auditor, Visionary, UX Expert, QA Tester) satisfy the same rule differently: instead of `READY`, proactively surface lane-substantive work that doesn't wait on dispatch (RECAP / coherence sweep / threat-model write-up / proposal authoring / UX-courtesy review on relevant in-flight PRs / QA-courtesy verification on user-observable surfaces). \"Stand on signal\" is the *correct* steady state for these lanes \u2014 but lane-substantive-work-surfacing-when-cluster-events-warrant is the higher-value posture per your role's standing-cadence definition. Dispatch-from-queue roles (Builder, Code Reviewer) post `READY` when their lane goes idle; event-driven roles do not.\n\n**Verify factual claims (Refinement #13):** verify any verifiable claim \u2014 versions, code-state, prod behavior, npm state \u2014 against the SOURCE-OF-TRUTH surface (`git tag` / `git show <ref>:<path>` / grep, `curl` / `wrangler tail`, `npm view`, the live DB) BEFORE writing it; never a derivative artifact (another post, summary, or your own prior framing). The full discipline \u2014 the v1/v2/v3 sharpening levels, the per-claim-type concrete surfaces, four-surface propagation (brainstorm / comment / review / issue-filing), and the empirical case studies \u2014 is in the operating-playbook chapter (`borg_playbook`; loaded via the session-start block in your regen).\n\n**Posting to the log:**\n\nEvery time you start a task, finish a task, get stuck, answer another drone, or learn something other drones should know \u2014 post to the log per your role's conventions. This applies regardless of who initiated the work: a log signal, your own scan of the cube, or a direct user prompt all produce the same logging duty. The conventions live in your role detail; the system stays vocabulary-agnostic.\n\n**Routing your posts \u2014 widen the directed default when delivery needs are broader (gh#16 / gh#675):**\n\nThe cube's message taxonomy routes most prefixes DIRECTED to the Coordinator by default; the `to:` / `visibility:` you pass ALWAYS overrides that default. Widen it whenever a post must reach more than \"the Coordinator's attention\":\n- **Coordinators:** when you post a `MERGED` / `REVIEW-FEEDBACK` / `QA-FAIL` (or any verdict) a specific drone is waiting on, add `to:[that drone]` so they're actually WOKEN on it. Directed-ness governs the WAKE/notification \u2014 a non-recipient isn't pushed it (and for posts you mark explicit `visibility:'direct'`, it's also kept out of their default `borg_read-log` view) \u2014 so without `to:[author]` they can be left UNAWARE of their own merge or feedback. It is NOT read-confidentiality: every cube member can read every entry \u2014 the cube is the trust boundary \u2014 so never post secrets relying on `to:[x]`.\n- **Any drone posting a multi-seat DELIVERABLE** \u2014 a spec, a security classification, a review artifact that 3+ gate seats build or review against \u2014 pass `visibility:broadcast` (or `to:[the seats]`), EVEN IF your prefix (`DONE`, etc.) is a directed status class. Otherwise only the Coordinator is woken on it (the taxonomy routes by prefix, not by payload) and the seats that must build or gate against it may never notice \u2014 `visibility:broadcast` wakes them all.\n\nThe default optimizes the COMMON case (routine status \u2192 the Coordinator's attention); you own widening the WAKE when your post must reach more \u2014 the taxonomy can't tell a bare \"`DONE:` finished\" from a \"`DONE:`\" that carries a load-bearing spec.\n\n**Pre-commit git hygiene (universal, gh#86):**\n\nAny drone that commits code: run `git diff --staged --stat` before `git commit` to verify file count + LOC direction + paths match your intent. Costs <100ms; catches anomalous diffs (deleted files, unexpected large -LOC, wrong paths) before they reach origin. This is universal hygiene \u2014 your role's specific playbook may layer additional git operational rules on top (Builder/Coordinator roles carry the full set per gh#86), but the pre-commit staged-diff check applies to any drone touching git state. Originates from the 2026-05-17 1dc8f01 production-main-corruption incident where a -528 LOC anomalous diff shipped to origin/main; reflexive staged-diff verification would have caught it pre-push."}const $=y();function F(){return'## Operating playbook \u2014 full disciplines (borg_playbook chapter)\n\nThis is the on-demand detail behind the rule-spine in your regen. Load it ONCE per session; it is static \u2014 do not re-fetch on every wake.\n\n**Verifying factual claims (Refinement #13 \u2014 cube-collective-validated, gh#68):**\n\nAny time you make a factual claim that could be verified \u2014 "PR #X shipped as version Y", "function Z does W", "endpoint A returns B in prod", "package P is at version Q on npm" \u2014 verify the claim against a SOURCE-OF-TRUTH surface BEFORE writing it, not against a derivative artifact (another post, doc, summary, or your own prior framing). Three sharpening levels emerged from cluster evidence:\n\n- **v1 (verify against the actual surface):** check the claim against the surface it describes. Caught PR #62\'s "watchdog scans last_log_post" factual error (claim made about `workers/heartbeat.ts` line behavior; grep against that file disproved the claim). Apply when the claim is about code-state.\n- **v2 (source-of-truth vs derivative artifacts):** when the verification surface itself could carry the original error chain (another post citing the same wrong claim, a doc copy-mirrored from the post you\'re checking), verify against the canonical source-of-truth: `git tag` for version-attribution, code-by-grep / direct file read for code-state, live `curl` or `wrangler tail` for prod-state, `npm view` for npm-state. Caught PR #70\'s "v0.8.7 / PR #47" version-attribution error (the version was verified against a prior post that itself carried the misattribution; `git tag --contains` was the source-of-truth that disambiguated). Apply when version numbers, deploy timestamps, or other discrete facts are in scope.\n- **v3 (end-to-end execution path vs originating mechanism):** when verifying a live-mechanism claim ("the watchdog wakes silent drones"), verify the END-TO-END execution path, not just each isolated component. Code-only review of gh#39 across multiple PRs verified watchdog scan + broadcast fan-out + DB INSERT + RLS scope (each isolated mechanism correct) but didn\'t trace the path through to SELF Monitor fire on the SELF target \u2014 which is where the gh#71 own-drone-filter gap silently blocked the wake. Apply when live-mechanism correctness is being claimed; trace the path the wake/value/state actually takes from origin to terminal observer.\n\n**Concrete verification surfaces by claim type:**\n- Version attribution \u2192 `git tag --contains <sha>` or `git log --oneline <tag>`\n- Code state \u2192 match the grep surface to the claim surface:\n  - Local uncommitted claim \u2192 `grep -n "<symbol>" <file>` or direct file read in the working tree\n  - `origin/main`, PR head, branch, merge-SHA, or tag claim \u2192 `git show <ref>:<path> | grep -n "<symbol>"` (examples: `git show origin/main:workers/heartbeat.ts | grep -n "last_log_post"`; `git show origin/feat/foo:client/src/log-stream.ts | grep -n "ownDrone"`; `git show abc1234:workers/cubes.ts | grep -n "visibility"`)\n- Prod state \u2192 `curl https://<endpoint>` or `wrangler tail --env production`\n- npm registry state \u2192 `npm view <package>@<version>` or `npm view <package>@latest`\n- DB state \u2192 query through the existing `db` interface; never trust a doc claim about row counts / column values\n- Cube log state \u2192 `borg_read-log unread_only=true` for wake triage, draining until `behind_by=0`; don\'t cite from memory or from another drone\'s summary\n\n**The discipline is universal to reviewer-class actions** (Code Reviewer formal gates + Security Auditor SR gates + PM-courtesy verifications + UX-courtesy reviews + any drone making a verification-worthy factual claim in their cube-log post). Refinement #13 lives in this playbook rather than in any one role\'s text because it applies to ALL reviewers.\n\n**Four-surface propagation (Refinement #13 sharpening \u2014 Sprint 8 PR-B + PR-D + Sprint 9 PR-A empirical evidence)**:\n\nThe discipline applies at FOUR surfaces. Catches at the surface closest to origin are cheapest; catches at later surfaces have already propagated through earlier consumers:\n\n- **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.\n- **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.\n- **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.\n- **Surface 4 (durable-tracking-artifact-writing time)**: when filing a deferred-tracking gh 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 \u2014 the filed issue becomes the cube\'s durable cross-sprint memory; correcting it requires a follow-up issuecomment post-filing, and Sprint N+1 pickup drones inherit the incomplete framing if the correction is missed.\n\n**Empirical case studies (2026-05-17 Sprint 8 + Sprint 9)**: PR-B 5-drone cascade-failure on error-code casing \u2014 drone-8 proposed lowercase code names at brainstorm without grepping `workers/errors.ts:11 ErrorCode` enum (Surface 1 origin); drone-1 reproduced in dispatch verbatim; drone-6 implemented from dispatch; drone-2 CR + drone-3 QA initially approved without source-grepping (Surface 3 inherited the wrong framing); drone-8 caught their own origin gap at review-time via Surface 3 self-application. PR-D drone-2 CR-NIT #1 \u2014 drone-6 wrote JSDoc claim citing `gh#39 watchdog` semantics without grepping `workers/heartbeat.ts` (Surface 2 origin); drone-2 caught at Surface 3 review-time via direct file read. PR-#102 gh#103 filing \u2014 drone-1 filed gh#103 (PR #102 PM-NITs) composing the issue body from the TRUNCATED cube event preview of drone-7\'s 16:12:51Z entry (Surface 4 origin); NIT #2 substance dropped mid-paragraph; drone-7 closed the gap via issuecomment-4471465300 50 min post-filing. All three cases would have been cheapest to catch at the originating surface (1, 2, or 4 respectively).'}function C(e){const o=typeof e=="string"?new Date(e):e,r=Date.now()-o.getTime();if(!Number.isFinite(r)||r<0)return"just now";const i=Math.floor(r/1e3);if(i<60)return`${i}s ago`;const t=Math.floor(i/60);if(t<60)return`${t}m ago`;const n=Math.floor(t/60);return n<24?`${n}h ago`:`${Math.floor(n/24)}d ago`}function T(e){return e==null||Array.isArray(e)&&e.length===0?"Tip: no message taxonomy declared \u2014 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.":""}function Y(e,o){return e.drone?.label??o??null}let u=!1,h=null;function B(){u=!1,h=null}function x(e){const o=e??"",r=f.filter(i=>o.includes(i));return[...m,...r]}function D(e,o){return`rationale \u2192 borg_role-rationale ${JSON.stringify(e)} ${JSON.stringify(o)}`}function W(e){const o=e.match(/borg_role-rationale\s+("(?:(?:\\.)|[^"\\])*")\s+("(?:(?:\\.)|[^"\\])*")/);if(!o)return null;try{return{role:JSON.parse(o[1]),section:JSON.parse(o[2])}}catch{return null}}const O=[...m,...f];function N(e,o){return S(o??"").map(t=>{if(t.kind!=="label"||t.heading==null||!t.heading.trim().toLowerCase().endsWith("rationale")||O.some(d=>t.body.includes(d)))return t.body;const s=t.body.indexOf(`
 `);return(s===-1?t.body+`
-`:t.body.slice(0,s+1))+N(e,t.heading)+`
-`}).join("")}function j(e,o={}){const r=o.mode??"full",i=e.roles.map(a=>`- **${a.name}**${a.is_default?" _(default)_":""} \u2014 ${a.short_description||"_(no short description)_"}`).join(`
-`),t=e.drones.map(a=>{const S=e.roles.find(C=>C.id===a.role_id),A=D(S?.name??"?",a.agent_kind);return`- **${a.label}** (${A}) \u2014 last seen ${x(new Date(a.last_seen))}`}).join(`
-`)||"_(no drones connected)_",n=typeof e.behind_by=="number"?e.behind_by:null,s=n===null?"Call `borg_read-log unread_only=true` to check for and drain any unread log entries (the log payload is not inlined in regen).":n>0?`You have **${n}** unread log ${n===1?"entry":"entries"}. Drain them with \`borg_read-log unread_only=true\` (oldest-unread first; repeat until \`behind_by=0\`). The log payload is not inlined here \u2014 fetch on demand.`:"You're caught up \u2014 **0** unread log entries. No need to read the log right now.",u=(n??0)===0&&e.drones.length<=1?["## Getting started","","Welcome to your first cube. Here's how to get going:","",'1. Post your first activity: `borg_log message="Starting work on <your task>"`',"2. Invite another agent session: open a new terminal and run `borg assimilate --worktree <name>`","3. Check who's here: `borg_roster`","","---",""].join(`
-`):"",f=O(e.cube.message_taxonomy),l=e.role.detailed_description_hash??null,c=e.cube.directive_hash??null,k=e.role.detailed_description?L(e.role.name,e.role.detailed_description):"_(no detailed description set)_",_="Before you post or act, load your full operating context \u2014 once per session; static, do NOT re-fetch on every wake:\n- `borg_playbook` \u2014 your full operating disciplines (verification, four-surface propagation, ack / routing / idle detail).\n- `borg_cube` \u2014 the cube directive + conventions (log vocabulary, project / git / dispatch conventions).",m=r==="full"||l==null||l!==p,R=r==="full"||c==null||c!==g,E=r==="full"||!h,d=[u+`# Cube: ${e.cube.name} \u2014 ${e.drone.label}`,"",`**Your role:** ${e.role.name}`,""];return r==="lite"&&d.push('_(lite regen \u2014 the role playbook may be omitted when unchanged; your operating context (playbook + cube directive) loads via the Session-start block (borg_playbook + borg_cube). If the playbook is NOT in your current context (e.g. after a context-compaction), call `borg_regen mode="full"` to re-orient.)_',""),d.push("## Session start \u2014 required before acting",_,"",...f?[f,""]:[],`## Your role: ${e.role.name}`,m?k:["_(role playbook unchanged since your last full/lite regen; omitted in lite mode)_","",...I(e.role.detailed_description)].join(`
-`),"","## Roles in this cube",i,"","## Connected drones",t,"","## Cube log",s),E&&(d.push("",v()),h=!0),m&&l!=null&&(p=l),R&&c!=null&&(g=c),d.join(`
-`)}function Q(e,o,r){const i=o.get(e.drone_id),t=i?r.get(i.role_id):null,n=new Date(e.created_at).toISOString(),s=typeof e.id=="string"&&e.id.length>0?` [entry_id: ${e.id}]`:"";return`**[${n}]**${s} ${i?.label??"?"} (${t?.name??"?"}): ${e.message}`}export{B as DRONE_PLAYBOOK,U as __resetRegenSessionState,L as compressRoleText,Q as formatLogEntryMarkdown,N as formatRationalePointer,j as formatRegenMarkdown,v as getDronePlaybook,W as getDronePlaybookChapter,x as humanAgo,O as nullTaxonomyTip,q as parseRationalePointer,M as regenWakePathDroneLabel};
+`:t.body.slice(0,s+1))+D(e,t.heading)+`
+`}).join("")}function M(e,o={}){const r=o.mode??"full",i=e.roles.map(a=>`- **${a.name}**${a.is_default?" _(default)_":""} \u2014 ${a.short_description||"_(no short description)_"}`).join(`
+`),t=e.drones.map(a=>{const _=e.roles.find(E=>E.id===a.role_id),R=A(_?.name??"?",a.agent_kind);return`- **${a.label}** (${R}) \u2014 last seen ${C(new Date(a.last_seen))}`}).join(`
+`)||"_(no drones connected)_",n=typeof e.behind_by=="number"?e.behind_by:null,s=n===null?"Call `borg_read-log unread_only=true` to check for and drain any unread log entries (the log payload is not inlined in regen).":n>0?`You have **${n}** unread log ${n===1?"entry":"entries"}. Drain them with \`borg_read-log unread_only=true\` (oldest-unread first; repeat until \`behind_by=0\`). The log payload is not inlined here \u2014 fetch on demand.`:"You're caught up \u2014 **0** unread log entries. No need to read the log right now.",d=(n??0)===0&&e.drones.length<=1?["## Getting started","","Welcome to your first cube. Here's how to get going:","",'1. Post your first activity: `borg_log message="Starting work on <your task>"`',"2. Invite another agent session: open a new terminal and run `borg assimilate --worktree <name>`","3. Check who's here: `borg_roster`","","---",""].join(`
+`):"",p=T(e.cube.message_taxonomy),c=e.role.detailed_description_hash??null,v=e.role.detailed_description?N(e.role.name,e.role.detailed_description):"_(no detailed description set)_",w="Before you post or act, load your full operating context \u2014 once per session; static, do NOT re-fetch on every wake:\n- `borg_playbook` \u2014 your full operating disciplines (verification, four-surface propagation, ack / routing / idle detail).\n- `borg_cube` \u2014 the cube directive + conventions (log vocabulary, project / git / dispatch conventions).",g=r==="full"||c==null||c!==h,k=r==="full"||!u,l=[d+`# Cube: ${e.cube.name} \u2014 ${e.drone.label}`,"",`**Your role:** ${e.role.name}`,""];return r==="lite"&&l.push('_(lite regen \u2014 the role playbook may be omitted when unchanged; your operating context (playbook + cube directive) loads via the Session-start block (borg_playbook + borg_cube). If the playbook is NOT in your current context (e.g. after a context-compaction), call `borg_regen mode="full"` to re-orient.)_',""),l.push(r==="full"?"## Session start \u2014 required before acting":"## Session start",r==="full"?w:'Operating context (playbook + cube directive) was loaded at session start \u2014 re-fetch `borg_playbook` / `borg_cube` ONLY after a context-compaction (a `mode="full"` regen), not on every wake.',"",...p?[p,""]:[],`## Your role: ${e.role.name}`,g?v:["_(role playbook unchanged since your last full/lite regen; omitted in lite mode)_","",...x(e.role.detailed_description)].join(`
+`),"","## Roles in this cube",i,"","## Connected drones",t,"","## Cube log",s),k&&(l.push("",y()),u=!0),g&&c!=null&&(h=c),l.join(`
+`)}function U(e,o,r){const i=o.get(e.drone_id),t=i?r.get(i.role_id):null,n=new Date(e.created_at).toISOString(),s=typeof e.id=="string"&&e.id.length>0?` [entry_id: ${e.id}]`:"";return`**[${n}]**${s} ${i?.label??"?"} (${t?.name??"?"}): ${e.message}`}export{$ as DRONE_PLAYBOOK,B as __resetRegenSessionState,N as compressRoleText,U as formatLogEntryMarkdown,D as formatRationalePointer,M as formatRegenMarkdown,y as getDronePlaybook,F as getDronePlaybookChapter,C as humanAgo,T as nullTaxonomyTip,W as parseRationalePointer,Y as regenWakePathDroneLabel};

package/dist/unknown-subcommand.d.ts

@@ -0,0 +1,21 @@
+/**
+ * gh#911: top-level CLI footgun guard.
+ *
+ * `borg <unknown>` (e.g. `borg evict-drone X`) used to fall through the
+ * subcommand router, get ignored by parseCliFlag (which validates only
+ * `--cli`), and silently LAUNCH a Claude Code session with the typo'd word as
+ * its prompt — surprising + wasteful, and the trailing args were dropped.
+ *
+ * This pure predicate lets claude.ts reject an unknown NON-FLAG argv[2] before
+ * the default launch. Bare `borg` (no argv[2]) and recognized flags
+ * (`--cli`, `--remote`, agent passthrough, …) still fall through to launch.
+ */
+/** The subcommands the claude.ts router dispatches on (lines 107-176). */
+export declare const KNOWN_SUBCOMMANDS: readonly ["setup", "assimilate", "spawn", "sync", "cleanup", "launch-all"];
+/**
+ * Returns the offending command string when argv[2] is an unknown non-flag
+ * positional (caller should error + exit 1), or null when it's bare `borg`,
+ * a flag, or a known subcommand (caller falls through to existing handling).
+ */
+export declare function unknownSubcommand(argv2: string | undefined): string | null;
+//# sourceMappingURL=unknown-subcommand.d.ts.map

package/dist/unknown-subcommand.js

@@ -0,0 +1 @@
+const u=["setup","assimilate","spawn","sync","cleanup","launch-all"];function t(n){return n===void 0||n.startsWith("-")||u.includes(n)?null:n}export{u as KNOWN_SUBCOMMANDS,t as unknownSubcommand};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp",
-  "version": "1.0.38",
+  "version": "1.0.39",
   "description": "Coordinate AI coding agents in shared cubes. Works with Claude Code and Codex. Create projects, assign roles, and share a live activity log.",
   "type": "module",
   "main": "dist/index.js",