@felixdotgo/aidlc-kit 0.1.1 → 0.3.0

package/dist/src/ui/data.js

@@ -0,0 +1,89 @@
+/**
+ * Authority-neutral read model: local reads canonical state in-process; fleet asks
+ * `loop-entry.mjs` (the only place that speaks to the coordination service).
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { checkGate, gateView } from "../gate.js";
+import { assertTaskArtifactPath, loadState, loadTask } from "../state.js";
+import { runNode } from "./daemon.js";
+import { loopArgs, uiMode } from "./options.js";
+export const ARTIFACT_NAMES = ["intent", "design", "workplan"];
+const FEEDBACK_DETAIL = /^Cancelled gate wait at (G0_confirm|G1_review|G2_codereview): /;
+/** Feedback entries not yet followed by a passing approval of that gate
+ * (mirrors `pendingFeedback` in the installed `loop-runtime.mjs`). */
+export const pendingFeedback = (task) => {
+    const pending = [];
+    task.evidence.forEach((entry, index) => {
+        if (entry.kind !== "diagnostic" || typeof entry.detail !== "string")
+            return;
+        const match = FEEDBACK_DETAIL.exec(entry.detail);
+        if (!match)
+            return;
+        const gate = match[1] ?? "";
+        const approvedAfter = task.evidence.slice(index + 1).some((later) => later.kind === "approval" && later.result === "pass" && later.gate === gate);
+        if (!approvedAfter)
+            pending.push({ gate, text: entry.detail.slice(match[0].length), recordedAt: entry.recordedAt });
+    });
+    return pending;
+};
+/* Fleet reads spawn `loop-entry.mjs`; live polling (every ~1.5s per open tab)
+ * shares one in-flight or recent result per key instead of spawning per request. */
+const fleetReads = new Map();
+const sharedFleetRead = (key, maxAgeMs, read) => {
+    if (maxAgeMs <= 0)
+        return read();
+    const now = Date.now();
+    const cached = fleetReads.get(key);
+    if (cached && now - cached.at < maxAgeMs)
+        return cached.value;
+    const value = read();
+    fleetReads.set(key, { at: now, value });
+    value.catch(() => { if (fleetReads.get(key)?.value === value)
+        fleetReads.delete(key); });
+    return value;
+};
+/** How stale a fleet read on the live-update path may be. Mutations always read fresh. */
+export const LIVE_FLEET_MAX_AGE_MS = 1000;
+export const readUiState = async (options, maxAgeMs = 0) => {
+    if (uiMode(options) === "local")
+        return loadState(options.root);
+    return sharedFleetRead(`${options.root}\0tasks`, maxAgeMs, async () => {
+        const parsed = JSON.parse(await runNode(options.root, loopArgs(options.root, "tasks"), { timeout: 15000 }));
+        if (!Array.isArray(parsed.tasks))
+            throw new Error("Fleet task list is unavailable");
+        return { schemaVersion: 4, tasks: Object.fromEntries(parsed.tasks.map((task) => [task.id, task])), archive: {} };
+    });
+};
+export const readUiTask = (options, id, state) => uiMode(options) === "local" ? loadTask(options.root, id, state) : state.tasks[id];
+export const fleetGate = (options, id, maxAgeMs = 0) => sharedFleetRead(`${options.root}\0gate\0${id}`, maxAgeMs, async () => JSON.parse(await runNode(options.root, loopArgs(options.root, "gate", id), { timeout: 15000 })));
+export const taskGatePayload = async (options, id, known, maxAgeMs = 0) => {
+    const state = known ?? await readUiState(options, maxAgeMs);
+    const task = readUiTask(options, id, state);
+    if (!task)
+        return { ok: false, error: `Task not found: ${id}` };
+    if (task.status !== "blocked_on_user" || task.gate === "none")
+        return { ok: false, error: "Task is not waiting at a human gate" };
+    if (uiMode(options) === "fleet") {
+        const gate = await fleetGate(options, id, maxAgeMs);
+        return gate.snapshot ? { ok: true, gate: task.gate, snapshot: gate.snapshot } : { ok: false, error: "No current review snapshot for this gate yet" };
+    }
+    const diagnostics = checkGate(options.root, state, id, task.gate);
+    return { ok: true, gate: task.gate, view: gateView(task, diagnostics) };
+};
+export const artifactPayload = (root, id, name, task = loadTask(root, id)) => {
+    if (!ARTIFACT_NAMES.includes(name))
+        return { ok: false, error: `Unknown artifact: ${name}` };
+    if (!task)
+        return { ok: false, error: `Task not found: ${id}` };
+    const artifactPath = task.artifacts?.[name];
+    if (!artifactPath)
+        return { ok: false, error: `Artifact ${name} not recorded for ${id}` };
+    assertTaskArtifactPath(id, artifactPath);
+    try {
+        return { ok: true, name, content: readFileSync(join(root, artifactPath), "utf8") };
+    }
+    catch {
+        return { ok: false, error: `Artifact ${name} is missing for ${id}` };
+    }
+};

