@dungle-scrubs/harness-cli-normalizer 0.1.2 → 0.3.0

package/dist/cli/check.js

@@ -0,0 +1,110 @@
+import { execFileSync } from "node:child_process";
+import { versionStatus } from "../interpretation/versions.js";
+import { defaultDescriptors } from "../knowledge/overrides.js";
+const npmLatest = async (pkg) => {
+    try {
+        const res = await fetch(`https://registry.npmjs.org/${pkg}`, {
+            headers: { accept: "application/vnd.npm.install-v1+json" },
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        const latest = body["dist-tags"]?.latest;
+        return typeof latest === "string" ? latest : null;
+    }
+    catch {
+        return null;
+    }
+};
+const installedVersion = (bin) => {
+    try {
+        const out = execFileSync(bin, ["--version"], { encoding: "utf8", timeout: 10_000 });
+        const match = out.match(/\d+\.\d+\.\d+(?:[.+-][0-9A-Za-z.-]+)?/);
+        return match ? match[0] : null;
+    }
+    catch {
+        return null;
+    }
+};
+const resolveLatest = async (h) => {
+    if (h.versionSource.kind === "npm") {
+        return {
+            latest: await npmLatest(h.versionSource.package),
+            source: `npm:${h.versionSource.package}`,
+        };
+    }
+    return { latest: installedVersion(h.bin), source: `installed:${h.bin}` };
+};
+export const check = async (rawArgs) => {
+    const wantJson = rawArgs.includes("--json");
+    const wantHelp = rawArgs.includes("--help") || rawArgs.includes("-h");
+    if (wantHelp) {
+        const { CHECK_HELP } = await import("./help.js");
+        process.stdout.write(CHECK_HELP);
+        return;
+    }
+    const descriptors = Object.values(defaultDescriptors()).filter((d) => d !== undefined);
+    const rows = await Promise.all(descriptors.map(async (h) => {
+        const { latest, source } = await resolveLatest(h);
+        return {
+            harness: h.name,
+            bin: h.bin,
+            verifiedAgainst: h.verifiedAgainst,
+            latest,
+            source,
+            status: versionStatus(h.verifiedAgainst, latest),
+        };
+    }));
+    const behind = rows.filter((r) => r.status === "behind");
+    const unknown = rows.filter((r) => r.status === "unknown");
+    if (wantJson) {
+        process.stdout.write(`${JSON.stringify({ checkedAt: new Date().toISOString(), rows, behind: behind.map((r) => r.harness) }, null, 2)}\n`);
+    }
+    else {
+        const mark = (s) => s === "ok" ? "✓ ok" : s === "behind" ? "⬆ NEW" : s === "ahead" ? "? ahead" : "– unknown";
+        process.stdout.write(`\n${"harness".padEnd(9)}${"verified".padEnd(12)}${"latest".padEnd(12)}status\n`);
+        for (const r of rows) {
+            process.stdout.write(`${r.harness.padEnd(9)}${r.verifiedAgainst.padEnd(12)}${(r.latest ?? "?").padEnd(12)}${mark(r.status)}\n`);
+        }
+        if (behind.length > 0) {
+            process.stdout.write(`\n${behind.length} harness(es) behind: ${behind.map((r) => `${r.harness} ${r.verifiedAgainst}→${r.latest}`).join(", ")}\n`);
+            process.stdout.write("Run the local capability tripwires (smoke:seven) against the new version, then file an issue + bump verifiedAgainst.\n");
+        }
+        else if (unknown.length > 0) {
+            process.stdout.write(`\n${unknown.length} harness(es) unknown (network or missing bin)\n`);
+        }
+        else {
+            process.stdout.write("\nall descriptors current with their published versions.\n");
+        }
+    }
+    // Exit logic: behind => 1, unknown (network failure) => 1 with partial results, else 0
+    // But we must not exit 1 for unknown if behind already counts? We'll handle:
+    if (behind.length > 0) {
+        process.exitCode = 1;
+    }
+    else if (unknown.length > 0 && rows.some((r) => r.latest === null)) {
+        // network failure at least one
+        // Per spec: network failure prints warning and exits 1 with partial results
+        // We'll check if any latest is null and that we attempted npm fetch (could be network)
+        // Simpler: if unknown and not all ok, exit 1
+        // But spec says check should reuse versions.ts and not crash; exit 1 with partial results
+        // We'll exit 1 if any harness has unknown and at least one npm source failed - but we can't distinguish installed missing vs network.
+        // For now, exit 1 if unknown.length >0 and at least one behind==0? Actually spec says network failure => exit 1.
+        // We'll exit 1 if unknown includes npm harnesses (they shouldn't be unknown without network).
+        const npmUnknown = rows.filter((r) => r.source.startsWith("npm:") && r.status === "unknown");
+        if (npmUnknown.length > 0)
+            process.exitCode = 1;
+        else if (behind.length === 0 && unknown.length > 0) {
+            // installed unknown (muse missing) is not necessarily failure? But spec says network failure case is 1.
+            // For installed missing, we treat as unknown but not failure - keep 0 to not break CI where muse not installed.
+            // However spec says check prints partial results and exits 1 on network failure.
+            // We'll only exit 1 for npmUnknown, otherwise 0.
+            process.exitCode = 0;
+        }
+    }
+    else {
+        process.exitCode = 0;
+    }
+};
+//# sourceMappingURL=check.js.map

package/dist/cli/check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../../src/cli/check.ts"],"names":[],"mappings":"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"}

package/dist/cli/exit-codes.d.ts

@@ -0,0 +1,7 @@
+import type { ExitCause } from "../execution/events.js";
+export declare const EXIT_CLEAN = 0;
+export declare const EXIT_REFUSAL = 2;
+export declare const EXIT_FAILURE = 1;
+export declare const exitCodeForCause: (cause: ExitCause) => number;
+export declare const exitCodeForRefusal: () => number;
+//# sourceMappingURL=exit-codes.d.ts.map

package/dist/cli/exit-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-codes.d.ts","sourceRoot":"","sources":["../../src/cli/exit-codes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD,eAAO,MAAM,UAAU,IAAI,CAAC;AAC5B,eAAO,MAAM,YAAY,IAAI,CAAC;AAC9B,eAAO,MAAM,YAAY,IAAI,CAAC;AAE9B,eAAO,MAAM,gBAAgB,UAAW,SAAS,KAAG,MAInD,CAAC;AAEF,eAAO,MAAM,kBAAkB,QAAO,MAAsB,CAAC"}

package/dist/cli/exit-codes.js

@@ -0,0 +1,11 @@
+export const EXIT_CLEAN = 0;
+export const EXIT_REFUSAL = 2;
+export const EXIT_FAILURE = 1;
+export const exitCodeForCause = (cause) => {
+    if (cause === "clean")
+        return EXIT_CLEAN;
+    // All non-clean causes are failures that should be exit 1, except refusal is already handled separately
+    return EXIT_FAILURE;
+};
+export const exitCodeForRefusal = () => EXIT_REFUSAL;
+//# sourceMappingURL=exit-codes.js.map

package/dist/cli/exit-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-codes.js","sourceRoot":"","sources":["../../src/cli/exit-codes.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC;AAC5B,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC;AAC9B,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC;AAE9B,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAgB,EAAU,EAAE;IAC3D,IAAI,KAAK,KAAK,OAAO;QAAE,OAAO,UAAU,CAAC;IACzC,wGAAwG;IACxG,OAAO,YAAY,CAAC;AACtB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAW,EAAE,CAAC,YAAY,CAAC"}

package/dist/cli/help.d.ts

@@ -0,0 +1,7 @@
+export declare const TOP_LEVEL_HELP = "hcn - One stable interface to four coding-agent CLIs\n\nUsage: hcn <command> [options] [prompt]\n\nCommands:\n  run <harness> [prompt]    One-shot headless turn (streamTurn)\n  session <harness>         Interactive session (openSession, Claude-only)\n  inspect <harness>         Descriptor / argv / capability inspection (no spawn)\n  ls                        List harnesses with verifiedAgainst versions\n  check                     Drift check (published version vs verifiedAgainst)\n\nOptions:\n  -h, --help                Show help\n  -V, --version             Show version\n\nRun 'hcn <command> --help' for command-specific help.\n";
+export declare const RUN_HELP = "hcn run - One-shot headless turn\n\nUsage: hcn run <harness> [prompt] [options]\n\nArguments:\n  <harness>                 claude | codex | pi | muse\n  [prompt]                  Prompt text (positional). Must not start with '-'.\n                            Use --prompt or --prompt-file for leading '-' or multi-line.\n\nOptions:\n  --prompt <text>           Prompt text (alternative to positional)\n  --prompt-file <path|->    Read prompt from file, or stdin when '-'\n  --model <id>              Model id (validated per harness)\n  --effort <value>          Effort level (validated per harness/model)\n  --sandbox <value>         Sandbox mode (codex only)\n  --provider <value>        Provider (pi only)\n  --tools <a,b>             Tool grants (claude only, comma-separated)\n  --autonomy                Enable autonomy flag (claude/codex/muse)\n  --no-autonomy             Disable autonomy\n  --write                   Enable write (muse)\n  --no-write                Disable write\n  --shell                   Enable shell (muse)\n  --no-shell                Disable shell\n  --max-steps <n>           Max steps (muse, 1-10000)\n  --no-tools                Disable tools discovery facet\n  --no-instruction-files    Disable instructionFiles discovery facet\n  --no-extensions           Disable extensions discovery facet\n  --no-skills               Disable skills discovery facet\n  --cwd <path>              Working directory for spawn\n  --env KEY=VAL             Environment (repeatable; KEY= deletes)\n  --resume <uuid>           Resume session id (UUID)\n  --json                    NDJSON HarnessEvent to stdout\n  -h, --help                Show help\n  -V, --version             Show version\n";
+export declare const SESSION_HELP = "hcn session - Interactive session (Claude-only)\n\nUsage: hcn session <harness> [options]\n\nArguments:\n  <harness>                 Must be 'claude' (other harnesses have no sessionMode)\n\nOptions:\n  --model <id>              Model for the session\n  --session-id <uuid>       Session id (UUID, else random)\n  --cwd <path>              Working directory\n  --help                    Show help\n  --version                 Show version\n";
+export declare const INSPECT_HELP = "hcn inspect - Descriptor / argv inspection\n\nUsage: hcn inspect <harness> [options]\n\nArguments:\n  <harness>                 claude | codex | pi | muse\n\nOptions:\n  --argv                    Preview argv that would be spawned\n  --prompt <text>           Prompt for argv preview\n  --prompt-file <path|->    Read prompt from file\n  --model <id>              Model\n  --effort <value>          Effort\n  --sandbox <value>         Sandbox\n  --provider <value>        Provider\n  --tools <a,b>             Tools\n  --autonomy / --no-autonomy\n  --write / --no-write\n  --shell / --no-shell\n  --max-steps <n>\n  --no-tools, --no-instruction-files, --no-extensions, --no-skills\n  --cwd <path>\n  --env KEY=VAL\n  --resume <uuid>\n  -h, --help                Show help\n";
+export declare const LS_HELP = "hcn ls - List harnesses\n\nUsage: hcn ls\n\nPrints each harness name with its verifiedAgainst version and versionSource.\n";
+export declare const CHECK_HELP = "hcn check - Drift check\n\nUsage: hcn check [--json]\n\nCompares each harness's verifiedAgainst against the latest published version.\nExits 0 when no drift, 1 when drift found, 1 on network failure with partial results.\n\nOptions:\n  --json                    Machine-readable output\n  -h, --help                Show help\n";
+//# sourceMappingURL=help.d.ts.map

package/dist/cli/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,koBAgB1B,CAAC;AAEF,eAAO,MAAM,QAAQ,irDAkCpB,CAAC;AAEF,eAAO,MAAM,YAAY,6bAaxB,CAAC;AAEF,eAAO,MAAM,YAAY,0wBAyBxB,CAAC;AAEF,eAAO,MAAM,OAAO,+HAKnB,CAAC;AAEF,eAAO,MAAM,UAAU,2UAUtB,CAAC"}

package/dist/cli/help.js

@@ -0,0 +1,110 @@
+export const TOP_LEVEL_HELP = `hcn - One stable interface to four coding-agent CLIs
+
+Usage: hcn <command> [options] [prompt]
+
+Commands:
+  run <harness> [prompt]    One-shot headless turn (streamTurn)
+  session <harness>         Interactive session (openSession, Claude-only)
+  inspect <harness>         Descriptor / argv / capability inspection (no spawn)
+  ls                        List harnesses with verifiedAgainst versions
+  check                     Drift check (published version vs verifiedAgainst)
+
+Options:
+  -h, --help                Show help
+  -V, --version             Show version
+
+Run 'hcn <command> --help' for command-specific help.
+`;
+export const RUN_HELP = `hcn run - One-shot headless turn
+
+Usage: hcn run <harness> [prompt] [options]
+
+Arguments:
+  <harness>                 claude | codex | pi | muse
+  [prompt]                  Prompt text (positional). Must not start with '-'.
+                            Use --prompt or --prompt-file for leading '-' or multi-line.
+
+Options:
+  --prompt <text>           Prompt text (alternative to positional)
+  --prompt-file <path|->    Read prompt from file, or stdin when '-'
+  --model <id>              Model id (validated per harness)
+  --effort <value>          Effort level (validated per harness/model)
+  --sandbox <value>         Sandbox mode (codex only)
+  --provider <value>        Provider (pi only)
+  --tools <a,b>             Tool grants (claude only, comma-separated)
+  --autonomy                Enable autonomy flag (claude/codex/muse)
+  --no-autonomy             Disable autonomy
+  --write                   Enable write (muse)
+  --no-write                Disable write
+  --shell                   Enable shell (muse)
+  --no-shell                Disable shell
+  --max-steps <n>           Max steps (muse, 1-10000)
+  --no-tools                Disable tools discovery facet
+  --no-instruction-files    Disable instructionFiles discovery facet
+  --no-extensions           Disable extensions discovery facet
+  --no-skills               Disable skills discovery facet
+  --cwd <path>              Working directory for spawn
+  --env KEY=VAL             Environment (repeatable; KEY= deletes)
+  --resume <uuid>           Resume session id (UUID)
+  --json                    NDJSON HarnessEvent to stdout
+  -h, --help                Show help
+  -V, --version             Show version
+`;
+export const SESSION_HELP = `hcn session - Interactive session (Claude-only)
+
+Usage: hcn session <harness> [options]
+
+Arguments:
+  <harness>                 Must be 'claude' (other harnesses have no sessionMode)
+
+Options:
+  --model <id>              Model for the session
+  --session-id <uuid>       Session id (UUID, else random)
+  --cwd <path>              Working directory
+  --help                    Show help
+  --version                 Show version
+`;
+export const INSPECT_HELP = `hcn inspect - Descriptor / argv inspection
+
+Usage: hcn inspect <harness> [options]
+
+Arguments:
+  <harness>                 claude | codex | pi | muse
+
+Options:
+  --argv                    Preview argv that would be spawned
+  --prompt <text>           Prompt for argv preview
+  --prompt-file <path|->    Read prompt from file
+  --model <id>              Model
+  --effort <value>          Effort
+  --sandbox <value>         Sandbox
+  --provider <value>        Provider
+  --tools <a,b>             Tools
+  --autonomy / --no-autonomy
+  --write / --no-write
+  --shell / --no-shell
+  --max-steps <n>
+  --no-tools, --no-instruction-files, --no-extensions, --no-skills
+  --cwd <path>
+  --env KEY=VAL
+  --resume <uuid>
+  -h, --help                Show help
+`;
+export const LS_HELP = `hcn ls - List harnesses
+
+Usage: hcn ls
+
+Prints each harness name with its verifiedAgainst version and versionSource.
+`;
+export const CHECK_HELP = `hcn check - Drift check
+
+Usage: hcn check [--json]
+
+Compares each harness's verifiedAgainst against the latest published version.
+Exits 0 when no drift, 1 when drift found, 1 on network failure with partial results.
+
+Options:
+  --json                    Machine-readable output
+  -h, --help                Show help
+`;
+//# sourceMappingURL=help.js.map

package/dist/cli/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;CAgB7B,CAAC;AAEF,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkCvB,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;;;;;;;;CAa3B,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;CAyB3B,CAAC;AAEF,MAAM,CAAC,MAAM,OAAO,GAAG;;;;;CAKtB,CAAC;AAEF,MAAM,CAAC,MAAM,UAAU,GAAG;;;;;;;;;;CAUzB,CAAC"}

package/dist/cli/index.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+export declare const failUnknownHarness: (name: string) => never;
+export declare const dispatch: (raw: string[]) => Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAwBA,eAAO,MAAM,kBAAkB,SAAU,MAAM,KAAG,KAQjD,CAAC;AAEF,eAAO,MAAM,QAAQ,QAAe,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CAyH1D,CAAC"}

package/dist/cli/index.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+import { TOP_LEVEL_HELP } from "./help.js";
+import { getVersion } from "./version.js";
+const SUPPORTED = ["claude", "codex", "pi", "muse"];
+// Prevent EPIPE crashes when piped to head/grep -q (e.g., hcn ls | head, hcn run --json | head)
+process.stdout.on("error", (err) => {
+    const code = err.code;
+    if (code === "EPIPE")
+        process.exit(0);
+});
+process.stderr.on("error", (err) => {
+    const code = err.code;
+    if (code === "EPIPE")
+        process.exit(0);
+});
+const printVersion = () => {
+    process.stdout.write(`${getVersion()}\n`);
+};
+const printTopHelp = () => {
+    process.stdout.write(TOP_LEVEL_HELP);
+};
+export const failUnknownHarness = (name) => {
+    process.stderr.write(`unknown harness ${JSON.stringify(name)}; supported: ${SUPPORTED.join(", ")}\n`);
+    process.stderr.write(`supported: ${SUPPORTED.join(", ")}\n`);
+    process.exitCode = 2;
+    // Use process.exit to ensure exit code is set even if async
+    process.exit(2);
+};
+export const dispatch = async (raw) => {
+    // Shared dispatch for programmatic use (tests) - mirrors main but takes argv slice
+    // Global --help / --version without command
+    if (raw.length === 0 || raw[0] === "--help" || raw[0] === "-h") {
+        if (raw.includes("--version") || raw.includes("-V")) {
+            printVersion();
+            return;
+        }
+        printTopHelp();
+        return;
+    }
+    if (raw[0] === "--version" || raw[0] === "-V") {
+        printVersion();
+        return;
+    }
+    const cmd = raw[0];
+    switch (cmd) {
+        case "ls": {
+            if (raw.includes("--help") || raw.includes("-h")) {
+                const { LS_HELP } = await import("./help.js");
+                process.stdout.write(LS_HELP);
+                return;
+            }
+            if (raw.includes("--version") || raw.includes("-V")) {
+                printVersion();
+                return;
+            }
+            if (raw.length > 1) {
+                const extra = raw.slice(1);
+                const hasUnknown = extra.some((a) => a.startsWith("-"));
+                if (hasUnknown) {
+                    process.stderr.write(`unknown flag for ls: ${extra.join(" ")}\n`);
+                    process.exitCode = 2;
+                    return;
+                }
+            }
+            const { ls } = await import("./ls.js");
+            ls();
+            return;
+        }
+        case "check": {
+            const { check } = await import("./check.js");
+            await check(raw.slice(1));
+            return;
+        }
+        case "inspect": {
+            if (raw.slice(1).includes("--help") || raw.slice(1).includes("-h")) {
+                const { INSPECT_HELP } = await import("./help.js");
+                process.stdout.write(INSPECT_HELP);
+                return;
+            }
+            const harness = raw[1];
+            if (!harness || harness.startsWith("-")) {
+                process.stderr.write(`inspect requires <harness>; supported: ${SUPPORTED.join(", ")}\n`);
+                process.exitCode = 2;
+                return;
+            }
+            if (!SUPPORTED.includes(harness))
+                failUnknownHarness(harness);
+            const { inspect } = await import("./inspect.js");
+            await inspect(harness, raw.slice(2));
+            return;
+        }
+        case "run": {
+            if (raw.slice(1).includes("--help") || raw.slice(1).includes("-h")) {
+                const { RUN_HELP } = await import("./help.js");
+                process.stdout.write(RUN_HELP);
+                return;
+            }
+            if (raw.slice(1).includes("--version") || raw.slice(1).includes("-V")) {
+                printVersion();
+                return;
+            }
+            const harness = raw[1];
+            if (!harness || harness.startsWith("-")) {
+                process.stderr.write(`run requires <harness>; supported: ${SUPPORTED.join(", ")}\n`);
+                process.exitCode = 2;
+                return;
+            }
+            if (!SUPPORTED.includes(harness))
+                failUnknownHarness(harness);
+            const { run } = await import("./run.js");
+            await run(harness, raw.slice(2));
+            return;
+        }
+        case "session": {
+            if (raw.slice(1).includes("--help") || raw.slice(1).includes("-h")) {
+                const { SESSION_HELP } = await import("./help.js");
+                process.stdout.write(SESSION_HELP);
+                return;
+            }
+            const harness = raw[1];
+            if (!harness || harness.startsWith("-")) {
+                process.stderr.write(`session requires <harness>; supported: ${SUPPORTED.join(", ")}\n`);
+                process.exitCode = 2;
+                return;
+            }
+            if (!SUPPORTED.includes(harness))
+                failUnknownHarness(harness);
+            const { session } = await import("./session.js");
+            await session(harness, raw.slice(2));
+            return;
+        }
+        case "help":
+        case "--help":
+        case "-h": {
+            printTopHelp();
+            return;
+        }
+        default: {
+            if (SUPPORTED.includes(cmd)) {
+                process.stderr.write(`missing command; did you mean 'hcn run ${cmd} <prompt>'?\n`);
+                process.stderr.write(TOP_LEVEL_HELP);
+                process.exitCode = 2;
+                return;
+            }
+            process.stderr.write(`unknown command ${JSON.stringify(cmd)}\n`);
+            process.stderr.write(TOP_LEVEL_HELP);
+            process.exitCode = 2;
+            return;
+        }
+    }
+};
+const main = async () => {
+    await dispatch(process.argv.slice(2));
+};
+const shouldAutoRun = (() => {
+    const entry = process.argv[1] ?? "";
+    return (entry.endsWith("cli.js") || entry.endsWith("cli/index.js") || entry.endsWith("src/cli/index.ts"));
+})();
+if (shouldAutoRun) {
+    main().catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`fatal: ${message}\n`);
+        if (err instanceof Error && err.stack)
+            process.stderr.write(`${err.stack}\n`);
+        process.exitCode = 1;
+        if (process.exitCode === 0)
+            process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}

package/dist/cli/inspect.d.ts

@@ -0,0 +1,3 @@
+export declare const inspect: (harnessName: string, rawArgs: string[]) => Promise<void>;
+export declare const inspectCommand: typeof inspect;
+//# sourceMappingURL=inspect.d.ts.map

package/dist/cli/inspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../src/cli/inspect.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,OAAO,gBAAuB,MAAM,WAAW,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CAqKlF,CAAC;AAEF,eAAO,MAAM,cAAc,gBAAU,CAAC"}

package/dist/cli/inspect.js

@@ -0,0 +1,170 @@
+import { redactArgv } from "../execution/stream-turn.js";
+import { buildLaunchArgv } from "../interpretation/argv.js";
+import { ArgvRefusalError } from "../interpretation/refusal.js";
+import { parseTurnOptions, resolvePromptAsync } from "./args.js";
+import { resolveHarness } from "./resolve-harness.js";
+export const inspect = async (harnessName, rawArgs) => {
+    const h = resolveHarness(harnessName);
+    // Check for --help
+    if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+        const { INSPECT_HELP } = await import("./help.js");
+        process.stdout.write(INSPECT_HELP);
+        return;
+    }
+    // Check for positional prompt injection before parse (only when --argv and no explicit prompt)
+    const { parseCommonFlags, detectPositionalPromptInjection } = await import("./args.js");
+    if (rawArgs.includes("--argv")) {
+        const injection = detectPositionalPromptInjection(rawArgs.filter((a) => a !== "--argv"));
+        if (injection) {
+            const err = new ArgvRefusalError({
+                issue: "prompt-flag-injection",
+                harness: h.name,
+                supported: ["prompt must not start with '-'"],
+                detail: `it would be parsed as a flag by ${h.bin}`,
+            });
+            process.stderr.write(`${err.message}\n`);
+            process.stderr.write(`supported: prompt must not start with '-'\n`);
+            process.exitCode = 2;
+            return;
+        }
+    }
+    // Parse flags for inspect
+    let parsed;
+    try {
+        parsed = parseCommonFlags(rawArgs);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`unknown flag: ${message}\n`);
+        process.stderr.write(`Run 'hcn inspect --help' for usage.\n`);
+        process.exitCode = 2;
+        return;
+    }
+    const values = parsed.values;
+    const wantArgv = values.argv === true;
+    if (!wantArgv) {
+        // Pure descriptor dump
+        const out = {
+            name: h.name,
+            bin: h.bin,
+            verifiedAgainst: h.verifiedAgainst,
+            versionSource: h.versionSource,
+            launch: {
+                baseFlags: h.launch.baseFlags,
+                subcommands: h.launch.subcommands,
+                streamFlags: h.launch.streamFlags,
+                promptStyle: h.launch.promptStyle,
+                toolsFlag: h.launch.toolsFlag,
+                idFlag: h.launch.idFlag,
+            },
+            resume: h.resume,
+            sessionMode: h.sessionMode,
+            vocabulary: {
+                models: h.vocabulary.models,
+                aliases: h.vocabulary.aliases,
+                efforts: h.vocabulary.efforts,
+                effortsByModel: h.vocabulary.effortsByModel,
+                extensible: h.vocabulary.extensible,
+                modelFlag: h.vocabulary.modelFlag,
+            },
+            turnOptions: h.turnOptions,
+        };
+        process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+        return;
+    }
+    // --argv preview path: need prompt + turn options
+    const positional = parsed.positionals;
+    // positional[0] would be harness already consumed, but we passed rawArgs without harness - check: caller passes remaining after harness
+    // So positionals are potential prompt positional if not using --prompt
+    const positionalPrompt = positional.length > 0 ? positional[0] : undefined;
+    if (positional.length > 1) {
+        process.stderr.write(`too many positionals for inspect --argv\n`);
+        process.exitCode = 2;
+        return;
+    }
+    let prompt;
+    let promptSource;
+    try {
+        const resolved = await resolvePromptAsync({
+            positionalPrompt,
+            promptFlag: values.prompt,
+            promptFile: values["prompt-file"],
+        });
+        prompt = resolved.prompt;
+        promptSource = resolved.source;
+    }
+    catch (err) {
+        if (err instanceof ArgvRefusalError) {
+            process.stderr.write(`${err.message}\n`);
+            if (err.supported.length)
+                process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
+            process.exitCode = 2;
+            return;
+        }
+        throw err;
+    }
+    // Build TurnOptions from flags
+    let turnOpts;
+    try {
+        turnOpts = parseTurnOptions(values);
+    }
+    catch (err) {
+        if (err instanceof ArgvRefusalError) {
+            process.stderr.write(`${err.message}\n`);
+            if (err.supported.length)
+                process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
+            process.exitCode = 2;
+            return;
+        }
+        throw err;
+    }
+    const fullOpts = {
+        ...turnOpts,
+        prompt,
+        ...(promptSource !== "positional" ? { __explicitPrompt: true } : {}),
+    };
+    let argv;
+    try {
+        argv = buildLaunchArgv(h, fullOpts);
+    }
+    catch (err) {
+        if (err instanceof ArgvRefusalError) {
+            process.stderr.write(`${err.message}\n`);
+            if (err.supported.length)
+                process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
+            process.exitCode = 2;
+            return;
+        }
+        throw err;
+    }
+    // Redact prompt for display, but keep structure
+    const redacted = redactArgv(argv, prompt);
+    // Also handle --resume case: need to use buildResumeArgv if resume present
+    if (values.resume !== undefined || values["session-id"] !== undefined) {
+        // For inspect --argv with --resume, show resume argv
+        const { buildResumeArgv } = await import("../interpretation/argv.js");
+        const resumeId = String(values.resume ?? values["session-id"]);
+        try {
+            const resumeOpts = { ...fullOpts, sessionId: resumeId };
+            const resumeArgv = buildResumeArgv(h, resumeOpts);
+            const redactedResume = redactArgv(resumeArgv, prompt);
+            process.stdout.write(`${JSON.stringify(redactedResume)}\n`);
+            process.stderr.write(`argv: ${redactedResume.join(" ")}\n`);
+            return;
+        }
+        catch (err) {
+            if (err instanceof ArgvRefusalError) {
+                process.stderr.write(`${err.message}\n`);
+                if (err.supported.length)
+                    process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
+                process.exitCode = 2;
+                return;
+            }
+            throw err;
+        }
+    }
+    process.stdout.write(`${JSON.stringify(redacted)}\n`);
+    process.stderr.write(`argv: ${redacted.join(" ")}\n`);
+};
+export const inspectCommand = inspect;
+//# sourceMappingURL=inspect.js.map