moshcode 0.24.0

package/prd/0003-cross-engine-mcp-and-skill-installation.md

@@ -0,0 +1,165 @@
+---
+openprd: "0.2"
+id: "0003"
+title: Install MCP servers and skills across every engine at once
+status: Accepted
+authors:
+  - anthony@chovy.com
+created: 2026-07-13
+updated: 2026-07-13
+repo: https://github.com/moshcoder/moshcode
+discussion:
+implementation: src/mcp.mjs, src/skills.mjs, src/integrations.mjs
+tags:
+  - cli
+  - mcp
+  - skills
+  - integrations
+  - orchestration
+supersedes:
+superseded-by:
+---
+
+## Problem
+
+Every coding engine MoshCode conducts (Claude, Gemini, Codex, OpenCode, Aider)
+maintains its own registry of MCP (Model Context Protocol) servers, each with a
+different config location, format, and `mcp add` flag surface. A user who wants
+the same MCP server available in all of their agents has to run four different
+commands and remember four different flag dialects. The same fragmentation is
+starting to appear for Agent Skills. MoshCode already conducts these CLIs' native
+command lines (see [[0001-wrap-ugig-and-coinpay-clis]]); it is the natural place
+to register a server or skill *once* and fan it out to every engine that can use
+it.
+
+## Goals
+
+- Register an MCP server across every installed MCP-capable engine with one
+  command, defaulting to global (user) scope.
+- Translate a single canonical server definition into each engine's native
+  `mcp add` invocation, rather than hand-writing four config formats.
+- Report per engine what happened: added, skipped (can't express it), failed, or
+  not installed — and flag servers that still need per-engine authentication.
+- Offer the equivalent one-shot install for Agent Skills to the engines that have
+  a skills primitive.
+- Never silently drop an engine: an engine that cannot express a requested server
+  MUST be reported, not omitted.
+
+## Non-Goals
+
+- Implementing MCP or skills for engines that lack the primitive (Aider has
+  neither; Codex/OpenCode have no skills concept).
+- Performing per-engine OAuth/login flows on the user's behalf (MoshCode registers
+  the server; the user authenticates in each engine).
+- Editing engine config files directly — MoshCode drives each engine's own
+  `mcp add` / `skills install` so the engine owns its config format.
+- Managing MCP server processes/runtime, health, or tool routing.
+- Reconciling or de-duplicating servers an engine already has.
+
+## Users
+
+- Developers who run more than one coding agent and want the same MCP tools
+  (Sentry, GitHub, a company internal server) available in all of them.
+- Teams standardizing a set of skills/servers across engines.
+- Scripts that need the same fan-out outside the MoshCode TUI.
+
+## Requirements
+
+- R1 [P0] A new command MUST register an MCP server across every installed
+  MCP-capable engine: `/mcp install <commandOrUrl>` and
+  `/mcp add <name> <commandOrUrl> [args…]` in the TUI, and `moshcode mcp …`
+  outside it.
+- R2 [P0] The MCP-capable engine set MUST be Claude, Gemini, Codex, and OpenCode.
+  Aider MUST be treated as having no MCP support.
+- R3 [P0] A canonical server definition — name, target (URL or stdio command +
+  args), transport, env vars, and headers — MUST be translated per engine into
+  its native `mcp add` argv:
+  - Claude: `claude mcp add -s user [-t <transport>] [-e K=V…] [-H "K: V"…] <name> <commandOrUrl> [args…]`
+  - Gemini: `gemini mcp add -s user [-t <transport>] [-e K=V…] [-H "K: V"…] <name> <commandOrUrl> [args…]`
+  - Codex: `codex mcp add <name> (--url <url> | -- <command> [args…]) [--env K=V…]`
+  - OpenCode: `opencode mcp add <name> --url <url> [--env K=V…] [--header K=V…]`
+- R4 [P0] Registration MUST default to global/user scope on every engine
+  (`-s user` where the engine offers it; the engine's user-level config
+  otherwise).
+- R5 [P0] `/mcp install <url>` MUST accept a bare remote URL, derive a sane
+  default server name from its host, and default the transport to `http`.
+  An explicit `--name` MUST override the derived name.
+- R6 [P0] When an engine cannot express the requested server (e.g. OpenCode with
+  a stdio command, or Codex with literal headers), MoshCode MUST skip that engine
+  with a stated reason and still register the others.
+- R7 [P0] Header syntax MUST be normalized per engine: Claude/Gemini `"Key: Value"`,
+  OpenCode `Key=Value`. Codex, which supports only a bearer-token env var, MUST be
+  skipped-with-reason when literal headers are supplied.
+- R8 [P1] A `/skill install <git-url|path>` command MUST fan a skill out to every
+  installed engine that has a skills primitive: Gemini via
+  `gemini skills install <source> --scope user`, and Claude by cloning the source
+  into `~/.claude/skills/<name>`. Engines without a skills primitive MUST be
+  reported as skipped.
+- R9 [P1] Every fan-out MUST print a per-engine summary (added / skipped+reason /
+  failed / not-installed) and MUST call out any server that still requires
+  authentication in a given engine.
+- R10 [P1] A removal path (`/mcp remove <name>`, `moshcode mcp remove <name>`)
+  MUST fan the corresponding native `mcp remove` out to the same engines.
+- R11 [P1] `/mcp` and `/skill` with no arguments MUST list the target engines and
+  their MCP/skills support + install status.
+- R12 [P1] The registration plan (engine → argv or skip-reason) MUST be a pure,
+  unit-tested function, mirroring the existing upgrade-plan tests, so adapters are
+  verified without spawning real engines.
+
+## UX Notes
+
+```sh
+# Remote HTTP server, global, everywhere that supports MCP:
+moshcode mcp install https://mcp.sentry.dev/mcp
+#   ✓ claude    added (-s user -t http)
+#   ✓ gemini    added
+#   ✓ codex     added (--url)
+#   ✓ opencode  added (--url)
+#   · aider      skipped — no MCP support
+
+# Explicit name + stdio command server:
+moshcode mcp add my-tools -- npx -y my-mcp-server
+#   ✓ claude    added
+#   ✓ gemini    added
+#   ✓ codex     added
+#   · opencode  skipped — CLI adds only remote (--url) servers non-interactively
+
+# A skill, to the engines that have skills:
+moshcode skill install https://github.com/acme/some-skill
+#   ✓ claude    cloned into ~/.claude/skills/some-skill
+#   ✓ gemini    installed (--scope user)
+#   · codex/opencode/aider  skipped — no skills primitive
+```
+
+TUI equivalents are `/mcp install …`, `/mcp add …`, `/mcp remove …`, and
+`/skill install …`. Bare `/mcp` and `/skill` print the support matrix.
+
+The per-engine translation is intentionally not uniform: Claude and Gemini share
+a `mcp add <name> <commandOrUrl>` shape with `-t`/`-H`; Codex distinguishes
+remote from stdio with `--url` vs `-- command` and only carries a bearer-token env
+var; OpenCode registers remote servers by `--url` and uses `Key=Value` headers.
+
+## Success Metrics
+
+- One `moshcode mcp install <url>` registers the server, at user scope, in every
+  installed MCP-capable engine, with a per-engine result line.
+- No engine is silently omitted: unsupported combinations are reported with a
+  reason.
+- The plan function returns the correct native argv (or skip reason) for each
+  engine and combination, verified by tests without spawning engines.
+- The full MoshCode test suite passes.
+
+## Risks & Open Questions
+
+- Engine `mcp add` flags can change between releases; their own `--help` remains
+  authoritative and the adapters need maintenance when a CLI renames a flag.
+- Secrets (env values, `Authorization` headers, bearer env-var names) flow through
+  MoshCode into each engine's config; MoshCode MUST NOT log their values.
+- Claude skill install by `git clone` assumes the source repo is a skill (a
+  `SKILL.md` at the root or a known sub-path); non-skill repos are out of scope
+  for v1.
+- Should MoshCode detect and skip servers an engine already has, or let the native
+  `mcp add` error surface? v1 surfaces the native result; de-dup is deferred.
+- OAuth-gated servers register but remain unauthenticated until the user runs the
+  engine's own auth (`opencode mcp auth`, `codex mcp login`); MoshCode only points
+  this out.

