@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

package/framework/hooks/shared/graph-refresh.js

@@ -1,44 +1,6 @@
-/**
- * graph-refresh.js — refresh em background do grafo da árvore PRINCIPAL.
- *
- * Quem dispara: o elo `graph-refresh-kick` (PostToolUse, depois de um comando
- * Bash ou PowerShell com git/gh/morph-spec) e o SessionStart
- * (`worktree-context`). Os dois chamam `kickGraphRefresh`, que só olha o disco
- * e solta este mesmo arquivo como processo DESTACADO (`--run <raiz>`): quem
- * dispara nunca espera o graphify, que custa ~80 s no MORPH_GHLBrain mesmo sem
- * mudança nenhuma.
- *
- * Só a raiz. O processo destacado segura o diretório em que roda, e no win32
- * um diretório em uso não se apaga: com o refresh de uma worktree correndo, o
- * `finish` e o `worktree remove` falhavam com "Permission denied" e deixavam a
- * worktree meio removida. Por isso o worker nasce com `cwd` no git common dir,
- * nunca recebe o caminho de uma worktree, e o `graphify update` roda só na
- * raiz — que nenhum `finish` remove. A worktree nasce com o grafo semeado da
- * raiz (`seedGraphFromRoot`) e, dali em diante, é atualizada por
- * `morph-spec graph refresh`, em primeiro plano.
- *
- * Por que não o hook git do próprio graphify (`graphify hook install`), medido
- * no 0.9.50:
- *   - ele sai sem fazer nada numa worktree vinculada (compara `--git-dir` com
- *     `--git-common-dir`);
- *   - não instala `post-merge`: merge, fast-forward e `git pull` — o caminho
- *     pelo qual toda feature volta para a raiz — nunca rebuildam;
- *   - o rebuild dele só re-extrai `git diff HEAD~1 HEAD`; um commit depois de
- *     um fast-forward carimba `built_at_commit` = HEAD num grafo SEM os
- *     arquivos que o merge trouxe — "fresh" mentiroso.
- * Aqui o critério é o da regra única (graph-freshness.js): o carimbo e o
- * registro da última rodada contra o HEAD, e as regras do ignore por conteúdo.
- *
- * Um lock por REPOSITÓRIO (no git common dir) serializa o refresh em
- * background com o `graph build|refresh` manual — cada `graphify update` usa
- * todos os núcleos e os dois escreveriam o mesmo graph.json. O dono renova o
- * carimbo do lock antes de cada rodada, e a checagem é refeita depois de
- * soltá-lo, para não perder o commit que chegou enquanto ele era segurado.
- *
- * Fail-open em tudo: sem git, sem graphify ou sem grafo, nada acontece.
- *
- * @module graph-refresh
- */
+// Só a raiz: o worker destacado nasce com `cwd` no git common dir, porque no win32
+// um diretório em uso não se apaga e o `finish` de uma worktree falhava no meio.
+// A worktree anda por `morph-spec graph refresh`, em primeiro plano.
 
 import { spawn, spawnSync } from 'child_process';
 import {
@@ -58,14 +20,8 @@ import {
 
 export { primaryTree };
 
-/**
- * O que uma worktree herda do grafo da raiz. Fora da lista, de propósito:
- * `.graphify_root` guarda o caminho ABSOLUTO da raiz, e `cache/` é indexado
- * pelo mtime da árvore de origem — medido: copiado, não poupou re-extração.
- * O `.graphifyignore` também não vem: a worktree lê o do próprio checkout, e
- * pôr `/.graphifyignore` no exclude do common dir escondia também o da RAIZ
- * ainda não versionado (o `git add` dele passava a ser recusado).
- */
+// Ficam fora de propósito: `.graphify_root` guarda o caminho absoluto da raiz, `cache/`
+// é indexado pelo mtime da origem, e excluir `.graphifyignore` esconderia o da raiz.
 const SEED_FILES = ['manifest.json', '.graphify_analysis.json', '.graphify_labels.json', 'graph.json'];
 
 const EXCLUDE_MARKER = '# morph-spec: codebase graph inside worktrees (managed — see graph-refresh)';
@@ -77,10 +33,6 @@ const GRAPHIFY_TIMEOUT_MS = 20 * 60 * 1000;
 const MAX_ROUNDS = 3;
 const LOG_MAX_BYTES = 256 * 1024;
 
-/**
- * @param {string} dir
- * @returns {boolean} `dir` está na árvore principal (o refresh automático a cobre)
- */
 export function isPrimaryTree(dir) {
   const top = dir ? workTreeTop(dir) : null;
   const primary = primaryTree(dir);
@@ -92,7 +44,6 @@ function stateDir(dir) {
   return common ? join(common, 'morph-spec') : null;
 }
 
-/** @param {string} dir */
 export function refreshLockPath(dir) {
   const d = stateDir(dir);
   return d ? join(d, 'graph-refresh.lock') : null;
@@ -111,16 +62,8 @@ function mtimeOf(path) {
   }
 }
 
-/**
- * Estado do lock do repositório — o que `graph status` mostra como "refresh em
- * andamento". A idade conta da última renovação: um lock de processo morto,
- * ou sem renovação há mais que o teto, é `live: false`, e o próximo refresh o
- * recupera.
- *
- * @param {string} dir
- * @param {{now?: number, isAlive?: (pid: number) => boolean}} [deps]
- * @returns {{pid: number, since: string, renewed?: string, live: boolean}|null}
- */
+// A idade conta da última renovação: processo morto ou sem renovação além do
+// teto é `live: false`, e o próximo refresh recupera o lock.
 export function readRefreshLock(dir, { now = Date.now(), isAlive = pidAlive } = {}) {
   const path = refreshLockPath(dir);
   if (!path) return null;
@@ -133,11 +76,6 @@ export function readRefreshLock(dir, { now = Date.now(), isAlive = pidAlive } =
   }
 }
 
-/**
- * @param {string} dir
- * @param {{isAlive?: (pid: number) => boolean}} [deps]
- * @returns {string|null} o caminho do lock adquirido, ou null (ocupado ou sem git)
- */
 export function acquireRefreshLock(dir, deps = {}) {
   const path = refreshLockPath(dir);
   if (!path) return null;
@@ -162,13 +100,8 @@ export function acquireRefreshLock(dir, deps = {}) {
   return null;
 }
 
-/**
- * Renova o carimbo do lock, só se ainda for deste processo. Chamado antes de
- * cada rodada do graphify: uma posse que atravessa várias rodadas passaria do
- * teto de idade e seria roubada no meio de uma escrita.
- *
- * @param {string|null} path
- */
+// Uma posse que atravessa várias rodadas passaria do teto de idade e seria
+// roubada no meio de uma escrita.
 export function renewRefreshLock(path) {
   if (!path) return;
   try {
@@ -178,7 +111,6 @@ export function renewRefreshLock(path) {
   } catch { /* solto por outro — o release confere de novo */ }
 }
 
-/** Solta o lock só se ainda for deste processo. */
 export function releaseRefreshLock(path) {
   if (!path) return;
   try {
@@ -199,13 +131,7 @@ function appendRefreshLog(dir, entry) {
   } catch { /* log é diagnóstico, nunca bloqueia */ }
 }
 
-/**
- * `graphify` no PATH. No win32 o libuv só acha `.exe` sem shell; `.cmd`/`.bat`
- * (o que um shim ou um dublê de teste instala) passa pelo shell.
- *
- * @param {NodeJS.ProcessEnv} [env]
- * @returns {{file: string, shell: boolean}|null}
- */
+// No win32 o libuv só acha `.exe` sem shell; `.cmd`/`.bat` passa pelo shell.
 export function resolveGraphify(env = process.env) {
   const names = process.platform === 'win32'
     ? ['graphify.exe', 'graphify.cmd', 'graphify.bat']
@@ -214,23 +140,13 @@ export function resolveGraphify(env = process.env) {
   return file ? { file, shell: /\.(cmd|bat)$/i.test(file) } : null;
 }
 
-/**
- * `graphify <args>` síncrono, com `cwd` em `tree`. É o runner do refresh em
- * background E do `graph build|refresh` manual: o mesmo binário resolvido e o
- * mesmo `PYTHONHASHSEED=0` — é o que o hook do próprio graphify fixa para o
- * clustering não trocar as comunidades de lugar a cada rodada.
- *
- * @param {string} tree
- * @param {string[]} args
- * @param {{env?: NodeJS.ProcessEnv, timeout?: number|null}} [opts] `timeout: null` = sem teto
- * @returns {{status: number|null, output: string, unavailable?: boolean, error?: string}}
- */
+// `PYTHONHASHSEED=0` impede o clustering de trocar as comunidades de lugar a cada
+// rodada. `timeout: null` = sem teto.
 export function runGraphify(tree, args, { env = process.env, timeout = GRAPHIFY_TIMEOUT_MS } = {}) {
   const bin = resolveGraphify(env);
   if (!bin) return { status: null, unavailable: true, output: '' };
-  // Nunca com cwd na árvore: o graphify lê o alvo pelo argumento (o ignore e o
-  // git dele, medido no 0.9.50), e um graphify órfão com cwd numa worktree a
-  // prende no win32 até terminar — o finish e o worktree remove falhavam.
+  // Nunca com cwd na árvore: o graphify lê o alvo pelo argumento, e um órfão com
+  // cwd numa worktree a prende no win32 até terminar.
   const opts = {
     cwd: resolveGitCommonDir(tree) ?? tree,
     env: { ...env, PYTHONHASHSEED: '0' },
@@ -247,20 +163,8 @@ export function runGraphify(tree, args, { env = process.env, timeout = GRAPHIFY_
   return { status: r.status, output, ...(r.error ? { error: r.error.code } : {}) };
 }
 
-/**
- * Semeia uma worktree com o grafo da raiz. A worktree nasce de um commit da
- * raiz, então o grafo copiado ou já é o do HEAD dela ou fica a um
- * `morph-spec graph refresh` de distância — nunca a uma extração do zero.
- *
- * Só `graphify-out/` (no exclude do common dir, senão a worktree fica suja
- * para o `finish`). O registro da worktree copia o que se SABE do grafo da
- * raiz: o commit em que ele está em dia e as regras com que foi extraído —
- * nada inventado. Raiz sem registro das regras deixa a semente sem elas.
- *
- * @param {string} tree
- * @param {string} root
- * @returns {{seeded: boolean, reason?: string}}
- */
+// O registro da semente copia só o que se SABE do grafo da raiz; `graphify-out/`
+// vai para o exclude do common dir, senão a worktree fica suja para o `finish`.
 export function seedGraphFromRoot(tree, root) {
   if (!tree || !root || treeKey(tree) === treeKey(root)) return { seeded: false, reason: 'is-root' };
   if (existsSync(graphFile(tree))) return { seeded: false, reason: 'present' };
@@ -272,8 +176,7 @@ export function seedGraphFromRoot(tree, root) {
     for (const name of SEED_FILES) {
       const src = join(root, GRAPH_DIR, name);
       if (!existsSync(src)) continue;
-      // Por rename, e o graph.json por último: a presença dele é o sinal de
-      // semeadura completa, e quem lê no meio nunca vê meio arquivo.
+      // graph.json por último: a presença dele é o sinal de semeadura completa.
       const tmp = join(dst, `${name}.seed.${process.pid}`);
       copyFileSync(src, tmp);
       renameSync(tmp, join(dst, name));
@@ -294,13 +197,6 @@ export function seedGraphFromRoot(tree, root) {
   }
 }
 
-/**
- * Semeia a árvore de `dir` a partir da raiz, se ela for uma worktree sem
- * grafo — o que o SessionStart faz por uma worktree criada antes da semeadura
- * existir.
- *
- * @param {string} dir
- */
 export function seedFromPrimary(dir) {
   const tree = dir ? workTreeTop(dir) : null;
   const root = primaryTree(dir);
@@ -308,17 +204,8 @@ export function seedFromPrimary(dir) {
   return seedGraphFromRoot(tree, root);
 }
 
-/**
- * O trabalho do processo destacado, em primeiro plano (é o que os testes
- * chamam). Roda `graphify update` na raiz do repositório de `dir` enquanto o
- * grafo dela precisar (`refreshPending`), até `MAX_ROUNDS` rodadas — um
- * commit que chega no meio pede outra. Cada rodada vai para o registro
- * (graph-freshness.js) e para o log.
- *
- * @param {string} dir - qualquer diretório do repositório; o alvo é sempre a raiz
- * @param {{env?: NodeJS.ProcessEnv, runUpdate?: (tree: string) => {status: number|null, unavailable?: boolean, output?: string}}} [deps]
- * @returns {{ran: boolean, locked?: boolean, reason?: string, results: object[]}}
- */
+// A checagem é refeita depois de soltar o lock: um commit que chegou enquanto
+// ele era segurado pede outra rodada.
 export function runRefresh(dir, { env = process.env, runUpdate = (tree) => runGraphify(tree, ['update', tree], { env }) } = {}) {
   const root = primaryTree(dir);
   if (!root) return { ran: false, reason: 'no-primary-tree', results: [] };
@@ -357,23 +244,8 @@ export function runRefresh(dir, { env = process.env, runUpdate = (tree) => runGr
   return { ran: results.length > 0, results };
 }
 
-/**
- * Dispara o refresh da RAIZ em background e volta na hora — de qualquer
- * árvore do repositório. Só olha o disco, sem subprocesso: sem grafo na raiz
- * não há o que refrescar; grafo que não pede refresh no HEAD lido do disco não
- * paga um processo por comando git; com o graphify registrado como ausente e
- * ainda fora do PATH, não há quem rode. HEAD que o disco não responde (reftable,
- * branch sem commit) fica para o worker, que confere de novo sob o lock.
- *
- * O worker nasce com `cwd` no git common dir e só recebe a raiz: nenhum
- * processo destacado segura o diretório de uma worktree.
- *
- * `MORPH_GRAPH_AUTO_REFRESH=0` desliga (CI, máquina sem folga de CPU).
- *
- * @param {string} dir
- * @param {{spawnFn?: typeof spawn, env?: NodeJS.ProcessEnv}} [deps]
- * @returns {{kicked: boolean, reason?: string, pid?: number}}
- */
+// Só olha o disco: roda a cada comando git do agente. HEAD que o disco não
+// responde (reftable, branch sem commit) fica para o worker, sob o lock.
 export function kickGraphRefresh(dir, { spawnFn = spawn, env = process.env } = {}) {
   if (env.MORPH_GRAPH_AUTO_REFRESH === '0') return { kicked: false, reason: 'disabled' };
   const root = primaryTree(dir);

package/framework/hooks/shared/heavy-command.js

@@ -95,13 +95,8 @@ function kindOfTokens(tokens) {
   return null;
 }
 
-/**
- * The first heavy command of a Bash command line, as a label, or null. Looks at the executable of
- * each `;`/`&&`/`||`/`|`/newline segment, so `morph-spec heavy run -- dotnet test` and `echo "dotnet build"`
- * are not heavy: the first runs under its own slot, the second runs nothing.
- * @param {string} command
- * @returns {string|null}
- */
+// Judges only each segment's executable: `morph-spec heavy run -- dotnet test` already holds its
+// own slot, and `echo "dotnet build"` runs nothing.
 export function heavyKind(command) {
   for (const segment of splitSegments(command)) {
     const tokens = skipWrappers(tokenize(segment.replace(/^[\s({]+/, '').replace(/[\s)}]+$/, '')));
@@ -111,11 +106,8 @@ export function heavyKind(command) {
   return null;
 }
 
-/**
- * How long a foreground Bash call can run: its own `timeout` (capped at the platform maximum) plus slack.
- * The lease has no live process to watch, so this is the only thing that frees it after a denied or
- * interrupted call.
- */
+// The lease has no live process to watch: this TTL is the only thing that frees it after a
+// denied or interrupted call.
 const BASH_DEFAULT_TIMEOUT_MS = 2 * 60_000;
 const BASH_MAX_TIMEOUT_MS = 10 * 60_000;
 const LEASE_SLACK_MS = 30_000;

package/framework/hooks/shared/hook-response.js

@@ -1,47 +1,18 @@
-/**
- * Shared hook response builders for Claude Code hooks.
- *
- * Claude Code hooks communicate via JSON to stdout.
- * - PreToolUse: { "decision": "block"|"approve", "reason": "..." }
- * - SessionStart/Stop/PostToolUse/etc (non-blocking context injection):
- *   { "hookSpecificOutput": { "hookEventName": "...", "additionalContext": "..." } }
- *   A top-level `additionalContext` is NOT honored by Claude Code for any
- *   event — it must be nested under `hookSpecificOutput` alongside the
- *   event name (see https://code.claude.com/docs/en/hooks.md).
- */
+// A top-level `additionalContext` is NOT honored for any event: it must be nested
+// under `hookSpecificOutput` (https://code.claude.com/docs/en/hooks.md).
 
-/**
- * Block a tool use with a reason.
- * @param {string} reason - Human-readable reason for blocking
- */
 export function block(reason) {
   console.log(JSON.stringify({ decision: 'block', reason }));
   process.exit(0);
 }
 
-/**
- * Approve a tool use, optionally injecting context.
- * @param {string} [context] - Additional context to inject
- */
 export function approve(context) {
   if (context) {
     console.log(JSON.stringify({ decision: 'approve', additionalContext: context }));
   }
-  // No output = implicit approve
   process.exit(0);
 }
 
-/**
- * Inject additional (non-blocking) context for the current hook event.
- *
- * Must be nested under `hookSpecificOutput` — Claude Code does not honor a
- * top-level `additionalContext` for any event.
- *
- * @param {string} text - Context text to inject
- * @param {string} eventName - The hook event this is responding to (e.g.
- *   'SessionStart', 'Stop', 'PostToolUse') — required, echoed back as
- *   `hookSpecificOutput.hookEventName`.
- */
 export function injectContext(text, eventName) {
   console.log(JSON.stringify({
     hookSpecificOutput: { hookEventName: eventName, additionalContext: text },
@@ -49,63 +20,26 @@ export function injectContext(text, eventName) {
   process.exit(0);
 }
 
-/**
- * Silent exit — no output, no blocking.
- */
 export function pass() {
   process.exit(0);
 }
 
-// ── Pure (non-exiting) result builders ──────────────────────────────────────
-//
-// Every core hook used to run inline at module scope and call block()/pass()/
-// injectContext() above to print+exit(0) the moment it knew its verdict. That
-// stops being safe once a hook's logic moves into an exported `run(payload)`
-// that can ALSO be called by framework/hooks/claude-code/core/chain.js — which
-// imports several hooks' run() into ONE process and cannot have any of them
-// call process.exit() mid-chain (it would kill the other links). run() must
-// instead RETURN the verdict object; chain.js (or this file's own
-// runStandalone(), below) is what actually prints it and exits.
-//
-// These builders produce the exact same JSON shapes as block()/approve()/
-// injectContext() above — keep them in sync if that shape ever changes.
-
-/** Pure equivalent of block(reason) — returns the verdict instead of printing+exiting. */
+// `run()` returns these instead of exiting: chain.js runs several hooks in one
+// process. Same JSON shapes as block()/approve()/injectContext() above.
 export function blockResult(reason) {
   return { decision: 'block', reason };
 }
 
-/** Pure equivalent of approve(context) — null means "pass" (nothing to say). */
 export function approveResult(context) {
   return context ? { decision: 'approve', additionalContext: context } : null;
 }
 
-/** Pure equivalent of injectContext(text, eventName). */
 export function contextResult(text, eventName) {
   return { hookSpecificOutput: { hookEventName: eventName, additionalContext: text } };
 }
 
-/**
- * Standalone tail every core hook calls as its last line:
- * `await runStandalone(run);`
- *
- * Reads stdin once, calls the hook's `run(payload)`, prints the JSON verdict
- * (if any) and exits 0 — reproducing exactly what block()/injectContext()/
- * pass() used to do when a hook's logic lived inline at module scope.
- *
- * No-ops when MORPH_HOOK_CHAINED is set: that means core/chain.js already
- * imported this module and will call run() itself with a payload it read
- * once for the whole chain — this file must not ALSO read stdin or exit here
- * (doing so would race chain.js's own stdin read and kill the chain process
- * after the first link). chain.js sets the flag BEFORE its first dynamic
- * import, so every hook it loads sees it already set at call time.
- *
- * Fail-open: any error (including a rejected run()) prints nothing and exits
- * 0 — the same silent-pass behavior every hook's own outer try/catch used to
- * produce on an unexpected error.
- *
- * @param {(payload: object) => Promise<object|null>} run
- */
+// No-op under MORPH_HOOK_CHAINED: chain.js reads stdin once for the whole chain,
+// and reading or exiting here would kill it after the first link.
 export async function runStandalone(run) {
   if (process.env.MORPH_HOOK_CHAINED) return;
 
@@ -123,17 +57,8 @@ export async function runStandalone(run) {
   process.exit(0);
 }
 
-/**
- * Pure builder for a PreToolUse rewrite: Claude Code runs the tool with
- * `updatedInput` in place of the original `tool_input`, and the decision is
- * an explicit `allow` (a rewrite without a decision is ignored). Use it ONLY
- * when the hook actually changed something — an unconditional `allow` would
- * skip the permission prompt for every call it touches.
- *
- * @param {object} updatedInput - the full replacement tool_input
- * @param {string} eventName - 'PreToolUse'
- * @param {string} [context] - optional additionalContext (what was changed)
- */
+// A rewrite without a decision is ignored, so it carries `allow`: use it ONLY when
+// the input changed, or every call it touches skips the permission prompt.
 export function updatedInputResult(updatedInput, eventName, context) {
   const out = { hookEventName: eventName, permissionDecision: 'allow', updatedInput };
   if (context) out.additionalContext = context;

package/framework/hooks/shared/morph-cli.js

@@ -1,36 +1,10 @@
-/**
- * morph-cli.js — run the morph-spec CLI from inside a hook.
- *
- * Hooks are installed STANDALONE into `.morph/framework/hooks/` and may never
- * import from `src/`; the only way for a hook to reuse a CLI command (the
- * WorktreeCreate hook needs `worktree setup`/`provision`, WorktreeRemove needs
- * `worktree remove --if-clean`) is to spawn the CLI as a subprocess. This
- * module is the ONE place that knows how to find it.
- *
- * Resolution order:
- *   1. `MORPH_SPEC_BIN` — an explicit command, possibly with leading args and
- *      quoted paths (`node "R:/my repo/bin/morph-spec.js"`). What tests and a
- *      framework checkout use.
- *   2. `morph-spec` on PATH — the npm-installed bin. On win32 the shim is
- *      `morph-spec.cmd`, which Node refuses to spawn without a shell, so it is
- *      located by scanning PATH ourselves and then run through the shell with
- *      each arg quoted; on POSIX a plain `shell:false` spawn.
- *   3. `npx --no-install morph-spec` — a project-local dependency.
- *
- * ENOENT (or the shell's "not recognized"/"could not determine executable")
- * everywhere → `{ unavailable: true }`, never a throw: the caller decides what
- * degraded behavior looks like.
- *
- * `json` is the LAST line of stdout that parses as a JSON object (the CLI's
- * commands print exactly one JSON line; anything a stray console.log adds
- * before it is skipped), or null.
- */
-
+// A hook cannot import `src/`, so it reuses a CLI command by spawning the CLI; this is the one
+// place that finds it. On win32 `morph-spec.cmd` is located on PATH by hand and run through the
+// shell, since Node refuses to spawn a `.cmd` without one.
 import { spawnSync } from 'child_process';
 import { existsSync } from 'fs';
 import { delimiter, join } from 'path';
 
-/** Split a command string into argv, honoring single and double quotes. */
 function splitCommand(command) {
   const tokens = [];
   const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
@@ -39,22 +13,13 @@ function splitCommand(command) {
   return tokens;
 }
 
-/** Quote one argument for cmd.exe (the only shell path this module uses). */
 export function quoteForCmd(arg) {
   if (arg === '') return '""';
   if (!/[\s"&|<>^()]/.test(arg)) return arg;
   return `"${arg.replace(/"/g, '""')}"`;
 }
 
-/**
- * First PATH entry holding any of `files`, or null. The entries are walked in
- * PATH order and every name is tried inside each one, the way cmd.exe applies
- * PATHEXT: a `graphify.cmd` early in PATH wins over a `graphify.exe` later.
- *
- * @param {string[]} files
- * @param {NodeJS.ProcessEnv} env
- * @returns {string|null}
- */
+/** Walks PATH in order and tries every name in each entry, the way cmd.exe applies PATHEXT. */
 export function findFirstOnPath(files, env) {
   const raw = env.PATH || env.Path || env.path || '';
   for (const dir of raw.split(delimiter)) {
@@ -69,7 +34,6 @@ export function findFirstOnPath(files, env) {
 
 const findOnPath = (file, env) => findFirstOnPath([file], env);
 
-/** Last stdout line that parses as a JSON object, or null. */
 export function lastJsonLine(stdout) {
   const lines = String(stdout || '').split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
   for (let i = lines.length - 1; i >= 0; i--) {
@@ -82,10 +46,6 @@ export function lastJsonLine(stdout) {
   return null;
 }
 
-/**
- * The candidates to try, in order. Each is `{ file, args, shell }`.
- * @param {NodeJS.ProcessEnv} env
- */
 function candidates(env) {
   const list = [];
   const explicit = env.MORPH_SPEC_BIN && splitCommand(env.MORPH_SPEC_BIN);
@@ -107,10 +67,8 @@ function candidates(env) {
 const NOT_FOUND_RE = /not recognized as an internal or external command|could not determine executable to run|command not found|ENOENT/i;
 
 /**
- * Run `morph-spec <args>` and return its result.
- *
- * @param {string[]} args - CLI argv after the program name
- * @param {{ cwd?: string, timeoutMs?: number, env?: NodeJS.ProcessEnv }} [opts]
+ * A missing CLI is `{ unavailable: true }`, never a throw. `json` is the last stdout line that
+ * parses as an object.
  * @returns {{ ok: boolean, code: number|null, stdout: string, stderr: string, json: object|null, unavailable: boolean }}
  */
 export function runMorphSpec(args, { cwd, timeoutMs = 120000, env } = {}) {
@@ -134,10 +92,8 @@ export function runMorphSpec(args, { cwd, timeoutMs = 120000, env } = {}) {
     }
     const stdout = r.stdout || '';
     const stderr = r.stderr || '';
-    // The npx/shell paths cannot surface ENOENT: the shell (or npx itself)
-    // reports "not found" as a non-zero exit with a message. Only those two
-    // kinds are read that way — a real morph-spec failure is never mistaken
-    // for absence.
+    // Shell and npx report "not found" as a non-zero exit, never ENOENT; the explicit
+    // MORPH_SPEC_BIN is excluded so a real morph-spec failure is never read as absence.
     if (cand.kind !== 'env' && r.status !== 0 && !stdout.trim() && NOT_FOUND_RE.test(stderr)) continue;
     return { ok: r.status === 0, code: r.status, stdout, stderr, json: lastJsonLine(stdout), unavailable: false };
   }