wendkeep 0.46.1 → 0.47.0

package/CHANGELOG.md

@@ -4,6 +4,63 @@ All notable changes to **wendkeep** are documented here. Format based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.47.0] — 2026-07-23
+
+### Added
+
+- **Grafo do vault conectado: todo artefato de change linka o hub.** `change new` gera
+  `design.md` e `tarefas.md` com um backlink full-path pro `proposta.md` da própria change —
+  antes nasciam sem nenhum wikilink, ilhas no grafo do Obsidian (num vault real: 48 de 63
+  `.md` de `08-Mudanças` órfãos). O full-path (nunca basename, ambíguo entre changes) sobrevive
+  ao archive: o `rewriteChangeLinks` retargeta pro `_arquivo` junto com os demais links.
+- **Auto-heal do backlink em `spec.md`.** O delta de spec é escrito à mão, então `verify` e
+  `archive` passam a injetar o backlink pro proposta em cada `specs/<capability>/spec.md` que
+  estiver sem — idempotente. Nenhum artefato de change fica desconectado do plano↔sessão.
+- **`wendkeep change backlink [--apply]`** — backfill dos artefatos órfãos que já existem no
+  vault (changes open e arquivadas), apontando cada `design`/`tarefas`/`spec` pro proposta no
+  seu local atual. Dry-run por default; `--apply` escreve. Idempotente.
+- **`wendkeep theme sync`** — re-aplica o color system (snippet CSS + graph color groups) num
+  vault existente, sem re-`init`. Recupera o grafo que ficou cinza quando o Obsidian (dono do
+  `graph.json`) zera os `colorGroups`. O instalador virou módulo compartilhado com o `init`,
+  então os dois nunca divergem.
+- **Snippet define `--file-line-width`.** O CSS gerado passa a definir a largura de linha
+  legível (1400px, ajustável) sobre o `body` com `!important` — antes era edição manual em
+  cada vault. As capabilities `change-graph` e `vault-theme` documentam o contrato em `07-Specs`.
+
+## [0.46.2] — 2026-07-19
+
+### Fixed
+
+- **Rollout de subagent do Codex virava sessão top-level no import.** Um subagent do Codex
+  não é um arquivo em `<transcript>/subagents/` — é um rollout **irmão** no
+  `~/.codex/sessions/`, cujo `session_meta` declara `source.subagent` e aponta pro pai via
+  `parent_thread_id`. O import ignorava o marcador e materializava o subagent como uma
+  "sessão" própria, com o contexto do pai inteiro replicado (subagent herda o histórico) —
+  no caso real, uma nota fantasma de 23 turnos duplicando a conversa da sessão-mãe. Agora a
+  descoberta expõe o marcador, o import conta subagents à parte no relatório (nunca em
+  `skipped`) e nenhuma nota é criada. A entrada de registry que o import antigo escreveu
+  para um subagent é removida — self-healing do nosso próprio dado errado, nunca limpeza
+  genérica: entrada com o mesmo id mas transcript diferente é preservada.
+- **Telemetria de subagent do Codex nunca chegava à sessão-mãe — nem ao vivo.** A descoberta
+  (`collectSubagentUsage`) era Claude-shaped: procurava um diretório `subagents/` ao lado do
+  transcript, que no Codex não existe. Resultado: toda sessão Codex fechava com
+  `subagents_count: 0`, tanto no import quanto no hook vivo `SubagentStop` wirado na 0.46.0
+  — o custo dos subagents simplesmente não existia no vault. A nova
+  `collectCodexSubagentUsage` acha os irmãos por `parent_thread_id` (no dia do rollout pai e
+  no dia seguinte, cobrindo spawn que cruza a meia-noite UTC — o caso real passou a seis
+  minutos disso) e devolve o mesmo agregado que o writer já consome: vivo e import passam a
+  atribuir pelo mesmo caminho.
+- **O bloco injetado ainda aparecia como fala do usuário no "Contexto conversado".** O fix
+  da 0.46.1 protegeu o título, mas a linha `**Usuário:**` da iteração vinha de um segundo
+  filtro (`shouldIgnoreUserText`) que duplicava por cópia a lista do `isBootstrapPrompt` — e
+  as cópias divergiram. O filtro agora delega: um lugar só para o próximo bloco que o
+  harness inventar.
+- Bytes NUL literais em `hooks/token-usage.mjs` e `hooks/subagent-usage.mjs` escapados —
+  mesma classe do fix de `taxonomy.mjs` (#7): o byte cru fazia o `file` classificar o fonte
+  como binário e o ripgrep pulá-lo em silêncio. Entrou `tests/source-hygiene.test.mjs`
+  barrando byte de controle em qualquer fonte publicado; ele pegou uma quarta ocorrência
+  introduzida durante esta própria mudança.
+
 ## [0.46.1] — 2026-07-19
 
 ### Fixed

package/README.md

@@ -70,7 +70,7 @@ npx wendkeep init
    - **`dotcontext`** — *legacy, not recommended, and hidden from the picker.* wendkeep's native a2 loop (`change` / `verify` / gate) already does its job, so installing it **duplicates the harness**. Reachable only via an explicit `--companions dotcontext` for anyone already invested (tune with `--dotcontext-mcp` / `--dotcontext-hooks`).
 
    Control with `--companions <csv>` or `--no-companions`. The Claude Code plugin layer (`extraKnownMarketplaces` + `enabledPlugins`) is wired as a bonus where the companion has one.
-6. Install a **color system** into the vault's `.obsidian/`: a CSS snippet that accents notes by type (session/decision/bug/learning, via the `cssclasses` the hooks emit) plus graph color groups by folder. Non-destructive merge into `appearance.json`/`graph.json`; skip with `--no-colors`.
+6. Install a **color system** into the vault's `.obsidian/`: a CSS snippet that accents notes by type (session/decision/bug/learning, via the `cssclasses` the hooks emit) plus graph color groups by folder. Non-destructive merge into `appearance.json`/`graph.json`; skip with `--no-colors`. Re-apply it any time on an existing vault with `wendkeep theme sync` — Obsidian owns `graph.json` and can drop the color groups (a grey graph); the re-sync restores them without a full re-`init`.
 7. Seed the **curated memory layer**: `.brain/CORE.md` (the hand-curated hot layer, with the 3 required sections) and `.brain/COMPACTION_PROTOCOL.md` (the protocol guide). The auto layers (`DIGEST.md`, `index.jsonl`) are generated by the hooks. Validate the curated layer with `wendkeep validate-memory` (cap 25 lines, 3 sections, no secrets/PII).
 8. Seed the **definitions + skills layer**: `.brain/agents/` + `.brain/skills/` (versioned source of truth), including the native process skills `wk-workflow` / `wk-tdd` / `wk-debugging` / `wk-brainstorming` / `wk-planning` / `wk-verify` (some ship templates — e.g. `wk-verify`'s `verdict-template.json` + reviewer prompt). `init` runs `wendkeep sync-defs` for you, delivering the skills to `.claude/skills/` and `.agents/skills/`, and the agent definitions (`.brain/agents/*.toml`) to `.codex/agents/`, plus a managed section in `AGENTS.md` that indexes the skills for Codex; `sync-defs --check` detects stale copies (re-run `sync-defs` after editing `.brain`).
 9. Seed the **change/spec lifecycle**: the `07-Specs/` + `08-Mudanças/` folders and a native `wendkeep.sensors.json` — a critical `memory-validation` sensor (`npx wendkeep validate-memory`) plus one for each of `typecheck` / `test` / `lint` / `build` found in your `package.json`. Add your own with `wendkeep sensors add`. Drives `wendkeep change` / `wendkeep verify` — see **Change lifecycle** below.
@@ -252,9 +252,13 @@ npx wendkeep change archive dark-mode          # gate: sensors + verdict + no op
 ```
 
 The archive promotes the delta into generated `07-Specs/ui.md`, mints an ADR, and the
-Obsidian graph now links *session ↔ change ↔ requirement ↔ decision*. A change that names
-no `[req:]` still runs `verify --deep`, but skips the `wk-verify` reading pass: the
-command writes a trivial verdict on its own and the sensor gate is the real proof.
+Obsidian graph now links *session ↔ change ↔ requirement ↔ decision*. Every generated
+artifact (`design`/`tarefas`) is born linking its change's `proposta` hub, and hand-authored
+`spec.md` deltas are auto-linked on `verify`/`archive` — no change artifact is a graph island.
+To backfill older changes that predate this, run `wendkeep change backlink --apply` (dry-run
+without `--apply`). A change that names no `[req:]` still runs `verify --deep`, but skips the
+`wk-verify` reading pass: the command writes a trivial verdict on its own and the sensor gate
+is the real proof.
 
 ## How it works
 

package/bin/wendkeep.mjs

@@ -44,8 +44,11 @@ Usage:
 
   wendkeep doctor [--vault P]  Run a vault health check.
   wendkeep change <sub>        Change lifecycle: new [--simple] | use | bind <slug> --session <id> | continue | list | show |
-                           status | done <id> | undone <id> | diff | archive [--force] | abandon.
+                           status | done <id> | undone <id> | diff | archive [--force] | abandon | relink | backlink.
                            archive exige verdict (rode verify --deep); abandon descarta sem ADR.
+                           backlink [--apply]: injeta o backlink pro proposta em design/tarefas/spec órfãos (open + _arquivo).
+  wendkeep theme sync          Re-aplica o color system (snippet CSS + graph color groups) num vault
+                           existente — recupera o grafo cinza sem re-init. --vault P.
   wendkeep session <sub>       Session registry: list | show <id> | use <id>.
   wendkeep spec <sub>          Specs: list | show | effective [--change] [--json] | migrate | rebase.
   wendkeep sensors <sub>       list | add <id> "<command>" [--severity --type --report].
@@ -175,6 +178,11 @@ async function main() {
       runSession(rest);
       break;
     }
+    case 'theme': {
+      const { runTheme } = await import('../src/theme.mjs');
+      runTheme(rest);
+      break;
+    }
     case 'verify': {
       const { runVerify } = await import('../src/verify.mjs');
       runVerify(rest);

package/hooks/change-core.mjs

@@ -2,10 +2,10 @@
 // Native change/spec lifecycle in the vault (Pilar B). Vault-facing lib consumed by
 // the `wendkeep change` CLI (src/change.mjs) and the brain-inject hook. No external deps.
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, relative } from 'node:path';
 import { ensureDir, wikilinkFromRel, monthFolderRelFromDateStr } from './obsidian-common.mjs';
 import { parseSpecsList, promoteSpecs, discoverSpecDeltas, tasksHashOf, captureSpecBaseline, REQ_ID_RE_SRC } from './spec-core.mjs';
-import { getLocale } from './locale.mjs';
+import { getLocale, LOCALES } from './locale.mjs';
 
 export const ARCHIVE_DIR = '_arquivo';
 const POINTER = '.brain/CURRENT_CHANGE.md';
@@ -39,12 +39,21 @@ specs: []
 
 ${en ? '## Why\n\n(reason for the change)\n\n## What changes\n\n(scope of the change)' : '## Por quê\n\n(motivo da mudança)\n\n## O que muda\n\n(escopo da mudança)'}
 `;
+  // Hub backlink: design/tarefas link the change's proposta so no generated artifact is a
+  // graph island. Full-path (never basename — proposta/design exist in every change) so the
+  // archive's rewriteChangeLinks retargets it to _arquivo when the change moves.
+  const changesFolder = (LOCALES[locale] || LOCALES['pt-BR']).folders.changes;
+  const hubLink = `> ${en ? 'Change:' : 'Mudança:'} [[${changesFolder}/${slug}/proposta]]`;
   const design = `# ${slug} — design
 
+${hubLink}
+
 ${en ? '## Approach\n\n(technical approach)' : '## Abordagem\n\n(abordagem técnica)'}
 `;
   const tarefas = `# ${slug} — ${en ? 'tasks' : 'tarefas'}
 
+${hubLink}
+
 - [ ] 1.1 ${en ? '(first task)' : '(primeira tarefa)'}
 `;
   const reqHeading = en ? 'Requirement' : 'Requisito';
@@ -419,6 +428,10 @@ export function archiveChange(vaultBase, slug, { gate = gateGreen, dateStr, adrN
   let reqIds = [];
   try { reqIds = [...new Set(parseTasks(readFileSync(join(src, 'tarefas.md'), 'utf8')).flatMap((t) => t.reqs ?? []))]; } catch { /* sem tarefas */ }
 
+  // Backlink dos artefatos escritos à mão (spec.md) ANTES do move — o rewriteChangeLinks
+  // abaixo retargeta o wikilink pro _arquivo junto com os demais. Fail-quiet.
+  try { healSpecBacklinks(src, vaultBase); } catch { /* heal é bônus */ }
+
   ensureDir(join(vaultBase, chDir, ARCHIVE_DIR));
   try {
     renameSync(src, destAbs);
@@ -512,6 +525,96 @@ function rewriteChangeLinks(vaultBase, fromRel, toRel) {
   return touched;
 }
 
+// --- backlinks de artefato -> hub proposta (grafo conectado) -------------------
+// design/tarefas nascem linkando o hub (renderChangeScaffold); spec.md é escrito à mão,
+// então recebe o backlink por auto-heal (verify/archive) + backfill dos vaults existentes.
+function backlinkLabel(loc) {
+  return loc.id === 'en' ? 'Change:' : 'Mudança:';
+}
+
+// Injeta a linha de backlink logo abaixo do primeiro heading — mas NUNCA acima de um bloco
+// de frontmatter YAML: prepender antes do `---` quebra o frontmatter (Obsidian para de ler
+// cssclasses/tags). Ordem: preserva o frontmatter, depois cai abaixo do 1º heading do corpo,
+// senão no topo do corpo.
+function insertBacklink(content, backlinkLine) {
+  let head = '';
+  let body = content;
+  const fm = content.match(/^---\n[\s\S]*?\n---\n?/);
+  if (fm) { head = fm[0]; body = content.slice(fm[0].length); }
+  const h = body.match(/^\s*#[^\n]*\n/);
+  if (h) {
+    const rest = body.slice(h[0].length).replace(/^\n+/, '');
+    return `${head}${h[0]}\n${backlinkLine}\n\n${rest}`;
+  }
+  const rest = body.replace(/^\n+/, '');
+  return `${head}${backlinkLine}\n\n${rest}`;
+}
+
+// Auto-heal (0.47): garante o backlink pro proposta em cada specs/<cap>/spec.md do change.
+// Idempotente (pula quem já tem o link exato). Chamado no verify e no archive (antes do move,
+// pra o rewriteChangeLinks retargetar pro _arquivo). Retorna quantos arquivos healou.
+export function healSpecBacklinks(changeDir, vaultBase) {
+  const loc = getLocale(vaultBase);
+  const propRel = `${relative(vaultBase, changeDir).replaceAll('\\', '/')}/proposta`;
+  const link = `[[${propRel}]]`;
+  const line = `> ${backlinkLabel(loc)} ${link}`;
+  let caps = [];
+  try { caps = readdirSync(join(changeDir, 'specs'), { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name); }
+  catch { return 0; }
+  let healed = 0;
+  for (const cap of caps) {
+    const p = join(changeDir, 'specs', cap, 'spec.md');
+    let c;
+    try { c = readFileSync(p, 'utf8'); } catch { continue; }
+    if (c.includes(link)) continue;
+    try { writeFileSync(p, insertBacklink(c, line), 'utf8'); healed += 1; } catch { /* readonly — segue */ }
+  }
+  return healed;
+}
+
+// Backfill (0.47): cura design/tarefas/spec órfãos em changes já existentes — open e _arquivo.
+// Aponta cada artefato pro proposta no seu local atual (arquivado usa o path do _arquivo).
+// Dry-run por default; `apply` escreve. Idempotente (pula quem já linka o proposta certo).
+export function backfillArtifactLinks(vaultBase, { apply = false } = {}) {
+  const loc = getLocale(vaultBase);
+  const chDir = loc.folders.changes;
+  const label = backlinkLabel(loc);
+  const base = join(vaultBase, chDir);
+  const dirs = [];
+  try {
+    for (const name of readdirSync(base)) {
+      if (name === ARCHIVE_DIR) continue;
+      const d = join(base, name);
+      if (existsSync(join(d, 'proposta.md'))) dirs.push(d);
+    }
+  } catch { /* sem changes */ }
+  try {
+    for (const name of readdirSync(join(base, ARCHIVE_DIR))) {
+      const d = join(base, ARCHIVE_DIR, name);
+      if (existsSync(join(d, 'proposta.md'))) dirs.push(d);
+    }
+  } catch { /* sem arquivo */ }
+
+  const changed = [];
+  for (const dir of dirs) {
+    const propRel = `${relative(vaultBase, dir).replaceAll('\\', '/')}/proposta`;
+    const link = `[[${propRel}]]`;
+    const line = `> ${label} ${link}`;
+    let caps = [];
+    try { caps = readdirSync(join(dir, 'specs'), { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => join('specs', e.name, 'spec.md')); }
+    catch { /* sem specs */ }
+    for (const rel of ['design.md', 'tarefas.md', ...caps]) {
+      const p = join(dir, rel);
+      let c;
+      try { c = readFileSync(p, 'utf8'); } catch { continue; }
+      if (c.includes(link)) continue;
+      if (apply) { try { writeFileSync(p, insertBacklink(c, line), 'utf8'); } catch { continue; } }
+      changed.push(relative(vaultBase, p).replaceAll('\\', '/'));
+    }
+  }
+  return { applied: apply, scanned: dirs.length, changed };
+}
+
 // Cura retroativa (vaults pré-0.35): wikilinks para changes que já moveram sem reescrita.
 // Dry-run por default; match por slug no nome datado do archive (`<data>-<slug>[-abandonada]`);
 // ambíguo (mesmo slug arquivado 2×) é reportado e pulado — nunca chuta.

package/hooks/import-sessions.mjs

@@ -17,7 +17,7 @@ import {
 import { buildSessionContent, allocateSessionPath } from './session-start.mjs';
 import { createLinkedNotes } from './linked-notes.mjs';
 import { updateSessionObservability } from './session-observability.mjs';
-import { readSessionRegistry, upsertSessionRegistry, formatLocalIso, formatDate, providerMeta, isBootstrapPrompt } from './obsidian-common.mjs';
+import { readSessionRegistry, upsertSessionRegistry, removeSessionRegistryEntry, formatLocalIso, formatDate, providerMeta, isBootstrapPrompt } from './obsidian-common.mjs';
 import { getLocale } from './locale.mjs';
 import { captureProseDecisions } from './decision-capture.mjs';
 
@@ -192,7 +192,12 @@ export function discoverCodexTranscripts(projectPath, fromDir) {
     const meta = readSessionMeta(path);
     if (!meta || !meta.id) continue;
     if (projectPath && !cwdMatchesProject(meta.cwd, projectPath)) continue;
-    transcripts.push({ path, sessionId: meta.id, cwd: meta.cwd || '' });
+    // A subagent thread's rollout is a SIBLING file of its parent's — same dir, own id. The
+    // meta says what the file IS; ignoring it turned hierarchy into a duplicate session note.
+    const subagent = meta.source?.subagent
+      ? { parentThreadId: meta.parent_thread_id || meta.source.subagent.thread_spawn?.parent_thread_id || '', nickname: meta.source.subagent.thread_spawn?.agent_nickname || '' }
+      : null;
+    transcripts.push({ path, sessionId: meta.id, cwd: meta.cwd || '', subagent });
   }
   return { dir, transcripts };
 }
@@ -350,10 +355,21 @@ export function runImport(vaultBase, opts = {}) {
   }
   const notes = capturedSessionNotes(vaultBase);
   const sinceMs = since ? Date.parse(since) : 0;
-  const report = { source: src, claudeDir, codexDir, scanned: transcripts.length, imported: 0, repaired: 0, skipped: 0, errors: [], sessions: [] };
+  const report = { source: src, claudeDir, codexDir, scanned: transcripts.length, imported: 0, repaired: 0, skipped: 0, subagents: 0, errors: [], sessions: [] };
 
   let done = 0;
   for (const t of transcripts) {
+    // A subagent rollout is telemetry of its PARENT session, never a session of its own —
+    // importing it materialized the parent's replayed context as a ghost note. Counted apart
+    // from `skipped` (which means "session already covered"). If import <=0.46.1 registered
+    // it as a top-level session, that entry is our own bad write: heal it.
+    if (t.subagent) {
+      report.subagents++;
+      if (!dryRun) {
+        try { removeSessionRegistryEntry(vaultBase, t.sessionId, t.path); } catch { /* best-effort */ }
+      }
+      continue;
+    }
     if (limit && done >= limit) break;
 
     // Every transcript is parsed now, including already-captured ones: partial coverage is

package/hooks/obsidian-common.mjs

@@ -355,6 +355,25 @@ function meaningfulPatch(patch = {}) {
   }));
 }
 
+// Remove one registry entry, but ONLY when its transcript matches the given path — this is
+// self-healing for entries wendkeep itself mis-wrote (a subagent rollout registered as a
+// top-level session by import <=0.46.1), never generic registry cleanup. An entry with the
+// same id but a different transcript belongs to someone else's state and is preserved.
+export function removeSessionRegistryEntry(vaultBase, sessionId, transcriptPath) {
+  if (!sessionId) return false;
+  let removed = false;
+  mutateSessionRegistry(vaultBase, (registry) => {
+    const entry = registry.sessions[sessionId];
+    if (!entry) return null;
+    const paths = [...(Array.isArray(entry.transcript_paths) ? entry.transcript_paths : []), entry.transcript_path].filter(Boolean);
+    if (!paths.some((p) => transcriptsMatch(p, transcriptPath))) return null;
+    delete registry.sessions[sessionId];
+    removed = true;
+    return null;
+  });
+  return removed;
+}
+
 export function upsertSessionRegistry(vaultBase, sessionId, patch) {
   if (!sessionId) return null;
   const clean = meaningfulPatch(patch);

package/hooks/session-observability.mjs

@@ -1,7 +1,7 @@
 // Single atomic writer for session usage, models, reasoning/effort and subagents.
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { collectSessionUsage } from './token-usage.mjs';
-import { collectSubagentUsage, sessionDirFromTranscript } from './subagent-usage.mjs';
+import { collectSubagentUsage, collectCodexSubagentUsage, sessionDirFromTranscript } from './subagent-usage.mjs';
 import { inspectTranscriptIdentity } from './session-identity.mjs';
 
 const HEADING = '## Agentes, tokens e custos';
@@ -137,7 +137,11 @@ ${renderSubagents(subagents)}`;
 export function buildSessionObservability({ sessionContent, transcriptPath }) {
   const main = collectSessionUsage({ sessionContent, transcriptPath });
   if (!main) return null;
-  const subagents = collectSubagentUsage(sessionDirFromTranscript(transcriptPath));
+  // Claude layout first (<transcript>/subagents/); when absent, the Codex layout — sibling
+  // rollouts linked by parent_thread_id. The Codex collector self-gates: a Claude transcript
+  // has no session_meta line, so it returns null and this stays a strict fallback.
+  const subagents = collectSubagentUsage(sessionDirFromTranscript(transcriptPath))
+    || collectCodexSubagentUsage(transcriptPath);
   const ledger = [...mainLedger(main), ...subagentLedger(subagents)];
   const sub = subagents?.aggregate || { count: 0, tokens: 0, cost: 0, wasted: 0, tools: [] };
   let content = main.content;

package/hooks/session-stop.mjs

@@ -18,6 +18,7 @@ import {
   formatLocalIso,
   getNextAdrNumber,
   getVaultBase,
+  isBootstrapPrompt,
   warnIfDefaultVault,
   listMarkdownFiles,
   readControl,
@@ -53,11 +54,12 @@ const SYNTHETIC_EVENT_TAG = /^<\/?(?:task-notification|system-reminder|local-com
 
 function shouldIgnoreUserText(text) {
   const trimmed = String(text || '').trim();
+  // Bootstrap detection is DELEGATED, not copied: this used to duplicate isBootstrapPrompt's
+  // prefix list and the copies drifted — <recommended_plugins> made it into one and not the
+  // other, so the title came out clean while the same block still showed as "Usuário" in the
+  // conversation context. One filter, one place to add the next injected block.
   return SYNTHETIC_EVENT_TAG.test(trimmed)
-    || /^# AGENTS\.md instructions/.test(trimmed)
-    || trimmed.startsWith('<permissions instructions>')
-    || trimmed.includes('You are Codex, a coding agent')
-    || trimmed.startsWith('## Memory')
+    || isBootstrapPrompt(trimmed)
     // Harness utility meta-prompts (title generation, classifiers) — not real user turns; they
     // were leaking into note titles/summaries on import.
     || /^Generate a concise( UI)? title/i.test(trimmed)

package/hooks/subagent-usage.mjs

@@ -76,6 +76,109 @@ const round4 = (n) => Math.round((Number(n) || 0) * 10000) / 10000;
 
 // Aggregate every subagent transcript under <sessionDir>/subagents. null when the dir is
 // absent (Codex / a session with no subagents) or nothing parseable.
+// --- Codex discovery ----------------------------------------------------------
+// A Codex subagent is not a file under `<transcript>/subagents/` — it is a SIBLING rollout
+// in ~/.codex/sessions/YYYY/MM/DD/, whose session_meta declares source.subagent and points
+// back via parent_thread_id. Without this, every Codex session closed with subagents_count 0,
+// live (SubagentStop) and on import alike.
+
+// First line of a rollout, bounded — Codex meta lines can be large (env, git, instructions).
+function readRolloutMeta(path, maxBytes = 4 * 1024 * 1024) {
+  try {
+    const text = readFileSync(path, 'utf-8');
+    if (text.length > maxBytes) return null;
+    const line = text.slice(0, text.indexOf('\n') === -1 ? text.length : text.indexOf('\n'));
+    const e = JSON.parse(line);
+    return e.type === 'session_meta' ? (e.payload || {}) : null;
+  } catch { return null; }
+}
+
+// Sibling day dirs to scan: the parent rollout's own dir plus the NEXT day — a session that
+// crosses midnight UTC spawns its subagent in the other day's folder, and the first real case
+// (Vendiva, 23:54 UTC) missed that by six minutes.
+function codexSiblingDirs(transcriptPath) {
+  const dir = join(transcriptPath, '..');
+  const m = String(dir).replace(/[\\/]+$/, '').match(/(\d{4})[\\/](\d{2})[\\/](\d{2})$/);
+  if (!m) return [dir];
+  const next = new Date(Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]) + 1));
+  const pad = (n) => String(n).padStart(2, '0');
+  const nextDir = join(dir, '..', '..', '..', String(next.getUTCFullYear()), pad(next.getUTCMonth() + 1), pad(next.getUTCDate()));
+  return [dir, nextDir];
+}
+
+export function collectCodexSubagentUsage(transcriptPath) {
+  const meta = readRolloutMeta(transcriptPath);
+  if (!meta?.id) return null; // not a Codex rollout — the Claude path stays untouched
+  const canonicalId = meta.id;
+
+  const subagents = [];
+  const allTools = new Set();
+  const usageAgg = { input: 0, cached: 0, cacheWrite: 0, output: 0, reasoning: 0, total: 0 };
+  const modelMap = new Map();
+  let count = 0;
+  let calls = 0;
+  let cost = 0;
+
+  for (const dayDir of codexSiblingDirs(transcriptPath)) {
+    let names;
+    try { names = readdirSync(dayDir); } catch { continue; }
+    for (const n of names) {
+      if (!/\.jsonl$/i.test(n)) continue;
+      const f = join(dayDir, n);
+      if (f === transcriptPath) continue;
+      const sib = readRolloutMeta(f);
+      if (!sib?.source?.subagent) continue;
+      const parent = sib.parent_thread_id || sib.source.subagent.thread_spawn?.parent_thread_id || '';
+      if (parent !== canonicalId) continue;
+
+      const summary = summarizeTokenUsage(parseTokenUsageFromTranscript(f));
+      if (!summary.calls) continue;
+      const tokens = tokensTotal(summary.totals);
+      for (const t of summary.tools) allTools.add(t);
+
+      subagents.push({
+        id: String(sib.id || basename(f, '.jsonl')).slice(0, 12),
+        agentType: sib.source.subagent.thread_spawn?.agent_nickname || 'codex-subagent',
+        workflow: null,
+        model: summary.models[0] || '?',
+        effort: summary.pensamento || '',
+        tools: summary.tools.length,
+        toolNames: summary.tools,
+        calls: summary.calls,
+        tokens,
+        cost: round4(summary.costs.model),
+        modelRows: summary.modelRows,
+      });
+
+      for (const row of summary.modelRows || []) {
+        const rowEffort = summary.pensamento || '';
+        const key = `${row.provider || '?'}\u0000${row.model || '?'}\u0000${rowEffort}`;
+        const current = modelMap.get(key) || { provider: row.provider || '?', model: row.model || '?', effort: rowEffort, calls: 0, tokens: 0, cost: 0,
+          usage: { input: 0, cached: 0, cacheWrite: 0, output: 0, reasoning: 0, total: 0 } };
+        current.calls += row.calls || 0;
+        current.tokens += tokensTotal(row.usage);
+        current.cost += row.costs?.model || 0;
+        for (const k of Object.keys(current.usage)) current.usage[k] += row.usage?.[k] || 0;
+        modelMap.set(key, current);
+      }
+
+      count += 1;
+      calls += summary.calls;
+      cost += summary.costs.model;
+      for (const k of Object.keys(usageAgg)) usageAgg[k] += summary.totals[k] || 0;
+    }
+  }
+
+  if (!count) return null;
+  return {
+    subagents,
+    workflows: [],
+    aggregate: { count, calls, tokens: tokensTotal(usageAgg), cost: round4(cost), wasted: 0, usage: usageAgg, tools: [...allTools],
+      modelRows: [...modelMap.values()].map((r) => ({ ...r, cost: round4(r.cost), source: 'subagent' })),
+    },
+  };
+}
+
 export function collectSubagentUsage(sessionDir) {
   const subDir = join(sessionDir, 'subagents');
   if (!existsSync(subDir)) return null;

package/hooks/token-usage.mjs

@@ -612,7 +612,7 @@ const USAGE_FIELDS = ['provider', 'pensamento', 'input', 'cache_write', 'cache_r
 
 export function sameUsageData(a, b) {
   if (!a || !b) return false;
-  const listEqual = (x, y) => (x || []).join('') === (y || []).join('');
+  const listEqual = (x, y) => (x || []).join('\u0000') === (y || []).join('\u0000');
   return USAGE_FIELDS.every((f) => (a[f] ?? null) === (b[f] ?? null))
     && listEqual(a.modelos, b.modelos) && listEqual(a.tools, b.tools);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.46.1",
+  "version": "0.47.0",
   "description": "A persistent-memory harness for AI coding agents on your Obsidian vault: turn-by-turn session capture plus a native, zero-dependency spec→change→verify→archive loop (sensor-gated, independent verdict, mutation discrimination). Local-first, agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "bin": {

package/src/change.mjs

@@ -14,6 +14,7 @@ import {
   archiveChange,
   abandonChange,
   relinkChanges,
+  backfillArtifactLinks,
   scaffoldPlaceholders,
 } from '../hooks/change-core.mjs';
 import { evaluateGate, requiredSensors } from '../hooks/sensors-core.mjs';
@@ -308,6 +309,15 @@ export function runChange(argv) {
     process.exit(0);
   }
 
+  if (sub === 'backlink') {
+    const r = backfillArtifactLinks(vaultBase, { apply: rest.includes('--apply') });
+    if (rest.includes('--json')) { process.stdout.write(`${JSON.stringify(r, null, 2)}\n`); process.exit(0); }
+    process.stdout.write(`${r.changed.length} artefato(s) órfão(s) em ${r.scanned} change(s)${r.applied ? ' · reescritos' : ''}\n`);
+    for (const f of r.changed) process.stdout.write(`  ${f}\n`);
+    if (!r.applied && r.changed.length) process.stdout.write('\ndry-run — nada escrito. Rode com --apply para injetar os backlinks.\n');
+    process.exit(0);
+  }
+
   if (sub === 'abandon') {
     const slug = slugArg() || activeChange(vaultBase);
     if (!slug) { process.stderr.write('wendkeep change abandon: missing <slug> and no active change\n'); process.exit(2); }
@@ -317,6 +327,6 @@ export function runChange(argv) {
     process.exit(0);
   }
 
-  process.stderr.write(`wendkeep change: unknown subcommand "${sub}". Known: new, use, continue, list, show, status, done, undone, diff, archive, abandon, relink.\n`);
+  process.stderr.write(`wendkeep change: unknown subcommand "${sub}". Known: new, use, continue, list, show, status, done, undone, diff, archive, abandon, relink, backlink.\n`);
   process.exit(2);
 }

package/src/init.mjs

@@ -31,13 +31,7 @@ import {
 import { renderVaultReadme } from './vault-readme.mjs';
 import { seedVaultViews } from './vault-views.mjs';
 import { canInteractiveSelect, selectCompanionsInteractive } from './companion-select.mjs';
-import {
-  SNIPPET_NAME,
-  renderColorSnippetCss,
-  mergeAppearance,
-  graphColorGroups,
-  mergeGraphColorGroups,
-} from './vault-theme.mjs';
+import { syncVaultTheme } from './theme.mjs';
 import { renderCoreSkeleton, renderCompactionProtocol } from './validate-core.mjs';
 import { seedDefinitions, syncDefs } from './sync-defs.mjs';
 import { seedWkSkills } from './skills-seed.mjs';
@@ -261,33 +255,11 @@ function runCavemanInstaller(log) {
   }
 }
 
-// Install the vault color system into .obsidian: write wendkeep's CSS snippet,
-// enable it (non-destructive), and add graph color groups. Returns a short note.
-// Unparseable user JSON is left untouched (we only merge into valid/absent files).
+// Install the vault color system into .obsidian: write wendkeep's CSS snippet, enable it
+// (non-destructive), and add graph color groups. Shared installer lives in theme.mjs so
+// `init` and `theme sync` never drift. Unparseable user JSON is left untouched.
 function installVaultColors(vaultPath) {
-  const loc = getLocale(vaultPath);
-  const obsidianDir = join(vaultPath, '.obsidian');
-  const snippetsDir = join(obsidianDir, 'snippets');
-  mkdirSync(snippetsDir, { recursive: true });
-  writeFileSync(join(snippetsDir, `${SNIPPET_NAME}.css`), renderColorSnippetCss(loc), 'utf8');
-
-  let enabled = false;
-  const appPath = join(obsidianDir, 'appearance.json');
-  const appRead = readJsonSafe(appPath);
-  if (appRead.ok) {
-    writeJson(appPath, mergeAppearance(appRead.data || {}, SNIPPET_NAME));
-    enabled = true;
-  }
-
-  let groups = 0;
-  const graphPath = join(obsidianDir, 'graph.json');
-  const graphRead = readJsonSafe(graphPath);
-  if (graphRead.ok) {
-    const merged = mergeGraphColorGroups(graphRead.data || {}, graphColorGroups(loc));
-    writeJson(graphPath, merged);
-    groups = graphColorGroups(loc).length;
-  }
-  return `snippet ${SNIPPET_NAME}.css${enabled ? ' (enabled)' : ' (enable by hand: appearance.json unreadable)'} + ${groups} graph group(s)`;
+  return syncVaultTheme(vaultPath).summary;
 }
 
 // --- main -------------------------------------------------------------------

package/src/theme.mjs

@@ -0,0 +1,89 @@
+// `wendkeep theme sync` — re-apply the vault color system into .obsidian on an EXISTING
+// vault, idempotently: rewrite the CSS snippet, enable it (non-destructive), and (re)merge
+// the graph color groups. The installer is shared with `wendkeep init` so the two never drift.
+//
+// Why a re-sync exists: .obsidian/graph.json is owned by Obsidian, which can drop the
+// colorGroups wendkeep wrote (vault init'd by an older version, or Obsidian rewriting the
+// file). Without a re-apply path the only fix was a full re-init. This command restores the
+// graph colors without touching anything else.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { getLocale } from '../hooks/locale.mjs';
+import {
+  SNIPPET_NAME,
+  renderColorSnippetCss,
+  mergeAppearance,
+  graphColorGroups,
+  mergeGraphColorGroups,
+} from './vault-theme.mjs';
+
+// { ok, data }. ok=false means the file EXISTS but is unparseable — never clobber it.
+// Absent -> ok=true, data=null (we create it).
+function readJsonSafe(path) {
+  if (!existsSync(path)) return { ok: true, data: null };
+  try { return { ok: true, data: JSON.parse(readFileSync(path, 'utf8')) }; }
+  catch { return { ok: false, data: null }; }
+}
+
+function writeJson(path, obj) {
+  writeFileSync(path, `${JSON.stringify(obj, null, 2)}\n`, 'utf8');
+}
+
+// Pure-ish installer (does file I/O, no process exit). Returns a short summary + counts.
+// Consumed by both `wendkeep init` (installVaultColors) and `wendkeep theme sync`.
+export function syncVaultTheme(vaultPath) {
+  const loc = getLocale(vaultPath);
+  const obsidianDir = join(vaultPath, '.obsidian');
+  const snippetsDir = join(obsidianDir, 'snippets');
+  mkdirSync(snippetsDir, { recursive: true });
+  writeFileSync(join(snippetsDir, `${SNIPPET_NAME}.css`), renderColorSnippetCss(loc), 'utf8');
+
+  let enabled = false;
+  const appPath = join(obsidianDir, 'appearance.json');
+  const appRead = readJsonSafe(appPath);
+  if (appRead.ok) {
+    writeJson(appPath, mergeAppearance(appRead.data || {}, SNIPPET_NAME));
+    enabled = true;
+  }
+
+  let groups = 0;
+  const graphPath = join(obsidianDir, 'graph.json');
+  const graphRead = readJsonSafe(graphPath);
+  if (graphRead.ok) {
+    writeJson(graphPath, mergeGraphColorGroups(graphRead.data || {}, graphColorGroups(loc)));
+    groups = graphColorGroups(loc).length;
+  }
+  return {
+    enabled,
+    groups,
+    summary: `snippet ${SNIPPET_NAME}.css${enabled ? ' (enabled)' : ' (enable by hand: appearance.json unreadable)'} + ${groups} graph group(s)`,
+  };
+}
+
+function resolveVault(argv) {
+  let vault;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--vault') vault = argv[++i];
+    else if (a.startsWith('--vault=')) vault = a.slice(8);
+  }
+  const base = vault || process.env.OBSIDIAN_VAULT_PATH;
+  if (!base) {
+    process.stderr.write('wendkeep theme: no vault. Pass --vault <path> or set OBSIDIAN_VAULT_PATH.\n');
+    process.exit(2);
+  }
+  return isAbsolute(base) ? base : resolve(process.cwd(), base);
+}
+
+export function runTheme(argv) {
+  const [sub, ...rest] = argv;
+  if (sub !== 'sync') {
+    process.stderr.write(`wendkeep theme: unknown subcommand "${sub || ''}". Known: sync.\n`);
+    process.exit(2);
+  }
+  const vaultBase = resolveVault(rest);
+  const r = syncVaultTheme(vaultBase);
+  process.stdout.write(`theme sync: ${r.summary}\n`);
+  process.stdout.write('feche o Obsidian antes de rodar e reabra depois — ele é dono do graph.json e recarrega as cores na abertura.\n');
+  process.exit(0);
+}

package/src/vault-theme.mjs

@@ -8,6 +8,10 @@
 
 export const SNIPPET_NAME = 'wendkeep-colors';
 
+// Readable line width for note content — Obsidian's default (~700px) wastes wide monitors.
+// Ajuste aqui (1200px / 1400px / 100vw) para mudar em todos os vaults de uma vez.
+export const READABLE_LINE_WIDTH = '1400px';
+
 import { LOCALES } from '../hooks/locale.mjs';
 const PT = LOCALES['pt-BR'];
 
@@ -86,6 +90,13 @@ ${rootVars}
 .theme-dark { --us-line-tint: 44%; }
 .theme-light { --us-line-tint: 36%; }
 
+/* --- Readable line width: wider than Obsidian's ~700px default ------------ */
+/* !important porque o Obsidian declara --file-line-width com specificity alta; sem ele
+   a regra do body não vence e a linha volta pro ~700px. */
+body {
+  --file-line-width: ${READABLE_LINE_WIDTH} !important;
+}
+
 /* --- File explorer: accented folders ------------------------------------- */
 ${FX} {
   border-left: 3px solid transparent;

package/src/verify.mjs

@@ -3,7 +3,7 @@
 // the VAULT. Writes 08-Mudanças/<slug>/evidencia.json; exit 1 if a critical sensor is red.
 import { readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
-import { parseTasks, activeChange, appendFixTasks } from '../hooks/change-core.mjs';
+import { parseTasks, activeChange, appendFixTasks, healSpecBacklinks } from '../hooks/change-core.mjs';
 import { loadSensorsDetailed, findProjectRoot, requiredSensors, runSensors, evaluateGate } from '../hooks/sensors-core.mjs';
 import {
   buildEffectiveRequirementPackage,
@@ -41,6 +41,9 @@ export function runVerify(argv) {
   try { tarefas = readFileSync(join(changeDir, 'tarefas.md'), 'utf8'); }
   catch { process.stderr.write(`wendkeep verify: change not found: ${slug}\n`); process.exit(2); }
 
+  // Backlink dos specs escritos à mão pro hub proposta (grafo conectado). Idempotente, fail-quiet.
+  try { healSpecBacklinks(changeDir, vaultBase); } catch { /* heal é bônus */ }
+
   const ids = requiredSensors(parseTasks(tarefas));
   const loaded = loadSensorsDetailed(projectRoot);
   if (loaded.error) {