@mjasnikovs/pi-task 0.24.5 → 0.26.0

package/dist/task/artifact-closure.d.ts

@@ -24,6 +24,12 @@ export interface ProducedOutputs {
     opaque: Set<string>;
     /** Dirs known to be created (mkdir, outdirs) — satisfies dir-kind refs. */
     dirs: Set<string>;
+    /** Dirs a BUILD TOOL declared as its output location (`--outdir`, `Bun.build`
+     *  outdir, a bundler's known dir, tsconfig/vite outDir). Strictly narrower
+     *  than `dirs`: writing one file into `report/` makes `report` enumerable but
+     *  never a build outdir. Generated-HTML scanning is gated on this set, so a
+     *  one-off HTML report writer cannot pull its assets into the check. */
+    outdirs: Set<string>;
 }
 export declare function emptyProducers(): ProducedOutputs;
 /** Normalize a literal path: posix separators, strip ./ prefixes, query/hash
@@ -34,6 +40,30 @@ export declare function normalizeRefPath(raw: string): string | null;
 export declare function extractJsRefs(source: string, referencer: string): RuntimeRef[];
 /** Extract local-asset refs from one HTML source. */
 export declare function extractHtmlRefs(source: string, referencer: string): RuntimeRef[];
+/** One HTML document a source writes into a build output. */
+export interface EmittedHtml {
+    /** Repo-relative path written to (`dist/index.html`). */
+    docPath: string;
+    /** The literal's raw text. */
+    html: string;
+}
+/** HTML documents this source writes: `Bun.write('x.html', <literal|ident>)` and
+ *  the writeFile family. Only literal destinations, only HTML extensions. */
+export declare function collectEmittedHtml(source: string): EmittedHtml[];
+/**
+ * Asset references inside HTML this source GENERATES into a build output.
+ *
+ * Resolution, deterministic:
+ *  • root-relative (`/app.css`) resolves against the build OUTDIR the document
+ *    lands in (`dist/index.html` ⇒ `dist/`) — that dir is the server's static
+ *    root by construction;
+ *  • document-relative (`app.css`, `./assets/x.js`) resolves against the
+ *    document's own directory;
+ *  • schemes (`https:`, `data:`, `cid:`), protocol-relative `//host/x`, and bare
+ *    `#fragment`s are dropped by normalizeRefPath;
+ *  • a literal not written into a declared build outdir is never scanned at all.
+ */
+export declare function extractGeneratedHtmlRefs(source: string, referencer: string, prod: ProducedOutputs): RuntimeRef[];
 /** Script entrypoints: `bun x.ts`, `bun run x.ts`, `node x.js`, `tsx x.ts` —
  *  the first path-shaped source arg of a runner command. */
 export declare function extractScriptEntrypoints(body: string, referencer: string): RuntimeRef[];
