vigiles 9.0.0 → 10.0.0

package/dist/audit-score.d.ts

@@ -4,9 +4,12 @@
  * A single structural-health number (the leaderboard's `scoreReport`) ranks
  * plugins, but it hides WHERE a harness is weak. This buckets the SAME
  * deterministic findings into four categories — Truthfulness, Triggering,
- * Structure, Tested — each a 0–100 ring, with a weighted overall. Same
- * detectors, no re-detection (one-detector-no-drift); all deterministic, no
- * execution. (Safety — "do your hooks actually block?" — is NOT an `audit` ring:
+ * Structure, Tested — each a 0–100 ring, as a DIAGNOSTIC breakdown beneath one
+ * headline `overall` = `100 − Σ(all graded penalties)` (the SAME summed model as
+ * the leaderboard's single health number, via the shared `computeIntegrityScore`
+ * — so the two surfaces never disagree). Same detectors, no re-detection
+ * (one-detector-no-drift); all deterministic, no execution. (Safety — "do your
+ * hooks actually block?" — is NOT an `audit` ring:
  * it requires executing your hooks, which needs cross-platform confinement
  * that isn't shipped yet, so it lives in the `vigiles/testing` API via
  * `guardrail-check`/`assertBlocksDisasters`, where you opt in explicitly.)
@@ -23,11 +26,25 @@ export interface CategoryScore {
     readonly score: number | null;
     /** Relative weight in the overall (equal by default — tune later). */
     readonly weight: number;
+    /**
+     * Advisory categories are shown but EXCLUDED from the overall grade. An untested
+     * surface (or any best-practice gap) is a HARDENING signal, not a broken harness
+     * — it must never drag the grade down, so `audit` doesn't read as F on a clean
+     * repo that simply hasn't written tests yet. The grade reflects what's BROKEN.
+     */
+    readonly advisory?: boolean;
     /** Human-readable deductions / notes, worst first; empty when clean. */
     readonly findings: readonly string[];
 }
 export interface AuditScore {
-    /** Weighted average over the ASSESSABLE categories (n/a excluded). 0 when empty. */
+    /**
+     * The headline score — `100 − Σ(all graded penalties)`, clamped to [0,100]
+     * (the SAME summed model as the leaderboard's single health number, computed by
+     * the shared {@link computeIntegrityScore}, so the two surfaces never disagree).
+     * The per-category rings below are a DIAGNOSTIC breakdown, not the headline: a
+     * plugin whose only issue is Structure −30 shows Structure 70 in the breakdown
+     * AND overall 70 (averaging the rings would dilute that to ~90). 0 when empty.
+     */
     readonly overall: number;
     readonly grade: PluginScore["grade"];
     readonly categories: readonly CategoryScore[];
@@ -35,10 +52,13 @@ export interface AuditScore {
     readonly empty: boolean;
 }
 /**
- * Bucket a scan report into the four deterministic Lighthouse categories with a
- * weighted overall. n/a categories are excluded from the overall, never scored 0.
+ * Bucket a scan report into the four deterministic Lighthouse categories as a
+ * DIAGNOSTIC breakdown, with the headline `overall` = `100 − Σ(all graded
+ * penalties)` (the shared summed model — NOT the average of the rings — so it
+ * equals the leaderboard's single health number). The advisory Tested ring and
+ * any n/a ring are shown but excluded from the headline.
  */
 export declare function auditScore(report: ScanReport): AuditScore;
-/** Render the category rings + the weighted overall for the terminal. */
+/** Render the category rings (diagnostic) + the summed overall for the terminal. */
 export declare function formatAuditScore(s: AuditScore): string;
 //# sourceMappingURL=audit-score.d.ts.map

package/dist/audit-score.js

@@ -8,9 +8,12 @@ exports.formatAuditScore = formatAuditScore;
  * A single structural-health number (the leaderboard's `scoreReport`) ranks
  * plugins, but it hides WHERE a harness is weak. This buckets the SAME
  * deterministic findings into four categories — Truthfulness, Triggering,
- * Structure, Tested — each a 0–100 ring, with a weighted overall. Same
- * detectors, no re-detection (one-detector-no-drift); all deterministic, no
- * execution. (Safety — "do your hooks actually block?" — is NOT an `audit` ring:
+ * Structure, Tested — each a 0–100 ring, as a DIAGNOSTIC breakdown beneath one
+ * headline `overall` = `100 − Σ(all graded penalties)` (the SAME summed model as
+ * the leaderboard's single health number, via the shared `computeIntegrityScore`
+ * — so the two surfaces never disagree). Same detectors, no re-detection
+ * (one-detector-no-drift); all deterministic, no execution. (Safety — "do your
+ * hooks actually block?" — is NOT an `audit` ring:
  * it requires executing your hooks, which needs cross-platform confinement
  * that isn't shipped yet, so it lives in the `vigiles/testing` API via
  * `guardrail-check`/`assertBlocksDisasters`, where you opt in explicitly.)
@@ -19,13 +22,9 @@ exports.formatAuditScore = formatAuditScore;
  * overall — never a false 0. Pure over the `ScanReport`, so it's fully testable.
  */
 const leaderboard_js_1 = require("./leaderboard.js");
-// Per-item penalties — mirror the leaderboard's weights so the category view and
-// the single health number stay consistent (broken-at-runtime costs most).
-const W_MISSING_HOOK = 15;
-const W_NO_DESCRIPTION = 10;
-const W_DANGLING_REF = 8;
-const W_OVERLAP = 8; // a description collision → the wrong skill fires
-const W_NO_CONTRACT = 5;
+// Per-item penalties are the SHARED leaderboard weights (imported above) so the
+// category rings and the single health number can never drift. W_UNTESTED is
+// audit-only — untested surfaces are advisory (shown, never scored into overall).
 const W_UNTESTED = 3;
 /** Apply deductions to a 100 base, clamped to [0,100], collecting non-zero labels. */
 function scoreFrom(deductions) {
@@ -48,12 +47,12 @@ function truthfulness(r) {
     const { score, findings } = scoreFrom([
         {
             n: r.danglingRefs.length,
-            weight: W_DANGLING_REF,
+            weight: leaderboard_js_1.W_DANGLING_REF,
             label: "broken intra-plugin reference(s)",
         },
         {
             n: missingHooks,
-            weight: W_MISSING_HOOK,
+            weight: leaderboard_js_1.W_MISSING_HOOK,
             label: "hook script(s) missing (never run)",
         },
     ]);
@@ -64,12 +63,12 @@ function triggering(r) {
     const { score, findings } = scoreFrom([
         {
             n: noDesc,
-            weight: W_NO_DESCRIPTION,
+            weight: leaderboard_js_1.W_NO_DESCRIPTION,
             label: "skill(s) with no usable description (can't trigger)",
         },
         {
             n: r.descriptionOverlaps.length,
-            weight: W_OVERLAP,
+            weight: leaderboard_js_1.W_OVERLAP,
             label: "near-identical skill description(s) (wrong one fires)",
         },
     ]);
@@ -83,76 +82,89 @@ function structure(r) {
     const { score, findings } = scoreFrom([
         {
             n: deadTools,
-            weight: W_DANGLING_REF,
+            weight: leaderboard_js_1.W_DANGLING_REF,
             label: "agent tool(s) that don't exist (typo / never-available)",
         },
         {
             n: deadMcpTools,
-            weight: W_DANGLING_REF,
+            weight: leaderboard_js_1.W_DANGLING_REF,
             label: "agent MCP tool(s) whose server isn't declared",
         },
         {
             n: r.hookEventIssues.length,
-            weight: W_MISSING_HOOK,
+            weight: leaderboard_js_1.W_MISSING_HOOK,
             label: "hook(s) on an unknown event (never fire)",
         },
         {
             n: r.mcpIssues.length,
-            weight: W_DANGLING_REF,
+            weight: leaderboard_js_1.W_DANGLING_REF,
             label: "MCP server(s) that can't start (no command/url)",
         },
         {
             n: r.mcpHookIssues.length,
-            weight: W_DANGLING_REF,
+            weight: leaderboard_js_1.W_DANGLING_REF,
             label: "mcp_tool hook(s) incomplete / undeclared server",
         },
         {
             n: r.frontmatterIssues.length,
-            weight: W_NO_DESCRIPTION,
+            weight: leaderboard_js_1.W_NO_DESCRIPTION,
             label: "surface(s) missing required frontmatter",
         },
         {
             n: r.frontmatterValueIssues.length,
-            weight: W_NO_CONTRACT,
+            weight: leaderboard_js_1.W_NO_CONTRACT,
             label: "agent(s) with an invalid model/color (silent fallback)",
         },
         {
             n: deadDisallowed,
-            weight: W_NO_CONTRACT,
+            weight: leaderboard_js_1.W_NO_CONTRACT,
             label: "disallowedTools typo(s) that block nothing",
         },
-        {
-            n: noContract,
-            weight: W_NO_CONTRACT,
-            label: "agent(s) inherit all tools (no contract)",
-        },
     ]);
-    return { key: "Structure", score, weight: 1, findings };
+    // inherit-all (no `tools:` line) is ADVISORY, not graded: it's surfaced as a
+    // least-privilege NUDGE but never lowers the Structure ring. WHY: omitting the
+    // tool contract is a near-universal, legitimate authoring style (a measured OSS
+    // sweep of 122 real plugins found 109 whose only finding was this), so grading
+    // it would make `audit` cry wolf on idiomatic subagents. See reportDeductions.
+    const advisory = noContract > 0
+        ? [
+            `${String(noContract)} agent(s) inherit all tools (no contract) (advisory)`,
+        ]
+        : [];
+    return {
+        key: "Structure",
+        score,
+        weight: 1,
+        findings: [...findings, ...advisory],
+    };
 }
 function tested(r) {
     const { score, findings } = scoreFrom([
         { n: r.untested, weight: W_UNTESTED, label: "untested surface(s)" },
     ]);
-    return { key: "Tested", score, weight: 1, findings };
+    // ADVISORY: untested surfaces are a hardening gap, not breakage — shown, but
+    // excluded from the overall grade (so a clean-but-untested repo isn't graded F).
+    return { key: "Tested", score, weight: 1, advisory: true, findings };
 }
-function isEmptyMachine(r) {
-    const surfaces = r.skills.length +
-        r.agents.length +
-        r.hooks.length +
-        r.inlineHooks +
-        r.commands;
-    // An instruction-only repo (just a CLAUDE.md/AGENTS.md, no plugin surface) is
-    // NOT empty — the scan records `instructions` precisely so it isn't graded
-    // F/0 "no loadable surface". Only a dir with NO instruction file AND no
-    // surface is the empty machine.
-    return surfaces === 0 && !r.mcp && !r.instructions;
+/**
+ * An instruction-only repo (just a CLAUDE.md/AGENTS.md, no plugin surface) is NOT
+ * empty — the scan records `instructions` precisely so it isn't graded F/0 "no
+ * loadable surface". Only a dir with NO instruction file AND no surface is empty.
+ * (The shared `isEmptyMachine` ignores `instructions`; audit additionally treats
+ * an instruction file as a surface.)
+ */
+function isEmptyAudit(r) {
+    return (0, leaderboard_js_1.isEmptyMachine)(r) && !r.instructions;
 }
 /**
- * Bucket a scan report into the four deterministic Lighthouse categories with a
- * weighted overall. n/a categories are excluded from the overall, never scored 0.
+ * Bucket a scan report into the four deterministic Lighthouse categories as a
+ * DIAGNOSTIC breakdown, with the headline `overall` = `100 − Σ(all graded
+ * penalties)` (the shared summed model — NOT the average of the rings — so it
+ * equals the leaderboard's single health number). The advisory Tested ring and
+ * any n/a ring are shown but excluded from the headline.
  */
 function auditScore(report) {
-    if (isEmptyMachine(report)) {
+    if (isEmptyAudit(report)) {
         const categories = [
             "Truthfulness",
             "Triggering",
@@ -177,11 +189,11 @@ function auditScore(report) {
         structure(report),
         tested(report),
     ];
-    const assessable = categories.filter((c) => c.score !== null);
-    const totalWeight = assessable.reduce((s, c) => s + c.weight, 0);
-    const overall = totalWeight === 0
-        ? 0
-        : Math.round(assessable.reduce((s, c) => s + c.score * c.weight, 0) / totalWeight);
+    // The headline is the SUMMED model (the shared integrity score), NOT the average
+    // of the rings — averaging would let a real problem in one category be diluted
+    // by clean siblings. The rings above stay a diagnostic breakdown; Tested
+    // (advisory) is never summed in (untested surfaces don't drag the grade).
+    const { score: overall } = (0, leaderboard_js_1.computeIntegrityScore)((0, leaderboard_js_1.reportDeductions)(report));
     return { overall, grade: (0, leaderboard_js_1.gradeFor)(overall), categories, empty: false };
 }
 // A 22-cell bar gauge ("ring" in the terminal; the real rings are the HTML).
@@ -202,14 +214,15 @@ function bar(score) {
     const filled = Math.round((score / 100) * BAR_CELLS);
     return "█".repeat(filled) + "░".repeat(BAR_CELLS - filled);
 }
-/** Render the category rings + the weighted overall for the terminal. */
+/** Render the category rings (diagnostic) + the summed overall for the terminal. */
 function formatAuditScore(s) {
     const lines = ["Harness audit", ""];
     for (const c of s.categories) {
         const glyph = bandGlyph(c.score);
         const label = c.key.padEnd(13);
         const num = (c.score === null ? "n/a" : String(c.score)).padStart(4);
-        lines.push(`  ${glyph} ${label} ${num}  ${bar(c.score)}`);
+        const tag = c.advisory ? "  · advisory (not graded)" : "";
+        lines.push(`  ${glyph} ${label} ${num}  ${bar(c.score)}${tag}`);
         if (c.findings.length > 0) {
             lines.push(`       └ ${c.findings.join("; ")}`);
         }

package/dist/audit-serve.d.ts

@@ -0,0 +1,109 @@
+/** A per-run server session: the secret token + the adopt allowlist. */
+export interface ServeSession {
+    /** Crypto-random hex; embedded in the HTML, required on every mutating POST. */
+    readonly token: string;
+    /** The loopback port the server is bound to (for the Origin check). */
+    readonly port: number;
+    /**
+     * The adoptable surfaces, keyed by their repo-relative path. A POST names a
+     * path; we resolve it HERE against this set, so an off-list path is refused.
+     */
+    readonly surfaces: ReadonlySet<string>;
+}
+/** The salient, transport-agnostic fields of an incoming request. */
+export interface RequestView {
+    readonly method: string;
+    /** The URL path (no query string). */
+    readonly path: string;
+    /** The `X-Vigiles-Token` header, if any. */
+    readonly token: string | null;
+    /** The `Origin` header, if any. */
+    readonly origin: string | null;
+    /** `body.target` for an adopt POST, if any. */
+    readonly target: string | null;
+}
+/** What the server should do with a request — a pure, testable verdict. */
+export type ServeDecision = {
+    readonly kind: "report";
+} | {
+    readonly kind: "adopt";
+    readonly target: string;
+} | {
+    readonly kind: "adopt-all";
+} | {
+    readonly kind: "shutdown";
+} | {
+    readonly kind: "reject";
+    readonly status: number;
+    readonly reason: string;
+};
+/**
+ * Constant-time token comparison (avoids a timing side-channel). Returns false
+ * for a missing/short token rather than throwing.
+ */
+export declare function tokenOk(provided: string | null, expected: string): boolean;
+/**
+ * A mutating POST's Origin must be the loopback server itself (or absent — some
+ * same-origin fetches omit it, and the token already guards those). A foreign
+ * site's Origin never matches, so a cross-site POST is refused even before the
+ * token check.
+ */
+export declare function originOk(origin: string | null, port: number): boolean;
+/**
+ * Resolve a client-supplied surface path against the allowlist. Returns the path
+ * only if it's a known adoptable surface — never trusts a raw path (no traversal).
+ */
+export declare function resolveSurface(target: string | null, surfaces: ReadonlySet<string>): string | null;
+/**
+ * The pure router: given a request and the session, decide what to do. Every
+ * MUTATING route (adopt / adopt-all / shutdown) requires POST + a valid Origin +
+ * a valid token; GET / serves the report page (its body is CORS-protected, so a
+ * foreign site can't read it even if it requests it).
+ */
+export declare function decideServe(req: RequestView, session: ServeSession): ServeDecision;
+/** A fresh crypto-random session token (32 hex chars = 16 bytes). */
+export declare function newToken(): string;
+/** Whether `audit` should start the live adoption server. */
+export type ServeGate = "serve" | "skip" | "ask";
+/**
+ * The pure serve-gate decision (option B). A plain `audit` stays a terminating,
+ * headless-safe read; the live server is only ever offered/started INTERACTIVELY
+ * and OWN-REPO (it writes specs — never into a stranger's dir):
+ *   - `--no-serve`, a foreign repo, or `--json`/headless → skip (never serve).
+ *   - `--serve` → serve (force, skip the prompt).
+ *   - a TTY with adoptable surfaces → ask once ("open the live report?").
+ *   - a TTY with nothing to adopt → skip (no point).
+ */
+export declare function decideServeGate(o: {
+    serveFlag: boolean;
+    noServeFlag: boolean;
+    json: boolean;
+    isTTY: boolean;
+    ownRepo: boolean;
+    adoptableCount: number;
+}): ServeGate;
+/** The outcome of running an adopt action, reported back to the report UI. */
+export interface AdoptOutcome {
+    readonly ok: boolean;
+    readonly message: string;
+}
+export interface ServeOptions {
+    /** The per-run secret token (already injected into `html`). */
+    readonly token: string;
+    /** The adopt allowlist (repo-relative surface paths). */
+    readonly surfaces: ReadonlySet<string>;
+    /** The rendered report HTML (with the token already injected). */
+    readonly html: string;
+    /** Adopt ONE surface (the CLI passes a closure over `init --target=`). */
+    readonly runAdopt: (target: string) => Promise<AdoptOutcome>;
+    /** Adopt every surface (bare `init`). */
+    readonly runAdoptAll: () => Promise<AdoptOutcome>;
+    /** Called once the server is listening, with the URL to open. */
+    readonly onListening?: (url: string) => void;
+}
+/**
+ * Start the loopback adoption server. Resolves when the server shuts down (via
+ * the /shutdown route or SIGINT). Bound to 127.0.0.1 only.
+ */
+export declare function serveAudit(opts: ServeOptions): Promise<void>;
+//# sourceMappingURL=audit-serve.d.ts.map

package/dist/audit-serve.js

@@ -0,0 +1,257 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tokenOk = tokenOk;
+exports.originOk = originOk;
+exports.resolveSurface = resolveSurface;
+exports.decideServe = decideServe;
+exports.newToken = newToken;
+exports.decideServeGate = decideServeGate;
+exports.serveAudit = serveAudit;
+/**
+ * `audit --serve` — the optional one-click-local adoption server.
+ *
+ * The HTML audit report is a STATIC file: a browser can't write your repo, so by
+ * default its "Create spec" buttons just COPY the `npx vigiles init …` command.
+ * `--serve` (or the TTY prompt) instead starts a tiny LOCAL server the report
+ * POSTs to, so a button click actually runs `init` for you — without ever leaving
+ * your machine.
+ *
+ * This is the only path where `audit` WRITES via a button, so it carries the
+ * standard localhost-server hardening (the Jupyter recipe — see
+ * research/audit-serve-design.md):
+ *
+ *   1. BIND 127.0.0.1 only (never 0.0.0.0) — unreachable off the machine.
+ *   2. A per-run SECRET TOKEN (crypto-random), embedded in the served HTML and
+ *      REQUIRED on every mutating POST. A foreign website can't read the token
+ *      (CORS blocks reading a cross-origin GET body), so it can't forge a POST —
+ *      this is the primary CSRF defense.
+ *   3. ORIGIN/Host check as belt-and-suspenders: a POST's Origin must be the
+ *      loopback server itself.
+ *   4. The adopt endpoint takes a surface ID from the pre-computed ALLOWLIST (the
+ *      surfaces audit already discovered), never a client-supplied path — so a
+ *      forged request can't traverse outside the repo.
+ *   5. The action calls `init` IN-PROCESS (an injected runner), never a shell, so
+ *      there's no command injection.
+ *   6. Worst-case blast radius is tiny: `init` writes a reversible local
+ *      `.spec.ts` (no exec, no network, no model); `eject` undoes it.
+ *
+ * The pure decision logic (`decideServe`, `tokenOk`, `originOk`,
+ * `resolveSurface`) is unit-tested; the http/IO shell (`serveAudit`) is the thin
+ * v8-ignored wrapper.
+ */
+const node_http_1 = require("node:http");
+const node_crypto_1 = require("node:crypto");
+/**
+ * Constant-time token comparison (avoids a timing side-channel). Returns false
+ * for a missing/short token rather than throwing.
+ */
+function tokenOk(provided, expected) {
+    if (!provided || provided.length !== expected.length)
+        return false;
+    const a = Buffer.from(provided);
+    const b = Buffer.from(expected);
+    // Lengths are equal here, so timingSafeEqual is safe to call.
+    return (0, node_crypto_1.timingSafeEqual)(a, b);
+}
+/**
+ * A mutating POST's Origin must be the loopback server itself (or absent — some
+ * same-origin fetches omit it, and the token already guards those). A foreign
+ * site's Origin never matches, so a cross-site POST is refused even before the
+ * token check.
+ */
+function originOk(origin, port) {
+    if (origin === null)
+        return true; // rely on the token (a foreign site can't have it)
+    return (origin === `http://127.0.0.1:${String(port)}` ||
+        origin === `http://localhost:${String(port)}`);
+}
+/**
+ * Resolve a client-supplied surface path against the allowlist. Returns the path
+ * only if it's a known adoptable surface — never trusts a raw path (no traversal).
+ */
+function resolveSurface(target, surfaces) {
+    if (!target)
+        return null;
+    return surfaces.has(target) ? target : null;
+}
+/**
+ * The pure router: given a request and the session, decide what to do. Every
+ * MUTATING route (adopt / adopt-all / shutdown) requires POST + a valid Origin +
+ * a valid token; GET / serves the report page (its body is CORS-protected, so a
+ * foreign site can't read it even if it requests it).
+ */
+function decideServe(req, session) {
+    if (req.method === "GET" &&
+        (req.path === "/" || req.path === "/index.html")) {
+        return { kind: "report" };
+    }
+    const mutating = req.path === "/adopt" ||
+        req.path === "/adopt-all" ||
+        req.path === "/shutdown";
+    if (!mutating) {
+        return { kind: "reject", status: 404, reason: "not found" };
+    }
+    if (req.method !== "POST") {
+        return { kind: "reject", status: 405, reason: "method not allowed" };
+    }
+    if (!originOk(req.origin, session.port)) {
+        return { kind: "reject", status: 403, reason: "bad origin" };
+    }
+    if (!tokenOk(req.token, session.token)) {
+        return { kind: "reject", status: 403, reason: "bad or missing token" };
+    }
+    if (req.path === "/shutdown")
+        return { kind: "shutdown" };
+    if (req.path === "/adopt-all")
+        return { kind: "adopt-all" };
+    const target = resolveSurface(req.target, session.surfaces);
+    if (!target) {
+        return { kind: "reject", status: 400, reason: "unknown surface" };
+    }
+    return { kind: "adopt", target };
+}
+/** A fresh crypto-random session token (32 hex chars = 16 bytes). */
+function newToken() {
+    return (0, node_crypto_1.randomBytes)(16).toString("hex");
+}
+/**
+ * The pure serve-gate decision (option B). A plain `audit` stays a terminating,
+ * headless-safe read; the live server is only ever offered/started INTERACTIVELY
+ * and OWN-REPO (it writes specs — never into a stranger's dir):
+ *   - `--no-serve`, a foreign repo, or `--json`/headless → skip (never serve).
+ *   - `--serve` → serve (force, skip the prompt).
+ *   - a TTY with adoptable surfaces → ask once ("open the live report?").
+ *   - a TTY with nothing to adopt → skip (no point).
+ */
+function decideServeGate(o) {
+    if (o.noServeFlag)
+        return "skip";
+    if (!o.ownRepo)
+        return "skip"; // serve writes specs → own repo only
+    if (o.serveFlag)
+        return "serve";
+    if (o.json || !o.isTTY)
+        return "skip"; // headless never serves
+    if (o.adoptableCount === 0)
+        return "skip"; // nothing to adopt
+    return "ask";
+}
+/* v8 ignore start — the http/IO shell; the decision logic above is unit-tested. */
+/** Read a request body to a string, capped to avoid an unbounded read. */
+async function readBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > 64 * 1024)
+            break; // an adopt POST is tiny; cap defensively
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf-8");
+}
+function viewOf(req, body) {
+    const path = (req.url ?? "/").split("?")[0];
+    let target = null;
+    try {
+        if (body)
+            target = JSON.parse(body).target ?? null;
+    }
+    catch {
+        target = null;
+    }
+    const header = (n) => {
+        const v = req.headers[n];
+        return typeof v === "string" ? v : null;
+    };
+    return {
+        method: req.method ?? "GET",
+        path,
+        token: header("x-vigiles-token"),
+        origin: header("origin"),
+        target,
+    };
+}
+function sendJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        "content-type": "application/json",
+        // No CORS headers: same-origin only. A cross-origin site can fire a request
+        // but cannot read this response — and can't forge the token anyway.
+        "x-content-type-options": "nosniff",
+    });
+    res.end(payload);
+}
+/**
+ * Start the loopback adoption server. Resolves when the server shuts down (via
+ * the /shutdown route or SIGINT). Bound to 127.0.0.1 only.
+ */
+async function serveAudit(opts) {
+    const { token, surfaces, html, runAdopt, runAdoptAll, onListening } = opts;
+    // The bound port is known only after listen(); the request handler reads it via
+    // this closure. No request can arrive before the server is listening, so the
+    // late assignment is race-free.
+    let session = { token, port: 0, surfaces };
+    await new Promise((resolveServer) => {
+        const server = (0, node_http_1.createServer)((req, res) => {
+            void (async () => {
+                const body = req.method === "POST" ? await readBody(req) : "";
+                const decision = decideServe(viewOf(req, body), session);
+                switch (decision.kind) {
+                    case "report":
+                        res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+                        res.end(html);
+                        return;
+                    case "adopt": {
+                        const out = await runAdopt(decision.target);
+                        sendJson(res, out.ok ? 200 : 500, out);
+                        return;
+                    }
+                    case "adopt-all": {
+                        const out = await runAdoptAll();
+                        sendJson(res, out.ok ? 200 : 500, out);
+                        return;
+                    }
+                    case "shutdown":
+                        sendJson(res, 200, { ok: true, message: "shutting down" });
+                        server.close(() => {
+                            resolveServer();
+                        });
+                        return;
+                    case "reject":
+                        sendJson(res, decision.status, {
+                            ok: false,
+                            message: decision.reason,
+                        });
+                        return;
+                }
+            })().catch(() => {
+                try {
+                    sendJson(res, 500, { ok: false, message: "internal error" });
+                }
+                catch {
+                    /* response already sent */
+                }
+            });
+        });
+        server.on("error", () => {
+            resolveServer();
+        });
+        // 127.0.0.1 ONLY — never 0.0.0.0; the server is unreachable off the machine.
+        // Port 0 → the OS assigns an ephemeral port; we learn it after binding.
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            const port = addr && typeof addr === "object" ? addr.port : 0;
+            session = { token, port, surfaces };
+            onListening?.(`http://127.0.0.1:${String(port)}/?token=${token}`);
+        });
+        const stop = () => {
+            server.close(() => {
+                resolveServer();
+            });
+        };
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+    });
+}
+/* v8 ignore stop */
+//# sourceMappingURL=audit-serve.js.map