@polymorphism-tech/morph-spec 8.37.0 → 8.38.0

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

@@ -0,0 +1,416 @@
+/**
+ * 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
+ */
+
+import { spawn, spawnSync } from 'child_process';
+import {
+  appendFileSync, closeSync, copyFileSync, existsSync, mkdirSync, openSync,
+  readFileSync, renameSync, statSync, unlinkSync, writeFileSync, writeSync,
+} from 'fs';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { readPrimaryHead, resolveGitCommonDir, workTreeTop } from './git-paths.js';
+import { findFirstOnPath, quoteForCmd } from './morph-cli.js';
+import { ensureCommonExclude } from './git-exclude.js';
+import {
+  GRAPH_DIR, graphFile, graphFreshness, ignoreRulesHash, primaryTree, readRefreshRecord,
+  recordRefreshRun, refreshPending, treeKey, writeRefreshRecord,
+} from './graph-freshness.js';
+
+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).
+ */
+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)';
+
+const WORKER = fileURLToPath(import.meta.url);
+const LOCK_MAX_AGE_MS = 30 * 60 * 1000;
+const LOCK_WRITE_GRACE_MS = 5000;
+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);
+  return Boolean(top && primary && treeKey(top) === treeKey(primary));
+}
+
+function stateDir(dir) {
+  const common = resolveGitCommonDir(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;
+}
+
+function refreshLogPath(dir) {
+  const d = stateDir(dir);
+  return d ? join(d, 'graph-refresh.log') : null;
+}
+
+function mtimeOf(path) {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err?.code === 'EPERM';
+  }
+}
+
+/**
+ * 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}
+ */
+export function readRefreshLock(dir, { now = Date.now(), isAlive = pidAlive } = {}) {
+  const path = refreshLockPath(dir);
+  if (!path) return null;
+  try {
+    const lock = JSON.parse(readFileSync(path, 'utf8'));
+    const age = now - Date.parse(lock.renewed ?? lock.since);
+    return { ...lock, live: Boolean(isAlive(lock.pid)) && age >= 0 && age < LOCK_MAX_AGE_MS };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @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;
+  try { mkdirSync(dirname(path), { recursive: true }); } catch { return null; }
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = openSync(path, 'wx');
+      writeSync(fd, JSON.stringify({ pid: process.pid, since: new Date().toISOString() }));
+      closeSync(fd);
+      return path;
+    } catch (err) {
+      if (err?.code !== 'EEXIST') return null;
+      const current = readRefreshLock(dir, deps);
+      if (current?.live) return null;
+      // Ilegível e recém-criado é o dono ainda escrevendo entre o `wx` e o
+      // conteúdo — roubá-lo aqui poria dois graphify no mesmo graph.json.
+      const age = Date.now() - (mtimeOf(path) ?? 0);
+      if (!current && age < LOCK_WRITE_GRACE_MS) return null;
+      try { unlinkSync(path); } catch { return null; }
+    }
+  }
+  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
+ */
+export function renewRefreshLock(path) {
+  if (!path) return;
+  try {
+    const lock = JSON.parse(readFileSync(path, 'utf8'));
+    if (lock.pid !== process.pid) return;
+    writeFileSync(path, JSON.stringify({ ...lock, renewed: new Date().toISOString() }));
+  } 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 {
+    if (JSON.parse(readFileSync(path, 'utf8')).pid === process.pid) unlinkSync(path);
+  } catch { /* já solto */ }
+}
+
+function appendRefreshLog(dir, entry) {
+  const path = refreshLogPath(dir);
+  if (!path) return;
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    if (existsSync(path) && statSync(path).size > LOG_MAX_BYTES) {
+      const lines = readFileSync(path, 'utf8').split('\n').filter(Boolean);
+      writeFileSync(path, `${lines.slice(-200).join('\n')}\n`);
+    }
+    appendFileSync(path, `${JSON.stringify({ ts: new Date().toISOString(), ...entry })}\n`);
+  } 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}
+ */
+export function resolveGraphify(env = process.env) {
+  const names = process.platform === 'win32'
+    ? ['graphify.exe', 'graphify.cmd', 'graphify.bat']
+    : ['graphify'];
+  const file = findFirstOnPath(names, 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}}
+ */
+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.
+  const opts = {
+    cwd: resolveGitCommonDir(tree) ?? tree,
+    env: { ...env, PYTHONHASHSEED: '0' },
+    encoding: 'utf8',
+    windowsHide: true,
+    maxBuffer: 64 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    ...(timeout ? { timeout } : {}),
+  };
+  const r = bin.shell
+    ? spawnSync(quoteForCmd(bin.file), args.map(quoteForCmd), { ...opts, shell: true })
+    : spawnSync(bin.file, args, opts);
+  const output = `${r.stdout ?? ''}${r.stderr ?? ''}`;
+  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}}
+ */
+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' };
+  if (!existsSync(graphFile(root))) return { seeded: false, reason: 'no-root-graph' };
+  try {
+    const rootNow = graphFreshness(root);
+    const dst = join(tree, GRAPH_DIR);
+    mkdirSync(dst, { recursive: true });
+    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.
+      const tmp = join(dst, `${name}.seed.${process.pid}`);
+      copyFileSync(src, tmp);
+      renameSync(tmp, join(dst, name));
+    }
+    ensureCommonExclude(tree, [`/${GRAPH_DIR}`], EXCLUDE_MARKER);
+    const rules = rootNow.record && 'ignoreHash' in rootNow.record
+      ? { ignoreHash: rootNow.record.ignoreHash }
+      : {};
+    writeRefreshRecord(tree, {
+      head: rootNow.state === 'fresh' ? rootNow.head : rootNow.built,
+      exit: 0,
+      ...rules,
+      seeded: true,
+    });
+    return { seeded: true };
+  } catch (err) {
+    return { seeded: false, reason: err?.code || 'copy-failed' };
+  }
+}
+
+/**
+ * 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);
+  if (!tree || !root) return { seeded: false, reason: 'not-a-repo' };
+  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[]}}
+ */
+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: [] };
+  const results = [];
+  let rounds = 0;
+
+  while (rounds < MAX_ROUNDS && refreshPending(graphFreshness(root))) {
+    const lock = acquireRefreshLock(root);
+    if (!lock) return { ran: results.length > 0, locked: true, results };
+    try {
+      while (rounds < MAX_ROUNDS) {
+        const before = graphFreshness(root);
+        if (!refreshPending(before)) break;
+        rounds += 1;
+        renewRefreshLock(lock);
+        const ignoreHash = ignoreRulesHash(root);
+        const started = Date.now();
+        const r = runUpdate(root);
+        const exit = r.status ?? null;
+        recordRefreshRun(root, { head: before.head, exit, ignoreHash, unavailable: Boolean(r.unavailable) });
+        const after = graphFreshness(root);
+        const entry = {
+          tree: root, from: before.built, head: before.head, to: after.built,
+          ok: exit === 0, fresh: after.state === 'fresh', exit, ms: Date.now() - started,
+          ...(r.unavailable ? { unavailable: true } : {}),
+          ...(exit !== 0 && r.output ? { output: r.output.slice(-400) } : {}),
+        };
+        appendRefreshLog(root, entry);
+        results.push(entry);
+        if (r.unavailable) return { ran: true, reason: 'graphify-unavailable', results };
+      }
+    } finally {
+      releaseRefreshLock(lock);
+    }
+  }
+  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}}
+ */
+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);
+  if (!root) return { kicked: false, reason: 'not-a-repo' };
+  if (!existsSync(graphFile(root))) return { kicked: false, reason: 'no-graph' };
+  const head = readPrimaryHead(root);
+  if (head && !refreshPending(graphFreshness(root, { head }))) return { kicked: false, reason: 'not-pending' };
+  if (readRefreshRecord(root)?.unavailable && !resolveGraphify(env)) {
+    return { kicked: false, reason: 'graphify-unavailable' };
+  }
+  try {
+    const child = spawnFn(process.execPath, [WORKER, '--run', root], {
+      cwd: resolveGitCommonDir(root), env, detached: true, stdio: 'ignore', windowsHide: true,
+    });
+    child.on?.('error', () => {});
+    child.unref?.();
+    return { kicked: true, pid: child.pid };
+  } catch {
+    return { kicked: false, reason: 'spawn-failed' };
+  }
+}
+
+const isMain = (() => {
+  const argv1 = process.argv[1];
+  if (!argv1) return false;
+  const norm = (p) => (process.platform === 'win32' ? resolve(p).toLowerCase() : resolve(p));
+  return norm(argv1) === norm(WORKER);
+})();
+
+if (isMain && process.argv[2] === '--run' && process.argv[3]) {
+  try { runRefresh(process.argv[3]); } catch { /* fail-open */ }
+}

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