package/dist/src/ui/docs.d.ts

@@ -0,0 +1,13 @@
+export interface DocPage {
+    slug: string;
+    label: string;
+}
+/** Sidebar order; the first entry is the landing page of `/docs`. */
+export declare const DOC_PAGES: readonly DocPage[];
+export declare const DEFAULT_DOC: string;
+export declare const findDocPage: (slug: string) => DocPage | undefined;
+/** The markdown of a whitelisted page, or undefined (unknown slug or missing file). */
+export declare const readDoc: (slug: string) => {
+    page: DocPage;
+    markdown: string;
+} | undefined;

package/dist/src/ui/docs.js

@@ -0,0 +1,39 @@
+/**
+ * In-app documentation: the package's own `docs/*.md` (shipped via package.json `files`),
+ * served read-only by slug from a fixed whitelist — never by a request-supplied path.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Sidebar order; the first entry is the landing page of `/docs`. */
+export const DOC_PAGES = [
+    { slug: "loop-runbook", label: "Getting started" },
+    { slug: "loop-local-run", label: "Local loop walkthrough" },
+    { slug: "configuration", label: "Configuration" },
+    { slug: "command-reference", label: "Command reference" },
+    { slug: "troubleshooting", label: "Troubleshooting" },
+    { slug: "operating-workflow", label: "Operating the workflow" },
+    { slug: "architecture", label: "Architecture" },
+];
+export const DEFAULT_DOC = DOC_PAGES[0]?.slug ?? "loop-runbook";
+/** `docs/` next to the package's `dist/` (dist/src/ui/docs.js → ../../../docs). */
+const docsDir = () => fileURLToPath(new URL("../../../docs/", import.meta.url));
+const cache = new Map();
+export const findDocPage = (slug) => DOC_PAGES.find((page) => page.slug === slug);
+/** The markdown of a whitelisted page, or undefined (unknown slug or missing file). */
+export const readDoc = (slug) => {
+    const page = findDocPage(slug);
+    if (!page)
+        return undefined;
+    let markdown = cache.get(slug);
+    if (markdown === undefined) {
+        try {
+            markdown = readFileSync(join(docsDir(), `${page.slug}.md`), "utf8");
+        }
+        catch {
+            return undefined;
+        }
+        cache.set(slug, markdown);
+    }
+    return { page, markdown };
+};

package/dist/src/ui/files.d.ts

@@ -0,0 +1,3 @@
+/** Reads bytes `[start, end)` of a file (shorter if the file shrank meanwhile). With `noFollow`
+ * the open refuses a symlink where the platform supports `O_NOFOLLOW`. */
+export declare const readRange: (path: string, start: number, end: number, noFollow?: boolean) => Buffer;

package/dist/src/ui/files.js

@@ -0,0 +1,20 @@
+import { closeSync, constants, openSync, readSync } from "node:fs";
+/** Reads bytes `[start, end)` of a file (shorter if the file shrank meanwhile). With `noFollow`
+ * the open refuses a symlink where the platform supports `O_NOFOLLOW`. */
+export const readRange = (path, start, end, noFollow = false) => {
+    const fd = openSync(path, noFollow ? constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) : "r");
+    try {
+        const buffer = Buffer.alloc(Math.max(0, end - start));
+        let read = 0;
+        while (read < buffer.length) {
+            const count = readSync(fd, buffer, read, buffer.length - read, start + read);
+            if (!count)
+                break;
+            read += count;
+        }
+        return buffer.subarray(0, read);
+    }
+    finally {
+        closeSync(fd);
+    }
+};

