talking-stick 0.4.9 → 0.4.11

package/dist/grok-session-store.js

@@ -0,0 +1,143 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveDataDir } from "./config.js";
+export const DEFAULT_GROK_SESSION_RECORD_MAX_AGE_MS = 4 * 60 * 60 * 1000;
+export function resolveGrokSessionLogPath(options = {}) {
+    return path.join(resolveDataDir(options), "grok-sessions.jsonl");
+}
+export function appendGrokSessionRecord(record, options = {}) {
+    const logPath = options.logPath ?? resolveGrokSessionLogPath(options.dataDirOptions ?? {});
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    fs.appendFileSync(logPath, `${JSON.stringify(record)}\n`, "utf8");
+}
+export function readGrokSessionRecords(logPath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(logPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+    const records = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            const record = parseGrokSessionRecord(parsed);
+            if (record)
+                records.push(record);
+        }
+        catch {
+            // Hook logs are append-only and best-effort; one bad line should not
+            // break identity resolution for the whole session.
+        }
+    }
+    return records;
+}
+export function findGrokSessionRecord(input) {
+    const workspaceRoot = normalizeWorkspaceRoot(input.workspaceRoot);
+    if (!workspaceRoot)
+        return null;
+    const logPath = input.logPath ?? resolveGrokSessionLogPath();
+    const nowMs = input.now?.getTime() ?? Date.now();
+    const maxAgeMs = input.maxAgeMs ?? DEFAULT_GROK_SESSION_RECORD_MAX_AGE_MS;
+    const records = readGrokSessionRecords(logPath);
+    const endedSessionIds = new Set();
+    const workspaceCandidates = [];
+    for (const record of records.slice().reverse()) {
+        if (normalizeWorkspaceRoot(record.workspace_root) !== workspaceRoot) {
+            continue;
+        }
+        if (isStaleRecord(record, nowMs, maxAgeMs)) {
+            continue;
+        }
+        if (isGrokSessionEndEvent(record.event)) {
+            endedSessionIds.add(record.grok_session_id);
+            continue;
+        }
+        if (endedSessionIds.has(record.grok_session_id)) {
+            continue;
+        }
+        workspaceCandidates.push(record);
+        if (input.grokPid != null &&
+            input.grokProcessStartedAt != null &&
+            record.grok_pid === input.grokPid &&
+            record.grok_process_started_at === input.grokProcessStartedAt) {
+            return record;
+        }
+    }
+    if (input.grokPid != null && input.grokProcessStartedAt != null) {
+        return null;
+    }
+    const uniqueSessionIds = new Set(workspaceCandidates.map((record) => record.grok_session_id));
+    if (uniqueSessionIds.size === 1) {
+        return workspaceCandidates[0] ?? null;
+    }
+    return null;
+}
+export function isGrokSessionEndEvent(event) {
+    return normalizeEventName(event) === "sessionend";
+}
+function parseGrokSessionRecord(value) {
+    if (!isObjectRecord(value))
+        return null;
+    if (value.source !== "grok_hook")
+        return null;
+    const grokSessionId = nonEmptyString(value.grok_session_id);
+    const workspaceRoot = nonEmptyString(value.workspace_root);
+    const event = nonEmptyString(value.event);
+    const observedAt = nonEmptyString(value.observed_at);
+    if (!grokSessionId || !workspaceRoot || !event || !observedAt) {
+        return null;
+    }
+    return {
+        source: "grok_hook",
+        grok_session_id: grokSessionId,
+        workspace_root: workspaceRoot,
+        cwd: nullableString(value.cwd),
+        event,
+        observed_at: observedAt,
+        grok_pid: nullableInteger(value.grok_pid),
+        grok_process_started_at: nullableString(value.grok_process_started_at)
+    };
+}
+function isStaleRecord(record, nowMs, maxAgeMs) {
+    const observedAtMs = Date.parse(record.observed_at);
+    if (Number.isNaN(observedAtMs))
+        return true;
+    return nowMs - observedAtMs > maxAgeMs;
+}
+function normalizeWorkspaceRoot(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return null;
+    try {
+        return fs.realpathSync.native(trimmed);
+    }
+    catch {
+        return path.resolve(trimmed);
+    }
+}
+function normalizeEventName(event) {
+    return event.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value
+        : null;
+}
+function nullableString(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value
+        : null;
+}
+function nullableInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) ? value : null;
+}
+function isObjectRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/identity.js

