greprag 5.75.0 → 5.77.0

package/dist/opencode-plugin.bundle.js

@@ -1771,7 +1771,7 @@ function crushMessages(messages, opts) {
 
 // src/commands/os-primer-reminder.ts
 function buildOsPrimer(env) {
-  const spawnEntry = env?.platform === "codex" ? "codex-chip-spawn" : env?.platform === "opencode" ? "chip-bootloader" : "chip-spawn";
+  const spawnEntry = env?.platform === "codex" ? "codex-chip-spawn" : env?.platform === "opencode" ? "chip-bootloader" : env?.platform === "grok" ? "grok-chip-spawn" : "chip-spawn";
   return [
     "[grepragOS \u2014 the operating laws. Full doctrine: `greprag load os`.]",
     '\u2022 Doctrine vs state: methods ship in the CLI (`greprag load`); live state lives in the repo. A skill that depends on repo state carries a "STATE \u2014 read these first" block naming exact paths.',
@@ -1818,7 +1818,7 @@ function buildInboxPrimer(env) {
     // "ToolSearch select:Monitor" is unactionable there (neither tool exists) and an
     // un-followable alarm decays into banner-blindness for the announces around it.
     grok ? "[GROK INBOX \u2014 greprag is your agent-to-agent mesh. Idle wake is Grok `monitor` (NOT Claude Monitor, NOT a bash while-true). Turn-boundary drain also rides Stop additionalContext. Unarmed, idle mail waits until the next Stop or user prompt.]" : codex ? "[CODEX INBOX \u2014 greprag is your agent-to-agent mesh. Codex-to-Codex: discover tasks and their repo/workspace with `codex_app.list_threads`, then coordinate with `codex_app.send_message_to_thread`. Reaching ANY non-Codex peer (Claude Code / opencode / Grok / another tenant's agent): `greprag send` IS the live primary path \u2014 native Codex messaging cannot reach them.]" : opencode ? "[OPENCODE INBOX \u2014 greprag is your agent-to-agent mesh. Inbound delivery is AUTOMATIC here: the greprag plugin arms a relay for this session (nothing to arm or re-arm) and inbound peer messages arrive as injected turns.]" : "[\u26A0 ARM YOUR INBOX WATCHER NOW \u2014 you are UNREACHABLE until you do. Peers are live in your mesh trying to coordinate with this session, and the operator can DM you \u2014 but they reach you ONLY while armed. Unarmed, you are invisible and their messages silently pile up. The watcher can DROP ANYTIME (crash / reload / OOM) \u2014 EVERY turn you are flagged unarmed you MUST re-arm, or coordination breaks.]",
-    grok ? `ARM (idle wake): Grok \`monitor\` tool, persistent:true, description:"greprag inbox ${env.short}", command: \`${arm}\`. \`--quiet\` is REQUIRED \u2014 Grok treats stderr as wake events; the Claude bash wrapper is PowerShell-invalid. Use full UUID / 16-hex, never 8-hex. Second session: spawn_subagent (child arms its own watch; parent keeps ONE). Floor: Stop-hook drain injects unread mail even if you never arm. Then \`greprag inbox\`.` : codex ? "CODEX: Native Codex tools are the source of truth: `codex_app.list_threads` discovers tasks plus their repo/workspace, and `codex_app.send_message_to_thread` handles Codex-to-Codex coordination. GrepRAG inbox rows for Codex surface through turn hooks only: SessionStart `drain` and UserPromptSubmit `codex-notify`. There is no Codex startup watcher to install. If hooks do not fire, open Codex Desktop Settings -> Settings -> Hooks, trust the GrepRAG commands, start a fresh Codex session, then drain what is waiting: `greprag inbox`." : opencode ? "DELIVERY: the relay arms itself on this session's first turn and injects inbound messages as they land \u2014 treat an injected `Message from <handle> (session <8hex>):` turn as async peer mail, not the operator typing. Drain anything already waiting: `greprag inbox`." : `ARM: Monitor is a deferred tool \u2014 \`ToolSearch select:Monitor\`, then call Monitor with persistent:true, timeout_ms:3600000, description:"greprag inbox ${env.short}", command: \`${arm}\`. The \`--session ${env.short}\` is REQUIRED \u2014 a bare \`greprag inbox watch\` writes no pidfile, so the arm-check reads you unarmed forever. NEVER run it bare also because it is a foreground stream and hangs the turn. Then drain what is waiting: \`greprag inbox\`.`,
+    grok ? `ARM (idle wake): Grok \`monitor\` tool, persistent:true, description:"greprag inbox ${env.short}", command: \`${arm}\`. \`--quiet\` is REQUIRED \u2014 Grok treats stderr as wake events; the Claude bash wrapper is PowerShell-invalid. Use full UUID / 16-hex, never 8-hex. A chip \u2192 \`greprag load grok-chip-spawn\` then \`greprag grok spawn\` (child arms its own watch; parent keeps ONE). A helper \u2192 spawn_subagent. Floor: Stop-hook drain injects unread mail even if you never arm. Then \`greprag inbox\`.` : codex ? "CODEX: Native Codex tools are the source of truth: `codex_app.list_threads` discovers tasks plus their repo/workspace, and `codex_app.send_message_to_thread` handles Codex-to-Codex coordination. GrepRAG inbox rows for Codex surface through turn hooks only: SessionStart `drain` and UserPromptSubmit `codex-notify`. There is no Codex startup watcher to install. If hooks do not fire, open Codex Desktop Settings -> Settings -> Hooks, trust the GrepRAG commands, start a fresh Codex session, then drain what is waiting: `greprag inbox`." : opencode ? "DELIVERY: the relay arms itself on this session's first turn and injects inbound messages as they land \u2014 treat an injected `Message from <handle> (session <8hex>):` turn as async peer mail, not the operator typing. Drain anything already waiting: `greprag inbox`." : `ARM: Monitor is a deferred tool \u2014 \`ToolSearch select:Monitor\`, then call Monitor with persistent:true, timeout_ms:3600000, description:"greprag inbox ${env.short}", command: \`${arm}\`. The \`--session ${env.short}\` is REQUIRED \u2014 a bare \`greprag inbox watch\` writes no pidfile, so the arm-check reads you unarmed forever. NEVER run it bare also because it is a foreground stream and hangs the turn. Then drain what is waiting: \`greprag inbox\`.`,
     "",
     // The facts + directives — a flat list (no MODEL/RULES scaffolding; the labels were
     // human doc-structure, dead weight to an agent). Everything that helps the agent DECIDE
@@ -1857,6 +1857,10 @@ var OPENCODE_CHIP_SPAWN_POINTER = [
   "[greprag chips \u2014 agent coordination is built in (messaging plumbing in the inbox primer).]",
   "\u2022 Delegating a component of a plan to an isolated chip session, or `greprag fix spawn` just printed a FIX-chip mission? \u2192 run `greprag load chip-bootloader` FIRST for the method: OpenCode chips spawn natively via `greprag opencode chip goal create` + `greprag opencode chip spawn` (HTTP child session; manual paste only when the API is down). \u22652 chips at one objective \u2192 `greprag load chip-leader-opencode` BEFORE the first spawn."
 ].join("\n");
+var GROK_CHIP_SPAWN_POINTER = [
+  "[greprag chips \u2014 agent coordination is built in (messaging plumbing in the inbox primer).]",
+  "\u2022 About to spawn a chip? \u2192 run `greprag load grok-chip-spawn` FIRST. Vehicle is `greprag grok spawn` (cmd /k TUI bootloader). Child arms its own quiet inbox watch; parent keeps one and talks via `greprag send`. `spawn_subagent` is a helper, not a chip. \u22652 chips at one objective \u2192 `greprag load chip-leader` BEFORE the first spawn."
+].join("\n");
 var CODEX_CHIP_SPAWN_POINTER = [
   "[greprag Codex delegation \u2014 1\u20132-chip quick path with the initiator as LEAD, or a separate LEAD for larger/seamed missions.]",
   "\u2022 About to delegate a Codex task? \u2192 run `greprag load codex-chip-spawn` FIRST. Use exact first-line titles `LEAD: <Mission>`, `Chip A/B/C: <Specific Purview>`, and `FIX: [type] <one friction unit>`. Chips are ordinary writable native tasks; completion is a native Codex task reply to the LEAD after committing. A `FIX:` task loads `greprag load mechanic` first."
@@ -1882,6 +1886,8 @@ var chipSpawnPointerModule = {
       return null;
     if (env.platform === "opencode")
       return OPENCODE_CHIP_SPAWN_POINTER;
+    if (env.platform === "grok")
+      return GROK_CHIP_SPAWN_POINTER;
     return CHIP_SPAWN_POINTER;
   },
   reminder: () => null
@@ -2432,15 +2438,15 @@ var loadoutRegistrarModule = {
 // src/commands/delivery-reminder.ts
 function coordinationLine(platform) {
   if (platform === "codex") {
-    return "Codex: at the merge/deploy gate, call codex_app.list_threads unfiltered, filter to peers in the same repo, then use codex_app.send_message_to_thread once for ready or overlapping work. Delivery owner: rename this task `DEPLOY: <existing title>`; transfer the prefix on handoff; remove the prefix when delivery is done.";
+    return "Codex: at the merge/deploy gate, call codex_app.list_threads unfiltered, filter to peers in the same repo, and inspect their current summaries/status. Use codex_app.send_message_to_thread only for visible evidence of an unlanded ready commit, overlapping integration, or a concrete blocker. Peers with nothing actionable stay silent; do not solicit or send negative acknowledgements or routine completion follow-ups. Delivery owner: rename this task `DEPLOY: <existing title>` for operator visibility only; transfer the prefix on handoff; remove it before reporting delivery complete or abandoned.";
   }
   if (platform === "claude-code") {
-    return "Claude Code: at the merge/deploy gate, discover peers in the same repo and send one concise delivery notice to peers with ready or overlapping work.";
+    return "Claude Code: at the merge/deploy gate, inspect peers in the same repo and send one concise delivery notice only for visible evidence of an unlanded ready commit, overlapping integration, or a concrete blocker. Peers with nothing actionable stay silent; do not solicit or send negative acknowledgements or routine completion follow-ups.";
   }
   if (platform === "opencode") {
-    return "OpenCode: at the merge/deploy gate, use the GrepRAG project/session registry and send one concise delivery notice to peers with ready or overlapping work.";
+    return "OpenCode: at the merge/deploy gate, use the GrepRAG project/session registry and send one concise notice only for visible evidence of an unlanded ready commit, overlapping integration, or a concrete blocker. Peers with nothing actionable stay silent; do not solicit or send negative acknowledgements or routine completion follow-ups.";
   }
-  return "At the merge/deploy gate, coordinate once with peers in the same repo who have ready or overlapping work.";
+  return "At the merge/deploy gate, inspect peers in the same repo and send one concise notice only for visible evidence of an unlanded ready commit, overlapping integration, or a concrete blocker. Peers with nothing actionable stay silent; do not solicit or send negative acknowledgements or routine completion follow-ups.";
 }
 function buildDeliveryAnnounce(env) {
   if (!env.deliveryRepo)
@@ -2450,7 +2456,7 @@ function buildDeliveryAnnounce(env) {
     `[DELIVERY \u2014 ${project}]`,
     "Commit useful, passing work.",
     coordinationLine(env.platform),
-    "Include ready peer commits and clear known blockers, then merge to the default branch and deploy immediately. Missing replies and unfinished peer work do not block delivery.",
+    "Include visible ready peer commits and clear known blockers, then merge to the default branch and deploy immediately. Silence means nothing actionable and does not block delivery.",
     "Use this repo's delivery profile and verify production."
   ].join("\n");
 }
@@ -2461,6 +2467,14 @@ var deliveryControlModule = {
   reminder: () => null
 };
 
+// src/commands/persona-reminder.ts
+var personaAnnounceModule = {
+  id: "persona-announce",
+  detect: () => ({ tier: "silent" }),
+  announce: (env) => env.personaAnnounce || null,
+  reminder: () => null
+};
+
 // src/commands/reminder-registry.ts
 var REGISTRY = [
   osPrimerModule,
@@ -2482,6 +2496,8 @@ var REGISTRY = [
   // active project procedures, rendered generically from operator-owned installs
   deliveryControlModule,
   // repo-scoped announce-first Delivery System pilot (all harnesses)
+  personaAnnounceModule,
+  // tenant-scoped Persona, shared across projects/harnesses
   loadoutRegistrarModule,
   // equipped loadouts: one advisor announce each + per-turn keyword Match (docs/loadout.md)
   setupWarningModule,
@@ -2585,12 +2601,16 @@ function buildOpenCodeEnv(params) {
     corpusApiDocs: params.corpusApiDocs ?? [],
     updateAvailable: params.updateAvailable ?? null,
     procedureAnnounces: params.procedureAnnounces ?? [],
-    mirroredSkills: params.mirroredSkills
+    mirroredSkills: params.mirroredSkills,
+    personaAnnounce: params.personaAnnounce ?? null
   };
 }
 function getOpenCodeAnnounces(env) {
   return [...collectAnnounces(env, opencodeRegistry), OPENCODE_QUOTA_WAITLIST_ANNOUNCE];
 }
+function getOpenCodePersistentAnnounces(env) {
+  return collectAnnounces(env, opencodeRegistry.filter((m) => m.id === "persona-announce"));
+}
 function getOpenCodeReminders(env) {
   return collectReminders(env, opencodeRegistry);
 }
@@ -4290,6 +4310,8 @@ async function fetchRecapInbox(anchor) {
 }
 var relayArmedBySession = /* @__PURE__ */ new Set();
 var announcedBySession = /* @__PURE__ */ new Set();
+var personaAnnounceBySession = /* @__PURE__ */ new Map();
+var PERSONA_SESSION_CACHE_MAX = 100;
 var turnCountBySession = /* @__PURE__ */ new Map();
 var procedurePromptKeyBySession = /* @__PURE__ */ new Map();
 var cachedRecap = null;
@@ -4327,6 +4349,32 @@ async function fetchSkillActivation(apiKey, cwd) {
     return void 0;
   }
 }
+async function fetchPersonaAnnounce(apiKey) {
+  try {
+    const response = await fetch(`${API_URL}/v1/persona`, {
+      headers: { Authorization: `Bearer ${apiKey}` }
+    });
+    if (!response.ok)
+      return null;
+    const data = await response.json();
+    return typeof data.announce === "string" && data.announce.length > 0 ? data.announce : null;
+  } catch {
+    return null;
+  }
+}
+async function personaAnnounceForSession(sessionId, apiKey) {
+  if (personaAnnounceBySession.has(sessionId)) {
+    return personaAnnounceBySession.get(sessionId) ?? null;
+  }
+  const announce = await fetchPersonaAnnounce(apiKey);
+  if (personaAnnounceBySession.size >= PERSONA_SESSION_CACHE_MAX) {
+    const oldest = personaAnnounceBySession.keys().next().value;
+    if (oldest)
+      personaAnnounceBySession.delete(oldest);
+  }
+  personaAnnounceBySession.set(sessionId, announce);
+  return announce;
+}
 function startSessionRelay(sessionId, serverUrl) {
   if (process.env.GREPRAG_OPENCODE_RELAY === "0")
     return;
@@ -4661,6 +4709,7 @@ ALWAYS pass \`--from-session ${sid82}\` when you run \`greprag send\`, so recipi
       if (sid8) {
         const turnCount = (turnCountBySession.get(sid8) ?? 0) + 1;
         turnCountBySession.set(sid8, turnCount);
+        const firstAnnounce = !announcedBySession.has(sid8);
         const env = buildOpenCodeEnv({
           short: sid8,
           turnCount,
@@ -4676,9 +4725,12 @@ ALWAYS pass \`--from-session ${sid82}\` when you run \`greprag send\`, so recipi
               return [];
             }
           })(),
-          mirroredSkills: !announcedBySession.has(sid8) ? await fetchSkillActivation(apiKey, workingDir) : void 0
+          mirroredSkills: firstAnnounce ? await fetchSkillActivation(apiKey, workingDir) : void 0,
+          // output.system is fresh on EVERY transform call. Resolve Persona
+          // once/session, then replay the cached shared-registry announce.
+          personaAnnounce: await personaAnnounceForSession(sid8, apiKey)
         });
-        if (!announcedBySession.has(sid8)) {
+        if (firstAnnounce) {
           announcedBySession.add(sid8);
           const announces = getOpenCodeAnnounces(env);
           if (announces.length > 0) {
@@ -4687,6 +4739,13 @@ ALWAYS pass \`--from-session ${sid82}\` when you run \`greprag send\`, so recipi
             }
             dlog(`interrupt: pushed ${announces.length} announce(s) for sid=${sid8}`);
           }
+        } else {
+          const persistent = getOpenCodePersistentAnnounces(env);
+          for (const line of persistent)
+            pushSystemPrompt(output, line);
+          if (persistent.length > 0) {
+            dlog(`interrupt: replayed ${persistent.length} persistent announce(s) for sid=${sid8}`);
+          }
         }
         const reminders = getOpenCodeReminders(env);
         if (reminders.length > 0) {

package/dist/opencode-plugin.js

@@ -548,6 +548,8 @@ async function fetchRecapInbox(anchor) {
 // ============================================================================
 const relayArmedBySession = new Set();
 const announcedBySession = new Set();
+const personaAnnounceBySession = new Map();
+const PERSONA_SESSION_CACHE_MAX = 100;
 const turnCountBySession = new Map();
 const procedurePromptKeyBySession = new Map();
 /** Cached recap body per projectId. opencode fires
@@ -596,6 +598,35 @@ async function fetchSkillActivation(apiKey, cwd) {
         return undefined;
     }
 }
+async function fetchPersonaAnnounce(apiKey) {
+    try {
+        const response = await fetch(`${API_URL}/v1/persona`, {
+            headers: { Authorization: `Bearer ${apiKey}` },
+        });
+        if (!response.ok)
+            return null;
+        const data = await response.json();
+        return typeof data.announce === 'string' && data.announce.length > 0
+            ? data.announce
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function personaAnnounceForSession(sessionId, apiKey) {
+    if (personaAnnounceBySession.has(sessionId)) {
+        return personaAnnounceBySession.get(sessionId) ?? null;
+    }
+    const announce = await fetchPersonaAnnounce(apiKey);
+    if (personaAnnounceBySession.size >= PERSONA_SESSION_CACHE_MAX) {
+        const oldest = personaAnnounceBySession.keys().next().value;
+        if (oldest)
+            personaAnnounceBySession.delete(oldest);
+    }
+    personaAnnounceBySession.set(sessionId, announce);
+    return announce;
+}
 // ============================================================================
 // Per-session relay spawner — "anytime opencode is opened and being used"
 // ============================================================================
@@ -1002,6 +1033,7 @@ const GrepRAGMemoryPlugin = async (ctx) => {
             if (sid8) {
                 const turnCount = (turnCountBySession.get(sid8) ?? 0) + 1;
                 turnCountBySession.set(sid8, turnCount);
+                const firstAnnounce = !announcedBySession.has(sid8);
                 // Build env — only populate what's available in the opencode context
                 const env = (0, opencode_interrupt_1.buildOpenCodeEnv)({
                     short: sid8,
@@ -1019,12 +1051,15 @@ const GrepRAGMemoryPlugin = async (ctx) => {
                             return [];
                         }
                     })(),
-                    mirroredSkills: !announcedBySession.has(sid8)
+                    mirroredSkills: firstAnnounce
                         ? await fetchSkillActivation(apiKey, workingDir)
                         : undefined,
+                    // output.system is fresh on EVERY transform call. Resolve Persona
+                    // once/session, then replay the cached shared-registry announce.
+                    personaAnnounce: await personaAnnounceForSession(sid8, apiKey),
                 });
                 // Announces: inject on first fire per session (static primers)
-                if (!announcedBySession.has(sid8)) {
+                if (firstAnnounce) {
                     announcedBySession.add(sid8);
                     const announces = (0, opencode_interrupt_1.getOpenCodeAnnounces)(env);
                     if (announces.length > 0) {
@@ -1034,6 +1069,14 @@ const GrepRAGMemoryPlugin = async (ctx) => {
                         dlog(`interrupt: pushed ${announces.length} announce(s) for sid=${sid8}`);
                     }
                 }
+                else {
+                    const persistent = (0, opencode_interrupt_1.getOpenCodePersistentAnnounces)(env);
+                    for (const line of persistent)
+                        pushSystemPrompt(output, line);
+                    if (persistent.length > 0) {
+                        dlog(`interrupt: replayed ${persistent.length} persistent announce(s) for sid=${sid8}`);
+                    }
+                }
                 // Reminders: inject every turn (dynamic nudges)
                 const reminders = (0, opencode_interrupt_1.getOpenCodeReminders)(env);
                 if (reminders.length > 0) {

package/dist/session-id.js

@@ -45,6 +45,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isUuidV7 = isUuidV7;
 exports.truncateSessionId = truncateSessionId;
+exports.isSessionAddressTarget = isSessionAddressTarget;
 exports.sameSessionId = sameSessionId;
 exports.readSessionEnv = readSessionEnv;
 exports.peerHumanTag = peerHumanTag;
@@ -83,6 +84,18 @@ function truncateSessionId(sessionId) {
         return hex.slice(0, 16);
     return hex.slice(0, 8);
 }
+function isSessionAddressTarget(target) {
+    if (!target)
+        return false;
+    const t = target.trim();
+    if (FULL_UUID_RE.test(t))
+        return true;
+    if (/^[0-9a-f]{8}$/i.test(t))
+        return true;
+    if (/^[0-9a-f]{16}$/i.test(t))
+        return true;
+    return false;
+}
 function sameSessionId(left, right) {
     if (!left || !right)
         return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "greprag",
-  "version": "5.75.0",
+  "version": "5.77.0",
   "description": "GrepRAG — agent memory for Claude Code, Codex, OpenCode, and Grok Build.",
   "main": "dist/index.js",
   "bin": {

package/skill/greprag/SKILL.md

@@ -17,7 +17,7 @@ description: |
   Codex work", "isolated Codex session", or "repo collisions".
 metadata:
   author: travsteward
-  version: "3.10.0"
+  version: "3.11.0"
   repository: https://github.com/travsteward/greprag
 license: MIT
 ---
@@ -30,7 +30,7 @@ Platform setup is progressive:
 - **Codex**: see `docs/setup.md § codex` after install (`greprag init --codex --tenant-id <handle>`, then Codex Desktop Settings -> Settings -> Hooks trust review).
 - **Claude Code**: see `docs/setup.md § claude-code` for the default hook/Monitor/conventions path (`greprag init --claude` or detected `greprag init`).
 - **OpenCode**: see `docs/setup.md § opencode` for plugin install (`greprag init --opencode`).
-- **Grok Build**: `greprag init --grok --tenant-id <handle>`. Recap is a sidecar plus `~/.grok/rules/greprag.md`. Idle inbox: Grok `monitor` + `greprag inbox watch --session $GROK_SESSION_ID --json --quiet`. **16-hex / full UUID**, never 8-hex (UUIDv7 collision). Second session: `spawn_subagent`. See `docs/platform-grok.md`.
+- **Grok Build TUI**: exact method below + `docs/platform-grok.md`. Setup: `greprag init --grok --tenant-id <handle>`, then `/hooks` → `r`.
 
 For collision-safe parallel Codex implementation, read `docs/codex-chip.md`.
 
@@ -139,9 +139,42 @@ All accept `--project <name>`, `--from ISO --to ISO`, `--format markdown|json`.
 
 Aliases (silent back-compat): `greprag memory briefing` → `recap` (renamed v5.16.0); `greprag odyssey ...` still works for v5.8.0-era scripts. Raw curl + `--type` value catalog: `docs/memory-advanced.md`.
 
+## Grok Build TUI — exact method
+
+Grok is not Claude. SessionStart stdout cannot inject. `monitor` treats **stderr as a wake**. Tool-runner PowerShell is `-NonInteractive` with redirected stdin; its Job Object **kills every child when the tool call returns**.
+
+**Session start (every turn-0):**
+1. Short = first **16 hex** of `$GROK_SESSION_ID` with dashes stripped (never 8 — UUIDv7 8-hex collides for ~65s).
+2. If `~/.greprag/grok-context/<16-hex>.md` exists, Read it. Else `greprag memory recap`.
+3. Send/reply with `--from-session $GROK_SESSION_ID` (full UUID).
+
+**Arm inbox (once per session):** Grok tool `monitor`, `persistent: true`, `description: "greprag inbox <16-hex>"`, command:
+
+```
+greprag inbox watch --session $GROK_SESSION_ID --json --quiet
+```
+
+- Not Claude Monitor. Not bash `while true`. `--quiet` is required.
+- If a greprag inbox monitor is **already listed**, do not start another. Instant exit = already armed, not a crash.
+- Floor: Stop-hook `drain` injects unread mail even unarmed. Do not nag UNARMED every Stop.
+
+**Chip (visible TUI):** `greprag load grok-chip-spawn` FIRST, then `greprag grok spawn`. Child is a real window + own inbox watch. **Helper:** `spawn_subagent` `background: true` (dies with this session, no mesh). Parent keeps **one** watch. Send:
+
+```
+greprag send "…" --to travis@greprag.com/<child-full-uuid> --from-session $GROK_SESSION_ID
+```
+
+Child watch events may appear on the parent TUI — resume the child to act. Do not arm a second parent watch.
+
+**Secrets / TTY (npm login, Read-Host, sticky consoles):**
+- `Read-Host` throws. Do not paste secrets in chat.
+- In-process paste: `powershell -STA -NoProfile -File $env:USERPROFILE\.claude\scripts\prompt-secret.ps1 …` (WinForms, prefix-only stdout).
+- `Start-Process` / `cmd /c start` windows **die with the tool call** (Job Object). A console that must outlive the call: `schtasks /Create … /IT` then `schtasks /Run` (outside the job).
+- npm publish with Windows Hello passkey: `npm login --auth-type=web` in that scheduled-task `cmd /k` window → browser **Use security key** / Hello PIN. If the page then shows a **token**, that is the CLI OTP — not the Hello PIN. `--otp` is TOTP or that page token only. Publish is a second Hello. Docs: https://docs.npmjs.com/accessing-npm-using-2fa/
+
 ## Proactive-fire rules
 
-**Grok Build: ABOUT TO ARM INBOX? USE Grok `monitor` (persistent:true) with `greprag inbox watch --session $GROK_SESSION_ID --json --quiet`.** Full UUID / 16-hex, never 8-hex (UUIDv7 collision). Not Claude Monitor. Not a bash `while true` wrapper. `--quiet` is required — Grok treats stderr as wake events. Second session: `spawn_subagent`; child arms its own watch; parent keeps one. Floor: Stop-hook drain injects unread mail even unarmed.
+**Grok Build: ABOUT TO ARM INBOX? USE the Grok TUI method above — `monitor` + `greprag inbox watch --session $GROK_SESSION_ID --json --quiet`.** One watch. Instant exit = armed. Full UUID / 16-hex, never 8-hex.
 
 **Claude Code: ABOUT TO BACKGROUND A `greprag inbox watch`? USE THE `Monitor` AGENT TOOL, NOT `Bash(run_in_background: true)`.** Bash background notifies only on process completion; watchers run forever, so the agent gets zero events until it manually reads the output file. Arm it with the **exit-aware relauncher** — `while true; do greprag inbox watch --session <short> --json --owner-pid <pid>; case $? in 0|64) break;; esac; sleep 1; done` — under Monitor `persistent:true` (this is exactly what the arm hook prints; paste it verbatim). The loop is supervisor-death recovery: Monitor `persistent:true` does NOT re-run the command on exit, so without it a crashed supervisor only recovers on the next turn. The `case $? in 0|64) break` is what makes it safe — it breaks on clean/consumer-gone (0) and fatal/bad-key (64), relaunching ONLY on a crash. (A *bare* `while true; …; sleep 1; done` WITHOUT that break is the 2026-06-04 OOM orphan — don't use that form; the exit-aware version was restored 2026-06-14.) Full pattern: `docs/inbox-watch.md`.
 
@@ -165,6 +198,7 @@ Aliases (silent back-compat): `greprag memory briefing` → `recap` (renamed v5.
 
 - `docs/setup.md` — codex · claude-code · opencode · auth · hooks · conventions · permissions · channels · anchor · bulk-register
 - `docs/platforms.md` — exact platform paths for Claude Code · Codex · OpenCode · Grok Build
+- `docs/platform-grok.md` — Grok Build TUI method (hooks, sidecar, monitor, Job Object)
 - `docs/codex-chip.md` — Codex quick-chip, Leader, reporting, and cleanup shape
 - `docs/per-project-flags.md` — flip `memory_capture` / `session_start_recap` / `inbox_notify`
 - `docs/inbox.md` — `greprag send`, `greprag inbox`, address grammar, retract (internal messaging)

package/skill/templates/chip-spawn.md

@@ -1,5 +1,7 @@
 # Chip Spawn Method
 
+**Grok Build?** Stop. Run `greprag load grok-chip-spawn`. This entry is Claude `spawn_task`.
+
 The `pre-spawn-check` PreToolUse hook **validates** chip prompts at the spawn boundary, but **cannot inject content** — `modifiedInput` is silently dropped by the CCD harness for MCP `spawn_task` calls (see `adr/spawn-task-hook-mode.md` 2026-05-27 entry). The agent writes Block 1 + Block 2 into the prompt itself. Validator rejects with `permissionDecision: deny` and a remediation reason if Block 1 or Block 2 markers are missing.
 
 > **Part of a multi-chip mission?** If this chip is one of ≥2 aimed at a single objective, you should already be inside a chip-leader plan — your **base branch** and **merge target** (the integration branch, *never* master) come from it. If you're not, stop and run `greprag load chip-leader` first. A lone chip targeting its own objective proceeds here directly.

package/skill/templates/grok-chip-spawn.md

@@ -0,0 +1,101 @@
+# Grok Chip Spawn Method
+
+The Grok chip is a **real TUI**: `greprag grok spawn` opens a `cmd /k` bootloader
+outside the tool Job Object. The child is its own Grok session (`$GROK_SESSION_ID`),
+arms its own quiet inbox watch, and talks on `greprag send`. Proven 2026-08-21
+(parent ping → child pong on the mesh).
+
+`spawn_subagent` is **not** a chip. It is a same-pager helper: no window, no
+inbox watch, dies with the parent. Use it for a bounded look-up. Never for a
+unit of work that must survive this session or that the operator should sit in.
+
+> **Part of a multi-chip mission?** If this chip is one of ≥2 aimed at a single
+> objective, stop and run `greprag load chip-leader` first. A lone chip at its
+> own objective proceeds here.
+
+There is no `pre-spawn-check` on Grok. You write Block 1 + task + Block 2 into
+the prompt yourself.
+
+## What the parent provides
+
+- `title: "Chip: <verb-phrase>"` — or leader label `"Chip A: …"` / `"Chip B: …"`.
+- Isolated worktree, then spawn `--cwd` **into that worktree**.
+- Prompt file: Block 1 + task body + Block 2.
+- Parent already has **one** quiet watch. Do not arm a second.
+
+`<slug>` = title slugified (`Chip: Fix synthesis loop` → `fix-synthesis-loop`).
+`<parent-uuid>` = **this** session's `$GROK_SESSION_ID` (full UUID). Short form
+for display is **16 hex**, never 8 (UUIDv7 8-hex collides ~65s).
+`<handle>` = operator greprag handle (from `greprag whoami`).
+
+## Parent — worktree then spawn (PowerShell)
+
+```powershell
+$repo = (git rev-parse --show-toplevel)
+$slug = "<slug>"
+$wt = Join-Path $repo ".claude\worktrees\$slug"
+if (-not (Test-Path $wt)) {
+  git worktree add $wt -b "chip/$slug"
+}
+$promptFile = Join-Path $env:TEMP "greprag-chip-$slug.md"
+Set-Content -LiteralPath $promptFile -Value $prompt -Encoding utf8
+greprag grok spawn --cwd $wt --title "Chip: <verb-phrase>" --prompt-file $promptFile
+```
+
+`$prompt` is Block 1 + task + Block 2 below. After spawn, wait for `IN-FLIGHT`
+on **your** watch. No ping = the window did not boot — do not wait on results.
+
+## Block 1 — Setup (verbatim, substitute parent uuid + handle)
+
+The chip starts already in the worktree (`--cwd`). It substitutes
+`<own-session-id>` from `$GROK_SESSION_ID`.
+
+````
+**Setup — do this FIRST:**
+
+1. Session id is `$GROK_SESSION_ID` (full UUID). Short = first 16 hex, dashes stripped.
+2. Arm ONE quiet watch (skip if a greprag inbox monitor is already listed):
+
+```
+greprag inbox watch --session $GROK_SESSION_ID --json --quiet
+```
+
+Grok `monitor`, `persistent:true`. Not Claude Monitor. Instant exit = already armed.
+
+3. Ping the parent:
+
+```
+greprag send "IN-FLIGHT: chip/<slug> launched — working" --to <handle>@greprag.com/<parent-uuid> --from-session $GROK_SESSION_ID
+```
+
+4. If `scripts/worktree-bootstrap.cjs` exists, run `node scripts/worktree-bootstrap.cjs`.
+````
+
+## Task body
+
+The work. Isolated to this worktree / `chip/<slug>`. Default autonomous. To pause
+for a human, say so in the body and `BLOCKED` ping the parent.
+
+## Block 2 — Report back (verbatim)
+
+````
+**Block 2 — Report back via greprag inbox:**
+
+```
+greprag send "<status>: <commit hash> on chip/<slug> — <one-line>" --to <handle>@greprag.com/<parent-uuid> --from-session $GROK_SESSION_ID --artifact commit:<hash>
+```
+
+Cleanup HARD RULE: no `git clean`, `git reset --hard`, `git worktree remove`,
+`git checkout <other>`, raw `rm -rf` outside this worktree's tracked files.
+````
+
+## After spawning (parent)
+
+Keep **one** watch. Talk with `greprag send --to <handle>@greprag.com/<child-full-uuid> --from-session $GROK_SESSION_ID`.
+`greprag inbox watchers` lists the child once it has armed. Child watch events
+may print on this TUI — they belong to the child; do not steal its turn.
+
+Merge / prune: same HARD RULES as `greprag load chip-spawn` (junction guard,
+`git worktree remove .claude/worktrees/<slug>`, `git branch -d chip/<slug>`).
+FIX chips: `greprag fix spawn` still prints the mission; you launch it with
+this method instead of `spawn_task`.