@aiwg/cli 2026.10.1 → 2026.10.4

package/dist/src/process/cli-command.mjs

@@ -0,0 +1,75 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+// Share PATH/PATHEXT lookup with callers that can launch arbitrary batch files.
+function* executableCandidates(command, searchPath, pathExt, preferNative = false, cwd = process.cwd()) {
+  const candidates = path.isAbsolute(command)
+    ? [command]
+    : /[\\/]/.test(command)
+      ? [path.resolve(cwd, ...command.split(/[\\/]/))]
+      : searchPath.split(';').filter(Boolean).map(dir => path.join(dir, command));
+  for (const candidate of candidates) {
+    const pathExtensions = pathExt.split(';').filter(Boolean).map(ext => ext.toLowerCase());
+    const extension = path.extname(candidate).toLowerCase();
+    const extensions = extension && (pathExtensions.includes(extension) || existsSync(candidate))
+      ? ['']
+      : pathExtensions;
+    if (preferNative) {
+      extensions.sort((a, b) => Number(!/\.(?:exe|com)$/i.test(a)) - Number(!/\.(?:exe|com)$/i.test(b)));
+    }
+    for (const extension of extensions) {
+      const executable = `${candidate}${extension}`;
+      if (existsSync(executable)) yield executable;
+    }
+  }
+}
+
+export function resolveExecutable(
+  command,
+  platform = process.platform,
+  searchPath = process.env.PATH ?? '',
+  pathExt = process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD',
+  cwd = process.cwd(),
+) {
+  if (platform !== 'win32') return command;
+  for (const executable of executableCandidates(command, searchPath, pathExt, true, cwd)) {
+    return executable;
+  }
+  return command;
+}
+
+// npm's Windows shims cannot be spawned directly without a shell. Resolve only
+// their standard Node invocation; never evaluate batch contents or shell args.
+export function cliCommand(
+  command,
+  args,
+  platform = process.platform,
+  searchPath = process.env.PATH ?? '',
+  pathExt = process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD',
+  cwd = process.cwd(),
+) {
+  if (platform !== 'win32') return [command, args];
+  for (const shim of executableCandidates(command, searchPath, pathExt, false, cwd)) {
+    if (!/\.(?:cmd|bat)$/i.test(shim)) return [shim, args];
+    const contents = readFileSync(shim, 'utf8');
+    const entry = contents.match(
+      /^\s*(?:endLocal & goto #_undefined_# 2>NUL \|\| title %COMSPEC% & )?(?:set PATHEXT=%PATHEXT:;.JS;=;% & )?"%_prog%"\s+((?:(?:"[^"\r\n&|<>^%]*"|[^\s"&|<>^%]+)\s+)*)"%dp0%\\([^"\r\n]+)"\s+%\*\s*$/m,
+    );
+    // Node distributions bundle npm/npx launchers with named entry variables
+    // rather than cmd-shim's _prog invocation. Resolve their local JS entry.
+    const bundled = !entry && /^(?:npm|npx)\.cmd$/i.test(path.basename(shim))
+      ? contents.match(/^SET "(NPM|NPX)_CLI_JS=%~dp0\\(node_modules\\npm\\bin\\(?:npm|npx)-cli\.js)"\s*$/im)
+      : null;
+    if (!entry && (!bundled || !contents.includes(`"%NODE_EXE%" "%${bundled[1]}_CLI_JS%" %*`))) {
+      throw new Error(`Unsupported Windows CLI shim: ${shim}`);
+    }
+    const nodeArgs = entry
+      ? Array.from(entry[1].matchAll(/"([^"]*)"|([^\s"]+)/g), match => match[1] ?? match[2])
+      : [];
+    const script = path.resolve(path.dirname(shim), ...(entry ? entry[2] : bundled[2]).split('\\'));
+    if (!existsSync(script)) throw new Error(`Missing Windows CLI entry point: ${script}`);
+    const localNode = path.join(path.dirname(shim), 'node.exe');
+    return [existsSync(localNode) ? localNode : process.execPath, [...nodeArgs, script, ...args]];
+  }
+  return [command, args];
+}

