@mjasnikovs/pi-task 0.24.5 → 0.25.0

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.25.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",