@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

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

@@ -1,41 +1,6 @@
-/**
- * graph-freshness.js — a regra ÚNICA de "o grafo desta árvore está em dia".
- *
- * Todo mundo que pergunta lê daqui: o refresh em background
- * (graph-refresh.js, decide se roda), o `graph status|explain|affected` e o
- * `doctor` (via src/lib/graph/graph-loader.js `getFreshness`) e o
- * `graph build|refresh` (grava o resultado). Mora em hooks/shared porque hook
- * não importa `src/`. Uma segunda cópia da regra é como o status dizia
- * "fresco" enquanto o refresh achava "velho", ou o contrário.
- *
- * Duas fontes, nesta ordem:
- *   1. o carimbo `built_at_commit` do graph.json contra o HEAD;
- *   2. o REGISTRO da última rodada, por árvore, em
- *      `<git-common-dir>/morph-spec/graph-refresh-state.json`:
- *      `{ [árvore]: { head, exit, ignoreHash?, at, unavailable?, seeded? } }`.
- *
- * O registro existe porque o `graphify update` do 0.9.50 NÃO recarimba quando
- * a topologia não muda — "No code-graph topology changes detected; outputs
- * left untouched" (watch.py): commit só de `.morph/`, corpo de método editado,
- * commit num arquivo excluído. O carimbo fica no commit antigo e, sem o
- * registro, o grafo parecia velho para sempre e cada disparo rodava o graphify
- * de novo (~80 s no MORPH_GHLBrain). Rodada com exit 0 no HEAD H vale como
- * grafo em dia em H: o 0.9.50 sai 1 quando recusa escrever (`_check_shrink`,
- * grafo ilegível), e "untouched" sai 0.
- *
- * As regras do `.graphifyignore` entram por CONTEÚDO, nunca pelo relógio: o
- * registro guarda o hash das regras sob as quais o grafo EM DISCO foi
- * extraído (uma rodada que falhou não o muda), e um hash diferente do das
- * regras que valem hoje é grafo velho — numa worktree sem arquivo próprio,
- * as da raiz, que são as que o `graph refresh` usa ali. Comentário, linha
- * em branco, BOM e CRLF não contam — trocar o cabeçalho não pede refresh.
- * Grafo sem registro das regras (anterior a este estado) com regras valendo é
- * `rules-unknown`: um refresh grava o registro e encerra.
- *
- * Fail-open: nada aqui lança.
- *
- * @module graph-freshness
- */
+// Regra ÚNICA de "grafo em dia". O registro da rodada existe porque o `graphify
+// update` não recarimba `built_at_commit` quando a topologia não muda; as regras
+// do ignore entram por CONTEÚDO, nunca pelo relógio. Fail-open: nada aqui lança.
 
 import { createHash } from 'crypto';
 import { execFileSync } from 'child_process';
@@ -50,19 +15,12 @@ export const GRAPH_DIR = 'graphify-out';
 export const GRAPHIFY_IGNORE = '.graphifyignore';
 const STATE_FILE = 'graph-refresh-state.json';
 
-/** @param {string} tree */
 export function graphFile(tree) {
   return join(tree, GRAPH_DIR, 'graph.json');
 }
 
-/**
- * `built_at_commit` do graph.json. O graphify o grava como a ÚLTIMA chave, então
- * a leitura do fim do arquivo evita parsear 18 MB; a leitura inteira fica de
- * reserva para qualquer outra forma.
- *
- * @param {string} tree
- * @returns {string|null}
- */
+// O graphify grava `built_at_commit` como a ÚLTIMA chave: ler o fim evita parsear
+// o grafo inteiro, que fica de reserva para outra forma.
 export function readBuiltAtCommit(tree) {
   const file = graphFile(tree);
   let fd;
@@ -86,10 +44,6 @@ export function readBuiltAtCommit(tree) {
   }
 }
 
