agentwrangler 0.1.0

package/dist/apply/open-terminal.js

@@ -0,0 +1,221 @@
+/**
+ * src/apply/open-terminal.ts — O11 Apply Console phase 1 (Option B).
+ *
+ * "Open in Claude Code ↗": launch the user's real terminal, detached, in a
+ * recommendation's workspace folder running an interactive `claude` session
+ * seeded with the INT-2 prompt artifact. The daemon NEVER runs the edit — the
+ * user's own session is the permission surface and git is the rollback. This
+ * module only spawns a detached terminal; it writes nothing to apply_jobs.
+ *
+ * Two invariants fixed by the 2026-09-04 spike (spec-apply-console.md §5):
+ *   - Q3 env strip: a detached child inherits the daemon's env, which carries
+ *     CLAUDECODE=1 + CLAUDE_CODE_* — those trip the nested-claude guard crash
+ *     (DR1). stripClaudeEnv() removes them (plus the CLAUDE_PID/PLUGIN_DATA/
+ *     EFFORT runtime residuals a fresh session must not inherit).
+ *   - Q4 no shell interpolation: the pinned CLI has no --append-system-prompt-file,
+ *     so the prompt is written to a temp file and only the file PATH rides the
+ *     terminal's command line. A tiny node wrapper (open-terminal-child.mjs)
+ *     reads the file and execs claude with the prompt as a single argv element,
+ *     so prompt CONTENT never touches any shell/command-line parser.
+ */
+import { spawn as realSpawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { getRecommendationCard } from "../query/api/recommendations.js";
+import { getQueryDb } from "../query/db-context.js";
+const WRAPPER_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "open-terminal-child.mjs");
+/**
+ * Strip the Claude Code runtime env vars from a child's environment. Removing
+ * CLAUDECODE is what prevents the nested-claude guard crash (DR1); the rest are
+ * parent-session runtime state a fresh interactive session must not inherit.
+ */
+export function stripClaudeEnv(env) {
+    const out = {};
+    for (const [k, v] of Object.entries(env)) {
+        if (k === "CLAUDECODE")
+            continue;
+        if (k.startsWith("CLAUDE_CODE_"))
+            continue;
+        if (k === "CLAUDE_PID" || k === "CLAUDE_PLUGIN_DATA" || k === "CLAUDE_EFFORT")
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+/** PATH-search a launcher command; returns an absolute path or null. */
+function defaultResolveCommand(command, env) {
+    if (path.isAbsolute(command))
+        return fs.existsSync(command) ? command : null;
+    const dirs = (env.PATH ?? env.Path ?? "").split(path.delimiter).filter((d) => d.length > 0);
+    // cmd.exe always lives in System32 even if PATH is unusual.
+    if (process.platform === "win32" && env.SystemRoot) {
+        dirs.push(path.join(env.SystemRoot, "System32"));
+    }
+    const exts = process.platform === "win32"
+        ? (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").map((e) => e.toLowerCase())
+        : [""];
+    for (const dir of dirs) {
+        if (path.extname(command) !== "") {
+            const p = path.join(dir, command);
+            if (fs.existsSync(p))
+                return p;
+            continue;
+        }
+        for (const ext of exts) {
+            const p = path.join(dir, command + ext);
+            if (fs.existsSync(p))
+                return p;
+        }
+    }
+    return null;
+}
+/** Shell-quote a single token for an AppleScript `do script` string (macOS arm, untested). */
+function shq(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+function candidatesFor(platform) {
+    const child = (ctx) => [
+        ctx.nodePath,
+        WRAPPER_PATH,
+        ctx.promptFile,
+        ctx.cwd,
+    ];
+    if (platform === "win32") {
+        return [
+            { launcher: "wt", command: "wt.exe", args: (ctx) => ["-d", ctx.cwd, ...child(ctx)] },
+            {
+                launcher: "cmd",
+                command: "cmd.exe",
+                args: (ctx) => ["/c", "start", "", "/d", ctx.cwd, ...child(ctx)],
+            },
+        ];
+    }
+    if (platform === "darwin") {
+        // UNTESTED (spec §5 Q4): no macOS host this session. Only file PATHS are
+        // interpolated into the AppleScript string; prompt content stays in the file.
+        return [
+            {
+                launcher: "osascript",
+                command: "osascript",
+                args: (ctx) => [
+                    "-e",
+                    `tell application "Terminal" to do script "cd ${shq(ctx.cwd)} && ${shq(ctx.nodePath)} ${shq(WRAPPER_PATH)} ${shq(ctx.promptFile)} ${shq(ctx.cwd)}"`,
+                ],
+            },
+        ];
+    }
+    // linux + others — UNTESTED (spec §5 Q4). argv arrays, no shell.
+    return [
+        {
+            launcher: "x-terminal-emulator",
+            command: "x-terminal-emulator",
+            args: (ctx) => ["-e", ...child(ctx)],
+        },
+        { launcher: "gnome-terminal", command: "gnome-terminal", args: (ctx) => ["--", ...child(ctx)] },
+        { launcher: "xterm", command: "xterm", args: (ctx) => ["-e", ...child(ctx)] },
+    ];
+}
+function defaultDeps() {
+    const env = process.env;
+    return {
+        spawn: realSpawn,
+        platform: process.platform,
+        env,
+        tmpRoot: os.tmpdir(),
+        nodePath: process.execPath,
+        resolveCommand: (command) => defaultResolveCommand(command, env),
+    };
+}
+/**
+ * Launch a detached terminal in `cwd` running an interactive claude seeded with
+ * `prompt`. Pure w.r.t. the DB — takes cwd + prompt directly. Injectable deps
+ * make terminal selection, env strip, and prompt hand-off unit-testable.
+ */
+export function openTerminal(input, deps = {}) {
+    const d = { ...defaultDeps(), ...deps };
+    const { cwd, prompt } = input;
+    if (typeof prompt !== "string" || prompt.length === 0) {
+        return { launched: false, reason: "No prompt to seed — Copy prompt instead." };
+    }
+    // Validate absoluteness against the TARGET platform, not the host: a daemon on
+    // Linux (or a cross-platform CI run) must still recognize a Windows `C:\…` cwd.
+    const targetPath = d.platform === "win32" ? path.win32 : path.posix;
+    if (typeof cwd !== "string" || cwd.length === 0 || !targetPath.isAbsolute(cwd)) {
+        return { launched: false, reason: "Workspace folder is not a valid absolute path." };
+    }
+    const candidate = candidatesFor(d.platform).find((c) => d.resolveCommand(c.command) !== null);
+    if (candidate === undefined) {
+        return { launched: false, reason: "No terminal emulator found — Copy prompt instead." };
+    }
+    const resolved = d.resolveCommand(candidate.command);
+    // Write the prompt to a temp file (Q4). The wrapper unlinks it after reading,
+    // so prompt content is transient (SEC-101) and never rides a command line.
+    const promptDir = fs.mkdtempSync(path.join(d.tmpRoot, "aw-open-"));
+    const promptFile = path.join(promptDir, "prompt.txt");
+    fs.writeFileSync(promptFile, prompt, "utf8");
+    const args = candidate.args({ nodePath: d.nodePath, promptFile, cwd });
+    try {
+        const child = d.spawn(resolved, args, {
+            cwd,
+            detached: true,
+            stdio: "ignore",
+            windowsHide: false,
+            env: stripClaudeEnv(d.env),
+        });
+        child.unref();
+    }
+    catch (e) {
+        try {
+            fs.rmSync(promptDir, { recursive: true, force: true });
+        }
+        catch {
+            // best-effort cleanup
+        }
+        return {
+            launched: false,
+            reason: `Couldn't start ${candidate.launcher} — Copy prompt instead. (${e instanceof Error ? e.message : String(e)})`,
+        };
+    }
+    return { launched: true, launcher: candidate.launcher };
+}
+/** Persisted counts-only demand signal for Option A (spec §4/§7). SEC-101: a scalar. */
+function incrementOpenTerminalCount(db) {
+    db.prepare(`INSERT INTO user_config (key, value, updated_at)
+       VALUES ('open_terminal_click_count', '1', ?)
+     ON CONFLICT(key) DO UPDATE
+       SET value = CAST(CAST(value AS INTEGER) + 1 AS TEXT), updated_at = excluded.updated_at`).run(new Date().toISOString());
+}
+/**
+ * Resolve a recommendation's workspace folder and open a terminal there. The
+ * cwd comes from workspaces.repo_path (server-side) so reach is every
+ * workspace-scoped rec with a local folder, not just file-ref recs. `prompt` is
+ * the UI-built INT-2 artifact (the daemon is fenced off from the UI templates).
+ */
+export function openTerminalForRec(recId, prompt, deps = {}) {
+    const db = getQueryDb();
+    const rec = getRecommendationCard(recId);
+    if (rec === null)
+        return { launched: false, reason: "Recommendation not found." };
+    if (rec.scope_workspace_id === null) {
+        return {
+            launched: false,
+            reason: "This is a cross-workspace recommendation with no single folder — Copy prompt instead.",
+        };
+    }
+    const row = db
+        .prepare("SELECT repo_path FROM workspaces WHERE workspace_id = ?")
+        .get(rec.scope_workspace_id);
+    const cwd = row?.repo_path ?? null;
+    if (cwd === null || !path.isAbsolute(cwd) || !fs.existsSync(cwd)) {
+        return {
+            launched: false,
+            reason: "This recommendation's workspace folder isn't available locally — Copy prompt instead.",
+        };
+    }
+    const result = openTerminal({ cwd, prompt }, deps);
+    if (result.launched)
+        incrementOpenTerminalCount(db);
+    return result;
+}

package/dist/apply/settings-gen.js

@@ -0,0 +1,35 @@
+/**
+ * Per-job Claude Code settings generation for W3-A assisted apply.
+ *
+ * The settings file is a best-effort pre-edit boundary. Headless Claude can
+ * silently ignore invalid settings, so callers must still run the post-apply
+ * path audit before marking a job APPLIED.
+ */
+function globPath(fileRef) {
+    return fileRef.replace(/\\/g, "/");
+}
+export function generateJobSettings(fileRef, mode) {
+    const escaped = globPath(fileRef);
+    const settings = mode === "apply"
+        ? {
+            permissions: {
+                allow: [
+                    `Edit(${escaped})`,
+                    `Write(${escaped})`,
+                    "Read(**)",
+                    "Bash(git diff*)",
+                    "Bash(git status*)",
+                ],
+                deny: ["Edit(**)", "Write(**)", "Bash(**)", "WebFetch(**)", "WebSearch(**)"],
+            },
+        }
+        : {
+            permissions: {
+                deny: ["Edit(**)", "Write(**)", "Bash(**)", "WebFetch(**)", "WebSearch(**)"],
+            },
+        };
+    return JSON.stringify(settings, null, 2);
+}
+export function assertValidSettingsJson(raw) {
+    JSON.parse(raw);
+}

package/dist/cli/agentwrangler.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+// This CLI ships compiled to dist/cli/agentwrangler.js and spawns the compiled
+// daemon at dist/daemon/index.js — no tsx at runtime. The prebuilt UI ships in
+// dist/ui, so there is no build-UI-if-missing step (that only applied to the
+// tsx clone path, which now builds dist via the package `prepare` script).
+// Browser auto-open, --smoke, --no-open and the hook commands are all handled
+// by the daemon itself.
+const cliDir = path.dirname(fileURLToPath(import.meta.url));
+const daemonPath = path.resolve(cliDir, "..", "daemon", "index.js");
+const daemon = spawn(process.execPath, [daemonPath, ...process.argv.slice(2)], {
+    stdio: "inherit",
+});
+// A null code means the daemon was terminated by a signal — surface that as a
+// non-zero exit so an abnormal end is visible to the calling shell / npx.
+daemon.on("exit", (code) => process.exit(code ?? 1));

package/dist/daemon/config.js

@@ -0,0 +1,51 @@
+/**
+ * src/daemon/config.ts — daemon configuration.
+ *
+ * Config is layered:
+ *   1. Compile-time defaults (below).
+ *   2. Environment variable overrides (AW_* prefix).
+ *   3. Runtime overrides from the user_config table (persisted by WP4).
+ *
+ * WP4 implements the user_config read/write path. This module provides the
+ * defaults and the environment-variable layer used at boot time.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+/** Default scan root for ~/.claude/projects/ transcript discovery. */
+const DEFAULT_SCAN_ROOT = path.join(os.homedir(), ".claude", "projects");
+/** Default TCP port for the loopback HTTP server. */
+const DEFAULT_PORT = 47821;
+/**
+ * Activity window in seconds: sessions with last_turn_at within this many
+ * seconds of now are considered LIVE. Beyond this, they are reconciled.
+ */
+const DEFAULT_ACTIVITY_WINDOW_SECS = 5 * 60; // 5 minutes
+/** Default on-disk database path. */
+const DEFAULT_DB_PATH = path.join(os.homedir(), ".agentwrangler", "db.sqlite");
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_UI_ROOT = path.resolve(MODULE_DIR, "..", "..", "dist", "ui");
+/**
+ * Load the daemon config from compile-time defaults and environment variables.
+ * WP4 will augment this with user_config table values after DB is open.
+ */
+export function loadConfig(overrides = {}) {
+    const dbPath = process.env.AW_DB_PATH ?? DEFAULT_DB_PATH;
+    const portEnv = process.env.AW_PORT;
+    const port = portEnv !== undefined ? Number.parseInt(portEnv, 10) : DEFAULT_PORT;
+    const scanRootEnv = process.env.AW_SCAN_ROOT;
+    const scanRoots = scanRootEnv !== undefined ? [scanRootEnv] : [DEFAULT_SCAN_ROOT];
+    const windowEnv = process.env.AW_ACTIVITY_WINDOW_SECS;
+    const activityWindowSecs = windowEnv !== undefined ? Number.parseInt(windowEnv, 10) : DEFAULT_ACTIVITY_WINDOW_SECS;
+    const uiRootEnv = process.env.AW_UI_ROOT;
+    const uiRoot = uiRootEnv !== undefined ? uiRootEnv : fs.existsSync(DEFAULT_UI_ROOT) ? DEFAULT_UI_ROOT : null;
+    return {
+        dbPath,
+        port,
+        scanRoots,
+        activityWindowSecs,
+        uiRoot,
+        ...overrides,
+    };
+}

package/dist/daemon/http.js

@@ -0,0 +1,258 @@
+/**
+ * src/daemon/http.ts — HTTP request handler with security baseline.
+ *
+ * Security layers (applied in order, before any handler):
+ *
+ * 1. Host guard (SEC-102 / ADR-100 loopback-only):
+ *    Refuse any request whose Host header doesn't resolve to a loopback address.
+ *    Strips the port before checking so the guard works regardless of the
+ *    ephemeral port chosen by the OS. Response: 421 Misdirected Request.
+ *
+ * 2. CSRF same-origin gate (POST/PUT/PATCH/DELETE only):
+ *    Implements the Fetch Metadata / OWASP Fetch-site algorithm:
+ *    (a) If Sec-Fetch-Site present: allow only "same-origin" or "none"; else 403.
+ *    (b) Else if Origin present: allow only exact-match against
+ *        {http://127.0.0.1:<port>, http://localhost:<port>, http://[::1]:<port>};
+ *        reject "null" Origin and all others; → 403.
+ *    (c) If neither header present: allow (legacy same-origin, no CORS context).
+ *
+ * 3. Content-Type gate (POST/PUT/PATCH/DELETE only):
+ *    Write requests must carry Content-Type: application/json; else → 415.
+ *
+ * NEVER emits permissive CORS headers. The SPA is served from the same origin;
+ * no cross-origin API access is needed or allowed.
+ */
+import { timingSafeEqual } from "node:crypto";
+import * as http from "node:http";
+import { isReady } from "./readiness.js";
+import { handleApiRequest } from "./router.js";
+import { createStaticHandler } from "./static.js";
+/** Inline loading page served while the daemon's initial back-scan is running. */
+const LOADING_HTML = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>AgentWrangler — Starting up</title>
+<style>
+*{box-sizing:border-box;margin:0;padding:0}
+body{background:#0b0f17;color:#c9d1d9;font-family:system-ui,sans-serif;display:flex;align-items:center;justify-content:center;min-height:100vh;text-align:center}
+.wrap{padding:2rem}
+h1{font-size:1.5rem;font-weight:700;color:#f0f6fc;letter-spacing:.05em}
+h2{font-size:1rem;font-weight:400;color:#38bdf8;margin:.75rem 0 .5rem}
+p{font-size:.875rem;color:#8b949e;max-width:36ch;margin:0 auto 2rem}
+.spinner{width:40px;height:40px;border:3px solid #1e293b;border-top-color:#38bdf8;border-radius:50%;animation:spin 1s linear infinite;margin:0 auto}
+.count{font-variant-numeric:tabular-nums;color:#8b949e;font-size:.875rem;margin:1.25rem auto 0;min-height:1.2em}
+@keyframes spin{to{transform:rotate(360deg)}}
+</style>
+</head>
+<body>
+<div class="wrap">
+  <h1>AgentWrangler</h1>
+  <h2>Starting up…</h2>
+  <p>Scanning your Claude Code transcripts — this can take a few minutes on first run; later loads are instant.</p>
+  <div class="spinner"></div>
+  <p class="count" id="count" aria-live="polite"></p>
+</div>
+<script>
+(function poll(){
+  fetch('/api/ready')
+    .then(function(r){return r.json();})
+    .then(function(d){
+      if(d.ready){location.reload();return;}
+      // Reuse the first-run onboarding counter so a large first scan shows live
+      // progress instead of a bare spinner. Cadence unchanged (1s).
+      fetch('/api/status')
+        .then(function(r){return r.json();})
+        .then(function(s){
+          if(s&&typeof s.files_seen==='number'&&s.files_seen>0){
+            document.getElementById('count').textContent=
+              'Scanning transcripts — '+s.files_parsed+' of '+s.files_seen+' files';
+          }
+        })
+        .catch(function(){})
+        .then(function(){setTimeout(poll,1000);});
+    })
+    .catch(function(){setTimeout(poll,1000);});
+})();
+</script>
+</body>
+</html>`;
+/**
+ * Strict allowlist for loopback Host headers.
+ * Matches 127.0.0.1, localhost, [::1] — each optionally with :PORT — and
+ * nothing else.  Using a full-pattern match prevents userinfo-syntax bypass
+ * (e.g. "localhost:user@evil.com") that a bare lastIndexOf(':') strip allows.
+ */
+const LOOPBACK_HOST_RE = /^(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/;
+/** Return true if the Host header is a loopback address (with optional port). */
+function isLoopbackHost(host) {
+    if (!host)
+        return false;
+    return LOOPBACK_HOST_RE.test(host);
+}
+const WRITE_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+/**
+ * Apply the CSRF same-origin gate to a write request.
+ * Returns null on success, or a {status, message} on failure.
+ */
+function csrfCheck(req, port) {
+    const sfs = req.headers["sec-fetch-site"];
+    if (sfs !== undefined) {
+        // Fetch Metadata present: enforce same-origin or none only.
+        if (sfs === "same-origin" || sfs === "none")
+            return null;
+        return { status: 403, message: "Forbidden — cross-origin write rejected (Sec-Fetch-Site)" };
+    }
+    const origin = req.headers.origin;
+    if (origin !== undefined) {
+        // Legacy CORS check: allow only the exact loopback origins (scheme+host+port).
+        const allowed = new Set([
+            `http://127.0.0.1:${port}`,
+            `http://localhost:${port}`,
+            `http://[::1]:${port}`,
+        ]);
+        if (origin === "null" || !allowed.has(origin)) {
+            return {
+                status: 403,
+                message: "Forbidden — cross-origin write rejected (Origin)",
+            };
+        }
+        return null;
+    }
+    // Neither Sec-Fetch-Site nor Origin — legacy same-origin request (e.g. curl).
+    return null;
+}
+/** Return true when a write path requires X-AgentWrangler-Token. */
+function requiresSessionToken(pathname) {
+    if (pathname === "/api/idle-sessions/end")
+        return true;
+    if (pathname === "/api/hook/install" || pathname === "/api/hook/uninstall")
+        return true;
+    if (pathname === "/api/recommendations/adopt" || pathname === "/api/recommendations/dismiss") {
+        return true;
+    }
+    if (/^\/api\/recommendations\/[^/]+\/apply$/.test(pathname))
+        return true;
+    if (/^\/api\/recommendations\/[^/]+\/open-terminal$/.test(pathname))
+        return true;
+    if (/^\/api\/recommendations\/jobs\/[^/]+\/(confirm|rollback)$/.test(pathname))
+        return true;
+    return false;
+}
+/**
+ * Create the Node HTTP request handler for the daemon.
+ *
+ * @param db            Open SQLite database.
+ * @param port          The port the server is bound to (used for CSRF Origin checks).
+ * @param uiRoot        Path to the built SPA assets directory. May be null in test/CI.
+ * @param sessionToken  In-memory CSRF session token (crypto.randomUUID() at startup).
+ *                      When provided, GET /api/token returns it and POST write endpoints
+ *                      for adopt/dismiss require it in X-AgentWrangler-Token. When null/
+ *                      undefined, the token gate is inactive (legacy/test mode).
+ */
+export function createHandler(db, port, uiRoot, sessionToken, kickBootScan) {
+    const staticHandler = uiRoot ? createStaticHandler(uiRoot) : null;
+    return function handler(req, res) {
+        // ── 1. Host guard ────────────────────────────────────────────────────────
+        const host = req.headers.host ?? "";
+        if (!isLoopbackHost(host)) {
+            res.writeHead(421, { "Content-Type": "text/plain" });
+            res.end("421 Misdirected Request — loopback only");
+            return;
+        }
+        const method = (req.method ?? "GET").toUpperCase();
+        const url = req.url ?? "/";
+        const pathname = url.split("?")[0] ?? url;
+        // ── GET /api/token — expose session token (same-origin readable only) ────
+        if (method === "GET" && pathname === "/api/token" && sessionToken != null) {
+            const body = JSON.stringify({ token: sessionToken });
+            res.writeHead(200, {
+                "Content-Type": "application/json; charset=utf-8",
+                "Content-Length": Buffer.byteLength(body),
+            });
+            res.end(body);
+            return;
+        }
+        // ── 2 & 3. CSRF + Content-Type gate (writes only) ────────────────────────
+        if (WRITE_METHODS.has(method)) {
+            const err = csrfCheck(req, port);
+            if (err) {
+                res.writeHead(err.status, { "Content-Type": "text/plain" });
+                res.end(err.message);
+                return;
+            }
+            const ct = req.headers["content-type"] ?? "";
+            if (!ct.startsWith("application/json")) {
+                res.writeHead(415, { "Content-Type": "text/plain" });
+                res.end("415 Unsupported Media Type — Content-Type must be application/json");
+                return;
+            }
+            // ── 4. Session-token gate (mutating recommendation actions, when token active) ─────
+            if (sessionToken != null && requiresSessionToken(pathname)) {
+                const provided = req.headers["x-agentwrangler-token"];
+                const providedStr = Array.isArray(provided) ? provided[0] : provided;
+                let tokenOk = false;
+                if (providedStr !== undefined) {
+                    try {
+                        // Compare by bytes so a multi-byte non-ASCII header can't bypass the
+                        // length guard and cause timingSafeEqual to throw ERR_CRYPTO_TIMING_SAFE_EQUAL_LENGTH.
+                        const a = Buffer.from(providedStr, "utf8");
+                        const b = Buffer.from(sessionToken, "utf8");
+                        if (a.length === b.length) {
+                            // Constant-time compare to prevent timing oracle on token value.
+                            tokenOk = timingSafeEqual(a, b);
+                        }
+                    }
+                    catch {
+                        // Defense-in-depth: any unexpected error → tokenOk stays false → 401.
+                    }
+                }
+                if (!tokenOk) {
+                    res.writeHead(401, { "Content-Type": "text/plain" });
+                    res.end("401 Unauthorized — missing or invalid X-AgentWrangler-Token");
+                    return;
+                }
+            }
+        }
+        // ── Loading page (daemon not ready yet) ──────────────────────────────────
+        // Serve while the initial back-scan is running. Only intercepts top-level
+        // HTML navigations — /api/* paths (including /api/ready) pass through so
+        // the polling script can detect readiness even while the loop is blocked.
+        if (!isReady() &&
+            (pathname === "/" ||
+                (!pathname.startsWith("/api/") && (req.headers.accept ?? "").includes("text/html")))) {
+            kickBootScan?.();
+            res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+            res.end(LOADING_HTML);
+            return;
+        }
+        // ── API routes (/api/*) ──────────────────────────────────────────────────
+        if (url.startsWith("/api/")) {
+            handleApiRequest(db, req, res, method, url);
+            return;
+        }
+        // ── Static SPA assets ────────────────────────────────────────────────────
+        if (staticHandler) {
+            staticHandler(req, res, () => {
+                // sirv calls next() when the file is not found — send 404.
+                res.writeHead(404, { "Content-Type": "text/plain" });
+                res.end("404 Not Found");
+            });
+            return;
+        }
+        // No static handler (UI not built yet).
+        res.writeHead(200, { "Content-Type": "text/plain" });
+        res.end("AgentWrangler daemon running — build the UI with `npm run build:ui`");
+    };
+}
+/**
+ * Create and return an HTTP server using the loopback handler.
+ * Pass sessionToken (generated by src/daemon/index.ts via crypto.randomUUID()) to
+ * enable the X-AgentWrangler-Token gate on write endpoints. Omit in tests that
+ * do not exercise the token gate.
+ */
+export function createServer(db, port, uiRoot, sessionToken, kickBootScan) {
+    const handler = createHandler(db, port, uiRoot, sessionToken, kickBootScan);
+    return http.createServer(handler);
+}