package/prd/0004-moshscript-run-programmable-moshcode.md

@@ -0,0 +1,344 @@
+---
+openprd: "0.2"
+id: "0004"
+title: moshscript — a scriptable /run for driving all of moshcode programmatically
+status: Accepted
+authors:
+  - anthony@chovy.com
+created: 2026-07-13
+updated: 2026-07-13
+repo: https://github.com/moshcoder/moshcode
+discussion:
+implementation: src/runtime.mjs, src/registry.mjs, src/commands.mjs, src/cli.mjs, src/tui.mjs, bin/moshcode.mjs
+tags:
+  - moshscript
+  - cli
+  - scripting
+  - automation
+  - dsl
+supersedes:
+superseded-by:
+---
+
+## Problem
+
+moshcode already ships a `/run <file.mosh>` command and a tiny moshscript
+runner (`src/interpreter.mjs` + `src/commands.mjs`), but the language is a toy.
+Its grammar is one construct — `while (alive) { … }` — and its vocabulary is
+seven cosmetic builtins (`code()`, `mosh()`, `notify()`, `repeat()`, `say()`,
+`sleep()`, `stop()`). None of them actually *do* anything moshcode does: a
+script cannot launch an engine, install a tool, publish a PRD, or fan an MCP
+server across engines. Everything moshcode is good at — conducting Claude,
+Codex, Gemini, OpenCode and Aider, and the ugig/coinpay/c0mpute workflow CLIs
+(see [[0001-wrap-ugig-and-coinpay-clis]], [[0002-separate-agent-and-raw-engine-launches]],
+[[0003-cross-engine-mcp-and-skill-installation]]) — is only reachable by a human
+typing at the mosh pit prompt.
+
+The pitch, in the user's words: *"very simple scripting language (although
+secretly all js is legal), but very basic commands like `code(); mosh();
+notify(); repeat();` — we can basically do everything moshcode cli supports but
+programmatically."* Two things have to become true that aren't today:
+
+1. **moshscript must be able to drive moshcode's real capabilities**, not just
+   print flavor text.
+2. **moshscript must accept real JavaScript** so that "very simple" scripts keep
+   working while power users can reach for loops, conditionals, variables, and
+   expressions without hitting a wall in the hand-rolled tokenizer
+   (`interpreter.mjs` throws on any character outside `(){};,` + string/number/
+   ident).
+
+## Goals
+
+- Evolve `/run <file.mosh>` from a cosmetic loop into a programmable interface to
+  the whole moshcode CLI: any verb reachable from the pit or `bin/moshcode.mjs`
+  is callable as a moshscript function.
+- Keep the "no bugs, only features" starter script — `while (alive) { code();
+  mosh(); notify(); repeat(); }` — running unchanged. The simple surface is the
+  brand; it must not regress.
+- Make "secretly all JS is legal" real: a `.mosh` file is executed as JavaScript
+  with the moshscript command vocabulary injected as globals, so `if`, `for`,
+  `const`, template strings, `await`, and arithmetic all Just Work.
+- Give scripts programmatic access to engines (`agents`, `start`, `install`),
+  workflow tools (`ugig`, `coinpay`, `c0mpute`), cross-engine fan-out (`mcp`,
+  `skill`), publishing (`prd`), and system verbs (`upgrade`, `shell`, `pwd`).
+- Preserve `--dry-run` as a first-class, honored mode: a dry run narrates every
+  action (spawn argv, network target) without executing it.
+- Keep it lean: zero new runtime dependencies, still Node 18+ ESM.
+
+## Non-Goals
+
+- Sandboxing untrusted scripts. A `.mosh` file runs with the user's full
+  privileges by design (it can spawn engines and shell out); moshscript is an
+  automation tool for its author, not a safe host for third-party code.
+- A bespoke parser/type-checker for the "simple" dialect. We reach JS-legality by
+  executing as JS, not by growing the custom tokenizer into a language.
+- Reimplementing engine/tool behavior. moshscript verbs call the *same* exported
+  functions the TUI and CLI call; it adds no new capability, only a new caller.
+- A package/module system, imports between `.mosh` files, or a stdlib beyond the
+  moshcode command vocabulary. (Deferred; see Open Questions.)
+- Long-lived daemon/scheduler semantics. `/loop`-style scheduling stays a harness
+  concern; moshscript runs to completion.
+
+## Users
+
+- **The starter user** who copies the `while (alive) { … }` snippet from the
+  README, runs `/run alive.mosh`, and gets the metal feedback loop. They never
+  learn it's JavaScript.
+- **The automator** who scripts a real chore: "install claude + codex, register
+  our Sentry MCP server across both, then open an agent session" as a handful of
+  `.mosh` lines committed to a repo.
+- **CI / cron** invoking `moshcode run pipeline.mosh --dry-run` in a check, and
+  `moshcode run pipeline.mosh` on the runner, with the same file.
+- **Skill/PRD authors** who want `prd("idea")` or a fan-out callable from a
+  script rather than retyped interactively.
+
+## Requirements
+
+- R1 [P0] A `.mosh` file MUST execute as JavaScript. The existing starter script
+  (`while (alive) { code(); mosh(); notify(); repeat(); }`) MUST run unchanged
+  and produce equivalent output. The custom `interpreter.mjs` grammar is retired
+  as the execution path (kept only if needed as a compatibility shim; see R11).
+- R2 [P0] The moshscript command vocabulary MUST be injected as callable globals
+  into the script scope, so `code()`, `mosh()`, `notify(...)`, etc. resolve
+  without imports. `alive` MUST be a mutable global initialized to `true`, and
+  `stop()` MUST set it `false` so `while (alive)` terminates.
+- R3 [P0] Execution MUST be bounded. A `--max <n>` iteration/step budget MUST be
+  honored to prevent a runaway `while (alive)` from hanging, and the two
+  entrypoints MUST agree on the default (today CLI `run` defaults `max=3` while
+  TUI `runFile` hard-codes `100000` — this inconsistency MUST be resolved to a
+  single documented default).
+- R4 [P0] CLI verbs MUST be implemented by shelling out to the moshcode CLI
+  itself — `agents("claude")` runs `moshcode agents claude`, `install("codex")`
+  runs `moshcode install codex` — NOT by reaching into `src/engines.mjs` /
+  internals. There is one implementation of every capability (the CLI) and
+  moshscript is a second caller of it. This shell-out MUST be synchronous and
+  blocking (spawnSync with inherited stdio) so that (a) the simple no-`await`
+  style runs verbs in order — `install("claude"); agents("claude");` — and
+  (b) interactive engine sessions own the real terminal and hand control back to
+  the script on exit. The engine/agent verbs are: `agents(engine, ...args)`,
+  `start(engine, ...args)`, `install(target)`.
+- R5 [P0] The workflow-tool verbs MUST likewise shell out: `ugig(...args)`,
+  `coinpay(...args)`, `c0mpute(...args)` → `moshcode ugig …` etc., with
+  byte-transparent stdio so JSON pipelines survive.
+- R6 [P0] The fan-out, publishing, and system verbs MUST also shell out:
+  `mcp(...args)`, `skill(...args)`, `prd(idea?)`, `upgrade(...targets)`,
+  `pwd()`. Local moshscript-only verbs with no CLI equivalent
+  (`mosh`, `code`, `say`, `notify`, `sleep`, `stop`, `repeat`) are implemented
+  in-process; `mosh()` is the reference example of a local verb.
+- R7 [P0] `--dry-run` MUST be honored by every side-effecting verb: no engine
+  spawns, no installs, no network POSTs, no PRD writes. Each MUST instead narrate
+  what it *would* do (the resolved argv or request target). `notify()` and
+  `mosh()`'s browser-open already gate on `ctx.dryRun`; all new verbs MUST too.
+- R8 [P0] A verb that fails (missing engine, non-zero child exit, network error)
+  MUST surface a clear, metal-toned error and MUST NOT crash the interpreter mid
+  script unless the script chose to let it throw; a documented convention (e.g.
+  verbs resolve to a `{ ok, ... }`-style result and only throw on truly fatal
+  misuse) MUST be specified so scripts can branch on outcomes.
+- R9 [P1] The command vocabulary MUST remain open for extension: a script (or a
+  host embedding moshscript) MUST be able to register additional verbs, matching
+  today's documented `ctx.commands[name] = fn` seam.
+- R10 [P1] `moshcode commands` MUST list the full, current vocabulary (engine,
+  tool, fan-out, system, and flavor verbs) with one-line descriptions, and the
+  README + `/help` MUST reflect that `.mosh` is JS-legal.
+- R11 [P1] Backward compatibility: any `.mosh` that ran under the old
+  tokenizer MUST still run (the old grammar is a strict subset of JS, so
+  executing as JS should suffice; if any construct differs, a shim MUST cover
+  it). Existing tests (`interpreter.test.mjs`, `commands.test.mjs`,
+  `run-options.test.mjs`) MUST pass or be migrated with equivalent coverage.
+- R12 [P1] The verb→argv mapping for each engine/tool MUST be a pure, unit-tested
+  function (mirroring the MCP plan tests from
+  [[0003-cross-engine-mcp-and-skill-installation]]), so `agents("claude")` and
+  friends are verified without spawning real engines.
+- R13 [P2] Ergonomics: a `.mosh` file MAY use `await` at top level (the runner
+  executes in an async context) and MAY read `argv`/env for parameterization, so
+  the same script can be reused across targets.
+- R14 [P1] moshscript files MUST be directly executable like shell scripts. A
+  leading shebang line (`#!…`) MUST be ignored by the runner (stripped before
+  execution, exactly as `sh`/`node` ignore their own shebang), so a file starting
+  with `#!/usr/bin/env moshscript` still parses. moshcode MUST provide a
+  `moshscript` executable on PATH — a thin alias for `moshcode run` — so that
+  `#!/usr/bin/env moshscript` resolves, a `chmod +x script.mosh` file runs as
+  `./script.mosh`, and any positional args after the file reach the script (see
+  R13's `argv`). The `moshscript` bin and its install/PATH wiring MUST match how
+  the `moshcode` bin is already published (`bin` map in `package.json` +
+  `install.sh`).
+- R15 [P1] Human-in-the-loop, two verbs:
+  - `notify(msg)` — fire-and-forget. Pings the operator across their configured
+    channels (email / SMS / Telegram / Slack / any webhook, fanned out by
+    moshcoding.com) and surfaces an approval link `app.moshcode.sh/approve/:id`.
+    Returns `{ id, url }` so the script can hand the link off. Non-blocking.
+  - `ask(prompt)` — the blocking gate. Delivers the same ping + link, then
+    BLOCKS until the operator opens `app.moshcode.sh/approve/:id`, reads the context,
+    types instructions, and hits submit; resolves with their text (or null on
+    timeout). This is what lets an unattended `while (alive)` loop pause for a
+    human and resume from the reply. `ask()` awaits a network long-poll, so it
+    is used with `await`.
+  Client contract (in this repo): create id → deliver `{ message, approval:{id,url} }`
+  → long-poll `GET {API}/api/approvals/:id` until `{ status:"submitted", response }`.
+  The `app.moshcode.sh/approve/:id` page, the approvals inbox it submits to,
+  channel fan-out, auth, and billing are a SEPARATE approvals web app
+  (app.moshcode.sh) — OUT OF SCOPE for this PRD. The client degrades gracefully
+  (prints the link; the poll simply never resolves) until that server ships.
+- R16 [P1] `run(file, ...args)` MUST compose scripts: a `.mosh` file can include
+  another by calling `run("other.mosh")`, which is exactly `moshcode run other.mosh`.
+  Because CLI verbs block (spawnSync), includes execute in order and finish before
+  the caller continues. This gives moshscript an include/compose system for free —
+  developers factor setup/teardown into reusable `.mosh` files. (Recursion/cycle
+  protection is a developer concern for v1; `--max` does not bound include depth.)
+- R17 [P1] **Shortcuts** — higher-level sugar verbs composed from the CLI. Because
+  moshscript already batch-scripts moshcode, calling an engine is *technically*
+  possible today via `agents("claude")`; shortcuts make the common moves ergonomic
+  and, crucially, *return values scripts can use*. The flagship shortcut is
+  **`ai(prompt, opts?)`** — run a coding engine on a prompt and RETURN its output
+  as a string, so a script can branch on what the AI said:
+  ```js
+  const summary = ai("summarize the git diff in one line");
+  notify(summary);
+  ```
+  - `ai(prompt)` MUST run the default/available engine (claude, else codex /
+    opencode / gemini / aider) headlessly and return stdout as a string.
+    `ai(prompt, { engine: "codex" })` MUST target a specific engine.
+  - This requires a NON-interactive capture mode distinct from `agents()`/`start()`
+    (which hand over the TTY with inherited stdio and return no value): `ai()`
+    spawns the engine in its headless/print mode with stdout **captured** (piped,
+    not inherited) and returns it. `agents()`/`start()` are unchanged.
+  - `ai()` MUST honor `--dry-run` (narrate the engine + prompt, return "" ) and be
+    bounded like other verbs. Engine headless invocation (e.g. `claude -p`,
+    `codex exec`) MUST be defined per engine in a pure, tested mapping (cf. R12).
+  - Shortcuts are a namespace to grow (e.g. `ask()` is itself a human shortcut);
+    `ai()` is the first. Each shortcut MUST be documented in `moshcode commands`.
+  - **`ai()` composes with `ask()` as the escalation gate.** The intended pattern
+    is an autonomous loop that uses `ai()` to do the work AND to decide when a
+    human is actually needed, then calls `ask()` only at that point — so the
+    operator is pinged (slack/email/sms → a link with the full context + the
+    question) exactly when their judgment matters, not on every iteration:
+    ```js
+    while (alive) {
+      const plan = ai("given the failing test, propose a fix. If you're unsure or it's risky, reply exactly NEEDS_HUMAN.");
+      const go = plan.includes("NEEDS_HUMAN") ? await ask(`unsure — ${plan}`) : plan;
+      if (go) ai(`apply this: ${go}`);
+      repeat();
+    }
+    ```
+    This is the through-line for the approvals web app (app.moshcode.sh): its whole
+    job is to render that context + question at the link and route the human's
+    reply back into the waiting `ask()`.
+
+## UX Notes
+
+The simple surface — unchanged, still the README hero:
+
+```js
+// moshscript toolkit
+while (alive) {
+  code();
+  mosh();
+  notify();
+  repeat();
+} // no bugs, only features
+```
+
+The secret that it's all JS — now legal, no new syntax to learn:
+
+```js
+// deploy-agents.mosh — real work, still reads like the toy
+const engines = ["claude", "codex"];
+for (const e of engines) {
+  install(e);                 // idempotent: installs if missing
+}
+mcp("install", "https://mcp.sentry.dev/mcp");   // fan out across engines
+say(`ready to mosh with ${engines.length} engines 🤘`);
+agents("claude");             // drop into an autonomous session
+```
+
+Invocation — unchanged, plus a shebang path so `.mosh` files run themselves:
+
+```sh
+moshcode run deploy-agents.mosh            # do it
+moshcode run deploy-agents.mosh --dry-run  # narrate the argv, touch nothing
+moshcode run alive.mosh --max 3            # bounded metal loop
+```
+
+```js
+#!/usr/bin/env moshscript
+// deploy-agents.mosh — chmod +x it and run it like any shell script
+install("claude");
+agents("claude");
+```
+
+```sh
+chmod +x deploy-agents.mosh
+./deploy-agents.mosh                        # shebang → `moshscript` → `moshcode run`
+./deploy-agents.mosh --dry-run staging      # args after the file reach the script
+```
+
+The leading `#!…` line is stripped before execution (like `sh`/`node`), so it
+never confuses the parser.
+
+Dry-run output narrates instead of acting:
+
+```
+🎸 moshcode — running moshscript (dry run)
+  ⌨  install(claude)  → would run: npm i -g @anthropic-ai/claude-code
+  🤘 mcp(install …)    → would fan out to claude, codex (2 engines)
+  💬 ready to mosh with 2 engines 🤘
+  🎤 agents(claude)    → would launch: claude --dangerously-skip-permissions
+✓ no bugs, only features. 🤘
+```
+
+Voice stays irreverent-metal throughout (`the pit`, `no bugs only features`,
+🤘). `mosh()` already blasts the moshcoding Spotify playlist and opens it in a
+desktop browser — scripts inherit that.
+
+## Success Metrics
+
+- The unchanged starter `while (alive) { code(); mosh(); notify(); repeat(); }`
+  runs under the new engine with equivalent output.
+- A single `.mosh` file can install an engine, register an MCP server across
+  engines, and launch an agent session — actions that previously required typing
+  three separate pit commands.
+- `--dry-run` performs zero side effects (verified by tests: no spawns, no
+  network) while narrating every intended action.
+- Engine/tool argv mappings are covered by pure unit tests with no real spawns.
+- The full moshcode test suite passes; the two entrypoints share one default
+  iteration budget.
+
+## Risks & Open Questions
+
+Several early questions were settled while building the base architecture
+(`src/runtime.mjs`, `src/registry.mjs`, `src/cli.mjs`); recorded here as
+decisions:
+
+- **RESOLVED — execution model.** JS runs via `new AsyncFunction(...)` with the
+  vocabulary injected through a `with (proxy)` scope. The proxy owns only the
+  vocabulary + `alive`/`argv`/`env`; everything else (locals, `console`, `Math`)
+  falls through to normal scoping, so full JS works with zero dependencies and no
+  sandbox promised.
+- **RESOLVED — one registry, and verbs shell out to the CLI.** Rather than share
+  the two dispatch ladders, CLI verbs simply run `moshcode <cmd> …` (spawnSync).
+  The CLI stays the single implementation; the moshscript vocabulary is a
+  `createRegistry()` of `{name, run}` commands, so it can't silently diverge from
+  the capability it wraps.
+- **RESOLVED — blocking semantics.** CLI verbs and `sleep()` are synchronous and
+  blocking, so the simple no-`await` style (`install(…); agents(…);`) runs in
+  order; fire-and-forget async verbs (`notify`) are drained before the runner
+  returns, so a bare `notify()` still delivers.
+- **RESOLVED — iteration budget.** `--max` counts reads of `alive`, so a
+  `while (alive)` loop runs at most `--max` times (shared default **3** across
+  both entrypoints); straight-line scripts and plain `for` loops are unbounded.
+- **Error convention** (R8): CLI verbs currently throw on a non-zero exit (fail
+  loud). Whether a non-zero passthrough should instead return a result the script
+  can branch on is still open; a throwing model can make `while (alive)` loops
+  brittle.
+- **Interactive verbs in non-interactive runs** (R15): with spawnSync+inherited
+  stdio, `agents()`/`start()` are fully interactive in a real terminal, but in
+  CI/cron (no TTY) they can hang or error. The intended answer is R15's
+  `notify()` bridge — a headless script pings the operator and waits on a
+  moshcode.sh reply instead of blocking on a dead TTY. The reply-inbox endpoint
+  that feeds a response back into a waiting script is not yet built.
+- **`--dry-run` for the shell-out.** Under dry-run, CLI verbs narrate
+  `would run: moshcode …` and never spawn; the parent CLI they'd invoke doesn't
+  re-parse `--dry-run`, so nested dry-run is a runtime concern, handled in
+  `src/cli.mjs`, not passed through.
+- Should `.mosh` files support `import`/module reuse later? Deferred; the
+  AsyncFunction model doesn't foreclose it.