export const TOP_LEVEL_HELP = `hcn - One stable interface to seven coding-agent CLIs Usage: hcn [options] [prompt] Commands: run [prompt] One-shot headless turn (streamTurn) session Interactive session (openSession, claude + pi + antigravity + popeye) interactive Strict native terminal resume with a separate control pipe inspect Descriptor / argv / capability inspection (no spawn) transcript read Passive native transcript export (JSONL) transcript ls List saved native sessions, newest first (JSONL) ls List harnesses with verifiedAgainst versions check Drift check (published version vs verifiedAgainst) Options: -h, --help Show help -V, --version Show version Exit codes: 0 ok, 1 failure (harness or transport), 2 usage error or refusal, 4 hcn internal crash (bug; a --json stream gets the failure/done pair with cause crash). The durable command ledger records every invocation start and end under the hcn state directory. Run 'hcn --help' for command-specific help. `; export const INTERACTIVE_HELP = `hcn interactive - Resume a native terminal with process lifecycle evidence Usage: hcn interactive --interface --launch-id --resume --cwd --control-fd [--env KEY=VALUE] [--startup-prompt ] Returns version 1 NDJSON on the caller's pipe (fd >= 3). Native stdin, stdout, and stderr remain on the inherited terminal. Optional --startup-prompt starts one native turn: nonempty UTF-8, at most 8192 bytes, no NUL. It is passed once as data; control never contains the prompt or proves receipt/adherence. Omit it for idle resume. No model, fork, fresh session, or native argument passthrough is accepted. Empty --env values remove keys. Duplicate or invalid startup text refuses before spawn. Control: ready means preflight passed; started identifies the created process; closed reports its exit status and owned cleanup. Started does not prove native history loaded. A refused record with spawn-not-attempted proves no child was created. Missing or truncated control is uncertain; do not retry it as a refusal. Current lane: codex-cli on macOS/Linux using a native executable and an exact saved UUID/folder. Launcher wrappers, claude-cli, pi-cli, muse-cli and codex-desktop are unavailable until their separate strict native launch paths are verified. Exit: native terminal exit code on closed; 2 for pre-start refusal; 1 for uncertain launch or a signal exit; 4 for an hcn internal crash. Exit code alone is not no-child evidence. `; const DENIAL_COUNT_HELP = ` Optional done.denialCount: positive count of denial observations, not unique calls; omitted when zero. The count does not change the native exit status or cause and is not a work-success verdict.`; export const RUN_HELP = `hcn run - One-shot headless turn Usage: hcn run [prompt] [options] Arguments: claude | codex | pi | muse | cursor | antigravity | popeye [prompt] Prompt text (positional). Must not start with '-'. Use --prompt or --prompt-file for leading '-' or multi-line. Options: --prompt Prompt text (alternative to positional) --prompt-file Read prompt from file, or stdin when '-' --model Model id (validated per harness) --effort Effort level (validated per harness/model) --sandbox Sandbox mode (codex; antigravity workspace-write) --context-window Context window. codex 1-272000 (launch default 272000); popeye 1-10000000; claude 100000-1000000 rendered as native --autocompact, an auto-compact window. hcn adds no request-token or cost enforcement. No launch default for claude: keeps its native default unless a flag or config sets it. Native env CLAUDE_CODE_AUTO_COMPACT_WINDOW overrides the flag. Native percentage and compaction-disable controls are separate; their interaction here is untested. config: contextWindow --provider Provider (pi only) --agent Named agent the harness defines natively - hcn selects among them, never defines. claude, antigravity, and popeye; pi when its subagent extension is installed (verified at run, see ADR 0010); others refuse. An unknown name is the harness's own error (native) --tools Tool grant allowlist - canonical names (read, write, edit, shell, grep, glob, list, web-fetch, web-search, subagent, skill); 'native:' passes a harness-native or extension tool through (claude, pi, popeye; a bare name matching a configured toolset expands to it) --exclude-tools Complement over known tools - canonical names (same vocabulary, native: passthrough); mutually exclusive with --tools (claude, pi, popeye) --autonomy Enable autonomy flag (claude/codex/muse/cursor/antigravity) --no-autonomy Disable autonomy --write Enable write (muse) --no-write Disable write --shell Enable shell (muse) --no-shell Disable shell --memory Use the harness's native memory setting; remove hcn's memory-off override. Does not force memory on when native settings disable it --no-memory Disable persistent memory (claude: env var; codex: --disable memories; pi: no-op, no built-in memory; popeye: no-op (declared divergence); muse/cursor/antigravity: refuse - no off switch, reported as divergence by the default profile) --questions Which preamble to inject: ask = escalation protocol (DEFAULT, question event + done cause "awaiting-input", exit 0), assume = never ask, state assumption, none = inject nothing --system-prompt Replace the built-in system prompt (claude, pi, popeye: flag; codex: -c instructions=; muse/cursor/antigravity refuse. claude pairs the dynamic-section exclusion automatically. Opt-in; no default) --append-system-prompt Append to the built-in prompt (claude, pi, popeye only) --extension Load this extension file for the turn (pi only; absolute path to a regular file; repeatable; loads even with --no-extensions) --access Access preset - read = read-only tool subset (canonical: read, grep, glob, list, web-fetch, web-search; claude via a closed --tools set (Read, Grep, Glob, WebFetch, WebSearch) plus --permission-mode dontAsk and an explicit --disallowedTools mcp__* deny, pi/popeye via --tools, codex via --sandbox read-only, muse via --disable-write --disable-shell, cursor via --mode ask --sandbox enabled; antigravity refuses); write = claude --permission-mode acceptEdits plus strict native sandbox (auto-approves sandboxed Bash; no unsandboxed retry; requests fail-closed startup). codex uses --sandbox workspace-write; cursor uses --force (unconfined commands, also bypasses trust); pi, muse, and popeye add no restrictions. The sandbox covers Bash, not file or web tools. Native tool denials, Bash checks and network limits still apply. Unless managed policy overrides strict mode, Claude ignores project domain allowlists; trusted user or managed domain policy may be needed for installs or tests. Claude keeps the explicit write sandbox with --autonomy. Cursor read with autonomy also adds --force; precedence is unverified. Use --no-autonomy for the qualified read preset. Mutually exclusive with --tools/--exclude-tools and with --sandbox on codex; no default --max-steps Max steps (muse, 1-10000) --timeout Wall-clock budget for the run (all harnesses, hcn-enforced; 0 disables; no default) --isolation Fresh tool-free turn (claude); no resume, tools, skills, access, autonomy, discovery, or native passthrough. Uses bare mode; native authentication must support it. --no-tools Disable tools discovery facet --no-instruction-files Disable instructionFiles discovery facet --no-extensions Disable extensions discovery facet --skills Skill allowlist (names resolved against $HCN_SKILLS_ROOT or ~/.agents/skills; pi loads, claude and codex narrow) --no-skills Disable skills discovery facet --cwd Working directory for spawn --env KEY=VAL Environment (repeatable; KEY= deletes) --resume Resume session id (UUID). Continues the conversation where it left off. The answer path for question escalation: resume with the chosen answer as the prompt; id continuity per harness (claude stable, pi/muse caller-assigned, codex/cursor/antigravity minted via identity event) Note: hcn refuses an unknown id before spawn (exit 2) for pi, muse, and cursor. Antigravity accepts the id and may announce a fresh conversation. --session-id Alias for --resume (mutually exclusive with --resume) --resume-last Resume the most recent session in the spawn cwd (claude, codex, pi, cursor, antigravity; muse and popeye refuse). Mutually exclusive with --resume/--session-id. --native-settings-fingerprint Codex or Pi resume only, with explicit --cwd. Re-read saved model, effort and recorded provider before native spawn. Get the hash from inspect --native-settings. Refuses changed/unavailable sources, competing model/effort/provider options and native passthrough. Grants no permissions. --native-approvals One verified Codex response through app-server. Requires --json, --resume, --cwd and the saved fingerprint. Retains supported read-only/user-review settings. Refuses explicit --memory and --no-memory overrides. Stdin carries NDJSON approval decisions, never the prompt. Answer only offered request/choice IDs; no automatic grants. Unsupported native interactions end with owned cleanup. -- Passthrough: native harness args verbatim (failures surface as labeled native errors) --json NDJSON HarnessEvent to stdout ${DENIAL_COUNT_HELP} -h, --help Show help -V, --version Show version Defaults with no flags: Every launch resolves args > project config (.hcn/config.json at the git root) > user config (~/.config/hcn/config.json) > built-in profile > harness default. The profile pins: effort medium, sandbox workspace-write (codex and antigravity; other harnesses report divergence), context window 272000 (codex and popeye; claude keeps its native auto-compaction default - the profile window does not transfer there; other harnesses report divergence), discovery on, autonomy off, write/shell on. timeout, max-steps and access have no default; no access preset is applied. Explicit access write emits --force on cursor, --sandbox workspace-write on codex, and --permission-mode acceptEdits plus strict sandbox settings on claude; no extra flags on pi, muse, or popeye; antigravity refuses --access. The profile's sandbox setting is separate from access. toolMap is config-only (no flag) - canonical -> native mapping per harness. A bare pi run renders no --tools list: pi's list is a strict allowlist and would drop extension and MCP tools; name them through toolMap or native: when you grant. Question mode defaults to ask (config keys "questions"; prompt preamble, never a harness flag). Provenance prints to stderr on every run; see 'hcn inspect ' for the resolved argv of a bare run. `; export const SESSION_HELP = `hcn session - Interactive session (claude, pi, antigravity, popeye, codex) Usage: hcn session [options] Arguments: claude | pi | antigravity | popeye | codex Options: --json Machine surface: NDJSON events on stdout, NDJSON commands on stdin ({"op":"send","id":..,"text":..}, "answer", "close"). Every send is answered with one disposition (started | rejected); Pi and Codex wait for their native command response before reporting acceptance. The turn a send opens carries its id. Pi and Codex steer a mid-turn send into the running turn, which keeps its opening send's id. A Pi prompt acceptance received after settlement opens a turn with that send's id. The stream opens with a session event and ends with a closed event. Exit 0 clean, 1 otherwise, 2 refusal, 4 hcn internal crash (failure/closed pair, cause crash). ${DENIAL_COUNT_HELP} --stall Per-turn inactivity budget; the turn ends and the session closes reporting a stall. 0 disables (default: no limit) --provider Provider (pi only) --agent Named agent for the session spawn (claude, antigravity, popeye; pi with its subagent extension verified at open; others refuse) --model Model for the session --skills Skill allowlist for the session, resolved against $HCN_SKILLS_ROOT (or ~/.agents/skills) exactly like hcn run --skills. pi loads only the picks (--skill per pick, discovery off); claude narrows via --settings skillOverrides; codex via -c skills.config. The allowlist is a spawn property: it holds for the whole session, every turn, resume included. antigravity and popeye cannot enforce it and refuse with exit 2 rather than open with the full set. Unknown names refuse with exit 2. --effort Effort level for the session spawn (validated per harness/model; no default - the harness's own effort applies without the flag) --context-window Context window for the session spawn (claude 100000-1000000 as native --autocompact, an auto-compact window; codex 1-272000; popeye 1-10000000; no default - the harness's own setting applies without the flag) --resume Resume session id (UUID). Continues the conversation where it left off. --session-id is an alias (mutually exclusive with --resume). If no id is given, a fresh session is started with a new id. hcn refuses an unknown id before spawn (exit 2) for harnesses that would otherwise create a fresh session silently (pi) --session-id Alias for --resume (mutually exclusive with --resume) --questions Which preamble to inject: ask = worker may ask (DEFAULT, pickable menu), assume = never ask, none = inject nothing --memory Use native memory settings for the session spawn; remove hcn's memory-off override --no-memory Disable persistent memory (DEFAULT; claude spawns with CLAUDE_CODE_DISABLE_AUTO_MEMORY=1, pi has no built-in memory) --cwd Working directory --help Show help --version Show version `; export const INSPECT_HELP = `hcn inspect - Descriptor / argv inspection Usage: hcn inspect [options] Arguments: claude | codex | pi | muse | cursor | antigravity | popeye Options: --transcript Report passive transcript methods and evidence; exclusive with other inspection modes; no history opened --argv Preview argv that would be spawned --native-settings Read saved model, effort and provider without starting a process (Codex or Pi). Requires exact --resume and --cwd. --session-id is the shared alias for --resume. Returns one JSON object, with or without --json: available plus a source fingerprint (exit 0), or unavailable plus a reason (exit 2). Excludes other modes and turn options. Codex uses latest native settings updates; Pi follows the saved leaf's parent chain for model and thinking level. permissions describes recorded local-command limits or why they are unavailable; it does not promise restoration. Reads at most 64 MiB, 1 MiB per line, 16384 directory entries. No conversation text, permission grant or ownership claim. --native-settings-fingerprint Require matching saved settings for --argv / --runtime headless-turn previews. Same restrictions as hcn run. --runtime Preview argv and probe the selected executable version; All harnesses use invocation support in supported modes. Version metadata never rejects a supported invocation. A resolved executable is required (does not run a model or prove the saved session exists) --context Inspect complete staged context through a disposable native process (Claude headless-turn only). Validates the native operation independently of version metadata. --json returns accounting plus executable/model provenance. Native estimate includes recalled history and the composed prompt. No assistant task is queried. Resume is forked with persistence disabled; the original session is unchanged. Unknown adapter/accounting returns unavailable, never a guessed budget. Callers own reserves and dispatch decisions. Excludes --argv, --runtime, --capabilities and passthrough. Maximum serialized prompt: 8 MiB. Probe deadline defaults to 30 seconds; positive --timeout/config timeout overrides it. Zero retains 30 seconds. Cleanup is bounded separately. Startup hooks may run. Interruption exits 1 after cleanup. Invalid requests exit 2 with the standard JSON failure/done pair when --json is set. An hcn internal crash exits 4 with the same pair (cause crash). --capabilities Print the capability record (vision, images, streaming, session, source) as one JSON line --models Print installed pi provider/model pairs from the registry stores as one JSON line with --json (pi only; mutually exclusive with other modes) --mode Mode for --capabilities or --runtime: headless-turn | headless-session | interactive (default headless-turn) --runtime excludes interactive; headless-session requires --resume and accepts no native passthrough arguments Session preview needs no prompt; only model, effort, provider, context-window and cwd process options are accepted --prompt Prompt for argv preview --prompt-file Read prompt from file --model Model --effort Effort --sandbox Sandbox --context-window Context window (codex 1-272000; popeye 1-10000000; claude 100000-1000000 as native --autocompact, an auto-compact window with no launch default) --provider Provider --tools Tools - canonical names (read, write, edit, shell, grep, glob, list, web-fetch, web-search, subagent, skill); 'native:' passes through --autonomy / --no-autonomy --write / --no-write --shell / --no-shell --memory / --no-memory (claude renders an env var, codex --disable memories; inspect --argv shows it in the spawn env, not the argv) --questions (accepted; renders nothing - rides the run prompt) --max-steps --isolation (fresh claude turn only) --no-tools, --no-instruction-files, --no-extensions, --no-skills --questions Accepted; renders nothing in argv (the mode rides the run prompt, not a harness flag) --cwd --env KEY=VAL --resume-last --resume -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 `; export const TRANSCRIPT_HELP = `hcn transcript - Passive native transcript export Usage: hcn transcript read (--id | --file ) [options] hcn transcript ls [--cwd | --all-workspaces] [--headless] [--harness ] [--limit ] [--since-time ] Harnesses: claude | codex | pi | muse | cursor | antigravity | popeye Inspect support first: hcn inspect --transcript read options: --cwd Resolution workspace (default invocation directory) --since Validate caller-held progress before continuing --limit Positive whole-entry batch limit --accept-limits Explicit coverage opt-ins, comma-separated: history,branches,original-records,embedded-content ls options: --cwd Only sessions whose workspace is exactly this directory (default invocation directory) --all-workspaces Every workspace; not combinable with --cwd --headless Also return headless runs (default: omit them) --harness Comma-separated harnesses (default: all of them) --limit Positive row limit; truncates the rows printed, not the walk --since-time Only sources written at or after this UTC instant, as YYYY-MM-DDTHH:MM:SS[.mmm]Z. An older source is never opened, so it costs one stat and no parse Common options: -h, --help Show help -V, --version Show version Stdout is JSONL: source, complete native records, terminal result. Only a complete result and exit 0 establish success. Failure exits 1; invalid arguments or unsupported operations exit 2. Output failures exit 1. No model, resume, instructions, extensions, store writes, or external attachment reads. Retained history includes saved branches and pre-compaction entries. No HCN index, retention, search, or persistent bookmark state. Enabled methods: Pi v3 file/ID with batches and bookmarks; Codex uncompressed legacy and paginated rollouts with ID/file lookup, batches and bookmarks. Each Codex source reports the cli_version its own header names as its writer build; the reader gates on the rollout's structure, not on that version. Codex inherited ranges are verified across sources; compressed files are unsupported. Claude main JSONL and Muse schema-1 session logs support ID/file reads, batches and bookmarks through a passive filesystem clone on supported macOS/Linux filesystems. Native formats and clone prerequisites apply. Compatible customized Pi must preserve the declared v3 storage semantics. Cursor chat stores (chats/*//store.db) and Antigravity untruncated step logs (brain//.system_generated/logs/transcript_full.jsonl) support ID/file reads, batches and bookmarks through the same clone. A Cursor chat whose store.db-wal holds writes (a running turn) refuses until the turn ends. ls walks each native store on every call and computes the rows from it; there is no index, no cache and no persistent state. Stdout is JSONL: one session-list-source header, one session row per saved session newest first, one session-list-result. A row carries harness, id, file, cwd, lastWriteAt, mode and readable. Its id and file are what transcript read --id and --file accept. mode is interactive, headless, or unknown where the store carries no marker; treat unknown as interactive unless you know better. Claude reads entrypoint and Codex reads session_meta source/originator; Pi, Muse, Cursor and Antigravity carry no observed marker. Child conversations are not rows: Claude sidechains, Codex spawned agent threads, Muse subagent/ sessions and Antigravity nested conversations. A harness with no listing method, and one whose store could not be read, are reported per harness in the result with the reason; the exit code stays 0 and the status reads partial. When HCN_OBSERVER names an executable file, the run streams lifecycle records (hcn-observer/1 NDJSON) to that command: one started line, each run event, and the terminal outcome. The harness child receives HCN_INVOCATION_ID. The observer is fire-and-forget and can never fail or slow the run; see docs/observer.md. `;