package/dist/src/process/signal-child.d.mts

@@ -0,0 +1,6 @@
+import type { ChildProcess } from 'node:child_process';
+
+export function signalChild(
+  child: Pick<ChildProcess, 'pid' | 'kill'> | null | undefined,
+  signal?: NodeJS.Signals | number,
+): boolean;

package/dist/src/process/signal-child.mjs

@@ -0,0 +1,7 @@
+/** Signal only a child that acquired a real PID. Failed spawns can retain a
+ * native handle with PID zero until their asynchronous error event arrives.
+ * Keep native return/throw behavior so callers retain their stop semantics. */
+export function signalChild(child, signal) {
+  if (!Number.isSafeInteger(child?.pid) || child.pid <= 0) return false;
+  return !!child.kill(signal);
+}

package/dist/src/providers/capability-matrix.js

@@ -82,6 +82,14 @@ export function getProviderCapabilities(providerKey) {
     }
     return undefined;
 }
+/**
+ * Get the S0 route-feasibility row for a provider by key or alias.
+ * Returns undefined when the matrix carries no row (e.g. registry-only
+ * `generic`, which is not a matrix provider).
+ */
+export function getRouteFeasibility(providerKey) {
+    return getProviderCapabilities(providerKey)?.route_feasibility;
+}
 export function getAgentCapabilities(providerKey, agentType = 'default') {
     const caps = getProviderCapabilities(providerKey);
     if (!caps?.agent_capabilities)

package/dist/src/providers/capability-matrix.yaml

@@ -15,6 +15,22 @@ version: "1.0"
 providers:
   claude-code:
     display_name: Claude Code
+    aliases:
+      - claude
+    route_feasibility:
+      scope: in
+      identity: runtime-configured-only
+      evidence: H
+      channel: "claude -p --output-format stream-json --verbose; terminal result extraction"
+      fanout: unknown
+      probe_budget: { status: authorized, calls: 3, tokens: 30000, authorized_by: operator, authorized_at: "2026-10-07", hosts: [titan, noodle] }
+      coverage:
+        profile_issue: "roctinam/aiwg#2900"
+        source_date: "2026-10-08"
+        live_qualified: false
+        sources:
+          - "host-help: claude 2.1.295 on titan (--version/--help only)"
+          - "tools/ralph-external/lib/claude-adapter.mjs"
     status: stable
     daemon_tier: unsupported
     daemon_pty_adapter: false
@@ -77,6 +93,20 @@ providers:
 
   codex:
     display_name: OpenAI Codex
+    route_feasibility:
+      scope: in
+      identity: runtime-configured-only
+      evidence: H
+      channel: "codex debug models + exec --json -o F thread/turn/item/error event stream"
+      fanout: unknown
+      probe_budget: { status: authorized, calls: 3, tokens: 50000, authorized_by: operator, authorized_at: "2026-10-07", hosts: [titan, noodle] }
+      coverage:
+        profile_issue: "roctinam/aiwg#2897"
+        source_date: "2026-10-08"
+        live_qualified: false
+        sources:
+          - "host-help: codex-cli 0.161.0 on titan (--version/--help only); `codex mcp-server --help` still prints root help"
+          - "tools/ralph-external/lib/codex-adapter.mjs"
     aliases:
       - openai
     status: stable
@@ -146,6 +176,21 @@ providers:
 
   copilot:
     display_name: GitHub Copilot
+    aliases:
+      - github-copilot
+    route_feasibility:
+      scope: in
+      identity: runtime-configured-only
+      evidence: D
+      channel: "copilot -p --output-format json; scoped --allow-tool permissions"
+      fanout: unknown
+      probe_budget: { status: authorized, calls: 3, tokens: 30000, authorized_by: operator, authorized_at: "2026-10-07", hosts: [titan, noodle] }
+      coverage:
+        profile_issue: "roctinam/aiwg#2901"
+        source_date: "2026-10-08"
+        live_qualified: false
+        sources:
+          - "https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-programmatic-reference"
     status: stable
     daemon_tier: unsupported
     daemon_pty_adapter: false
@@ -181,6 +226,21 @@ providers:
 
   factory:
     display_name: Factory AI
+    aliases:
+      - factory-ai
+    route_feasibility:
+      scope: in
+      identity: runtime-configured-only
+      evidence: R
+      channel: "droid exec --output-format stream-json; terminal parser to qualify"
+      fanout: unknown
+      probe_budget: { status: authorized, calls: 3, tokens: 30000, authorized_by: operator, authorized_at: "2026-10-07", hosts: [titan, noodle] }
+      coverage:
+        profile_issue: "roctinam/aiwg#2902"
+        source_date: "2026-10-07"
+        live_qualified: false
+        sources:
+          - "tools/ralph-external/lib/factory-adapter.mjs"
     status: stable
     # droid CLI runs headless via `droid exec`; AIWG daemon provides persistence layer
     daemon_tier: unsupported
@@ -217,6 +277,20 @@ providers:
 
   cursor:
     display_name: Cursor IDE
+    route_feasibility:
+      scope: in
+      identity: runtime-configured-only
+      evidence: D
+      channel: "agent -p --output-format json; sandbox/permission profile to qualify"
+      fanout: unknown
+      probe_budget: { status: authorized, calls: 3, tokens: 30000, authorized_by: operator, authorized_at: "2026-10-07", hosts: [titan, noodle] }
+      coverage:
+        profile_issue: "roctinam/aiwg#2903"
+        source_date: "2026-10-08"
+        live_qualified: false
+        sources:
+          - "https://cursor.com/docs/cli/overview"
+          - "https://cursor.com/docs/cli/reference/output-format"
     status: stable
     # Cursor requires a display server (VS Code extension host) — daemon not supported
     daemon_tier: unsupported
@@ -253,6 +327,20 @@ providers:
 
   opencode:
     display_name: OpenCode
+    route_feasibility:
+      scope: in
+      identity: runtime-configured-only
+      evidence: R
+      channel: "opencode run --format json; JSONL framing to qualify"
+      fanout: unknown
+      probe_budget: { status: authorized, calls: 3, tokens: 30000, authorized_by: operator, authorized_at: "2026-10-07", hosts: [titan, noodle] }
+      coverage:
+        profile_issue: "roctinam/aiwg#2904"
+        source_date: "2026-10-07"
+        live_qualified: false
+        sources:
+          - "tools/ralph-external/lib/opencode-adapter.mjs"
+          - "https://opencode.ai/docs/cli/"
     status: stable
     daemon_tier: unsupported
     daemon_pty_adapter: false
@@ -288,6 +376,19 @@ providers:
 
   warp:
     display_name: Warp Terminal
+    route_feasibility:
+      scope: in
+      identity: runtime-configured-only
+      evidence: D
+      channel: "oz agent run --prompt/--model/--cwd/--profile; stdout capture"
+      fanout: unknown
+      probe_budget: { status: authorized, calls: 3, tokens: 30000, authorized_by: operator, authorized_at: "2026-10-07", hosts: [titan, noodle] }
+      coverage:
+        profile_issue: "roctinam/aiwg#2905"
+        source_date: "2026-10-08"
+        live_qualified: false
+        sources:
+          - "https://docs.warp.dev/agents/cli/oz-cli/"
     status: stable
     daemon_tier: unsupported
     daemon_pty_adapter: false
@@ -324,6 +425,28 @@ providers:
 
   windsurf:
     display_name: Devin Desktop
+    aliases:
+      - devin
+      - devin-desktop
+      - devin-local
+      - cascade
+    route_feasibility:
+      scope: out
+      identity: unavailable
+      evidence: R
+      channel: "none - no verified headless Desktop worker command; recheck B-OG-47"
+      fanout: unknown
+      probe_budget: { status: authorized, calls: 1, tokens: 0, authorized_by: operator, authorized_at: "2026-10-07", hosts: [titan, noodle] }
+      coverage:
+        profile_issue: null
+        source_date: "2026-10-08"
+        live_qualified: false
+        sources:
+          - "src/providers/provider-definitions.ts#windsurf"
+          - "https://docs.devin.ai/cli/reference/commands.md"
+          - "https://docs.devin.ai/_llms/en/desktop.md"
+        exclusion_gap: "Devin Desktop documents no headless worker command and no worker-serving MCP tool; its MCP settings configure clients, IDE startup is not inference."
+        recheck: "Rechecked 2026-10-08: Desktop unchanged, still OUT. Devin CLI documents `devin -p/--print`, `--model`, `--prompt-file`, `--permission-mode` and `--sandbox` (no JSON output or effort flag found; `devin acp` is ACP, `devin mcp` manages client servers). Devin CLI stays a distinct future-provider surface, not a windsurf alias, until registry support exists."
     status: stable
     # Devin Desktop uses the Windsurf compatibility surface and requires a VS Code host — daemon not supported
     daemon_tier: unsupported
@@ -361,6 +484,25 @@ providers:
 
   grokbot:
     display_name: Grok Bot
+    route_feasibility:
+      scope: out
+      identity: unavailable
+      evidence: R
+      channel: "none - desktop CreateAgent is not a headless subprocess contract; recheck B-OG-47"
+      fanout: unknown
+      probe_budget: { status: authorized, calls: 1, tokens: 0, authorized_by: operator, authorized_at: "2026-10-07", hosts: [titan, noodle] }
+      coverage:
+        profile_issue: null
+        source_date: "2026-10-08"
+        live_qualified: false
+        sources:
+          - "src/providers/provider-definitions.ts#grokbot"
+          - "https://docs.x.ai/grok-bot/overview.md"
+          - "https://docs.x.ai/grok-bot/skills-routines-and-automations.md"
+          - "https://docs.x.ai/grok-bot/computer-and-apps.md"
+          - "https://docs.x.ai/grok-bot/faq.md"
+        exclusion_gap: "Grok Bot runs Bots on xAI-hosted computers driven from desktop/mobile chat, routines and connectors; no documented local CLI, headless subprocess or worker-serving MCP tool."
+        recheck: "Rechecked 2026-10-08 against the official Grok Bot docs: no change, still OUT. Third-party bridges are not official interfaces and were not evaluated; desktop CreateAgent names are never synthesized into a command."
     status: stable
     # Multi-agent desktop assistant runtime. Distinct from Cursor IDE and from
     # xAI Grok Build / API. Native skill root is operator-configured via
@@ -403,6 +545,19 @@ providers:
 
   grok-build:
     display_name: Grok Build
+    route_feasibility:
+      scope: in
+      identity: runtime-configured-only
+      evidence: R
+      channel: "grok -p --output-format streaming-json; bounded parser + model/effort pinning"
+      fanout: unknown
+      probe_budget: { status: authorized, calls: 3, tokens: 30000, authorized_by: operator, authorized_at: "2026-10-07", hosts: [titan, noodle] }
+      coverage:
+        profile_issue: "roctinam/aiwg#2906"
+        source_date: "2026-10-07"
+        live_qualified: false
+        sources:
+          - "src/providers/grok-build-headless.ts"
     status: experimental
     # xAI Grok Build CLI/TUI. Distinct from Grok Bot (`grokbot`).
     # #2577: fixture-backed native subagents and background tasks; see
@@ -448,6 +603,20 @@ providers:
 
   hermes:
     display_name: Hermes
+    route_feasibility:
+      scope: in
+      identity: runtime-configured-only
+      evidence: H
+      channel: "hermes -z plain final + --usage-file; session-filtered log binding"
+      fanout: unknown
+      probe_budget: { status: authorized, calls: 3, tokens: 30000, authorized_by: operator, authorized_at: "2026-10-07", hosts: [titan, noodle] }
+      coverage:
+        profile_issue: "roctinam/aiwg#2912"
+        source_date: "2026-10-07"
+        live_qualified: false
+        sources:
+          - "host-help: hermes 0.20.6 on titan (2026-10-07 observation; not rechecked in this pass)"
+          - "/usr/local/lib/hermes-agent/mcp_serve.py"
     status: stable
     daemon_tier: unsupported
     daemon_pty_adapter: false
@@ -488,6 +657,22 @@ providers:
 
   muse:
     display_name: Muse Code
+    route_feasibility:
+      scope: in
+      identity: runtime-configured-only
+      evidence: H
+      channel: "model-catalog JSON + exec --json invocation-bound session logs"
+      fanout: unknown
+      probe_budget: { status: authorized, calls: 3, tokens: 30000, authorized_by: operator, authorized_at: "2026-10-07", hosts: [titan, noodle] }
+      coverage:
+        profile_issue: "roctinam/aiwg#2898"
+        source_date: "2026-10-08"
+        live_qualified: false
+        sources:
+          - "host-help: Muse Code 1.4.4 (1.4.4-R5419.1) on titan (--version/--help only)"
+          - "tools/ralph-external/lib/muse-adapter.mjs"
+          - "test/fixtures/providers/muse/direct-manifest.json (synthetic only; strict finals/live controls remain unqualified)"
+          - "docs/providers/muse-ralph-exec.md (manual smoke run and S1 blockers)"
     status: stable
     # Meta's terminal/CI coding agent (Muse Spark-powered). Explicitly not a
     # model-API surface: Glimmer/Image/Voice are out of scope.
@@ -534,6 +719,19 @@ providers:
 
   openclaw:
     display_name: OpenClaw
+    route_feasibility:
+      scope: in
+      identity: runtime-configured-only
+      evidence: D
+      channel: "openclaw agent exec --json; workspace/settings mapping to qualify"
+      fanout: unknown
+      probe_budget: { status: authorized, calls: 3, tokens: 30000, authorized_by: operator, authorized_at: "2026-10-07", hosts: [titan, noodle] }
+      coverage:
+        profile_issue: "roctinam/aiwg#2907"
+        source_date: "2026-10-08"
+        live_qualified: false
+        sources:
+          - "https://docs.openclaw.ai/cli/agent"
     status: stable
     daemon_tier: unsupported
     daemon_pty_adapter: false
@@ -567,6 +765,25 @@ providers:
 
   openhuman:
     display_name: OpenHuman
+    aliases:
+      - tinyhumansai
+    route_feasibility:
+      scope: in
+      identity: runtime-configured-only
+      evidence: D
+      channel: "openhuman-core --model M call --method openhuman.agent_chat --params-stdin; conductor-framed params JSON on stdin to EOF, final JSON stdout, no event stream"
+      fanout: unknown
+      probe_budget: { status: proposed, calls: 3, tokens: 30000 }
+      coverage:
+        profile_issue: "roctinam/aiwg#2911"
+        source_date: "2026-10-08"
+        live_qualified: false
+        sources:
+          - "https://github.com/tinyhumansai/openhuman/blob/216ea322a3c1269dada70751ac5c08eac7dc7596/crates/openhuman-core/src/core/cli.rs"
+          - "https://github.com/tinyhumansai/openhuman/blob/216ea322a3c1269dada70751ac5c08eac7dc7596/crates/openhuman-core/src/agent/schemas.rs"
+          - "https://github.com/tinyhumansai/openhuman/blob/216ea322a3c1269dada70751ac5c08eac7dc7596/crates/openhuman-core/src/mcp/server/tools/specs.rs"
+          - "https://github.com/tinyhumansai/openhuman/releases/tag/v0.64.14"
+        recheck: "Rechecked 2026-10-08 and promoted into S1 (doc/source-only, unqualified): `openhuman-core --model M call --method openhuman.agent_chat --params-stdin` reads the `message`, `model_override` and `cwd` params as JSON from stdin until EOF, runs one in-process agent turn and prints the JSON result on stdout; the conductor frames the params from the brief so prompt text never enters argv. Profile pinned to 0.64.14; live qualification is an open S1 blocker (not installed on an authorized host, budget proposed). Effort, step cap, approval/sandbox mapping and child fan-out are unknown. Native `openhuman-core mcp` `agent.run_subagent` takes only `agent_id`/`prompt` (no model, effort or workspace pin) and may nest subagents, so it is not a qualifying worker MCP tool."
     status: experimental
     # tinyhumansai/openhuman — OSS personal-AI runtime (Rust core + Tauri shell).
     # AIWG-convention-aware out of the box (.agents/, AGENTS.md, .claude/, .codex/).
@@ -605,6 +822,20 @@ providers:
 
   antigravity:
     display_name: Google Antigravity CLI
+    route_feasibility:
+      scope: in
+      identity: runtime-configured-only
+      evidence: R
+      channel: "agy -p stream-json per provider-contract; fixture-qualified flags only"
+      fanout: unknown
+      probe_budget: { status: authorized, calls: 3, tokens: 30000, authorized_by: operator, authorized_at: "2026-10-07", hosts: [titan, noodle] }
+      coverage:
+        profile_issue: "roctinam/aiwg#2908"
+        source_date: "2026-10-07"
+        live_qualified: false
+        sources:
+          - "agentic/code/providers/antigravity/provider-contract.v1.json"
+          - "https://antigravity.google/docs/cli/headless/"
     aliases:
       - agy
     status: experimental
@@ -650,6 +881,19 @@ providers:
 
   deepseek-harness:
     display_name: DeepSeek Harness
+    route_feasibility:
+      scope: in
+      identity: runtime-configured-only
+      evidence: R
+      channel: "dsh --profile headless + validated Cordis route patch; no guessed --model flag"
+      fanout: unknown
+      probe_budget: { status: authorized, calls: 3, tokens: 30000, authorized_by: operator, authorized_at: "2026-10-07", hosts: [titan, noodle] }
+      coverage:
+        profile_issue: "roctinam/aiwg#2909"
+        source_date: "2026-10-07"
+        live_qualified: false
+        sources:
+          - "tools/ralph-external/lib/deepseek-harness-adapter.mjs"
     aliases:
       - dsh
     status: experimental
@@ -692,6 +936,19 @@ providers:
 
   pi:
     display_name: Pi Coding Agent
+    route_feasibility:
+      scope: in
+      identity: runtime-configured-only
+      evidence: R
+      channel: "pi --mode json --model/--thinking/--tools; closed stdin, no RPC abort"
+      fanout: unknown
+      probe_budget: { status: authorized, calls: 3, tokens: 30000, authorized_by: operator, authorized_at: "2026-10-07", hosts: [titan, noodle] }
+      coverage:
+        profile_issue: "roctinam/aiwg#2910"
+        source_date: "2026-10-07"
+        live_qualified: false
+        sources:
+          - "tools/ralph-external/lib/pi-adapter.mjs"
     aliases:
       - pi-coding-agent
     status: experimental
@@ -733,6 +990,19 @@ providers:
 
   omp:
     display_name: Oh My Pi
+    route_feasibility:
+      scope: in
+      identity: runtime-configured-only
+      evidence: R
+      channel: "omp --mode json --model/--thinking/--profile; --no-tools for text-only"
+      fanout: unknown
+      probe_budget: { status: authorized, calls: 3, tokens: 30000, authorized_by: operator, authorized_at: "2026-10-07", hosts: [titan, noodle] }
+      coverage:
+        profile_issue: "roctinam/aiwg#2910"
+        source_date: "2026-10-07"
+        live_qualified: false
+        sources:
+          - "tools/ralph-external/lib/omp-adapter.mjs"
     aliases:
       - oh-my-pi
     status: experimental

package/dist/src/providers/deployed-skill-roots.js

@@ -0,0 +1,20 @@
+import path from 'node:path';
+import { getProviderArtifactPathStrings, getProviderKernelSkillPath } from './provider-definitions.js';
+import { resolveGrokbotSkillsDir } from './grokbot-paths.js';
+/** All shared-copier tiers, including adapter mirrors. */
+export function deployedSkillRoots(target, provider) {
+    const roots = [(getProviderArtifactPathStrings(provider) ?? getProviderArtifactPathStrings('claude'))?.skills,
+        getProviderKernelSkillPath(provider) || getProviderKernelSkillPath('claude')];
+    if (provider === 'muse')
+        roots.push('.agents/.aiwg/skills');
+    if (provider === 'grok-build')
+        roots.push('.grok/.aiwg/skills');
+    if (provider === 'grokbot') {
+        const root = resolveGrokbotSkillsDir();
+        if (root)
+            roots.push(root, path.join(root, '.aiwg', 'skills'));
+    }
+    return [...new Set(roots.filter((root) => Boolean(root))
+            .map(root => path.isAbsolute(root) ? root : path.join(target, root)))];
+}
+//# sourceMappingURL=deployed-skill-roots.js.map

package/dist/src/providers/grok-build-acp.js

@@ -1,4 +1,5 @@
 /** Grok Build ACP stdio client. Separate from one-shot headless execution. */
+import { signalChild } from '../process/signal-child.mjs';
 import { spawn } from 'node:child_process';
 import { redactGrokOutput } from './grok-build-headless.js';
 export class GrokAcpClient {
@@ -182,9 +183,9 @@ export class GrokAcpClient {
         this.terminated = true;
         this.failAll(new Error('Grok ACP connection closed'));
         this.child.stdin.end();
-        if (!this.child.kill('SIGTERM'))
+        if (!signalChild(this.child, 'SIGTERM'))
             return;
-        const forceTimer = setTimeout(() => this.child.kill('SIGKILL'), 2_000);
+        const forceTimer = setTimeout(() => signalChild(this.child, 'SIGKILL'), 2_000);
         forceTimer.unref();
         this.child.once('close', () => clearTimeout(forceTimer));
     }

package/dist/src/providers/grok-build-headless.js

@@ -1,8 +1,13 @@
 /** Bounded Grok Build headless transport. The caller owns task authorization. */
+import { signalChild } from '../process/signal-child.mjs';
 import { spawn } from 'node:child_process';
 const MAX_TIMEOUT_MS = 10 * 60_000;
 const DEFAULT_TIMEOUT_MS = 2 * 60_000;
 const DEFAULT_MAX_OUTPUT = 8 * 1024 * 1024;
+// grok 1.0.50 --output-format streaming-json: ACP session updates.
+// See docs/providers/grok-build-cli-evidence.md; json is a separate result object.
+const STREAM_EVENT_TYPES = new Set(['text', 'thought', 'tool_call', 'tool_call_update',
+    'usage', 'plan', 'available_commands', 'end', 'error']);
 export function redactGrokOutput(value, env = process.env) {
     let redacted = value
         .replace(/\b(Bearer\s+)[A-Za-z0-9._~+/-]+/gi, '$1[REDACTED]')
@@ -20,20 +25,22 @@ function scrubEvent(event, env) {
     return JSON.parse(redactGrokOutput(JSON.stringify(event), env));
 }
 function isTerminal(event) {
-    return ['result', 'error', 'complete', 'completed'].includes(String(event.type ?? event.event ?? ''));
+    return event.type === 'end' || event.type === 'error';
 }
 function isError(event) {
-    return event.is_error === true || event.error !== undefined || ['error', 'failed'].includes(String(event.type ?? event.event ?? ''));
+    return event.type === 'error' || event.is_error === true || event.error != null
+        || (event.type === 'end' && event.stopReason !== 'end_turn')
+        || (['tool_call', 'tool_call_update'].includes(String(event.type)) && event.status === 'failed');
 }
 function stopProcess(child) {
-    if (child.pid && process.platform !== 'win32') {
+    if (Number.isSafeInteger(child.pid) && child.pid > 0 && process.platform !== 'win32') {
         try {
             process.kill(-child.pid, 'SIGTERM');
             return;
         }
         catch { /* process already exited */ }
     }
-    child.kill('SIGTERM');
+    signalChild(child, 'SIGTERM');
 }
 export async function runGrokHeadless(options) {
     if (!options.prompt.trim())
@@ -44,7 +51,7 @@ export async function runGrokHeadless(options) {
     const timeoutMs = Math.min(Math.max(options.timeoutMs ?? DEFAULT_TIMEOUT_MS, 1), MAX_TIMEOUT_MS);
     const maxBytes = Math.min(Math.max(options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT, 1024), DEFAULT_MAX_OUTPUT);
     const env = options.env ?? process.env;
-    const args = [...(options.prefixArgs ?? []), '--no-auto-update', ...(options.disableSubagents ? ['--no-subagents'] : []), '-p', options.prompt, '--output-format', format];
+    const args = [...(options.prefixArgs ?? []), ...(options.disableSubagents ? ['--no-subagents'] : []), '-p', options.prompt, '--output-format', format];
     return new Promise((resolve, reject) => {
         const child = spawn(options.command ?? 'grok', args, {
             cwd: options.cwd,
@@ -88,7 +95,9 @@ export async function runGrokHeadless(options) {
             if (format === 'json') {
                 try {
                     const parsed = JSON.parse(cleanStdout);
-                    if (isError(parsed))
+                    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)
+                        || typeof parsed.text !== 'string' || isError(parsed)
+                        || parsed.stopReason !== 'end_turn')
                         throw new Error('Grok Build returned a JSON error result');
                     events.push(parsed);
                 }
@@ -105,7 +114,41 @@ export async function runGrokHeadless(options) {
         if (options.signal?.aborted)
             abort();
         child.on('error', error => finish(new Error(`Grok Build headless launch failed: ${error.message}`)));
+        const acceptEvent = (event) => {
+            if (settled)
+                return;
+            if (!event || typeof event !== 'object' || Array.isArray(event)
+                || typeof event.type !== 'string' || !STREAM_EVENT_TYPES.has(event.type)) {
+                finish(new Error('Invalid Grok Build streaming-json event'));
+                return;
+            }
+            // ACP end is always last. Failure is latched across the whole stream.
+            if (terminalSeen) {
+                finish(new Error('Grok Build event after terminal event'));
+                return;
+            }
+            const safe = scrubEvent(event, env);
+            events.push(safe);
+            options.onEvent?.(safe);
+            if (isError(safe))
+                terminalError = true;
+            if (isTerminal(safe)) {
+                terminalSeen = true;
+                // Some builds leave background work attached after end. Allow a
+                // short drain, then terminate the process group.
+                drainTimer ??= setTimeout(() => {
+                    if (pending.trim()) {
+                        finish(new Error('Invalid trailing Grok Build streaming-json event'));
+                        return;
+                    }
+                    stopProcess(child);
+                    finish(undefined, terminalError ? 1 : 0);
+                }, 300);
+            }
+        };
         child.stdout.on('data', (chunk) => {
+            if (settled)
+                return;
             bytes += chunk.length;
             if (bytes > maxBytes) {
                 finish(new Error(`Grok Build headless output exceeded ${maxBytes} bytes`));
@@ -130,17 +173,9 @@ export async function runGrokHeadless(options) {
                     finish(new Error('Invalid Grok Build streaming-json event'));
                     return;
                 }
-                const safe = scrubEvent(event, env);
-                events.push(safe);
-                options.onEvent?.(safe);
-                if (isError(safe))
-                    terminalError = true;
-                if (isTerminal(safe)) {
-                    terminalSeen = true;
-                    // Some provider builds leave background work attached after the
-                    // result. Allow a short drain, then terminate the process group.
-                    drainTimer ??= setTimeout(() => { stopProcess(child); finish(undefined, terminalError ? 1 : 0); }, 300);
-                }
+                acceptEvent(event);
+                if (settled)
+                    return;
             }
         });
         child.stderr.on('data', (chunk) => {
@@ -151,12 +186,7 @@ export async function runGrokHeadless(options) {
         child.on('close', code => {
             if (format === 'streaming-json' && pending.trim()) {
                 try {
-                    const event = scrubEvent(JSON.parse(pending), env);
-                    events.push(event);
-                    if (isError(event))
-                        terminalError = true;
-                    if (isTerminal(event))
-                        terminalSeen = true;
+                    acceptEvent(JSON.parse(pending));
                 }
                 catch {
                     finish(new Error('Invalid trailing Grok Build streaming-json event'));