@polymorphism-tech/morph-spec 8.41.0 → 8.43.0

package/src/lib/validators/verify-runner.js

@@ -47,6 +47,7 @@ import { runValidation } from './validation-runner.js';
 import { loadRubric, aggregateScores } from './score-aggregator.js';
 import { checkOutputsTraceability } from './traceability-check.js';
 import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
+import { createHeavyGate } from '../heavy/gate.js';
 
 /** Default build timeout — dotnet cold build is slow; 30s (the Stop-hook default) is too short. */
 const DEFAULT_BUILD_TIMEOUT = 120_000;
@@ -105,9 +106,20 @@ export class VerifyUsageError extends Error {
  * @param {Function} [options._runValidation] - Injectable override for runValidation (testing)
  * @param {Function} [options._runE2eCheck] - Injectable override for runE2eCheck (testing)
  * @param {Function} [options._checkOutputsTraceability] - Injectable override for checkOutputsTraceability (testing)
+ * @param {Object} [options._heavyGate] - Injectable heavy-slot gate (testing); default is one per run
  * @returns {Promise<Object>} Aggregated verify result — see module docs for shape
+ * @throws {HeavyBusyError} when no heavy slot (or RAM) freed within `heavy.waitTimeoutSec`
  */
 export async function runVerify(projectPath, featureName, taskId, options = {}) {
+  const gate = options._heavyGate ?? createHeavyGate({ projectPath, feature: featureName });
+  try {
+    return await runVerifyGated(projectPath, featureName, taskId, options, gate);
+  } finally {
+    gate.release();
+  }
+}
+
+async function runVerifyGated(projectPath, featureName, taskId, options, gate) {
   const {
     rubric: rubricOverride,
     timeout = DEFAULT_BUILD_TIMEOUT,
@@ -209,7 +221,7 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
   const feedback = [];
 
   // 1. build
-  nodes.build = await runBuildNode({ projectPath, stack, paths, timeout, skipBuild, _runBuildCheck });
+  nodes.build = await runBuildNode({ projectPath, stack, paths, timeout, skipBuild, gate, _runBuildCheck });
   appendBuildFeedback(feedback, nodes.build);
 
   // 2. tests — skipped entirely (no invocation) when build already failed.
@@ -229,6 +241,7 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
     refreshCache,
     linux,
     linuxImage,
+    gate,
     _runTestSuite,
     _runLinuxSuite,
     _exec,
@@ -255,6 +268,7 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
     skipE2e,
     freshE2e,
     buildNode: nodes.build,
+    gate,
     _runE2eCheck,
   });
   appendE2eFeedback(feedback, nodes.e2e);
@@ -297,7 +311,7 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
 // Build node
 // ============================================================================
 
-async function runBuildNode({ projectPath, stack, paths = {}, timeout, skipBuild, _runBuildCheck }) {
+async function runBuildNode({ projectPath, stack, paths = {}, timeout, skipBuild, gate, _runBuildCheck }) {
   if (skipBuild) {
     return { status: 'skip', command: null, durationMs: 0, reason: 'requested', output: '' };
   }
@@ -309,6 +323,7 @@ async function runBuildNode({ projectPath, stack, paths = {}, timeout, skipBuild
   }
   const command = steps.map((s) => s.command).join(' && ');
 
+  gate.enter('build');
   const start = Date.now();
   const result = await _runBuildCheck(projectPath, stack, timeout, paths);
   const durationMs = Date.now() - start;
@@ -352,7 +367,7 @@ function appendBuildFeedback(feedback, buildNode) {
  */
 async function runTestsNode({
   projectPath, testPlan, filter, skipTests, buildNode, timeout, taskId, refreshCache = false,
-  linux = false, linuxImage = null, _runTestSuite, _runLinuxSuite = runLinuxSuite, _exec,
+  linux = false, linuxImage = null, gate, _runTestSuite, _runLinuxSuite = runLinuxSuite, _exec,
 }) {
   const { nodes, source } = testPlan;
   // Kept readable for whoever only prints the string — the same join the
@@ -372,7 +387,7 @@ async function runTestsNode({
 
   if (linux) {
     const { runs, environment } = await runNodesInLinux({
-      projectPath, nodes, filter, taskId, timeout, linuxImage, _runLinuxSuite, _exec,
+      projectPath, nodes, filter, taskId, timeout, linuxImage, gate, _runLinuxSuite, _exec,
     });
     return rollUpTestRuns(runs, { command, source, environment });
   }
@@ -380,7 +395,7 @@ async function runTestsNode({
   const runs = [];
   for (const node of nodes) {
     runs.push(await runOneTestNode({
-      projectPath, node, filter, taskId, timeout, refreshCache, _runTestSuite,
+      projectPath, node, filter, taskId, timeout, refreshCache, gate, _runTestSuite,
     }));
   }
 
@@ -403,7 +418,7 @@ async function runTestsNode({
  * bind mount: see linux-runner.js. That is the whole reason this path exists.
  */
 async function runNodesInLinux({
-  projectPath, nodes, filter, taskId, timeout, linuxImage, _runLinuxSuite, _exec,
+  projectPath, nodes, filter, taskId, timeout, linuxImage, gate, _runLinuxSuite, _exec,
 }) {
   const decided = new Map();
   const toRun = [];
@@ -419,6 +434,7 @@ async function runNodesInLinux({
     (sum, node) => sum + resolveTestTimeout(projectPath, node, timeout), 0
   ) || undefined;
 
+  if (toRun.length > 0) gate.enter('tests');
   const suite = await _runLinuxSuite({
     projectPath,
     nodes: toRun,
@@ -458,7 +474,7 @@ async function runNodesInLinux({
  * from the report is the defect this whole feature exists to close.
  */
 async function runOneTestNode({
-  projectPath, node, filter, taskId, timeout, refreshCache = false, _runTestSuite,
+  projectPath, node, filter, taskId, timeout, refreshCache = false, gate, _runTestSuite,
 }) {
   const decided = preDecideRun({ node, filter, taskId, projectPath, refreshCache });
   if (decided) return decided;
@@ -476,6 +492,7 @@ async function runOneTestNode({
   // wrote nothing the old scenario count — and hiding an empty run behind it.
   if (evalChannel) discardFile(evalChannel.summaryPath);
 
+  gate.enter('tests');
   const start = Date.now();
   const result = await _runTestSuite(projectPath, {
     timeout, node, ...(evalChannel ? { env: evalChannel.env } : {}),
@@ -1027,7 +1044,7 @@ function appendValidatorsFeedback(feedback, validatorsNode) {
 // E2E node
 // ============================================================================
 
-async function runE2eNode({ projectPath, featureName, taskId, task = null, skipE2e, freshE2e, buildNode, _runE2eCheck }) {
+async function runE2eNode({ projectPath, featureName, taskId, task = null, skipE2e, freshE2e, buildNode, gate, _runE2eCheck }) {
   if (buildNode.status === 'fail') {
     return {
       status: 'skip',
@@ -1056,6 +1073,7 @@ async function runE2eNode({ projectPath, featureName, taskId, task = null, skipE
     env: buildComposeEnv({ cwd: projectPath, config, featureName, gitCommonDir }),
     skipRequested: skipE2e,
     forceFresh: freshE2e,
+    beforeHeavy: () => gate.enter('e2e'),
     // The stack stays up between verifies on purpose: cold-starting a .NET
     // container per task is the difference between a usable loop and one
     // nobody runs. `morph-spec e2e down` (and `finish`) tear it down.

package/src/lib/worktree/agent-reaper.js

@@ -0,0 +1,247 @@
+import { execFileSync } from 'node:child_process';
+import {
+  closeSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, statSync, unlinkSync, writeFileSync,
+} from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import {
+  cwdIsInsideWorktree, isGitRepo, parseWorktreeList, resolvePrimaryRoot, runWorktreeRemove,
+  sessionAnchoredInWorktree,
+} from '../../commands/project/worktree.js';
+import { containerDirs, isUnder } from '../../../framework/hooks/shared/worktree-root.js';
+import { withoutLeftoverIgnore } from '../../../framework/hooks/shared/graph-freshness.js';
+import { resolveGitCommonDir } from '../../../framework/hooks/shared/git-paths.js';
+import { pidAlive } from '../../../framework/hooks/shared/process-alive.js';
+import { readProjectConfig } from '../../../framework/hooks/shared/heavy-config.js';
+
+export const DEFAULT_GRACE_MINUTES = 30;
+
+const AGENT_DIR = /^agent-([0-9a-f]+)$/;
+const AGENT_BRANCH = /^morph-task\/agent-([0-9a-f]+)$/;
+const AGENT_REF = /^refs\/heads\/morph-task\/agent-[0-9a-f]+$/;
+const TAIL_BYTES = 64 * 1024;
+const LOCK_MAX_AGE_MS = 15 * 60_000;
+const SAMPLE = 5;
+
+const norm = (p) => resolve(p).replace(/\\/g, '/');
+const gitOut = (cwd, args, input) => execFileSync('git', args, {
+  cwd, stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf8', input,
+});
+const sample = (list) => `${list.slice(0, SAMPLE).join(', ')}${list.length > SAMPLE ? `, +${list.length - SAMPLE}` : ''}`;
+
+export function resolveGraceMinutes(root, override) {
+  const valid = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0;
+  if (valid(override)) return override;
+  const configured = readProjectConfig(root)?.worktree?.reap?.graceMinutes;
+  return valid(configured) ? configured : DEFAULT_GRACE_MINUTES;
+}
+
+/**
+ * Commits reachable from `tip` and from no other branch, remote or tag; agent branches are left out
+ * of the comparison, and `--all` is not used (the agent's own HEAD would protect it). `null` = unmeasured.
+ */
+export function exclusiveCommitCount(root, tip) {
+  if (!tip) return null;
+  try {
+    const refs = gitOut(root, ['for-each-ref', '--format=%(refname)', 'refs/heads', 'refs/remotes', 'refs/tags'])
+      .split(/\r?\n/).filter((r) => r && !AGENT_REF.test(r));
+    const input = `${[tip, ...refs.map((r) => `^${r}`)].join('\n')}\n`;
+    const count = Number.parseInt(gitOut(root, ['rev-list', '--count', '--stdin'], input).trim(), 10);
+    return Number.isInteger(count) ? count : null;
+  } catch {
+    return null;
+  }
+}
+
+function tailOfEvents(file) {
+  const fd = openSync(file, 'r');
+  try {
+    const { size, mtimeMs } = fstatSync(fd);
+    const len = Math.min(size, TAIL_BYTES);
+    const buf = Buffer.alloc(len);
+    readSync(fd, buf, 0, len, size - len);
+    const lines = buf.toString('utf8').split(/\r?\n/).filter((l) => l.trim());
+    if (size > len) lines.shift();
+    return { last: lines.at(-1) ?? null, mtimeMs };
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** `stopped` only when the tree's last event is this agent's own `AgentUsage`. */
+export function readAgentStop(worktreePath, hex) {
+  const file = join(worktreePath, '.morph', 'logs', 'events.jsonl');
+  if (!existsSync(file)) return { status: 'unknown', detail: 'sem .morph/logs/events.jsonl na árvore' };
+  let tail;
+  try { tail = tailOfEvents(file); } catch { return { status: 'unknown', detail: 'events.jsonl ilegível' }; }
+  let event = null;
+  try { event = tail.last ? JSON.parse(tail.last) : null; } catch { event = null; }
+  if (!event || typeof event !== 'object') return { status: 'unknown', detail: 'último evento ilegível' };
+  if (event.event !== 'AgentUsage') return { status: 'active', detail: `último evento: ${event.event ?? '?'}` };
+  if (String(event.agentId ?? '').toLowerCase() !== hex) return { status: 'unknown', detail: 'AgentUsage de outro agente' };
+  return { status: 'stopped', mtimeMs: tail.mtimeMs };
+}
+
+function dirtOf(worktreePath) {
+  try {
+    const lines = gitOut(worktreePath, ['status', '--porcelain', '--untracked-files=all']).split(/\r?\n/).filter((l) => l.trim());
+    return withoutLeftoverIgnore(worktreePath, lines).map((l) => (l.startsWith('??') ? `untracked ${l.slice(3)}` : l.slice(3)));
+  } catch {
+    return null;
+  }
+}
+
+function agentBranches(root) {
+  try {
+    return gitOut(root, ['for-each-ref', '--format=%(refname:short) %(objectname)', 'refs/heads/morph-task/'])
+      .split(/\r?\n/).filter(Boolean)
+      .map((line) => { const [name, sha] = line.split(' '); return { name, sha, hex: AGENT_BRANCH.exec(name)?.[1] }; })
+      .filter((b) => b.hex);
+  } catch {
+    return [];
+  }
+}
+
+function branchTouchedMs(root, branch) {
+  const common = resolveGitCommonDir(root);
+  if (!common) return null;
+  try { return statSync(join(common, 'logs', 'refs', 'heads', ...branch.split('/'))).mtimeMs; } catch { return null; }
+}
+
+function agentWorktrees(root) {
+  const rootNorm = norm(root);
+  const containers = containerDirs(root);
+  return parseWorktreeList(root).flatMap((e) => {
+    const path = norm(e.path);
+    const hex = AGENT_DIR.exec(basename(path))?.[1];
+    if (!hex || path === rootNorm) return [];
+    if (!isUnder(containers, path)) return [];
+    const branch = e.branch ? e.branch.replace(/^refs\/heads\//, '') : null;
+    if (branch && branch !== `morph-task/agent-${hex}`) return [];
+    return [{ path, hex, branch, tip: e.head, locked: e.locked }];
+  });
+}
+
+function judgeWorktree(item, ctx) {
+  const keep = (state, reason, detail) => ({ ...item, state, reason, detail });
+  if (!existsSync(item.path)) return keep('preserved', 'directory-missing', 'o diretório sumiu; `morph-spec doctor --worktrees --prune` limpa o registro');
+  if (cwdIsInsideWorktree(ctx.cwd, item.path) || sessionAnchoredInWorktree(item.path, ctx.env)) return keep('active', 'anchored');
+  if (item.locked) return keep('preserved', 'locked', '`git worktree unlock` libera, se o lock já não vale');
+
+  const stop = readAgentStop(item.path, item.hex);
+  if (stop.status === 'active') return keep('active', 'agent-active', stop.detail);
+  if (stop.status !== 'stopped') return keep('preserved', 'no-usage-event', stop.detail);
+  const idleMin = (ctx.now - stop.mtimeMs) / 60_000;
+  if (idleMin < ctx.graceMinutes) return keep('pending', 'within-grace', `parou há ${Math.floor(idleMin)} min (graça de ${ctx.graceMinutes} min)`);
+
+  const dirt = dirtOf(item.path);
+  if (dirt === null) return keep('preserved', 'unknown', 'git status falhou');
+  if (dirt.length) return keep('preserved', 'dirty', sample(dirt));
+
+  const exclusive = exclusiveCommitCount(ctx.root, item.tip);
+  if (exclusive === null) return keep('preserved', 'unknown', 'não foi possível contar os commits exclusivos');
+  if (exclusive > 0) return keep('preserved', 'exclusive-commits', `${exclusive} commit(s) só nesta branch`);
+  return keep('reapable', 'stopped-clean');
+}
+
+function judgeOrphanBranch(branch, ctx) {
+  const item = { path: null, hex: branch.hex, branch: branch.name, tip: branch.sha };
+  const keep = (state, reason, detail) => ({ ...item, state, reason, detail });
+  const exclusive = exclusiveCommitCount(ctx.root, branch.sha);
+  if (exclusive === null) return keep('preserved', 'unknown', 'não foi possível contar os commits exclusivos');
+  if (exclusive > 0) return keep('preserved', 'exclusive-commits', `${exclusive} commit(s) só nesta branch`);
+  const touched = branchTouchedMs(ctx.root, branch.name);
+  if (touched === null) return keep('preserved', 'unknown', 'sem reflog para medir a idade da branch');
+  const idleMin = (ctx.now - touched) / 60_000;
+  if (idleMin < ctx.graceMinutes) return keep('pending', 'within-grace', `branch tocada há ${Math.floor(idleMin)} min (graça de ${ctx.graceMinutes} min)`);
+  return keep('reapable', 'orphan-branch');
+}
+
+/** Read-only: every agent tree and orphan agent branch with its verdict. */
+export function planAgentReap(root, { cwd = root, now = Date.now(), graceMinutes, env = process.env } = {}) {
+  const ctx = { root, cwd, now, env, graceMinutes: resolveGraceMinutes(root, graceMinutes) };
+  const trees = agentWorktrees(root);
+  const withTree = new Set(trees.map((t) => t.branch).filter(Boolean));
+  const orphans = agentBranches(root).filter((b) => !withTree.has(b.name));
+  const items = [...trees.map((t) => judgeWorktree(t, ctx)), ...orphans.map((b) => judgeOrphanBranch(b, ctx))];
+  return { graceMinutes: ctx.graceMinutes, items };
+}
+
+function acquireReapLock(root, now) {
+  const common = resolveGitCommonDir(root);
+  if (!common) return null;
+  const dir = join(common, 'morph-spec');
+  const file = join(dir, 'agent-reap.lock');
+  try { mkdirSync(dir, { recursive: true }); } catch { return null; }
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      writeFileSync(file, JSON.stringify({ pid: process.pid, since: now }), { flag: 'wx' });
+      return () => { try { unlinkSync(file); } catch { /* already gone */ } };
+    } catch (err) {
+      if (err.code !== 'EEXIST') return null;
+    }
+    let holder = null;
+    try { holder = JSON.parse(readFileSync(file, 'utf8')); } catch { holder = null; }
+    const stale = !holder || !pidAlive(holder.pid) || now - Number(holder.since) > LOCK_MAX_AGE_MS;
+    if (!stale) return null;
+    try { unlinkSync(file); } catch { return null; }
+  }
+  return null;
+}
+
+function deleteAgentBranch(root, branch, sha) {
+  if (exclusiveCommitCount(root, sha) !== 0) return false;
+  try { gitOut(root, ['branch', '-D', branch]); return true; } catch { return false; }
+}
+
+const brief = ({ path, branch, hex }) => ({ path, branch, hex });
+const why = ({ path, branch, hex, reason, detail }) => ({ path, branch, hex, reason, ...(detail ? { detail } : {}) });
+
+/**
+ * Removes the worktrees and branches of stopped, clean agents that hold no commit only they have;
+ * everything else is listed with the reason and left alone.
+ */
+export async function reapAgentWorktrees(cwd = process.cwd(), {
+  dryRun = false, graceMinutes, now = Date.now, env = process.env, remove = runWorktreeRemove,
+} = {}) {
+  if (!isGitRepo(cwd)) return { ok: false, error: 'not-a-git-repo', dryRun };
+  const root = resolvePrimaryRoot(cwd);
+  const summarize = (plan, extra = {}) => {
+    const of = (state) => plan.items.filter((i) => i.state === state);
+    return {
+      ok: true, dryRun, graceMinutes: plan.graceMinutes,
+      reaped: [], branchesDeleted: [],
+      ...(dryRun ? { wouldReap: of('reapable').map(brief) } : {}),
+      preserved: [...of('preserved'), ...of('pending')].map(why),
+      active: of('active').length,
+      ...extra,
+    };
+  };
+
+  if (dryRun) return summarize(planAgentReap(root, { cwd, now: now(), graceMinutes, env }));
+
+  const release = acquireReapLock(root, now());
+  if (!release) return { ...summarize({ graceMinutes: resolveGraceMinutes(root, graceMinutes), items: [] }), busy: true };
+  try {
+    const plan = planAgentReap(root, { cwd, now: now(), graceMinutes, env });
+    const out = summarize(plan);
+    for (const item of plan.items.filter((i) => i.state === 'reapable')) {
+      if (item.path) {
+        const { out: removal } = await remove(null, { target: item.path, ifClean: true, relinkOnFailure: true, cwd: root });
+        if (!removal.removed) {
+          out.preserved.push(why({ ...item, reason: 'remove-failed', detail: removal.hint || removal.error }));
+          continue;
+        }
+        out.reaped.push({ ...brief(item), ...(removal.ignoredBackup ? { backup: removal.ignoredBackup } : {}) });
+        if (item.branch && deleteAgentBranch(root, item.branch, item.tip)) out.branchesDeleted.push(item.branch);
+      } else if (deleteAgentBranch(root, item.branch, item.tip)) {
+        out.branchesDeleted.push(item.branch);
+        out.reaped.push(brief(item));
+      } else {
+        out.preserved.push(why({ ...item, reason: 'unknown', detail: 'a branch mudou antes de ser apagada' }));
+      }
+    }
+    return out;
+  } finally {
+    release();
+  }
+}

package/src/lib/worktree/dirs.js

@@ -1,32 +1,3 @@
-/**
- * dirs.js — the ONE place the worktree container directory is named.
- *
- * Every reader that resolves worktrees BY CONVENTION (test discovery, graph
- * ignore list, the installed .gitignore, the architecture scanner, the
- * dashboard scanner) imports from here. Duplicating the string is how the
- * C1 bug comes back: a reader keeps the old name and silently goes blind.
- *
- * Readers that go through `git worktree list` (fleet, finish, worktree list)
- * never depended on this — git records absolute paths.
- */
-
-/**
- * The directory new worktrees are created under, relative to the primary root.
- *
- * NO leading dot, deliberately (C1). Jest escapes the `.` when it interpolates
- * an absolute `rootDir` into the `testMatch` glob, so `<root>/.worktrees/...`
- * stops matching and an entire frontend suite reports **0 tests without an
- * error** — the suite "passes" having tested nothing. The dot bought nothing:
- * the directory is gitignored either way.
- */
-export const WORKTREES_DIR = 'worktrees';
-
-/**
- * The pre-C1 directory name. New worktrees never land here, but every reader
- * that resolves worktrees BY CONVENTION must still accept it, so a machine
- * that already had `.worktrees/{f}` keeps working with no manual migration.
- */
-export const LEGACY_WORKTREES_DIR = '.worktrees';
-
-/** Both names, new first — the read order for convention-based lookups. */
-export const WORKTREE_DIR_NAMES = [WORKTREES_DIR, LEGACY_WORKTREES_DIR];
+// The names live in framework/hooks/shared/worktree-root.js (a hook cannot import `src/`, and the
+// `worktree.root` resolver needs them); every convention-based reader still imports them from here.
+export { WORKTREES_DIR, LEGACY_WORKTREES_DIR, WORKTREE_DIR_NAMES } from '../../../framework/hooks/shared/worktree-root.js';

package/src/lib/worktree/vscode-settings.js

@@ -0,0 +1,113 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { jsoncToJson, stripComments } from '../../../framework/hooks/shared/comment-stripper.js';
+import { ensureCommonExclude } from '../../../framework/hooks/shared/git-exclude.js';
+import { readProjectConfig } from '../../../framework/hooks/shared/heavy-config.js';
+import { getProjectTags } from '../stack-filter.js';
+import { realEffects } from '../installers/effects.js';
+import { WORKTREE_DIR_NAMES } from './dirs.js';
+
+const SETTINGS_REL = join('.vscode', 'settings.json');
+const EXCLUDE_MARKER = '# morph-spec: editor settings';
+const DEFAULT_INDENT = '    ';
+const DOTNET_ROOT_FILE = /\.(sln|slnx|csproj)$/i;
+
+const isDotnet = (root, config) => getProjectTags(config).includes('dotnet')
+  || (() => { try { return readdirSync(root).some((n) => DOTNET_ROOT_FILE.test(n)); } catch { return false; } })();
+
+/** Globs per settings key. `bin/obj` leave `files.exclude` outside .NET: a JS `bin/` holds source. */
+export function desiredEditorSettings({ dotnet }) {
+  const dirs = WORKTREE_DIR_NAMES.map((n) => `**/${n}/**`);
+  const watched = Object.fromEntries([...dirs, '**/node_modules/**', '**/bin/**', '**/obj/**'].map((g) => [g, true]));
+  const listed = Object.fromEntries([...dirs, '**/node_modules/**', ...(dotnet ? ['**/bin/**', '**/obj/**'] : [])].map((g) => [g, true]));
+  return { 'files.watcherExclude': watched, 'search.exclude': { ...watched }, 'files.exclude': listed };
+}
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+function isTracked(root, rel) {
+  try {
+    execFileSync('git', ['ls-files', '--error-unmatch', '--', rel], { cwd: root, stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function mergeMissing(current, wanted) {
+  const added = [];
+  const skipped = [];
+  for (const [key, globs] of Object.entries(wanted)) {
+    if (current[key] === undefined) {
+      current[key] = { ...globs };
+      added.push(...Object.keys(globs).map((g) => `${key}:${g}`));
+    } else if (isPlainObject(current[key])) {
+      for (const glob of Object.keys(globs)) {
+        if (!(glob in current[key])) { current[key][glob] = true; added.push(`${key}:${glob}`); }
+      }
+    } else {
+      skipped.push(key);
+    }
+  }
+  return { added, skipped };
+}
+
+function snippetFor(wanted, present) {
+  const missing = {};
+  for (const [key, globs] of Object.entries(wanted)) {
+    const gaps = Object.fromEntries(Object.entries(globs).filter(([g]) => !(isPlainObject(present?.[key]) && g in present[key])));
+    if (Object.keys(gaps).length) missing[key] = gaps;
+  }
+  return JSON.stringify(missing, null, 2);
+}
+
+/**
+ * Read-only: what `.vscode/settings.json` would need. `write` carries the full new text;
+ * `suggest` carries the snippet to paste, because rewriting would drop comments, trailing
+ * commas or a tracked file's cleanliness.
+ */
+export function planEditorSettings(root, { config = readProjectConfig(root), env = process.env } = {}) {
+  const file = join(root, SETTINGS_REL);
+  if (config?.worktree?.editorSettings === false || env.MORPH_EDITOR_SETTINGS === '0') return { status: 'off', file };
+
+  const wanted = desiredEditorSettings({ dotnet: isDotnet(root, config) });
+  if (!existsSync(file)) {
+    return { status: 'write', file, created: true, added: Object.entries(wanted).flatMap(([k, g]) => Object.keys(g).map((x) => `${k}:${x}`)), content: `${JSON.stringify(wanted, null, DEFAULT_INDENT)}\n` };
+  }
+
+  const suggest = (reason, present) => ({ status: 'suggest', file, reason, snippet: snippetFor(wanted, present) });
+  let text;
+  try { text = readFileSync(file, 'utf8'); } catch { return suggest('unreadable'); }
+  const body = text.replace(/^\uFEFF/, '');
+  let parsed;
+  try { parsed = JSON.parse(jsoncToJson(body)); } catch { return suggest('unreadable'); }
+  if (!isPlainObject(parsed)) return suggest('not-object');
+  if (stripComments(body) !== body || jsoncToJson(body) !== stripComments(body)) return suggest('comments', parsed);
+
+  const { added, skipped } = mergeMissing(parsed, wanted);
+  if (!added.length) return { status: 'unchanged', file, ...(skipped.length ? { skipped } : {}) };
+  if (isTracked(root, SETTINGS_REL)) return suggest('tracked', JSON.parse(jsoncToJson(body)));
+
+  const indent = /^([ \t]+)"/m.exec(body)?.[1] ?? DEFAULT_INDENT;
+  const eol = body.includes('\r\n') ? '\r\n' : '\n';
+  const out = JSON.stringify(parsed, null, indent).replace(/\n/g, eol) + (/\n$/.test(body) ? eol : '');
+  return { status: 'write', file, created: false, added, ...(skipped.length ? { skipped } : {}), content: `${text.startsWith('\uFEFF') ? '\uFEFF' : ''}${out}` };
+}
+
+/**
+ * Applies the plan through `fx` (so `update --dry-run` predicts it). A created file joins the
+ * common `info/exclude`: untracked, it would count as root dirt and `finish --merge` refuses that.
+ */
+export function applyEditorSettings(root, { fx = realEffects(), config, env } = {}) {
+  const plan = planEditorSettings(root, { config, env });
+  const { content, ...report } = plan;
+  if (plan.status !== 'write') return report;
+  try {
+    fx.writeFile(plan.file, content);
+    if (plan.created && !fx.dryRun) ensureCommonExclude(root, ['/.vscode/settings.json'], EXCLUDE_MARKER);
+    return { ...report, written: !fx.dryRun };
+  } catch (err) {
+    return { status: 'failed', file: plan.file, reason: String(err?.message ?? err).slice(0, 200) };
+  }
+}

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

@@ -30,16 +30,48 @@ import {
   isGitRepo,
   resolvePrimaryRoot,
   parseWorktreeList,
-  WORKTREE_DIR_NAMES,
   clearDanglingWorktreeRegistration,
 } from '../../commands/project/worktree.js';
+import { containerDirs, isUnder } from '../../../framework/hooks/shared/worktree-root.js';
 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';
 import { auditFinishBackups } from './finish-backup.js';
+import { planAgentReap } from './agent-reaper.js';
 
 const norm = (p) => resolve(p).replace(/\\/g, '/');
+const AGENT_TASK = /^agent-[0-9a-f]+$/;
+
+const AGENT_FIX = {
+  'stopped-clean': 'morph-spec worktree reap  (ou `morph-spec doctor --worktrees --prune`)',
+  'orphan-branch': 'morph-spec worktree reap  (ou `morph-spec doctor --worktrees --prune`)',
+  'directory-missing': 'morph-spec doctor --worktrees --prune',
+  locked: 'a árvore está com `git worktree lock`; `git worktree unlock <path>` libera, se o lock já não vale',
+  unknown: 'não foi possível provar que é seguro remover — deixe como está',
+};
+
+function agentLeftoverIssue(item) {
+  const where = item.path ?? item.branch;
+  const reapable = item.state === 'reapable';
+  const fix = AGENT_FIX[item.reason]
+    ?? (item.reason === 'exclusive-commits'
+      ? `integre a branch (\`git merge --no-ff ${item.branch}\` no orquestrador) antes de remover — ela é o único exemplar`
+      : item.reason === 'dirty'
+        ? `confira o trabalho na árvore (commite ou descarte) e rode \`morph-spec worktree remove --target "${item.path}"\``
+        : `o harness não registrou o fim do agente; se ele já terminou, \`morph-spec worktree remove --target "${item.path}"\``);
+  return {
+    type: 'agent-worktree-leftover',
+    severity: 'info',
+    ...(item.path ? { path: item.path } : {}),
+    branch: item.branch,
+    reapable,
+    detail: reapable
+      ? `${where} é sobra de sub-agent que já parou, sem trabalho pendente`
+      : `${where} é sobra de sub-agent com trabalho a preservar (${item.reason}${item.detail ? `: ${item.detail}` : ''})`,
+    fix,
+  };
+}
 
 /** Feature names morph knows about in the primary root. */
 function knownFeatures(root) {
@@ -170,15 +202,16 @@ function isEmptyDir(path) {
 /** Directories physically present under either worktree root. */
 function dirsOnDisk(root) {
   const found = [];
-  for (const dirName of WORKTREE_DIR_NAMES) {
-    const base = join(root, dirName);
+  const rootNorm = norm(root);
+  for (const base of containerDirs(root)) {
     if (!existsSync(base)) continue;
+    const label = base.startsWith(`${rootNorm}/`) ? base.slice(rootNorm.length + 1) : base;
     try {
       for (const name of readdirSync(base)) {
         const full = join(base, name);
         try {
           if (statSync(full).isDirectory()) {
-            found.push({ name, path: norm(full), container: dirName, empty: isEmptyDir(full) });
+            found.push({ name, path: norm(full), container: label, empty: isEmptyDir(full) });
           }
         } catch { /* unreadable entry — skip */ }
       }
@@ -214,6 +247,11 @@ function dirsOnDisk(root) {
  *                                 directory that exists but git's own
  *                                 registry does not know as a worktree
  *
+ *   • agent-worktree-leftover (info) — a sub-agent's `agent-<hex>` tree or
+ *                                 `morph-task/agent-<hex>` branch left behind:
+ *                                 `reapable` when the agent stopped and nothing
+ *                                 is lost, otherwise the reason it is kept
+ *
  *   • docker-stack-orphan (warn) — a `morph-*` docker stack of this repository
  *                                 still running for a feature this tree does
  *                                 not know, and
@@ -242,6 +280,7 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
   // two differently on purpose.
   const prIndex = buildPrIndex(root);
 
+  const containers = containerDirs(root);
   const registered = parseWorktreeList(root);
   const registeredPaths = new Set();
   const features = knownFeatures(root);
@@ -263,7 +302,7 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
 
     const feature = entry.branch?.match(/^refs\/heads\/morph\/(.+)$/)?.[1] || null;
     if (!feature) {
-      const inContainer = WORKTREE_DIR_NAMES.some((d) => path.startsWith(`${rootNorm}/${d}/`));
+      const inContainer = isUnder(containers, path);
       const task = entry.branch?.match(/^refs\/heads\/morph-task\/(.+)$/)?.[1] || null;
 
       if (!inContainer) {
@@ -287,6 +326,7 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
       }
 
       if (task) {
+        if (AGENT_TASK.test(task)) continue; // reported once, by the agent plan below
         // `morph-task/*`: a task-isolation tree provisioned by the WorktreeCreate
         // hook. Clean → nothing to say (the orchestrator removes it after the
         // merge). With commits the default does not have → report, never
@@ -367,6 +407,10 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
     }
   }
 
+  for (const item of planAgentReap(root, { cwd }).items) {
+    if (item.state === 'reapable' || item.state === 'preserved') issues.push(agentLeftoverIssue(item));
+  }
+
   for (const d of dirsOnDisk(root)) {
     if (registeredPaths.has(d.path)) continue;
     issues.push({