greprag 5.75.0 → 5.76.0

package/dist/commands/grok-spawn.js

@@ -0,0 +1,208 @@
+"use strict";
+/** Open a fresh Grok Build TUI from another agent session.
+ *
+ *  Grok's tool-runner Job Object kills `Start-Process` / `cmd /c start`
+ *  children when the tool call returns. The surviving launch is a scheduled
+ *  task (`schtasks /Create /IT` then `/Run`) that `start`s a new `cmd /k`
+ *  window running grok.exe — a visible command-prompt bootloader outside the
+ *  job. adr: adr/grok-platform.md */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveGrokExe = resolveGrokExe;
+exports.buildGrokSpawnScript = buildGrokSpawnScript;
+exports.grokSpawnHelp = grokSpawnHelp;
+exports.runGrokSpawn = runGrokSpawn;
+exports.runGrok = runGrok;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+function winQuote(value) {
+    return `"${value.replace(/"/g, '""')}"`;
+}
+function resolveGrokExe() {
+    const home = os.homedir();
+    const named = process.platform === 'win32' ? 'grok.exe' : 'grok';
+    const pinned = path.join(home, '.grok', 'bin', named);
+    if (fs.existsSync(pinned))
+        return pinned;
+    try {
+        const out = (0, child_process_1.execFileSync)(process.platform === 'win32' ? 'where.exe' : 'which', ['grok'], {
+            encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const first = out.split(/\r?\n/).map(s => s.trim()).find(s => s);
+        if (first && fs.existsSync(first))
+            return first;
+    }
+    catch { /* fall through */ }
+    return named;
+}
+function buildGrokSpawnScript(opts) {
+    const cwd = path.resolve(opts.cwd);
+    const title = opts.title || `grok ${path.basename(cwd)}`;
+    const grok = opts.grokExe || resolveGrokExe();
+    const promptArg = opts.prompt ? ` ${winQuote(opts.prompt)}` : '';
+    // Self-relaunch: schtasks runs this hidden; `start cmd /k %~f0 --boot`
+    // opens a visible command-prompt bootloader that then execs grok.exe.
+    // Immediate task-delete used to cancel the launch — caller waits.
+    return [
+        '@echo off',
+        'if /I "%~1"=="--boot" goto boot',
+        `start ${winQuote(title)} cmd /k "%~f0" --boot`,
+        'goto :eof',
+        ':boot',
+        `cd /d ${winQuote(cwd)}`,
+        `echo [greprag] booting Grok TUI in ${cwd}`,
+        `${winQuote(grok)}${promptArg}`,
+        'echo.',
+        'echo [greprag] grok exited. This window is yours.',
+    ].join('\r\n') + '\r\n';
+}
+function grokSpawnHelp() {
+    return `greprag grok spawn — open a fresh Grok Build TUI in a new command prompt.
+
+  greprag grok spawn [--cwd <path>] [--prompt "<text>"|--prompt-file <path>] [--title <name>]
+  greprag grok spawn --dry-run
+
+Windows: schtasks /IT starts a new \`cmd /k\` window (bootloader) that runs
+grok.exe. That escapes the agent tool Job Object. The child is a real TUI
+with its own $GROK_SESSION_ID; it arms its own inbox watch. This session
+keeps one watch. Message it with:
+  greprag send "…" --to <handle>@greprag.com/<child-uuid> --from-session $GROK_SESSION_ID
+`;
+}
+function sleepMs(ms) {
+    const end = Date.now() + ms;
+    while (Date.now() < end) { /* wait for Task Scheduler to start the .cmd */ }
+}
+function runGrokSpawn(args) {
+    if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+        console.log(grokSpawnHelp());
+        return;
+    }
+    const cwd = path.resolve(getArg(args, '--cwd') || process.cwd());
+    const promptFile = getArg(args, '--prompt-file');
+    let prompt = getArg(args, '--prompt') || positionalPrompt(args);
+    if (promptFile) {
+        if (!fs.existsSync(promptFile)) {
+            console.error(`greprag grok spawn: prompt file not found: ${promptFile}`);
+            process.exit(1);
+        }
+        prompt = fs.readFileSync(promptFile, 'utf8').replace(/^\uFEFF/, '').trimEnd();
+    }
+    const title = getArg(args, '--title');
+    const dryRun = args.includes('--dry-run');
+    const grokExe = resolveGrokExe();
+    const opts = { cwd, prompt, title, grokExe, dryRun };
+    if (process.platform !== 'win32') {
+        const cmd = [grokExe, '--cwd', cwd, prompt].filter((p) => !!p);
+        if (dryRun) {
+            console.log(cmd.join(' '));
+            return;
+        }
+        console.error('greprag grok spawn: Windows-only bootloader (Job Object). Run this yourself:');
+        console.error(`  ${cmd.map(a => /\s/.test(a) ? JSON.stringify(a) : a).join(' ')}`);
+        process.exitCode = 1;
+        return;
+    }
+    const script = buildGrokSpawnScript(opts);
+    if (dryRun) {
+        process.stdout.write(script);
+        return;
+    }
+    if (!fs.existsSync(cwd) || !fs.statSync(cwd).isDirectory()) {
+        console.error(`greprag grok spawn: cwd is not a directory: ${cwd}`);
+        process.exit(1);
+    }
+    const tn = `greprag-grok-${Date.now().toString(36)}`;
+    const file = path.join(os.tmpdir(), `${tn}.cmd`);
+    fs.writeFileSync(file, script, 'utf8');
+    try {
+        (0, child_process_1.execFileSync)('schtasks', [
+            '/Create', '/TN', tn, '/TR', file, '/SC', 'ONCE', '/ST', '23:59',
+            '/F', '/IT',
+        ], { stdio: ['ignore', 'pipe', 'pipe'] });
+        (0, child_process_1.execFileSync)('schtasks', ['/Run', '/TN', tn], { stdio: ['ignore', 'pipe', 'pipe'] });
+        // /Run is async. Deleting immediately cancelled the launch (field 2026-08-21).
+        sleepMs(2500);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`greprag grok spawn: schtasks failed: ${msg}`);
+        process.exit(1);
+    }
+    finally {
+        try {
+            (0, child_process_1.execFileSync)('schtasks', ['/Delete', '/TN', tn, '/F'], { stdio: 'ignore' });
+        }
+        catch { /* leftover task is harmless */ }
+    }
+    console.log(`Spawned Grok TUI (cmd /k bootloader) for ${cwd}${prompt ? ` — prompt: ${prompt}` : ''}`);
+    console.log('The new session arms its own inbox watch. This session keeps one.');
+}
+function runGrok(args) {
+    const sub = args[0];
+    if (!sub || sub === 'help' || sub === '--help' || sub === '-h') {
+        console.log(grokSpawnHelp());
+        return;
+    }
+    if (sub === 'spawn')
+        return runGrokSpawn(args.slice(1));
+    console.error(`Unknown "grok ${sub}". Run \`greprag grok spawn --help\`.`);
+    process.exit(1);
+}
+function getArg(args, flag) {
+    const idx = args.indexOf(flag);
+    if (idx === -1 || idx + 1 >= args.length)
+        return undefined;
+    const value = args[idx + 1];
+    return value.startsWith('--') ? undefined : value;
+}
+function positionalPrompt(args) {
+    const skip = new Set(['--cwd', '--prompt', '--prompt-file', '--title']);
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        if (skip.has(args[i])) {
+            i += 1;
+            continue;
+        }
+        if (args[i] === '--dry-run' || args[i] === '--help' || args[i] === '-h')
+            continue;
+        if (args[i].startsWith('--'))
+            continue;
+        out.push(args[i]);
+    }
+    return out.length ? out.join(' ') : undefined;
+}

