@polymorphism-tech/morph-spec 8.20.0 → 8.22.0

package/src/core/templates/template-registry.js

@@ -171,34 +171,6 @@ export function searchTemplates(keyword, projectPath = null) {
   });
 }
 
-/**
- * Get template absolute path with fallback logic.
- *
- * Resolution order:
- *   1. Project-local override (.morph/framework/templates/{path})
- *   2. Framework universal template (framework/templates/{path})
- *
- * @param {string} templateId - Template identifier
- * @param {string} projectPath - Project root path
- * @returns {string|null} Absolute template path or null if not found
- */
-export function resolveTemplatePathById(templateId, projectPath) {
-  const template = getTemplateById(templateId, projectPath);
-  if (!template) {
-    return null;
-  }
-
-  // 1. Project-local override
-  const projectLocalPath = join(projectPath, '.morph/framework/templates', template.path);
-  if (existsSync(projectLocalPath)) {
-    return projectLocalPath;
-  }
-
-  // 2. Framework universal template
-  const frameworkPath = join(projectPath, 'framework/templates', template.path);
-  return existsSync(frameworkPath) ? frameworkPath : null;
-}
-
 /** Absolute path of this repo's own framework/templates/ directory. */
 const FRAMEWORK_TEMPLATES_DIR = join(__dirname, '../../../framework/templates');
 
@@ -206,8 +178,8 @@ const FRAMEWORK_TEMPLATES_DIR = join(__dirname, '../../../framework/templates');
  * Resolve a template id to its absolute path inside THIS framework repo's
  * `framework/templates/` directory — for generators running against the
  * framework itself (scaffold-generator, context-generator), not against an
- * installed `.morph/`. Use resolveTemplatePathById() when a project root and
- * its project-local overrides are in play.
+ * installed `.morph/`. Use architecture-scanner.js's `resolveTemplatePath()`
+ * when a project root and its project-local overrides are in play.
  *
  * @param {string} templateId - Template identifier (REGISTRY.json `id`)
  * @returns {string} Absolute path to the template file

package/src/lib/e2e/compose-env.js

@@ -0,0 +1,74 @@
+/**
+ * Compose environment for the e2e stack — the port block a feature owns, plus
+ * the credentials its auth setup needs.
+ *
+ * This lives in ONE place because it has two callers that must never disagree:
+ * `morph-spec e2e up` (manual) and the `e2e` node inside `morph-spec verify`
+ * (the one that actually runs in the loop). When only the manual path built the
+ * port block, the isolation was real in the command nobody runs and absent in
+ * the one everybody runs — two worktrees would get distinct container names via
+ * COMPOSE_PROJECT_NAME and then collide on host port 3000 anyway, surfacing as
+ * "port is already allocated" and pausing a gate over an infrastructure clash
+ * rather than a defect.
+ *
+ * It sits in src/lib rather than framework/hooks/shared because it depends on
+ * env-allocator.js: hooks are installed standalone into target projects, where
+ * `src/` does not exist, so the dependency may only point this way.
+ *
+ * @module lib/e2e/compose-env
+ */
+
+import { join } from 'path';
+
+import { loadEnvFile } from '../../../framework/hooks/shared/e2e-check.js';
+import { allocateEnvBlock, resolveFleetConfig } from '../worktree/env-allocator.js';
+
+/**
+ * Build the environment a `docker compose` invocation should carry.
+ *
+ * Port variables mirror `buildEnvFileContent()` in env-allocator.js so a
+ * compose file and a `.morph/worktree.env` describe the same world: `PORT` for
+ * the web tier, `ASPNETCORE_URLS` on base+1 for a .NET backend.
+ *
+ * `PLAYWRIGHT_BASE_URL` is derived here rather than left to the spec config —
+ * the suite has to be told where the app actually landed, otherwise a feature
+ * on port 4020 gets tested against a hardcoded localhost:3000 and fails with
+ * ECONNREFUSED that looks exactly like a broken app.
+ *
+ * Fail-open throughout: with no git dir (or a corrupt registry) the caller gets
+ * default ports, which only matters when two stacks run at once.
+ *
+ * @param {object} params
+ * @param {string} params.cwd - project root
+ * @param {object|null} [params.config] - .morph/config/config.json contents
+ * @param {string} params.featureName
+ * @param {string|null} [params.gitCommonDir]
+ * @returns {Record<string,string>}
+ */
+export function buildComposeEnv({ cwd, config, featureName, gitCommonDir }) {
+  const env = {};
+
+  if (gitCommonDir) {
+    try {
+      const { basePort, blockSize } = resolveFleetConfig(cwd);
+      const block = allocateEnvBlock(featureName, { gitCommonDir, basePort, blockSize });
+
+      env.MORPH_PORT_BASE = String(block.base);
+      env.MORPH_PORT_RANGE = `${block.range[0]}-${block.range[1]}`;
+      env.PORT = String(block.base);
+      env.PLAYWRIGHT_BASE_URL = `http://localhost:${block.base}`;
+
+      if (/\bdotnet\b/i.test(String(config?.project?.stack ?? ''))) {
+        env.ASPNETCORE_URLS = `http://localhost:${block.base + 1}`;
+      }
+    } catch {
+      // No block → default ports. Surfaces later as a port conflict, never here.
+    }
+  }
+
+  // Credentials live in a gitignored env file, never in the committed config.
+  const envFile = config?.e2e?.auth?.envFile;
+  if (envFile) Object.assign(env, loadEnvFile(join(cwd, envFile)));
+
+  return env;
+}

