@polymorphism-tech/morph-spec 8.42.0 → 8.44.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/env-allocator.js

@@ -168,10 +168,10 @@ export const PORT_OFFSETS = Object.freeze({ web: 0, api: 1, postgres: 2, redis:
  * not in the root's. Every value is a string (env-safe); key order is stable.
  *
  * @param {{ base: number, range: [number, number] }} block
- * @param {{ stack?: string, feature?: string }} [opts]
+ * @param {{ stack?: string, feature?: string, aliases?: Record<string, string> }} [opts] - aliases: resolvePortAliases()
  * @returns {Record<string,string>}
  */
-export function portLayout(block, { stack = '', feature = '' } = {}) {
+export function portLayout(block, { stack = '', feature = '', aliases = {} } = {}) {
   const env = {};
   if (feature) env.COMPOSE_PROJECT_NAME = composeProjectName(feature);
   env.MORPH_PORT_BASE = String(block.base);
@@ -183,9 +183,39 @@ export function portLayout(block, { stack = '', feature = '' } = {}) {
   if (/\bdotnet\b/i.test(String(stack))) {
     env.ASPNETCORE_URLS = `http://localhost:${block.base + PORT_OFFSETS.api}`;
   }
+  for (const [alias, port] of Object.entries(aliases)) env[alias] = String(block.base + PORT_OFFSETS[port]);
   return env;
 }
 
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const RESERVED_ENV_NAMES = new Set([
+  ...Object.keys(portLayout({ base: 0, range: [0, 0] }, { stack: 'dotnet', feature: 'x' })),
+  'PLAYWRIGHT_BASE_URL',
+  'MORPH_FEATURE',
+]);
+
+// e2e.portEnvNames: extra env names for the same four ports, so a compose file reading
+// ${PG_PORT} is fed by the block, not by its own default. An entry that cannot be
+// honoured is dropped and named in `problems`.
+export function resolvePortAliases(config) {
+  const declared = config?.e2e?.portEnvNames;
+  const aliases = {};
+  const problems = [];
+  if (declared === undefined || declared === null) return { aliases, problems };
+  if (typeof declared !== 'object' || Array.isArray(declared)) {
+    return { aliases, problems: [`e2e.portEnvNames deve ser um objeto { ${Object.keys(PORT_OFFSETS).join('|')}: "NOME" }`] };
+  }
+  for (const [port, name] of Object.entries(declared)) {
+    const at = `e2e.portEnvNames.${port}`;
+    if (!Object.hasOwn(PORT_OFFSETS, port)) problems.push(`${at}: porta desconhecida (use ${Object.keys(PORT_OFFSETS).join('|')})`);
+    else if (typeof name !== 'string' || !ENV_NAME.test(name)) problems.push(`${at}: ${JSON.stringify(name)} não é um nome de variável de ambiente válido`);
+    else if (RESERVED_ENV_NAMES.has(name)) problems.push(`${at}: "${name}" já é uma variável do layout`);
+    else if (Object.hasOwn(aliases, name)) problems.push(`${at}: "${name}" já é o alias de ${aliases[name]}`);
+    else aliases[name] = port;
+  }
+  return { aliases, problems };
+}
+
 /**
  * Render the `.morph/worktree.env` contents for a block: a header, the
  * feature, and exactly the `portLayout()` pairs — nothing else, so the file
@@ -199,15 +229,15 @@ export function portLayout(block, { stack = '', feature = '' } = {}) {
  * @param {string} feature - the env-registry key: `<feature>` or `task/<name>`
  * @param {{ base: number, range: [number, number] }} block
  * @param {string} [stack] - config.json `project.stack` (e.g. "nextjs+dotnet")
- * @param {{ morphFeature?: string|null }} [opts]
+ * @param {{ morphFeature?: string|null, aliases?: Record<string, string> }} [opts]
  * @returns {string}
  */
-export function buildEnvFileContent(feature, block, stack = '', { morphFeature = null } = {}) {
+export function buildEnvFileContent(feature, block, stack = '', { morphFeature = null, aliases = {} } = {}) {
   const lines = [
     `# Managed by morph-spec — ambiente dedicado desta worktree (feature: ${feature}).`,
     '# Derivado, git-invisível, regenerado por `worktree setup|link`; nunca editar nem commitar.',
     `MORPH_FEATURE=${morphFeature || feature}`,
-    ...Object.entries(portLayout(block, { stack, feature })).map(([k, v]) => `${k}=${v}`),
+    ...Object.entries(portLayout(block, { stack, feature, aliases })).map(([k, v]) => `${k}=${v}`),
   ];
   return `${lines.join('\n')}\n`;
 }

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) };
+  }
+}