package/dist/commands/inbox-drain.js

@@ -9,7 +9,13 @@
  *  inbox`. This closes it: on every arm (SessionStart startup|resume|compact)
  *  drain THIS session's unread, session-DIRECTED messages into the agent's
  *  context, tagged peer/human, mark them read, and advance the stored cursor so
- *  there is no double-delivery. adr: adr/monitor-resilience.md
+ *  there is no double-delivery.
+ *
+ *  INJECT ONLY WHEN UNARMED. A live watcher already printed the body (Claude
+ *  Monitor / Grok monitor stdout). Grok also wires drain on Stop because
+ *  SessionStart stdout cannot inject — that Stop path is the unarmed floor.
+ *  Passing `armed: true` still marks inbound unread + advances the cursor, but
+ *  does not inject (and never claims "no live watcher"). adr: adr/monitor-resilience.md
  *
  *  SCOPE = session-directed INBOUND only (to_session_id == me). NOT the front
  *  desk (cold opens + email — that's the human-scoped `mail` hook's job) and NOT
@@ -126,7 +132,31 @@ async function runInboxDrain(opts) {
         return none;
     // Chronological (oldest → newest) so a coordination thread reads in order.
     inbound.sort((a, b) => tsOf(a) - tsOf(b));
-    // 3. Cap the injected volume to the NEWEST `cap`. Older inbound-unread stay
+    // 3. Armed watcher already delivered the body (live stdout). Mark every
+    //    inbound-unread read and advance the cursor, but do not inject — the
+    //    unarmed copy would lie, and Grok Stop would duplicate a live interrupt.
+    const cursor = newestId(messages);
+    if (opts.armed) {
+        if (cursor) {
+            try {
+                writeCursor(opts.session, cursor);
+            }
+            catch { /* best-effort */ }
+        }
+        const ids = inbound.map(m => m.id).filter(Boolean);
+        if (ids.length > 0) {
+            try {
+                await doFetch(`${base}/v1/inbox/read`, {
+                    method: 'POST',
+                    headers: { Authorization: `Bearer ${opts.apiKey}`, 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ ids }),
+                });
+            }
+            catch { /* mark-read is best-effort */ }
+        }
+        return { context: null, drained: inbound.length, truncated: 0, cursorAdvancedTo: cursor };
+    }
+    // 4. Cap the injected volume to the NEWEST `cap`. Older inbound-unread stay
     //    unread (NOT marked, NOT silently dropped): they remain in `greprag inbox`
     //    and the next arm re-drains them. The overflow count is stated below.
     let drain = inbound;
@@ -135,20 +165,20 @@ async function runInboxDrain(opts) {
         truncated = inbound.length - cap;
         drain = inbound.slice(inbound.length - cap); // newest `cap`, still chronological
     }
-    // 4. Build the injected context (peer/human tagged).
+    // 5. Build the injected context (peer/human tagged). Unarmed-only — this copy
+    //    is true because we returned above when a live watcher was present.
     const context = buildDrainContext(drain, truncated, opts.session);
-    // 5. Advance the poll cursor to the newest endpoint message id so the just-
+    // 6. Advance the poll cursor to the newest endpoint message id so the just-
     //    armed poll resumes strictly AFTER everything already in the inbox — no
     //    double-delivery. Only when there is something to drain (never disturb a
     //    healthy poll's cursor on an empty arm).
-    const cursor = newestId(messages);
     if (cursor) {
         try {
             writeCursor(opts.session, cursor);
         }
         catch { /* best-effort */ }
     }
-    // 6. Mark the drained (injected) ids read LAST — after inject + cursor — so a
+    // 7. Mark the drained (injected) ids read LAST — after inject + cursor — so a
     //    crash before this point re-drains next arm rather than losing a message.
     //    Inbound ids only, so a peer's view of my outbound is never touched.
     //    Fail-quiet: an unreachable / not-yet-deployed /read route leaves the

package/dist/commands/inbox-primer-reminder.js

@@ -48,7 +48,7 @@ function buildInboxPrimer(env) {
                     ? '[OPENCODE INBOX — 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.]'
                     : '[⚠ ARM YOUR INBOX WATCHER NOW — you are UNREACHABLE until you do. Peers are live in your mesh trying to coordinate with this session, and the operator can DM you — 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) — 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 — 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\`.`