package/dist/src/ui/http.d.ts

@@ -0,0 +1,14 @@
+/** HTTP response helpers, HTML escaping, and request-body parsing. */
+import type { IncomingMessage, ServerResponse } from "node:http";
+export declare const sendJson: (res: ServerResponse, status: number, body: unknown) => void;
+export declare const sendHtml: (res: ServerResponse, body: string, status?: number) => void;
+/** Static assets (CSS, client JS) are cacheable; script URLs carry a content hash to bust upgrades. */
+export declare const sendAsset: (res: ServerResponse, contentType: string, body: string) => void;
+export declare const escapeHtml: (value: string) => string;
+/** A client error mapped to HTTP 400 by the request handler. */
+export declare class BadRequest extends Error {
+}
+/** Reads a request body up to `limit` bytes (default 8 KiB). Routes that carry an 8192-byte
+ * text field pass a larger limit so JSON escaping does not count against the field. */
+export declare const readBody: (req: IncomingMessage, limit?: number) => Promise<string>;
+export declare const readFields: (body: string, contentType: string | undefined) => Record<string, string>;

package/dist/src/ui/http.js

@@ -0,0 +1,80 @@
+export const sendJson = (res, status, body) => {
+    res.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
+    res.end(JSON.stringify(body));
+};
+export const sendHtml = (res, body, status = 200) => {
+    res.writeHead(status, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+    res.end(body);
+};
+/** Static assets (CSS, client JS) are cacheable; script URLs carry a content hash to bust upgrades. */
+export const sendAsset = (res, contentType, body) => {
+    res.writeHead(200, { "content-type": contentType, "cache-control": "public, max-age=3600" });
+    res.end(body);
+};
+export const escapeHtml = (value) => value.replace(/[&<>"']/g, (char) => {
+    switch (char) {
+        case "&": return "&amp;";
+        case "<": return "&lt;";
+        case ">": return "&gt;";
+        case '"': return "&quot;";
+        default: return "&#39;";
+    }
+});
+/** A client error mapped to HTTP 400 by the request handler. */
+export class BadRequest extends Error {
+}
+/** Reads a request body up to `limit` bytes (default 8 KiB). Routes that carry an 8192-byte
+ * text field pass a larger limit so JSON escaping does not count against the field. */
+export const readBody = (req, limit = 8192) => new Promise((resolveBody, reject) => {
+    const chunks = [];
+    let size = 0;
+    req.on("data", (chunk) => {
+        size += chunk.length;
+        if (size > limit) {
+            reject(new BadRequest(`Request body exceeds ${limit} bytes`));
+            req.destroy();
+            return;
+        }
+        chunks.push(chunk);
+    });
+    req.on("end", () => resolveBody(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+});
+const decode = (value) => { try {
+    return decodeURIComponent(value.replace(/\+/g, " "));
+}
+catch {
+    return value;
+} };
+const parseForm = (body) => {
+    const result = {};
+    for (const pair of body.split("&")) {
+        if (!pair)
+            continue;
+        const [rawKey, rawValue = ""] = pair.split("=");
+        const key = decode(rawKey ?? "");
+        if (key)
+            result[key] = decode(rawValue);
+    }
+    return result;
+};
+const isJson = (contentType) => (contentType ?? "").includes("application/json");
+export const readFields = (body, contentType) => {
+    if (isJson(contentType)) {
+        let value;
+        try {
+            value = JSON.parse(body);
+        }
+        catch {
+            throw new BadRequest("Request body is not valid JSON");
+        }
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            throw new BadRequest("JSON body must be an object");
+        const result = {};
+        for (const [key, entry] of Object.entries(value))
+            if (typeof entry === "string")
+                result[key] = entry;
+        return result;
+    }
+    return parseForm(body);
+};

package/dist/src/ui/live.d.ts

@@ -0,0 +1,5 @@
+import { type UiOptions } from "./options.js";
+/** `/api/live`: re-renders the regions the client lists in `known` (name:hash)
+ * from one state read and returns only those whose hash changed, plus the full
+ * review list for the tab title and new-review toasts. */
+export declare const livePayload: (options: UiOptions, url: URL) => Promise<unknown>;

package/dist/src/ui/live.js

@@ -0,0 +1,43 @@
+import { LIVE_FLEET_MAX_AGE_MS, readUiState } from "./data.js";
+import { uiMode } from "./options.js";
+import { renderBoard } from "./views/board.js";
+import { gateLabel } from "./views/components.js";
+import { LIVE_REGIONS, notifyLimit, regionHash, renderDaemonPill, renderNotifications, reviewQueue } from "./views/layout.js";
+import { drawerNotFound, renderTaskBody, taskNotFound } from "./views/task.js";
+/** `/api/live`: re-renders the regions the client lists in `known` (name:hash)
+ * from one state read and returns only those whose hash changed, plus the full
+ * review list for the tab title and new-review toasts. */
+export const livePayload = async (options, url) => {
+    const known = new Map();
+    for (const entry of (url.searchParams.get("known") ?? "").split(",")) {
+        const at = entry.indexOf(":");
+        const name = at < 0 ? entry : entry.slice(0, at);
+        if (LIVE_REGIONS.includes(name))
+            known.set(name, at < 0 ? "" : entry.slice(at + 1));
+    }
+    const maxAgeMs = uiMode(options) === "fleet" ? LIVE_FLEET_MAX_AGE_MS : 0;
+    const state = await readUiState(options, maxAgeMs);
+    const task = url.searchParams.get("task") ?? "";
+    const drawer = url.searchParams.get("drawer") ?? "";
+    const reviews = reviewQueue(state);
+    const render = async (name) => {
+        switch (name) {
+            case "notify": return renderNotifications(reviews, task, notifyLimit(url.searchParams.get("notify")));
+            case "daemon": return renderDaemonPill(options.root);
+            case "board": return renderBoard(state);
+            case "detail": return task ? (await renderTaskBody(options, state, task, false, maxAgeMs))?.html ?? taskNotFound(options, task) : undefined;
+            case "drawer": return drawer ? (await renderTaskBody(options, state, drawer, true, maxAgeMs))?.html ?? drawerNotFound(drawer) : undefined;
+            default: return undefined;
+        }
+    };
+    const regions = {};
+    for (const [name, hash] of known) {
+        const html = await render(name);
+        if (html === undefined)
+            continue;
+        const next = regionHash(html);
+        if (next !== hash)
+            regions[name] = { hash: next, html };
+    }
+    return { ok: true, ...(drawer ? { drawer } : {}), regions, reviews: { count: reviews.length, items: reviews.map((item) => ({ id: item.id, title: item.title, gate: gateLabel(item.gate) })) } };
+};

package/dist/src/ui/markdown.d.ts

@@ -0,0 +1,2 @@
+/** Renders a small subset of Markdown to escaped HTML. Exported for tests. */
+export declare const markdownToHtml: (markdown: string) => string;

package/dist/src/ui/markdown.js

@@ -0,0 +1,127 @@
+/** Markdown renderer (minimal, escaping-first, no runtime dependency). */
+import { escapeHtml } from "./http.js";
+const safeUrl = (raw) => {
+    const url = raw.trim();
+    const scheme = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(url);
+    if (scheme && !/^(https?|mailto)$/i.test(scheme[1] ?? ""))
+        return "#";
+    return escapeHtml(url);
+};
+const renderInline = (text) => {
+    let out = escapeHtml(text);
+    out = out.replace(/`([^`]+)`/g, "<code>$1</code>");
+    out = out.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
+    out = out.replace(/__([^_]+)__/g, "<strong>$1</strong>");
+    out = out.replace(/\*([^*\s][^*]*)\*/g, "<em>$1</em>");
+    out = out.replace(/(^|[^\w])_([^_\s][^_]*)_(?![\w])/g, "$1<em>$2</em>");
+    out = out.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (_m, label, url) => `<a href="${safeUrl(url)}">${label}</a>`);
+    return out;
+};
+const splitRow = (line) => line.replace(/^\s*\|/, "").replace(/\|\s*$/, "").split("|");
+const isTableSeparator = (line) => /^[\s|:-]+$/.test(line.trim()) && line.includes("-");
+/** Renders a small subset of Markdown to escaped HTML. Exported for tests. */
+export const markdownToHtml = (markdown) => {
+    const lines = markdown.replace(/\r\n?/g, "\n").split("\n");
+    const html = [];
+    let i = 0;
+    let listKind = null;
+    let paragraph = [];
+    const flushParagraph = () => {
+        if (paragraph.length) {
+            html.push(`<p>${renderInline(paragraph.join(" "))}</p>`);
+            paragraph = [];
+        }
+    };
+    const closeList = () => {
+        if (listKind) {
+            html.push(`</${listKind}>`);
+            listKind = null;
+        }
+    };
+    while (i < lines.length) {
+        const line = lines[i] ?? "";
+        const trimmed = line.trim();
+        if (trimmed.startsWith("```")) {
+            flushParagraph();
+            closeList();
+            const codeLines = [];
+            i += 1;
+            while (i < lines.length && !(lines[i] ?? "").trim().startsWith("```")) {
+                codeLines.push(lines[i] ?? "");
+                i += 1;
+            }
+            i += 1;
+            html.push(`<pre><code>${escapeHtml(codeLines.join("\n"))}</code></pre>`);
+            continue;
+        }
+        const heading = /^(#{1,6})\s+(.*)$/.exec(trimmed);
+        if (heading) {
+            flushParagraph();
+            closeList();
+            const level = (heading[1] ?? "#").length;
+            html.push(`<h${level}>${renderInline(heading[2] ?? "")}</h${level}>`);
+            i += 1;
+            continue;
+        }
+        if (/^([-*_])(\s*\1){2,}\s*$/.test(trimmed)) {
+            flushParagraph();
+            closeList();
+            html.push("<hr>");
+            i += 1;
+            continue;
+        }
+        if (trimmed.startsWith(">")) {
+            flushParagraph();
+            closeList();
+            const quote = [];
+            while (i < lines.length && (lines[i] ?? "").trim().startsWith(">")) {
+                quote.push((lines[i] ?? "").trim().replace(/^>\s?/, ""));
+                i += 1;
+            }
+            html.push(`<blockquote>${renderInline(quote.join(" "))}</blockquote>`);
+            continue;
+        }
+        if (trimmed.includes("|") && i + 1 < lines.length && isTableSeparator(lines[i + 1] ?? "")) {
+            flushParagraph();
+            closeList();
+            const header = splitRow(trimmed);
+            i += 2;
+            const rows = [];
+            while (i < lines.length && (lines[i] ?? "").trim().includes("|")) {
+                rows.push(splitRow((lines[i] ?? "").trim()));
+                i += 1;
+            }
+            const cols = header.length;
+            const ths = header.map((c) => `<th>${renderInline(c.trim())}</th>`).join("");
+            const trs = rows.map((r) => `<tr>${Array.from({ length: cols }, (_x, k) => `<td>${renderInline((r[k] ?? "").trim())}</td>`).join("")}</tr>`).join("");
+            html.push(`<table class="table is-fullwidth is-striped is-bordered"><thead><tr>${ths}</tr></thead><tbody>${trs}</tbody></table>`);
+            continue;
+        }
+        const ul = /^\s*[-*+]\s+(.*)$/.exec(line);
+        const ol = /^\s*\d+[.)]\s+(.*)$/.exec(line);
+        if (ul || ol) {
+            flushParagraph();
+            const kind = ol ? "ol" : "ul";
+            if (listKind !== kind) {
+                closeList();
+                html.push(`<${kind}>`);
+                listKind = kind;
+            }
+            html.push(`<li>${renderInline((ul?.[1] ?? ol?.[1] ?? "").trim())}</li>`);
+            i += 1;
+            continue;
+        }
+        if (trimmed === "") {
+            flushParagraph();
+            closeList();
+            i += 1;
+            continue;
+        }
+        closeList();
+        paragraph.push(trimmed);
+        i += 1;
+    }
+    flushParagraph();
+    closeList();
+    return html.join("\n");
+};

