@mjasnikovs/pi-task 0.21.7 → 0.21.8

package/dist/task/deep-render-check.d.ts

@@ -0,0 +1,112 @@
+export type DeepRenderOutcome = {
+    outcome: 'pass';
+    detail: string;
+} | {
+    outcome: 'fail';
+    detail: string;
+} | {
+    outcome: 'skip';
+    note: string;
+};
+export interface LoginCredentials {
+    identifier: string;
+    password: string;
+    /** Key names only — the value is never logged or surfaced anywhere. */
+    identifierKey: string;
+    passwordKey: string;
+}
+/**
+ * Parse a dotenv-style file into a plain record. Deliberately minimal (KEY=VALUE,
+ * `export ` prefix, # comments, optional matching quotes) — this reads the same
+ * file the app's own runtime reads, and anything it cannot parse simply yields no
+ * credentials, which is a SKIP.
+ */
+export declare function parseEnvFile(text: string): Record<string, string>;
+/** The variables the booted app itself sees: its dotenv files, overlaid by the real
+ *  process environment (bun/node never let a file override an exported var). */
+export declare function collectProjectEnv(cwd: string, env?: NodeJS.ProcessEnv): Record<string, string>;
+/**
+ * A declared app-account credential PAIR sharing one prefix (`ADMIN_PHONE` +
+ * `ADMIN_PASSWORD` — exactly what the launch contract's seed step consumes), or
+ * null when the project declares none. Null is a SKIP, never a FAIL (I3): a gate
+ * that failed for missing credentials would fail every project that has no login.
+ */
+export declare function findLoginCredentials(vars: Record<string, string>): LoginCredentials | null;
+/**
+ * The LOCAL port the project's own client was built to call, when its dotenv pins
+ * one (`APP_URL=http://localhost:3000`, `VITE_API_URL=…`), else null.
+ *
+ * Why the boot check wants it (measured on mx5@373e88d, both directions): a bundler
+ * bakes that base URL into the client at BUILD time, so a client served on the
+ * gate's freshly-reserved private port calls an origin nothing is listening on. The
+ * app is then unusable for reasons that have nothing to do with the code, and the
+ * authenticated assertions cannot run at all — the sign-in POST leaves for the dead
+ * origin and never reaches the server we booted. Serving on the app's own declared
+ * port makes the session same-origin and the evidence real.
+ *
+ * This deliberately narrows the private-port ownership evidence of run 14, so it
+ * only applies when the port is LOCAL, DECLARED by the project itself, and CURRENTLY
+ * FREE — the caller checks freeness and falls back to a reserved port otherwise.
+ */
+export declare function pinnedLocalPort(vars: Record<string, string>): number | null;
+export interface DeepSessionFacts {
+    /** The landing page presented a sign-in wall (a visible password input). */
+    landingHadAuthWall: boolean;
+    /** A credential pair was declared by the project. */
+    credentialsFound: boolean;
+    /** The form could be filled and submitted. */
+    submitted: boolean;
+    /** The sign-in request the SUBMIT issued, when one was issued at all. */
+    authRequest: {
+        method: string;
+        path: string;
+        status: number | null;
+        failed: boolean;
+    } | null;
+    /** Same-origin XHR/fetch requests issued AFTER the sign-in response, excluding
+     *  the sign-in request itself. */
+    postAuthDataAttempted: number;
+    postAuthData2xx: number;
+    /** Origins the client called that are not the app's own, whose requests failed
+     *  (a bundle pinned to a build-time base URL that is not the port under test). */
+    foreignOriginFailures: string[];
+    /** No visible password input after settle, or the URL path changed. */
+    leftAuthWall: boolean;
+    urlBefore: string;
+    urlAfter: string;
+    /** judgeRenderedDom over the post-sign-in DOM. */
+    postAuthDomOk: boolean;
+    postAuthDomDetail: string;
+}
+/**
+ * Judge a recorded session. The ONE thing that may FAIL is a session the SERVER
+ * authenticated (2xx on the sign-in request) whose client then could not use it:
+ *
+ *   - never left the wall                → the run-17 signature exactly;
+ *   - data calls attempted, none 2xx     → the same class one page deeper;
+ *   - post-sign-in page renders blank    → the run-16 class behind the wall.
+ *
+ * Everything else is an environment or shape gap and SKIPs. Note what is NOT a
+ * failure: zero data calls attempted after sign-in. A server-rendered app that
+ * redirects to a fresh document legitimately issues no XHR at all, so the missing
+ * half is reported UNOBSERVED in the detail instead. (The task text asked for
+ * "≥1 same-origin /api/* 2xx during the session" as a hard assertion; STEP 0
+ * refuted that wording — the BROKEN mx5 build satisfies it with the probe's own
+ * login POST — so the assertion is registered post-auth and excludes the sign-in
+ * request. See the scratch REGISTERED-METRIC record quoted in the commit.)
+ */
+export declare function judgeDeepSession(f: DeepSessionFacts): DeepRenderOutcome;
+/** Whole-session wall-clock cap, including browser launch (I4). */
+export declare const DEEP_RENDER_TIMEOUT_MS = 45000;
+/**
+ * Drive one authenticated session against `url` and judge it. `cwd` is the project
+ * whose dotenv declares the account. Every failure mode of the DRIVER itself
+ * (no browser, launch failure, protocol error, timeout) resolves to SKIP: this
+ * check may only report on the app, never on itself.
+ */
+export declare function runDeepRenderCheck(url: string, cwd: string, opts?: {
+    browser?: string | null;
+    credentials?: LoginCredentials | null;
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+}): Promise<DeepRenderOutcome>;

package/dist/task/deep-render-check.js

