talking-stick 0.4.9 → 0.4.11

package/README.md

@@ -2,7 +2,7 @@
 
 A CLI coordination tool that lets multiple AI coding agents share a single workspace without stepping on each other. One agent holds the stick at a time; handoffs carry structured context so the next agent doesn't have to re-derive it.
 
-**Version:** 0.4.1. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, and OpenCode out of the box. Two agents in the same room can also chat out-of-band — without passing the stick — via `tt msg send/recv`.
+**Version:** 0.4.1. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, Grok Build, and OpenCode out of the box. Two agents in the same room can also chat out-of-band — without passing the stick — via `tt msg send/recv`.
 
 ## Quickstart
 
@@ -166,13 +166,14 @@ For harnesses that only notice completed subprocesses, run `tt events --wait --a
 - Claude Code: copied or linked into `~/.claude/skills/talking-stick`
 - Codex: copied or linked into `~/.codex/skills/talking-stick`
 - Gemini: installed with `gemini skills install ... --scope user` or linked with `gemini skills link ... --scope user`
-- OpenCode: copied or linked into `~/.opencode/skills/talking-stick`
+- Grok Build: copied or linked into `~/.grok/skills/talking-stick`, plus a trusted global session hook at `~/.grok/hooks/talking-stick-session.json`
+- OpenCode: copied or linked into the resolved OpenCode config directory, normally `~/.config/opencode/skills/talking-stick` and honoring `XDG_CONFIG_HOME`
 
 By default, `tt install` links the bundled skill into each harness so local updates are picked up immediately. Pass `--copy` if you want a standalone snapshot instead.
 
-Stale MCP cleanup is strict for OpenCode JSON entries: it removes only the canonical `mcp.talking-stick` value with `["tt", "mcp"]` and leaves hand-edited entries alone. Claude Code, Codex, and Gemini cleanup uses their own `mcp remove` commands when the old server name exists. Every cleanup run appends JSONL audit entries to `${TALKING_STICK_DATA_DIR}/update-migrations.log`.
+Stale MCP cleanup is strict for OpenCode JSON entries: it removes only the canonical `mcp.talking-stick` value with `["tt", "mcp"]` and leaves hand-edited entries alone. Claude Code, Codex, and Gemini cleanup uses their own `mcp remove` commands when the old server name exists. Grok Build has no Talking Stick MCP registration path; install is native skill plus hook only. Every cleanup run appends JSONL audit entries to `${TALKING_STICK_DATA_DIR}/update-migrations.log`.
 
-Human CLI invocations also perform a silent best-effort sync for already-installed file-based skills in Claude Code, Codex, and OpenCode. If the installed skill is a copy, it is refreshed from the bundled skill; if it is a stale symlink, it is relinked. Missing harness config directories and missing skill installs are skipped. Gemini skills are managed by Gemini's own registry, so use `tt install gemini` after updating when needed.
+Human CLI invocations also perform a silent best-effort sync for already-installed file-based skills in Claude Code, Codex, Grok Build, and OpenCode. If the installed skill is a copy, it is refreshed from the bundled skill; if it is a stale symlink, it is relinked. Missing harness config directories and missing skill installs are skipped. Gemini skills are managed by Gemini's own registry, so use `tt install gemini` after updating when needed.
 
 ## Human CLI
 
@@ -189,7 +190,7 @@ tt state [path]                                           # full room state
 tt events [path] [--after N] [--limit N] [--wait|--follow] [--event TYPE[,TYPE]] [--target self|any|agent]  # room event log; --wait/--follow long-polls
 tt msg send <recipient|room> <body...> [--interrupt] [--stdin] [--path DIR]  # send an OOB message
 tt msg recv [--wait|--follow] [--from agent] [--after N] [--target self|any|agent] [--path DIR]  # receive OOB messages
-tt instructions show [path] [--harness claude|codex|gemini|opencode|all] [--scope effective|bundled|user|project]  # show collaboration prompt
+tt instructions show [path] [--harness claude|codex|gemini|grok|opencode|all] [--scope effective|bundled|user|project]  # show collaboration prompt
 tt instructions edit [path] [--user|--project]             # edit user or project prompt
 tt instructions reset [path] (--user|--project)            # delete a user or project prompt
 tt release [path] --status TEXT --next-action TEXT        # normal handoff
@@ -216,7 +217,8 @@ By default, `tt` behaves like a human CLI and resolves to `human:<username>` onl
 
 Harness-aware CLI identity is resolved before the human fallback:
 
-- Known harness environment markers such as `CLAUDECODE=1`, `CODEX_THREAD_ID`, `GEMINI_CLI=1`, or `OPENCODE=1` make `tt` derive a harness-style identity automatically.
+- Known harness environment markers such as `CLAUDECODE=1`, `CODEX_THREAD_ID`, `GEMINI_CLI=1`, `CMUX_AGENT_LAUNCH_KIND=grok`, or `OPENCODE=1` make `tt` derive a harness-style identity automatically. The cmux Grok marker is optional; Grok Build also works without cmux by walking process ancestry for a `grok` root process.
+- Grok Build's installed hook records hook-only `GROK_SESSION_ID` context into `${TALKING_STICK_DATA_DIR}/grok-sessions.jsonl`, letting later Grok-launched `tt` calls upgrade from process identity to the real Grok session id. `GROK_SESSION_ID` by itself is not treated as a normal shell marker, and the hook is not required for basic Grok detection.
 - Set `TT_HARNESS_AGENT_ID=<agent-id>` if the harness wants to export the exact agent id directly.
 - Set `TT_HARNESS_EXPORT=1` only when you need ancestry-based harness detection without a known harness environment marker.
 

package/dist/atomic-write.js

@@ -0,0 +1,21 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+export function writeFileAtomic(filePath, data) {
+    const directory = path.dirname(filePath);
+    fs.mkdirSync(directory, { recursive: true });
+    const tempPath = path.join(directory, `.${path.basename(filePath)}.${process.pid}.${Date.now()}.${crypto.randomUUID()}.tmp`);
+    try {
+        fs.writeFileSync(tempPath, data);
+        fs.renameSync(tempPath, filePath);
+    }
+    catch (error) {
+        try {
+            fs.rmSync(tempPath, { force: true });
+        }
+        catch {
+            // Best effort cleanup for failed writes.
+        }
+        throw error;
+    }
+}

package/dist/cli/grok-session-hook.js

@@ -0,0 +1,69 @@
+import { createSystemProcessInspector } from "../process-utils.js";
+import { appendGrokSessionRecord } from "../grok-session-store.js";
+import { findHarnessRootInAncestry } from "../identity.js";
+export async function runGrokSessionHookCommand(options = {}) {
+    try {
+        const env = options.env ?? process.env;
+        const input = parseHookInput(options.stdin ?? await readStdin());
+        const sessionId = firstNonEmptyString(env.GROK_SESSION_ID, input.sessionId);
+        const workspaceRoot = firstNonEmptyString(env.GROK_WORKSPACE_ROOT, env.CLAUDE_PROJECT_DIR, input.workspaceRoot);
+        if (!sessionId || !workspaceRoot) {
+            return;
+        }
+        const event = firstNonEmptyString(env.GROK_HOOK_EVENT, input.hookEventName) ?? "unknown";
+        const inspector = options.inspector ?? createSystemProcessInspector();
+        const parentPid = options.parentPid ?? process.ppid;
+        const parentInspection = inspector.inspect(parentPid);
+        const grokRoot = findHarnessRootInAncestry("grok", parentPid, parentInspection, inspector, 20);
+        const record = {
+            source: "grok_hook",
+            grok_session_id: sessionId,
+            workspace_root: workspaceRoot,
+            cwd: firstNonEmptyString(input.cwd),
+            event,
+            observed_at: firstNonEmptyString(input.timestamp) ??
+                (options.now ?? new Date()).toISOString(),
+            grok_pid: grokRoot?.pid ?? null,
+            grok_process_started_at: grokRoot?.startTime ?? null
+        };
+        appendGrokSessionRecord(record, { logPath: options.logPath });
+    }
+    catch {
+        // Grok hooks must fail open. Identity can fall back to pid-root detection
+        // when the hook cannot record a session row.
+    }
+}
+function parseHookInput(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return {};
+    try {
+        const parsed = JSON.parse(trimmed);
+        return isObjectRecord(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        let raw = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => {
+            raw += chunk;
+        });
+        process.stdin.on("error", reject);
+        process.stdin.on("end", () => resolve(raw));
+    });
+}
+function firstNonEmptyString(...values) {
+    for (const value of values) {
+        if (typeof value === "string" && value.trim().length > 0) {
+            return value.trim();
+        }
+    }
+    return null;
+}
+function isObjectRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/cli/guardian.js

@@ -103,8 +103,46 @@ export async function spawnGuardian(input) {
         const inspector = createSystemProcessInspector();
         let stdout = "";
         let stderr = "";
+        let settled = false;
+        const cleanup = () => {
+            clearTimeout(timeout);
+            child.stdout?.removeAllListeners();
+            child.stderr?.removeAllListeners();
+            child.removeAllListeners("exit");
+            child.removeAllListeners("error");
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+        };
+        const killChild = () => {
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                // Best effort cleanup for a child that failed readiness.
+            }
+        };
+        const rejectOnce = (error, kill = false) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (kill) {
+                killChild();
+            }
+            cleanup();
+            reject(error);
+        };
+        const resolveOnce = (value) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            cleanup();
+            child.unref();
+            resolve(value);
+        };
         const timeout = setTimeout(() => {
-            reject(new Error("Guardian did not signal readiness in time."));
+            rejectOnce(new Error("Guardian did not signal readiness in time."), true);
         }, GUARD_READY_TIMEOUT_MS);
         child.stdout?.setEncoding("utf8");
         child.stderr?.setEncoding("utf8");
@@ -113,15 +151,11 @@ export async function spawnGuardian(input) {
             if (!stdout.includes(GUARD_READY)) {
                 return;
             }
-            clearTimeout(timeout);
-            child.stdout?.destroy();
-            child.stderr?.destroy();
-            child.unref();
             if (!child.pid) {
-                reject(new Error("Guardian started without a PID."));
+                rejectOnce(new Error("Guardian started without a PID."), true);
                 return;
             }
-            resolve({
+            resolveOnce({
                 pid: child.pid,
                 process_started_at: inspector.inspect(child.pid)?.startTime ?? null
             });
@@ -130,8 +164,10 @@ export async function spawnGuardian(input) {
             stderr += chunk;
         });
         child.on("exit", (code) => {
-            clearTimeout(timeout);
-            reject(new Error(`Guardian exited before readiness (code ${code ?? "unknown"}): ${stderr.trim()}`));
+            rejectOnce(new Error(`Guardian exited before readiness (code ${code ?? "unknown"}): ${stderr.trim()}`));
+        });
+        child.on("error", (error) => {
+            rejectOnce(error instanceof Error ? error : new Error(String(error)));
         });
     });
 }

package/dist/cli/install-commands.js

@@ -1,16 +1,13 @@
 import { spawn } from "node:child_process";
-import { SUPPORTED_HARNESSES, detectHarness, parseHarnessList, planUninstall, runAction } from "../install.js";
+import { SUPPORTED_HARNESSES, detectHarness, parseHarnessList, planGrokSessionHookInstall, planGrokSessionHookUninstall, planUninstall, runAction } from "../install.js";
 import { planSkillInstall, planSkillUninstall } from "../skill-install.js";
 import { resolveDataDir } from "../config.js";
 import { FileAuditLog, defaultAuditLogPath } from "../install-audit.js";
 import { removeStaleMcpRegistrations } from "../install-migration.js";
 import { detectInstallSource, isPackageManager, planSelfUpdate, resolveCurrentBinaryPath } from "../self-update.js";
 import { readPackageVersion, runStaleMcpCleanup } from "../update-migration.js";
-import { getStringOption, hasOption, normalizeBooleanFlag } from "./parser.js";
+import { getStringOption, hasOption } from "./parser.js";
 export async function runInstallCommand(parsed) {
-    normalizeBooleanFlag(parsed, "print");
-    normalizeBooleanFlag(parsed, "copy");
-    normalizeBooleanFlag(parsed, "link");
     const harnesses = selectHarnesses(parsed);
     const dryRun = hasOption(parsed, "print");
     const installOptions = {
@@ -32,7 +29,6 @@ export async function runInstallCommand(parsed) {
     printInstructionHint(results);
 }
 export async function runUninstallCommand(parsed) {
-    normalizeBooleanFlag(parsed, "print");
     const harnesses = selectHarnesses(parsed);
     const dryRun = hasOption(parsed, "print");
     const installOptions = { skipMissing: true };
@@ -48,9 +44,6 @@ export async function runUninstallCommand(parsed) {
     reportCleanupResults(await runCleanup(harnesses, "uninstall", installOptions), "uninstall");
 }
 export async function runInstallSkillCommand(parsed) {
-    normalizeBooleanFlag(parsed, "print");
-    normalizeBooleanFlag(parsed, "copy");
-    normalizeBooleanFlag(parsed, "link");
     const harnesses = selectHarnesses(parsed);
     const dryRun = hasOption(parsed, "print");
     const link = resolveSkillInstallLinkMode(parsed);
@@ -66,7 +59,6 @@ export async function runInstallSkillCommand(parsed) {
     reportInstallResults(results, "install");
 }
 export async function runUninstallSkillCommand(parsed) {
-    normalizeBooleanFlag(parsed, "print");
     const harnesses = selectHarnesses(parsed);
     const dryRun = hasOption(parsed, "print");
     const installOptions = { skipMissing: true };
@@ -81,7 +73,6 @@ export async function runUninstallSkillCommand(parsed) {
     reportInstallResults(results, "uninstall");
 }
 export async function runSelfUpdateCommand(parsed, cliEntryUrl) {
-    normalizeBooleanFlag(parsed, "print");
     const dryRun = hasOption(parsed, "print");
     const managerOverride = getStringOption(parsed, "manager");
     let source;
@@ -121,7 +112,6 @@ export async function runSelfUpdateCommand(parsed, cliEntryUrl) {
     process.stdout.write("Done. Restart any long-running harness sessions to pick up the new tt.\n");
 }
 export async function runMcpMigrationCommand(parsed) {
-    normalizeBooleanFlag(parsed, "quiet");
     const reason = parseAuditReason(getStringOption(parsed, "reason") ?? "manual");
     const quiet = hasOption(parsed, "quiet");
     const cleanup = await runStaleMcpCleanup({
@@ -145,7 +135,7 @@ function resolveSkillInstallLinkMode(parsed) {
     return true;
 }
 function planInstallActions(harnesses, installOptions) {
-    return harnesses.map((harness) => planSkillInstall(harness, installOptions));
+    return harnesses.flatMap((harness) => planInstallActionsForHarness(harness, installOptions));
 }
 function planUninstallActions(harnesses, installOptions) {
     return harnesses.flatMap((harness) => [
@@ -153,6 +143,14 @@ function planUninstallActions(harnesses, installOptions) {
             ...installOptions,
             skipMissing: false
         }),
+        ...(harness === "grok"
+            ? [
+                planGrokSessionHookUninstall({
+                    ...installOptions,
+                    skipMissing: false
+                })
+            ]
+            : []),
         planUninstall(harness, installOptions)
     ]);
 }
@@ -160,14 +158,31 @@ function planCleanupActions(harnesses, installOptions) {
     return harnesses.map((harness) => planUninstall(harness, installOptions));
 }
 async function runSkillInstall(harness, installOptions) {
-    const skillAction = planSkillInstall(harness, installOptions);
-    const skillResult = await runAction(skillAction, installOptions);
-    return [skillResult];
+    const actions = planInstallActionsForHarness(harness, installOptions);
+    return Promise.all(actions.map((action) => runAction(action, installOptions)));
 }
 async function runSkillUninstall(harness, installOptions) {
-    const skillAction = planSkillUninstall(harness, installOptions);
-    const skillResult = await runAction(skillAction, installOptions);
-    return [skillResult];
+    const actions = [
+        planSkillUninstall(harness, {
+            ...installOptions,
+            skipMissing: false
+        }),
+        ...(harness === "grok"
+            ? [
+                planGrokSessionHookUninstall({
+                    ...installOptions,
+                    skipMissing: false
+                })
+            ]
+            : [])
+    ];
+    return Promise.all(actions.map((action) => runAction(action, installOptions)));
+}
+function planInstallActionsForHarness(harness, installOptions) {
+    return [
+        planSkillInstall(harness, installOptions),
+        ...(harness === "grok" ? [planGrokSessionHookInstall(installOptions)] : [])
+    ];
 }
 async function runCleanup(harnesses, reason, installOptions) {
     const dataDir = resolveDataDir();

package/dist/cli/instructions-commands.js

@@ -24,8 +24,6 @@ export async function handleInstructionsCommand(parsed) {
     }
 }
 function handleInstructionsShowCommand(parsed) {
-    repairBooleanFlag(parsed, "json", 0);
-    repairBooleanFlag(parsed, "text", 0);
     const contextPath = resolveContextPathArg(parsed);
     const scope = parseInstructionScope(getStringOption(parsed, "scope"));
     const identity = deriveCliIdentity(parsed);
@@ -45,10 +43,6 @@ function handleInstructionsShowCommand(parsed) {
     });
 }
 async function handleInstructionsEditCommand(parsed) {
-    repairBooleanFlag(parsed, "json", 0);
-    repairBooleanFlag(parsed, "text", 0);
-    repairBooleanFlag(parsed, "user", 0);
-    repairBooleanFlag(parsed, "project", 0);
     const contextPath = resolveContextPathArg(parsed);
     const scope = resolveEditableScope(parsed, false);
     const result = await editInstructions({
@@ -66,10 +60,6 @@ async function handleInstructionsEditCommand(parsed) {
     });
 }
 function handleInstructionsResetCommand(parsed) {
-    repairBooleanFlag(parsed, "json", 0);
-    repairBooleanFlag(parsed, "text", 0);
-    repairBooleanFlag(parsed, "user", 0);
-    repairBooleanFlag(parsed, "project", 0);
     const contextPath = resolveContextPathArg(parsed);
     const scope = resolveEditableScope(parsed, true);
     const result = resetInstructions({
@@ -104,10 +94,3 @@ function resolveContextPathArg(parsed) {
     }
     return pathOption ?? parsed.positionals[0] ?? process.cwd();
 }
-function repairBooleanFlag(parsed, key, insertAt) {
-    const value = parsed.options.get(key);
-    if (typeof value === "string") {
-        parsed.positionals.splice(insertAt, 0, value);
-        parsed.options.set(key, true);
-    }
-}

package/dist/cli/msg-commands.js

@@ -29,8 +29,6 @@ async function handleMsgSendCommand(runtime, parsed) {
     const identity = deriveCliIdentity(parsed);
     const session = resolveSessionForNotes(runtime, parsed, identity);
     const usesRoomFlag = hasOption(parsed, "room");
-    repairBooleanFlag(parsed, "room", 0);
-    repairBooleanFlag(parsed, "interrupt", usesRoomFlag ? 0 : 1);
     const recipientSelector = usesRoomFlag ? "room" : parsed.positionals[0];
     if (!recipientSelector) {
         throw new Error("Usage: tt msg send <recipient|room> <body...> [--interrupt] [--stdin].");
@@ -69,13 +67,6 @@ async function handleMsgRecvCommand(runtime, parsed) {
         force_tail_cursor: false
     });
 }
-function repairBooleanFlag(parsed, key, insertAt) {
-    const value = parsed.options.get(key);
-    if (typeof value === "string") {
-        parsed.positionals.splice(insertAt, 0, value);
-        parsed.options.set(key, true);
-    }
-}
 function shortEventId(eventId) {
     return eventId.slice(0, 8);
 }

package/dist/cli/output.js

@@ -164,7 +164,7 @@ Commands:
   tt events [path] [--after N] [--limit N] [--wait|--follow] [--event TYPE[,TYPE]] [--target self|any|agent]
   tt msg send <recipient|room> <body...> [--interrupt] [--stdin] [--path DIR]
   tt msg recv [--wait|--follow] [--from agent] [--after N] [--target self|any|agent] [--path DIR]
-  tt instructions show [path] [--harness claude|codex|gemini|opencode|all] [--scope effective|bundled|user|project]
+  tt instructions show [path] [--harness claude|codex|gemini|grok|opencode|all] [--scope effective|bundled|user|project]
   tt instructions edit [path] [--user|--project]
   tt instructions reset [path] (--user|--project)
   tt release [path] (--status TEXT --next-action TEXT | --stdin)

package/dist/cli/parser.js

@@ -1,3 +1,26 @@
+const BOOLEAN_FLAGS = new Set([
+    "all",
+    "copy",
+    "events",
+    "explain",
+    "follow",
+    "force",
+    "force-new",
+    "help",
+    "interrupt",
+    "json",
+    "link",
+    "operator-requested",
+    "park",
+    "print",
+    "project",
+    "quiet",
+    "room",
+    "stdin",
+    "text",
+    "user",
+    "wait"
+]);
 export function parseCommand(argv) {
     const [name = "", ...rest] = argv;
     const options = new Map();
@@ -9,6 +32,10 @@ export function parseCommand(argv) {
             continue;
         }
         const key = token.slice(2);
+        if (BOOLEAN_FLAGS.has(key)) {
+            options.set(key, true);
+            continue;
+        }
         const next = rest[index + 1];
         if (!next || next.startsWith("--")) {
             options.set(key, true);
@@ -33,18 +60,14 @@ export function requireStringOption(parsed, key) {
     }
     return value;
 }
-export function normalizeBooleanFlag(parsed, key) {
-    const value = parsed.options.get(key);
-    if (typeof value === "string") {
-        parsed.positionals.unshift(value);
-        parsed.options.set(key, true);
-    }
-}
 export function parseOptionalInteger(parsed, key) {
     const value = getStringOption(parsed, key);
     if (!value) {
         return undefined;
     }
+    if (!/^\d+$/.test(value)) {
+        throw new Error(`--${key} must be an integer.`);
+    }
     const parsedValue = Number.parseInt(value, 10);
     if (!Number.isInteger(parsedValue)) {
         throw new Error(`--${key} must be an integer.`);

package/dist/cli/registry.js

@@ -1,4 +1,5 @@
 import { runGuardCommand } from "./guardian.js";
+import { runGrokSessionHookCommand } from "./grok-session-hook.js";
 import { runInstallCommand, runMcpMigrationCommand, runSelfUpdateCommand, runUninstallCommand } from "./install-commands.js";
 import { handleInstructionsCommand } from "./instructions-commands.js";
 import { handleMsgCommand } from "./msg-commands.js";
@@ -15,6 +16,15 @@ export const COMMAND_REGISTRY = [
         description: "Run an internal lease heartbeat guardian.",
         handler: ({ parsed }) => runGuardCommand(parsed)
     },
+    {
+        name: "grok-session-hook",
+        needsRuntime: false,
+        startupMaintenance: false,
+        internal: true,
+        usage: "tt grok-session-hook",
+        description: "Record Grok hook session context for identity resolution.",
+        handler: () => runGrokSessionHookCommand()
+    },
     {
         name: "install",
         needsRuntime: false,

package/dist/cli/room-commands.js

@@ -1,7 +1,7 @@
 import { deriveCliIdentity, resolveCliIdentity } from "./identity.js";
 import { removeCliSession, removeCliSessionsForRoom, resolveCliSessionPath } from "../index.js";
 import { stopGuardian } from "./guardian.js";
-import { getStringOption, hasOption, normalizeBooleanFlag, parseOptionalInteger } from "./parser.js";
+import { getStringOption, hasOption, parseOptionalInteger } from "./parser.js";
 import { formatRelativeTime, printResult } from "./output.js";
 import { parseEventTypeFilter, runEventStream } from "./event-stream.js";
 import { resolveSessionForReads, upsertSessionFromJoin } from "./session.js";
@@ -129,8 +129,6 @@ export function handleStateCommand(runtime, parsed) {
     });
 }
 export async function handleEventsCommand(runtime, parsed) {
-    normalizeBooleanFlag(parsed, "wait");
-    normalizeBooleanFlag(parsed, "follow");
     const identity = deriveCliIdentity(parsed);
     const session = resolveSessionForReads(runtime, parsed, identity);
     if (hasOption(parsed, "wait") || hasOption(parsed, "follow")) {

package/dist/cli/turn-commands.js

@@ -2,13 +2,11 @@ import { clearCliSessionLease, createSystemProcessInspector, findCliSessionByRoo
 import { checkGuardianLiveness, spawnGuardian, stopGuardian } from "./guardian.js";
 import { resolveHandoff } from "./handoff.js";
 import { deriveCliIdentity, resolveTakeoverReason, shouldUseOperatorOverride } from "./identity.js";
-import { getStringOption, hasOption, normalizeBooleanFlag, parseRequiredInteger, parseWaitTimeout } from "./parser.js";
+import { getStringOption, hasOption, parseRequiredInteger, parseWaitTimeout } from "./parser.js";
 import { resolveTargetFilter } from "./event-stream.js";
 import { formatWaitResult, printResult } from "./output.js";
 import { requireLeaseSession, upsertSessionFromJoin } from "./session.js";
 export async function handleWaitCommand(runtime, parsed, isTry, cliEntryUrl) {
-    normalizeBooleanFlag(parsed, "park");
-    normalizeBooleanFlag(parsed, "events");
     const park = hasOption(parsed, "park");
     const includeEvents = hasOption(parsed, "events");
     const afterEventSeq = includeEvents

package/dist/cli.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { isProtocolError } from "./index.js";
 import { parseCommand } from "./cli/parser.js";
-import { printHelp } from "./cli/output.js";
+import { printHelp, shouldUseJson } from "./cli/output.js";
 import { getCommand } from "./cli/registry.js";
 import { createRuntime } from "./cli/runtime.js";
 import { runStartupMaintenance } from "./cli/startup-maintenance.js";
@@ -49,12 +49,24 @@ function isDirectExecution() {
 }
 if (isDirectExecution()) {
     await runCli().catch((error) => {
-        const message = isProtocolError(error)
-            ? JSON.stringify(error.toJSON(), null, 2)
-            : error instanceof Error
+        const parsed = parseCommand(process.argv.slice(2));
+        if (shouldUseJson(parsed)) {
+            const payload = isProtocolError(error)
+                ? error.toJSON()
+                : {
+                    error: "cli_error",
+                    message: error instanceof Error ? error.message : String(error)
+                };
+            process.stderr.write(`${JSON.stringify(payload, null, 2)}\n`);
+        }
+        else {
+            const message = isProtocolError(error)
                 ? error.message
-                : String(error);
-        process.stderr.write(`${message}\n`);
+                : error instanceof Error
+                    ? error.message
+                    : String(error);
+            process.stderr.write(`${message}\n`);
+        }
         process.exit(1);
     });
 }