package/dist/src/ui/options.d.ts

@@ -0,0 +1,48 @@
+export type UiAuthorityMode = "local" | "fleet";
+export interface UiOptions {
+    root: string;
+    host: string;
+    port: number;
+    /** Loop authority the dashboard reads and acts on; defaults to `.agents/config.json` `loop.mode` (local unless fleet). */
+    mode?: UiAuthorityMode;
+    /** Fleet reviewer credential held server-side; passed only to the approve child process. */
+    reviewerToken?: string;
+    /** Random id of this dashboard process, served at `/api/instance` so `loop down` signals
+     * only the dashboard it recorded (not whatever now answers on the same port). */
+    instance?: string;
+}
+export declare const scrubbedEnv: (extra?: Record<string, string>) => NodeJS.ProcessEnv;
+/**
+ * A credential from a file (`--reviewer-token-file`: the fleet reviewer credential the approve
+ * child process receives). The file must live outside the project (agents work inside it), be a
+ * regular non-symlink file, and be private to the owner (mode 600/400). With `create`, a missing
+ * file is created with a random token. The credential is never passed to the daemon, lead, or
+ * workers; it reaches only the single approve child process.
+ */
+export declare const readCredentialFile: (root: string, path: string, { create }: {
+    create: boolean;
+}) => string;
+/** Best-effort browser launch for `aidlc-kit ui --open`; failures are ignored (the URL is printed anyway). */
+export declare const openBrowser: (url: string) => void;
+/** The configured loop authority: `fleet` only when `loop.mode` says so; everything else reads local state. */
+export declare const resolveUiMode: (root: string) => UiAuthorityMode;
+export declare const uiMode: (options: UiOptions) => UiAuthorityMode;
+export declare const loopEntryPath: (root: string) => string;
+export declare const stateScriptPath: (root: string) => string;
+export declare const loopDataDir: (root: string) => string;
+export declare const eventsLogPath: (root: string) => string;
+/** Canonical task id (orchestrator §Turn routing); also the only names the per-task event logs use. */
+export declare const TASK_ID_PATTERN: RegExp;
+/** `.agents/data/tasks`: one directory per task (review artifacts at its root, operational data under `runtime/`). */
+export declare const tasksDataDir: (root: string) => string;
+/** `.agents/data/tasks/<taskId>/runtime`: the task's operational files (validate with TASK_ID_PATTERN first). */
+export declare const taskRuntimeDir: (root: string, taskId: string) => string;
+/** Where aidlc-kit versions before the `runtime/` layout kept the per-task event logs (`<taskId>.jsonl`, rotated to `.1`). */
+export declare const legacyTaskEventsDir: (root: string) => string;
+/** Per-task event log (`runtime/events.jsonl`, rotated to `events.jsonl.1`) of a canonical task id (validate with TASK_ID_PATTERN first). */
+export declare const taskEventsLogPath: (root: string, taskId: string) => string;
+/** The same log where older versions wrote it; read as a fallback until `loop migrate-data` has run. */
+export declare const legacyTaskEventsLogPath: (root: string, taskId: string) => string;
+export declare const daemonLockPath: (root: string) => string;
+export declare const daemonLogPath: (root: string) => string;
+export declare const loopArgs: (root: string, action: string, taskId?: string) => string[];