@@ -0,0 +1,659 @@
+/**
+ * deep-render-check — sign in on the booted app and prove the AUTHENTICATED half
+ * of it is alive (mx5 run 17).
+ *
+ * The failure class this closes: the shallow render check (render-check.ts) loads
+ * ONE url and judges the rendered DOM. mx5 run 17 satisfies it completely while
+ * being unusable — GET / redirects to /login, the login page renders fully, and
+ * that is the whole check. Behind it, src/client/hooks/useAuth.ts called
+ * `typedClient.api.auth.me.get()`; hono RPC methods are `$get`/`$post`, so a bare
+ * `.get` is just another path segment in hono's createProxy and the call returns a
+ * request BUILDER that never issues a request. Login POSTs 200 and sets the
+ * session cookie, zero /api/auth/me requests are ever made, and the app bounces to
+ * /login forever. Seven call sites were dead the same way, mixed in the same files
+ * with correct `$get` ones — the signature of code no runtime ever executed. The
+ * server was healthy throughout: 134/134 tests, tsc clean, login 200, me-with-
+ * cookie 200. Nothing static could see it.
+ *
+ * The generic instrument is a NETWORK FACT: after a real sign-in, did the client
+ * actually leave the wall, and did its data calls actually reach the server. No
+ * cast, mock, replica or type assertion can fake a 2xx on the wire. Deliberately
+ * NOT a hono `.get`-vs-`$get` linter: that is a point fix for one library, while
+ * the runtime assertion catches the whole dead-client-call class for every client
+ * library.
+ *
+ * SCOPE HONESTY: this is WEB-ONLY. It runs only behind detectsServedApp() and does
+ * nothing for C++, Godot, CLI or library projects, which are most of the fleet. It
+ * is here because the class is the most expensive one observed — it ended run 16
+ * (blank page) and run 17 (dead login) outright.
+ *
+ * Mechanism, dependency-free: the same discovered Chrome-family binary the shallow
+ * check uses, driven over the DevTools protocol through the `ws` dependency the
+ * remote server already ships. Nothing is installed; no browser on the box → SKIP.
+ *
+ * WHAT MAY FAIL, and nothing else: only a session where the server ITSELF accepted
+ * our credentials (the sign-in request returned 2xx) and the client still could not
+ * use them. Every other outcome — no browser, no declared credentials, a form we
+ * could not drive, a sign-in the server rejected, a client pinned to another origin
+ * — is an environment gap and SKIPs with an UNOBSERVED note. See judgeDeepSession.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import WebSocket from 'ws';
+import { findHeadlessBrowser, judgeRenderedDom } from './render-check.js';
+/** Identifier halves of a credential pair, in preference order. */
+const IDENTIFIER_SUFFIXES = ['PHONE', 'EMAIL', 'USERNAME', 'USER', 'LOGIN', 'IDENTIFIER'];
+const PASSWORD_SUFFIXES = ['PASSWORD', 'PASSWD', 'PASS'];
+/** Prefixes whose `_PASSWORD` belongs to infrastructure, not to an app account.
+ *  `DB_USER`/`DB_PASSWORD` pair perfectly and would otherwise be tried as a login. */
+const INFRA_PREFIX_RE = /^(DATABASE|DB|POSTGRES|POSTGRESQL|PG|MYSQL|MARIADB|MONGO|MONGODB|REDIS|RABBIT|RABBITMQ|AMQP|KAFKA|SMTP|IMAP|MAIL|MAILER|S3|MINIO|AWS|GCP|AZURE|DOCKER|REGISTRY|NPM|GITHUB|GITLAB|PROXY|LDAP|VAULT|GRAFANA|SENTRY)$/i;
+/** Prefixes that name a seeded APP account, tried before any other pair. */
+const ACCOUNT_PREFIX_ORDER = ['ADMIN', 'TEST', 'E2E', 'SEED', 'DEV', 'DEFAULT', 'USER', 'LOGIN'];
+/** Split `ADMIN_PHONE` into prefix `ADMIN` + suffix `PHONE`; '' prefix for a bare
+ *  `PASSWORD`. Returns null when the key does not end in one of `suffixes`. */
+function splitKey(key, suffixes) {
+    const upper = key.toUpperCase();
+    for (const suffix of suffixes) {
+        if (upper === suffix)
+            return { prefix: '', suffix };
+        if (upper.endsWith(`_${suffix}`)) {
+            return { prefix: upper.slice(0, -(suffix.length + 1)), suffix };
+        }
+    }
+    return null;
+}
+/**
+ * Parse a dotenv-style file into a plain record. Deliberately minimal (KEY=VALUE,
+ * `export ` prefix, # comments, optional matching quotes) — this reads the same
+ * file the app's own runtime reads, and anything it cannot parse simply yields no
+ * credentials, which is a SKIP.
+ */
+export function parseEnvFile(text) {
+    const out = {};
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line.length === 0 || line.startsWith('#'))
+            continue;
+        const m = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+        if (!m)
+            continue;
+        let value = m[2].trim();
+        const quote = value[0];
+        if ((quote === '"' || quote === "'") && value.endsWith(quote) && value.length > 1) {
+            value = value.slice(1, -1);
+        }
+        else {
+            value = value.split(' #')[0].trim();
+        }
+        out[m[1]] = value;
+    }
+    return out;
+}
+/** The variables the booted app itself sees: its dotenv files, overlaid by the real
+ *  process environment (bun/node never let a file override an exported var). */
+export function collectProjectEnv(cwd, env = process.env) {
+    const merged = {};
+    for (const name of ['.env', '.env.local', '.env.development']) {
+        const file = path.join(cwd, name);
+        if (!existsSync(file))
+            continue;
+        try {
+            Object.assign(merged, parseEnvFile(readFileSync(file, 'utf8')));
+        }
+        catch {
+            // unreadable dotenv → no credentials from it, never a failure
+        }
+    }
+    for (const [k, v] of Object.entries(env)) {
+        if (typeof v === 'string' && v.length > 0)
+            merged[k] = v;
+    }
+    return merged;
+}
+/**
+ * A declared app-account credential PAIR sharing one prefix (`ADMIN_PHONE` +
+ * `ADMIN_PASSWORD` — exactly what the launch contract's seed step consumes), or
+ * null when the project declares none. Null is a SKIP, never a FAIL (I3): a gate
+ * that failed for missing credentials would fail every project that has no login.
+ */
+export function findLoginCredentials(vars) {
+    const passwords = new Map(); // prefix → key
+    const identifiers = new Map(); // prefix → keys, preference order
+    for (const key of Object.keys(vars)) {
+        if ((vars[key] ?? '').length === 0)
+            continue;
+        const pw = splitKey(key, PASSWORD_SUFFIXES);
+        if (pw && !INFRA_PREFIX_RE.test(pw.prefix) && !passwords.has(pw.prefix)) {
+            passwords.set(pw.prefix, key);
+            continue;
+        }
+        const id = splitKey(key, IDENTIFIER_SUFFIXES);
+        if (id && !INFRA_PREFIX_RE.test(id.prefix)) {
+            const list = identifiers.get(id.prefix) ?? [];
+            list.push(key);
+            identifiers.set(id.prefix, list);
+        }
+    }
+    const rank = (prefix) => {
+        const i = ACCOUNT_PREFIX_ORDER.indexOf(prefix);
+        return i === -1 ? ACCOUNT_PREFIX_ORDER.length : i;
+    };
+    const prefixes = [...passwords.keys()]
+        .filter(p => (identifiers.get(p) ?? []).length > 0)
+        .sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
+    const prefix = prefixes[0];
+    if (prefix === undefined)
+        return null;
+    const idKeys = identifiers.get(prefix) ?? [];
+    const bySuffix = (key) => {
+        const s = splitKey(key, IDENTIFIER_SUFFIXES);
+        return s ? IDENTIFIER_SUFFIXES.indexOf(s.suffix) : IDENTIFIER_SUFFIXES.length;
+    };
+    const identifierKey = [...idKeys].sort((a, b) => bySuffix(a) - bySuffix(b))[0];
+    const passwordKey = passwords.get(prefix);
+    if (!identifierKey || !passwordKey)
+        return null;
+    return {
+        identifier: vars[identifierKey],
+        password: vars[passwordKey],
+        identifierKey,
+        passwordKey
+    };
+}
+/**
+ * The LOCAL port the project's own client was built to call, when its dotenv pins
+ * one (`APP_URL=http://localhost:3000`, `VITE_API_URL=…`), else null.
+ *
+ * Why the boot check wants it (measured on mx5@373e88d, both directions): a bundler
+ * bakes that base URL into the client at BUILD time, so a client served on the
+ * gate's freshly-reserved private port calls an origin nothing is listening on. The
+ * app is then unusable for reasons that have nothing to do with the code, and the
+ * authenticated assertions cannot run at all — the sign-in POST leaves for the dead
+ * origin and never reaches the server we booted. Serving on the app's own declared
+ * port makes the session same-origin and the evidence real.
+ *
+ * This deliberately narrows the private-port ownership evidence of run 14, so it
+ * only applies when the port is LOCAL, DECLARED by the project itself, and CURRENTLY
+ * FREE — the caller checks freeness and falls back to a reserved port otherwise.
+ */
+export function pinnedLocalPort(vars) {
+    const ports = [];
+    for (const [key, value] of Object.entries(vars)) {
+        if (!/URL$/i.test(key) || typeof value !== 'string')
+            continue;
+        const m = /^https?:\/\/(?:localhost|127\.0\.0\.1|\[::1\]|0\.0\.0\.0)(?::(\d{2,5}))?(?:\/|$)/i.exec(value.trim());
+        if (!m)
+            continue;
+        const port = m[1] ? Number(m[1])
+            : value.trim().toLowerCase().startsWith('https') ? 443
+                : 80;
+        if (Number.isInteger(port) && port > 1024 && port < 65536)
+            ports.push(port);
+    }
+    return ports.length > 0 ? Math.min(...ports) : null;
+}
+/**
+ * Judge a recorded session. The ONE thing that may FAIL is a session the SERVER
+ * authenticated (2xx on the sign-in request) whose client then could not use it:
+ *
+ *   - never left the wall                → the run-17 signature exactly;
+ *   - data calls attempted, none 2xx     → the same class one page deeper;
+ *   - post-sign-in page renders blank    → the run-16 class behind the wall.
+ *
+ * Everything else is an environment or shape gap and SKIPs. Note what is NOT a
+ * failure: zero data calls attempted after sign-in. A server-rendered app that
+ * redirects to a fresh document legitimately issues no XHR at all, so the missing
+ * half is reported UNOBSERVED in the detail instead. (The task text asked for
+ * "≥1 same-origin /api/* 2xx during the session" as a hard assertion; STEP 0
+ * refuted that wording — the BROKEN mx5 build satisfies it with the probe's own
+ * login POST — so the assertion is registered post-auth and excludes the sign-in
+ * request. See the scratch REGISTERED-METRIC record quoted in the commit.)
+ */
+export function judgeDeepSession(f) {
+    if (!f.landingHadAuthWall) {
+        return {
+            outcome: 'pass',
+            detail: 'the landing page is not a sign-in wall — the authenticated assertions do not apply'
+        };
+    }
+    if (!f.credentialsFound) {
+        return {
+            outcome: 'skip',
+            note: 'the landing page is a sign-in wall but the project declares no account credentials '
+                + '(no matching <PREFIX>_PHONE/EMAIL/USER + <PREFIX>_PASSWORD pair) — the authenticated '
+                + 'half of the app was NOT observed'
+        };
+    }
+    if (!f.submitted) {
+        return {
+            outcome: 'skip',
+            note: 'the sign-in form could not be driven (no submit control found) — the authenticated half of the app was NOT observed'
+        };
+    }
+    if (f.authRequest === null) {
+        const pinned = f.foreignOriginFailures.length > 0 ?
+            ` — the client calls ${f.foreignOriginFailures.join(', ')}, not the origin under test (a base URL baked in at build time)`
+            : '';
+        return {
+            outcome: 'skip',
+            note: `submitting the sign-in form issued no request to the app's own origin${pinned} — the authenticated half of the app was NOT observed`
+        };
+    }
+    const { method, path: p, status, failed } = f.authRequest;
+    if (failed || status === null || status < 200 || status >= 300) {
+        return {
+            outcome: 'skip',
+            note: `the server did not accept the declared credentials (\`${method} ${p}\` → `
+                + `${failed ? 'request failed' : String(status)}) — with no authenticated session there is `
+                + 'nothing to assert; the authenticated half of the app was NOT observed'
+        };
+    }
+    const signedIn = `signed in (\`${method} ${p}\` → ${status})`;
+    if (!f.leftAuthWall) {
+        return {
+            outcome: 'fail',
+            detail: `${signedIn} but the client NEVER LEFT THE SIGN-IN WALL: the page is still `
+                + `${f.urlAfter} with a password field, and ${f.postAuthData2xx} of `
+                + `${f.postAuthDataAttempted} same-origin data request(s) after sign-in succeeded. `
+                + 'The server authenticated the session and the client could not use it — the dead '
+                + 'client-call class (a request builder that is never sent, a wrong RPC method name, '
+                + 'a handler that never fires). No type, cast or mock can produce the missing 2xx.'
+        };
+    }
+    if (!f.postAuthDomOk) {
+        return {
+            outcome: 'fail',
+            detail: `${signedIn} and reached ${f.urlAfter}, but ${f.postAuthDomDetail}`
+        };
+    }
+    if (f.postAuthDataAttempted > 0 && f.postAuthData2xx === 0) {
+        return {
+            outcome: 'fail',
+            detail: `${signedIn} and reached ${f.urlAfter}, but EVERY same-origin data request the `
+                + `authenticated client made failed: 0 of ${f.postAuthDataAttempted} returned 2xx. `
+                + 'The page rendered, its data did not.'
+        };
+    }
+    const dataEvidence = f.postAuthDataAttempted > 0 ?
+        `${f.postAuthData2xx}/${f.postAuthDataAttempted} same-origin data requests returned 2xx`
+        : 'UNOBSERVED: the authenticated page issued no same-origin data request, so the '
+            + 'network half could not be checked (a server-rendered app legitimately issues none)';
+    return {
+        outcome: 'pass',
+        detail: `${signedIn}, left the wall for ${f.urlAfter}, ${dataEvidence}`
+    };
+}
+// ── CDP driver ───────────────────────────────────────────────────────────────
+/** Whole-session wall-clock cap, including browser launch (I4). */
+export const DEEP_RENDER_TIMEOUT_MS = 45_000;
+/** No new request for this long ⇒ the page has settled. */
+const QUIET_MS = 1_200;
+/** Caps for the two settle windows (initial load, post-submit). */
+const SETTLE_CAP_MS = 8_000;
+const POST_SUBMIT_CAP_MS = 12_000;
+/** Minimal DevTools-protocol client: request/response ids over one socket, plus
+ *  event fan-out. Everything the driver needs and nothing more. */
+class Cdp {
+    ws;
+    nextId = 1;
+    pending = new Map();
+    handlers = new Map();
+    constructor(ws) {
+        this.ws = ws;
+        ws.on('message', (data) => {
+            let msg;
+            try {
+                msg = JSON.parse(String(data));
+            }
+            catch {
+                return;
+            }
+            if (typeof msg.id === 'number') {
+                const p = this.pending.get(msg.id);
+                if (!p)
+                    return;
+                this.pending.delete(msg.id);
+                if (msg.error)
+                    p.reject(new Error(msg.error.message ?? 'CDP error'));
+                else
+                    p.resolve(msg.result ?? {});
+                return;
+            }
+            if (!msg.method)
+                return;
+            for (const h of this.handlers.get(msg.method) ?? [])
+                h(msg.params ?? {});
+        });
+    }
+    on(method, cb) {
+        const list = this.handlers.get(method) ?? [];
+        list.push(cb);
+        this.handlers.set(method, list);
+    }
+    send(method, params = {}, sessionId) {
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            try {
+                this.ws.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
+            }
+            catch (e) {
+                this.pending.delete(id);
+                reject(e instanceof Error ? e : new Error(String(e)));
+            }
+        });
+    }
+}
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+/** Page-side probe: what the user would see right now. */
+const INSPECT_EXPR = `(() => {
+    const visible = el => {
+        const r = el.getBoundingClientRect()
+        const s = getComputedStyle(el)
+        return s.display !== 'none' && s.visibility !== 'hidden' && (r.width > 0 || r.height > 0)
+    }
+    const pw = [...document.querySelectorAll('input[type=password]')].filter(visible)
+    return {
+        hasPassword: pw.length > 0,
+        url: location.href,
+        pathname: location.pathname,
+        html: document.documentElement.outerHTML.slice(0, 400000)
+    }
+})()`;
+/** Page-side fill: native value setters + input/change events, so a controlled
+ *  React/Vue/Svelte input actually updates its state (a bare `el.value = …` does
+ *  not, and the form then submits empty). */
+function fillExpr(identifier, password) {
+    return `(() => {
+    const setValue = (el, v) => {
+        const proto = el instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype
+        const desc = Object.getOwnPropertyDescriptor(proto, 'value')
+        if (desc && desc.set) desc.set.call(el, v)
+        else el.value = v
+        el.dispatchEvent(new Event('input', {bubbles: true}))
+        el.dispatchEvent(new Event('change', {bubbles: true}))
+    }
+    const pw = document.querySelector('input[type=password]')
+    if (!pw) return {ok: false, reason: 'no password input'}
+    const scope = pw.form ?? document
+    const skip = ['hidden', 'submit', 'button', 'checkbox', 'radio', 'file', 'image', 'reset', 'password']
+    const ident = [...scope.querySelectorAll('input')].find(i => !skip.includes(i.type))
+    if (ident) { ident.focus(); setValue(ident, ${JSON.stringify(identifier)}) }
+    pw.focus()
+    setValue(pw, ${JSON.stringify(password)})
+    return {ok: true, identifierFilled: !!ident, hasForm: !!pw.form}
+})()`;
+}
+/** Page-side submit, run as a SEPARATE evaluation so the framework has flushed the
+ *  state updates the fill scheduled before the handler reads them. */
+const SUBMIT_EXPR = `(() => {
+    const pw = document.querySelector('input[type=password]')
+    if (!pw) return {ok: false, reason: 'no password input'}
+    const scope = pw.form ?? document
+    const submit =
+        scope.querySelector('button[type=submit], input[type=submit]')
+        ?? [...scope.querySelectorAll('button')].find(b => !b.disabled)
+        ?? null
+    if (pw.form && typeof pw.form.requestSubmit === 'function') {
+        pw.form.requestSubmit(submit && submit.tagName === 'BUTTON' ? submit : undefined)
+        return {ok: true, how: 'requestSubmit'}
+    }
+    if (submit) { submit.click(); return {ok: true, how: 'click'} }
+    return {ok: false, reason: 'no submit control'}
+})()`;
+/** Wait until `ms` of silence pass with no new request, or `cap` elapses. */
+async function settle(lastActivity, cap, quiet = QUIET_MS) {
+    const deadline = Date.now() + cap;
+    for (;;) {
+        const idleFor = Date.now() - lastActivity();
+        if (idleFor >= quiet || Date.now() >= deadline)
+            return;
+        await sleep(Math.min(200, quiet - idleFor));
+    }
+}
+/**
+ * Drive one authenticated session against `url` and judge it. `cwd` is the project
+ * whose dotenv declares the account. Every failure mode of the DRIVER itself
+ * (no browser, launch failure, protocol error, timeout) resolves to SKIP: this
+ * check may only report on the app, never on itself.
+ */
+export async function runDeepRenderCheck(url, cwd, opts = {}) {
+    const credentials = opts.credentials !== undefined ?
+        opts.credentials
+        : findLoginCredentials(collectProjectEnv(cwd, opts.env));
+    const bin = opts.browser === undefined ? findHeadlessBrowser() : opts.browser;
+    if (!bin) {
+        return {
+            outcome: 'skip',
+            note: 'no headless Chrome-family browser found on this box (PATH, CHROME_BIN, Playwright cache) — the authenticated half of the app was NOT observed'
+        };
+    }
+    const budget = opts.timeoutMs ?? DEEP_RENDER_TIMEOUT_MS;
+    const userDataDir = mkdtempSync(path.join(os.tmpdir(), 'pi-task-deep-render-'));
+    let child = null;
+    let socket = null;
+    const cleanup = () => {
+        try {
+            socket?.close();
+        }
+        catch {
+            // socket already gone
+        }
+        try {
+            if (child?.pid)
+                process.kill(-child.pid, 'SIGKILL');
+        }
+        catch {
+            // group already gone
+        }
+        try {
+            rmSync(userDataDir, { recursive: true, force: true });
+        }
+        catch {
+            // best-effort temp cleanup
+        }
+    };
+    try {
+        return await withTimeout(drive(url, bin, userDataDir, credentials, c => {
+            child = c;
+        }, s => {
+            socket = s;
+        }), budget);
+    }
+    catch (e) {
+        const why = e instanceof Error ? e.message : String(e);
+        return {
+            outcome: 'skip',
+            note: `the authenticated render session could not run (${why}) — the authenticated half of the app was NOT observed`
+        };
+    }
+    finally {
+        cleanup();
+    }
+}
+function withTimeout(p, ms) {
+    return new Promise((resolve, reject) => {
+        const t = setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms);
+        t.unref?.();
+        p.then(v => {
+            clearTimeout(t);
+            resolve(v);
+        }, e => {
+            clearTimeout(t);
+            reject(e instanceof Error ? e : new Error(String(e)));
+        });
+    });
+}
+async function drive(url, bin, userDataDir, credentials, holdChild, holdSocket) {
+    const origin = new URL(url).origin;
+    const child = spawn(bin, [
+        '--headless',
+        '--disable-gpu',
+        '--no-sandbox',
+        '--disable-dev-shm-usage',
+        '--no-first-run',
+        '--no-default-browser-check',
+        '--disable-extensions',
+        `--user-data-dir=${userDataDir}`,
+        '--remote-debugging-port=0',
+        'about:blank'
+    ], { detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    holdChild(child);
+    child.unref();
+    const wsUrl = await new Promise((resolve, reject) => {
+        let buf = '';
+        const onData = (d) => {
+            buf += String(d);
+            const m = /DevTools listening on (ws:\/\/\S+)/.exec(buf);
+            if (m)
+                resolve(m[1]);
+        };
+        child.stderr?.on('data', onData);
+        child.stdout?.on('data', onData);
+        child.on('error', e => reject(e));
+        child.on('exit', code => reject(new Error(`browser exited ${code} before listening`)));
+    });
+    const socket = new WebSocket(wsUrl, { perMessageDeflate: false, maxPayload: 128 * 1024 * 1024 });
+    holdSocket(socket);
+    await new Promise((resolve, reject) => {
+        socket.once('open', () => resolve());
+        socket.once('error', e => reject(e instanceof Error ? e : new Error(String(e))));
+    });
+    const cdp = new Cdp(socket);
+    const requests = new Map();
+    let lastActivity = Date.now();
+    cdp.on('Network.requestWillBeSent', p => {
+        const req = p.request;
+        requests.set(String(p.requestId), {
+            url: String(req?.url ?? ''),
+            method: String(req?.method ?? 'GET'),
+            type: String(p.type ?? ''),
+            status: null,
+            failed: false,
+            at: Date.now()
+        });
+        lastActivity = Date.now();
+    });
+    cdp.on('Network.responseReceived', p => {
+        const r = requests.get(String(p.requestId));
+        const res = p.response;
+        if (r) {
+            r.status = typeof res?.status === 'number' ? res.status : r.status;
+            if (p.type)
+                r.type = String(p.type);
+        }
+        lastActivity = Date.now();
+    });
+    cdp.on('Network.loadingFailed', p => {
+        const r = requests.get(String(p.requestId));
+        if (r)
+            r.failed = true;
+        lastActivity = Date.now();
+    });
+    const { targetId } = (await cdp.send('Target.createTarget', { url: 'about:blank' }));
+    const { sessionId } = (await cdp.send('Target.attachToTarget', { targetId, flatten: true }));
+    await cdp.send('Page.enable', {}, sessionId);
+    await cdp.send('Runtime.enable', {}, sessionId);
+    await cdp.send('Network.enable', {}, sessionId);
+    const evaluate = async (expression) => {
+        const r = (await cdp.send('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: true }, sessionId));
+        return r.result?.value;
+    };
+    await cdp.send('Page.navigate', { url }, sessionId);
+    await settle(() => lastActivity, SETTLE_CAP_MS);
+    const before = await evaluate(INSPECT_EXPR);
+    if (!before)
+        throw new Error('the page could not be inspected');
+    const sameOrigin = (r) => r.url.startsWith(`${origin}/`) || r.url === origin;
+    const isData = (r) => r.type === 'XHR' || r.type === 'Fetch';
+    const foreignOriginFailures = () => {
+        const out = new Set();
+        for (const r of requests.values()) {
+            if (sameOrigin(r) || !r.failed || !r.url.startsWith('http'))
+                continue;
+            try {
+                out.add(new URL(r.url).origin);
+            }
+            catch {
+                // unparseable url — nothing to name
+            }
+        }
+        return [...out];
+    };
+    const facts = (over) => ({
+        landingHadAuthWall: before.hasPassword,
+        credentialsFound: credentials !== null,
+        submitted: false,
+        authRequest: null,
+        postAuthDataAttempted: 0,
+        postAuthData2xx: 0,
+        foreignOriginFailures: foreignOriginFailures(),
+        leftAuthWall: false,
+        urlBefore: before.url,
+        urlAfter: before.url,
+        postAuthDomOk: true,
+        postAuthDomDetail: '',
+        ...over
+    });
+    if (!before.hasPassword || credentials === null)
+        return judgeDeepSession(facts({}));
+    const submitMark = Date.now();
+    const filled = await evaluate(fillExpr(credentials.identifier, credentials.password));
+    if (!filled?.ok)
+        return judgeDeepSession(facts({ submitted: false }));
+    // Separate turn: the fill's input events schedule framework state updates that
+    // the submit handler must already see.
+    await sleep(300);
+    const submitted = await evaluate(SUBMIT_EXPR);
+    if (!submitted?.ok)
+        return judgeDeepSession(facts({ submitted: false }));
+    lastActivity = Date.now();
+    await settle(() => lastActivity, POST_SUBMIT_CAP_MS);
+    // The sign-in request: the first same-origin non-GET issued by the submit. Its
+    // own 2xx is the precondition for judging anything, and it is excluded from the
+    // data evidence (STEP 0: the broken build satisfies "≥1 same-origin 2xx" with
+    // exactly this request and nothing else).
+    const after = new Map([...requests].filter(([, r]) => r.at >= submitMark));
+    let authId = null;
+    for (const [id, r] of after) {
+        if (sameOrigin(r) && r.method !== 'GET') {
+            authId = id;
+            break;
+        }
+    }
+    const authReq = authId !== null ? after.get(authId) : null;
+    const authAt = authReq?.at ?? submitMark;
+    const postAuthData = [...after]
+        .filter(([id, r]) => id !== authId && sameOrigin(r) && isData(r) && r.at >= authAt)
+        .map(([, r]) => r);
+    const now = await evaluate(INSPECT_EXPR);
+    const domJudgment = judgeRenderedDom(now?.html ?? '');
+    return judgeDeepSession(facts({
+        submitted: true,
+        authRequest: authReq ?
+            {
+                method: authReq.method,
+                path: pathOf(authReq.url),
+                status: authReq.status,
+                failed: authReq.failed
+            }
+            : null,
+        postAuthDataAttempted: postAuthData.length,
+        postAuthData2xx: postAuthData.filter(r => r.status !== null && r.status >= 200 && r.status < 300).length,
+        foreignOriginFailures: foreignOriginFailures(),
+        leftAuthWall: !(now?.hasPassword ?? false) || (now?.pathname ?? '') !== before.pathname,
+        urlAfter: now?.url ?? before.url,
+        postAuthDomOk: domJudgment.ok,
+        postAuthDomDetail: domJudgment.detail
+    }));
+}
+function pathOf(url) {
+    try {
+        return new URL(url).pathname;
+    }
+    catch {
+        return url;
+    }
+}

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

@@ -1,6 +1,7 @@
 import { type HealthCommand } from './repo-health-check.js';
 import { type AcceptDebt } from './accept-debt.js';
 import { type RenderOutcome } from './render-check.js';
+import { type DeepRenderOutcome } from './deep-render-check.js';
 import { taskThatIntroduced } from './task-provenance.js';
 export interface FinalGateOutcome {
     /** true → statics and every runnable integration command passed (or nothing to run). */
@@ -88,7 +89,9 @@ export declare function discoverBootCommand(cwd: string): HealthCommand | null;
 type BootOutcome = {
     outcome: 'skip' | 'pass';
     /** Set when the render check could not OBSERVE the served page (no browser,
-     *  undeterminable port) — surfaced by the gate as an UNOBSERVED warning. */
+     *  undeterminable port) or its AUTHENTICATED half (no declared credentials,
+     *  an undrivable sign-in form, credentials the server rejected) — surfaced
+     *  by the gate as an UNOBSERVED warning. */
     renderNote?: string;
     /** skip only: the boot command never spawned (ENOENT) — feeds the
      *  full-blindness guard (mx5 run 16), unlike a 127 where the runner ran. */
@@ -134,6 +137,17 @@ export interface BootDeps {
      * the gate wires runRenderCheck by default for served apps.
      */
     renderProbe?: (url: string) => RenderOutcome;
+    /**
+     * SIGN IN on the served page and judge the AUTHENTICATED half of the app (mx5
+     * run 17). Runs only after `renderProbe` PASSED — the shallow blank-page rule
+     * keeps its own RED/GREEN-proven verdict and is never shadowed by this one.
+     * Absent → the boot check behaves exactly as before; the gate wires
+     * runDeepRenderCheck by default for served apps. May only FAIL when the SERVER
+     * itself authenticated the session (see deep-render-check.judgeDeepSession);
+     * anything else — no browser, no declared credentials, an undrivable form,
+     * rejected credentials — is an env gap and skips with an UNOBSERVED note.
+     */
+    deepRenderProbe?: (url: string) => DeepRenderOutcome | Promise<DeepRenderOutcome>;
     /**
      * Can this box enumerate listeners with pids AT ALL (ss/netstat/lsof)? False
      * means the served-app requirement is UNOBSERVABLE here and must degrade to the
@@ -146,6 +160,13 @@ export interface BootDeps {
      * pgid attribution alone). Injected for tests.
      */
     pickPort?: () => Promise<number | null>;
+    /**
+     * The port the project's own client was BUILT to call, when it declares one and
+     * nothing is holding it — preferred over a freshly reserved port so the served
+     * origin and the origin the client calls are the same one (see pinnedLocalPort).
+     * null → use the reserved private port exactly as before.
+     */
+    preferredPort?: () => Promise<number | null>;
     /** Does anything answer HTTP on 127.0.0.1:`port`? Injected for tests. */
     httpProbe?: (port: number) => boolean;
 }
@@ -189,6 +210,15 @@ export declare function resetListenerToolCapability(): void;
  * conventional :3000 and passed checks the app had not earned).
  */
 export declare function pickFreePort(): Promise<number | null>;
+/** Can we bind 127.0.0.1:`port` right now? (Free ⇒ the boot child can have it.) */
+export declare function isPortFree(port: number): Promise<boolean>;
+/**
+ * The project's own declared local port, but only if nothing is holding it — the
+ * default `preferredPort` for the gate. A declared port that is BUSY falls back to
+ * a reserved one rather than colliding: a stranger's server on :3000 must never be
+ * mistaken for the app we just booted.
+ */
+export declare function preferredDeclaredPort(cwd: string): Promise<number | null>;
 /**
  * Exercise the start command ONCE. For a CLI project (`expectServer` false) the
  * command's own fate within the grace window decides:

package/dist/task/final-gate.js

@@ -47,6 +47,7 @@ import { readAcceptDebts, recheckAcceptDebts, writeAcceptDebts, buildAcceptDebtN
 import { readDeclaredScripts, missingDeclaredScripts, runnableDeclaredScripts } from './launch-contract.js';
 import { readEnvNotes, parseEnvNotes, isExcuseNote } from './env-notes.js';
 import { runRenderCheck } from './render-check.js';
+import { collectProjectEnv, pinnedLocalPort, runDeepRenderCheck } from './deep-render-check.js';
 import { resolveRunner, runnerEnv } from './runner-resolve.js';
 import { taskThatIntroduced } from './task-provenance.js';
 import { findDanglingArtifacts, danglingGateFailureText } from './artifact-closure.js';
@@ -388,6 +389,31 @@ export function pickFreePort() {
         }
     });
 }
+/** Can we bind 127.0.0.1:`port` right now? (Free ⇒ the boot child can have it.) */
+export function isPortFree(port) {
+    return new Promise(resolve => {
+        try {
+            const srv = net.createServer();
+            srv.once('error', () => resolve(false));
+            srv.listen(port, '127.0.0.1', () => srv.close(() => resolve(true)));
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
+/**
+ * The project's own declared local port, but only if nothing is holding it — the
+ * default `preferredPort` for the gate. A declared port that is BUSY falls back to
+ * a reserved one rather than colliding: a stranger's server on :3000 must never be
+ * mistaken for the app we just booted.
+ */
+export async function preferredDeclaredPort(cwd) {
+    const port = pinnedLocalPort(collectProjectEnv(cwd));
+    if (port === null)
+        return null;
+    return (await isPortFree(port)) ? port : null;
+}
 /**
  * Does anything answer HTTP on 127.0.0.1:`port`? Any response at all (404, 500 —
  * a status is a listener) counts; only a connection error or timeout is a no.
@@ -534,7 +560,14 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
     const canEnumerate = expectServer ? (opts.deps?.enumerationCapable ?? canEnumerateListeners)() : true;
     // Only served apps get an assigned port: a CLI project has nothing to bind, and
     // an unexpected PORT in its env is noise.
-    const assignedPort = expectServer ? await (opts.deps?.pickPort ?? pickFreePort)() : null;
+    // The app's OWN declared local port wins when it is free (see pinnedLocalPort):
+    // a client whose base URL was baked in at build time calls that origin and no
+    // other, so serving it anywhere else makes the whole authenticated half
+    // unobservable. Anything else — no declaration, a port already held — falls back
+    // to the freshly reserved private port that run 14's ownership evidence needs.
+    const noPreference = () => Promise.resolve(null);
+    const preferred = expectServer ? await (opts.deps?.preferredPort ?? noPreference)() : null;
+    const assignedPort = preferred ?? (expectServer ? await (opts.deps?.pickPort ?? pickFreePort)() : null);
     // Runner resolution (mx5 run 16): same contract as runGateCommand — resolve
     // the runner and carry its directory on PATH so the boot script's own chain
     // can re-invoke it.
@@ -605,9 +638,13 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
         // check against the LIVE listener (mx5 runs 8/11: a listener that serves a
         // permanently blank page passed every curl-shaped check), then PASS/FAIL.
         // The probe is spawnSync, so the interval cannot re-enter mid-check.
+        // The deep probe is asynchronous (it drives a browser session), so the
+        // interval body must not re-enter while one is in flight — a second session
+        // would race the first for the same still-booting child.
+        let probing = false;
         const poll = expectServer ?
             setInterval(() => {
-                if (settled || !child.pid)
+                if (settled || probing || !child.pid)
                     return;
                 // pgid attribution first (precise, cheap). If it saw nothing — or
                 // cannot see anything here — fall back to the private assigned
@@ -627,14 +664,48 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
                 if (port === null) {
                     return passAndKill('render check UNOBSERVED: a listener was seen but its port could not be determined');
                 }
-                const rr = probe(`http://127.0.0.1:${port}/`);
+                const url = `http://127.0.0.1:${port}/`;
+                const rr = probe(url);
                 if (rr.outcome === 'fail') {
                     return failAndKill(`listens on :${port} but ${rr.detail}`);
                 }
-                passAndKill(rr.outcome === 'skip' ? `render check UNOBSERVED: ${rr.note}` : undefined);
+                const deep = opts.deps?.deepRenderProbe;
+                if (rr.outcome !== 'pass' || !deep) {
+                    return passAndKill(rr.outcome === 'skip' ?
+                        `render check UNOBSERVED: ${rr.note}`
+                        : undefined);
+                }
+                // The page renders. Now sign in and prove the AUTHENTICATED half
+                // is alive (mx5 run 17): the server accepted the login and the
+                // client never used it. Async, so the interval is held off by
+                // `probing` until this settles.
+                probing = true;
+                void Promise.resolve(deep(url)).then(dr => {
+                    if (settled)
+                        return;
+                    if (dr.outcome === 'fail') {
+                        return failAndKill(`listens on :${port} but ${dr.detail}`);
+                    }
+                    passAndKill(dr.outcome === 'skip' ?
+                        `authenticated render check UNOBSERVED: ${dr.note}`
+                        : undefined);
+                }, () => {
+                    // The deep probe may never fail the gate on its own fault.
+                    if (!settled)
+                        passAndKill();
+                });
             }, 500)
             : null;
-        const timer = setTimeout(() => {
+        const onGrace = () => {
+            // A browser session in flight outlives the grace window by design (it
+            // signs in and waits for the app's data calls). Settling here would kill
+            // the server under it and discard its verdict, so the window re-arms
+            // until the probe resolves — which it always does, on its own hard
+            // timeout (DEEP_RENDER_TIMEOUT_MS).
+            if (probing) {
+                timer = setTimeout(onGrace, 500);
+                return;
+            }
             if (expectServer && !listenerSeen) {
                 // Blind here (no enumeration tool, and the assigned port never
                 // answered) ⇒ we cannot tell "never listened" from "ignores PORT".
@@ -651,7 +722,8 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
                 return;
             }
             passAndKill();
-        }, graceMs);
+        };
+        let timer = setTimeout(onGrace, graceMs);
         child.on('error', () => settle({ outcome: 'skip', spawnFailed: true }));
         child.on('exit', (status, signal) => {
             if (status === 0) {
@@ -1045,9 +1117,19 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
         // blank-mount app passed every prior "renders" check. Default to the real
         // probe; tests inject their own. runRenderCheck env-gap-SKIPs when no
         // browser exists, so a box without one never gets a false FAIL.
+        // Authenticated deep-render check (mx5 run 17): the page above renders, so
+        // now sign in with the account the project's own dotenv declares (the same
+        // ADMIN_PHONE/ADMIN_PASSWORD the launch contract's seed step consumes) and
+        // require the session to actually work. WEB-ONLY by construction — it hangs
+        // off the served-app branch and never runs for C++, Godot, CLI or library
+        // projects. It may only FAIL when the SERVER authenticated us; no browser,
+        // no credentials, an undrivable form or rejected credentials all skip as
+        // env gaps (judgeDeepSession).
         const bootDepsWithRender = {
             ...bootDeps,
-            renderProbe: bootDeps.renderProbe ?? runRenderCheck
+            renderProbe: bootDeps.renderProbe ?? runRenderCheck,
+            deepRenderProbe: bootDeps.deepRenderProbe ?? (url => runDeepRenderCheck(url, cwd)),
+            preferredPort: bootDeps.preferredPort ?? (() => preferredDeclaredPort(cwd))
         };
         let b = await runBootCheck(cwd, boot, bootGraceMs, {
             expectServer,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.21.7",
+    "version": "0.21.8",
     "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",