-/**
- * @param {string} tree
- * @returns {string|null}
- */
 export function readHead(tree) {
   try {
     return execFileSync('git', ['rev-parse', 'HEAD'], {
@@ -100,14 +54,7 @@ export function readHead(tree) {
   }
 }
 
-/**
- * As REGRAS de um `.graphifyignore`, sem o que o graphify não lê: comentário,
- * linha em branco, espaço no fim, BOM e CRLF. A ordem fica — no gitignore ela
- * muda o resultado.
- *
- * @param {string} text
- * @returns {string}
- */
+// A ordem fica: no gitignore ela muda o resultado.
 export function ignoreRules(text) {
   return String(text ?? '')
     .replace(/^\uFEFF/, '')
@@ -117,37 +64,22 @@ export function ignoreRules(text) {
     .join('\n');
 }
 
-/**
- * @param {string|null} text
- * @returns {string|null} null quando não há arquivo
- */
 export function rulesHash(text) {
   if (text === null || text === undefined) return null;
   return createHash('sha256').update(ignoreRules(text)).digest('hex').slice(0, 16);
 }
 
-/**
- * A árvore principal do repositório — a única que o refresh em background
- * toca. `null` fora de um repositório e quando o common dir não é o `.git` de
- * uma árvore (repositório bare, `--separate-git-dir`): aí não há raiz.
- *
- * @param {string} dir - qualquer diretório do repositório, raiz ou worktree
- * @returns {string|null}
- */
+/** `null` também quando o common dir não é o `.git` de uma árvore (bare, `--separate-git-dir`). */
 export function primaryTree(dir) {
   const common = dir ? resolveGitCommonDir(dir) : null;
   if (!common || basename(common) !== '.git') return null;
   return dirname(common);
 }
 
-/**
- * 1ª linha do `.graphifyignore` que o `graph refresh` põe numa worktree só
- * durante a rodada. Comentário não muda as regras nem o hash, e é por ele que a
- * sobra de uma rodada cujo processo morreu no meio é reconhecida.
- */
+// 1ª linha da cópia temporária: reconhece a sobra de uma rodada que morreu no
+// meio sem mudar as regras nem o hash.
 export const TEMP_IGNORE_MARKER = '# morph-spec: cópia temporária do graph refresh, apagada ao fim da rodada';
 
-/** @param {string|null} text */
 export function isTemporaryIgnore(text) {
   return String(text ?? '').replace(/^/, '').split(/\r?\n/, 1)[0] === TEMP_IGNORE_MARKER;
 }
@@ -160,14 +92,8 @@ function readText(path) {
   }
 }
 
-/**
- * O `.graphifyignore` com que o graphify roda nesta árvore: o do checkout;
- * numa worktree sem um (ou só com a sobra temporária), o da raiz, que é o que o
- * `graph refresh` põe no lugar durante a rodada.
- *
- * @param {string} tree
- * @returns {string|null} null quando nenhum arquivo vale
- */
+// Numa worktree sem arquivo próprio valem as regras da raiz: é o que o
+// `graph refresh` põe no lugar durante a rodada.
 export function ignoreTextOf(tree) {
   const own = readText(join(tree, GRAPHIFY_IGNORE));
   if (own !== null && !isTemporaryIgnore(own)) return own;
@@ -177,37 +103,18 @@ export function ignoreTextOf(tree) {
   return inherited !== null && !isTemporaryIgnore(inherited) ? inherited : null;
 }
 
-/**
- * @param {string} tree
- * @returns {string|null} null quando nenhum `.graphifyignore` vale para a árvore
- */
 export function ignoreRulesHash(tree) {
   return rulesHash(ignoreTextOf(tree));
 }
 
-/**
- * As linhas de `git status --porcelain` de `tree` sem a da sobra do
- * `.graphifyignore` temporário: ela é só uma cópia das regras da raiz, e o
- * `?? .graphifyignore` que deixa fazia o `finish` e o
- * `worktree remove --if-clean` recusarem. Só lê — quem confere a árvore chama
- * isto antes das recusas, e `dropLeftoverIgnore` só depois delas.
- *
- * @param {string} tree
- * @param {string[]} lines
- * @returns {string[]}
- */
+// Só lê: quem confere a árvore chama isto antes das recusas, e
+// `dropLeftoverIgnore` só depois delas.
 export function withoutLeftoverIgnore(tree, lines) {
   const leftover = `?? ${GRAPHIFY_IGNORE}`;
   if (!lines.includes(leftover) || !isTemporaryIgnore(readText(join(tree, GRAPHIFY_IGNORE)))) return lines;
   return lines.filter((line) => line !== leftover);
 }
 
-/**
- * Apaga a sobra do `.graphifyignore` temporário, reconhecida pelo marcador.
- *
- * @param {string} tree
- * @returns {boolean} apagou
- */
 export function dropLeftoverIgnore(tree) {
   const path = join(tree, GRAPHIFY_IGNORE);
   if (!isTemporaryIgnore(readText(path))) return false;
@@ -219,21 +126,12 @@ export function dropLeftoverIgnore(tree) {
   }
 }
 
-/**
- * Chave de uma árvore no registro. No win32 o caminho não distingue caixa, e
- * `R:\x` e `r:\x` são a mesma árvore.
- *
- * @param {string} tree
- */
+// No win32 o caminho não distingue caixa.
 export function treeKey(tree) {
   const path = resolve(tree);
   return process.platform === 'win32' ? path.toLowerCase() : path;
 }
 
-/**
- * @param {string} dir - qualquer diretório do repositório
- * @returns {string|null}
- */
 export function refreshStatePath(dir) {
   const common = dir ? resolveGitCommonDir(dir) : null;
   return common ? join(common, 'morph-spec', STATE_FILE) : null;
@@ -248,10 +146,7 @@ function readState(path) {
   }
 }
 
-/**
- * @param {string} tree
- * @returns {{head: string|null, exit: number|null, ignoreHash?: string|null, at: string, unavailable?: boolean, seeded?: boolean}|null}
- */
+/** @returns {{head: string|null, exit: number|null, ignoreHash?: string|null, at: string, unavailable?: boolean, seeded?: boolean}|null} */
 export function readRefreshRecord(tree) {
   const path = refreshStatePath(tree);
   if (!path) return null;
@@ -263,15 +158,7 @@ function pause(ms) {
   try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); } catch { /* sem espera */ }
 }
 
-/**
- * Grava o registro de `tree` (substitui o anterior). Por tmp + rename: quem lê
- * no meio vê o arquivo velho ou o novo, nunca meio. As árvores que não existem
- * mais saem na mesma escrita — uma worktree removida não deixa lixo.
- *
- * @param {string} tree
- * @param {object} record
- * @returns {object|null} o registro gravado, ou null (sem git, disco)
- */
+// As árvores que não existem mais saem na mesma escrita.
 export function writeRefreshRecord(tree, record) {
   const path = refreshStatePath(tree);
   if (!path) return null;
@@ -286,8 +173,7 @@ export function writeRefreshRecord(tree, record) {
     }
     state[key] = entry;
     writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
-    // No win32 o rename sobre um arquivo aberto por outro leitor falha por um
-    // instante (EPERM/EBUSY); o registro vale umas tentativas.
+    // No win32 o rename sobre um arquivo aberto por outro leitor falha por um instante.
     for (let attempt = 0; ; attempt++) {
       try {
         renameSync(tmp, path);
@@ -303,15 +189,8 @@ export function writeRefreshRecord(tree, record) {
   }
 }
 
-/**
- * Registra uma rodada do graphify sobre `tree`. As regras só mudam com exit 0:
- * uma rodada que falhou não mexeu no grafo, e o hash descreve o grafo em
- * disco, não a tentativa.
- *
- * @param {string} tree
- * @param {{head: string|null, exit: number|null, ignoreHash: string|null, unavailable?: boolean}} run
- *   `head` e `ignoreHash` lidos ANTES da rodada — é o que o graphify leu
- */
+// O hash das regras só muda com exit 0: descreve o grafo em disco, não a
+// tentativa. `head` e `ignoreHash` são lidos ANTES da rodada.
 export function recordRefreshRun(tree, { head, exit, ignoreHash, unavailable = false }) {
   const previous = readRefreshRecord(tree);
   let rules = {};
@@ -325,23 +204,7 @@ export function recordRefreshRun(tree, { head, exit, ignoreHash, unavailable = f
   });
 }
 
-/**
- * O frescor do grafo de `tree`.
- *
- *   missing  sem graph.json
- *   unknown  sem git, ou sem carimbo nem registro que diga o commit
- *   stale    atrás do HEAD (`reason` ausente), ou em dia no commit mas com as
- *            regras do ignore mudadas (`ignore-changed`) ou desconhecidas
- *            (`rules-unknown`)
- *   fresh    carimbo = HEAD, ou rodada com exit 0 neste HEAD — e as regras
- *            que valem para a árvore são as do grafo (`ignoreTextOf`; nenhum
- *            arquivo valendo não afirma nada)
- *
- * @param {string} tree - o diretório que contém `graphify-out/`
- * @param {{graph?: object, head?: string|null}} [known] o que o chamador já
- *   leu: o grafo parseado (o carimbo sai dele) e o HEAD
- * @returns {{state: 'missing'|'unknown'|'stale'|'fresh', built: string|null, head: string|null, reason?: 'ignore-changed'|'rules-unknown', record: object|null}}
- */
+/** @returns {{state: 'missing'|'unknown'|'stale'|'fresh', built: string|null, head: string|null, reason?: 'ignore-changed'|'rules-unknown', record: object|null}} */
 export function graphFreshness(tree, { graph, head } = {}) {
   if (!graph && !existsSync(graphFile(tree))) {
     return { state: 'missing', built: null, head: null, record: null };
@@ -363,15 +226,8 @@ export function graphFreshness(tree, { graph, head } = {}) {
   return { state: 'fresh', ...base };
 }
 
-/**
- * Um refresh em background resolveria? Grafo velho, e sem uma rodada que já
- * FALHOU neste mesmo HEAD — essa só se repete quando o HEAD andar (ou por
- * `morph-spec graph refresh`, que é explícito). "graphify ausente" não conta
- * como falha: instalado, ele roda no próximo disparo.
- *
- * @param {{state: string, head: string|null, record: object|null}} freshness
- * @returns {boolean}
- */
+// Uma rodada que FALHOU neste HEAD só se repete quando o HEAD andar;
+// "graphify ausente" não conta como falha.
 export function refreshPending(freshness) {
   if (freshness?.state !== 'stale') return false;
   const r = freshness.record;

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;