@pmelab/gtd 59.0.1 → 60.1.0

package/src/cli/Cli.ts

@@ -1,5 +1,4 @@
-import { NodeContext } from "@effect/platform-node"
-import { Cause, Effect, Either, Layer } from "effect"
+import { Cause, Effect, Layer, Result } from "effect"
 import {
   GtdError,
   GtdUsageError,
@@ -9,6 +8,7 @@ import {
   Host,
   Workspace,
   CommandRunner,
+  NodeServices,
 } from "../platform/index.js"
 import {
   flagSettings,
@@ -20,6 +20,7 @@ import { GTD_VERSION } from "../install/index.js"
 import {
   ConfigDiscovery,
   ConfigService,
+  EngineCore,
   isSettingName,
   SETTING_NAME_RULE,
   StartFlags,
@@ -75,7 +76,7 @@ interface FlagRow {
   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 decode: (raws: readonly string[]) => Result.Result<unknown, string>
   readonly scopeError: string
   readonly valueHint: string
   /** One sentence for a command's help, wrapped when rendered; `helpFor` overrides it for a command the flag means something else on. */
@@ -85,20 +86,63 @@ interface FlagRow {
   readonly conflicts?: readonly string[]
 }
 
-const nonNegativeNumber = (raw: string, flag: string): Either.Either<number, string> => {
+/** `<name>=<value>` occurrences of `flag` → one record, each name a setting name given at most once. */
+const decodeAssignments = (
+  flag: string,
+  raws: readonly string[],
+): Result.Result<Readonly<Record<string, string>>, string> => {
+  const vars: Record<string, string> = {}
+  for (const raw of raws) {
+    const eq = raw.indexOf("=")
+    if (eq <= 0) {
+      return Result.fail(`gtd: ${flag} 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 Result.fail(
+        `gtd: ${flag} ${JSON.stringify(name)} is not a valid setting name — ${SETTING_NAME_RULE}`,
+      )
+    }
+    if (/[\r\n]/.test(value)) return Result.fail(`gtd: ${flag} ${name} must be a single-line value`)
+    if (Object.hasOwn(vars, name))
+      return Result.fail(`gtd: ${flag} ${name} specified more than once`)
+    if (!name.startsWith("flag_")) {
+      vars[name] = value
+      continue
+    }
+    const pinned = flagSettingValue(value)
+    if (pinned === undefined) return Result.fail(`gtd: ${flag} ${name} must be 1, 0, true or false`)
+    vars[name] = pinned
+  }
+  return Result.succeed(vars)
+}
+
+const nonNegativeNumber = (raw: string, flag: string): Result.Result<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 Result.fail(`gtd: ${flag} must be a non-negative number — got "${raw}"`)
   }
-  return Either.right(n)
+  return Result.succeed(n)
 }
 
+/** The commands whose only output is a script: `--json` prints `{ schema, script }`. */
+const SCRIPT_KINDS: ReadonlySet<Command["kind"]> = new Set<Command["kind"]>([
+  "start",
+  "abandon",
+  "restore",
+  "validate",
+  "historyFetch",
+])
+
+const SCRIPT_JSON_HELP = "Print { schema, script }, or with --json=script the script alone"
+
 const JSON_KINDS: ReadonlySet<Command["kind"] | undefined> = new Set<Command["kind"]>([
+  ...SCRIPT_KINDS,
   "next",
   "land",
   "judge",
   "judgeAnswer",
-  "doors",
   "historyList",
   "historyShow",
   "historyMetrics",
@@ -112,14 +156,16 @@ const FLAGS: readonly FlagRow[] = [
     arity: "optional",
     repeatable: false,
     scope: (kind) => JSON_KINDS.has(kind),
-    decode: ([raw]) => Either.right(raw ?? ""),
+    decode: ([raw]) => Result.succeed(raw ?? ""),
     scopeError:
-      "gtd: --json is only valid for `gtd next`/`gtd land`/`gtd judge`/`gtd judge answer`/`gtd doors`/`gtd history list`/`gtd history show`/`gtd history metrics`/`gtd history judges`/`gtd strays` — " +
-      "every other command prints plain text; see `gtd install` for the driver protocol briefing",
+      "gtd: --json is only valid for `gtd next`/`gtd land`, the commands that print a script, and the listings whose help names it (e.g. `gtd strays`) — " +
+      "every other command prints plain text; see `gtd guide` for the driver protocol briefing",
     valueHint: "<path>",
     help: "Print the JSON document, or with --json=<path> one field of it (e.g. --json=kind): a scalar bare, a list one entry per line, nothing for an absent field",
     helpFor: {
       strays: "Print one entry of the array (--json=0), nothing past its end",
+      ...Object.fromEntries([...SCRIPT_KINDS].map((kind) => [kind, SCRIPT_JSON_HELP])),
+      start: `${SCRIPT_JSON_HELP}. Bare, print the list as a JSON array of { kind, name } (a door adds workflow and args)`,
     },
   },
   {
@@ -130,8 +176,8 @@ const FLAGS: readonly FlagRow[] = [
     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 ?? ""}')`)
+        ? Result.succeed(n)
+        : Result.fail(`gtd: --port must be an integer 0–65535 (got '${raw ?? ""}')`)
     },
     scopeError: "gtd: --port is only valid for `gtd ui`",
     valueHint: "<n>",
@@ -144,8 +190,8 @@ const FLAGS: readonly FlagRow[] = [
     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),
+        ? Result.fail("gtd: --host must be a non-empty, single-line value")
+        : Result.succeed(raw),
     scopeError: "gtd: --host is only valid for `gtd ui`",
     valueHint: "<addr>",
     help: "Bind this address directly instead of publishing through tailscale serve",
@@ -155,7 +201,7 @@ const FLAGS: readonly FlagRow[] = [
     arity: 0,
     repeatable: false,
     scope: (kind) => kind === "ui",
-    decode: () => Either.right(true),
+    decode: () => Result.succeed(true),
     scopeError: "gtd: --self-signed is only valid for `gtd ui`",
     valueHint: "",
     help: "Bind directly with a throwaway self-signed certificate instead of the configured ui.cert/ui.key",
@@ -165,7 +211,7 @@ const FLAGS: readonly FlagRow[] = [
     arity: 0,
     repeatable: false,
     scope: (kind) => kind === "ui",
-    decode: () => Either.right(true),
+    decode: () => Result.succeed(true),
     scopeError: "gtd: --dev is only valid for `gtd ui`",
     valueHint: "",
     help: "Serve local development sources instead of the packaged build",
@@ -177,8 +223,8 @@ const FLAGS: readonly FlagRow[] = [
     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 ?? ""}"`),
+        ? Result.succeed(raw)
+        : Result.fail(`gtd: --provider must be one of fixed, jev, llm — got "${raw ?? ""}"`),
     scopeError: "gtd: --provider is only valid for `gtd judge run`",
     valueHint: "<name>",
     help: "The answerer: fixed, jev or llm (default: $GTD_JUDGE_PROVIDER, then ~/.config/gtd/judge.json, then jev when $TYPESAFE_API_KEY is set, else llm)",
@@ -190,8 +236,8 @@ const FLAGS: readonly FlagRow[] = [
     scope: (kind) => kind === "judgeRun",
     decode: ([raw]) =>
       raw === undefined || raw === ""
-        ? Either.left("gtd: --answers must be a non-empty path")
-        : Either.right(raw),
+        ? Result.fail("gtd: --answers must be a non-empty path")
+        : Result.succeed(raw),
     scopeError: "gtd: --answers is only valid for `gtd judge run`",
     valueHint: "<path>",
     help: "With --provider fixed: a JSON verdict file [{ id, answer, p }] (default: $GTD_JUDGE_ANSWERS, inline JSON)",
@@ -213,96 +259,55 @@ const FLAGS: readonly FlagRow[] = [
     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`",
+        ? Result.fail("gtd: --model must be a non-empty, single-line value")
+        : Result.succeed(raw),
+    scopeError:
+      "gtd: --model is only valid for `gtd land` (with --cost: the model to record the cost against) or `gtd judge run` (the model that answers)",
     valueHint: "<name>",
     help: "",
     helpFor: {
-      land: "With --cost: the model that cost was spent on",
+      land: "With --cost: the model that cost was spent on — recorded on the commit, nothing runs on it",
       judgeRun:
         "The claude model the llm answerer uses (default: $GTD_JUDGE_MODEL, then judge.json, then sonnet)",
     },
   },
   {
-    name: "--workflow",
+    name: "--threshold",
     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: "Start a new process on the named workflow",
+    repeatable: true,
+    scope: (kind) => kind === "historyJudges",
+    decode: (raws) => decodeAssignments("--threshold", raws),
+    scopeError: "gtd: --threshold is only valid for `gtd history judges`",
+    valueHint: "<name>=<value>",
+    help: "Re-decide every past verdict under this threshold: judgeIdenticalMinP or qualityTriageMinP (repeatable)",
   },
   {
     name: "--var",
     arity: 1,
     repeatable: true,
-    scope: (kind) => kind === "start" || kind === "historyJudges",
-    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)
-        if (name.startsWith("flag_")) {
-          const pinned = flagSettingValue(value)
-          if (pinned === undefined) {
-            return Either.left(`gtd: --var ${name} must be 1, 0, true or false`)
-          }
-          vars[name] = pinned
-          continue
-        }
-        vars[name] = value
-      }
-      return Either.right(vars)
-    },
-    scopeError: "gtd: --var requires --workflow (or `gtd history judges`)",
+    scope: (kind) => kind === "start",
+    decode: (raws) => decodeAssignments("--var", raws),
+    scopeError: "gtd: --var is only valid for `gtd start <name>`",
     valueHint: "<name>=<value>",
-    help: "",
-    helpFor: {
-      start: "Pin one of the workflow's declared settings for the new process (repeatable)",
-      historyJudges:
-        "Re-decide every past verdict under this threshold: judgeIdenticalMinP or qualityTriageMinP (repeatable)",
-    },
+    help: "Pin one of the workflow's declared settings for the new process (repeatable); through a door, on top of the settings its args set",
   },
   {
     name: "--jsonl",
     arity: 0,
     repeatable: false,
     scope: (kind) => kind === "historyJudges",
-    decode: () => Either.right(true),
+    decode: () => Result.succeed(true),
     scopeError: "gtd: --jsonl is only valid for `gtd history judges`",
     valueHint: "",
     help: "Print one JSON line per verdict instead of the report",
-    conflicts: ["--json", "--var"],
+    conflicts: ["--json", "--threshold"],
   },
   {
     name: "--open-questions",
     arity: 0,
     repeatable: false,
     scope: (kind) => kind === "check",
-    decode: () => Either.right(true),
+    decode: () => Result.succeed(true),
     scopeError: "gtd: --open-questions is only valid for `gtd check`",
     valueHint: "",
     help: "Instead of <mode>'s findings, list the unanswered questions in <file>; exits 1 when any remain",
@@ -312,7 +317,7 @@ const FLAGS: readonly FlagRow[] = [
     arity: 0,
     repeatable: false,
     scope: (kind) => kind === "check",
-    decode: () => Either.right(true),
+    decode: () => Result.succeed(true),
     scopeError: "gtd: --open-threads is only valid for `gtd check`",
     valueHint: "",
     help: "Instead of <mode>'s findings, list the open threads in <file>; exits 1 when any are open. Alone, lists the open code-comment threads in the files the current process changed",
@@ -322,7 +327,7 @@ const FLAGS: readonly FlagRow[] = [
     arity: 0,
     repeatable: false,
     scope: () => true,
-    decode: () => Either.right(true),
+    decode: () => Result.succeed(true),
     scopeError: "gtd: --verbose is valid for every command — this error is unreachable",
     valueHint: "",
     help: "Narrate on stderr what gtd resolved and where its config came from",
@@ -356,6 +361,8 @@ type Arity =
   | { readonly names: readonly [string, string] }
   // One required leading positional, then any number the command itself judges.
   | { readonly name: string; readonly variadic: string }
+  // The same, the leading one optional too.
+  | { readonly name: string; readonly variadic: string; readonly bare: true }
   // At most one trailing positional.
   | { readonly name: string; readonly optional: true }
   // Any number of positionals, none included.
@@ -407,25 +414,21 @@ gtd writes nothing itself. Plain output names the commit it would make; --json=s
     arity: "none",
     group: "Core loop",
     summary: "Print the script that checks the steering file",
-    details: `Print the script that formats, then validates, the current step's steering file with its mode's commands. gtd runs nothing: the script's exit code is the verdict, and on a failure it prints a ready-to-send fix prompt. Prints "nothing to validate" when the step declares no file to check.`,
+    details: `Print the script that formats, then validates, the current step's steering file with its mode's commands. gtd runs nothing: the script's exit code is the verdict, and on a failure it prints a ready-to-send fix prompt. Prints "nothing to validate" when the step declares no file to check; --json=script then prints an empty script.`,
   },
   {
-    token: "door",
-    kind: "door",
-    arity: { name: "name", variadic: "args" },
+    token: "start",
+    kind: "start",
+    arity: { name: "name", variadic: "args", bare: true },
     group: "Start and stop",
-    summary: "Start a process through a named shortcut",
-    details: `Start a process through a door: a named shortcut to a workflow that maps its positional args to the workflow's settings. It prints the same start script \`gtd --workflow\` does. Each workflow the config exports brings its own doors, plus the config's \`doors\` export.
+    summary: "Start a workflow or door; bare, list them",
+    details: `Start a new process: print the script that makes its first commit, which also commits whatever the working tree holds.
 
-With no <name>, an unknown one, or the wrong number of args, it lists the doors and exits 2.`,
-  },
-  {
-    token: "doors",
-    kind: "doors",
-    arity: "none",
-    group: "Start and stop",
-    summary: "List the doors",
-    details: `List every door, sorted: one \`name [args] → workflow\` line each. --json prints a JSON array of { name, workflow, args: [{ name, optional }] }. Writes nothing.`,
+<name> is a door — a named shortcut whose positional args set the workflow's settings — or else a workflow the config exports, which takes no args. A door shadows a workflow of the same name. --var pins a setting either way.
+
+  s=$(gtd start <name> --json=script) && sh -c "$s"
+
+With no <name>, list every workflow and door it can start. An unknown <name>, the wrong number of args, or a --var the workflow does not declare is a usage error (exit 2); a process already underway is a refusal (exit 1).`,
   },
   {
     token: "abandon",
@@ -435,7 +438,7 @@ With no <name>, an unknown one, or the wrong number of args, it lists the doors
     summary: "Stop the process, keeping its changes",
     details: `Stop the process underway without finishing it. The printed script moves HEAD back to the commit the process started from and keeps everything it produced as uncommitted changes; \`gtd restore\` undoes it. With no process underway the script does nothing.
 
-  s=$(gtd abandon) && sh -c "$s"`,
+  s=$(gtd abandon --json=script) && sh -c "$s"`,
   },
   {
     token: "restore",
@@ -513,7 +516,7 @@ Prints a sorted JSON array ([] when clean) and a summary on stderr; --verbose ad
     summary: "Print a script that fetches finished processes",
     details: `Print a script that fetches every finished process kept on <remote> (default: origin) and reports how many arrived. gtd runs no git itself:
 
-  s=$(gtd history fetch) && sh -c "$s"`,
+  s=$(gtd history fetch --json=script) && sh -c "$s"`,
   },
   {
     token: "ui",
@@ -524,13 +527,21 @@ Prints a sorted JSON array ([] when clean) and a summary on stderr; --verbose ad
     details: `Serve gtd's web and phone client for this worktree. By default it publishes through \`tailscale serve\`, reachable from anywhere on the tailnet, on the first of ports 8443, 10000 and 443 that works; when none does it serves HTTPS locally instead of refusing.`,
   },
   {
-    token: "install",
-    kind: "install",
+    token: "guide",
+    kind: "guide",
     arity: "none",
     group: "Driver plumbing",
     summary: "Print a briefing for writing a driver",
     details: `Print a self-contained briefing that teaches an agent or a person to build a gtd driver in any shell or runtime, and where to get a workflow — gtd ships none. Writes nothing.`,
   },
+  {
+    token: "bundle",
+    kind: "bundle",
+    arity: "none",
+    group: "Driver plumbing",
+    summary: "Print the pin of the current workflow",
+    details: `Print a pin to stdout: gtd's engine and the current workflow — gtd.config.ts, every module it imports and every npm package they use — as one gzipped ES module, after a plain-text header line \`gtdpin <format> gtd <version>\`. Git diffs it as binary. Refuses a workflow gtd would refuse, and a package that loads a native addon (.node), naming it. Writes nothing.`,
+  },
   {
     token: "judge",
     kind: "judge",
@@ -555,7 +566,7 @@ Prints a sorted JSON array ([] when clean) and a summary on stderr; --verbose ad
     summary: "Answer a judgment with a model",
     details: `Answer a judgment: read the \`gtd judge --json\` document from stdin and print the verdict [{ id, answer, p }] \`gtd judge answer\` reads. Needs no repository.
 
-The fixed answerer reads --answers and leaves out the questions it does not cover; jev asks TypeSafe ($TYPESAFE_API_KEY); llm asks the \`claude\` CLI on PATH. jev and llm exit 1, printing nothing, when they cannot answer every question.`,
+The fixed answerer reads --answers and leaves out the questions it does not cover; jev asks TypeSafe ($TYPESAFE_API_KEY); llm asks the \`claude\` CLI on PATH. jev and llm exit 1, printing nothing, when they cannot answer every question. A stdin that is not a judgment document is a usage error (exit 2).`,
   },
   {
     token: "check",
@@ -563,7 +574,7 @@ The fixed answerer reads --answers and leaves out the questions it does not cove
     arity: { names: ["mode", "file"] },
     group: "Driver plumbing",
     summary: "Check a steering file's format",
-    details: `Run the steering format <mode> (qa, review or findings) over <file> and print each finding on a line of its own; exits 1 when there are any. Reads no workflow and runs from any directory — emitted validation scripts call it.`,
+    details: `Run the steering format <mode> (qa, review or findings) over <file> and print each finding on a line of its own; exits 1 when there are any, or when <file> does not exist. An unknown <mode> is a usage error (exit 2). Reads no workflow and runs from any directory — emitted validation scripts call it.`,
   },
   {
     token: "uncheck",
@@ -602,13 +613,14 @@ const synopsis = (row: CommandRow): string => {
   const { token, arity } = row
   if (arity === "none") return token
   if ("names" in arity) return `${token} <${arity.names[0]}> <${arity.names[1]}>`
+  if ("bare" in arity) return `${token} [${arity.name}] [${arity.variadic}...]`
   if ("variadic" in arity) return `${token} <${arity.name}> [${arity.variadic}...]`
   if ("optional" in arity) return `${token} [${arity.name}]`
   if ("many" in arity) return `${token} [${arity.name}...]`
   return `${token} <${arity.name}>`
 }
 
-const SPACE_FORM_FLAGS = new Set(["--workflow", "--var"])
+const SPACE_FORM_FLAGS = new Set(["--var", "--threshold"])
 
 const flagHeader = (row: FlagRow): string => {
   if (row.valueHint === "") return row.name
@@ -618,15 +630,11 @@ const flagHeader = (row: FlagRow): string => {
     : `${row.name}=${row.valueHint}`
 }
 
-const START_ROW = {
-  term: "--workflow <name>",
-  summary: "Start a process on a workflow; --var <name>=<value> pins one of its settings",
-}
-
 const GLOBAL_OPTIONS: readonly (readonly [string, string])[] = [
   ["-v, --verbose", "Narrate on stderr what gtd resolved"],
   ["-h, --help", "Print help; gtd <command> --help for one command"],
   ["-V, --version", "Print the version"],
+  ["--", "End the options: every word after it is an argument"],
 ]
 
 const EXTRA_TOPICS: readonly (readonly [string, string, string])[] = [
@@ -638,7 +646,8 @@ const EXTRA_TOPICS: readonly (readonly [string, string, string])[] = [
   ["version", "Print the version", "Print gtd's version."],
 ]
 
-const EXAMPLES = `  $ gtd --workflow <name>                       start a process
+const EXAMPLES = `  $ gtd start                                   list what can start
+  $ gtd start <name>                            start a process
   $ gtd next                                    see what happens next
   $ s=$(gtd land --json=script) && sh -c "$s"   land the turn
   $ gtd help land                               one command's details`
@@ -652,13 +661,11 @@ export const renderHelp = (): string => {
     const rows = COMMAND_ROWS.filter((r) => r.group === group).flatMap((r) =>
       definition(synopsis(r), r.summary, TOP_COLUMN),
     )
-    const start =
-      group === "Start and stop" ? definition(START_ROW.term, START_ROW.summary, TOP_COLUMN) : []
     const extra =
       group === "Driver plumbing"
         ? EXTRA_TOPICS.flatMap(([term, summary]) => definition(term, summary, TOP_COLUMN))
         : []
-    return `${group}:\n${lines([...start, ...rows, ...extra])}`
+    return `${group}:\n${lines([...rows, ...extra])}`
   })
   return (
     "Usage: gtd <command> [options]\n\n" +
@@ -674,7 +681,7 @@ export const renderHelp = (): string => {
     `\nExamples:\n${EXAMPLES}\n\n` +
     lines(
       wrap(
-        "Run `gtd help <command>` for a command's details and options, and `gtd install` to learn how to drive gtd.",
+        "Run `gtd help <command>` for a command's details and options, and `gtd guide` to learn how to drive gtd.",
       ),
     )
   )
@@ -683,7 +690,7 @@ export const renderHelp = (): string => {
 /** Shown on stderr above a bare `gtd`'s usage error — the overview stays one `gtd help` away. */
 const SHORT_USAGE = `Usage: gtd <command> [options]
 
-  gtd --workflow <name>   start a process
+  gtd start <name>        start a process
   gtd next                print what should happen next
   gtd land                record what the tree now shows
 
@@ -764,11 +771,13 @@ const tokenize = (tail: readonly string[]): TokenizeError | TokenizeOk => {
   const present = new Set<string>()
   let jsonSeen = false
   let afterBareJson: string | undefined
+  const end = tail.indexOf("--")
 
   for (let i = 0; i < tail.length; i++) {
     const original = tail[i]!
+    if (i === end) continue
     const tok = SINGLE_DASH_ALIASES.get(original) ?? original
-    if (!tok.startsWith("-") || tok === "-") {
+    if ((end !== -1 && i > end) || !tok.startsWith("-") || tok === "-") {
       if (tail[i - 1] === "--json") afterBareJson ??= original
       positionals.push(original)
       continue
@@ -894,7 +903,7 @@ const tooMany = (
 const arityError = (cmd: string, rest: readonly string[], arity: Arity): string | undefined => {
   if (arity === "none") return tooMany(cmd, rest, "none", 0)
   if ("names" in arity) return pairArityError(cmd, rest, arity.names)
-  if ("many" in arity) return undefined
+  if ("many" in arity || "bare" in arity) return undefined
   if ("optional" in arity) return tooMany(cmd, rest, `at most one ${arity.name}`, 1)
   if (rest.length === 0) return `gtd ${cmd}: missing ${arity.name} argument`
   return "variadic" in arity ? undefined : tooMany(cmd, rest, `one ${arity.name}`, 1)
@@ -916,7 +925,7 @@ const pairArityError = (
 /** 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> => {
+): Result.Result<Readonly<Record<string, unknown>>, string> => {
   const bag: Record<string, unknown> = {}
   for (const row of FLAGS) {
     const raws = byFlag.get(row.name)
@@ -925,10 +934,31 @@ const decodeFlags = (
     // 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
+    if (Result.isFailure(decoded)) return Result.fail(decoded.failure)
+    bag[row.name] = decoded.success
   }
-  return Either.right(bag)
+  return Result.succeed(bag)
+}
+
+/** `gtd history judges`' thresholds: each a known judge threshold with a numeric value. */
+const judgeThresholds = (
+  thresholds: Readonly<Record<string, string>>,
+): Result.Result<Readonly<Record<string, string>>, string> => {
+  const unknown = Object.keys(thresholds).find((name) => !Object.hasOwn(THRESHOLDS, name))
+  if (unknown !== undefined) {
+    return Result.fail(
+      `gtd history judges: --threshold ${unknown} is no judge threshold — use ${Object.keys(THRESHOLDS).join(" or ")}`,
+    )
+  }
+  const nan = Object.entries(thresholds).find(
+    ([, value]) => value.trim() === "" || !Number.isFinite(Number(value)),
+  )
+  if (nan !== undefined) {
+    return Result.fail(
+      `gtd history judges: --threshold ${nan[0]} must be a number — got "${nan[1]}"`,
+    )
+  }
+  return Result.succeed(thresholds)
 }
 
 /** 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. */
@@ -943,9 +973,19 @@ const buildLandCommand = (bag: {
 
 const HELP_FLAGS = new Set(["--help", "-h"])
 
-/** `--help`/`-h` anywhere: the named command's own help, else the overview — never a usage error, so a typo'd command still gets help. */
+/** The options part of argv: everything before a `--`, which ends the options. */
+const optionsOf = (argv: readonly string[]): readonly string[] => {
+  const end = argv.indexOf("--", 2)
+  return end === -1 ? argv : argv.slice(0, end)
+}
+
+/** `--help`/`-h` anywhere before `--`: the named command's own help, else the overview — never a usage error, so a typo'd command still gets help. */
 const helpPlan = (argv: readonly string[]): CliPlan => {
-  const tokenized = tokenize(argv.slice(2).filter((tok) => !HELP_FLAGS.has(tok)))
+  const tokenized = tokenize(
+    optionsOf(argv)
+      .slice(2)
+      .filter((tok) => !HELP_FLAGS.has(tok)),
+  )
   const topic = tokenized.kind === "ok" ? tokenized.positionals : []
   return { kind: "output", stdout: renderTopicHelp(topic) ?? renderHelp() }
 }
@@ -963,8 +1003,9 @@ const helpCommandPlan = (topic: readonly string[], json: boolean): CliPlan => {
 
 // fallow-ignore-next-line complexity
 export const parseArgv = (argv: readonly string[]): CliPlan => {
-  if (argv.some((tok) => HELP_FLAGS.has(tok))) return helpPlan(argv)
-  if (argv.includes("--version") || argv.includes("-V")) {
+  const options = optionsOf(argv)
+  if (options.some((tok) => HELP_FLAGS.has(tok))) return helpPlan(argv)
+  if (options.includes("--version") || options.includes("-V")) {
     return { kind: "output", stdout: `${GTD_VERSION}\n` }
   }
 
@@ -973,8 +1014,6 @@ export const parseArgv = (argv: readonly string[]): CliPlan => {
   const { positionals, byFlag, present, jsonSeen, afterBareJson } = 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 helpCommandPlan(positionals.slice(1), jsonSeen)
@@ -1012,31 +1051,17 @@ export const parseArgv = (argv: readonly string[]): CliPlan => {
   // `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) {
+
+  if (row === undefined || first === undefined) {
     // 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).
+    // used here (e.g. a bare `gtd --var x=1`) is a more specific error than
+    // "missing command"/"unknown command", so it takes priority.
     const violation = scopeViolation(undefined, present)
     if (violation !== undefined) return usagePlan(violation, jsonSeen)
     if (first === undefined) {
       return usagePlan(
-        "gtd: missing command — run `gtd help` for every command, or `gtd install` to learn how to drive gtd",
+        "gtd: missing command — run `gtd help` for every command, or `gtd guide` to learn how to drive gtd",
         jsonSeen,
         SHORT_USAGE,
       )
@@ -1047,37 +1072,21 @@ export const parseArgv = (argv: readonly string[]): CliPlan => {
     )
   }
 
-  // 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 || isHistory ? 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.
-    // A bare `gtd door` lists the doors — which only the loaded config knows.
-    const bare =
-      (kind === "check" && restPositionals.length === 0 && present.has("--open-threads")) ||
-      (kind === "door" && restPositionals.length === 0)
-    const arityMsg = bare
-      ? undefined
-      : arityError(isHistory ? row!.token : first!, restPositionals, row!.arity)
-    if (arityMsg !== undefined) {
-      const hint =
-        afterBareJson !== undefined && restPositionals.includes(afterBareJson)
-          ? ` — to print one field, write --json=${afterBareJson}`
-          : ""
-      return usagePlan(arityMsg + hint, jsonSeen)
-    }
+  const kind: Command["kind"] = judgeAnswer ? "judgeAnswer" : judgeRun ? "judgeRun" : row.kind
+
+  // `judgeAnswer` consumes TWO leading positionals ("judge" and "answer"), everything else one.
+  const restPositionals = positionals.slice(judgeAnswer || judgeRun || isHistory ? 2 : 1)
+
+  const bare = kind === "check" && restPositionals.length === 0 && present.has("--open-threads")
+  const arityMsg = bare
+    ? undefined
+    : arityError(isHistory ? row.token : first, restPositionals, row.arity)
+  if (arityMsg !== undefined) {
+    const hint =
+      afterBareJson !== undefined && restPositionals.includes(afterBareJson)
+        ? ` — to print one field, write --json=${afterBareJson}`
+        : ""
+    return usagePlan(arityMsg + hint, jsonSeen)
   }
 
   const violation = scopeViolation(kind, present)
@@ -1087,13 +1096,14 @@ export const parseArgv = (argv: readonly string[]): CliPlan => {
   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 {
+  if (Result.isFailure(decoded)) return usagePlan(decoded.failure, jsonSeen)
+  const bag = decoded.success as {
     readonly "--json"?: string
     readonly "--port"?: number
     readonly "--cost"?: number
     readonly "--model"?: string
     readonly "--var"?: Readonly<Record<string, string>>
+    readonly "--threshold"?: Readonly<Record<string, string>>
     readonly "--open-questions"?: boolean
     readonly "--open-threads"?: boolean
     readonly "--host"?: string
@@ -1125,28 +1135,20 @@ export const parseArgv = (argv: readonly string[]): CliPlan => {
   }
 
   if (kind === "start") {
-    const label = `gtd --workflow ${workflowRaw}`
+    const [name, ...args] = restPositionals
+    if (name === undefined && bag["--var"] !== undefined) {
+      return usagePlan(
+        "gtd start: --var needs a <name> — run `gtd start` to list the workflows and doors",
+        jsonSeen,
+      )
+    }
     return {
       kind: "command",
       command: {
         kind: "start",
-        actor: "human",
-        workflow: workflowRaw!,
+        ...(name !== undefined ? { name } : {}),
+        args,
         vars: bag["--var"] ?? {},
-        label,
-      },
-      json,
-      verbose,
-    }
-  }
-
-  if (kind === "door") {
-    return {
-      kind: "command",
-      command: {
-        kind: "door",
-        ...(restPositionals[0] !== undefined ? { name: restPositionals[0] } : {}),
-        args: restPositionals.slice(1),
       },
       json,
       verbose,
@@ -1237,23 +1239,9 @@ export const parseArgv = (argv: readonly string[]): CliPlan => {
   }
 
   if (kind === "historyJudges") {
-    const vars = bag["--var"] ?? {}
-    const unknown = Object.keys(vars).find((name) => !Object.hasOwn(THRESHOLDS, name))
-    if (unknown !== undefined) {
-      return usagePlan(
-        `gtd history judges: --var ${unknown} is no judge threshold — use ${Object.keys(THRESHOLDS).join(" or ")}`,
-        jsonSeen,
-      )
-    }
-    const nan = Object.entries(vars).find(
-      ([, value]) => value.trim() === "" || !Number.isFinite(Number(value)),
-    )
-    if (nan !== undefined) {
-      return usagePlan(
-        `gtd history judges: --var ${nan[0]} must be a number — got "${nan[1]}"`,
-        jsonSeen,
-      )
-    }
+    const thresholds = judgeThresholds(bag["--threshold"] ?? {})
+    if (Result.isFailure(thresholds)) return usagePlan(thresholds.failure, jsonSeen)
+    const vars = thresholds.success
     return {
       kind: "command",
       command: {
@@ -1315,8 +1303,8 @@ export const parseArgv = (argv: readonly string[]): CliPlan => {
       | "restore"
       | "next"
       | "validate"
-      | "install"
-      | "doors"
+      | "guide"
+      | "bundle"
       | "base"
       | "judge"
       | "judgeAnswer"
@@ -1330,7 +1318,7 @@ export const parseArgv = (argv: readonly string[]): CliPlan => {
 // ---------------------------------------------------------------------------
 
 export interface CliIo {
-  readonly stdout: (chunk: string) => void
+  readonly stdout: (chunk: string | Uint8Array) => void
   readonly stderr: (chunk: string) => void
   readonly exit: (code: number) => void
   /**
@@ -1355,7 +1343,7 @@ const writeStderr = (chunk: string): void => {
 export type LiveToolCommands = Layer.Layer<
   ToolCommands,
   never,
-  Exclude<CommandRequirements, ToolCommands> | NodeContext.NodeContext
+  Exclude<CommandRequirements, ToolCommands> | NodeServices.NodeServices
 >
 
 export const nodeCliIo = (tools: LiveToolCommands): CliIo => ({
@@ -1380,20 +1368,21 @@ export const nodeCliIo = (tools: LiveToolCommands): CliIo => ({
   // "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
+    // Host, and GitService needs NodeServices' ChildProcessSpawner. Each
     // `provideMerge` satisfies the layers above it AND stays in the output.
     tools.pipe(
       Layer.provideMerge(
         Layer.mergeAll(
           ConfigService.Live,
           ConfigDiscovery.Live,
+          EngineCore.Live,
           Workspace.Live,
           Narrator.layer(writeStderr, verbose),
           CommandRunner.Live,
         ).pipe(
           Layer.provideMerge(GitService.Live),
           Layer.provideMerge(Host.Live),
-          Layer.provideMerge(NodeContext.layer),
+          Layer.provideMerge(NodeServices.layer),
         ),
       ),
     ),
@@ -1408,14 +1397,20 @@ export const nodeCliIo = (tools: LiveToolCommands): CliIo => ({
 export const normalizeTrailingNewline = (artifact: string): string =>
   artifact.length === 0 ? artifact : `${artifact.replace(/\n+$/, "")}\n`
 
+// Bytes are a binary artifact, written as they are.
 const bufferedArtifactOut = (io: CliIo): ArtifactOut => {
-  let buffer = ""
+  let buffer: string | Uint8Array = ""
   return {
     write: (chunk) => {
-      buffer += chunk
+      buffer =
+        typeof buffer === "string" && typeof chunk === "string"
+          ? buffer + chunk
+          : Buffer.concat([Buffer.from(buffer), Buffer.from(chunk)])
     },
     flush: () => {
-      if (buffer.length > 0) io.stdout(normalizeTrailingNewline(buffer))
+      if (buffer.length > 0) {
+        io.stdout(typeof buffer === "string" ? normalizeTrailingNewline(buffer) : buffer)
+      }
       buffer = ""
     },
   }
@@ -1501,8 +1496,8 @@ export const runCli = (argv: readonly string[], io: CliIo): Effect.Effect<void,
     // (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.catch((cause) =>
+      Cause.hasInterruptsOnly(cause)
         ? Effect.failCause(cause)
         : report(io, plan.json.kind !== "off")(cause),
     ),