@@ -1,6 +1,8 @@
 import crypto from "node:crypto";
 import os from "node:os";
 import path from "node:path";
+import { findGrokSessionRecord, resolveGrokSessionLogPath } from "./grok-session-store.js";
+import { resolveContextPath } from "./path-resolution.js";
 import { createSystemProcessInspector } from "./process-utils.js";
 const HARNESS_CLI_EXPORT_ENV = "TT_HARNESS_EXPORT";
 const HARNESS_CLI_AGENT_ID_ENV = "TT_HARNESS_AGENT_ID";
@@ -41,7 +43,11 @@ export function deriveMcpHarnessIdentity(options = {}) {
     const signal = detectHarnessSignal(env);
     if (signal) {
         const processRef = resolveSignalProcessRef(signal, parentPid, parentInspection, inspector);
-        const sessionId = resolveHarnessSessionId(signal, env, processRef.pid, processRef.inspection, username, hostId, inspector);
+        const sessionId = resolveHarnessSessionId(signal, env, processRef.pid, processRef.inspection, username, hostId, inspector, {
+            contextPath: options.contextPath,
+            grokSessionLogPath: options.grokSessionLogPath,
+            now: options.now
+        });
         const harnessProcess = resolveHarnessProcessRef(signal, processRef, inspector);
         const agentId = options.agentId ?? harnessAgentId(signal.harness, sessionId, hostId, username);
         return {
@@ -100,7 +106,9 @@ export function deriveHarnessCliIdentity(options = {}) {
     }
     let signal = detectHarnessSignal(env);
     if (!signal && !isHarnessCliExportEnabled(env)) {
-        return null;
+        signal = detectGrokViaAncestry(parentPid, parentInspection, inspector);
+        if (!signal)
+            return null;
     }
     if (!signal) {
         signal = detectHarnessViaAncestry(parentPid, inspector);
@@ -109,7 +117,11 @@ export function deriveHarnessCliIdentity(options = {}) {
         return null;
     const processRef = resolveSignalProcessRef(signal, parentPid, parentInspection, inspector);
     const username = options.username ?? safeUsername();
-    const sessionId = resolveHarnessSessionId(signal, env, processRef.pid, processRef.inspection, username, hostId, inspector);
+    const sessionId = resolveHarnessSessionId(signal, env, processRef.pid, processRef.inspection, username, hostId, inspector, {
+        contextPath: options.contextPath,
+        grokSessionLogPath: options.grokSessionLogPath,
+        now: options.now
+    });
     const agentId = options.agentId ?? harnessAgentId(signal.harness, sessionId, hostId, username);
     const harnessProcess = resolveHarnessProcessRef(signal, processRef, inspector);
     return {
@@ -136,10 +148,16 @@ function harnessAgentId(harness, sessionId, hostId, username) {
         sanitizeIdentityComponent(username)
     ])}`;
 }
-function resolveHarnessSessionId(signal, env, parentPid, parentInspection, username, hostId, inspector) {
+function resolveHarnessSessionId(signal, env, parentPid, parentInspection, username, hostId, inspector, options = {}) {
     if (signal.sessionId)
         return `harness:${signal.sessionId}`;
     const harnessRoot = findHarnessRootInAncestry(signal.harness, parentPid, parentInspection, inspector);
+    if (signal.harness === "grok") {
+        const grokSessionId = resolveGrokHookSessionId(env, harnessRoot, options);
+        if (grokSessionId) {
+            return `harness:${grokSessionId}`;
+        }
+    }
     if (harnessRoot) {
         return `pid:${harnessRoot.pid}@${harnessRoot.startTime}`;
     }
@@ -165,7 +183,7 @@ function resolveHarnessProcessRef(signal, processRef, inspector) {
 // process whose command matches the named harness. Anchoring session id to
 // that root keeps `tt` invocations stable whether they're spawned directly
 // by the harness (MCP subprocess) or through intermediate shells (CLI shell-out).
-function findHarnessRootInAncestry(harness, startPid, startInspection, inspector, maxDepth = 10) {
+export function findHarnessRootInAncestry(harness, startPid, startInspection, inspector, maxDepth = 10) {
     let result = null;
     let currentPid = startPid;
     let currentInspection = startInspection;
@@ -220,6 +238,7 @@ const HARNESS_COMMAND_MAPPING = {
     "claude-code": "claude",
     codex: "codex",
     gemini: "gemini",
+    grok: "grok",
     opencode: "opencode"
 };
 function detectHarnessViaAncestry(pid, inspector, maxDepth = 10) {
@@ -231,10 +250,13 @@ function detectHarnessViaAncestry(pid, inspector, maxDepth = 10) {
         if (!inspection)
             break;
         const label = deriveCommandLabel(inspection.command);
-        if (HARNESS_COMMAND_MAPPING[label]) {
+        const harness = HARNESS_COMMAND_MAPPING[label];
+        if (harness) {
             return {
-                harness: HARNESS_COMMAND_MAPPING[label],
-                sessionId: `pid:${inspection.pid}@${inspection.startTime}`,
+                harness,
+                sessionId: harness === "grok"
+                    ? null
+                    : `pid:${inspection.pid}@${inspection.startTime}`,
                 pidHint: null
             };
         }
@@ -267,8 +289,51 @@ function detectHarnessSignal(env) {
             pidHint: null
         };
     }
+    const cmuxHarness = resolveCmuxLaunchHarness(env);
+    if (cmuxHarness) {
+        return {
+            harness: cmuxHarness,
+            sessionId: null,
+            pidHint: null
+        };
+    }
     return null;
 }
+function detectGrokViaAncestry(parentPid, parentInspection, inspector) {
+    const grokRoot = findHarnessRootInAncestry("grok", parentPid, parentInspection, inspector, 20);
+    return grokRoot
+        ? { harness: "grok", sessionId: null, pidHint: null }
+        : null;
+}
+function resolveGrokHookSessionId(env, harnessRoot, options) {
+    const workspaceRoot = resolveGrokWorkspaceRoot(env, options.contextPath);
+    const record = findGrokSessionRecord({
+        logPath: options.grokSessionLogPath ??
+            resolveGrokSessionLogPath({ env }),
+        workspaceRoot,
+        grokPid: harnessRoot?.pid ?? null,
+        grokProcessStartedAt: harnessRoot?.startTime ?? null,
+        now: options.now
+    });
+    return record?.grok_session_id ?? null;
+}
+function resolveGrokWorkspaceRoot(env, contextPath) {
+    const explicit = nonEmpty(env.GROK_WORKSPACE_ROOT) ??
+        nonEmpty(env.CLAUDE_PROJECT_DIR);
+    if (explicit)
+        return path.resolve(explicit);
+    const candidate = contextPath ?? nonEmpty(env.PWD) ?? process.cwd();
+    try {
+        return resolveContextPath(candidate).workspace_root;
+    }
+    catch {
+        return path.resolve(candidate);
+    }
+}
+function resolveCmuxLaunchHarness(env) {
+    const launchKind = normalizeEnvValue(env.CMUX_AGENT_LAUNCH_KIND);
+    return launchKind ? HARNESS_COMMAND_MAPPING[launchKind] ?? null : null;
+}
 function resolveSignalProcessRef(signal, fallbackPid, fallbackInspection, inspector) {
     if (signal.pidHint && signal.pidHint !== fallbackPid) {
         const hintedInspection = inspector.inspect(signal.pidHint);
@@ -294,6 +359,10 @@ function parsePositiveInteger(value) {
 function nonEmpty(value) {
     return value && value.trim().length > 0 ? value : null;
 }
+function normalizeEnvValue(value) {
+    const nonBlank = nonEmpty(value);
+    return nonBlank ? nonBlank.toLowerCase() : null;
+}
 function deriveCommandLabel(command) {
     if (!command) {
         return "harness";

package/dist/index.js

@@ -5,7 +5,8 @@ export { ProtocolError, isProtocolError } from "./errors.js";
 export { deriveHarnessCliIdentity, deriveHumanCliIdentity, deriveMcpHarnessIdentity } from "./identity.js";
 export { ancestorPaths, canonicalizeContextPath, resolveContextPath, resolveWorkspaceRoot } from "./path-resolution.js";
 export { DEFAULT_MAX_INSTRUCTION_FILE_BYTES, DEFAULT_INSTRUCTIONS_MARKDOWN, editInstructions, extractHarnessInstructions, normalizeInstructionHarness, parseInstructionScope, resetInstructions, resolveInstructionHarness, resolveInstructionPaths, showInstructions } from "./instructions.js";
-export { SUPPORTED_HARNESSES, MissingHarnessError, detectHarness, parseHarnessList, planUninstall, resolveHarnessConfigDir, resolveOpencodeConfigDir, resolveOpencodeConfigPath, runAction, skipAction } from "./install.js";
+export { SUPPORTED_HARNESSES, buildGrokSessionHookConfig, DEFAULT_GROK_SESSION_HOOK_COMMAND, GROK_SESSION_HOOK_EVENTS, GROK_SESSION_HOOK_FILE, MissingHarnessError, detectHarness, parseHarnessList, planGrokSessionHookInstall, planGrokSessionHookUninstall, planUninstall, resolveGrokSessionHookPath, resolveHarnessConfigDir, resolveOpencodeConfigDir, resolveOpencodeConfigPath, runAction, skipAction } from "./install.js";
+export { DEFAULT_GROK_SESSION_RECORD_MAX_AGE_MS, appendGrokSessionRecord, findGrokSessionRecord, isGrokSessionEndEvent, readGrokSessionRecords, resolveGrokSessionLogPath } from "./grok-session-store.js";
 export { DEFAULT_SKILL_NAME, planSkillInstall, planSkillUninstall, resolveBundledSkillPath, resolveSkillTargetPath, syncInstalledSkills } from "./skill-install.js";
 export { readPackageVersion, readUpdateMigrationState, resolveUpdateMigrationStatePath, runFirstRunMcpMigration, runStaleMcpCleanup, writeUpdateMigrationState } from "./update-migration.js";
 export { createSystemProcessInspector, terminateKnownProcess } from "./process-utils.js";

package/dist/install.js

@@ -2,9 +2,19 @@ import { spawn } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-export const SUPPORTED_HARNESSES = ["claude-code", "codex", "gemini", "opencode"];
+import { writeFileAtomic } from "./atomic-write.js";
+export const SUPPORTED_HARNESSES = ["claude-code", "codex", "gemini", "grok", "opencode"];
 export const DEFAULT_SERVER_NAME = "talking-stick";
+// Legacy MCP command retained only to identify stale config entries for removal.
 export const DEFAULT_SERVER_COMMAND = ["tt", "mcp"];
+export const GROK_SESSION_HOOK_FILE = "talking-stick-session.json";
+export const DEFAULT_GROK_SESSION_HOOK_COMMAND = ": talking-stick-grok-session-hook; if command -v tt >/dev/null 2>&1; then tt grok-session-hook >/dev/null 2>/dev/null || true; fi";
+export const GROK_SESSION_HOOK_EVENTS = [
+    "SessionStart",
+    "UserPromptSubmit",
+    "PreToolUse",
+    "SessionEnd"
+];
 export class MissingHarnessError extends Error {
     constructor(message) {
         super(message);
@@ -60,7 +70,7 @@ function defaultReadFile(filePath) {
     }
 }
 function defaultWriteFile(filePath, data) {
-    fs.writeFileSync(filePath, data);
+    writeFileAtomic(filePath, data);
 }
 function defaultEnsureDir(dirPath) {
     fs.mkdirSync(dirPath, { recursive: true });
@@ -96,11 +106,21 @@ export function resolveHarnessConfigDir(harness, options = {}) {
     const resolved = resolveOptions(options);
     return resolveHarnessConfigDirFromResolved(harness, resolved);
 }
+export function resolveGrokSessionHookPath(options = {}) {
+    const resolved = resolveOptions(options);
+    return path.join(resolveGrokConfigDirFromResolved(resolved), "hooks", GROK_SESSION_HOOK_FILE);
+}
 function resolveOpencodeConfigDirFromResolved(resolved) {
     const xdg = resolved.env.XDG_CONFIG_HOME?.trim();
     const base = xdg && xdg.length > 0 ? xdg : path.join(resolved.homeDir, ".config");
     return path.join(base, "opencode");
 }
+function resolveGrokConfigDirFromResolved(resolved) {
+    const grokHome = resolved.env.GROK_HOME?.trim();
+    return grokHome && grokHome.length > 0
+        ? grokHome
+        : path.join(resolved.homeDir, ".grok");
+}
 function resolveHarnessConfigDirFromResolved(harness, resolved) {
     switch (harness) {
         case "claude-code":
@@ -109,6 +129,8 @@ function resolveHarnessConfigDirFromResolved(harness, resolved) {
             return path.join(resolved.homeDir, ".codex");
         case "gemini":
             return path.join(resolved.homeDir, ".gemini");
+        case "grok":
+            return resolveGrokConfigDirFromResolved(resolved);
         case "opencode":
             return resolveOpencodeConfigDirFromResolved(resolved);
         default:
@@ -157,6 +179,8 @@ export function planUninstall(harness, options = {}) {
                 operation: "uninstall",
                 serverName: resolved.serverName
             };
+        case "grok":
+            return skipAction(harness, "legacy Talking Stick cleanup is not applicable for grok");
         case "opencode": {
             const filePath = resolveOpencodeConfigPath(options);
             const configDir = path.dirname(filePath);
@@ -174,7 +198,7 @@ export function planUninstall(harness, options = {}) {
                 operation: "uninstall",
                 serverName: resolved.serverName,
                 inspect: () => inspectOpencodeConfig(filePath, resolved),
-                apply: () => patchOpencodeConfig(filePath, resolved, "uninstall")
+                apply: () => patchOpencodeConfig(filePath, resolved)
             };
         }
         default:
@@ -189,29 +213,90 @@ export function skipAction(harness, message) {
         message
     };
 }
-function patchOpencodeConfig(filePath, resolved, mode) {
+export function planGrokSessionHookInstall(options = {}) {
+    const resolved = resolveOptions(options);
+    const grokConfigDir = resolveGrokConfigDirFromResolved(resolved);
+    const filePath = resolveGrokSessionHookPath(options);
+    if (resolved.skipMissing && !resolved.hooks.pathExists(grokConfigDir)) {
+        return skipAction("grok", `grok config directory not found: ${grokConfigDir}`);
+    }
+    return {
+        kind: "file-patch",
+        harness: "grok",
+        filePath,
+        description: `write Grok session hook ${filePath}`,
+        inspect: () => inspectGrokSessionHook(filePath, resolved),
+        apply: () => writeGrokSessionHook(filePath, resolved)
+    };
+}
+export function planGrokSessionHookUninstall(options = {}) {
+    const resolved = resolveOptions(options);
+    const grokConfigDir = resolveGrokConfigDirFromResolved(resolved);
+    const filePath = resolveGrokSessionHookPath(options);
+    if (resolved.skipMissing && !resolved.hooks.pathExists(grokConfigDir)) {
+        return skipAction("grok", `grok config directory not found: ${grokConfigDir}`);
+    }
+    return {
+        kind: "file-patch",
+        harness: "grok",
+        filePath,
+        description: `remove Grok session hook ${filePath}`,
+        inspect: () => resolved.hooks.readFile(filePath) === null ? "absent" : "present",
+        apply: () => removeGrokSessionHook(filePath, resolved)
+    };
+}
+export function buildGrokSessionHookConfig() {
+    const hook = {
+        type: "command",
+        command: DEFAULT_GROK_SESSION_HOOK_COMMAND,
+        timeout: 5
+    };
+    const hooks = Object.fromEntries(GROK_SESSION_HOOK_EVENTS.map((event) => [
+        event,
+        [
+            {
+                hooks: [hook]
+            }
+        ]
+    ]));
+    return JSON.stringify({ hooks }, null, 2) + "\n";
+}
+function inspectGrokSessionHook(filePath, resolved) {
+    const existing = resolved.hooks.readFile(filePath);
+    if (existing === null)
+        return "absent";
+    return existing === buildGrokSessionHookConfig() ? "present" : "different";
+}
+function writeGrokSessionHook(filePath, resolved) {
+    resolved.hooks.ensureDir(path.dirname(filePath));
+    resolved.hooks.writeFile(filePath, buildGrokSessionHookConfig());
+}
+function removeGrokSessionHook(filePath, resolved) {
+    void resolved;
+    try {
+        fs.rmSync(filePath, { force: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return;
+        }
+        throw error;
+    }
+}
+function patchOpencodeConfig(filePath, resolved) {
     const existing = resolved.hooks.readFile(filePath);
     if (resolved.skipMissing) {
         const configDir = path.dirname(filePath);
         if (!resolved.hooks.pathExists(configDir)) {
             throw new MissingHarnessError(`opencode config directory not found: ${configDir}`);
         }
-        if (mode === "uninstall" && existing === null) {
+        if (existing === null) {
             throw new MissingHarnessError(`opencode config not found: ${filePath}`);
         }
     }
     const config = existing ? parseJsonOrThrow(existing, filePath) : {};
     const mcp = isPlainObject(config.mcp) ? { ...config.mcp } : {};
-    if (mode === "install") {
-        mcp[resolved.serverName] = {
-            type: "local",
-            command: [...resolved.serverCommand],
-            enabled: true
-        };
-    }
-    else {
-        delete mcp[resolved.serverName];
-    }
+    delete mcp[resolved.serverName];
     config.mcp = mcp;
     resolved.hooks.ensureDir(path.dirname(filePath));
     resolved.hooks.writeFile(filePath, JSON.stringify(config, null, 2) + "\n");
@@ -305,6 +390,15 @@ export function detectHarness(harness, options = {}) {
                 return { harness, detected: true, evidence: configDir };
             return { harness, detected: false, evidence: "gemini not on PATH and no config directory" };
         }
+        case "grok": {
+            const bin = resolved.hooks.which("grok");
+            if (bin)
+                return { harness, detected: true, evidence: bin };
+            const configDir = resolveHarnessConfigDirFromResolved(harness, resolved);
+            if (resolved.hooks.pathExists(configDir))
+                return { harness, detected: true, evidence: configDir };
+            return { harness, detected: false, evidence: "grok not on PATH and no config directory" };
+        }
         case "opencode": {
             const bin = resolved.hooks.which("opencode");
             if (bin)
@@ -505,6 +599,22 @@ function successStatusForOperation(operation, beforeState) {
 }
 function formatMcpActionMessage(action, status, fallback) {
     if (!action.serverName || !action.operation) {
+        if (action.kind === "file-patch") {
+            switch (status) {
+                case "added":
+                    return `Installed ${action.filePath}.`;
+                case "updated":
+                    return `Updated ${action.filePath}.`;
+                case "already_present":
+                    return `${action.filePath} is already installed.`;
+                case "removed":
+                    return `Removed ${action.filePath}.`;
+                case "already_absent":
+                    return `${action.filePath} is already absent.`;
+                default:
+                    break;
+            }
+        }
         return fallback ?? "ok";
     }
     const target = `MCP server '${action.serverName}'`;
@@ -534,6 +644,8 @@ function mcpConfigLocation(action) {
             return "Codex global config";
         case "gemini":
             return "Gemini user config";
+        case "grok":
+            return "Grok config";
         case "opencode":
             return "OpenCode config";
         default:

package/dist/instructions.js

@@ -12,7 +12,7 @@ On freshly invoked multi-agent tasks, give peers a short window to join before d
 
 Use phase names in handoffs when they clarify the work: draft, adversarial review, convergence, implementation, implementation review, test review, and release. These phases are vocabulary, not protocol state.
 
-Typical fits are advisory. Claude is usually strong at prose, first-pass synthesis, tool-running, implementation review, and test review. Codex is usually strong at adversarial review, convergence, implementation, edge cases, and release mechanics after operator approval. Gemini and OpenCode start with conservative local guidance until project dogfood says otherwise.
+Claude and Codex are peers of comparable capability; neither outranks the other. Split work evenly between them rather than routing by stereotype, and have all models plan, implement, and evaluate together: any harness can draft, review, converge, implement, or release. Gemini and OpenCode start with conservative local guidance until project dogfood says otherwise.
 
 For multi-agent design work, prefer independent read-only drafts first, then adversarial review and convergence. Do not impose a draft file structure on the workspace by default. If scratch draft files are useful, delete superseded pre-convergence drafts after the converged plan exists unless the operator asks to keep them.
 
@@ -20,16 +20,20 @@ Default to normal release handoffs. Use named assignment only when a specific me
 
 ## Claude
 
-Lean into drafting, synthesis, tool-running, implementation review, and test review. Watch for scope creep and messy first-pass artifacts. When implementation belongs elsewhere, make the next phase explicit in the handoff.
+Take a full, even share of planning, implementation, and evaluation. Watch for scope creep and messy first-pass artifacts. Make the next phase explicit in the handoff.
 
 ## Codex
 
-Lean into adversarial review, convergence, precise implementation, edge-case sweeps, and release mechanics after operator approval. Watch for over-indexing on mechanics when the operator still needs to decide direction.
+Take a full, even share of planning, implementation, and evaluation. Watch for over-indexing on mechanics when the operator still needs to decide direction. Make the next phase explicit in the handoff.
 
 ## Gemini
 
 Use broad context review and exploration conservatively until the project has stronger Gemini-specific dogfood. Keep handoffs concrete and do not assume responsibility that the operator assigned to another harness.
 
+## Grok
+
+Use Grok Build as a first-class local coding harness. Keep coordination safety ahead of speed, rely on the native Grok skill and session hook when installed, and keep handoffs concrete when another harness is better positioned to implement or review.
+
 ## OpenCode
 
 Use terminal-native local exploration and implementation conservatively until the project has stronger OpenCode-specific dogfood. Keep coordination safety ahead of speed.
@@ -41,6 +45,8 @@ const HARNESS_ALIASES = {
     "claude-code": "claude",
     codex: "codex",
     gemini: "gemini",
+    grok: "grok",
+    "grok-build": "grok",
     opencode: "opencode"
 };
 export function resolveInstructionPaths(options = {}) {
@@ -108,7 +114,7 @@ export function resolveInstructionHarness(explicitHarness, identity) {
 export function normalizeInstructionHarness(value) {
     const normalized = HARNESS_ALIASES[normalizeKey(value)];
     if (!normalized) {
-        throw new Error(`--harness must be one of claude, codex, gemini, opencode, all (got ${value}).`);
+        throw new Error(`--harness must be one of claude, codex, gemini, grok, opencode, all (got ${value}).`);
     }
     return normalized;
 }
@@ -145,6 +151,10 @@ export function extractHarnessInstructions(markdown, harness) {
             sections.get(current)?.push(line);
             continue;
         }
+        if (sawSection && isMarkdownH2Header(line)) {
+            current = null;
+            continue;
+        }
         if (!sawSection) {
             shared.push(line);
             continue;
@@ -196,6 +206,9 @@ function ensureInstructionFile(filePath) {
     fs.writeFileSync(filePath, DEFAULT_INSTRUCTIONS_MARKDOWN);
     return true;
 }
+function isMarkdownH2Header(line) {
+    return /^##\s+.+?\s*$/.test(line);
+}
 function parseHarnessHeader(line) {
     const match = line.match(/^##\s+(.+?)\s*$/);
     if (!match) {
@@ -208,6 +221,8 @@ function parseHarnessHeader(line) {
         return "codex";
     if (key.startsWith("gemini"))
         return "gemini";
+    if (key.startsWith("grok"))
+        return "grok";
     if (key.startsWith("opencode"))
         return "opencode";
     return null;

package/dist/process-utils.js

@@ -56,7 +56,11 @@ function inspectSystemProcess(pid, options) {
     try {
         const output = (options.execFile ?? defaultExecFile)("ps", ["-o", "ppid=", "-o", "lstart=", "-o", "command=", "-p", String(pid)], {
             encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"]
+            stdio: ["ignore", "pipe", "ignore"],
+            env: {
+                ...process.env,
+                LC_ALL: "C"
+            }
         }).trimEnd();
         if (!output.trim()) {
             return null;