@@ -40,23 +40,35 @@ function splitCommand(command) {
 }
 
 /** Quote one argument for cmd.exe (the only shell path this module uses). */
-function quoteForCmd(arg) {
+export function quoteForCmd(arg) {
   if (arg === '') return '""';
   if (!/[\s"&|<>^()]/.test(arg)) return arg;
   return `"${arg.replace(/"/g, '""')}"`;
 }
 
-/** First PATH entry holding `file`, or null. */
-function findOnPath(file, env) {
+/**
+ * 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}
+ */
+export function findFirstOnPath(files, env) {
   const raw = env.PATH || env.Path || env.path || '';
   for (const dir of raw.split(delimiter)) {
     if (!dir) continue;
-    const candidate = join(dir, file);
-    try { if (existsSync(candidate)) return candidate; } catch { /* unreadable entry */ }
+    for (const file of files) {
+      const candidate = join(dir, file);
+      try { if (existsSync(candidate)) return candidate; } catch { /* unreadable entry */ }
+    }
   }
   return null;
 }
 
+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);

package/framework/hooks/shared/redact-secrets.js

@@ -0,0 +1,55 @@
+/**
+ * Redaction of obvious secrets in free text that telemetry persists (Bash
+ * commands, dispatch prompts). events.jsonl is copied into finish backups
+ * under `.git/`, so whatever lands there outlives the session.
+ *
+ * Pattern-based by design: it catches a secret written NEXT TO its name
+ * (`KEY=…`, `Authorization: …`, `user:pass@`) or in a well-known token shape.
+ * A bare value with no name beside it is invisible to any pattern — which is
+ * why tool OUTPUT (stdout/stderr, a failure's `error` body) is never persisted
+ * at all instead of being redacted.
+ */
+
+export const REDACTED = '[REDACTED]';
+
+const SECRET_KEY =
+  '[A-Za-z0-9_.-]*(?:secret|token|passw(?:or)?d|pwd|api[_-]?key|access[_-]?key|private[_-]?key|account[_-]?key|sharedaccesskey|credentials?|auth[_-]?key)[A-Za-z0-9_.-]*';
+
+const VALUE = `("[^"]*"|'[^']*'|[^\\s'",;&|}]+)`;
+
+const RULES = [
+  // A port (`host:8080/…`) is not a password; a password may contain `/`.
+  [/\b([a-z][a-z0-9+.-]*:\/\/[^\s:@/?#]+:)(?!\d+(?:[/?#\s]|$))[^\s@]+@/gi, `$1${REDACTED}@`],
+  [/\b(authorization\s*[:=]\s*)(?:(bearer|basic|token|digest)\s+)?[^\s'",;]+/gi,
+    (_, head, scheme) => `${head}${scheme ? `${scheme} ` : ''}${REDACTED}`],
+  // A token carries a digit; "Bearer authentication" is prose.
+  [/\b(bearer\s+)(?=[A-Za-z0-9._~+/=-]*\d)[A-Za-z0-9._~+/=-]{8,}/gi, `$1${REDACTED}`],
+  // `-u 1000:1000` is a uid:gid, not credentials.
+  [/(\s-u\s+|--user[=\s]+)(['"]?)(?!\d+:\d+\b)[^\s:'"]+:[^\s'"]+\2/g, `$1${REDACTED}`],
+  [new RegExp(`(["']?)(${SECRET_KEY})\\1(\\s*[:=]\\s*)${VALUE}`, 'gi'),
+    (_, quote, key, sep) => `${quote}${key}${quote}${sep}${REDACTED}`],
+  [new RegExp(`\\b([A-Z][A-Z0-9_]*_(?:KEY|PASS|PAT|SIG))(\\s*=\\s*)${VALUE}`, 'g'), `$1$2${REDACTED}`],
+  [new RegExp(`(--(?:password|passwd|pass|token|secret|api-?key|access-key|auth-token)(?:\\s+|=))${VALUE}`, 'gi'),
+    `$1${REDACTED}`],
+  [new RegExp(`(\\buser-secrets\\s+set\\s+(?:"[^"]*"|'[^']*'|\\S+)\\s+)${VALUE}`, 'gi'), `$1${REDACTED}`],
+  [/([?&](?:sig|access_token|token|api[_-]?key|key|password|secret|code)=)[^&\s'"#]+/gi, `$1${REDACTED}`],
+  [/\b(?:gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{22,})\b/g, REDACTED],
+  [/\bsk-(?:ant-)?[A-Za-z0-9_-]{16,}/g, REDACTED],
+  [/\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{10,}/g, REDACTED],
+  [/\bnpm_[A-Za-z0-9]{36}\b/g, REDACTED],
+  [/\bxox[abposr]-[A-Za-z0-9-]{10,}/g, REDACTED],
+  [/\bAKIA[0-9A-Z]{16}\b/g, REDACTED],
+  [/\bAIza[0-9A-Za-z_-]{35}\b/g, REDACTED],
+  [/\beyJ[A-Za-z0-9_-]{5,}\.eyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]+/g, REDACTED],
+];
+
+/**
+ * @param {*} text
+ * @returns {*} the text with secrets replaced by `[REDACTED]`; non-strings unchanged
+ */
+export function redactSecrets(text) {
+  if (typeof text !== 'string' || text === '') return text;
+  let out = text;
+  for (const [pattern, replacement] of RULES) out = out.replace(pattern, replacement);
+  return out;
+}

package/framework/hooks/shared/telemetry-logger.js

@@ -20,6 +20,8 @@ import {
   appendFileSync, readFileSync, mkdirSync, existsSync, statSync, renameSync,
 } from 'fs';
 import { join, dirname } from 'path';
+import { randomUUID } from 'crypto';
+import { redactSecrets } from './redact-secrets.js';
 
 const LOGS_DIR = '.morph/logs';
 export const EVENTS_FILE = join(LOGS_DIR, 'events.jsonl');
@@ -32,13 +34,26 @@ export const EVENTS_FILE = join(LOGS_DIR, 'events.jsonl');
 // this it grows forever the way activity.jsonl used to before R1.2.
 export const ROTATE_THRESHOLD_BYTES = 5 * 1024 * 1024; // 5 MB
 
+// Bumped when a field changes meaning. Readers key legacy handling off its
+// absence (v1 events carry no schemaVersion and no eventId).
+export const TELEMETRY_SCHEMA_VERSION = 2;
+
+const FREE_TEXT_FIELDS = ['command', 'prompt', 'desc', 'target'];
+
+/** A tool call that failed read nothing and changed nothing. */
+export function isFailedToolCall(event) {
+  return event?.event === 'PostToolUseFailure';
+}
+
 function getEventsPath(projectPath) {
   return join(projectPath || process.cwd(), EVENTS_FILE);
 }
 
 /**
  * Append a single telemetry event as one JSON line.
- * Stamps an ISO `ts` when the caller omits one.
+ * Stamps `ts` (unless given), `schemaVersion` and a unique `eventId` — the
+ * dedupe key when the same line is read back from a rotated archive or a
+ * finish backup — and redacts secrets in the free-text fields.
  *
  * @param {Object} event - Event payload (tool, skill/persona/target/prompt, feature, phase…)
  * @param {string} [projectPath] - Project root (defaults to cwd)
@@ -49,7 +64,15 @@ export function appendTelemetryEvent(event, projectPath) {
     const dir = dirname(eventsPath);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 
-    const stamped = { ts: event?.ts || new Date().toISOString(), ...event };
+    const stamped = {
+      ts: event?.ts || new Date().toISOString(),
+      schemaVersion: TELEMETRY_SCHEMA_VERSION,
+      eventId: randomUUID(),
+      ...event,
+    };
+    for (const field of FREE_TEXT_FIELDS) {
+      if (typeof stamped[field] === 'string') stamped[field] = redactSecrets(stamped[field]);
+    }
     appendFileSync(eventsPath, JSON.stringify(stamped) + '\n', 'utf-8');
   } catch {
     // Fail-silent — never block hooks

package/framework/hooks/shared/transcript-usage.js

@@ -0,0 +1,80 @@
+/**
+ * Real token usage read from a Claude Code transcript (JSONL), shared by the
+ * Stop hook (the main session's transcript) and SubagentStop (each
+ * sub-agent's own transcript, which the main one does not include).
+ */
+
+import { readFileSync, existsSync, statSync } from 'fs';
+
+// A 45 MB / ~16k-line transcript parses in ~350 ms; above this, skip rather
+// than risk an unbounded read inside a hook.
+const MAX_TRANSCRIPT_BYTES = 50 * 1024 * 1024;
+
+export const USAGE_KEYS = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheCreationTokens'];
+
+/**
+ * Sum `message.usage` over the assistant turns of a transcript.
+ *
+ * One turn is written as several lines (one per content block), each repeating
+ * the same usage under the same `message.id`: summing lines double-counts, so
+ * the sum is deduplicated by message id.
+ *
+ * @param {string} [transcriptPath]
+ * @returns {{inputTokens:number,outputTokens:number,cacheReadTokens:number,cacheCreationTokens:number}|null}
+ *   null when there is nothing to report (no/oversized/unreadable file, no usage)
+ */
+export function readTranscriptUsage(transcriptPath) {
+  if (!transcriptPath || typeof transcriptPath !== 'string') return null;
+  try {
+    if (!existsSync(transcriptPath)) return null;
+    if (statSync(transcriptPath).size > MAX_TRANSCRIPT_BYTES) return null;
+
+    const totals = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 };
+    const seen = new Set();
+    let sawAny = false;
+
+    for (const line of readFileSync(transcriptPath, 'utf-8').split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      let entry;
+      try { entry = JSON.parse(trimmed); } catch { continue; }
+      if (entry?.type !== 'assistant') continue;
+      const usage = entry?.message?.usage;
+      if (!usage || typeof usage !== 'object') continue;
+
+      const key = entry?.message?.id || entry?.uuid;
+      if (key) {
+        if (seen.has(key)) continue;
+        seen.add(key);
+      }
+
+      sawAny = true;
+      totals.inputTokens += Number(usage.input_tokens) || 0;
+      totals.outputTokens += Number(usage.output_tokens) || 0;
+      totals.cacheReadTokens += Number(usage.cache_read_input_tokens) || 0;
+      totals.cacheCreationTokens += Number(usage.cache_creation_input_tokens) || 0;
+    }
+
+    return sawAny ? totals : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The usage added since the previous sample of the same transcript.
+ *
+ * A counter going DOWN means the transcript restarted (a new file under the
+ * same key), so the whole current total is new usage — subtracting would
+ * produce negative spend.
+ *
+ * @param {object|null|undefined} previous - last recorded totals for this key
+ * @param {object} current - totals just read
+ * @returns {{delta: object, changed: boolean}}
+ */
+export function usageDelta(previous, current) {
+  const reset = !previous || USAGE_KEYS.some((k) => (current[k] ?? 0) < (previous[k] ?? 0));
+  const delta = {};
+  for (const k of USAGE_KEYS) delta[k] = reset ? (current[k] ?? 0) : (current[k] ?? 0) - (previous[k] ?? 0);
+  return { delta, changed: USAGE_KEYS.some((k) => delta[k] !== 0) };
+}

package/framework/rubrics/backend.json

@@ -10,8 +10,8 @@
     },
     "code_quality": {
       "weight": 0.25,
-      "validators": ["architecture", "reuse"],
-      "description": "Architecture patterns, dependency direction, code structure, and reuse of what the codebase already has"
+      "validators": ["architecture", "reuse", "code-budget"],
+      "description": "Architecture patterns, dependency direction, code structure, reuse of what the codebase already has, and comment and test budget"
     },
     "design_ui": {
       "weight": 0.05,

package/framework/rubrics/default.json

@@ -10,8 +10,8 @@
     },
     "code_quality": {
       "weight": 0.25,
-      "validators": ["architecture", "reuse"],
-      "description": "Architecture patterns, code structure, and reuse of what the codebase already has"
+      "validators": ["architecture", "reuse", "code-budget"],
+      "description": "Architecture patterns, code structure, reuse of what the codebase already has, and comment and test budget"
     },
     "design_ui": {
       "weight": 0.15,

package/framework/rubrics/frontend.json

@@ -10,8 +10,8 @@
     },
     "code_quality": {
       "weight": 0.15,
-      "validators": ["architecture", "reuse"],
-      "description": "Architecture patterns, code structure, and reuse of what the codebase already has"
+      "validators": ["architecture", "reuse", "code-budget"],
+      "description": "Architecture patterns, code structure, reuse of what the codebase already has, and comment and test budget"
     },
     "design_ui": {
       "weight": 0.35,