claude-flow 3.58.1 → 3.59.1

package/.claude/proven-config.json

@@ -1,5 +1,5 @@
 {
-  "adoptedAt": 1792482576260,
+  "adoptedAt": 1792516520191,
   "championId": "sha256:6141a8ea990c5063b77e090ae8f37f9c539d8aa8f58dcceb30f3a82f97e57319",
   "manifest": {
     "schema": "ruflo.proven-config/v1",

package/README.md

@@ -118,6 +118,8 @@ User → Ruflo (CLI/MCP) → Router → Swarm → Agents → Memory → LLM prov
 
 A harness is the workbench around the model: it organizes tasks, carries context between steps and helps check results. **This establishes Ruflo's lineage, not a universal first across every Claude Code tool.** [See the illustrated explainer, exact commits and earlier ecosystem context](docs/harness-origins.md).
 
+**Grok Build:** `npx ruflo init --grok` writes the project host surface (`.grok/`, the team bus, and the operator guide) and nothing outside the project; add `--dry-run` to preview. Setup, the `spawn_subagent` contract, the optional status row, and what to re-check when Grok updates: [the Grok operator guide](v3/@claude-flow/cli/templates/grok/docs/README.md).
+
 <details>
 <summary><strong>📖 Background — where the name comes from</strong></summary>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.58.1",
+  "version": "3.59.1",
   "workspaces": [
     "v3/@claude-flow/codex",
     "v3/@claude-flow/mcp",
@@ -30,6 +30,7 @@
     "!v3/@claude-flow/cli/dist/**/*.map",
     "v3/@claude-flow/cli/package.json",
     "v3/@claude-flow/cli/catalog-manifest.json",
+    "v3/@claude-flow/cli/templates/**",
     "v3/@claude-flow/shared/dist/**/*.js",
     "v3/@claude-flow/shared/dist/**/*.d.ts",
     "!v3/@claude-flow/shared/dist/**/*.map",

package/v3/@claude-flow/cli/README.md

@@ -118,6 +118,8 @@ User → Ruflo (CLI/MCP) → Router → Swarm → Agents → Memory → LLM prov
 
 A harness is the workbench around the model: it organizes tasks, carries context between steps and helps check results. **This establishes Ruflo's lineage, not a universal first across every Claude Code tool.** [See the illustrated explainer, exact commits and earlier ecosystem context](docs/harness-origins.md).
 
+**Grok Build:** `npx ruflo init --grok` writes the project host surface (`.grok/`, the team bus, and the operator guide) and nothing outside the project; add `--dry-run` to preview. Setup, the `spawn_subagent` contract, the optional status row, and what to re-check when Grok updates: [the Grok operator guide](v3/@claude-flow/cli/templates/grok/docs/README.md).
+
 <details>
 <summary><strong>📖 Background — where the name comes from</strong></summary>
 

package/v3/@claude-flow/cli/bin/cli.js

@@ -161,7 +161,25 @@ const isMCPMode = !process.stdin.isTTY
   && !explicitNonStdioTransport
   && (process.argv.length === 2 || isExplicitMCP);
 
-if (isMCPMode) {
+// `harness` observes the running system (it is the SessionStart hook), so it
+// skips normal CLI startup entirely: no daemon autostart, update check, policy
+// migration or config adoption, and no heavy imports. With --hook it fails
+// silently (no stack on stderr) so a missing dist/ can't disturb a session.
+const isHarness = cliArgs[0] === 'harness' && !cliArgs.includes('--help') && !cliArgs.includes('-h');
+
+if (isHarness) {
+  const hook = cliArgs.includes('--hook');
+  try {
+    const { runHarnessCli } = await import('../dist/src/commands/harness.js');
+    process.exitCode = runHarnessCli(cliArgs.slice(1));
+  } catch (error) {
+    if (!hook) {
+      const missing = error && error.code === 'ERR_MODULE_NOT_FOUND';
+      console.error(`ruflo harness: ${missing ? 'the CLI is not built (dist/ is missing)' : (error && error.message) || error}`);
+    }
+    process.exitCode = hook ? 0 : 1;
+  }
+} else if (isMCPMode) {
   // Run MCP server mode
   const { listMCPTools, callMCPTool, hasTool } = await import('../dist/src/mcp-client.js');
   const { isPolicyEnforcementEnabled, loadMcpPolicy, evaluateToolCall } =

package/v3/@claude-flow/cli/catalog-manifest.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "generation": 7,
-  "generatedAt": "2026-10-20T07:55:51.186Z",
-  "gitSha": "f5f2e40c",
+  "generatedAt": "2026-10-20T17:15:56.251Z",
+  "gitSha": "9271be48",
   "catalog": {
     "agents": 176,
-    "tools": 423,
+    "tools": 432,
     "skills": 34
   },
   "benchmark": null

package/v3/@claude-flow/cli/dist/src/commands/harness.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Live harness status.
+ *
+ * This is not `doctor` and not `status`. Those describe install health or
+ * call tool handlers inside this process. `harness` reports what is already
+ * running for this working tree: the host session, a live daemon pid, ruflo
+ * MCP servers whose cwd is this tree, processes holding the memory databases
+ * open, and teams that are still active.
+ *
+ *   ruflo harness
+ *   ruflo harness --json
+ *   ruflo harness --hook               # SessionStart payload for Codex (and Claude)
+ *   ruflo harness --print-codex-hook   # opt-in .codex/hooks.json for this install
+ *
+ * `harness` is observe-only: bin/cli.js runs it through `runHarnessCli`
+ * before the normal CLI starts, so no daemon autostart, update check, policy
+ * migration or config adoption runs, and nothing is written to disk. The CLI
+ * class also exempts it from those side effects (see OBSERVE_ONLY_COMMANDS).
+ */
+import type { Command } from '../types.js';
+import { type LiveHarness } from '../services/live-harness.js';
+export type { LiveHarness } from '../services/live-harness.js';
+export { collectLiveHarness } from '../services/live-harness.js';
+/** This install's bin/cli.js, from dist/src/commands/harness.js (or src/commands). */
+export declare function installedCliPath(moduleUrl?: string): string;
+/**
+ * A .codex/hooks.json that runs this install's harness on SessionStart. The
+ * path is absolute, so the hook does not depend on the session's git root.
+ * Autostart and the update check are off, and failures stay silent.
+ */
+export declare function codexHookConfig(cliPath?: string): string;
+/**
+ * Entry used by bin/cli.js before the CLI class loads. Returns the exit code.
+ * With --hook it never fails: on any error it prints nothing and returns 0,
+ * so a SessionStart hook can't break a session.
+ */
+export declare function runHarnessCli(argv: string[], write?: (text: string) => void, collect?: () => LiveHarness): number;
+export declare const harnessCommand: Command;
+export default harnessCommand;
+//# sourceMappingURL=harness.d.ts.map

package/v3/@claude-flow/cli/dist/src/commands/harness.js

@@ -0,0 +1,142 @@
+/**
+ * Live harness status.
+ *
+ * This is not `doctor` and not `status`. Those describe install health or
+ * call tool handlers inside this process. `harness` reports what is already
+ * running for this working tree: the host session, a live daemon pid, ruflo
+ * MCP servers whose cwd is this tree, processes holding the memory databases
+ * open, and teams that are still active.
+ *
+ *   ruflo harness
+ *   ruflo harness --json
+ *   ruflo harness --hook               # SessionStart payload for Codex (and Claude)
+ *   ruflo harness --print-codex-hook   # opt-in .codex/hooks.json for this install
+ *
+ * `harness` is observe-only: bin/cli.js runs it through `runHarnessCli`
+ * before the normal CLI starts, so no daemon autostart, update check, policy
+ * migration or config adoption runs, and nothing is written to disk. The CLI
+ * class also exempts it from those side effects (see OBSERVE_ONLY_COMMANDS).
+ */
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { collectLiveHarness } from '../services/live-harness.js';
+export { collectLiveHarness } from '../services/live-harness.js';
+function renderText(report) {
+    const out = [report.line];
+    if (Object.keys(report.session).length) {
+        out.push(`session ${Object.entries(report.session).map(([k, v]) => `${k}=${v}`).join(' ')}`);
+    }
+    for (const server of report.mcp.servers)
+        out.push(`mcp ${server.pid} ${server.command}`);
+    if (report.memory.openPids?.length)
+        out.push(`memory held by ${report.memory.openPids.join(',')}`);
+    for (const team of report.teams)
+        out.push(`team ${team.name} ${team.status} members=${team.members}`);
+    if (report.staleTeams.length)
+        out.push(`stale teams (no activity, not shut down) ${report.staleTeams.join(',')}`);
+    return out.join('\n') + '\n';
+}
+function renderHook(report) {
+    return JSON.stringify({
+        hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: report.line },
+    }) + '\n';
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** This install's bin/cli.js, from dist/src/commands/harness.js (or src/commands). */
+export function installedCliPath(moduleUrl = import.meta.url) {
+    return join(dirname(fileURLToPath(moduleUrl)), '..', '..', '..', 'bin', 'cli.js');
+}
+/**
+ * A .codex/hooks.json that runs this install's harness on SessionStart. The
+ * path is absolute, so the hook does not depend on the session's git root.
+ * Autostart and the update check are off, and failures stay silent.
+ */
+export function codexHookConfig(cliPath = installedCliPath()) {
+    const command = `RUFLO_DAEMON_AUTOSTART=0 node ${shellQuote(cliPath)} harness --hook --no-update 2>/dev/null || true`;
+    return JSON.stringify({
+        hooks: {
+            SessionStart: [
+                {
+                    matcher: 'startup|resume|clear|compact|fork',
+                    hooks: [{ type: 'command', command, timeout: 8 }],
+                },
+            ],
+        },
+    }, null, 2) + '\n';
+}
+function render(mode, collect) {
+    if (mode === 'codex-hook')
+        return { text: codexHookConfig() };
+    const report = collect();
+    if (mode === 'hook')
+        return { text: renderHook(report), report };
+    if (mode === 'json')
+        return { text: JSON.stringify(report, null, 2) + '\n', report };
+    return { text: renderText(report), report };
+}
+function modeOf(flags) {
+    if (flags.printCodexHook)
+        return 'codex-hook';
+    if (flags.hook)
+        return 'hook';
+    if (flags.json)
+        return 'json';
+    return 'text';
+}
+/**
+ * Entry used by bin/cli.js before the CLI class loads. Returns the exit code.
+ * With --hook it never fails: on any error it prints nothing and returns 0,
+ * so a SessionStart hook can't break a session.
+ */
+export function runHarnessCli(argv, write = (text) => { process.stdout.write(text); }, collect = () => collectLiveHarness()) {
+    const mode = modeOf({
+        hook: argv.includes('--hook'),
+        json: argv.includes('--json'),
+        printCodexHook: argv.includes('--print-codex-hook'),
+    });
+    try {
+        write(render(mode, collect).text);
+        return 0;
+    }
+    catch (error) {
+        if (mode === 'hook')
+            return 0;
+        process.stderr.write(`ruflo harness: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
+export const harnessCommand = {
+    name: 'harness',
+    description: 'Show the running harness for this tree (live pids and open state, not install config)',
+    options: [
+        { name: 'json', description: 'Print the live report as JSON', type: 'boolean', default: false },
+        {
+            name: 'hook',
+            description: 'Print a SessionStart additionalContext payload for Codex or Claude',
+            type: 'boolean',
+            default: false,
+        },
+        {
+            name: 'print-codex-hook',
+            description: 'Print an opt-in .codex/hooks.json that runs this install on SessionStart',
+            type: 'boolean',
+            default: false,
+        },
+    ],
+    examples: [
+        { command: 'ruflo harness', description: 'One line plus any live mcp, memory holders, and teams' },
+        { command: 'ruflo harness --json', description: 'Machine-readable live report' },
+        { command: 'ruflo harness --hook', description: 'SessionStart payload' },
+        { command: 'ruflo harness --print-codex-hook > .codex/hooks.json', description: 'Opt in to the Codex SessionStart hook' },
+    ],
+    action: async (ctx) => {
+        const mode = modeOf(ctx.flags);
+        const { text, report } = render(mode, () => collectLiveHarness());
+        process.stdout.write(text);
+        return { success: true, data: report };
+    },
+};
+export default harnessCommand;
+//# sourceMappingURL=harness.js.map

package/v3/@claude-flow/cli/dist/src/commands/index.js

@@ -45,6 +45,7 @@ const commandLoaders = {
     // P0 Commands
     completions: () => import('./completions.js'),
     doctor: () => import('./doctor.js'),
+    harness: () => import('./harness.js'),
     // Verification (ADR-095, signed witness manifest)
     verify: () => import('./verify.js'),
     // Analysis Commands

package/v3/@claude-flow/cli/dist/src/commands/init.js

@@ -8,6 +8,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { spawnSync } from 'node:child_process';
 import { executeInit, executeUpgrade, executeUpgradeWithMissing, DEFAULT_INIT_OPTIONS, MINIMAL_INIT_OPTIONS, FULL_INIT_OPTIONS, } from '../init/index.js';
+import { executeGrokInit } from '../init/grok-generator.js';
 import { ENROLLMENT_SCREEN, recordEnrollmentOutcome, shouldOfferEnrollment, } from '../funnel/enrollment.js';
 import { commandExists } from '../services/harness-hosts.js';
 /**
@@ -361,6 +362,90 @@ async function maybeInstallSkillsSh(ctx) {
         // Skills.sh registration is a bonus, never a requirement — swallow everything.
     }
 }
+// Grok Build host initialization (ADR-402)
+async function initGrokAction(ctx, options) {
+    const { force, statusLine, dryRun } = options;
+    output.writeln();
+    output.writeln(output.bold(dryRun ? 'Grok Build init (dry run — nothing is written)' : 'Initializing RuFlo for Grok Build'));
+    output.writeln();
+    try {
+        const result = executeGrokInit({
+            targetDir: ctx.cwd,
+            force,
+            docs: true,
+            statusLine,
+            dryRun,
+        });
+        if (!result.success) {
+            output.printError('Grok initialization failed');
+            for (const err of result.errors) {
+                output.printError(err);
+            }
+            return { success: false, exitCode: 1, message: 'Grok init failed' };
+        }
+        output.printBox([
+            `.grok/config.toml — project MCP (ruflo) + permissions`,
+            `.grok/rules/ruflo-grok.md — host doctrine / tool map`,
+            `.grok/agents/ — ruflo-architect/coder/tester/reviewer`,
+            `.grok/skills/ — agent-teams-grok`,
+            `.grok/hooks/ — SubagentStop advances the team plan`,
+            `scripts/grok-team-bus.mjs (+ grok-team-store.mjs) — ADR-402 team bus CLI`,
+            `scripts/host-statusline.mjs — "what is loaded" row`,
+            `docs/grok/README.md — operator guide`,
+        ].join('\n'), 'Grok Build Integration (ADR-402)');
+        output.writeln();
+        const verb = dryRun ? 'Would write' : 'Wrote';
+        output.writeln(output.bold(`${verb} (${result.filesCreated.length}):`));
+        output.printList(result.filesCreated.map((f) => (path.relative(ctx.cwd, f).startsWith('..') ? f : path.relative(ctx.cwd, f))));
+        if (result.filesSkipped.length > 0) {
+            output.printInfo(`Skipped ${result.filesSkipped.length} existing file(s)${force ? '' : ' — use --force to overwrite'}`);
+        }
+        output.writeln();
+        const mcp = result.mcp;
+        output.printInfo(mcp.source === 'published'
+            ? `MCP server pinned to ruflo@${mcp.version} (the release that ships the team_* tools)`
+            : `MCP server points at this checkout: ${mcp.args[0]} — rebuild it before use, and re-run init from a published release before committing .grok/config.toml`);
+        const uc = result.userConfig;
+        if (uc.action === 'not-requested' || uc.action === 'snippet') {
+            output.writeln();
+            output.writeln(uc.action === 'snippet'
+                ? output.bold(`Did not change ${uc.path}: ${uc.reason}`)
+                : output.bold('Optional status row (Grok reads it only from your user config):'));
+            output.writeln(output.dim(`  Add this to ${uc.path}, or re-run with --grok-statusline to have init merge it`));
+            output.writeln(output.dim(`  (that also installs the script it runs under ~/.grok/ruflo/):`));
+            output.writeln(uc.snippet.trimEnd().split('\n').map((l) => `    ${l}`).join('\n'));
+        }
+        else if (uc.action === 'already-set') {
+            output.printInfo(uc.reason || `${uc.path} already has the Ruflo status row; refreshed the script it runs`);
+        }
+        output.writeln();
+        output.writeln(output.bold('Next steps:'));
+        output.printList([
+            'Trust this folder in Grok (/hooks-trust or grok --trust) so MCP, hooks, skills, and rules load together',
+            'Restart Grok so .grok/config.toml is applied',
+            'Read docs/grok/README.md — spawn contract checked on Grok Build 1.0.41',
+            'Verify: grok mcp list && grok mcp doctor ruflo',
+            'Optional: npx ruvnet-brain@latest then enable ruvnet-brain in .grok/config.toml',
+            'Teams: team_create / team_spawn MCP tools (or node scripts/grok-team-bus.mjs)',
+        ]);
+        output.writeln();
+        return {
+            success: true,
+            data: {
+                adapter: 'grok',
+                dryRun,
+                filesCreated: result.filesCreated,
+                filesSkipped: result.filesSkipped,
+                mcp: result.mcp,
+                userConfig: { action: uc.action, path: uc.path },
+            },
+        };
+    }
+    catch (e) {
+        output.printError(`Grok initialization failed: ${e.message}`);
+        return { success: false, exitCode: 1, message: e.message };
+    }
+}
 // Codex initialization action
 async function initCodexAction(ctx, options) {
     const { force, minimal, full, dualMode } = options;
@@ -848,6 +933,15 @@ const initAction = async (ctx) => {
     const full = ctx.flags.full;
     const codexMode = ctx.flags.codex;
     const dualMode = ctx.flags.dual;
+    const grokMode = ctx.flags.grok;
+    // Grok Build host (ADR-402) — separate surface under .grok/
+    if (grokMode) {
+        return initGrokAction(ctx, {
+            force,
+            statusLine: ctx.flags.grokStatusline === true || ctx.flags['grok-statusline'] === true,
+            dryRun: ctx.flags.dryRun === true || ctx.flags['dry-run'] === true,
+        });
+    }
     if (codexMode && !dualMode) {
         return initCodexAction(ctx, { codexMode, dualMode: false, force, minimal, full });
     }
@@ -1598,6 +1692,24 @@ export const initCommand = {
             type: 'boolean',
             default: false,
         },
+        {
+            name: 'grok',
+            description: 'Initialize for Grok Build host (creates .grok/, team bus scripts, ADR-402 surface)',
+            type: 'boolean',
+            default: false,
+        },
+        {
+            name: 'grok-statusline',
+            description: 'With --grok: also merge the Ruflo status row into ~/.grok/config.toml (user file; off by default)',
+            type: 'boolean',
+            default: false,
+        },
+        {
+            name: 'dry-run',
+            description: 'With --grok: list the files init would write, write nothing',
+            type: 'boolean',
+            default: false,
+        },
         {
             name: 'dual',
             description: 'Initialize for both Claude Code and OpenAI Codex',
@@ -1647,6 +1759,10 @@ export const initCommand = {
         { command: 'claude-flow init upgrade --verbose', description: 'Show detailed upgrade info' },
         { command: 'claude-flow init --codex', description: 'Initialize for OpenAI Codex (AGENTS.md)' },
         { command: 'claude-flow init --codex --full', description: 'Codex init with all canonical packaged skills' },
+        { command: 'claude-flow init --grok', description: 'Initialize for Grok Build (.grok/, team bus, ADR-402)' },
+        { command: 'claude-flow init --grok --force', description: 'Overwrite existing Grok host files' },
+        { command: 'claude-flow init --grok --dry-run', description: 'Show what init --grok would write' },
+        { command: 'claude-flow init --grok --grok-statusline', description: 'Also add the Ruflo status row to ~/.grok/config.toml' },
         { command: 'claude-flow init --dual', description: 'Initialize for both Claude Code and Codex' },
         { command: 'claude-flow init --no-codex-detect', description: 'Skip auto-configuring OpenAI Codex even if it is installed' },
         { command: 'claude-flow init --no-skills-sh', description: 'Skip the post-init skills.sh registration' },

package/v3/@claude-flow/cli/dist/src/commands/memory.js

@@ -814,11 +814,16 @@ const listCommand = {
         const namespace = ctx.flags.namespace;
         const limit = ctx.flags.limit;
         const includeEmbedding = ctx.flags.embeddings === true && ctx.flags.format === 'json';
+        // Mirrors memory_list's MCP tool handling: comma-separated flag →
+        // non-empty string array, require entries to carry every tag (AND).
+        const tags = ctx.flags.tags
+            ? ctx.flags.tags.split(',').map(t => t.trim()).filter((t) => t.length > 0)
+            : undefined;
         // Use sql.js directly for consistent data access
         try {
             const { listEntries, resolveDbPath: _rdbList } = await import('../memory/memory-initializer.js');
             const dbPathList = _rdbList(ctx.flags.path);
-            const listResult = await listEntries({ namespace, limit, offset: 0, dbPath: dbPathList, ...(includeEmbedding && { includeEmbedding: true }) });
+            const listResult = await listEntries({ namespace, limit, offset: 0, dbPath: dbPathList, tags, ...(includeEmbedding && { includeEmbedding: true }) });
             if (!listResult.success) {
                 output.printError(`Failed to list: ${listResult.error}`);
                 return { success: false, exitCode: 1 };

package/v3/@claude-flow/cli/dist/src/commands/status.js

@@ -484,11 +484,11 @@ const tasksCommand = {
                     { key: 'progress', header: 'Progress', width: 10 }
                 ],
                 data: result.tasks.map(t => ({
-                    id: t.id,
+                    id: t.taskId,
                     type: t.type,
                     status: formatHealth(t.status),
                     priority: t.priority,
-                    agent: t.agent || '-',
+                    agent: t.assignedTo?.length ? t.assignedTo.join(', ') : '-',
                     progress: `${t.progress}%`
                 }))
             });

package/v3/@claude-flow/cli/dist/src/commands/tui.js

@@ -8,7 +8,8 @@
  * No bundle is a message and exit 1, never a crash; ruflo stays operational without it. Without a terminal (a pipe, CI) the live view cannot run:
  * a one-line hint and exit 2, unless --plain asks for one frame as plain text and exit 0 (ADR-489 decision E).
  *
- *   npx ruflo tui                 # interactive, in a terminal
+ *   npx ruflo tui                 # interactive, in a terminal (mouse on: click a page in the bar, scroll with the wheel)
+ *   npx ruflo tui --no-mouse      # keyboard only, if SGR mouse reporting fights your terminal's text selection
  *   npx ruflo tui --view swarm    # start on the Swarm page (keys 1-6 or o c s e m a switch pages)
  *   npx ruflo tui --plain | head  # one plain frame, exit 0 (scripts, CI)
  *   npx ruflo tui | cat           # not a terminal and no --plain: a hint on stderr, exit 2
@@ -45,7 +46,10 @@ export function lookFlags(flags) {
         ...(flags?.anim === false ? { anim: false } : {}),
         ...(flags?.pictures === false ? { pictures: false } : {}),
         ...(flags?.boot === true ? { boot: true } : {}),
-        ...(flags?.mouse === true ? { mouse: true } : {}),
+        // Mouse defaults ON at the CLI layer (the runTui library itself still defaults off, unchanged for other
+        // callers/tests): only --no-mouse turns it off. The CLI must say so explicitly either way rather than
+        // omit the key, since (unlike anim/pictures) the CLI's default disagrees with the library's own default.
+        ...{ mouse: flags?.mouse !== false },
     };
 }
 /** The AI page's settings from the flags (and one environment variable for the endpoint list). Absent flags leave the defaults; a bad number is ignored, never passed on. */
@@ -69,12 +73,13 @@ export const tuiCommand = {
         { name: 'fps', description: 'Frames per second for moving pictures, 0-30 (default 8; 0 draws every picture still)', type: 'number' },
         { name: 'anim', description: 'Animate the pictures. --no-anim draws them still', type: 'boolean', default: true },
         { name: 'pictures', description: 'Draw the pictures of the console (title art, swarm graph, gauges). --no-pictures shows their words only', type: 'boolean', default: true },
-        { name: 'mouse', description: 'Read mouse reports: click a page in the bar, scroll with the wheel (every action also has a key)', type: 'boolean', default: false },
+        { name: 'mouse', description: 'Read mouse reports: click a page in the bar, scroll with the wheel (every action also has a key). On by default; --no-mouse turns it off if SGR reporting fights your terminal\'s text selection', type: 'boolean', default: true },
         { name: 'boot', description: 'Play the look\'s start-up screen first (as the console\'s boot setting)', type: 'boolean', default: false },
         { name: 'plain', description: 'Print one frame as plain text and exit 0 (scripts and CI). Without it, a non-terminal gets a hint and exit 2', type: 'boolean', default: false },
     ],
     examples: [
-        { command: 'npx ruflo tui', description: 'Open the console in this terminal' },
+        { command: 'npx ruflo tui', description: 'Open the console in this terminal (mouse on: click a page in the bar, scroll with the wheel)' },
+        { command: 'npx ruflo tui --no-mouse', description: 'Keyboard only, if SGR mouse reporting fights your terminal\'s text selection' },
         { command: 'npx ruflo tui --view swarm', description: 'Start on the Swarm page (keys 1-6 switch pages, tab cycles, q quits)' },
         { command: 'npx ruflo tui --view ai --model openai/gpt-4o-mini --max-spend-usd 0.1', description: 'The AI page on a cheap OpenRouter model, stopping at $0.10 reported (key in $OPENROUTER_API_KEY, never shown)' },
         { command: 'npx ruflo tui --plain | head -40', description: 'One plain frame, exit 0: for scripts and CI (no terminal needed)' },

package/v3/@claude-flow/cli/dist/src/index.d.ts

@@ -6,6 +6,9 @@
  */
 import './log-filters.js';
 export declare const VERSION: string;
+/** Commands that only observe the running system and must not start or write anything. */
+export declare const OBSERVE_ONLY_COMMANDS: ReadonlySet<string>;
+export declare function isObserveOnlyCommand(name: string | undefined): boolean;
 export interface CLIOptions {
     name?: string;
     description?: string;

package/v3/@claude-flow/cli/dist/src/index.js

@@ -36,6 +36,11 @@ function getPackageVersion() {
     }
 }
 export const VERSION = getPackageVersion();
+/** Commands that only observe the running system and must not start or write anything. */
+export const OBSERVE_ONLY_COMMANDS = new Set(['harness']);
+export function isObserveOnlyCommand(name) {
+    return name !== undefined && OBSERVE_ONLY_COMMANDS.has(name);
+}
 /**
  * V3 CLI Application
  */
@@ -113,8 +118,13 @@ export class CLI {
                 this.output.printDebug(`Flags: ${JSON.stringify(Object.fromEntries(Object.entries(flags).filter(([k]) => k !== '_')))}`);
                 this.output.printDebug(`CWD: ${process.cwd()}`);
             }
+            // Observe-only commands (e.g. `harness`, run from SessionStart hooks)
+            // report on the running system, so they must not change it: no update
+            // check, no policy migration, no helper refresh, no proven-config
+            // adoption, no daemon autostart.
+            const observeOnly = isObserveOnlyCommand(commandPath[0] ?? positional[0]);
             // Run startup update check (non-blocking, silent on skip)
-            if (!flags.noUpdate && flags.update !== false && commandPath[0] !== 'update' && !(commandPath[0] === 'doctor' && flags.json)) {
+            if (!flags.noUpdate && flags.update !== false && commandPath[0] !== 'update' && !(commandPath[0] === 'doctor' && flags.json) && !observeOnly) {
                 this.checkForUpdatesOnStartup().catch(() => { });
             }
             // Version-stamped helper auto-refresh — propagate hook fixes to an already
@@ -123,7 +133,7 @@ export class CLI {
             // command can't exit before the copy lands; the fast path is a single
             // stamp read + string compare (sub-ms), and the copy runs at most once per
             // version bump. Best-effort + silent — never blocks or fails a command.
-            if (commandPath[0] !== 'init' && commandPath[0] !== 'update') {
+            if (commandPath[0] !== 'init' && commandPath[0] !== 'update' && !observeOnly) {
                 // ADR-324: existing installations acquire a versioned policy state on
                 // first use. Migration is additive and starts in legacy mode, so older
                 // AgentDB, MCP, hooks, and swarm workflows keep their exact behavior.

package/v3/@claude-flow/cli/dist/src/init/grok-generator.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Grok Build host init (ADR-402).
+ *
+ * Mirrors `init --codex`: writes project-scoped `.grok/` surface + team bus scripts
+ * so any repo can run Ruflo Agent Teams under Grok without Claude SendMessage.
+ *
+ * Writes outside the project only with `statusLine: true` (`--grok-statusline`):
+ * the status row lives in the user's ~/.grok/config.toml, which is parsed and
+ * merged with a real TOML parser, never blindly appended to.
+ */
+import { grokTemplatesRoot } from './grok-templates.js';
+export interface GrokInitOptions {
+    targetDir: string;
+    force?: boolean;
+    /** Also write docs/grok/README.md operator guide */
+    docs?: boolean;
+    /** Install the status row into the user's ~/.grok/config.toml (opt-in). */
+    statusLine?: boolean;
+    /** Report what would be written; write nothing. */
+    dryRun?: boolean;
+    /** Home directory for the user-level status row (tests). */
+    homeDir?: string;
+}
+export type GrokUserConfigAction = 'not-requested' | 'created' | 'merged' | 'already-set' | 'snippet' | 'would-write';
+export interface GrokUserConfigResult {
+    action: GrokUserConfigAction;
+    /** ~/.grok/config.toml */
+    path: string;
+    /** TOML to paste when init did not write it */
+    snippet: string;
+    reason?: string;
+}
+export interface GrokMcpLaunch {
+    command: string;
+    args: string[];
+    /** published: pinned to this CLI's npm version; checkout: this local build */
+    source: 'published' | 'checkout';
+    version: string;
+}
+export interface GrokInitResult {
+    success: boolean;
+    dryRun: boolean;
+    /** Files written (or, in a dry run, that would be written) */
+    filesCreated: string[];
+    filesSkipped: string[];
+    errors: string[];
+    mcp: GrokMcpLaunch;
+    userConfig: GrokUserConfigResult;
+}
+export { grokTemplatesRoot };
+/**
+ * How the project .grok/config.toml starts the Ruflo MCP server.
+ *
+ * The team_* tools ship in the same release as `init --grok`, so the server is
+ * pinned to the version that is running this init — never `@latest`, which can
+ * be an older release without them. Running from a source checkout (not under
+ * node_modules) points at that checkout's CLI, since its version may not be
+ * published yet.
+ */
+export declare function rufloMcpLaunch(root?: string): GrokMcpLaunch;
+/**
+ * Fill the template placeholders. Every inserted value is escaped as a TOML
+ * string, so a Windows path such as C:\Users\x stays valid TOML.
+ */
+export declare function materializeGrokConfig(template: string, launch: GrokMcpLaunch, home: string): string;
+/** Where the opt-in status row script is installed: a stable absolute path. */
+export declare function grokStatusScriptPath(home: string): string;
+/** `node "<abs path>"` — no shell builtins, and never a repo-relative script. */
+export declare function grokStatusLineCommand(home: string): string;
+export declare function grokStatusLineSnippet(home: string): string;
+type MergeOutcome = {
+    kind: 'write';
+    text: string;
+} | {
+    kind: 'already-set';
+    ours: boolean;
+} | {
+    kind: 'unsafe';
+    reason: string;
+};
+/**
+ * Add the status row to an existing user config without disturbing it.
+ *
+ * Any existing `ui.status_line` — header, `[ ui.status_line ]`,
+ * `[ui."status_line"]`, dotted keys, or an inline table — is detected by
+ * parsing, and left alone. Otherwise the block is appended and the result is
+ * re-parsed: it is written only if it parses, carries exactly our status row,
+ * and every other value is unchanged. Anything else (unparseable file, `ui`
+ * as an inline table, …) falls back to printing the snippet.
+ */
+export declare function mergeGrokStatusLine(existing: string, home: string): MergeOutcome;
+/**
+ * Initialize Grok host surface in targetDir.
+ */
+export declare function executeGrokInit(options: GrokInitOptions): GrokInitResult;
+//# sourceMappingURL=grok-generator.d.ts.map