@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

package/src/lib/worktree/docker-audit.js

@@ -0,0 +1,287 @@
+/**
+ * docker-audit.js — the part of "which worktrees exist" that the filesystem
+ * cannot answer: the docker stacks still running for them.
+ *
+ * `worktree-audit.js` reconciles git's registry, the disk and morph's features.
+ * None of the three can see a CONTAINER. A stack survives everything they look
+ * at: `finish` removes the worktree and the branch, the directory disappears,
+ * git forgets the registration — and `morph-{feature}` keeps running, holding
+ * the feature's whole port block (and its named volumes) against the next
+ * worktree that lands on the same block. The failure surfaces later, somewhere
+ * else, as `port is already allocated` during an `e2e up` that has nothing to
+ * do with the stack that is actually holding the port.
+ *
+ * Two findings, both `severity: 'warn'` — reported, never a failure of
+ * `doctor --worktrees` (`doctor.js` treats `info`/`warn` as non-problems):
+ *
+ *   • docker-stack-orphan — a `morph-*` compose project of THIS repository
+ *     running for a feature this tree does not know
+ *   • docker-port-held    — a port from a feature's allocated block published
+ *     by a container belonging to a DIFFERENT compose project
+ *
+ * This module does not go into `doctor --full`, on purpose (D10): every check
+ * there must be satisfiable in the framework repo itself, and a docker check in
+ * a repo with no compose file could only be permanently yellow. A check that
+ * can never pass where it runs teaches nothing.
+ *
+ * Nothing here mutates anything — not the registry it reads (see
+ * `allocatedFeatures`), and certainly not docker. The `fix` strings name the
+ * destructive command; a human runs it.
+ *
+ * @module lib/worktree/docker-audit
+ */
+
+import { execFileSync } from 'child_process';
+import { resolve } from 'path';
+
+// src/ → framework/hooks/shared/ is the allowed direction (hooks are installed
+// standalone into target projects, where src/ does not exist).
+import {
+  composeProjectName,
+  defaultExec,
+  isDockerAvailable,
+  parseComposePs,
+} from '../../../framework/hooks/shared/e2e-check.js';
+import { allocateEnvBlock, allocatedFeatures, portLayout, resolveFleetConfig } from './env-allocator.js';
+
+/**
+ * The prefix `composeProjectName()` stamps on every stack morph brings up,
+ * derived from the function itself rather than retyped — the string `morph-`
+ * living in two places is how the two stop agreeing.
+ */
+const PROJECT_PROBE = 'probe';
+const MORPH_PROJECT_PREFIX = composeProjectName(PROJECT_PROBE).slice(0, -PROJECT_PROBE.length);
+
+/**
+ * Same fail-open resolution the other callers use: the COMMON git dir is the
+ * one location every linked worktree shares, and it is where the port-block
+ * registry lives.
+ */
+function resolveGitCommonDir(cwd) {
+  try {
+    const common = execFileSync('git', ['rev-parse', '--git-common-dir'], {
+      cwd, stdio: 'pipe', encoding: 'utf-8', windowsHide: true,
+    }).trim();
+    return common ? resolve(cwd, common) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Path comparison that matches the host's own rules. Windows paths differ in
+ * drive-letter case between what git reports and what docker echoes back;
+ * treating those as different paths would make every stack look foreign.
+ */
+const samePathCase = process.platform === 'win32' ? (s) => s.toLowerCase() : (s) => s;
+const norm = (p) => samePathCase(resolve(String(p)).replace(/\\/g, '/'));
+
+/**
+ * Is this compose project OURS to talk about?
+ *
+ * The `morph-` prefix is global to the host, not to a repository: two different
+ * repos that use morph-spec and both have a feature named `triagem` produce the
+ * SAME compose project name. Without this test, `doctor` in repo A would report
+ * repo B's live stack as an orphan and hand the reader a `down -v` — volumes
+ * included — for somebody else's running database. The compose file's path is
+ * what ties a stack to a repository, and it keeps pointing inside the root even
+ * after the worktree directory it named is gone.
+ *
+ * Unattributable (no config file in the listing) counts as NOT ours: an
+ * unknown owner is not evidence of ownership.
+ */
+function belongsToRoot(entry, rootNorm) {
+  const configFiles = String(entry?.ConfigFiles ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+  if (configFiles.length === 0) return false;
+  return configFiles.some((f) => {
+    try {
+      return norm(f).startsWith(`${rootNorm}/`);
+    } catch {
+      return false;
+    }
+  });
+}
+
+/**
+ * Host ports a `docker ps`/`docker compose ps` entry publishes.
+ * Both output shapes are accepted rather than pinning a docker version:
+ * `Ports` as the human string (`0.0.0.0:4002->5432/tcp`) and `Publishers` as
+ * the structured array compose emits.
+ *
+ * @returns {Set<number>}
+ */
+function publishedPorts(entry) {
+  const ports = new Set();
+  for (const pub of Array.isArray(entry?.Publishers) ? entry.Publishers : []) {
+    const p = Number(pub?.PublishedPort);
+    if (Number.isInteger(p) && p > 0) ports.add(p);
+  }
+  const raw = String(entry?.Ports ?? '');
+  for (const m of raw.matchAll(/:(\d{1,5})->/g)) {
+    const p = Number(m[1]);
+    if (Number.isInteger(p) && p > 0) ports.add(p);
+  }
+  return ports;
+}
+
+/** The compose project a container belongs to, from its labels. `null` = unknown. */
+function composeProjectOf(entry) {
+  const labels = String(entry?.Labels ?? '');
+  for (const part of labels.split(',')) {
+    const idx = part.indexOf('=');
+    if (idx < 0) continue;
+    if (part.slice(0, idx).trim() === 'com.docker.compose.project') return part.slice(idx + 1).trim() || null;
+  }
+  return null;
+}
+
+/** Readable container name for a `docker ps` entry (Names may be a list). */
+function containerNameOf(entry) {
+  const names = String(entry?.Names ?? entry?.Name ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+  return names[0] || String(entry?.ID ?? 'container desconhecido');
+}
+
+/**
+ * Parse a docker JSON listing that may be an array or NDJSON.
+ * `null` means the output could not be read — DISTINCT from `[]`, which means
+ * docker answered and there was nothing running. A caller that conflated the
+ * two would turn "could not ask" into "nothing to report", or worse, into a
+ * finding.
+ *
+ * @returns {Array<object>|null}
+ */
+function parseDockerJson(raw) {
+  const text = String(raw ?? '').trim();
+  if (!text) return [];
+  const parsed = parseComposePs(text);
+  if (parsed.length > 0) return parsed;
+  // parseComposePs (the ONE docker-JSON parser in this codebase) collapses two
+  // very different answers into `[]`: "docker listed nothing" and "this is not
+  // JSON". Only a literal empty array is the first one; everything else that
+  // parsed to nothing is garbage, and garbage must not read as "all clear".
+  return /^\[\s*\]$/.test(text) ? [] : null;
+}
+
+/**
+ * Audit the docker stacks around this repository.
+ *
+ * Returns `[]` — asking docker nothing at all — in three situations, and the
+ * silence is the point: this module is loaded by `doctor --worktrees` in every
+ * repo, including ones that never containerize anything.
+ *
+ *   1. no feature ever allocated a port block (no registry): there is no
+ *      isolation contract to compare a running stack against;
+ *   2. the docker CLI is not usable here;
+ *   3. any docker call exits non-zero or answers with something that is not
+ *      JSON — fail-open, the standing rule of this repo's diagnostics.
+ *
+ * `[]` here reads as "nothing to report", not as "unknown": with no docker or
+ * no blocks, nothing CAN be colliding. That is why this is not the `null`-is-
+ * UNKNOWN shape `pr-index.js` uses — there the question stays open, here the
+ * absence is itself the answer.
+ *
+ * @param {string} root - primary root of the repository
+ * @param {object} [opts]
+ * @param {(file: string, args: string[], o?: object) => {code: number, output: string}} [opts.exec]
+ *   injectable executor, exactly like `e2e-check.js` — the CI runners have no
+ *   guaranteed daemon, so every path here must be testable without docker
+ * @param {Iterable<string>} [opts.features] - feature names this tree knows.
+ *   Passed IN rather than re-derived: `auditWorktrees` already read
+ *   `.morph/features/` and `git worktree list`, and two scans of the same fact
+ *   are two chances to disagree about whether a stack is orphaned
+ * @param {string|null} [opts.gitCommonDir]
+ * @returns {Array<{type: string, severity: string, detail: string, fix: string, feature?: string}>}
+ */
+export function auditDockerStacks(root, { exec = defaultExec, features = [], gitCommonDir } = {}) {
+  const commonDir = gitCommonDir === undefined ? resolveGitCommonDir(root) : gitCommonDir;
+  if (!commonDir) return [];
+
+  // (1) No port block was ever allocated → no fleet isolation to protect.
+  const allocated = allocatedFeatures(commonDir);
+  if (allocated.length === 0) return [];
+
+  // (2) No docker → nothing can be holding anything.
+  if (!isDockerAvailable(root, exec)) return [];
+
+  const known = new Set(features);
+  const rootNorm = norm(root);
+  const issues = [];
+
+  // ---- docker-stack-orphan ----------------------------------------------
+  const lsResult = exec('docker', ['compose', 'ls', '--format', 'json'], { cwd: root });
+  if (lsResult.code !== 0) return []; // (3) fail-open
+  const projects = parseDockerJson(lsResult.output);
+  if (projects === null) return []; // (3) unreadable answer is not a finding
+
+  const knownProjects = new Set([...known].map((f) => composeProjectName(f)));
+  for (const entry of projects) {
+    const name = String(entry?.Name ?? '').trim();
+    if (!name.startsWith(MORPH_PROJECT_PREFIX)) continue;
+    if (knownProjects.has(name)) continue;
+    if (!belongsToRoot(entry, rootNorm)) continue;
+
+    const slug = name.slice(MORPH_PROJECT_PREFIX.length);
+    issues.push({
+      type: 'docker-stack-orphan',
+      severity: 'warn',
+      feature: slug || null,
+      detail: `stack docker "${name}" está de pé (${String(entry?.Status ?? 'estado desconhecido')}) e não corresponde a nenhuma feature desta árvore — sobra de outra sessão, segurando o bloco de portas e os volumes de "${slug}"`,
+      // NEVER `morph-spec e2e down {slug}`: that command resolves the feature's
+      // compose file, and this stack's feature no longer exists here. The
+      // project name is the only handle that still works.
+      fix: `docker compose -p ${name} down -v`,
+    });
+  }
+
+  // ---- docker-port-held --------------------------------------------------
+  const psResult = exec('docker', ['ps', '--format', 'json'], { cwd: root });
+  if (psResult.code !== 0) return []; // (3) fail-open
+  const containers = parseDockerJson(psResult.output);
+  if (containers === null) return [];
+
+  const { basePort, blockSize } = resolveFleetConfig(root);
+  for (const feature of allocated) {
+    // A block allocated by a feature this tree does not know belongs to another
+    // worktree of the repo; its collisions are that worktree's to report.
+    if (!known.has(feature)) continue;
+
+    let layout;
+    try {
+      // `allocateEnvBlock` for a feature that is ALREADY in the registry takes
+      // the early-return path and writes nothing. The expected ports are
+      // DERIVED from portLayout — the same function that writes worktree.env
+      // and the compose env — never recomputed here.
+      const block = allocateEnvBlock(feature, { gitCommonDir: commonDir, basePort, blockSize });
+      layout = portLayout(block, { feature });
+    } catch {
+      continue; // block out of range / corrupt entry — nothing to compare
+    }
+
+    const ownProject = layout.COMPOSE_PROJECT_NAME;
+    const expected = new Map();
+    for (const key of ['PORT', 'API_PORT', 'POSTGRES_PORT', 'REDIS_PORT']) {
+      const port = Number(layout[key]);
+      if (Number.isInteger(port)) expected.set(port, key);
+    }
+
+    for (const container of containers) {
+      const project = composeProjectOf(container);
+      if (project === ownProject) continue; // the feature's own stack, as intended
+      for (const port of publishedPorts(container)) {
+        const key = expected.get(port);
+        if (!key) continue;
+        issues.push({
+          type: 'docker-port-held',
+          severity: 'warn',
+          feature,
+          detail: `a porta ${port} (${key} do bloco de "${feature}") está publicada pelo container ${containerNameOf(container)}${project ? ` do projeto compose "${project}"` : ' (sem projeto compose)'}, não por "${ownProject}" — a stack de "${feature}" não sobe enquanto ela estiver presa`,
+          fix: project
+            ? `docker compose -p ${project} down  (ou pare o container ${containerNameOf(container)}) antes de subir a stack de "${feature}"`
+            : `docker stop ${containerNameOf(container)} antes de subir a stack de "${feature}"`,
+        });
+      }
+    }
+  }
+
+  return issues;
+}

package/src/lib/worktree/env-allocator.js

@@ -110,6 +110,30 @@ export function allocateEnvBlock(feature, { gitCommonDir, basePort = DEFAULT_BAS
   return { index, base, range: [base, base + blockSize - 1], created: true };
 }
 
+/**
+ * The features that ALREADY own a block — read-only, allocating nothing.
+ *
+ * `allocateEnvBlock` is the only sanctioned way to get a block, and it WRITES
+ * when the feature has none. A diagnostic that has to ask "who owns a block?"
+ * must not answer by handing one out: `doctor` is read-only, and an audit that
+ * mutates the registry it audits invents the very state it then reports. So
+ * this reader exists to bound the question, and the block itself still comes
+ * from `allocateEnvBlock` (which, for a feature listed here, takes the
+ * early-return path and writes nothing).
+ *
+ * An absent or corrupt registry yields `[]` — "nobody allocated anything",
+ * which for every caller is the same as "nothing to compare against".
+ *
+ * @param {string} gitCommonDir
+ * @returns {string[]} feature names with an allocated block
+ */
+export function allocatedFeatures(gitCommonDir) {
+  const registry = readRegistry(gitCommonDir);
+  return Object.entries(registry.allocations)
+    .filter(([, a]) => Number.isInteger(a?.index))
+    .map(([feature]) => feature);
+}
+
 /**
  * Release a feature's block. Returns false when nothing was allocated.
  *

package/src/lib/worktree/worktree-audit.js

@@ -36,6 +36,7 @@ import {
 import { detectDefaultBranch } from '../git/default-branch.js';
 import { buildPrIndex } from '../git/pr-index.js';
 import { classifyBranch, commitsAhead, resolveBaseRef } from '../git/branch-classifier.js';
+import { auditDockerStacks } from './docker-audit.js';
 
 const norm = (p) => resolve(p).replace(/\\/g, '/');
 
@@ -212,10 +213,24 @@ function dirsOnDisk(root) {
  *                                 directory that exists but git's own
  *                                 registry does not know as a worktree
  *
+ *   • docker-stack-orphan (warn) — a `morph-*` docker stack of this repository
+ *                                 still running for a feature this tree does
+ *                                 not know, and
+ *   • docker-port-held (warn)    — a port from a feature's block published by
+ *                                 another compose project. Both come from
+ *                                 `docker-audit.js`: the three sources above
+ *                                 cannot see a CONTAINER, and a stack outlives
+ *                                 every one of them
+ *
  * @param {string} [cwd]
+ * @param {object} [opts]
+ * @param {Function} [opts.exec] - injectable executor handed to the docker
+ *   audit, so the docker paths are testable with no daemon (the CI runners
+ *   have none). Absent, the real `docker` CLI is used — and answers `[]` when
+ *   it is not installed.
  * @returns {Array<{ type: string, detail: string, path?: string, feature?: string, fix: string }>}
  */
-export function auditWorktrees(cwd = process.cwd()) {
+export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
   if (!isGitRepo(cwd)) return [];
   const root = resolvePrimaryRoot(cwd);
   const rootNorm = norm(root);
@@ -394,6 +409,20 @@ export function auditWorktrees(cwd = process.cwd()) {
     }
   }
 
+  // The fourth source, and the only one that is not a file: the docker stacks.
+  // A container survives the removal of the worktree, of the branch and of the
+  // feature — none of the three reconciliations above can see it, and it keeps
+  // holding the feature's port block. The feature names come from HERE (the
+  // ones morph knows plus the ones the registered `morph/*` worktrees carry)
+  // rather than from a second scan inside docker-audit: two readings of the
+  // same fact are two chances to disagree about which stack is orphaned.
+  const treeFeatures = new Set(features);
+  for (const entry of registered) {
+    const f = entry.branch?.match(/^refs\/heads\/morph\/(.+)$/)?.[1];
+    if (f) treeFeatures.add(f);
+  }
+  issues.push(...auditDockerStacks(root, { exec, features: treeFeatures }));
+
   return issues;
 }
 

package/src/scripts/setup-infra.js

@@ -14,7 +14,7 @@
 import { join, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
-import { readFileSync, readdirSync, copyFileSync, unlinkSync } from 'fs';
+import { readFileSync, readdirSync } from 'fs';
 import {
   copyDirectory,
   copyFile,
@@ -33,6 +33,7 @@ import { installSkills } from '../utils/skills-installer.js';
 import { installAgents, installDomainAgents } from '../utils/agents-installer.js';
 import { resolvePrimaryRoot } from '../commands/project/worktree.js';
 import { reconcileLegacyTemplatesCopy } from '../lib/installers/templates-reconcile.js';
+import { realEffects } from '../lib/installers/effects.js';
 
 const FRAMEWORK_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'framework');
 
@@ -61,7 +62,7 @@ async function installRequiredPlugins(log, exec) {
  * @param {string} rulesDest - Destination rules directory (.claude/rules/)
  * @param {string[]} projectTags - Stack tags from config (e.g., ['dotnet', 'blazor'])
  */
-export function installRulesForStack(rulesSrc, rulesDest, projectTags) {
+export function installRulesForStack(rulesSrc, rulesDest, projectTags, fx = realEffects()) {
   const sourceFiles = readdirSync(rulesSrc).filter(f => f.endsWith('.md'));
   const installed = new Set();
 
@@ -69,15 +70,19 @@ export function installRulesForStack(rulesSrc, rulesDest, projectTags) {
     const content = readFileSync(join(rulesSrc, file), 'utf-8');
     const stacks = parseStacks(content);
     if (shouldInstall(stacks, projectTags)) {
-      copyFileSync(join(rulesSrc, file), join(rulesDest, file));
+      fx.copyFile(join(rulesSrc, file), join(rulesDest, file));
       installed.add(file);
     }
   }
 
-  // Cleanup orphans
-  for (const file of readdirSync(rulesDest).filter(f => f.endsWith('.md'))) {
-    if (!installed.has(file)) {
-      unlinkSync(join(rulesDest, file));
+  // Cleanup orphans — calado em `dryRun` pelo mesmo motivo dos laços gêmeos em
+  // skills-installer.js e agents-installer.js (D6): `cleanFrameworkDirs()` já
+  // apagou `.claude/rules/` inteiro antes de este código rodar de verdade.
+  if (!fx.dryRun) {
+    for (const file of readdirSync(rulesDest).filter(f => f.endsWith('.md'))) {
+      if (!installed.has(file)) {
+        fx.remove(join(rulesDest, file));
+      }
     }
   }
 
@@ -134,12 +139,20 @@ async function installStackAwareAssets(targetPath, log) {
  *
  * @param {string} claudeMdPath - Absolute path to the installed .claude/CLAUDE.md
  * @param {Array<{ name: string, title: string, domains: string[] }>} agents
+ * @param {object} [options]
+ * @param {ReturnType<import('../lib/installers/effects.js').createEffects>} [options.fx]
+ * @param {string} [options.readFrom] - De onde LER o conteúdo-base.
+ *   Num `--dry-run` o arquivo de destino ainda não recebeu a cópia que o passo
+ *   anterior previu, então ler o destino diria "sem marcadores" e o efeito de
+ *   escrita sumiria da previsão — divergindo da execução real. Lendo a MESMA
+ *   origem que seria copiada, previsão e execução decidem igual.
  */
-export async function updateClaudeMdAgentsBlock(claudeMdPath, agents = []) {
-  if (!(await pathExists(claudeMdPath))) return;
+export async function updateClaudeMdAgentsBlock(claudeMdPath, agents = [], options = {}) {
+  const { fx = realEffects(), readFrom = claudeMdPath } = options;
+  if (!(await pathExists(readFrom))) return;
   const START = '<!-- morph-agents:start -->';
   const END = '<!-- morph-agents:end -->';
-  const content = readFileSync(claudeMdPath, 'utf-8');
+  const content = readFileSync(readFrom, 'utf-8');
   if (!content.includes(START) || !content.includes(END)) return;
 
   const list = agents.length > 0
@@ -151,7 +164,7 @@ export async function updateClaudeMdAgentsBlock(claudeMdPath, agents = []) {
     new RegExp(`${START}[\\s\\S]*?${END}`),
     block
   );
-  await writeFile(claudeMdPath, updated);
+  fx.writeFile(claudeMdPath, updated);
 }
 
 /**

package/src/utils/agent-id-mapper.js

@@ -1,11 +1,11 @@
-/**
- * Map an agents.json ID to the Claude Code subagent_type.
- *
- * @param {string} id - Agent ID from agents.json (e.g., "nextjs-expert")
- * @param {number} [tier] - Agent tier (1-4). Defaults to non-validator.
- * @returns {string} subagent_type matching .claude/agents/ filename stem
- */
-export function agentIdToSubagentType(id, tier) {
-  const prefix = tier === 4 ? 'morph-validator-' : 'morph-';
-  return `${prefix}${id}`;
-}
+/**
+ * Map an agents.json ID to the Claude Code subagent_type.
+ *
+ * @param {string} id - Agent ID from agents.json (e.g., "nextjs-expert")
+ * @param {number} [tier] - Agent tier (1-4). Defaults to non-validator.
+ * @returns {string} subagent_type matching .claude/agents/ filename stem
+ */
+export function agentIdToSubagentType(id, tier) {
+  const prefix = tier === 4 ? 'morph-validator-' : 'morph-';
+  return `${prefix}${id}`;
+}

package/src/utils/agents-installer.js

@@ -21,9 +21,10 @@
  * Evaluator) are assumed by Claude itself per MORPH.md, not as separate agents.
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, unlinkSync } from 'node:fs';
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { join } from 'path';
 import { shouldInstall } from '../lib/stack-filter.js';
+import { realEffects } from '../lib/installers/effects.js';
 
 /** Default tool scope for domain personas (override per agent via agents.json `tools`). */
 export const DEFAULT_AGENT_TOOLS = 'Read, Write, Edit, Bash, Glob, Grep';
@@ -79,10 +80,12 @@ const MANAGED_HEADER =
  * @param {string} frameworkDir - Path to morph-spec framework/ directory
  * @param {object} options
  * @param {string[]} [options.projectTags=[]] - Stack tags from config (e.g. ['dotnet', 'nextjs'])
+ * @param {ReturnType<import('../lib/installers/effects.js').createEffects>} [options.fx]
+ *   Coletor de efeitos; o default executa e registra numa lista descartada.
  * @returns {Promise<{ installed: number }>}
  */
 export async function installAgents(projectDir, frameworkDir = 'framework', options = {}) {
-  const { projectTags = [] } = options;
+  const { projectTags = [], fx = realEffects() } = options;
 
   const agentsJsonPath = join(frameworkDir, 'agents.json');
   const agentsJson = JSON.parse(readFileSync(agentsJsonPath, 'utf-8'));
@@ -93,7 +96,7 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
     .map(([id, data]) => ({ id, ...data }));
 
   const targetDir = join(projectDir, '.claude', 'agents');
-  mkdirSync(targetDir, { recursive: true });
+  fx.ensureDir(targetDir);
 
   const knownMcpIds = loadKnownMcpIds(frameworkDir);
 
@@ -111,7 +114,7 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
     const filename = `morph-${agent.id}.md`;
     const targetPath = join(targetDir, filename);
 
-    writeFileSync(targetPath, renderAgentMd(agent, knownMcpIds), 'utf-8');
+    fx.writeFile(targetPath, renderAgentMd(agent, knownMcpIds));
     installedFilenames.add(filename);
     installedAgents.push({
       id: agent.id,
@@ -122,10 +125,17 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
     installed++;
   }
 
-  // Cleanup orphan morph-* files filtered out by stack
-  for (const file of readdirSync(targetDir)) {
-    if (allPossible.has(file) && !installedFilenames.has(file)) {
-      unlinkSync(join(targetDir, file));
+  // Cleanup orphan morph-* files filtered out by stack.
+  //
+  // Calado em `dryRun` pelo mesmo motivo do laço gêmeo em skills-installer.js
+  // (D6): numa execução real do `update` este diretório acabou de ser apagado
+  // inteiro por `cleanFrameworkDirs()`, então o laço nunca remove nada. Num
+  // dry ingênuo ele veria o diretório antigo e preveria remoções inexistentes.
+  if (!fx.dryRun) {
+    for (const file of readdirSync(targetDir)) {
+      if (allPossible.has(file) && !installedFilenames.has(file)) {
+        fx.remove(join(targetDir, file));
+      }
     }
   }
 

package/src/utils/claude-md-injector.js

@@ -8,7 +8,8 @@
  * The root CLAUDE.md belongs to the USER — morph-spec only adds its import.
  */
 
-import { pathExists, readFile, writeFile } from './file-copier.js';
+import { pathExists, readFile } from './file-copier.js';
+import { realEffects } from '../lib/installers/effects.js';
 
 const MORPH_IMPORT = '@.claude/CLAUDE.md';
 const MORPH_MARKER = 'MORPH-SPEC';
@@ -24,11 +25,15 @@ const MORPH_MARKER = 'MORPH-SPEC';
  * Idempotent — does nothing if the import already exists.
  *
  * @param {string} claudeMdPath - Absolute path to root CLAUDE.md
+ * @param {ReturnType<import('../lib/installers/effects.js').createEffects>} [fx]
+ *   Coletor de efeitos; o default executa e registra numa lista descartada.
+ *   A DECISÃO (criar / migrar / anexar / nada) sai de uma LEITURA, que
+ *   acontece igual nos dois modos — por isso previsão e execução concordam.
  * @returns {Promise<'created'|'migrated'|'injected'|'already-present'>}
  */
-export async function injectMorphImport(claudeMdPath) {
+export async function injectMorphImport(claudeMdPath, fx = realEffects()) {
   if (!await pathExists(claudeMdPath)) {
-    await writeFile(claudeMdPath, `# Project\n\n${MORPH_IMPORT}\n`);
+    fx.writeFile(claudeMdPath, `# Project\n\n${MORPH_IMPORT}\n`);
     return 'created';
   }
 
@@ -39,13 +44,13 @@ export async function injectMorphImport(claudeMdPath) {
   }
 
   if (isMorphOnly(content)) {
-    await writeFile(claudeMdPath, `# Project\n\n${MORPH_IMPORT}\n`);
+    fx.writeFile(claudeMdPath, `# Project\n\n${MORPH_IMPORT}\n`);
     return 'migrated';
   }
 
   // User has their own content — append the import section
   const separator = content.endsWith('\n') ? '\n' : '\n\n';
-  await writeFile(claudeMdPath, `${content}${separator}## MORPH-SPEC\n\n${MORPH_IMPORT}\n`);
+  fx.writeFile(claudeMdPath, `${content}${separator}## MORPH-SPEC\n\n${MORPH_IMPORT}\n`);
   return 'injected';
 }