package/src/lib/git/default-branch.js

@@ -112,26 +112,62 @@ function parseShortstat(text) {
   };
 }
 
+/**
+ * Count brand-new UNTRACKED files (never `git add`-ed) — the gap plain
+ * `git diff --shortstat` never sees, tracked-edits-only by design. Fail-open:
+ * any error (not a repo, git missing) reads as 0 untracked, never throws —
+ * this must not take down the whole `getDiffStat` result over a probe that
+ * is secondary to the diff itself.
+ *
+ * `--exclude-standard` matches gitignore the same way `git status` does, so
+ * scratch/build output never inflates the count.
+ *
+ * @param {string} cwd
+ * @returns {number}
+ */
+function countUntrackedFiles(cwd) {
+  try {
+    const out = execFileSync('git', ['ls-files', '--others', '--exclude-standard'], { cwd, stdio: 'pipe' })
+      .toString();
+    return out.split('\n').filter((l) => l.trim()).length;
+  } catch {
+    return 0;
+  }
+}
+
 /**
  * `git diff --shortstat <baseRef>` against the CURRENT WORKING TREE (tracked
  * edits — staged, unstaged, and everything committed since baseRef —
  * deliberately not `baseRef...HEAD`, so a gate-check mid-implement still sees
- * uncommitted work). Same as plain `git diff`, this does NOT count brand-new
- * UNTRACKED files (never `git add`-ed) — a real, known gap if a gate check
- * runs before `git add`; not fixed here since covering it needs `--no-index`
- * or `git add -N` bookkeeping this shared helper doesn't own. Fail-open: null
- * when `baseRef` is falsy, cwd isn't a git repo, or the diff itself fails
- * (e.g. baseRef doesn't resolve).
+ * uncommitted work), PLUS a count of brand-new UNTRACKED files (never
+ * `git add`-ed) that plain `git diff` never shows regardless of commit vs
+ * working tree. `filesChanged` is the combined total (tracked-changed +
+ * untracked) so a caller reading just that one number gets the true scope of
+ * what changed; `untrackedFiles` is broken out separately so a caller that
+ * cares CAN tell diff-vs-new apart instead of the two being silently fused.
+ *
+ * Both git calls run with the same `cwd` — every current caller passes a
+ * feature/worktree root there, so `git diff`'s repo-wide default and
+ * `git ls-files`'s cwd-relative listing agree; a caller passing a
+ * sub-directory as `cwd` would see `untrackedFiles` scoped to that
+ * sub-directory while `insertions`/`deletions` stay repo-wide — not a
+ * concern today, but worth knowing if that assumption ever changes.
+ *
+ * Fail-open: null when `baseRef` is falsy, cwd isn't a git repo, or the diff
+ * itself fails (e.g. baseRef doesn't resolve). The untracked probe fails open
+ * on its own (see countUntrackedFiles) and never turns a good diff into null.
  *
  * @param {string|null} baseRef - typically `detectDefaultBranch(cwd)`
  * @param {string} [cwd]
- * @returns {{ filesChanged: number, insertions: number, deletions: number }|null}
+ * @returns {{ filesChanged: number, insertions: number, deletions: number, untrackedFiles: number }|null}
  */
 export function getDiffStat(baseRef, cwd = process.cwd()) {
   if (!baseRef) return null;
   try {
     const out = execFileSync('git', ['diff', '--shortstat', baseRef], { cwd, stdio: 'pipe' }).toString().trim();
-    return parseShortstat(out);
+    const stat = parseShortstat(out);
+    const untrackedFiles = countUntrackedFiles(cwd);
+    return { ...stat, filesChanged: stat.filesChanged + untrackedFiles, untrackedFiles };
   } catch {
     return null;
   }

package/src/lib/installers/templates-reconcile.js

@@ -0,0 +1,81 @@
+/**
+ * templates-reconcile.js — reconcile a pre-existing `.morph/framework/templates/`
+ * copy against the project's prior recorded morph-spec version.
+ *
+ * Shared by BOTH install paths that can encounter this directory:
+ *   - `morph-spec update` (src/commands/project/update.js) — always knows the
+ *     project's prior version (`checkProjectOutdated().current`, read from
+ *     `.morph/.morphversion` BEFORE this run overwrites it).
+ *   - `morph-spec init`/`setup-infra` (src/scripts/setup-infra.js) — the SAME
+ *     source (`getProjectMorphVersion()`, the function `checkProjectOutdated`
+ *     itself calls), read at the same point in the run (before its own write
+ *     of `.morph/.morphversion`), when it's available — e.g. a repair run
+ *     over an already-initialized project. Falls back to a plain warning when
+ *     it isn't (a project with no recorded version has nothing here for this
+ *     function to reconcile against safely).
+ */
+
+import { existsSync } from 'fs';
+import fs from 'fs-extra';
+import { compareVersions } from '../../utils/version-checker.js';
+
+/**
+ * Last CLI version whose `update`/`setup-infra` still wrote
+ * `.morph/framework/templates/` unconditionally, before Task 2 of the R3
+ * perf plan removed that copy. Used as the decision boundary in
+ * `reconcileLegacyTemplatesCopy` below — see its doc comment for why a
+ * version check is used instead of diffing file content.
+ */
+export const LAST_VERSION_THAT_COPIED_TEMPLATES = '8.17.0';
+
+/**
+ * Reconcile a pre-existing `.morph/framework/templates/` copy now that
+ * neither install path unconditionally writes it anymore (Task 2, R3 perf
+ * plan — resolution falls back to the npm package's own framework/templates/,
+ * see template-registry.js / architecture-scanner.js's layered resolver).
+ *
+ * Decided from the project's PRIOR recorded CLI version (before THIS run
+ * writes a new one), not by diffing content against the package. A content
+ * diff can't tell "stale copy from an older CLI version" apart from
+ * "deliberate user override" — and staleness is the dominant case for
+ * anyone who actually runs `update`/`setup-infra` again, since template
+ * content does change between releases. The version boundary is unambiguous
+ * instead:
+ *
+ *   - No local copy → nothing to do.
+ *   - Prior version is unrecorded, OR <= LAST_VERSION_THAT_COPIED_TEMPLATES
+ *     → the copy could ONLY have been put there by the OLD installer:
+ *     `.morph/framework/**` is Edit-denied to the agent (MORPH_DENY in
+ *     hooks-installer.js — "installer-managed, immutable at runtime"),
+ *     the directory is gitignored, and every install/update before this fix
+ *     unconditionally wiped + recopied it. There is no path by which a
+ *     project on an old version could have a genuine override sitting
+ *     here. Safe to delete unconditionally — it is dead weight, not data.
+ *   - Prior version > LAST_VERSION_THAT_COPIED_TEMPLATES → this install path
+ *     has never written this directory for this project. Anything found
+ *     here was placed deliberately (by the user or other tooling) — this is
+ *     the forward-looking override use case the layered resolver exists
+ *     for. Preserve untouched, unconditionally, with no diffing.
+ *
+ * @param {string} templatesDest - .morph/framework/templates (may not exist)
+ * @param {string|null} priorProjectVersion - project's recorded morph-spec
+ *   version BEFORE this run (e.g. `checkProjectOutdated().current`)
+ * @returns {'absent'|'removed-legacy'|'preserved-override'}
+ */
+export function reconcileLegacyTemplatesCopy(templatesDest, priorProjectVersion) {
+  if (!existsSync(templatesDest)) return 'absent';
+
+  const isLegacy = !priorProjectVersion
+    || compareVersions(priorProjectVersion, LAST_VERSION_THAT_COPIED_TEMPLATES) <= 0;
+
+  if (!isLegacy) return 'preserved-override';
+
+  try {
+    fs.removeSync(templatesDest);
+    return 'removed-legacy';
+  } catch {
+    // Couldn't remove — don't risk a half-broken state; leave it and let
+    // the layered resolver's override-first check pick it up as before.
+    return 'preserved-override';
+  }
+}

package/src/lib/risk-detector.js

@@ -8,7 +8,9 @@
  * Signals checked (in order):
  *   - designSystemDivergence: boolean — conflicting design sources detected
  *   - standardsViolations: string[]   — violations of mandate.md proibições
- *   - verificationStatus: string      — último `morph-spec verify` ('fail' pausa)
+ *   - verificationStatus: string      — último `morph-spec verify` ('fail' pausa, qualquer gate)
+ *   - verificationStale + gate: bool/str — stamp com sha != HEAD pausa SÓ no
+ *     ship (gate 'review') — código mudou depois do último verify
  *   - evalScore: number               — morph-eval score (pause if < 9)
  *   - taskCount: number               — total tasks (pause if > 20)
  */
@@ -64,6 +66,20 @@ export function shouldPauseGate(config, signals) {
     };
   }
 