@@ -58,12 +88,34 @@ export declare function collectProducersFromCommand(cmd: string, prod: ProducedO
  * shape: tailwind's `-o dist/app.css` lives in a spawn array).
  */
 export declare function collectProducersFromSource(source: string, prod: ProducedOutputs): void;
+/**
+ * A WATCH/DEV script — one a production build never invokes.
+ *
+ * The load-bearing rule of nexttask 3 (mx5 run 18): `dist/app.css` had exactly
+ * one producer, `dev:css` (`@tailwindcss/cli … -o dist/app.css --watch`), a
+ * watch-mode dev script. The gate's own commands are `build`, `test`, `lint` —
+ * none of them runs it, so the shipped page loaded zero CSS while the closure
+ * table happily reported the file "produced". A production artifact closed only
+ * by a watch script is dangling by construction.
+ *
+ * Deterministic and name-or-flag based, exactly as pre-registered: a script
+ * whose NAME starts with `dev`/`watch`, or whose BODY carries `--watch`.
+ */
+export declare function isDevScript(name: string, body: string): boolean;
+export interface ProducerOpts {
+    /**
+     * Drop watch/dev scripts (and the build files reachable only through them)
+     * from the producer table — the PRODUCTION view of what a release contains.
+     * Off by default: the shipped resolution path is unchanged by this task.
+     */
+    excludeDevScripts?: boolean;
+}
 /**
  * Discover everything the project's own machinery produces: package.json script
  * bodies, build files those scripts run (plus conventional root build files),
  * tsconfig/vite outDirs.
  */
-export declare function discoverProducers(cwd: string): ProducedOutputs;
+export declare function discoverProducers(cwd: string, opts?: ProducerOpts): ProducedOutputs;
 /**
  * Resolve refs against existence + producers. DANGLING requires POSITIVE
  * evidence (see the module doc): the ref sits under an ENUMERATED output dir
@@ -79,6 +131,24 @@ export declare function resolveDanglingRefs(refs: RuntimeRef[], prod: ProducedOu
  * producers (an app that writes its own cache file satisfies its own read).
  */
 export declare function findDanglingArtifacts(cwd: string): DanglingRef[];
+/** How a generated-HTML asset reference resolves — the STEP 0 measurement. */
+export type GeneratedHtmlRefClass = 
+/** Produced by the production build (or already on disk). */
+'produced'
+/** Only a watch/dev script produces it — dangling for a production build. */
+ | 'dev-only'
+/** Nothing produces it at all. */
+ | 'missing';
+/** Classify one generated-HTML ref against both producer tables (STEP 0 / A/B
+ *  reporting; the gate itself only needs the dangling verdict). */
+export declare function classifyGeneratedHtmlRef(ref: RuntimeRef, full: ProducedOutputs, production: ProducedOutputs, exists: (rel: string) => boolean): GeneratedHtmlRefClass;
+/** STEP 0 / A/B helper: every generated-HTML asset ref in a tree, with the
+ *  producer tables it was measured against. Read-only, deterministic. */
+export declare function collectGeneratedHtmlRefs(cwd: string): {
+    refs: RuntimeRef[];
+    full: ProducedOutputs;
+    production: ProducedOutputs;
+};
 /** Ranked-failure text for the final gate (names referencer + missing path). */
 export declare function danglingGateFailureText(d: DanglingRef): string;
 /** Does the spec LIST the file as its own artifact — a file-tree entry or a

package/dist/task/artifact-closure.js

@@ -43,7 +43,13 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import * as path from 'node:path';
 export function emptyProducers() {
-    return { files: new Set(), enumerable: new Map(), opaque: new Set(), dirs: new Set() };
+    return {
+        files: new Set(),
+        enumerable: new Map(),
+        opaque: new Set(),
+        dirs: new Set(),
+        outdirs: new Set()
+    };
 }
 /** Normalize a literal path: posix separators, strip ./ prefixes, query/hash
  *  tails (HTML), trailing slash. Returns null when the literal is not a
@@ -147,6 +153,159 @@ export function extractHtmlRefs(source, referencer) {
     }
     return out;
 }
+// ---------------------------------------------------------------------------
+// GENERATED HTML (nexttask 3, mx5 run 18).
+//
+// The run-13 checker fired correctly on `src/server/index.ts → dist/index.html`;
+// the autofix satisfied it by appending an HTML template literal to `build.ts`
+// and `Bun.write`ing it — and that page pointed at `/app.css`, which `bun run
+// build` never emits (only the watch-mode `dev:css` does). The re-run gate saw
+// nothing, because the extractor scans HTML FILES and JS READS, never the HTML a
+// source GENERATES. So one dangling reference was closed by creating another one
+// indirection deeper.
+//
+// Scope discipline, the reason this does not become an FP machine: a literal is
+// scanned ONLY when it reaches a write whose destination is an HTML file inside a
+// directory a BUILD TOOL declared as its output (`prod.outdirs`). An email-body
+// template (`~/hub/aiz-server/src/connections/mailTemplate.ts` — `export default
+// \`<!doctype html>…\``) is never written to a build output and is therefore
+// never scanned, `<img src="cid:logo">` and all.
+// ---------------------------------------------------------------------------
+/** Asset attributes scanned in GENERATED HTML. Wider than HTML_PATTERNS (which
+ *  keeps scanning on-disk .html files exactly as it always has) by the media
+ *  tags nexttask 3 names. */
+const GENERATED_HTML_PATTERNS = [
+    ...HTML_PATTERNS,
+    {
+        re: /<(?:source|video|audio)\b[^>]*\bsrc\s*=\s*(['"])([^'"]+)\1/gi,
+        construct: 'media src',
+        kind: 'file'
+    }
+];
+/** Read a quoted/template literal starting at `i` (src[i] is the quote char).
+ *  Returns the body and the index just past the closing quote, or null when
+ *  unterminated. Escapes are honoured; a `${…}` hole is left in the text, where
+ *  normalizeRefPath rejects it. */
+function readLiteral(src, i) {
+    const q = src[i];
+    if (q !== '"' && q !== "'" && q !== '`')
+        return null;
+    let out = '';
+    for (let j = i + 1; j < src.length; j++) {
+        const c = src[j];
+        if (c === '\\') {
+            out += src[j + 1] ?? '';
+            j++;
+            continue;
+        }
+        if (c === q)
+            return { text: out, end: j + 1 };
+        if (c === '\n' && q !== '`')
+            return null; // unterminated single-line literal
+        out += c;
+    }
+    return null;
+}
+/** `const NAME = <literal>` bindings (also let/var) — the mx5 build.ts shape is
+ *  `const html = \`…\`` followed by `Bun.write('dist/index.html', html)`. */
+function literalBindings(src) {
+    const out = new Map();
+    const re = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?=['"`])/g;
+    for (let m = re.exec(src); m !== null; m = re.exec(src)) {
+        const lit = readLiteral(src, m.index + m[0].length);
+        if (lit === null)
+            continue;
+        out.set(m[1], lit.text);
+        re.lastIndex = lit.end;
+    }
+    return out;
+}
+/** HTML documents this source writes: `Bun.write('x.html', <literal|ident>)` and
+ *  the writeFile family. Only literal destinations, only HTML extensions. */
+export function collectEmittedHtml(source) {
+    const src = stripCommentLines(source);
+    const bindings = literalBindings(src);
+    const out = [];
+    const writeRe = /\b(?:Bun\.write|writeFileSync|writeFile|fs\.promises\.writeFile)\(\s*(['"`])([^'"`\n]+)\1\s*,\s*/g;
+    for (let m = writeRe.exec(src); m !== null; m = writeRe.exec(src)) {
+        const docPath = normalizeRefPath(m[2]);
+        if (docPath === null || !SCAN_HTML_RE.test(docPath))
+            continue;
+        const at = m.index + m[0].length;
+        let html;
+        const lit = readLiteral(src, at);
+        if (lit !== null)
+            html = lit.text;
+        else {
+            const id = /^[A-Za-z_$][\w$]*/.exec(src.slice(at, at + 80));
+            if (id)
+                html = bindings.get(id[0]);
+        }
+        if (html === undefined || !html.includes('<'))
+            continue;
+        out.push({ docPath, html });
+    }
+    return out;
+}
+/** The narrowest build outdir containing `p`, or null when no build tool
+ *  declared one that covers it. */
+function containingOutdir(p, prod) {
+    let best = null;
+    for (const d of prod.outdirs) {
+        if (!underDir(p, d))
+            continue;
+        if (best === null || d.length > best.length)
+            best = d;
+    }
+    return best;
+}
+/**
+ * Asset references inside HTML this source GENERATES into a build output.
+ *
+ * Resolution, deterministic:
+ *  • root-relative (`/app.css`) resolves against the build OUTDIR the document
+ *    lands in (`dist/index.html` ⇒ `dist/`) — that dir is the server's static
+ *    root by construction;
+ *  • document-relative (`app.css`, `./assets/x.js`) resolves against the
+ *    document's own directory;
+ *  • schemes (`https:`, `data:`, `cid:`), protocol-relative `//host/x`, and bare
+ *    `#fragment`s are dropped by normalizeRefPath;
+ *  • a literal not written into a declared build outdir is never scanned at all.
+ */
+export function extractGeneratedHtmlRefs(source, referencer, prod) {
+    const out = [];
+    const seen = new Set();
+    for (const { docPath, html } of collectEmittedHtml(source)) {
+        const outdir = containingOutdir(docPath, prod);
+        if (outdir === null)
+            continue; // not a build artifact — out of scope
+        const docDir = path.posix.dirname(docPath);
+        for (const { re, construct, kind } of GENERATED_HTML_PATTERNS) {
+            re.lastIndex = 0;
+            for (let m = re.exec(html); m !== null; m = re.exec(html)) {
+                const raw = m[2];
+                const rootRelative = /^\/(?!\/)/.test(raw.trim());
+                const p = normalizeRefPath(raw);
+                if (p === null || !hasExt(p))
+                    continue;
+                const base = rootRelative ? outdir : docDir;
+                const resolved = path.posix.normalize(base === '.' ? p : `${base}/${p}`);
+                if (resolved.startsWith('..'))
+                    continue;
+                if (seen.has(resolved))
+                    continue;
+                seen.add(resolved);
+                out.push({
+                    path: resolved,
+                    referencer,
+                    construct: `${construct} in generated ${docPath}`,
+                    kind
+                });
+            }
+        }
+    }
+    return out;
+}
 /** A path-shaped shell token: contains a separator or an extension, no shell
  *  metacharacters, not a flag. */
 function isPathToken(t) {
@@ -230,8 +389,10 @@ export function collectProducersFromCommand(cmd, prod, opts = {}) {
     let rest = cmd.replace(/2>&1|&>\s*\S+|2>\s*\S+/g, ' ');
     for (const { re, dirs } of OPAQUE_TOOL_DIRS) {
         if (re.test(rest))
-            for (const d of dirs)
+            for (const d of dirs) {
                 prod.opaque.add(d);
+                prod.outdirs.add(d);
+            }
     }
     // Redirect target.
     rest = rest.replace(/>>?\s*([^\s&|;]+)/g, (_, f) => {
@@ -248,12 +409,16 @@ export function collectProducersFromCommand(cmd, prod, opts = {}) {
         const p = normalizeRefPath(val);
         if (p === null)
             return ' ';
-        if (flag === '--outdir' || flag === '--out-dir')
+        if (flag === '--outdir' || flag === '--out-dir') {
             addEnumerable(prod, p, []);
+            prod.outdirs.add(p);
+        }
         else if (hasExt(p))
             addFile(prod, p);
-        else
+        else {
             addEnumerable(prod, p, []);
+            prod.outdirs.add(p);
+        }
         return ' ';
     });
     const toks = rest.trim().split(/\s+/);
@@ -304,8 +469,10 @@ export function collectProducersFromCommand(cmd, prod, opts = {}) {
         if (p !== null)
             declaredDirs.push(p);
     }
-    for (const d of declaredDirs)
+    for (const d of declaredDirs) {
         addEnumerable(prod, d, sourceArgs.map(stem));
+        prod.outdirs.add(d);
+    }
     // Unrecognized command: any leftover path token pointing INTO a directory
     // makes that directory opaque — the tool may generate arbitrary files there.
     if ((opts.escalate ?? true) && !KNOWN_NON_PRODUCING_RE.test(bin) && !/^@/.test(bin)) {
@@ -375,6 +542,7 @@ export function collectProducersFromSource(source, prod) {
         const dir = normalizeRefPath(outdirM[2]);
         if (dir === null)
             continue;
+        prod.outdirs.add(dir);
         if (/\bnaming:/.test(body)) {
             prod.opaque.add(dir); // custom naming — outputs underivable
             continue;
@@ -422,8 +590,10 @@ function collectTsconfigOutDirs(cwd, prod) {
             const m = /"outDir"\s*:\s*"([^"]+)"/.exec(readFileSync(path.join(cwd, n), 'utf8'));
             if (m) {
                 const p = normalizeRefPath(m[1]);
-                if (p !== null)
+                if (p !== null) {
                     prod.opaque.add(p);
+                    prod.outdirs.add(p);
+                }
             }
         }
         catch {
@@ -445,12 +615,15 @@ function collectBundlerConfigOutDirs(cwd, prod) {
         if (!existsSync(f))
             continue;
         prod.opaque.add('dist');
+        prod.outdirs.add('dist');
         try {
             const m = /\boutDir:\s*(['"`])([^'"`\n]+)\1/.exec(readFileSync(f, 'utf8'));
             if (m) {
                 const p = normalizeRefPath(m[2]);
-                if (p !== null)
+                if (p !== null) {
                     prod.opaque.add(p);
+                    prod.outdirs.add(p);
+                }
             }
         }
         catch {
@@ -468,14 +641,33 @@ function packageScripts(cwd) {
         return {};
     }
 }
+/**
+ * A WATCH/DEV script — one a production build never invokes.
+ *
+ * The load-bearing rule of nexttask 3 (mx5 run 18): `dist/app.css` had exactly
+ * one producer, `dev:css` (`@tailwindcss/cli … -o dist/app.css --watch`), a
+ * watch-mode dev script. The gate's own commands are `build`, `test`, `lint` —
+ * none of them runs it, so the shipped page loaded zero CSS while the closure
+ * table happily reported the file "produced". A production artifact closed only
+ * by a watch script is dangling by construction.
+ *
+ * Deterministic and name-or-flag based, exactly as pre-registered: a script
+ * whose NAME starts with `dev`/`watch`, or whose BODY carries `--watch`.
+ */
+export function isDevScript(name, body) {
+    return /^(?:dev|watch)\b|^(?:dev|watch)[:._-]/i.test(name) || /(?:^|\s)--watch\b/.test(body);
+}
 /**
  * Discover everything the project's own machinery produces: package.json script
  * bodies, build files those scripts run (plus conventional root build files),
  * tsconfig/vite outDirs.
  */
-export function discoverProducers(cwd) {
+export function discoverProducers(cwd, opts = {}) {
     const prod = emptyProducers();
-    const scripts = packageScripts(cwd);
+    const all = packageScripts(cwd);
+    const scripts = opts.excludeDevScripts === true ?
+        Object.fromEntries(Object.entries(all).filter(([n, b]) => !isDevScript(n, b)))
+        : all;
     const buildFiles = new Set(['build.ts', 'build.js', 'build.mjs'].filter(f => existsSync(path.join(cwd, f))));
     for (const body of Object.values(scripts)) {
         for (const cmd of splitShellCommands(body)) {
@@ -504,6 +696,19 @@ export function discoverProducers(cwd) {
     return prod;
 }
 const underDir = (p, dir) => p === dir || p.startsWith(dir + '/');
+/** Is a FILE path positively produced — named exactly, under an opaque dir, or
+ *  an enumerated stem of an enumerable outdir? */
+function fileProduced(c, prod) {
+    if (prod.files.has(c))
+        return true;
+    if ([...prod.opaque].some(d => underDir(c, d)))
+        return true;
+    for (const [dir, stems] of prod.enumerable) {
+        if (underDir(path.posix.dirname(c), dir) && stems.has(stem(c)))
+            return true;
+    }
+    return false;
+}
 /**
  * Resolve refs against existence + producers. DANGLING requires POSITIVE
  * evidence (see the module doc): the ref sits under an ENUMERATED output dir
@@ -549,17 +754,7 @@ export function resolveDanglingRefs(refs, prod, exists) {
             push(ref, `directory does not exist and no script or build step creates it`);
             continue;
         }
-        const isSatisfied = candidates.some(c => {
-            if (prod.files.has(c))
-                return true;
-            if ([...prod.opaque].some(d => underDir(c, d)))
-                return true;
-            for (const [dir, stems] of prod.enumerable) {
-                if (underDir(path.posix.dirname(c), dir) && stems.has(stem(c)))
-                    return true;
-            }
-            return false;
-        });
+        const isSatisfied = candidates.some(c => fileProduced(c, prod));
         if (isSatisfied)
             continue;
         // Positive-evidence branches:
@@ -644,7 +839,14 @@ function scanCandidates(cwd, prod) {
  */
 export function findDanglingArtifacts(cwd) {
     const prod = discoverProducers(cwd);
+    // Second, PRODUCTION-only table: identical machinery minus watch/dev scripts.
+    // Generated-HTML refs resolve against this one, so a file whose only producer
+    // is `dev:css --watch` does not close a reference the built page makes
+    // (nexttask 3's load-bearing rule). Everything else keeps resolving against
+    // the full table, so no existing finding moves.
+    const prodProduction = discoverProducers(cwd, { excludeDevScripts: true });
     const refs = [];
+    const sources = [];
     for (const rel of scanCandidates(cwd, prod)) {
         let src;
         try {
@@ -659,12 +861,63 @@ export function findDanglingArtifacts(cwd) {
         else {
             refs.push(...extractJsRefs(src, rel));
             collectProducersFromSource(src, prod);
+            collectProducersFromSource(src, prodProduction);
+            sources.push({ rel, src });
         }
     }
     for (const [name, body] of Object.entries(packageScripts(cwd))) {
         refs.push(...extractScriptEntrypoints(body, `package.json scripts.${name}`));
     }
-    return resolveDanglingRefs(refs, prod, rel => existsSync(path.join(cwd, rel)));
+    const out = resolveDanglingRefs(refs, prod, rel => existsSync(path.join(cwd, rel)));
+    // Generated HTML runs in a SECOND pass: whether a literal counts as a build
+    // artifact depends on outdirs any source in the tree may have declared, so
+    // the producer table has to be complete first.
+    const generated = [];
+    for (const { rel, src } of sources) {
+        generated.push(...extractGeneratedHtmlRefs(src, rel, prodProduction));
+    }
+    const seen = new Set(out.map(d => `${d.referencer} ${d.path}`));
+    for (const d of resolveDanglingRefs(generated, prodProduction, rel => existsSync(path.join(cwd, rel)))) {
+        if (seen.has(`${d.referencer} ${d.path}`))
+            continue;
+        seen.add(`${d.referencer} ${d.path}`);
+        out.push(d);
+    }
+    return out;
+}
+/** Classify one generated-HTML ref against both producer tables (STEP 0 / A/B
+ *  reporting; the gate itself only needs the dangling verdict). */
+export function classifyGeneratedHtmlRef(ref, full, production, exists) {
+    if (exists(ref.path) || fileProduced(ref.path, production))
+        return 'produced';
+    if (fileProduced(ref.path, full))
+        return 'dev-only';
+    return 'missing';
+}
+/** STEP 0 / A/B helper: every generated-HTML asset ref in a tree, with the
+ *  producer tables it was measured against. Read-only, deterministic. */
+export function collectGeneratedHtmlRefs(cwd) {
+    const full = discoverProducers(cwd);
+    const production = discoverProducers(cwd, { excludeDevScripts: true });
+    const sources = [];
+    for (const rel of scanCandidates(cwd, full)) {
+        if (SCAN_HTML_RE.test(rel))
+            continue;
+        let src;
+        try {
+            src = readFileSync(path.join(cwd, rel), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        collectProducersFromSource(src, full);
+        collectProducersFromSource(src, production);
+        sources.push({ rel, src });
+    }
+    const refs = [];
+    for (const { rel, src } of sources)
+        refs.push(...extractGeneratedHtmlRefs(src, rel, production));
+    return { refs, full, production };
 }
 /** Ranked-failure text for the final gate (names referencer + missing path). */
 export function danglingGateFailureText(d) {

package/dist/task/final-gate.d.ts

@@ -83,12 +83,57 @@ export declare function discoverIntegrationCommands(cwd: string): {
 };
 /** Every lockfile consistency check that applies to this tree (possibly none). */
 export declare function discoverLockfileChecks(cwd: string): HealthCommand[];
+/**
+ * Why this script is NOT a launch of the shipped app, or null when it plausibly
+ * is one (mx5 run 18, validated).
+ *
+ * Run 18's boot command resolved to `bun run dev`, whose body is
+ * `docker compose -f docker-compose.dev.yml up -d && until docker compose … pg_isready
+ * … && concurrently "bun run dev:css" "bun run dev:js" "bun run --watch
+ * src/server/index.ts"`. The gate sandbox has no docker, so the chain died at 127 and
+ * the boot SKIPPED as an environment gap — while the shipped app had no HTTP listener
+ * at all. A script whose first act is `docker compose up` cannot distinguish "the app
+ * is broken" from "this box has no docker", so it is not evidence either way: better
+ * to discover NO boot command — reported as "nothing to boot" — and let the static
+ * serve-entry check (serve-entry.ts) carry the signal, than to spend the grace window
+ * producing an unfalsifiable skip.
+ *
+ * CONSERVATIVE AND LEXICAL BY CONSTRUCTION. Only two shapes are rejected, both
+ * decidable from the script text alone:
+ *   1. the chain OPENS with container orchestration (docker/podman/nerdctl … up|start|run);
+ *   2. the whole body is a multiplexer (concurrently/npm-run-all/run-p/run-s/turbo)
+ *      whose every child is an ASSET watcher in watch mode (tailwind/tsc/esbuild/…),
+ *      i.e. nothing in it can ever listen.
+ * Anything else — `vite`, `next dev`, `node dist/index.js`, `nodemon`, `bun --watch
+ * src/index.ts`, and any multiplexer with one non-asset child — is accepted
+ * unchanged. Deciding whether a watcher actually SERVES is not attempted here; that
+ * is exactly what the static serve-entry check is for.
+ */
+export declare function nonLaunchScriptReason(body: string, scripts?: Record<string, string>): string | null;
 /**
  * The project's OWN launch command, if it declares one (package.json `start`,
  * else `dev`; Makefile `run`). null means the project has nothing to boot —
  * the boot check degrades to nothing-to-run.
+ *
+ * A script that is not a LAUNCH at all (nonLaunchScriptReason — mx5 run 18's
+ * `docker compose up` orchestrator) is rejected here and falls through to the
+ * next candidate, then to null. Discovering nothing is strictly better than
+ * discovering something unfalsifiable: an env-gap skip of an orchestration script
+ * says nothing about the app, and null is reported as "nothing to boot".
  */
 export declare function discoverBootCommand(cwd: string): HealthCommand | null;
+/**
+ * The launch script that EXISTS but was rejected as not-a-launch, if any. Without
+ * this the rejection would trade run 18's unfalsifiable skip for pure silence: no
+ * boot command means bootSkipVerdict has no label to name, and a project whose test
+ * suite ran still reports `observed > 0`, so unobservedVerdict stays quiet too. A
+ * served app whose only declared launch script cannot start it was not observed to
+ * run, and must say so.
+ */
+export declare function rejectedLaunchScript(cwd: string): {
+    name: string;
+    reason: string;
+} | null;
 type BootOutcome = {
     outcome: 'skip' | 'pass';
     /** Set when the render check could not OBSERVE the served page (no browser,

package/dist/task/final-gate.js

@@ -58,6 +58,7 @@ import { collectProjectEnv, pinnedLocalPort, runDeepRenderCheck } from './deep-r
 import { resolveRunner, runnerEnv } from './runner-resolve.js';
 import { taskThatIntroduced } from './task-provenance.js';
 import { findDanglingArtifacts, danglingGateFailureText } from './artifact-closure.js';
+import { findMissingServeEntry, serveEntryGateFailureText } from './serve-entry.js';
 function packageScripts(cwd) {
     try {
         const j = JSON.parse(readFileSync(path.join(cwd, 'package.json'), 'utf8'));
@@ -192,16 +193,128 @@ export function discoverLockfileChecks(cwd) {
     }
     return cmds;
 }
+/** Leading `FOO=bar` env assignments and `sudo`/`exec` wrappers carry no verb. */
+function commandTokens(member) {
+    const t = member.trim().split(/\s+/).filter(Boolean);
+    while (t.length > 0
+        && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(t[0]) || /^(?:sudo|exec|env)$/.test(t[0]))) {
+        t.shift();
+    }
+    return t;
+}
+/** The chain members of a shell script body, in order (`&&`, `||`, `;`, `|`). */
+function chainMembers(body) {
+    return body
+        .split(/&&|\|\||;|\|/)
+        .map(s => s.trim())
+        .filter(s => s.length > 0);
+}
+/** Container/infra orchestration: `docker compose … up`, `docker-compose … up -d`,
+ *  `podman-compose … up`, `docker run …`. The verb must be a bare token, so a
+ *  filename like `docker-compose.dev.yml` never counts as one. */
+function isContainerOrchestration(member) {
+    const t = commandTokens(member);
+    if (t.length === 0)
+        return false;
+    const bin = path.posix.basename(t[0]);
+    if (!/^(?:docker|podman|nerdctl)(?:-compose)?$/.test(bin))
+        return false;
+    const verbs = new Set(['up', 'start', 'run']);
+    return t.slice(1).some(tok => verbs.has(tok));
+}
+const MULTIPLEXER_RE = /^(?:concurrently|npm-run-all|run-p|run-s|turbo)$/;
+/** A watcher that recompiles ASSETS and never listens: the tool is a
+ *  bundler/compiler/preprocessor AND it is in watch mode. `bun run --watch x.ts`
+ *  is deliberately NOT here — that re-executes an entrypoint, which may serve. */
+const ASSET_TOOL_RE = /(?:^|[\s/@])(?:tailwindcss|postcss|sass|node-sass|less|stylus|esbuild|rollup|webpack|parcel|swc|babel|tsc|tsup|chokidar)(?:$|[\s"'])/;
+const WATCH_FLAG_RE = /(?:^|\s)(?:--watch|-w|--watch=[^\s]*)(?:\s|$)/;
+/** The quoted commands a multiplexer runs, or its bare script-name arguments
+ *  resolved through the manifest (`run-p dev:css dev:js`). One level only. */
+function multiplexerChildren(member, scripts) {
+    const quoted = [...member.matchAll(/"([^"]+)"|'([^']+)'/g)].map(m => m[1] ?? m[2]);
+    if (quoted.length > 0)
+        return quoted;
+    const t = commandTokens(member)
+        .slice(1)
+        .filter(a => !a.startsWith('-'));
+    return t.flatMap(name => (scripts[name] !== undefined ? [scripts[name]] : []));
+}
+/** Every member of the chain that could plausibly stay up and serve. Members that
+ *  are one-shot setup (`mkdir`, `sleep`, an `until … done` wait loop) are not
+ *  themselves launches, but they are not disqualifying either — only the two
+ *  shapes below are. */
+function isWatcherOnlyMultiplexer(member, scripts) {
+    const t = commandTokens(member);
+    if (t.length === 0)
+        return false;
+    const bin = path.posix.basename(t[0]);
+    const runner = /^(?:npx|bunx|pnpm|yarn|npm)$/.test(bin);
+    const head = runner ?
+        (t.slice(1).find(a => !a.startsWith('-') && a !== 'exec' && a !== 'dlx' && a !== 'run')
+            ?? '')
+        : bin;
+    if (!MULTIPLEXER_RE.test(path.posix.basename(head)))
+        return false;
+    const children = multiplexerChildren(member, scripts);
+    if (children.length === 0)
+        return false;
+    // Every child is an ASSET watcher ⇒ nothing in here ever listens.
+    return children.every(c => ASSET_TOOL_RE.test(c) && WATCH_FLAG_RE.test(c));
+}
+/**
+ * Why this script is NOT a launch of the shipped app, or null when it plausibly
+ * is one (mx5 run 18, validated).
+ *
+ * Run 18's boot command resolved to `bun run dev`, whose body is
+ * `docker compose -f docker-compose.dev.yml up -d && until docker compose … pg_isready
+ * … && concurrently "bun run dev:css" "bun run dev:js" "bun run --watch
+ * src/server/index.ts"`. The gate sandbox has no docker, so the chain died at 127 and
+ * the boot SKIPPED as an environment gap — while the shipped app had no HTTP listener
+ * at all. A script whose first act is `docker compose up` cannot distinguish "the app
+ * is broken" from "this box has no docker", so it is not evidence either way: better
+ * to discover NO boot command — reported as "nothing to boot" — and let the static
+ * serve-entry check (serve-entry.ts) carry the signal, than to spend the grace window
+ * producing an unfalsifiable skip.
+ *
+ * CONSERVATIVE AND LEXICAL BY CONSTRUCTION. Only two shapes are rejected, both
+ * decidable from the script text alone:
+ *   1. the chain OPENS with container orchestration (docker/podman/nerdctl … up|start|run);
+ *   2. the whole body is a multiplexer (concurrently/npm-run-all/run-p/run-s/turbo)
+ *      whose every child is an ASSET watcher in watch mode (tailwind/tsc/esbuild/…),
+ *      i.e. nothing in it can ever listen.
+ * Anything else — `vite`, `next dev`, `node dist/index.js`, `nodemon`, `bun --watch
+ * src/index.ts`, and any multiplexer with one non-asset child — is accepted
+ * unchanged. Deciding whether a watcher actually SERVES is not attempted here; that
+ * is exactly what the static serve-entry check is for.
+ */
+export function nonLaunchScriptReason(body, scripts = {}) {
+    const members = chainMembers(body);
+    if (members.length === 0)
+        return null;
+    if (isContainerOrchestration(members[0])) {
+        return 'it opens with container orchestration, which starts infrastructure rather than the app';
+    }
+    if (members.every(m => isWatcherOnlyMultiplexer(m, scripts))) {
+        return 'its only long-running member multiplexes asset watchers, none of which serves';
+    }
+    return null;
+}
 /**
  * The project's OWN launch command, if it declares one (package.json `start`,
  * else `dev`; Makefile `run`). null means the project has nothing to boot —
  * the boot check degrades to nothing-to-run.
+ *
+ * A script that is not a LAUNCH at all (nonLaunchScriptReason — mx5 run 18's
+ * `docker compose up` orchestrator) is rejected here and falls through to the
+ * next candidate, then to null. Discovering nothing is strictly better than
+ * discovering something unfalsifiable: an env-gap skip of an orchestration script
+ * says nothing about the app, and null is reported as "nothing to boot".
  */
 export function discoverBootCommand(cwd) {
     if (existsSync(path.join(cwd, 'package.json'))) {
         const s = packageScripts(cwd);
         for (const name of ['start', 'dev']) {
-            if (s[name])
+            if (s[name] && nonLaunchScriptReason(s[name], s) === null)
                 return ['bun', ['run', name]];
         }
         return null;
@@ -211,6 +324,28 @@ export function discoverBootCommand(cwd) {
     }
     return null;
 }
+/**
+ * The launch script that EXISTS but was rejected as not-a-launch, if any. Without
+ * this the rejection would trade run 18's unfalsifiable skip for pure silence: no
+ * boot command means bootSkipVerdict has no label to name, and a project whose test
+ * suite ran still reports `observed > 0`, so unobservedVerdict stays quiet too. A
+ * served app whose only declared launch script cannot start it was not observed to
+ * run, and must say so.
+ */
+export function rejectedLaunchScript(cwd) {
+    if (!existsSync(path.join(cwd, 'package.json')))
+        return null;
+    const s = packageScripts(cwd);
+    for (const name of ['start', 'dev']) {
+        if (!s[name])
+            continue;
+        const reason = nonLaunchScriptReason(s[name], s);
+        if (reason === null)
+            return null; // this one IS a launch — it was chosen
+        return { name, reason };
+    }
+    return null;
+}
 /** Recognise an "address already in use" bind failure across runtimes (Node
  *  EADDRINUSE, Bun "Is port N in use?", Go "address already in use", generic). */
 function isAddressInUse(text) {
@@ -1058,6 +1193,23 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
             fail(`launch contract: the design declares script(s) the shipped package.json does not expose: ${missing.join(', ')} (declared: ${declared.join(', ')})`);
         }
     }
+    // Serve-entry closure (mx5 run 18, nexttask 2B): the tree builds a server app,
+    // expects to serve (SPA fallback / static read / a design clause), and NOTHING
+    // anywhere starts a listener — `src/server/index.ts` ended at `export {app}`, so
+    // the product could not be started at all while every dynamic probe went blind on
+    // a docker-less box. Static, deterministic, milliseconds, and — unlike the boot
+    // check — decidable in exactly the environment where the boot skipped. Rank 0:
+    // "the app cannot be started" is the same load-bearing class as boot/render.
+    // Placed BEFORE the zero-discovery early return on purpose: a project with no
+    // runnable command at all must still fail this, not report UNOBSERVED.
+    try {
+        const noServeEntry = findMissingServeEntry(cwd, planText);
+        if (noServeEntry)
+            fail(serveEntryGateFailureText(noServeEntry), 0);
+    }
+    catch {
+        // best-effort scan — a scanner fault must never break the gate
+    }
     const lockCmds = discoverLockfileChecks(cwd);
     const { cmds } = discoverIntegrationCommands(cwd);
     const boot = discoverBootCommand(cwd);
@@ -1225,6 +1377,18 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
                 warnings.push(b.renderNote);
         }
     }
+    else {
+        // Nothing to boot — but if the reason is that the project's only launch
+        // script was REJECTED as not-a-launch (2A), that is not the same thing as a
+        // project with no launch surface, and it must not degrade into silence.
+        const rejected = rejectedLaunchScript(cwd);
+        if (rejected && detectsServedApp(cwd, planText)) {
+            bootUnobserved =
+                `boot check: this project's only launch script (\`${rejected.name}\`) is not a `
+                    + `launch — ${rejected.reason} — so nothing was started and the app was never `
+                    + 'observed to run.';
+        }
+    }
     // Full-skip blindness guard (mx5 run 16): commands were discovered but every
     // one skipped → rank-0 failure, never a static-only PASS. Runner resolvability
     // is checked through resolveRunner so the failure text can name the missing

package/dist/task/serve-entry.d.ts

@@ -0,0 +1,60 @@
+export interface ServeEntryFinding {
+    /** Repo-relative module that constructs the app and is the natural home for the bind. */
+    file: string;
+    /** The construct that matched there (`new Hono()`, `express()`, …). */
+    construct: string;
+    /** Why this project is expected to serve, in words. */
+    expectation: string;
+    /** Where that expectation was found (repo-relative file, or 'the design/spec'). */
+    expectationSource: string;
+    /** Every construction file found, for the report. */
+    appFiles: string[];
+}
+/** Constructions in one source file, plus the variable each was assigned to. */
+export declare function findAppConstructions(raw: string): Array<{
+    construct: string;
+    name: string | null;
+}>;
+/** Bind evidence in one source file, or null. */
+export declare function findBindEvidence(src: string, appNames?: Set<string>): string | null;
+/** Why this file makes the project a SERVING one, or null. */
+export declare function findServeExpectation(src: string): string | null;
+/** A design/spec clause that names a served path — the plan-side half of the same
+ *  expectation (mx5's `DESIGN/PROJECT.md:285`: "serves `/api` + static `dist/`"). */
+export declare function planExpectsServing(planText: string | undefined): string | null;
+/** The platform that would bind on this project's behalf, or null. */
+export declare function opaqueLauncher(cwd: string): string | null;
+/** What a whole tree looks like to this check — the base-rate row, and the
+ *  intermediate the finding is derived from. */
+export interface ServeEntryScan {
+    /** Files that construct a server app, with the construct that matched. */
+    apps: Array<{
+        file: string;
+        construct: string;
+        name: string | null;
+    }>;
+    /** The first bind found anywhere, with its file. */
+    bind: {
+        file: string;
+        what: string;
+    } | null;
+    /** Why the project is expected to serve, with its source. */
+    expectation: {
+        source: string;
+        what: string;
+    } | null;
+    /** Non-null ⇒ somebody else's launcher owns the listener; the check stands down. */
+    launcher: string | null;
+    filesScanned: number;
+}
+/** Read the tree once and answer all three questions. Read-only, deterministic. */
+export declare function scanServeEntry(cwd: string, planText?: string): ServeEntryScan;
+/**
+ * FINAL-GATE seam: does this project build a server app it expects to serve, with
+ * nothing anywhere to start it? Returns at most ONE finding — the defect is a
+ * property of the whole tree, not of each file. Best-effort and read-only.
+ */
+export declare function findMissingServeEntry(cwd: string, planText?: string): ServeEntryFinding | null;
+/** Ranked-failure text for the final gate. Names the module that must bind and the
+ *  reason the project is a serving one, so the autofix child has both halves. */
+export declare function serveEntryGateFailureText(f: ServeEntryFinding): string;

package/dist/task/serve-entry.js

@@ -0,0 +1,343 @@
+/**
+ * serve-entry — the project builds a server app, expects to SERVE, and nothing in
+ * the tree ever starts a listener (nexttask 2 part B).
+ *
+ * THE FAILURE THIS CLOSES (mx5 run 18, measured). The shipped `src/server/index.ts`
+ * is 28 lines that construct a Hono app, mount five `/api` routers, add an SPA
+ * fallback reading `Bun.file('dist/index.html')` — and end at `export {app}`. There
+ * is no `Bun.serve`, no `export default app`, no `serve()` from an adapter, no
+ * `start` script. Running the entry directly exits 0 in milliseconds:
+ *
+ *     $ DATABASE_URL=… timeout 15 bun run src/server/index.ts   → EXIT=0
+ *
+ * The product could not be started at all, and the run shipped green: the gate's
+ * boot command resolved to a `docker compose up` orchestrator, docker was absent in
+ * the sandbox, and the boot SKIPPED. This is the SECOND run to lose this exact
+ * clause — mx5 run 16 shipped a server that never served the client bundle
+ * (scripts/live-owned-requirement-compose-ab.ts) — so a dynamic-only gate has now
+ * failed to catch it twice.
+ *
+ * WHY STATIC. The check needs no runtime, no browser, no docker, no database and no
+ * model: the tree either contains a bind or it does not. It runs in milliseconds and
+ * is decidable in exactly the environment where every dynamic probe went blind.
+ *
+ * FP DISCIPLINE (the standing rule — inconclusive is NEVER evidence). Three
+ * independent conditions must ALL hold before anything is reported, and each one
+ * steps aside on doubt:
+ *   1. a module CONSTRUCTS a server app (a known framework construct, literal);
+ *   2. the project is expected to SERVE (a catch-all route, a static/dist read, a
+ *      static-file middleware, or a design clause naming a served path);
+ *   3. NOTHING anywhere in the scanned tree binds — `Bun.serve(`/`Deno.serve(`,
+ *      any `.listen(`, an adapter `serve(` import, `export default <the app>` or
+ *      `export default {fetch…}` (the Workers/Bun default-export protocol),
+ *      `app.fire()`, or a platform handler export.
+ * And a project whose LAUNCHER is somebody else's (next/nuxt/astro/remix/sveltekit/
+ * nest/wrangler/vercel/netlify/serverless/…, by dependency or by script) steps aside
+ * whole: those frameworks bind inside their own CLI, so their app modules correctly
+ * contain no listener and the question is not decidable from this tree.
+ *
+ * Ground truth is the file tree only. No model, no network.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import * as path from 'node:path';
+/** A server-app construction: framework, and the regex that recognises it. */
+const CONSTRUCT_PATTERNS = [
+    { re: /\bnew\s+Hono\s*[<(]/, construct: 'new Hono()' },
+    { re: /\bnew\s+Elysia\s*[<(]/, construct: 'new Elysia()' },
+    { re: /\bnew\s+Koa\s*\(/, construct: 'new Koa()' },
+    { re: /\bnew\s+Application\s*\(\s*\)/, construct: 'new Application()' },
+    { re: /(?:^|[^.\w])express\s*\(\s*\)/, construct: 'express()' },
+    { re: /(?:^|[^.\w])[Ff]astify\s*\(/, construct: 'fastify()' },
+    { re: /(?:^|[^.\w])polka\s*\(/, construct: 'polka()' }
+    // `connect()` (the middleware framework) is deliberately absent: gofer's
+    // src/store/db.ts calls `connect()` on a DATABASE, and a construct signal that
+    // cannot tell a server from a db handle is not a construct signal.
+];
+/**
+ * Anything that starts (or hands off) a listener. Deliberately GENEROUS: every
+ * pattern here SUPPRESSES a finding, so a loose match costs a missed defect while a
+ * tight one costs a false accusation — and the standing direction is that a false
+ * accusation is the worse failure.
+ */
+const BIND_PATTERNS = [
+    { re: /\bBun\s*\.\s*serve\s*\(/, what: 'Bun.serve(' },
+    { re: /\bDeno\s*\.\s*serve\s*\(/, what: 'Deno.serve(' },
+    { re: /\.listen\s*\(/, what: '.listen(' },
+    { re: /\bcreateServer\s*\([^)]*\)\s*\.\s*listen/, what: 'createServer().listen(' },
+    { re: /\.\s*fire\s*\(\s*\)/, what: 'app.fire()' },
+    { re: /\bserveHandler\s*\(|\bstartServer\s*\(/, what: 'a server-start helper' }
+];
+/** `export default` forms that ARE a bind: the runtime (Bun, Workers, Deno Deploy,
+ *  Vercel) starts whatever is exported. A default-exported config object
+ *  (`export default defineConfig({…})`) is not one of them, and neither is a React
+ *  component — hence the identifier must be a name the tree BOUND to a server-app
+ *  construction (aiz-client's `export default App` is a component, not a listener). */
+function defaultExportBind(src, appNames) {
+    for (const m of src.matchAll(/export\s+default\s+([A-Za-z_$][\w$]*)/g)) {
+        if (appNames.has(m[1]))
+            return `export default ${m[1]}`;
+    }
+    // `export default {fetch: app.fetch, port}` / `export default {async fetch(…)}` —
+    // the Workers/Bun protocol. The `fetch` key must be in the same object literal.
+    for (const m of src.matchAll(/export\s+default\s*\{([\s\S]{0,400}?)\}/g)) {
+        if (/(?:^|[\s,{])(?:async\s+)?fetch\s*[:(]/.test(m[1]))
+            return 'export default {fetch…}';
+    }
+    if (/export\s+default\s+(?:handle|serve|createHandler)\s*\(/.test(src)) {
+        return 'export default handle(app)';
+    }
+    return null;
+}
+/** An adapter whose `serve(app)` binds for you (`@hono/node-server`, `srvx`, …). */
+function adapterServeBind(src) {
+    const importsAdapter = /from\s+['"](?:@hono\/node-server|srvx|@fastify\/[\w-]+|h3|listhen)['"]/.test(src);
+    return importsAdapter && /(?:^|[^.\w])(?:serve|listen)\s*\(/.test(src) ?
+        'serve() from a server adapter'
+        : null;
+}
+/** Blank out same-line string literals. Real code never constructs an app inside a
+ *  quote, but a module that NAMES the constructs — a detector, a doc, this file's
+ *  own `construct: 'new Hono()'` labels — otherwise reads as seven server apps.
+ *  Applied to construction matching only: the serve-expectation patterns are ABOUT
+ *  string literals (`app.get('*')`, `Bun.file('dist/…')`) and must keep them. */
+function stripStringLiterals(src) {
+    return src.replace(/'[^'\n]*'|"[^"\n]*"/g, "''");
+}
+/** Constructions in one source file, plus the variable each was assigned to. */
+export function findAppConstructions(raw) {
+    const src = stripStringLiterals(raw);
+    const out = [];
+    for (const { re, construct } of CONSTRUCT_PATTERNS) {
+        if (!re.test(src))
+            continue;
+        // `const app = new Hono()` → remember `app`, so `export default app` counts.
+        const assign = new RegExp(`(?:const|let|var)\\s+([A-Za-z_$][\\w$]*)\\s*(?::[^=]{0,80})?=\\s*[^=]{0,40}?${re.source}`).exec(src);
+        out.push({ construct, name: assign ? assign[1] : null });
+    }
+    return out;
+}
+/** Bind evidence in one source file, or null. */
+export function findBindEvidence(src, appNames = new Set()) {
+    for (const { re, what } of BIND_PATTERNS) {
+        if (re.test(src))
+            return what;
+    }
+    return defaultExportBind(src, appNames) ?? adapterServeBind(src);
+}
+const SERVE_EXPECTATIONS = [
+    {
+        re: /\.\s*(?:get|all|use|route)\s*\(\s*['"`]\/?\*['"`]/,
+        what: 'a catch-all route (the SPA fallback)'
+    },
+    {
+        re: /(?:Bun\s*\.\s*file|readFileSync|readFile|createReadStream|sendFile)\s*\(\s*['"`]\.?\/?(?:dist|build|out|public|static|client|assets)\//,
+        what: 'a read of a built asset under dist/ (the client bundle)'
+    },
+    { re: /\bserveStatic\s*\(/, what: 'static-file middleware (serveStatic)' },
+    { re: /\bexpress\s*\.\s*static\s*\(/, what: 'static-file middleware (express.static)' },
+    { re: /\bfastifyStatic\b|@fastify\/static/, what: 'static-file middleware (@fastify/static)' }
+];
+/** Why this file makes the project a SERVING one, or null. */
+export function findServeExpectation(src) {
+    for (const { re, what } of SERVE_EXPECTATIONS) {
+        if (re.test(src))
+            return what;
+    }
+    return null;
+}
+/** A design/spec clause that names a served path — the plan-side half of the same
+ *  expectation (mx5's `DESIGN/PROJECT.md:285`: "serves `/api` + static `dist/`"). */
+export function planExpectsServing(planText) {
+    if (!planText)
+        return null;
+    const re = /\bserves?\b[^\n]{0,120}?\b(?:static|dist\/?|client|bundle|index\.html|spa|frontend)\b/i;
+    const m = re.exec(planText);
+    return m ? `the design declares a served path ("${m[0].trim().slice(0, 100)}")` : null;
+}
+/**
+ * Frameworks and platforms that own the listener themselves. When one of these is a
+ * dependency or drives a script, an app module with no bind is CORRECT, so the whole
+ * check steps aside — it is not decidable from this tree.
+ */
+const LAUNCHER_DEPS = /^(?:next|nuxt|nuxt3|astro|@remix-run\/|@sveltejs\/kit|@nestjs\/core|@angular\/|@adonisjs\/core|redwoodjs|blitz|wrangler|@cloudflare\/|vercel|@vercel\/|netlify-cli|@netlify\/|serverless|serverless-http|firebase-functions|aws-lambda|@aws-sdk\/client-lambda|sst|nitropack|encore\.dev|@medusajs\/|keystone|payload|gatsby|@builder\.io\/qwik-city)/;
+const LAUNCHER_SCRIPT_RE = /\b(?:next|nuxt|astro|remix-serve|nest|wrangler|vercel|netlify|sst|gatsby|blitz|redwood|encore|payload|medusa)\s+(?:dev|start|serve|build\s+&&|run\b)/;
+/** The platform that would bind on this project's behalf, or null. */
+export function opaqueLauncher(cwd) {
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    const deps = Object.keys({ ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) });
+    const dep = deps.find(d => LAUNCHER_DEPS.test(d));
+    if (dep)
+        return `the \`${dep}\` framework starts its own server`;
+    for (const [name, body] of Object.entries(pkg.scripts ?? {})) {
+        if (LAUNCHER_SCRIPT_RE.test(body))
+            return `\`${name}\` runs a framework launcher (${body.slice(0, 60)})`;
+    }
+    return null;
+}
+// Directories never scanned: VCS/dep trees, build output (bundled copies of the
+// same sources), and test/fixture/example/doc trees — a test that stands up a
+// throwaway listener is not the app's launch, and a doc snippet is not code.
+const SKIP_DIR_RE = /^(?:\.git|node_modules|\.pi-tasks|dist|build|out|coverage|target|vendor|__pycache__|\.venv|venv|tmp|test|tests|__tests__|__mocks__|__fixtures__|fixtures|e2e|examples|example|docs|doc|bench|benchmarks)$/;
+const SKIP_FILE_RE = /\.(?:test|spec|stories|bench)\.[a-z]+$|\.d\.[mc]?ts$/i;
+const SCAN_RE = /\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts)$/i;
+const MAX_SCAN_FILES = 3000;
+const MAX_FILE_BYTES = 400_000;
+/** Authored sources, bounded and in deterministic order. */
+function scanCandidates(cwd) {
+    const out = [];
+    const walk = (rel) => {
+        if (out.length >= MAX_SCAN_FILES)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(path.join(cwd, rel)).sort();
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            if (out.length >= MAX_SCAN_FILES)
+                return;
+            const relPath = rel === '' ? name : `${rel}/${name}`;
+            let st;
+            try {
+                st = statSync(path.join(cwd, relPath));
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                if (name.startsWith('.') || SKIP_DIR_RE.test(name))
+                    continue;
+                walk(relPath);
+            }
+            else if (st.isFile() && st.size <= MAX_FILE_BYTES) {
+                if (SKIP_FILE_RE.test(name))
+                    continue;
+                if (SCAN_RE.test(name))
+                    out.push(relPath);
+            }
+        }
+    };
+    walk('');
+    return out;
+}
+/** Strip comment-only lines — a `Bun.serve` quoted in a comment is not a bind, and
+ *  a commented-out catch-all is not a route. Inline comments are left alone. */
+function stripCommentLines(src) {
+    return src
+        .split('\n')
+        .filter(l => !/^\s*(?:\/\/|\*|\/\*)/.test(l))
+        .join('\n');
+}
+/** A `/…/flags` literal whose body carries a regex METACHARACTER — `[`, `\`, `+`,
+ *  `?`, `|`, a group. A path string like `'/api/admin'` has none, so it survives. */
+const REGEX_LITERAL_RE = /\/(?![*/])((?:\\.|\[(?:\\.|[^\]\\])*\]|[^/\\\n])+)\/[gimsuyd]*/g;
+const METACHAR_RE = /[\\[\]+*?^$|(){}]/;
+/**
+ * Blank out regex literals. A project that MATCHES on `new Hono` — a linter, a
+ * codemod, this very module — does not construct one, and a source scanner that
+ * cannot tell the two apart reports every detector as an app (pi-task scanned
+ * itself and found "9 server apps", all of them pattern tables). Only literals
+ * carrying a metacharacter are stripped, so `'/api/v1'` is untouched, and because
+ * stripping can only REMOVE matches it is safe in the FP direction by construction.
+ */
+function stripRegexLiterals(src) {
+    return src.replace(REGEX_LITERAL_RE, (whole, body) => METACHAR_RE.test(body) ? ' ' : whole);
+}
+/** Read the tree once and answer all three questions. Read-only, deterministic. */
+export function scanServeEntry(cwd, planText) {
+    const scan = {
+        apps: [],
+        bind: null,
+        expectation: null,
+        launcher: opaqueLauncher(cwd),
+        filesScanned: 0
+    };
+    const files = scanCandidates(cwd);
+    scan.filesScanned = files.length;
+    // Two passes: constructions first, so `export default app` can be resolved
+    // against the app variable names the tree actually uses.
+    const sources = new Map();
+    const appNames = new Set();
+    for (const rel of files) {
+        let src;
+        try {
+            src = stripRegexLiterals(stripCommentLines(readFileSync(path.join(cwd, rel), 'utf8')));
+        }
+        catch {
+            continue;
+        }
+        sources.set(rel, src);
+        for (const c of findAppConstructions(src)) {
+            scan.apps.push({ file: rel, construct: c.construct, name: c.name });
+            if (c.name)
+                appNames.add(c.name);
+        }
+    }
+    for (const [rel, src] of sources) {
+        if (scan.bind === null) {
+            const what = findBindEvidence(src, appNames);
+            if (what)
+                scan.bind = { file: rel, what };
+        }
+        if (scan.expectation === null) {
+            const what = findServeExpectation(src);
+            if (what)
+                scan.expectation = { source: rel, what };
+        }
+    }
+    if (scan.expectation === null) {
+        const fromPlan = planExpectsServing(planText);
+        if (fromPlan)
+            scan.expectation = { source: 'the design/spec', what: fromPlan };
+    }
+    return scan;
+}
+/** The construction file that should carry the bind: the one holding the serve
+ *  expectation, else the most entry-like name, else the first. */
+function entryFile(scan) {
+    const withExpectation = scan.apps.find(a => a.file === scan.expectation?.source);
+    if (withExpectation)
+        return withExpectation;
+    const entryish = scan.apps.find(a => /(?:^|\/)(?:index|main|server|app)\.[a-z]+$/i.test(a.file));
+    return entryish ?? scan.apps[0];
+}
+/**
+ * FINAL-GATE seam: does this project build a server app it expects to serve, with
+ * nothing anywhere to start it? Returns at most ONE finding — the defect is a
+ * property of the whole tree, not of each file. Best-effort and read-only.
+ */
+export function findMissingServeEntry(cwd, planText) {
+    const scan = scanServeEntry(cwd, planText);
+    if (scan.launcher !== null)
+        return null;
+    if (scan.apps.length === 0)
+        return null;
+    if (scan.bind !== null)
+        return null;
+    if (scan.expectation === null)
+        return null;
+    const { file, construct } = entryFile(scan);
+    return {
+        file,
+        construct,
+        expectation: scan.expectation.what,
+        expectationSource: scan.expectation.source,
+        appFiles: [...new Set(scan.apps.map(a => a.file))]
+    };
+}
+/** Ranked-failure text for the final gate. Names the module that must bind and the
+ *  reason the project is a serving one, so the autofix child has both halves. */
+export function serveEntryGateFailureText(f) {
+    return (`serve entry missing: \`${f.file}\` builds a server app (${f.construct}) and the project `
+        + `is expected to serve — ${f.expectation} in ${f.expectationSource === 'the design/spec' ? 'the design/spec' : `\`${f.expectationSource}\``} — `
+        + 'but NOTHING in the tree ever starts a listener (no `Bun.serve(`, `export default app`, '
+        + 'adapter `serve()`, or `.listen(`), so the app cannot be started at all');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.24.5",
+    "version": "0.26.0",
     "description": "Deterministic task planning and spec-orchestration for local models — crash-safe /task pipelines with verify/enforce gates, a real-time remote web view, and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",