+            ? `ARM (idle wake): Grok \`monitor\` tool, persistent:true, description:"greprag inbox ${env.short}", command: \`${arm}\`. \`--quiet\` is REQUIRED — Grok treats stderr as wake events; the Claude bash wrapper is PowerShell-invalid. Use full UUID / 16-hex, never 8-hex. A chip → \`greprag load grok-chip-spawn\` then \`greprag grok spawn\` (child arms its own watch; parent keeps ONE). A helper → 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

package/dist/commands/inbox-watch.js

@@ -50,6 +50,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CONSUMER_GONE_EXIT_CODE = void 0;
+exports.resolveWatchPlatform = resolveWatchPlatform;
 exports.getConfig = getConfig;
 exports.fmtDuration = fmtDuration;
 exports.parseEventBlock = parseEventBlock;
@@ -59,6 +60,7 @@ exports.runInboxWatch = runInboxWatch;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const session_id_1 = require("../session-id");
+const harness_1 = require("../harness");
 const mechanic_friction_1 = require("../mechanic-friction");
 const inbox_watch_supervisor_1 = require("./inbox-watch-supervisor");
 const API_URL_DEFAULT = 'https://api.greprag.com';
@@ -84,6 +86,14 @@ exports.CONSUMER_GONE_EXIT_CODE = 65;
 // than waiting for the next real message that may never come. Env-overridable
 // for tests (the idle path otherwise takes the full 30s to observe).
 const CONSUMER_PROBE_MS = Number(process.env.GREPRAG_WATCH_PROBE_MS) || 30_000;
+const WATCH_PLATFORMS = new Set(['claude-code', 'codex', 'opencode', 'grok']);
+/** Platform tag for this watch attach. Explicit opt wins; else infer. */
+function resolveWatchPlatform(explicit) {
+    if (explicit && WATCH_PLATFORMS.has(explicit))
+        return explicit;
+    const h = (0, harness_1.inferCurrentHarness)();
+    return (h && WATCH_PLATFORMS.has(h)) ? h : undefined;
+}
 // -- Config (mirrors the loader in index.ts/discover.ts) -------------------
 function loadEnvFile(filePath) {
     try {
@@ -392,7 +402,7 @@ async function readStream(url, apiKey, signal, initialId, json, idleTimeoutMs, s
         signal.removeEventListener('abort', onOuterAbort);
     }
 }
-function buildUrl(apiUrl, project, session, since, receptionist, assistant, mechanic) {
+function buildUrl(apiUrl, project, session, since, receptionist, assistant, mechanic, platform) {
     const u = new URL(apiUrl.replace(/\/+$/, '') + '/v1/inbox/stream');
     if (project)
         u.searchParams.set('project', project);
@@ -406,6 +416,8 @@ function buildUrl(apiUrl, project, session, since, receptionist, assistant, mech
         u.searchParams.set('role', 'mechanic');
     else if (assistant)
         u.searchParams.set('role', 'assistant');
+    if (platform)
+        u.searchParams.set('platform', platform);
     return u.toString();
 }
 /** Public entry for `greprag inbox watch`. Dispatches by mode:
@@ -545,7 +557,7 @@ async function runWatchLoop(opts) {
             watchErr(`${LOG_PREFIX} reconnecting (last_seen_id=${lastSeen})`, opts);
         }
         isFirstAttempt = false;
-        const url = buildUrl(cfg.apiUrl, opts.project, opts.session, cursor, !!opts.receptionist, !!opts.assistant, !!opts.mechanic);
+        const url = buildUrl(cfg.apiUrl, opts.project, opts.session, cursor, !!opts.receptionist, !!opts.assistant, !!opts.mechanic, resolveWatchPlatform(opts.platform));
         try {
             const lastId = await readStream(url, cfg.apiKey, controller.signal, cursor, !!opts.json, idleTimeoutMs, opts.session);
             if (lastId)

package/dist/commands/init.js

@@ -668,9 +668,10 @@ Before other work this session:
    \`greprag inbox watch --session $GROK_SESSION_ID --json --quiet\`
    Not Claude Monitor. No bash while-true. \`--quiet\` required (stderr is a wake).
    If a greprag inbox monitor is already listed in this session, do not start another. Instant exit = already armed, not a crash.
-4. Second session: \`spawn_subagent\` background=true. Child arms its own quiet watch with ITS \`$GROK_SESSION_ID\`. Parent sends:
+4. Chip: \`greprag load grok-chip-spawn\` then \`greprag grok spawn\` (real TUI + inbox). Helper: \`spawn_subagent\` background=true. Child arms its own quiet watch with ITS \`$GROK_SESSION_ID\`. Parent sends:
    \`greprag send "…" --to travis@greprag.com/<child-full-uuid> --from-session $GROK_SESSION_ID\`
    Parent keeps ONE watch, for itself. Child watch events may appear on the parent TUI — resume the child to act. Do not arm a second parent watch.
+5. Tool shell: stdin redirected + \`-NonInteractive\`. \`Read-Host\` throws. \`Start-Process\` windows die with the tool Job Object. Secret paste: \`~/.claude/scripts/prompt-secret.ps1\`. Sticky console: \`schtasks /Create … /IT\` then \`schtasks /Run\`. npm Hello: \`npm login --auth-type=web\` in that window; browser Use security key; page token ≠ Hello PIN.
 `;
 function getGrokHooksPath() {
     const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
@@ -691,6 +692,15 @@ function applyGrokHooks(config) {
     const changes = [];
     if (!config.hooks)
         config.hooks = {};
+    // Empty matcher = every SessionStart source (startup, resume, /new, dashboard
+    // dispatch, fork). `startup|resume` missed /new and dashboard agents, so this
+    // session never got a recap sidecar. adr: adr/grok-platform.md
+    const sessionStartMatcher = '';
+    if (!config.hooks.SessionStart)
+        config.hooks.SessionStart = [];
+    const retargeted = ['recap', 'session-id', 'drain'].reduce((n, sub) => (n + retargetGrepragHookMatcher(config.hooks.SessionStart, sub, ['startup|resume'], sessionStartMatcher)), 0);
+    if (retargeted)
+        changes.push(`Retargeted Grok SessionStart matcher (${retargeted})`);
     const add = (event, matcher, sub, timeout, label) => {
         if (hasGrepragHook(config.hooks[event], sub)) {
             changes.push(`Grok ${event} ${label} already configured (skipped)`);
@@ -701,9 +711,9 @@ function applyGrokHooks(config) {
         config.hooks[event].push({ matcher, hooks: [grokCommand(sub, timeout)] });
         changes.push(`Added Grok ${event} hook (${label})`);
     };
-    add('SessionStart', 'startup|resume', 'recap', 15, 'memory recap');
-    add('SessionStart', 'startup|resume', 'session-id', 5, 'session-id');
-    add('SessionStart', 'startup|resume', 'drain', 8, 'inbox drain');
+    add('SessionStart', sessionStartMatcher, 'recap', 15, 'memory recap');
+    add('SessionStart', sessionStartMatcher, 'session-id', 5, 'session-id');
+    add('SessionStart', sessionStartMatcher, 'drain', 8, 'inbox drain');
     add('UserPromptSubmit', '', 'notify', 8, 'prompt cache');
     add('PreToolUse', 'Bash|run_terminal_command', 'crush-wrap', 5, 'crush-wrap');
     add('PreToolUse', '*', 'guard', 5, 'guard');
@@ -797,7 +807,7 @@ async function runGrokInit(opts) {
     console.log('  Reload hooks in Grok (/hooks then r) or start a fresh session.');
     console.log('  Recap lands in ~/.greprag/grok-context/<16-hex>.md — Grok ignores SessionStart stdout.');
     console.log('  Idle inbox: Grok monitor + `greprag inbox watch --session $GROK_SESSION_ID --json --quiet`.');
-    console.log('  Second session: spawn_subagent; child arms its own watch; parent keeps one.\n');
+    console.log('  Second session: `greprag grok spawn` (TUI) or spawn_subagent; child arms its own watch; parent keeps one.\n');
 }
 /** greprag init --global
  *  Creates ~/.greprag/project.json with a stable UUID.

package/dist/commands/load-primer-reminder.js

@@ -19,7 +19,7 @@
  *  load-primer` / `chip-spawn-pointer`). Announce-only: detect → silent,
  *  reminder → null. adr: docs/load-system.md, docs/reminder-interrupt.md */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.codexChipSpawnPointerModule = exports.chipSpawnPointerModule = exports.loadPrimerModule = exports.CODEX_CHIP_SPAWN_POINTER = exports.OPENCODE_CHIP_SPAWN_POINTER = exports.CHIP_SPAWN_POINTER = exports.LOAD_PRIMER = void 0;
+exports.codexChipSpawnPointerModule = exports.chipSpawnPointerModule = exports.loadPrimerModule = exports.CODEX_CHIP_SPAWN_POINTER = exports.GROK_CHIP_SPAWN_POINTER = exports.OPENCODE_CHIP_SPAWN_POINTER = exports.CHIP_SPAWN_POINTER = exports.LOAD_PRIMER = void 0;
 /** PRIMER — teaches the loader itself. Resident (fires every SessionStart +
  *  re-teaches after compaction). Terse: it is in context every session. */
 exports.LOAD_PRIMER = [
@@ -43,6 +43,11 @@ exports.OPENCODE_CHIP_SPAWN_POINTER = [
     '[greprag chips — agent coordination is built in (messaging plumbing in the inbox primer).]',
     '• Delegating a component of a plan to an isolated chip session, or `greprag fix spawn` just printed a FIX-chip mission? → 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). ≥2 chips at one objective → `greprag load chip-leader-opencode` BEFORE the first spawn.',
 ].join('\n');
+/** POINTER — Grok Build TUI chip. Real window + inbox mesh, not spawn_subagent. */
+exports.GROK_CHIP_SPAWN_POINTER = [
+    '[greprag chips — agent coordination is built in (messaging plumbing in the inbox primer).]',
+    '• About to spawn a chip? → 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. ≥2 chips at one objective → `greprag load chip-leader` BEFORE the first spawn.',
+].join('\n');
 /** POINTER — Codex Desktop's native chip path. This is intentionally distinct
  *  from Claude Code spawn_task: different lifecycle, runtime, and handoff. */
 exports.CODEX_CHIP_SPAWN_POINTER = [
@@ -70,6 +75,8 @@ exports.chipSpawnPointerModule = {
             return null;
         if (env.platform === 'opencode')
             return exports.OPENCODE_CHIP_SPAWN_POINTER;
+        if (env.platform === 'grok')
+            return exports.GROK_CHIP_SPAWN_POINTER;
         return exports.CHIP_SPAWN_POINTER;
     },
     reminder: () => null,

package/dist/commands/load.js

@@ -73,6 +73,10 @@ const LIBRARY = {
         files: ['skill/templates/codex-chip-spawn.md'],
         purpose: 'Spawn an independent writable native Codex Desktop task with an isolated worktree and native completion/cleanup.',
     },
+    'grok-chip-spawn': {
+        files: ['skill/templates/grok-chip-spawn.md'],
+        purpose: 'Spawn a Grok TUI chip (cmd /k bootloader + isolated worktree). Child arms its own inbox watch; parent talks via greprag send. Not spawn_subagent.',
+    },
     'skill-change': {
         files: ['skill/templates/skill-change.md'],
         purpose: 'Internal bundled schema for safely updating a skill after a run: when to edit, Convention A/B shapes, and when to propose instead.',

package/dist/commands/os-primer-reminder.js

@@ -20,7 +20,8 @@ function buildOsPrimer(env) {
     // vehicle is the chip-bootloader entry: native `greprag opencode chip` spawn).
     const spawnEntry = env?.platform === 'codex' ? 'codex-chip-spawn'
         : env?.platform === 'opencode' ? 'chip-bootloader'
-            : 'chip-spawn';
+            : env?.platform === 'grok' ? 'grok-chip-spawn'
+                : 'chip-spawn';
     return [
         '[grepragOS — the operating laws. Full doctrine: `greprag load os`.]',
         '• 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 — read these first" block naming exact paths.',

package/dist/commands/status.js

@@ -267,7 +267,7 @@ function buildStatus(cwd, platform = 'all') {
                 skill_path: grokSkillPath,
                 skill_installed: fs.existsSync(grokSkillPath),
                 hooks: grokHookStatus,
-                note: 'Grok recap is a sidecar + ~/.grok/rules (SessionStart stdout is ignored). Idle inbox: Grok monitor + quiet watch. Stop drain injects unread mail.',
+                note: 'Grok recap is a sidecar + ~/.grok/rules (SessionStart stdout is ignored). Idle inbox: Grok monitor + quiet watch. Stop drain injects unread mail only when unarmed.',
             },
         },
         project: {

package/dist/hook.js

@@ -1334,7 +1334,7 @@ function grokSidecarHead(short, full) {
     return (0, session_id_1.buildSessionIdContext)(short, (0, session_id_1.readIdentityAlias)())
         + `\n\nARM (Grok monitor persistent:true): \`${arm}\`\n`
         + `Send with --from-session ${full || short} (full UUID or 16-hex, never 8-hex).\n`
-        + 'Second session: spawn_subagent background=true; child arms its own quiet watch; parent keeps ONE watch.\n'
+        + 'Chip: `greprag load grok-chip-spawn` then `greprag grok spawn`. Helper: spawn_subagent. Parent keeps ONE watch. Peers: `greprag inbox watchers` then `greprag send`.\n'
         + 'If a greprag inbox monitor is already listed, do not start another. Instant exit = already armed.\n\n';
 }
 function writeRecapOutput(text, mode, grokShort, grokFull) {
@@ -2023,7 +2023,9 @@ async function collisionCheck(input) {
  *  poll live-tails with no double-delivery. Closes the dead-window gap where a
  *  session-directed message that lands between watcher death and re-arm sits
  *  unread until a manual `greprag inbox`. Inbound-only — the front desk (cold
- *  opens + email) stays with the human-scoped `mail` hook. All real logic lives
+ *  opens + email) stays with the human-scoped `mail` hook. Injects only when
+ *  unarmed (`isLocallyArmed`); a live watcher already delivered the body.
+ *  Grok also wires this on Stop as the unarmed floor. All real logic lives
  *  in ./commands/inbox-drain (pure + tested). Best-effort: any miss → silent,
  *  never blocks SessionStart. adr: adr/monitor-resilience.md */
 async function drain(input) {
@@ -2034,7 +2036,10 @@ async function drain(input) {
     const short = (0, session_id_1.truncateSessionId)(input.session_id);
     if (!short)
         return; // no session id → silent
-    const result = await (0, inbox_drain_1.runInboxDrain)({ session: short, apiUrl: cfg.apiUrl, apiKey: cfg.apiKey });
+    const result = await (0, inbox_drain_1.runInboxDrain)({
+        session: short, apiUrl: cfg.apiUrl, apiKey: cfg.apiKey,
+        armed: (0, watcher_registry_1.isLocallyArmed)(short),
+    });
     if (result.context) {
         (0, hook_runtime_1.writeAdditionalContext)(input.hook_event_name || 'SessionStart', result.context);
         if ((0, harness_1.inferCurrentHarness)() === 'grok')
@@ -2417,10 +2422,11 @@ async function main() {
         // best-effort state stash. docs/ingress-trigger-bridge.md
         await store(input, harness === 'grok' ? 'grok' : 'claude-code');
         if (harness === 'grok') {
-            // Floor: inject unread mail. Do NOT nag UNARMED here — Grok Stop
-            // fires every turn, and a pidfile-alias miss made that a re-arm loop
-            // (watch already live → singleton-guard exits instantly → model arms
-            // again). Arm teaching is sidecar + rules. adr: adr/grok-platform.md
+            // Floor: inject unread mail only when unarmed. Do NOT nag UNARMED here —
+            // Grok Stop fires every turn, and a pidfile-alias miss made that a
+            // re-arm loop (watch already live → singleton-guard exits instantly →
+            // model arms again). Arm teaching is sidecar + rules.
+            // adr: adr/grok-platform.md
             await drain(input);
         }
         stateUpdate(input);

package/dist/index.js

@@ -43,6 +43,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
 const init_1 = require("./commands/init");
 const status_1 = require("./commands/status");
 const doctor_1 = require("./commands/doctor");
@@ -77,6 +78,7 @@ const crush_1 = require("./commands/crush");
 const crush_stats_1 = require("./commands/crush-stats");
 const archive_1 = require("./commands/archive");
 const inbox_watch_1 = require("./commands/inbox-watch");
+const grok_spawn_1 = require("./commands/grok-spawn");
 const inbox_attachments_1 = require("./inbox-attachments");
 const discord_1 = require("./commands/discord");
 const project_anchor_1 = require("./project-anchor");
@@ -272,6 +274,23 @@ undici error, OS kill); and it SELF-TERMINATES when its Monitor consumer's pipe
 breaks (session reload/end) so it never orphans. Within-session robustness only;
 a watcher cannot survive session reload / --resume / /compact.
 adr: adr/monitor-resilience.md`;
+function readProjectRegistry() {
+    try {
+        const file = path.join(os.homedir(), '.greprag', 'projects.json');
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return {};
+        const out = {};
+        for (const [k, v] of Object.entries(parsed)) {
+            if (typeof v === 'string' && v)
+                out[k] = v;
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
 /** greprag inbox [--all] [--session <id>] | inbox keep <id> | inbox delete <id> | inbox watch */
 /** greprag desk — the machine's desk-line (reverse-RPC relay to the cloud).
  *    desk run      hold the line open and answer cloud questions (long-running)
@@ -405,8 +424,13 @@ async function inbox(args) {
         }
         const res = await apiGet(`${cfg.apiUrl}/v1/inbox/watchers`, cfg.apiKey);
         const watchers = (res.watchers || []);
+        const repos = readProjectRegistry();
+        const decorated = watchers.map(w => ({
+            ...w,
+            repo: w.repo || (w.project_name && repos[w.project_name]) || null,
+        }));
         if (json) {
-            console.log(JSON.stringify({ watchers }, null, 2));
+            console.log(JSON.stringify({ watchers: decorated }, null, 2));
             return;
         }
         if (watchers.length === 0) {
@@ -415,13 +439,17 @@ async function inbox(args) {
         }
         console.log(`${watchers.length} live watcher(s):\n`);
         // Label = project · title — both resolved from the session's memory (the
-        // auto-armed watcher carries neither on its WS tag). The 8-hex session id
+        // auto-armed watcher carries neither on its WS tag). The session short
         // rides in parens; orchestrator mode reads it back to address sends.
-        for (const w of watchers) {
+        // Platform + local repo path (from ~/.greprag/projects.json) say which
+        // harness armed it and which checkout it's in.
+        for (const w of decorated) {
             const proj = w.project_name ? w.project_name : (w.wide ? '(tenant-wide)' : '(no project)');
             const label = w.title ? `${proj} · ${w.title}` : proj;
             const sess = w.session_id ? `  (${w.session_id})` : '';
-            console.log(`  ${label}${sess}`);
+            const plat = w.platform ? `  [${w.platform}]` : '';
+            const repo = w.repo ? `  ${w.repo}` : '';
+            console.log(`  ${label}${sess}${plat}${repo}`);
         }
         return;
     }
@@ -666,7 +694,7 @@ function parseFileFlag(raw) {
  *  is a session id; anything else is a project name. Project names that
  *  look like UUIDs are rejected at registration time so this is unambiguous.
  *  adr: adr/session-id-awareness.md, adr/address-grammar.md */
-const SESSION_ID_PATTERN = /^([0-9a-f]{8}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i;
+const SESSION_ID_PATTERN = /^([0-9a-f]{8}|[0-9a-f]{16}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i;
 /** Parse a send address under the v0.12 grammar:
  *    <handle>@greprag.com[/<target>]
  *  where <target> is exactly one segment — a session UUID (or 8-hex short form)
@@ -719,7 +747,7 @@ function parseSendAddress(addr) {
     if (!target) {
         return { ok: false, error: `address "${addr}" has an empty target segment.` };
     }
-    const kind = SESSION_ID_PATTERN.test(target) ? 'session' : 'project';
+    const kind = ((0, session_id_1.isSessionAddressTarget)(target) || SESSION_ID_PATTERN.test(target)) ? 'session' : 'project';
     return { ok: true, targetKind: kind, target };
 }
 /** Internal (self-desk) message types — KEEP IN SYNC with
@@ -1267,6 +1295,10 @@ Commands:
                                   Configure lifecycle hooks + anchor for Codex
   init --grok [--api-key <key>] [--tenant-id <handle>]
                                   Configure Grok Build hooks + skill + rules
+  grok spawn [--cwd <path>] [--prompt "<text>"]
+                                  Open a fresh Grok TUI in a new terminal
+                                  (Windows schtasks bootloader — survives the
+                                  tool Job Object; child arms its own watch)
   init --all [--root <path>]       Standard init for cwd, then bulk-register every
                                    other git repo at depth 1 under <path> (default:
                                    parent of repo root). Each becomes inbox-addressable.
@@ -1306,11 +1338,12 @@ Inbox (email-style messaging across tenants):
                                 --session scopes to one specific session's view.
                                 --project filters by project name.
                                 --peek: NON-MUTATING — does not mark any message read.
-  inbox watchers [--json]       List currently-attached live GrepRAG/Claude/OpenCode
-                                watchers under this tenant. Each row: project ·
-                                title (session_id) — project + nano title resolved
-                                from session memory. Codex task and repo/workspace
-                                discovery uses codex_app.list_threads.
+  inbox watchers [--json]       List currently-attached live watchers
+                                (Claude / Codex / OpenCode / Grok). Each row:
+                                project · title (session_id) [platform] repo —
+                                project + nano title from session memory, repo
+                                from ~/.greprag/projects.json. Codex task
+                                discovery also uses codex_app.list_threads.
   inbox watch                   Long-lived SSE stream — prints each message as it lands.
                                 Self-supervising by default: a parent process
                                 respawns the SSE loop (via CreateProcess) on any
@@ -1895,6 +1928,7 @@ async function main() {
         case 'loadout': return (0, loadout_1.runLoadout)(subArgs); // Loadout: cross-tenant skill-bundle gifting (docs/loadout.md)
         case 'assistant': return (0, assistant_1.runAssistant)(subArgs); // designate this project as the tenant's Assistant (role flag)
         case 'opencode': return opencode(subArgs);
+        case 'grok': return (0, grok_spawn_1.runGrok)(subArgs);
         default:
             console.error(`Unknown command: ${command}\n`);
             console.log(HELP);

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

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.76.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`.