+  // Furo 2: no gate de SHIP (review) apenas, um stamp de verification cujo
+  // sha diverge do HEAD atual significa que código mudou depois do último
+  // `morph-spec verify` — o resultado carimbado não cobre mais o que está
+  // prestes a ser aprovado. Pausa só aqui, nunca em plan/uiux/proposal: essa
+  // é uma regra de ship, não uma regra geral de gate. Stamp AUSENTE não entra
+  // aqui (verificationStale é fail-open para `false` em collectSignals
+  // quando não há stamp) — features legadas sem stamp continuam liberadas.
+  if (signals.gate === 'review' && signals.verificationStale === true) {
+    return {
+      pause: true,
+      reason: 'verification stamp desatualizado (sha difere do HEAD) — rode `morph-spec verify` de novo antes do ship',
+    };
+  }
+
   if (typeof signals.evalScore === 'number' && signals.evalScore < MIN_EVAL_SCORE) {
     return {
       pause: true,
@@ -93,6 +109,9 @@ export function getRiskSignals(signals) {
     out.push(`standards violations: ${signals.standardsViolations.join(', ')}`);
   }
   if (signals.verificationStatus === 'fail') out.push('verify vermelho');
+  if (signals.gate === 'review' && signals.verificationStale === true) {
+    out.push('verification stamp desatualizado (stale) no ship');
+  }
   if (typeof signals.evalScore === 'number' && signals.evalScore < MIN_EVAL_SCORE) {
     out.push(`eval score ${signals.evalScore}/10`);
   }

package/src/lib/telemetry/telemetry-reader.js

@@ -10,7 +10,8 @@
  */
 
 import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
+import { join, basename } from 'path';
+import { parseWorktreeList, resolvePrimaryRoot } from '../../commands/project/worktree.js';
 
 const EVENTS_FILE = join('.morph', 'logs', 'events.jsonl');
 
@@ -37,6 +38,45 @@ export function loadTelemetry(projectPath) {
   }
 }
 
+/**
+ * Enumerate every git worktree that has its OWN `.morph/logs/events.jsonl` —
+ * the data source for `cost --all-trees` (Furo 3). Reuses the SAME worktree
+ * enumeration `doctor --worktrees`/`fleet` already use (`parseWorktreeList` +
+ * `resolvePrimaryRoot` from commands/project/worktree.js — see
+ * src/lib/worktree/fleet-scanner.js and worktree-audit.js for the sibling
+ * consumers) instead of re-walking `git worktree list` here.
+ *
+ * `git worktree list --porcelain` always lists the PRIMARY worktree first —
+ * that entry is labeled `'root'`; every other entry is labeled by its
+ * directory basename (typically the feature slug, e.g. `worktrees/{f}` →
+ * `f`). Only trees whose events.jsonl actually exists are returned — a
+ * worktree that never ran the harness contributes nothing, silently.
+ *
+ * Fail-open, like `loadTelemetry`: outside a git repo (or on any git error)
+ * `resolvePrimaryRoot`/`parseWorktreeList` degrade to a single root entry —
+ * never throws.
+ *
+ * @param {string} [cwd]
+ * @returns {Array<{ tree: string, path: string, events: Object[] }>}
+ */
+export function loadTelemetryAllTrees(cwd = process.cwd()) {
+  const root = resolvePrimaryRoot(cwd);
+  const entries = parseWorktreeList(root);
+  const trees = entries.length ? entries : [{ path: root }];
+
+  const out = [];
+  for (const t of trees) {
+    const eventsPath = join(t.path, EVENTS_FILE);
+    if (!existsSync(eventsPath)) continue;
+    out.push({
+      tree: t.path === root ? 'root' : basename(t.path),
+      path: t.path,
+      events: loadTelemetry(t.path),
+    });
+  }
+  return out;
+}
+
 function rank(map) {
   return [...map.entries()]
     .map(([name, count]) => ({ name, count }))
@@ -211,6 +251,26 @@ function finalizeTask(state) {
  * check) — today only Read events carry `bytes`, but this stays correct if
  * that widens rather than reporting a silent 0.
  *
+ * Dispatch prompt size (Furo 3 — contract with the hooks-side telemetry-log
+ * rewrite): a dispatch event's `prompt` field is now TRUNCATED to 2k chars on
+ * write, with the original length carried separately as `promptChars`. When
+ * `promptChars` (a number) is present it is preferred; a legacy stream that
+ * only ever had the untruncated `prompt` string falls back to
+ * `prompt.length`, unchanged from before — every existing byte count stays
+ * exact against old logs.
+ *
+ * SessionUsage events (`{ event: 'SessionUsage', inputTokens, outputTokens,
+ * cacheReadTokens, cacheCreationTokens }`) are a session-level rollup, not a
+ * per-tool event — they don't touch toolCounts/bytesByKind/dispatches, only
+ * sum into `sessionUsage` (real, hook-observed token counts — NOT the bytes
+ * proxy). They participate in the `--feature` filter exactly like every
+ * other event (via `scoped`, computed once at the top): a rollup with no
+ * `feature` field is silently excluded by a feature-scoped call, same as any
+ * other feature-less event would be — no special-casing. `sessionUsage` is
+ * `null` when the stream carries none (nothing to show), never a zeroed
+ * object, so a caller can tell "observed, all zero" apart from "never
+ * observed" the same way `evalScore` does in gate-check's signals.
+ *
  * @param {Object[]} events - raw events (from loadTelemetry)
  * @param {{ feature?: string }} [opts] - optional feature filter
  * @returns {{
@@ -220,11 +280,14 @@ function finalizeTask(state) {
  *   bytesByKind: Object<string, number>,
  *   bytesTotal: number,
  *   dispatches: {count:number, promptChars:number},
+ *   sessionUsage: {inputTokens:number, outputTokens:number, cacheReadTokens:number, cacheCreationTokens:number, sessions:number}|null,
  *   tools: Array<{name:string,count:number}>,
  *   tasks: Array<Object>,
  *   phases: Array<{phase:string, bytesByKind:Object<string,number>, bytesTotal:number}>,
  * }}
  */
+const SESSION_USAGE_KEYS = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheCreationTokens'];
+
 export function aggregateCost(events, opts = {}) {
   const scoped = opts.feature
     ? (events || []).filter(e => e.feature === opts.feature)
@@ -237,6 +300,8 @@ export function aggregateCost(events, opts = {}) {
   const phaseBytes = new Map(); // phase -> Map(kind -> bytes)
   const activeByFeature = new Map(); // featureKey -> open task state
   const tasks = [];
+  const sessionUsageTotals = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 };
+  let sessionUsageCount = 0;
 
   for (const e of scoped) {
     if (!e || typeof e !== 'object') continue;
@@ -260,6 +325,14 @@ export function aggregateCost(events, opts = {}) {
       continue;
     }
 
+    if (e.event === 'SessionUsage') {
+      sessionUsageCount += 1;
+      for (const key of SESSION_USAGE_KEYS) {
+        if (typeof e[key] === 'number' && Number.isFinite(e[key])) sessionUsageTotals[key] += e[key];
+      }
+      continue;
+    }
+
     if (e.tool) toolCounts.set(e.tool, (toolCounts.get(e.tool) || 0) + 1);
     const active = activeByFeature.get(featureKey(e));
     if (active && e.tool) {
@@ -277,12 +350,14 @@ export function aggregateCost(events, opts = {}) {
       }
     }
 
-    if ((e.tool === 'Agent' || e.tool === 'Task') && typeof e.prompt === 'string' && e.prompt) {
+    const hasPromptChars = typeof e.promptChars === 'number' && Number.isFinite(e.promptChars);
+    if ((e.tool === 'Agent' || e.tool === 'Task') && (hasPromptChars || (typeof e.prompt === 'string' && e.prompt))) {
+      const chars = hasPromptChars ? e.promptChars : e.prompt.length;
       dispatches.count += 1;
-      dispatches.promptChars += e.prompt.length;
+      dispatches.promptChars += chars;
       if (active) {
         active.dispatches.count += 1;
-        active.dispatches.promptChars += e.prompt.length;
+        active.dispatches.promptChars += chars;
       }
     }
   }
@@ -309,6 +384,7 @@ export function aggregateCost(events, opts = {}) {
     bytesByKind: mapToObj(bytesByKindGlobal),
     bytesTotal: sumValues(bytesByKindGlobal),
     dispatches,
+    sessionUsage: sessionUsageCount > 0 ? { ...sessionUsageTotals, sessions: sessionUsageCount } : null,
     tools: rank(toolCounts),
     tasks,
     phases,

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

@@ -1,24 +1,33 @@
 /**
- * Verify Runner — deterministic build+tests+validators cadence.
+ * Verify Runner — deterministic build+tests+validators+e2e cadence.
  *
  * v8 adds a DETERMINISTIC verification node that runs BEFORE the LLM judge
  * in the per-task loop: build + tests + validators (code, free) first; the
  * LLM judge is only invoked once verify passes. This is a BINARY gate
  * (pass/fail per node), NOT a second "bar 9" — the bar 9 remains morph-eval's.
  *
+ * The `e2e` node closes the last gap in that chain: build proves the code
+ * COMPILES, tests prove units behave, validators read structure — none of
+ * them prove the application RUNS. See e2e-check.js for why that distinction
+ * is load-bearing rather than academic.
+ *
  * Pure orchestration — reuses (never reimplements):
  *   - runBuildCheck()  from framework/hooks/shared/build-check.js
  *   - runTestSuite()   from src/lib/tasks/test-runner.js
  *   - runValidation()  from ./validation-runner.js
+ *   - runE2eCheck()    from framework/hooks/shared/e2e-check.js
  *   - loadRubric() + aggregateScores() from ./score-aggregator.js
  *
  * @module verify-runner
  */
 
+import { execFileSync } from 'child_process';
 import { existsSync, readFileSync } from 'fs';
-import { join } from 'path';
+import { join, resolve } from 'path';
 
 import { runBuildCheck, getBuildSteps } from '../../../framework/hooks/shared/build-check.js';
+import { runE2eCheck } from '../../../framework/hooks/shared/e2e-check.js';
+import { buildComposeEnv } from '../e2e/compose-env.js';
 import { runTestSuite, resolveTestCommand } from '../tasks/test-runner.js';
 import { runValidation } from './validation-runner.js';
 import { loadRubric, aggregateScores } from './score-aggregator.js';
@@ -41,9 +50,12 @@ const OUTPUT_TAIL_LINES = 20;
  * @param {number} [options.timeout] - Build timeout in ms (default 120000)
  * @param {boolean} [options.skipTests] - Skip the tests node
  * @param {boolean} [options.skipBuild] - Skip the build node
+ * @param {boolean} [options.skipE2e] - Skip the e2e node
+ * @param {boolean} [options.freshE2e] - Force a stack rebuild instead of reusing a warm one
  * @param {Function} [options._runBuildCheck] - Injectable override for runBuildCheck (testing)
  * @param {Function} [options._runTestSuite] - Injectable override for runTestSuite (testing)
  * @param {Function} [options._runValidation] - Injectable override for runValidation (testing)
+ * @param {Function} [options._runE2eCheck] - Injectable override for runE2eCheck (testing)
  * @returns {Promise<Object>} Aggregated verify result — see module docs for shape
  */
 export async function runVerify(projectPath, featureName, taskId, options = {}) {
@@ -52,9 +64,12 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
     timeout = DEFAULT_BUILD_TIMEOUT,
     skipTests = false,
     skipBuild = false,
+    skipE2e = false,
+    freshE2e = false,
     _runBuildCheck = runBuildCheck,
     _runTestSuite = runTestSuite,
     _runValidation = runValidation,
+    _runE2eCheck = runE2eCheck,
   } = options;
 
   const stack = readStack(projectPath);
@@ -76,6 +91,20 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
   nodes.validators = await runValidatorsNode({ projectPath, featureName, rubricId, _runValidation });
   appendValidatorsFeedback(feedback, nodes.validators);
 
+  // 4. e2e — the only node that runs the application. Like tests, it is not
+  // invoked at all on a red build: a stack that cannot compile cannot come up,
+  // and the docker output would bury the actual compile error.
+  nodes.e2e = await runE2eNode({
+    projectPath,
+    featureName,
+    taskId,
+    skipE2e,
+    freshE2e,
+    buildNode: nodes.build,
+    _runE2eCheck,
+  });
+  appendE2eFeedback(feedback, nodes.e2e);
+
   const status = Object.values(nodes).some((n) => n.status === 'fail') ? 'fail' : 'pass';
 
   return {
@@ -239,6 +268,63 @@ function appendValidatorsFeedback(feedback, validatorsNode) {
   }
 }
 
+// ============================================================================
+// E2E node
+// ============================================================================
+
+async function runE2eNode({ projectPath, featureName, taskId, skipE2e, freshE2e, buildNode, _runE2eCheck }) {
+  if (buildNode.status === 'fail') {
+    return {
+      status: 'skip',
+      command: null,
+      durationMs: 0,
+      reason: 'build failed — the stack could not come up anyway',
+      output: '',
+    };
+  }
+
+  const config = readConfig(projectPath);
+  const taskGroup = taskId ? readTaskGroup(projectPath, featureName, taskId) : null;
+  const gitCommonDir = resolveGitCommonDir(projectPath);
+
+  const start = Date.now();
+  const result = _runE2eCheck(projectPath, {
+    config,
+    featureName,
+    taskGroup,
+    scope: taskId ? 'task' : 'feature',
+    gitCommonDir,
+    // The port block matters MORE here than in `e2e up`: this is the path that
+    // runs in the loop, and two worktrees verifying at once would otherwise get
+    // distinct container names and then collide on host port 3000 — a red gate
+    // over an infrastructure clash instead of a defect.
+    env: buildComposeEnv({ cwd: projectPath, config, featureName, gitCommonDir }),
+    skipRequested: skipE2e,
+    forceFresh: freshE2e,
+    // 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.
+    keepUp: true,
+  });
+  const durationMs = Date.now() - start;
+
+  return {
+    status: result.status,
+    command: result.command ?? null,
+    durationMs,
+    reason: result.reason ?? null,
+    output: result.output || '',
+  };
+}
+
+function appendE2eFeedback(feedback, e2eNode) {
+  if (e2eNode.status !== 'fail') return;
+  if (e2eNode.reason) feedback.push(`[e2e] ${e2eNode.reason}`);
+  for (const line of linesOf(e2eNode.output)) {
+    feedback.push(`[e2e] ${line}`);
+  }
+}
+
 // ============================================================================
 // Rubric selection — flag > task group > config > default
 // ============================================================================
@@ -328,6 +414,39 @@ function readProjectPaths(projectPath) {
   }
 }
 
+/** Read the whole config.json — the e2e node needs `e2e` and `project` together. */
+function readConfig(projectPath) {
+  try {
+    const configPath = join(projectPath, '.morph', 'config', 'config.json');
+    if (!existsSync(configPath)) return null;
+    return JSON.parse(readFileSync(configPath, 'utf8').replace(/^/, ''));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the shared git dir, where the e2e freshness stamp lives — the same
+ * location and rationale as the fleet env-registry (see env-allocator.js): it
+ * is the one place every linked worktree of a repo shares, and writing there
+ * can never dirty the `git status` the worktree-finish gates read.
+ *
+ * Fail-open: no git, no stamp — the cost is a rebuild, never a crash.
+ */
+function resolveGitCommonDir(projectPath) {
+  try {
+    const common = execFileSync('git', ['rev-parse', '--git-common-dir'], {
+      cwd: projectPath,
+      stdio: 'pipe',
+      encoding: 'utf-8',
+      windowsHide: true,
+    }).trim();
+    return common ? resolve(projectPath, common) : null;
+  } catch {
+    return null;
+  }
+}
+
 function linesOf(text) {
   const trimmed = (text || '').trim();
   return trimmed ? trimmed.split('\n') : [];