package/dist/src/ui/options.js

@@ -0,0 +1,81 @@
+/** Server options, credential hygiene for child processes, and installed-workflow paths. */
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+/** Credentials that never reach the daemon or read-only child processes. */
+const SCRUBBED_ENV = ["AIDLC_FLEET_REVIEWER_TOKEN", "AIDLC_UI_REVIEWER_TOKEN_FILE"];
+export const scrubbedEnv = (extra = {}) => {
+    const env = { ...process.env };
+    for (const name of SCRUBBED_ENV)
+        delete env[name];
+    return { ...env, ...extra };
+};
+/**
+ * A credential from a file (`--reviewer-token-file`: the fleet reviewer credential the approve
+ * child process receives). The file must live outside the project (agents work inside it), be a
+ * regular non-symlink file, and be private to the owner (mode 600/400). With `create`, a missing
+ * file is created with a random token. The credential is never passed to the daemon, lead, or
+ * workers; it reaches only the single approve child process.
+ */
+export const readCredentialFile = (root, path, { create }) => {
+    const target = resolve(path);
+    const project = resolve(root);
+    if (target === project || target.startsWith(`${project}${sep}`))
+        throw new Error("Credential file must live outside the project directory");
+    if (!existsSync(target)) {
+        if (!create)
+            throw new Error(`Credential file not found: ${target}`);
+        const token = randomBytes(32).toString("base64url");
+        writeFileSync(target, `${token}\n`, { flag: "wx", mode: 0o600 });
+        return token;
+    }
+    const stat = lstatSync(target);
+    if (stat.isSymbolicLink() || !stat.isFile())
+        throw new Error("Credential file must be a regular file, not a symlink");
+    if (process.platform !== "win32" && (stat.mode & 0o077) !== 0)
+        throw new Error(`Credential file must be private to its owner (chmod 600 ${target})`);
+    const token = readFileSync(target, "utf8").trim();
+    if (token.length < 16 || token.length > 256 || /\s/.test(token))
+        throw new Error("Credential file must contain one token of 16–256 non-whitespace characters");
+    return token;
+};
+/** Best-effort browser launch for `aidlc-kit ui --open`; failures are ignored (the URL is printed anyway). */
+export const openBrowser = (url) => {
+    const [command, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+    try {
+        const child = spawn(command, args, { detached: true, stdio: "ignore" });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch { /* no browser launcher */ }
+};
+/** The configured loop authority: `fleet` only when `loop.mode` says so; everything else reads local state. */
+export const resolveUiMode = (root) => {
+    try {
+        return JSON.parse(readFileSync(join(root, ".agents", "config.json"), "utf8"))?.loop?.mode === "fleet" ? "fleet" : "local";
+    }
+    catch {
+        return "local";
+    }
+};
+export const uiMode = (options) => options.mode ?? "local";
+export const loopEntryPath = (root) => join(root, ".agents", "aidlc", "scripts", "loop-entry.mjs");
+export const stateScriptPath = (root) => join(root, ".agents", "aidlc", "scripts", "state.mjs");
+export const loopDataDir = (root) => join(root, ".agents", "data", "loop");
+export const eventsLogPath = (root) => join(loopDataDir(root), "ui-events.jsonl");
+/** Canonical task id (orchestrator §Turn routing); also the only names the per-task event logs use. */
+export const TASK_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+/** `.agents/data/tasks`: one directory per task (review artifacts at its root, operational data under `runtime/`). */
+export const tasksDataDir = (root) => join(root, ".agents", "data", "tasks");
+/** `.agents/data/tasks/<taskId>/runtime`: the task's operational files (validate with TASK_ID_PATTERN first). */
+export const taskRuntimeDir = (root, taskId) => join(tasksDataDir(root), taskId, "runtime");
+/** Where aidlc-kit versions before the `runtime/` layout kept the per-task event logs (`<taskId>.jsonl`, rotated to `.1`). */
+export const legacyTaskEventsDir = (root) => join(loopDataDir(root), "events");
+/** Per-task event log (`runtime/events.jsonl`, rotated to `events.jsonl.1`) of a canonical task id (validate with TASK_ID_PATTERN first). */
+export const taskEventsLogPath = (root, taskId) => join(taskRuntimeDir(root, taskId), "events.jsonl");
+/** The same log where older versions wrote it; read as a fallback until `loop migrate-data` has run. */
+export const legacyTaskEventsLogPath = (root, taskId) => join(legacyTaskEventsDir(root), `${taskId}.jsonl`);
+export const daemonLockPath = (root) => join(loopDataDir(root), "daemon.lock");
+export const daemonLogPath = (root) => join(loopDataDir(root), "daemon.log");
+export const loopArgs = (root, action, taskId = "") => [loopEntryPath(root), action, taskId, root, "", "", "", ""];

package/dist/src/ui/security.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Request guards for a dashboard that has no session credential: the dashboard is meant for
+ * trusted local/LAN networks, so what remains to defend against is a browser on the same
+ * machine being used as a confused deputy (DNS rebinding, cross-site form posts, cross-site
+ * `fetch`). Three request-shape checks cover that:
+ *
+ * - **Host** must name the bound address (any loopback name when bound to loopback). A DNS
+ *   rebinding attack reaches the server with the attacker's hostname in `Host`, so it is
+ *   rejected before any route runs. A wildcard bind cannot be pinned to one name, so it
+ *   accepts only IP-literal or `localhost` Hosts (rebinding needs a DNS name) and otherwise
+ *   relies on the remaining checks (the launcher warns when exposing it).
+ * - **Origin** must be present and equal to `http://<Host>` on every state-changing request.
+ *   Browsers always attach `Origin` to cross-site `POST`s (forms and `fetch` alike), so a
+ *   foreign page can never make it match; a missing `Origin` is treated as foreign too.
+ *   **Sec-Fetch-Site**, when the browser sends it, must say `same-origin` (or `none` for a
+ *   direct navigation), which closes the same hole from the browser's own point of view.
+ * - A custom **x-aidlc-request** header must be present. It is not a "simple" header, so a
+ *   cross-site `fetch` cannot send it without a CORS preflight that this server never
+ *   answers, and an HTML form cannot set headers at all. The client sends `x-aidlc-request: 1`
+ *   on every `POST` (see `assets/ui/common.js` `post()`).
+ *
+ * `GET`/`HEAD`/`OPTIONS` are read-only and pass with just the Host check.
+ */
+import type { IncomingMessage } from "node:http";
+import type { UiOptions } from "./options.js";
+/** Custom header every state-changing request must carry (any value). */
+export declare const REQUEST_HEADER = "x-aidlc-request";
+/** DNS-rebinding guard plus the request-shape CSRF guards described in the module doc. */
+export declare const requestAllowed: (options: Pick<UiOptions, "host">, req: IncomingMessage) => {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};

package/dist/src/ui/security.js

@@ -0,0 +1,38 @@
+const LOOPBACK_HOSTS = ["127.0.0.1", "localhost", "[::1]"];
+/** Methods that never change state and therefore need only the Host check. */
+const READ_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+/** `host:port` forms that are not DNS names: IPv4, bracketed IPv6, or `localhost`. */
+const ADDRESS_HOST = /^(?:\d{1,3}(?:\.\d{1,3}){3}|\[[0-9a-f:.]+\]|localhost):\d{1,5}$/;
+/** Custom header every state-changing request must carry (any value). */
+export const REQUEST_HEADER = "x-aidlc-request";
+/** DNS-rebinding guard plus the request-shape CSRF guards described in the module doc. */
+export const requestAllowed = (options, req) => {
+    const host = String(req.headers.host ?? "").toLowerCase();
+    const port = req.socket?.localPort;
+    const bind = (options.host || "127.0.0.1").toLowerCase();
+    const wildcard = bind === "0.0.0.0" || bind === "::" || bind === "[::]";
+    if (!wildcard) {
+        const named = bind.includes(":") && !bind.startsWith("[") ? `[${bind}]` : bind;
+        const loopback = LOOPBACK_HOSTS.includes(named) || named === "::1";
+        const allowed = new Set([named, ...(loopback ? LOOPBACK_HOSTS : [])].map((name) => `${name}:${port}`));
+        if (!allowed.has(host))
+            return { ok: false, error: "Host header does not match this dashboard; open it at its bound address" };
+    }
+    else if (!ADDRESS_HOST.test(host)) {
+        // A wildcard bind cannot be pinned to one name, but DNS rebinding needs a DNS name:
+        // accept only IP literals and `localhost` (with the bound port) so a rebound page is still refused.
+        return { ok: false, error: "Host header must be an IP address or localhost on a wildcard bind" };
+    }
+    const method = (req.method ?? "GET").toUpperCase();
+    if (READ_METHODS.has(method))
+        return { ok: true };
+    const origin = req.headers.origin;
+    if (typeof origin !== "string" || origin.toLowerCase() !== `http://${host}`)
+        return { ok: false, error: "Cross-origin request rejected: Origin must match this dashboard" };
+    const site = req.headers["sec-fetch-site"];
+    if (typeof site === "string" && site !== "same-origin" && site !== "none")
+        return { ok: false, error: "Cross-site request rejected" };
+    if (req.headers[REQUEST_HEADER] === undefined)
+        return { ok: false, error: `Request rejected: missing ${REQUEST_HEADER} header` };
+    return { ok: true };
+};