@pmelab/gtd 23.2.0 → 24.1.0

package/src/cli/Cli.ts

@@ -0,0 +1,1348 @@
+import { NodeContext } from "@effect/platform-node"
+import { Cause, Effect, Either, Layer } from "effect"
+import {
+  GtdUsageError,
+  Narrator,
+  renderFailure,
+  GitService,
+  Host,
+  Workspace,
+  CommandRunner,
+} from "../platform/index.js"
+import { GTD_VERSION } from "../install/index.js"
+import {
+  ConfigDiscovery,
+  ConfigService,
+  isSettingName,
+  SETTING_NAME_RULE,
+} from "../workflow/index.js"
+// The shared command types live in `Program.ts`, which imports nothing from
+// here, so this dependency stays one-directional.
+import {
+  runCommand,
+  SelectorUsageError,
+  type ArtifactOut,
+  type Command,
+  type CommandRequirements,
+  type JsonMode,
+} from "./Program.js"
+import type { ToolCommands } from "./ToolCommands.js"
+import { EXIT_OK, EXIT_RUNTIME_ERROR, EXIT_USAGE_ERROR } from "../wire/index.js"
+
+export type { Command, CommandRequirements } from "./Program.js"
+export { needsOf, standaloneKinds } from "./Program.js"
+
+export type CliPlan =
+  | { readonly kind: "output"; readonly stdout: string }
+  | {
+      readonly kind: "usage"
+      readonly stdout: string
+      readonly message: string
+      readonly json: boolean
+    }
+  | {
+      readonly kind: "command"
+      readonly command: Command
+      readonly json: JsonMode
+      /** Whether `--verbose`/`-v` was present — gates the `Narrator` `Cli.ts` builds for this dispatch (see `runCli`). */
+      readonly verbose: boolean
+    }
+
+// ---------------------------------------------------------------------------
+// Flag table
+// ---------------------------------------------------------------------------
+
+type FlagScope = (kind: Command["kind"] | undefined) => boolean
+
+interface FlagRow {
+  readonly name: string
+  /**
+   * `"optional"` is a third generic mode: a value only from the `=` form
+   * (`--json=<path>`), never consuming a following token — bare `--json`
+   * records presence with no value. See `tokenize`'s single generic branch.
+   */
+  readonly arity: 0 | 1 | "optional"
+  readonly repeatable: boolean
+  readonly scope: FlagScope
+  /** All raw occurrences (already de-`=`-ed) → the decoded value, or an error message. */
+  readonly decode: (raws: readonly string[]) => Either.Either<unknown, string>
+  readonly scopeError: string
+  readonly valueHint: string
+  /** Pre-wrapped help lines (data, not generated prose) — see `renderHelp`. */
+  readonly help: readonly string[]
+  /** Flag names this one may never appear alongside — checked generically after parsing (see `conflictViolation`), never as a bespoke `if`. Defaults to none. */
+  readonly conflicts?: readonly string[]
+}
+
+const nonNegativeNumber = (raw: string, flag: string): Either.Either<number, string> => {
+  const n = Number(raw)
+  if (raw.trim() === "" || !Number.isFinite(n) || n < 0) {
+    return Either.left(`gtd: ${flag} must be a non-negative number — got "${raw}"`)
+  }
+  return Either.right(n)
+}
+
+const FLAGS: readonly FlagRow[] = [
+  {
+    name: "--json",
+    arity: "optional",
+    repeatable: false,
+    scope: (kind) =>
+      kind === "next" ||
+      kind === "land" ||
+      kind === "judge" ||
+      kind === "judgeAnswer" ||
+      kind === "doors",
+    decode: ([raw]) => Either.right(raw ?? ""),
+    scopeError:
+      "gtd: --json is only valid for `gtd next`/`gtd land`/`gtd judge`/`gtd judge answer`/`gtd doors` — " +
+      "every other command prints plain text; see `gtd install` for the driver protocol briefing",
+    valueHint: "<path>",
+    help: [
+      "(gtd next/gtd land/gtd judge/gtd judge answer/gtd doors only) output",
+      "structured JSON. Bare --json prints the whole document;",
+      "--json=<path> (a dotted key path into that document, e.g.",
+      "kind, content, session.id) prints just that value: a",
+      "scalar raw and unquoted, a boolean as true/false, a list",
+      "one JSON entry per line — a numeric segment (e.g.",
+      "skills.0) indexes into one entry of a list field instead.",
+      "An absent optional field prints nothing and exits 0 —",
+      "including when an earlier segment of <path> is itself",
+      "absent/null (e.g. session.id at a non-prompt rest), which",
+      "never counts as unknown; an unknown path is a usage error",
+      "(exit 2).",
+    ],
+  },
+  {
+    name: "--port",
+    arity: 1,
+    repeatable: false,
+    scope: (kind) => kind === "ui",
+    decode: ([raw]) => {
+      const n = Number(raw)
+      return raw !== undefined && Number.isInteger(n) && n >= 0 && n <= 65535
+        ? Either.right(n)
+        : Either.left(`gtd: --port must be an integer 0–65535 (got '${raw ?? ""}')`)
+    },
+    scopeError: "gtd: --port is only valid for `gtd ui`",
+    valueHint: "<n>",
+    help: [
+      "(gtd ui only) the tailscale serve port (default: the first",
+      "free of 8443, 10000, 443), or the bind port when --host",
+      "opts out of serve (default: a free port)",
+    ],
+  },
+  {
+    name: "--host",
+    arity: 1,
+    repeatable: false,
+    scope: (kind) => kind === "ui",
+    decode: ([raw]) =>
+      raw === undefined || raw.trim() === "" || /[\r\n]/.test(raw)
+        ? Either.left("gtd: --host must be a non-empty, single-line value")
+        : Either.right(raw),
+    scopeError: "gtd: --host is only valid for `gtd ui`",
+    valueHint: "<addr>",
+    help: [
+      "(gtd ui only) opt out of the default tailscale serve front",
+      "door and bind this address directly instead, showing it in",
+      "the printed URL",
+    ],
+  },
+  {
+    name: "--self-signed",
+    arity: 0,
+    repeatable: false,
+    scope: (kind) => kind === "ui",
+    decode: () => Either.right(true),
+    scopeError: "gtd: --self-signed is only valid for `gtd ui`",
+    valueHint: "",
+    help: [
+      "(gtd ui only) generate a throwaway self-signed TLS",
+      "certificate instead of the configured ui.cert/ui.key",
+    ],
+  },
+  {
+    name: "--dev",
+    arity: 0,
+    repeatable: false,
+    scope: (kind) => kind === "ui",
+    decode: () => Either.right(true),
+    scopeError: "gtd: --dev is only valid for `gtd ui`",
+    valueHint: "",
+    help: ["(gtd ui only) run against local development sources", "instead of the packaged build"],
+  },
+  {
+    name: "--provider",
+    arity: 1,
+    repeatable: false,
+    scope: (kind) => kind === "judgeRun",
+    decode: ([raw]) =>
+      raw === "fixed" || raw === "jev" || raw === "llm"
+        ? Either.right(raw)
+        : Either.left(`gtd: --provider must be one of fixed, jev, llm — got "${raw ?? ""}"`),
+    scopeError: "gtd: --provider is only valid for `gtd judge run`",
+    valueHint: "<name>",
+    help: [
+      "(gtd judge run only) the answerer: fixed | jev | llm;",
+      "omitted: GTD_JUDGE_PROVIDER, then judge.json, then jev",
+      "when TYPESAFE_API_KEY is set, else llm",
+    ],
+  },
+  {
+    name: "--answers",
+    arity: 1,
+    repeatable: false,
+    scope: (kind) => kind === "judgeRun",
+    decode: ([raw]) =>
+      raw === undefined || raw === ""
+        ? Either.left("gtd: --answers must be a non-empty path")
+        : Either.right(raw),
+    scopeError: "gtd: --answers is only valid for `gtd judge run`",
+    valueHint: "<path>",
+    help: [
+      "(gtd judge run --provider fixed only) a JSON verdict array",
+      "[{ id, answer, p }]; else the GTD_JUDGE_ANSWERS env var",
+      "(inline JSON) is read",
+    ],
+  },
+  {
+    name: "--cost",
+    arity: 1,
+    repeatable: false,
+    scope: (kind) => kind === "land",
+    decode: ([raw]) => nonNegativeNumber(raw ?? "", "--cost"),
+    scopeError: "gtd: --cost is only valid for `gtd land` — a start is not a metered agent turn",
+    valueHint: "<n>",
+    help: ["(gtd land only) record the invocation's token cost"],
+  },
+  {
+    name: "--model",
+    arity: 1,
+    repeatable: false,
+    scope: (kind) => kind === "land" || kind === "judgeRun",
+    decode: ([raw]) =>
+      raw === undefined || raw.trim() === "" || /[\r\n]/.test(raw)
+        ? Either.left("gtd: --model must be a non-empty, single-line value")
+        : Either.right(raw),
+    scopeError: "gtd: --model is only valid for `gtd land` (with --cost) or `gtd judge run`",
+    valueHint: "<name>",
+    help: [
+      "(gtd land, with --cost) tag that cost's model",
+      "(gtd judge run, llm answerer) the claude model; omitted:",
+      "GTD_JUDGE_MODEL, then judge.json, then haiku",
+    ],
+  },
+  {
+    name: "--workflow",
+    arity: 1,
+    repeatable: false,
+    scope: (kind) => kind === "start",
+    decode: ([raw]) => Either.right(raw ?? ""),
+    scopeError:
+      "gtd: --workflow is only valid with no other command — use the bare `gtd --workflow <name>` " +
+      "form; landing and starting are different verbs",
+    valueHint: "<name>",
+    help: [
+      "(with no command at all) start a brand new process on",
+      "the named workflow — authenticated as human",
+    ],
+  },
+  {
+    name: "--var",
+    arity: 1,
+    repeatable: true,
+    scope: (kind) => kind === "start",
+    decode: (raws) => {
+      const vars: Record<string, string> = {}
+      const seen = new Set<string>()
+      for (const raw of raws) {
+        const eq = raw.indexOf("=")
+        if (eq <= 0) {
+          return Either.left(
+            `gtd: --var must be <name>=<value> with a non-empty name — got "${raw}"`,
+          )
+        }
+        const name = raw.slice(0, eq)
+        const value = raw.slice(eq + 1)
+        if (!isSettingName(name)) {
+          return Either.left(
+            `gtd: --var ${JSON.stringify(name)} is not a valid setting name — ${SETTING_NAME_RULE}`,
+          )
+        }
+        if (/[\r\n]/.test(value)) {
+          return Either.left(`gtd: --var ${name} must be a single-line value`)
+        }
+        if (seen.has(name)) {
+          return Either.left(`gtd: --var ${name} specified more than once`)
+        }
+        seen.add(name)
+        vars[name] = value
+      }
+      return Either.right(vars)
+    },
+    scopeError: "gtd: --var requires --workflow",
+    valueHint: "<name>=<value>",
+    help: [
+      "(with --workflow; repeatable) pin a process setting for the",
+      "new process; the name must already be declared by the",
+      "workflow's defaults (environment settings are not",
+      "pinnable)",
+    ],
+  },
+  {
+    name: "--open-questions",
+    arity: 0,
+    repeatable: false,
+    scope: (kind) => kind === "check",
+    decode: () => Either.right(true),
+    scopeError: "gtd: --open-questions is only valid for `gtd check`",
+    valueHint: "",
+    help: [
+      "(gtd check only) ignore <mode>'s structural findings and",
+      "instead run the qa open-questions predicate over <file>,",
+      "printing each unanswered question one per line and exiting",
+      "non-zero when any remain",
+    ],
+  },
+  {
+    name: "--open-threads",
+    arity: 0,
+    repeatable: false,
+    scope: (kind) => kind === "check",
+    decode: () => Either.right(true),
+    scopeError: "gtd: --open-threads is only valid for `gtd check`",
+    valueHint: "",
+    help: [
+      "(gtd check only) ignore <mode>'s structural findings and",
+      "instead list every open thread (a footnote whose last",
+      "entry is the agent's) over <file>, one per line with its",
+      "first H entry, exiting non-zero when any are open. With no",
+      "<mode>/<file>, lists code-comment threads in the files the",
+      "current process changed (read from its diff base, unlike",
+      "the rest of `gtd check`)",
+    ],
+  },
+  {
+    name: "--verbose",
+    arity: 0,
+    repeatable: false,
+    scope: () => true,
+    decode: () => Either.right(true),
+    scopeError: "gtd: --verbose is valid for every command — this error is unreachable",
+    valueHint: "",
+    help: [
+      "enable stderr narration for this invocation: which rest",
+      "resolved and how config resolved across layers. Aliased",
+      "to -v",
+    ],
+  },
+]
+
+/**
+ * `-v` is `--verbose`'s single-dash alias (the only one today) — resolved to
+ * its canonical `--` name before flag-row lookup, so the rest of the
+ * tokenizer never distinguishes how a flag was spelled. A `Map`, not a plain
+ * object: an object literal inherits `Object.prototype`, so a positional
+ * argument that happens to spell an inherited property name (`"valueOf"`,
+ * `"toString"`, …) would otherwise resolve to that inherited FUNCTION instead
+ * of `undefined`.
+ */
+const SINGLE_DASH_ALIASES: ReadonlyMap<string, string> = new Map([["-v", "--verbose"]])
+
+const flagByToken = (token: string): FlagRow | undefined => {
+  const eq = token.indexOf("=")
+  const bareName = eq === -1 ? token : token.slice(0, eq)
+  return FLAGS.find((f) => f.name === bareName)
+}
+
+// ---------------------------------------------------------------------------
+// Command table
+// ---------------------------------------------------------------------------
+
+type Arity =
+  | "none"
+  | { readonly name: string }
+  | { readonly names: readonly [string, string] }
+  // One required leading positional, then any number the command itself judges.
+  | { readonly name: string; readonly variadic: string }
+
+interface CommandRow {
+  readonly token: string
+  readonly kind: Command["kind"]
+  readonly arity: Arity
+  readonly details: readonly string[]
+}
+
+const COMMAND_ROWS: readonly CommandRow[] = [
+  {
+    token: "land",
+    kind: "land",
+    arity: "none",
+    details: [
+      "Land whatever the tree now shows at the currently resolved",
+      "rest — a human capture, an agent/check turn, or an empty",
+      "attempt (a fruitless prompt turn). Pass",
+      "--cost=<n> (optionally --model=<name>) to record the",
+      "just-finished invocation's token cost and model on the",
+      "turn commit (summed into it.processCost/",
+      "processCostByModel). Plain (the default) prints one",
+      "human-readable sentence naming the commit subject (or a",
+      "no-op note) plus a pointer to `gtd land --json=script | sh`",
+      "to get the landing script — never the script itself.",
+      "--json emits script (the actual POSIX sh",
+      "a driver runs) alongside settled, idle, state (the",
+      "post-land target), subject, cost and model. Exits 0 on",
+      "success, 1 on any refusal — see the Exit codes section",
+      "below",
+    ],
+  },
+  {
+    token: "abandon",
+    kind: "abandon",
+    arity: "none",
+    details: [
+      "End the process currently underway without completing it:",
+      "rewind HEAD to the commit the process started from,",
+      "keeping everything it produced as uncommitted changes. A",
+      "no-op when no process is underway",
+    ],
+  },
+  {
+    token: "restore",
+    kind: "restore",
+    arity: "none",
+    details: [
+      "Hard-reset HEAD back to the tip retained by the last",
+      "abandon (refs/worktree/gtd/history), bringing back an",
+      "abandoned process's turns. Refuses on a dirty working",
+      "tree, when there is no retained history, or when HEAD has",
+      "advanced past the retained tip with commits that would be",
+      "lost",
+    ],
+  },
+  {
+    token: "next",
+    kind: "next",
+    arity: "none",
+    details: [
+      "Print the resolved rest's beat (no mutation, safe to",
+      "poll), in one of three encodings. Plain (the default): a",
+      "status summary, a blank line, then the step verbatim — at a",
+      "script/capture rest an instruction line ('Run this",
+      "script:' / 'The edit is already made — run `gtd land` to",
+      "land it.') precedes the status summary; at a prompt rest",
+      "it's the bare step (plus the self-validation instruction",
+      "when applicable) with no header at all, since those bytes",
+      "are the agent's own input. --json emits the one structured",
+      "surface gtd has: kind (capture|message|script|prompt|",
+      "stalled) selects what a driver does, content is what it",
+      "runs or shows, idle marks the workflow's initial state with",
+      "a clean tree, plus the prompt session, model, validate",
+      "script, log path, changes, next and the resting state's own",
+      "fields. --json=<path> (a dotted key path into that same",
+      "document, e.g. kind, content, session.id) prints just that",
+      "value instead of the whole document — see --json's own help",
+      "above. Exits 0 — see the Exit codes section below",
+    ],
+  },
+  {
+    token: "validate",
+    kind: "validate",
+    arity: "none",
+    details: [
+      "Print the script that formats (when declared) then",
+      "validates the resolved rest's steering file, using its",
+      "mode's commands (its file:/mode:), instead of running it —",
+      "a driver runs the script and reads the findings from its",
+      'own exit code/output. Always exits 0; prints "nothing to',
+      'validate" when the resolved rest declares nothing to run.',
+      "On a non-zero validate exit the emitted script prints a",
+      "ready-to-send fix prompt (instruction + findings) and",
+      "exits with the validator's own code",
+    ],
+  },
+  {
+    token: "lsp",
+    kind: "lsp",
+    arity: "none",
+    details: ["Start the LSP server for .gtd/ steering files (stdio)"],
+  },
+  {
+    token: "ui",
+    kind: "ui",
+    arity: "none",
+    details: [
+      "Expose gtd's web/phone client for THIS worktree — the",
+      "invoking directory, never a configured list of roots — and",
+      "refuses outside a repository like every other state command.",
+      "By default, publishes through `tailscale serve` (reachable",
+      "from anywhere on the tailnet, including over a DERP relay)",
+      "with tailscaled terminating TLS, walking 8443, then 10000,",
+      "then 443 until one publishes; falls back to binding a local",
+      "HTTPS server directly, never refusing, when none of the",
+      "three works. --host <addr> opts out of serve and binds that",
+      "address directly instead; --port <n> overrides the serve",
+      "port (default: the first free of 8443, 10000, 443), or the",
+      "bind port when --host is given (default: a free port);",
+      "--self-signed also opts out of serve, generating a",
+      "throwaway TLS certificate instead of the configured",
+      "ui.cert/ui.key; --dev runs against local development sources",
+      "instead of the packaged build",
+    ],
+  },
+  {
+    token: "check",
+    kind: "check",
+    arity: { names: ["mode", "file"] },
+    details: [
+      "Read <file> and run the built-in steering format named",
+      "<mode> (see `gtd validate`'s modes: qa, review) over its",
+      "contents, printing each finding one per line and exiting",
+      "non-zero when there are any. Resolves no workflow state and",
+      "reads no config — standalone, runnable from any directory",
+      "with <mode>/<file> given explicitly. This is what a",
+      "workflow's emitted validation script invokes as a leaf step.",
+      "--open-questions runs the qa unanswered-questions predicate",
+      "instead (see --help); --open-threads lists open threads.",
+      "`gtd check --open-threads` alone lists open code-comment",
+      "threads (`// H: ...`) in the files the process changed;",
+      "it prints nothing when no process is underway.",
+    ],
+  },
+  {
+    token: "uncheck",
+    kind: "uncheck",
+    arity: { name: "file" },
+    details: [
+      "Read <file> and reset every review-mode `- [x]`/`- [X]`",
+      "file-pointer box back to `- [ ]`, writing the result back",
+      "only when the bytes actually changed. Resolves no workflow",
+      "state and reads no config — standalone, runnable from any",
+      "directory with <file> given explicitly. This is what the",
+      "landing script runs ahead of the commit at the human review",
+      "gate, so no tick ever reaches a commit. Takes no <mode> —",
+      "it means review-mode file pointers and nothing else, never",
+      "qa-mode's answered-question boxes. A missing file writes",
+      "nothing and exits 0",
+    ],
+  },
+  {
+    token: "install",
+    kind: "install",
+    arity: "none",
+    details: [
+      "Print a complete, self-contained briefing that teaches an",
+      "agent (or a human) to build a gtd driver in any shell or",
+      "runtime — the self-serve version of",
+      "https://github.com/pmelab/gtd/blob/main/docs/driver.md's",
+      "'Writing your own driver'. At a repository root no",
+      "gtd.config.ts governs yet, it also writes one importing each",
+      "shipped workflow from @pmelab/gtd/workflows/<name>; anywhere",
+      "else it writes nothing.",
+    ],
+  },
+  {
+    token: "loop",
+    kind: "loop",
+    arity: "none",
+    details: [
+      "Drive this worktree's process until it rests on you: read",
+      "each beat, run the agent turn or script it demands, and",
+      "land the result. Exits 0 at a human gate, at idle and when",
+      "a landing settles; exits 1 on a stall or a failed turn or",
+      "landing. The agent CLI and the model each workflow hint",
+      "maps to are per-machine settings (GTD_LOOP_* variables, or",
+      "~/.config/gtd/loop.json); see docs/driver.md",
+    ],
+  },
+  {
+    token: "summary",
+    kind: "summary",
+    arity: "none",
+    details: [
+      "Print the prompt for an agent to write the process HEAD",
+      "closes or sits inside its own closing message — the entry",
+      "commit, each human-authored commit (a review round, an",
+      "answered question gate), the diff range to inspect, and",
+      "it.processCost/processCostByModel. Writes nothing: no git,",
+      "no state transition, no file, no session identity — the",
+      "driver pipes the output to a cold agent and does what it",
+      "wants with the result (a squash, an amend, a PR body).",
+      "Refuses (exit 1) when the workflow declares no summary:",
+      "template, or when the resolved run has no commits to name",
+      "— runnable any time before the next thing lands on the",
+      "branch",
+    ],
+  },
+  {
+    token: "base",
+    kind: "base",
+    arity: "none",
+    details: [
+      "Print the review anchor hash — the diff base an external",
+      "tool (a diff, a PR tool, another agent) should point at —",
+      "bare, newline-terminated, and nothing else. Writes nothing:",
+      "no git, no state transition, no session identity. Before",
+      "the first review round it's the process's diff base;",
+      "afterward it's the most-recent review round's boundary.",
+      "Refuses (exit 1) when no process is underway.",
+    ],
+  },
+  {
+    token: "door",
+    kind: "door",
+    arity: { name: "name", variadic: "args" },
+    details: [
+      "Start a process through a named shortcut, mapping the",
+      "positional args to that workflow's process settings — the",
+      "same start `gtd --workflow` makes, printed the same way.",
+      "Each workflow the config exports brings its own doors (gtd's",
+      "`fix` brings `fix`, `review` brings `review [base]`), plus",
+      "the config's `doors` export. An unknown door, or too few or",
+      "too many args, is a usage error (exit 2) naming the doors or",
+      "the door's synopsis",
+    ],
+  },
+  {
+    token: "doors",
+    kind: "doors",
+    arity: "none",
+    details: [
+      "List every door, sorted: one `name [args] → workflow` line",
+      "each. --json prints one JSON array of { name, workflow,",
+      "args: [{ name, optional }] } instead; --json=<path> reads one",
+      "value off it. Writes nothing",
+    ],
+  },
+  {
+    token: "judge",
+    kind: "judge",
+    arity: "none",
+    details: [
+      "Print the resolved rest's pending judgment — the prepared",
+      "state, its typed questions, and their criteria — the same",
+      "judge field `gtd next --json` already carries. Read-only:",
+      "resolves no session, writes nothing. Refuses (exit 1) when",
+      "the resolved rest declares no judge:",
+    ],
+  },
+  {
+    token: "judge answer",
+    kind: "judgeAnswer",
+    arity: "none",
+    details: [
+      "Read a verdict off stdin — one { id, answer, p } entry per",
+      "question the pending judgment declared — and decode it",
+      "against an Effect Schema built from those same question",
+      "ids. Refuses (exit 1) when the resolved rest declares no",
+      "judge:. Exits 2 (a usage error, like an unknown --json",
+      "selector) when stdin isn't valid JSON or the verdict",
+      "doesn't decode against the pending question ids.",
+    ],
+  },
+  {
+    token: "judge run",
+    kind: "judgeRun",
+    arity: "none",
+    details: [
+      "Answer a judgment: read the `gtd judge --json` document off",
+      "stdin, write a verdict [{ id, answer, p }] on stdout — what",
+      "`gtd judge answer` decodes. --provider fixed answers from",
+      "--answers <path> or GTD_JUDGE_ANSWERS; questions the file",
+      "does not cover are left out. --provider jev asks TypeSafe",
+      "(TYPESAFE_API_KEY). --provider llm asks the `claude` CLI",
+      "on PATH (Claude Code only), model haiku unless --model.",
+      "No --provider: GTD_JUDGE_PROVIDER, then ~/.config/gtd/",
+      "judge.json, else jev when TYPESAFE_API_KEY is set and no",
+      "model is given, else llm; --model likewise falls back to",
+      "GTD_JUDGE_MODEL, then the file's model. Needs no",
+      "repository. jev and llm exit 1 when they cannot answer",
+      "every question, with nothing on stdout",
+    ],
+  },
+]
+
+const commandByToken = (token: string): CommandRow | undefined =>
+  COMMAND_ROWS.find((r) => r.token === token)
+
+// ---------------------------------------------------------------------------
+// Help rendering
+// ---------------------------------------------------------------------------
+
+const COLUMN = 19
+
+const renderBlock = (header: string, lines: readonly string[]): string => {
+  const [first, ...rest] = lines
+  const headerCell = `  ${header}`
+  const headerLine =
+    headerCell.length < COLUMN
+      ? `${headerCell.padEnd(COLUMN)}${first ?? ""}\n`
+      : `${headerCell}\n${" ".repeat(COLUMN)}${first ?? ""}\n`
+  return headerLine + rest.map((l) => `${" ".repeat(COLUMN)}${l}\n`).join("")
+}
+
+const START_SHORT_FORM = renderBlock("(no command) --workflow <name>", [
+  "Starts a new process authenticated as human, e.g.",
+  "'gtd --workflow <name>'",
+])
+
+const VERSION_BLOCK = renderBlock("version", ["Print version and exit"])
+const HELP_BLOCK = renderBlock("help", ["Print this help and exit"])
+
+const SPACE_FORM_FLAGS = new Set(["--workflow", "--var"])
+
+const flagHeader = (row: FlagRow): string => {
+  if (row.valueHint === "") return row.name
+  return SPACE_FORM_FLAGS.has(row.name)
+    ? `${row.name} ${row.valueHint}`
+    : `${row.name}=${row.valueHint}`
+}
+
+export const renderHelp = (): string => {
+  const commandBlocks = COMMAND_ROWS.map((row) => {
+    const header =
+      row.arity === "none"
+        ? row.token
+        : "names" in row.arity
+          ? `${row.token} <${row.arity.names[0]}> <${row.arity.names[1]}>`
+          : "variadic" in row.arity
+            ? `${row.token} <${row.arity.name}> [${row.arity.variadic}...]`
+            : `${row.token} <${row.arity.name}>`
+    return renderBlock(header, row.details)
+  })
+  const commands = [
+    commandBlocks[0], // land
+    START_SHORT_FORM,
+    ...commandBlocks.slice(1), // abandon..base
+    VERSION_BLOCK,
+    HELP_BLOCK,
+  ].join("")
+
+  const options = FLAGS.map((row) => renderBlock(flagHeader(row), row.help)).join("")
+  const versionHelpOptions =
+    renderBlock("--version, -V", ["Print version and exit"]) +
+    renderBlock("--help, -h", ["Print this help and exit"])
+
+  return (
+    `Usage: gtd [command] [options]\n\n` +
+    `Commands:\n${commands}\n` +
+    `Options:\n${options}${versionHelpOptions}`
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Tokenizer
+// ---------------------------------------------------------------------------
+
+interface TokenizeError {
+  readonly kind: "error"
+  readonly message: string
+  readonly jsonSeen: boolean
+}
+
+interface TokenizeOk {
+  readonly kind: "ok"
+  readonly positionals: readonly string[]
+  readonly byFlag: ReadonlyMap<string, readonly string[]>
+  readonly present: ReadonlySet<string>
+  readonly jsonSeen: boolean
+}
+
+// fallow-ignore-next-line complexity
+const tokenize = (tail: readonly string[]): TokenizeError | TokenizeOk => {
+  const positionals: string[] = []
+  const byFlag = new Map<string, string[]>()
+  const present = new Set<string>()
+  let jsonSeen = false
+
+  for (let i = 0; i < tail.length; i++) {
+    const original = tail[i]!
+    const tok = SINGLE_DASH_ALIASES.get(original) ?? original
+    if (!tok.startsWith("--")) {
+      positionals.push(original)
+      continue
+    }
+    const row = flagByToken(tok)
+    if (row === undefined) {
+      return {
+        kind: "error",
+        message: `gtd: unknown option '${tok}' — see \`gtd --help\``,
+        jsonSeen,
+      }
+    }
+    const eq = tok.indexOf("=")
+    const alreadyPresent = present.has(row.name)
+    present.add(row.name)
+    if (row.name === "--json") jsonSeen = true
+
+    if (row.arity === 0) {
+      if (eq !== -1) {
+        return {
+          kind: "error",
+          message: `gtd: unknown option '${tok}' — see \`gtd --help\``,
+          jsonSeen,
+        }
+      }
+      if (!byFlag.has(row.name)) byFlag.set(row.name, [])
+      continue
+    }
+
+    if (row.arity === "optional") {
+      if (!row.repeatable && alreadyPresent) {
+        return { kind: "error", message: `gtd: ${row.name} may be given at most once`, jsonSeen }
+      }
+      if (eq !== -1) {
+        const value = tok.slice(eq + 1)
+        if (value === "") {
+          // Unlike arity-1, an "optional" flag's bare/space form is a
+          // deliberate, DIFFERENT meaning (presence with no value) — never a
+          // rejected value-missing form — so this message names only the
+          // one legal way to supply a value, `=`, not the arity-1 template's
+          // "or <name> <value>" (which would recommend the very space form
+          // the settled decisions make a usage error on purpose).
+          return {
+            kind: "error",
+            message: `gtd: ${row.name} requires a value — use ${row.name}=${row.valueHint}`,
+            jsonSeen,
+          }
+        }
+        byFlag.set(row.name, [value])
+        continue
+      }
+      // Bare presence — never consumes the following token, unlike arity 1.
+      if (!byFlag.has(row.name)) byFlag.set(row.name, [])
+      continue
+    }
+
+    let raw: string
+    if (eq !== -1) {
+      raw = tok.slice(eq + 1)
+    } else {
+      const next = tail[i + 1]
+      if (next === undefined || next.startsWith("--")) {
+        raw = ""
+      } else {
+        raw = next
+        i++
+      }
+    }
+    if (raw === "") {
+      return {
+        kind: "error",
+        message: `gtd: ${row.name} requires a value — use ${row.name}=${row.valueHint} or ${row.name} ${row.valueHint}`,
+        jsonSeen,
+      }
+    }
+    const existing = byFlag.get(row.name) ?? []
+    if (!row.repeatable && existing.length >= 1) {
+      return { kind: "error", message: `gtd: ${row.name} may be given at most once`, jsonSeen }
+    }
+    byFlag.set(row.name, [...existing, raw])
+  }
+
+  return { kind: "ok", positionals, byFlag, present, jsonSeen }
+}
+
+// ---------------------------------------------------------------------------
+// parseArgv
+// ---------------------------------------------------------------------------
+
+const usagePlan = (message: string, json: boolean, stdout = ""): CliPlan => ({
+  kind: "usage",
+  stdout,
+  message,
+  json,
+})
+
+const scopeViolation = (
+  kind: Command["kind"] | undefined,
+  present: ReadonlySet<string>,
+): string | undefined => {
+  for (const row of FLAGS) {
+    if (present.has(row.name) && !row.scope(kind)) return row.scopeError
+  }
+  return undefined
+}
+
+/** A table field, not an `if`: any row present alongside a flag it names in `conflicts` is a usage error — checked generically over every row, so a new conflicting pair is one table edit. */
+const conflictViolation = (present: ReadonlySet<string>): string | undefined => {
+  for (const row of FLAGS) {
+    if (!present.has(row.name)) continue
+    for (const other of row.conflicts ?? []) {
+      if (present.has(other)) return `gtd: ${row.name} and ${other} are mutually exclusive`
+    }
+  }
+  return undefined
+}
+
+const arityError = (cmd: string, rest: readonly string[], arity: Arity): string | undefined => {
+  if (arity === "none") {
+    return rest.length > 0
+      ? `gtd ${cmd}: too many arguments — expected none, got: ${rest.join(", ")}`
+      : undefined
+  }
+  if ("names" in arity) return pairArityError(cmd, rest, arity.names)
+  if (rest.length === 0) return `gtd ${cmd}: missing ${arity.name} argument`
+  if (!("variadic" in arity) && rest.length > 1) {
+    return `gtd ${cmd}: too many arguments — expected one ${arity.name}, got: ${rest.join(", ")}`
+  }
+  return undefined
+}
+
+const pairArityError = (
+  cmd: string,
+  rest: readonly string[],
+  [first, second]: readonly [string, string],
+): string | undefined => {
+  if (rest.length === 0) return `gtd ${cmd}: missing ${first} and ${second} arguments`
+  if (rest.length === 1) return `gtd ${cmd}: missing ${second} argument`
+  if (rest.length > 2) {
+    return `gtd ${cmd}: too many arguments — expected ${first} and ${second}, got: ${rest.join(", ")}`
+  }
+  return undefined
+}
+
+/** Decode every present flag into a bag of values, or the first decode error encountered. */
+const decodeFlags = (
+  byFlag: ReadonlyMap<string, readonly string[]>,
+): Either.Either<Readonly<Record<string, unknown>>, string> => {
+  const bag: Record<string, unknown> = {}
+  for (const row of FLAGS) {
+    const raws = byFlag.get(row.name)
+    if (raws === undefined) continue
+    // A bare `"optional"`-arity flag (e.g. `--json` with no `=`) has nothing
+    // to decode — presence alone is tracked via `present`, not the bag.
+    if (row.arity === "optional" && raws.length === 0) continue
+    const decoded = row.decode(raws)
+    if (Either.isLeft(decoded)) return Either.left(decoded.left)
+    bag[row.name] = decoded.right
+  }
+  return Either.right(bag)
+}
+
+/** Assembles a `land` `Command` from its already-scope-checked flag bag — split out of `parseArgv` so its two independent, omit-when-absent optional fields don't inflate that function's own branching. */
+const buildLandCommand = (bag: {
+  readonly "--cost"?: number
+  readonly "--model"?: string
+}): Command => ({
+  kind: "land",
+  ...(bag["--cost"] !== undefined ? { cost: bag["--cost"] } : {}),
+  ...(bag["--model"] !== undefined ? { model: bag["--model"] } : {}),
+})
+
+// fallow-ignore-next-line complexity
+export const parseArgv = (argv: readonly string[]): CliPlan => {
+  if (argv.includes("--help") || argv.includes("-h"))
+    return { kind: "output", stdout: renderHelp() }
+  if (argv.includes("--version") || argv.includes("-V")) {
+    return { kind: "output", stdout: `${GTD_VERSION}\n` }
+  }
+
+  const tokenized = tokenize(argv.slice(2))
+  if (tokenized.kind === "error") return usagePlan(tokenized.message, tokenized.jsonSeen)
+  const { positionals, byFlag, present, jsonSeen } = tokenized
+
+  const first = positionals[0]
+  const workflowRaw = byFlag.get("--workflow")?.[0]
+  const workflowPresent = workflowRaw !== undefined
+
+  if (first === "version") return { kind: "output", stdout: `${GTD_VERSION}\n` }
+  if (first === "help") return { kind: "output", stdout: renderHelp() }
+
+  const row = first === undefined ? undefined : commandByToken(first)
+
+  // `gtd judge answer` — the CLI's one two-level verb. The NORMAL path is
+  // "answer" arriving as `positionals[1]`, a second token after "judge" —
+  // detected below via `judgeAnswer`, not through a second dispatchable
+  // `COMMAND_ROWS` row: the `"judge answer"`-tokened row above exists for
+  // `renderHelp()`'s two-line entry. It CAN also be matched by
+  // `commandByToken` directly, but only if a caller passes the single
+  // (space-containing) argv token `"judge answer"` — an unusual shell quoting
+  // choice, not the normal two-argv-token invocation `gtd judge answer` — and
+  // `row.kind` is `"judgeAnswer"` either way, so nothing downstream branches
+  // differently between the two paths. `row`'s own arity (still "none",
+  // judge's own) applies to whatever follows "answer" below, so no bespoke
+  // `Arity` variant is needed for this one verb.
+  const judgeAnswer = row?.kind === "judge" && positionals[1] === "answer"
+
+  // The `--workflow` selector: no command at all, with `--workflow` present,
+  // resolves to the generic `start` command instead — landing and starting
+  // are different verbs, so `gtd land --workflow <name>` is NOT a synonym (it
+  // fails the scope check below instead).
+  const selectsStart = workflowPresent && first === undefined
+  const judgeRun = row?.kind === "judge" && positionals[1] === "run"
+  const kind: Command["kind"] | undefined = selectsStart
+    ? "start"
+    : judgeAnswer
+      ? "judgeAnswer"
+      : judgeRun
+        ? "judgeRun"
+        : row?.kind
+
+  if (row === undefined && !selectsStart) {
+    // No dispatchable row resolved (missing/unknown command) — a scoped flag
+    // used here (e.g. `--var` with no `--workflow`) is a more specific error
+    // than "missing command"/"unknown command", so it takes priority (mirrors
+    // the old parser, which validated --workflow/--var/--cost/--model ahead of
+    // subcommand resolution).
+    const violation = scopeViolation(undefined, present)
+    if (violation !== undefined) return usagePlan(violation, jsonSeen)
+    if (first === undefined) {
+      return usagePlan(
+        "gtd: missing command — gtd decides and prints, a driver executes; " +
+          "run `gtd install`, or copy one from " +
+          "https://github.com/pmelab/gtd/blob/main/docs/driver.md's " +
+          '"A complete minimal driver" section and run that, or see usage ' +
+          "above (`gtd --help`)",
+        jsonSeen,
+        renderHelp(),
+      )
+    }
+    return usagePlan(`unknown command '${first}'`, jsonSeen)
+  }
+
+  // From here, `kind` is a genuine `Command["kind"]`. `judgeAnswer` consumes
+  // TWO leading positionals ("judge" and "answer"), everything else one.
+  const restPositionals =
+    first === undefined ? positionals : positionals.slice(judgeAnswer || judgeRun ? 2 : 1)
+
+  if (kind === "start" && first === undefined) {
+    if (restPositionals.length > 0) {
+      return usagePlan(
+        `gtd: too many arguments — expected none, got: ${restPositionals.join(", ")}`,
+        jsonSeen,
+      )
+    }
+  } else {
+    // `kind === "start"` is unreachable here: `selectsStart` only fires when
+    // `first === undefined`, which the `if` branch above already handled.
+    const bareCheck =
+      kind === "check" && restPositionals.length === 0 && present.has("--open-threads")
+    const arityMsg = bareCheck ? undefined : arityError(first!, restPositionals, row!.arity)
+    if (arityMsg !== undefined) return usagePlan(arityMsg, jsonSeen)
+  }
+
+  const violation = scopeViolation(kind, present)
+  if (violation !== undefined) return usagePlan(violation, jsonSeen)
+
+  const conflict = conflictViolation(present)
+  if (conflict !== undefined) return usagePlan(conflict, jsonSeen)
+
+  const decoded = decodeFlags(byFlag)
+  if (Either.isLeft(decoded)) return usagePlan(decoded.left, jsonSeen)
+  const bag = decoded.right as {
+    readonly "--json"?: string
+    readonly "--port"?: number
+    readonly "--cost"?: number
+    readonly "--model"?: string
+    readonly "--var"?: Readonly<Record<string, string>>
+    readonly "--open-questions"?: boolean
+    readonly "--open-threads"?: boolean
+    readonly "--host"?: string
+    readonly "--self-signed"?: boolean
+    readonly "--dev"?: boolean
+    readonly "--provider"?: "fixed" | "jev" | "llm"
+    readonly "--answers"?: string
+  }
+
+  // `present.has("--json")` alone can't distinguish bare `--json` (no value
+  // decoded) from `--json=<path>` (a value in the bag) — see `decodeFlags`'s
+  // optional-arity skip above.
+  const json: JsonMode = !present.has("--json")
+    ? { kind: "off" }
+    : bag["--json"] !== undefined
+      ? { kind: "select", path: bag["--json"] }
+      : { kind: "document" }
+  const verbose = present.has("--verbose")
+
+  if (kind === "land") {
+    if (bag["--model"] !== undefined && bag["--cost"] === undefined) {
+      return usagePlan(
+        "gtd: --model requires --cost — it tags the recorded cost with the model that ran",
+        jsonSeen,
+      )
+    }
+    return { kind: "command", command: buildLandCommand(bag), json, verbose }
+  }
+
+  if (kind === "start") {
+    const label = `gtd --workflow ${workflowRaw}`
+    return {
+      kind: "command",
+      command: {
+        kind: "start",
+        actor: "human",
+        workflow: workflowRaw!,
+        vars: bag["--var"] ?? {},
+        label,
+      },
+      json,
+      verbose,
+    }
+  }
+
+  if (kind === "door") {
+    return {
+      kind: "command",
+      command: { kind: "door", name: restPositionals[0]!, args: restPositionals.slice(1) },
+      json,
+      verbose,
+    }
+  }
+
+  if (kind === "ui") {
+    return {
+      kind: "command",
+      command: {
+        kind: "ui",
+        ...(bag["--host"] !== undefined ? { host: bag["--host"] } : {}),
+        ...(bag["--port"] !== undefined ? { port: bag["--port"] } : {}),
+        selfSigned: bag["--self-signed"] ?? false,
+        dev: bag["--dev"] ?? false,
+      },
+      json,
+      verbose,
+    }
+  }
+
+  if (kind === "check") {
+    return {
+      kind: "command",
+      command: {
+        kind: "check",
+        ...(restPositionals[0] !== undefined ? { mode: restPositionals[0] } : {}),
+        ...(restPositionals[1] !== undefined ? { file: restPositionals[1] } : {}),
+        ...(bag["--open-questions"] !== undefined
+          ? { openQuestions: bag["--open-questions"] }
+          : {}),
+        ...(bag["--open-threads"] !== undefined ? { openThreads: bag["--open-threads"] } : {}),
+      },
+      json,
+      verbose,
+    }
+  }
+
+  if (kind === "judgeRun") {
+    const provider = bag["--provider"]
+    if (provider !== "fixed" && bag["--answers"] !== undefined) {
+      return usagePlan("gtd judge run: --answers is only valid with --provider fixed", jsonSeen)
+    }
+    if ((provider === "fixed" || provider === "jev") && bag["--model"] !== undefined) {
+      return usagePlan(
+        "gtd judge run: --model is only valid with --provider llm (or when it is auto-selected)",
+        jsonSeen,
+      )
+    }
+    return {
+      kind: "command",
+      command: {
+        kind: "judgeRun",
+        ...(provider !== undefined ? { provider } : {}),
+        ...(bag["--answers"] !== undefined ? { answers: bag["--answers"] } : {}),
+        ...(bag["--model"] !== undefined ? { model: bag["--model"] } : {}),
+      },
+      json,
+      verbose,
+    }
+  }
+
+  if (kind === "uncheck") {
+    return {
+      kind: "command",
+      command: { kind: "uncheck", file: restPositionals[0]! },
+      json,
+      verbose,
+    }
+  }
+
+  // Every other kind carries no extra fields.
+  const command: Command = {
+    kind: kind as
+      | "lsp"
+      | "abandon"
+      | "restore"
+      | "next"
+      | "validate"
+      | "install"
+      | "loop"
+      | "doors"
+      | "summary"
+      | "base"
+      | "judge"
+      | "judgeAnswer",
+  }
+  return { kind: "command", command, json, verbose }
+}
+
+// ---------------------------------------------------------------------------
+// runCli
+// ---------------------------------------------------------------------------
+
+export interface CliIo {
+  readonly stdout: (chunk: string) => void
+  readonly stderr: (chunk: string) => void
+  readonly exit: (code: number) => void
+  /**
+   * Deferred thunk — a layer is built only for a resolved `Command`, never
+   * for `--version`/`--help`/a usage error. `verbose` (`--verbose`/`-v`,
+   * decoded by `parseArgv`) gates the `Narrator` this builds — a no-op
+   * writer when `false`.
+   */
+  readonly layers: (verbose: boolean) => Layer.Layer<CommandRequirements>
+}
+
+// The one write-to-stderr primitive nodeCliIo uses for both `stderr` (errors)
+// and `layers`'s `Narrator` (narration) — same sink, so a real invocation's
+// narration and its remediation interleave on the same fd exactly as
+// written.
+const writeStderr = (chunk: string): void => {
+  process.stderr.write(chunk)
+}
+
+export type LiveToolCommands = Layer.Layer<
+  ToolCommands,
+  never,
+  Exclude<CommandRequirements, ToolCommands> | NodeContext.NodeContext
+>
+
+export const nodeCliIo = (tools: LiveToolCommands): CliIo => ({
+  // `process.stdout.write` is asynchronous whenever stdout is a pipe or
+  // socket — passing a completion callback (and never force-closing, see
+  // `exit` below) keeps a queued remainder from being discarded, so a large
+  // artifact still reaches a slow reader even after a non-zero exit.
+  stdout: (chunk) => {
+    process.stdout.write(chunk, () => {})
+  },
+  stderr: writeStderr,
+  exit: (code) => {
+    // Never `process.exit(code)`: that tears the process down out from under
+    // an undrained `stdout.write` above and truncates the artifact mid-pipe.
+    // Setting `exitCode` lets the event loop run to completion — draining
+    // any queued write — before Node exits gracefully with this code.
+    process.exitCode = code
+  },
+  // A Layer is a lazy description, not a running service — building this
+  // object touches no filesystem/git; only `Effect.provide` running the
+  // result does. `runCli` calls this thunk exactly when `plan.kind ===
+  // "command"`, so --version/--help/a usage error never provoke it.
+  layers: (verbose) =>
+    // Dependency order matters: Workspace.Live needs GitService, both need
+    // Host, and GitService needs NodeContext's CommandExecutor. Each
+    // `provideMerge` satisfies the layers above it AND stays in the output.
+    tools.pipe(
+      Layer.provideMerge(
+        Layer.mergeAll(
+          ConfigService.Live,
+          ConfigDiscovery.Live,
+          Workspace.Live,
+          Narrator.layer(writeStderr, verbose),
+          CommandRunner.Live,
+        ).pipe(
+          Layer.provideMerge(GitService.Live),
+          Layer.provideMerge(Host.Live),
+          Layer.provideMerge(NodeContext.layer),
+        ),
+      ),
+    ),
+})
+
+/**
+ * Normalizes an artifact's trailing newlines to exactly one — an emitted
+ * script ends with none, plain text already ends with one, so this is the
+ * single place both become uniform. A byte-empty artifact stays byte-empty
+ * (never becomes a lone `\n`); several trailing newlines collapse to one.
+ */
+export const normalizeTrailingNewline = (artifact: string): string =>
+  artifact.length === 0 ? artifact : `${artifact.replace(/\n+$/, "")}\n`
+
+const bufferedArtifactOut = (io: CliIo): ArtifactOut => {
+  let buffer = ""
+  return {
+    write: (chunk) => {
+      buffer += chunk
+    },
+    flush: () => {
+      if (buffer.length > 0) io.stdout(normalizeTrailingNewline(buffer))
+      buffer = ""
+    },
+  }
+}
+
+/**
+ * The single envelope writer: `{state:"error",prompt}` on **stderr** under
+ * `--json`, `renderFailure` on stderr always, exit `EXIT_RUNTIME_ERROR`.
+ * stdout is never touched here — the command's `ArtifactOut` buffer was never
+ * flushed, so a `--json` driver reading stdout on a failed run reads nothing
+ * — it must read stderr or the exit code instead. `Effect.sandbox` means this also
+ * fires for a DEFECT, not just a typed error. Unreached by an ordinary usage
+ * error (an unknown flag, bad arity, a scope violation) — those never build a
+ * layer at all. Two exceptions map to `EXIT_USAGE_ERROR` instead, below:
+ * `SelectorUsageError` (an unknown `--json=<path>` selector can only be
+ * judged after the layer is built and the fields object it's reduced
+ * against is fully resolved, so it fails HERE rather than in `parseArgv`)
+ * and `GtdUsageError` (`gtd ui` refusing to start on a step it cannot
+ * render — see `Commentary.ts`).
+ */
+const report =
+  (io: CliIo, json: boolean) =>
+  (cause: Cause.Cause<Error>): Effect.Effect<void> =>
+    Effect.sync(() => {
+      const error = Cause.squash(cause)
+      if (json) {
+        const message = error instanceof Error ? error.message : String(error)
+        io.stderr(`${JSON.stringify({ state: "error", prompt: message })}\n`)
+      }
+      io.stderr(`${renderFailure(error)}\n`)
+      io.exit(
+        error instanceof SelectorUsageError || error instanceof GtdUsageError
+          ? EXIT_USAGE_ERROR
+          : EXIT_RUNTIME_ERROR,
+      )
+    })
+
+export const runCli = (argv: readonly string[], io: CliIo): Effect.Effect<void, Error> => {
+  const plan = parseArgv(argv)
+
+  if (plan.kind === "output") {
+    return Effect.sync(() => io.stdout(plan.stdout))
+  }
+
+  if (plan.kind === "usage") {
+    return Effect.sync(() => {
+      // The rendered help text (missing-command only) and the `--json`
+      // envelope both move to stderr — stdout stays byte-empty on a usage
+      // error exactly like every other failure surface.
+      if (plan.stdout.length > 0) io.stderr(plan.stdout)
+      if (plan.json) {
+        io.stderr(`${JSON.stringify({ state: "error", prompt: plan.message })}\n`)
+      }
+      io.stderr(`${renderFailure(plan.message)}\n`)
+      io.exit(EXIT_USAGE_ERROR)
+    })
+  }
+
+  const out = bufferedArtifactOut(io)
+  return runCommand(plan.command, plan.json, out).pipe(
+    // `flush()` fires here, on success, BEFORE `io.exit` — the one point
+    // where the whole buffered artifact is known-complete and safe to hand
+    // to stdout (a failure discards the buffer instead — see
+    // `bufferedArtifactOut`).
+    Effect.map(() => {
+      out.flush()
+      io.exit(EXIT_OK)
+    }),
+    Effect.provide(io.layers(plan.verbose)),
+    Effect.sandbox,
+    // `sandbox` moves EVERY failure mode — a typed error, a defect, an
+    // interruption — into this handler's `cause`. An interrupt-only cause
+    // (Ctrl-C on `ui`/`lsp`'s blocking `Effect.never`) is passed
+    // through untouched via `failCause` so `NodeRuntime.runMain` still sees a
+    // real interruption; everything else gets the envelope.
+    Effect.catchAll((cause) =>
+      Cause.isInterruptedOnly(cause)
+        ? Effect.failCause(cause)
+        : report(io, plan.json.kind !== "off")(cause),
+    ),
+  )
+}