@felixdotgo/aidlc-kit 0.2.0 → 0.3.0

package/dist/src/cli/commands.js

@@ -9,24 +9,67 @@ import { fileURLToPath } from "node:url";
 import { doctor, doctorData, status, statusData } from "../installer.js";
 import { applyMcpSetup, planMcpSetup } from "../mcp-setup.js";
 import { loadProjectConfig, resolveProfiles } from "../profiles.js";
-import { openBrowser, readUiTokenFile, startUiServer } from "../task-ui.js";
 import { assertKnownOptions, DOCTOR_FLAGS, flags, MCP_FLAGS, rootArg, STATUS_FLAGS, UI_FLAGS, value } from "./argv.js";
+import { loopDown, loopEnv, loopOverview, loopStop, loopUp, serveDashboard } from "./loop-launcher.js";
 import { confirmGeneral, mcpSetupSelections } from "./prompt.js";
+/** `loop leases [--task-id ID] [--root PATH] [--json] [--clear-stale]` and
+ * `loop migrate-data [--root PATH] [--json] [--dry-run]`: forwarded to
+ * loop-entry.mjs as `<action> [task-id] <root> [switches]`. */
+const loopDiagnosticArgs = (action, args) => {
+    const allowedSwitches = action === "leases" ? ["--json", "--clear-stale"] : ["--json", "--dry-run"];
+    const allowedValues = action === "leases" ? ["--task-id", "--root"] : ["--root"];
+    const parsed = new Map();
+    const switches = new Set();
+    for (let index = 0; index < args.length; index += 1) {
+        const key = args[index] ?? "";
+        if (allowedSwitches.includes(key)) {
+            if (switches.has(key))
+                throw new Error("Invalid or duplicate loop option");
+            switches.add(key);
+            continue;
+        }
+        const entry = args[index + 1];
+        if (!allowedValues.includes(key) || !entry || entry.startsWith("--") || parsed.has(key))
+            throw new Error("Invalid or duplicate loop option");
+        parsed.set(key, entry);
+        index += 1;
+    }
+    const root = resolve(parsed.get("--root") ?? ".");
+    return { root, argv: action === "leases" ? ["leases", parsed.get("--task-id") ?? "", root, ...switches] : ["migrate-data", root, ...switches] };
+};
 export const runLoopCommand = async (args) => {
     const action = args[0] ?? "";
-    if (!["start", "status", "resume", "intake", "worker-image"].includes(action))
-        throw new Error("Expected loop start, status, intake, or worker-image");
+    if (!["up", "down", "stop", "env", "start", "status", "resume", "intake", "worker-image", "leases", "migrate-data"].includes(action))
+        throw new Error("Expected loop up, down, stop, env, start, status, intake, leases, migrate-data, or worker-image");
+    if (action === "up")
+        return loopUp(args.slice(1));
+    if (action === "down")
+        return loopDown(args.slice(1));
+    if (action === "stop")
+        return loopStop(args.slice(1));
+    if (action === "env")
+        return loopEnv(args.slice(1));
+    if (action === "status" && !args.includes("--task-id"))
+        return loopOverview(args.slice(1));
+    if (action === "leases" || action === "migrate-data") {
+        const { root, argv } = loopDiagnosticArgs(action, args.slice(1));
+        const child = spawn(process.execPath, [join(root, ".agents", "aidlc", "scripts", "loop-entry.mjs"), ...argv], { stdio: "inherit" });
+        const code = await new Promise((resolveExit, rejectExit) => { child.once("error", rejectExit); child.once("exit", (exitCode) => resolveExit(exitCode)); });
+        if (code !== 0)
+            process.exitCode = code ?? 1;
+        return;
+    }
     const parsed = new Map();
     for (let index = 1; index < args.length; index += 2) {
         const key = args[index];
         const entry = args[index + 1];
-        if (key === undefined || !["--task-id", "--title", "--root", "--mode", "--provider", "--tag"].includes(key) || !entry || entry.startsWith("--") || parsed.has(key))
+        if (key === undefined || !["--task-id", "--title", "--root", "--mode", "--provider", "--tag", "--loop-env"].includes(key) || !entry || entry.startsWith("--") || parsed.has(key))
             throw new Error("Invalid or duplicate loop option");
         parsed.set(key, entry);
     }
     const root = resolve(parsed.get("--root") ?? ".");
     const script = join(root, ".agents", "aidlc", "scripts", "loop-entry.mjs");
-    const child = spawn(process.execPath, [script, action, parsed.get("--task-id") ?? "", root, parsed.get("--mode") ?? "", parsed.get("--provider") ?? "", parsed.get("--tag") ?? "", parsed.get("--title") ?? ""], { stdio: "inherit" });
+    const child = spawn(process.execPath, [script, action, parsed.get("--task-id") ?? "", root, parsed.get("--mode") ?? "", parsed.get("--provider") ?? "", parsed.get("--tag") ?? "", parsed.get("--title") ?? ""], { stdio: "inherit", env: { ...process.env, ...(parsed.has("--loop-env") ? { AIDLC_ENV_FILE: resolve(parsed.get("--loop-env") ?? "") } : {}) } });
     // Stay alive while the child runs so its own staged shutdown (stop after the
     // current turn → cancel the turn → exit) stays reachable. A terminal Ctrl-C
     // already reaches the child through the process group, so SIGINT is only
@@ -52,26 +95,13 @@ export const runLoopCommand = async (args) => {
 };
 export const runUi = async (args) => {
     assertKnownOptions(args, UI_FLAGS);
-    const root = resolve(rootArg(args));
+    const reviewerTokenFile = value(args, "--reviewer-token-file");
     const port = Number(value(args, "--port") ?? 4173);
     if (!Number.isInteger(port) || port < 1 || port > 65535)
         throw new Error("--port must be an integer between 1 and 65535");
-    const host = value(args, "--host") ?? "127.0.0.1";
-    const tokenFile = value(args, "--token-file");
-    const reviewerFile = value(args, "--reviewer-token-file");
-    const token = tokenFile ? readUiTokenFile(root, tokenFile, { create: true }) : undefined;
-    const reviewerToken = reviewerFile ? readUiTokenFile(root, reviewerFile, { create: false }) : undefined;
-    const { server, port: boundPort, token: sessionToken } = await startUiServer({ root, host, port, ...(token ? { token } : {}), ...(reviewerToken ? { reviewerToken } : {}) });
-    const base = `http://${host.includes(":") ? `[${host}]` : host}:${boundPort}`;
-    const loginUrl = `${base}/#token=${encodeURIComponent(sessionToken)}`;
-    console.log(`Loop (AI-DLC UI) listening on ${base} (Ctrl-C to stop)`);
-    console.log(`Open (signs this browser in for loop actions and gate approval): ${loginUrl}`);
-    if (flags(args).has("--open"))
-        openBrowser(loginUrl);
-    await new Promise((resolve) => {
-        const close = () => { server.close(() => resolve()); };
-        process.once("SIGINT", close);
-        process.once("SIGTERM", close);
+    await serveDashboard({
+        root: resolve(rootArg(args)), host: value(args, "--host") ?? "127.0.0.1", port, open: flags(args).has("--open"),
+        ...(reviewerTokenFile ? { reviewerTokenFile } : {}),
     });
 };
 const mcpSetupOptions = async (args) => {

package/dist/src/cli/loop-launcher.d.ts

@@ -0,0 +1,47 @@
+export interface LauncherArgs {
+    root: string;
+    values: Map<string, string>;
+    switches: Set<string>;
+}
+/** Parses `--flag value` / `--switch` options against the per-action allowlist. */
+export declare const parseLauncherArgs: (args: string[], allowed: string[]) => LauncherArgs;
+export declare const installerCliPath: (root: string) => string;
+export declare const recordInstallerCli: (root: string) => void;
+export declare const uiStatePath: (root: string) => string;
+interface UiRecord {
+    pid: number;
+    url: string;
+    startedAt: string;
+    instance?: string;
+}
+/** The recorded dashboard, if any. `running` only means the pid exists; use
+ * `dashboardReachable` before trusting or signalling it (the pid may have been reused). */
+export declare const readUiRecord: (root: string) => (UiRecord & {
+    running: boolean;
+}) | undefined;
+/** True when the recorded dashboard itself still answers: the URL serves the same random
+ * instance id the record holds (another project's dashboard on that port does not match). */
+export declare const dashboardReachable: (record: {
+    url: string;
+    instance?: string;
+}) => Promise<boolean>;
+export interface ServeOptions {
+    root: string;
+    host: string;
+    port: number;
+    open: boolean;
+    reviewerTokenFile?: string;
+    record?: boolean;
+}
+export declare const isLoopbackHost: (host: string) => boolean;
+/** Printed when the dashboard listens on a non-loopback address: it has no authentication. */
+export declare const EXPOSED_WARNING = "Warning: the dashboard has no authentication; expose it only on a trusted network.";
+/** Serves the dashboard until SIGINT/SIGTERM. `record` writes ui.json so `loop down`/`up` can find it. */
+export declare const serveDashboard: (options: ServeOptions) => Promise<void>;
+export declare const loopUp: (args: string[]) => Promise<void>;
+export declare const loopStop: (args: string[]) => Promise<void>;
+export declare const loopDown: (args: string[]) => Promise<void>;
+export declare const loopEnv: (args: string[]) => void;
+/** `loop status` without a task id: daemon, dashboard, and environment at a glance. */
+export declare const loopOverview: (args: string[]) => Promise<void>;
+export {};

package/dist/src/cli/loop-launcher.js

@@ -0,0 +1,322 @@
+/**
+ * One-command local loop: `loop up | down | stop | env | status` (no task id).
+ *
+ * `up` checks the configuration and environment (`loop-entry.mjs env`), starts the
+ * daemon detached, then serves the dashboard in the foreground. Ctrl-C closes only
+ * the dashboard; the daemon keeps running until `loop down` / `loop stop`. The
+ * shipped `.agents/aidlc/scripts/loop.sh|loop.cmd` wrappers forward to these commands.
+ */
+import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { packageVersion } from "../workflow.js";
+import { daemonHealth, daemonStatus, ensureDaemon, pidAlive, stopDaemon } from "../ui/daemon.js";
+import { daemonLogPath, loopDataDir, loopEntryPath, openBrowser, readCredentialFile, scrubbedEnv } from "../ui/options.js";
+import { startUiServer } from "../ui/server.js";
+const SWITCHES = new Set(["--open", "--no-ui", "--now", "--json"]);
+const VALUES = new Set(["--root", "--loop-env", "--port", "--host", "--reviewer-token-file"]);
+/** Parses `--flag value` / `--switch` options against the per-action allowlist. */
+export const parseLauncherArgs = (args, allowed) => {
+    const values = new Map();
+    const switches = new Set();
+    for (let index = 0; index < args.length; index += 1) {
+        const key = args[index] ?? "";
+        if (!allowed.includes(key))
+            throw new Error(`Unknown loop option: ${key}`);
+        if (SWITCHES.has(key)) {
+            switches.add(key);
+            continue;
+        }
+        const entry = args[index + 1];
+        if (!VALUES.has(key) || entry === undefined || entry.startsWith("--") || values.has(key))
+            throw new Error(`${key} requires a value`);
+        values.set(key, entry);
+        index += 1;
+    }
+    return { root: resolve(values.get("--root") ?? "."), values, switches };
+};
+/** `AIDLC_ENV_FILE` for children when `--loop-env` is given (resolved against the caller's cwd). */
+const envOverlay = (parsed) => {
+    const file = parsed.values.get("--loop-env");
+    return file ? { AIDLC_ENV_FILE: resolve(file) } : {};
+};
+const readConfig = (root) => {
+    try {
+        return JSON.parse(readFileSync(join(root, ".agents", "config.json"), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Fails with actionable guidance unless the project is installed with local loop mode. */
+const requireLocalLoop = (root) => {
+    if (!existsSync(loopEntryPath(root)))
+        throw new Error(`AI-DLC is not installed in ${root}; run: npx @felixdotgo/aidlc-kit init --loop-mode local`);
+    const mode = readConfig(root)?.loop?.mode ?? "off";
+    if (mode === "fleet")
+        throw new Error("loop up/down manage the local daemon; this project uses fleet mode (see docs/loop-runbook.md#fleet-multi-machine)");
+    if (mode !== "local")
+        throw new Error([
+            "Loop mode is off. Enable it in .agents/config.json:",
+            '  "loop": { "mode": "local", "agents": { "lead": "opencode", "workers": { "worker-a": "opencode" } } }',
+            "(providers: codex, claude, or opencode), or run: npx @felixdotgo/aidlc-kit init --loop-mode local",
+        ].join("\n"));
+};
+/** Runs `loop-entry.mjs env` for `root`; returns its exit status (output inherited or captured). */
+const envReport = (root, overlay, options = {}) => {
+    const result = spawnSync(process.execPath, [loopEntryPath(root), "env", root, ...(options.json ? ["--json"] : [])], {
+        cwd: root, encoding: "utf8", env: scrubbedEnv(overlay), stdio: options.capture ? ["ignore", "pipe", "pipe"] : "inherit",
+    });
+    if (result.error)
+        throw result.error;
+    return { status: result.status ?? 1, stdout: result.stdout ?? "" };
+};
+/* ---- Installing CLI record (`.agents/data/loop/cli.json`) ----
+ * `init`/`upgrade` record the CLI that wrote `.agents/`, so `loop.sh`/`loop.cmd` run that
+ * exact build even when it came from the npx cache or a local `.tgz` (npx caches those by
+ * spec, so `npx --no-install @felixdotgo/aidlc-kit` cannot find them). Machine-local data,
+ * next to daemon.lock and daemon.log; never part of the managed manifest. */
+export const installerCliPath = (root) => join(loopDataDir(root), "cli.json");
+export const recordInstallerCli = (root) => {
+    try {
+        mkdirSync(loopDataDir(root), { recursive: true });
+        const cli = fileURLToPath(new URL("../cli.js", import.meta.url));
+        writeFileSync(installerCliPath(root), `${JSON.stringify({ cli, version: packageVersion(), recordedAt: new Date().toISOString() }, null, 2)}\n`);
+    }
+    catch (error) {
+        console.warn(`warning: could not record the aidlc-kit CLI for the loop launcher (${error instanceof Error ? error.message : String(error)}); install the package in the project to use loop.sh`);
+    }
+};
+/* ---- Dashboard process record (`.agents/data/loop/ui.json`) ---- */
+export const uiStatePath = (root) => join(loopDataDir(root), "ui.json");
+/** The recorded dashboard, if any. `running` only means the pid exists; use
+ * `dashboardReachable` before trusting or signalling it (the pid may have been reused). */
+export const readUiRecord = (root) => {
+    try {
+        const record = JSON.parse(readFileSync(uiStatePath(root), "utf8"));
+        if (typeof record.pid !== "number" || typeof record.url !== "string")
+            return undefined;
+        return { pid: record.pid, url: record.url, startedAt: String(record.startedAt ?? ""), ...(typeof record.instance === "string" ? { instance: record.instance } : {}), running: pidAlive(record.pid) };
+    }
+    catch {
+        return undefined;
+    }
+};
+/** True when the recorded dashboard itself still answers: the URL serves the same random
+ * instance id the record holds (another project's dashboard on that port does not match). */
+export const dashboardReachable = async (record) => {
+    if (!record.instance)
+        return false;
+    try {
+        const response = await fetch(`${record.url}/api/instance`, { signal: AbortSignal.timeout(3000) });
+        const body = await response.json();
+        return response.ok && body.instance === record.instance;
+    }
+    catch {
+        return false;
+    }
+};
+/** A URL this machine can reach for a wildcard bind (0.0.0.0 / ::), else the bound host. */
+const recordHost = (host) => host === "0.0.0.0" ? "127.0.0.1" : host === "::" ? "::1" : host;
+const validPort = (raw) => {
+    const port = Number(raw ?? 4173);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new Error("--port must be an integer between 1 and 65535");
+    return port;
+};
+/** Loopback binds are reachable only from this machine; anything else exposes the dashboard. */
+const LOOPBACK_BINDS = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+export const isLoopbackHost = (host) => LOOPBACK_BINDS.has(host.toLowerCase());
+/** Printed when the dashboard listens on a non-loopback address: it has no authentication. */
+export const EXPOSED_WARNING = "Warning: the dashboard has no authentication; expose it only on a trusted network.";
+/** Serves the dashboard until SIGINT/SIGTERM. `record` writes ui.json so `loop down`/`up` can find it. */
+export const serveDashboard = async (options) => {
+    const { root, host } = options;
+    const port = validPort(String(options.port));
+    const reviewerToken = options.reviewerTokenFile ? readCredentialFile(root, options.reviewerTokenFile, { create: false }) : undefined;
+    const instance = randomUUID();
+    const { server, port: boundPort } = await startUiServer({ root, host, port, instance, ...(reviewerToken ? { reviewerToken } : {}) });
+    const base = `http://${host.includes(":") && !host.startsWith("[") ? `[${host}]` : host}:${boundPort}`;
+    console.log(`Loop (AI-DLC UI) listening on ${base} (Ctrl-C to stop)`);
+    console.log(`Open: ${base}`);
+    if (!isLoopbackHost(host))
+        console.log(EXPOSED_WARNING);
+    if (options.record) {
+        mkdirSync(loopDataDir(root), { recursive: true });
+        const local = recordHost(host);
+        const url = `http://${local.includes(":") ? `[${local}]` : local}:${boundPort}`;
+        writeFileSync(uiStatePath(root), `${JSON.stringify({ pid: process.pid, url, instance, startedAt: new Date().toISOString() })}\n`);
+    }
+    if (options.open)
+        openBrowser(base);
+    await new Promise((resolveClose) => {
+        const close = () => { server.close(() => resolveClose()); server.closeAllConnections?.(); };
+        process.once("SIGINT", close);
+        process.once("SIGTERM", close);
+    });
+    if (options.record && readUiRecord(root)?.pid === process.pid)
+        rmSync(uiStatePath(root), { force: true });
+};
+const sleep = (ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+const logTail = (root, lines = 15) => {
+    try {
+        return readFileSync(daemonLogPath(root), "utf8").trimEnd().split("\n").slice(-lines).join("\n");
+    }
+    catch {
+        return "";
+    }
+};
+/** Env file of this start: `--loop-env`, `AIDLC_ENV_FILE`, or the default. */
+const envFilePath = (root, overlay) => resolve(root, overlay.AIDLC_ENV_FILE ?? process.env.AIDLC_ENV_FILE ?? join(".agents", "loop.env"));
+/** Starts the daemon unless it runs; confirms it survived start-up. Returns false on failure. */
+const startDaemon = async (root, overlay) => {
+    const current = daemonStatus(root);
+    if (current.running) {
+        console.log(`Loop daemon already running (pid ${current.pid}${current.startedAt ? `, started ${current.startedAt}` : ""})`);
+        try {
+            if (current.startedAt && statSync(envFilePath(root, overlay)).mtimeMs > Date.parse(current.startedAt)) {
+                console.log("  note: the env file changed after the daemon started; restart it to apply: loop down, then loop up");
+            }
+        }
+        catch { /* no env file */ }
+        return true;
+    }
+    const started = ensureDaemon(root, overlay);
+    // The daemon writes its lock right after the environment check; an early exit means start-up failed.
+    for (let waited = 0; waited < 5000; waited += 250) {
+        await sleep(250);
+        if (daemonStatus(root).running) {
+            console.log(`Started the loop daemon (pid ${daemonStatus(root).pid}); log: ${daemonLogPath(root)}`);
+            return true;
+        }
+        if (started.pid !== null && !pidAlive(started.pid))
+            break;
+    }
+    if (daemonStatus(root).running)
+        return true;
+    if (started.pid !== null && pidAlive(started.pid)) {
+        console.log(`Loop daemon is starting (pid ${started.pid}); log: ${daemonLogPath(root)}`);
+        return true;
+    }
+    console.error(`The loop daemon exited during start-up. Last lines of ${daemonLogPath(root)}:`);
+    console.error(logTail(root) || "  (empty)");
+    return false;
+};
+export const loopUp = async (args) => {
+    const parsed = parseLauncherArgs(args, ["--root", "--loop-env", "--port", "--host", "--open", "--no-ui", "--reviewer-token-file"]);
+    const { root } = parsed;
+    requireLocalLoop(root);
+    const port = validPort(parsed.values.get("--port"));
+    const overlay = envOverlay(parsed);
+    if (envReport(root, overlay).status !== 0) {
+        console.error("\nFix the errors above, then run loop up again.");
+        process.exitCode = 1;
+        return;
+    }
+    console.log("");
+    if (!await startDaemon(root, overlay)) {
+        process.exitCode = 1;
+        return;
+    }
+    if (parsed.switches.has("--no-ui")) {
+        console.log("Dashboard not started (--no-ui). Start it with: aidlc-kit ui");
+        return;
+    }
+    const ui = readUiRecord(root);
+    if (ui?.running && ui.pid !== process.pid && await dashboardReachable(ui)) {
+        console.log(`Dashboard already running at ${ui.url} (pid ${ui.pid}); open it there, or stop it with loop down.`);
+        return;
+    }
+    // A daemon the dashboard starts later (New task after loop stop) loads the same env file.
+    if (overlay.AIDLC_ENV_FILE)
+        process.env.AIDLC_ENV_FILE = overlay.AIDLC_ENV_FILE;
+    await serveDashboard({
+        root, host: parsed.values.get("--host") ?? "127.0.0.1", port, open: parsed.switches.has("--open"), record: true,
+        ...(parsed.values.has("--reviewer-token-file") ? { reviewerTokenFile: parsed.values.get("--reviewer-token-file") } : {}),
+    });
+    console.log("Dashboard stopped. The loop daemon keeps running; stop it with: loop down");
+};
+const reportStop = (result, now) => {
+    if (!result.wasRunning) {
+        console.log("Loop daemon is not running");
+        return;
+    }
+    if (result.stopped) {
+        console.log(`Stopped the loop daemon (pid ${result.pid})`);
+        return;
+    }
+    console.log(now
+        ? `Loop daemon (pid ${result.pid}) is still shutting down; check again with: loop status`
+        : `Loop daemon (pid ${result.pid}) will stop after its current agent turn. To cancel that turn now: loop stop --now`);
+};
+export const loopStop = async (args) => {
+    const parsed = parseLauncherArgs(args, ["--root", "--now"]);
+    const now = parsed.switches.has("--now");
+    reportStop(await stopDaemon(parsed.root, { now }), now);
+};
+export const loopDown = async (args) => {
+    const parsed = parseLauncherArgs(args, ["--root", "--now"]);
+    const { root } = parsed;
+    const ui = readUiRecord(root);
+    // Signal only a dashboard that still answers at its recorded URL: after a crash or reboot
+    // the recorded pid may belong to an unrelated process.
+    if (ui?.running && ui.pid !== process.pid && await dashboardReachable(ui)) {
+        try {
+            process.kill(ui.pid, "SIGTERM");
+        }
+        catch { /* already gone */ }
+        for (let waited = 0; waited < 5000 && pidAlive(ui.pid); waited += 200)
+            await sleep(200);
+        console.log(pidAlive(ui.pid) ? `Dashboard (pid ${ui.pid}) did not stop yet` : `Stopped the dashboard (pid ${ui.pid})`);
+        if (!pidAlive(ui.pid))
+            rmSync(uiStatePath(root), { force: true });
+    }
+    else if (ui?.running && ui.pid !== process.pid) {
+        // Not provably ours (busy, or the pid was reused): never signal it; keep the record.
+        console.log(`Dashboard record (pid ${ui.pid}, ${ui.url}) did not answer as this project's dashboard; not stopping it. Close it with Ctrl-C, or delete ${uiStatePath(root)} if it is gone.`);
+    }
+    else if (ui)
+        rmSync(uiStatePath(root), { force: true });
+    const now = parsed.switches.has("--now");
+    reportStop(await stopDaemon(root, { now }), now);
+};
+export const loopEnv = (args) => {
+    const parsed = parseLauncherArgs(args, ["--root", "--loop-env", "--json"]);
+    if (!existsSync(loopEntryPath(parsed.root)))
+        throw new Error(`AI-DLC is not installed in ${parsed.root}`);
+    const { status } = envReport(parsed.root, envOverlay(parsed), { json: parsed.switches.has("--json") });
+    if (status !== 0)
+        process.exitCode = status;
+};
+/** `loop status` without a task id: daemon, dashboard, and environment at a glance. */
+export const loopOverview = async (args) => {
+    const parsed = parseLauncherArgs(args, ["--root", "--loop-env", "--json"]);
+    const { root } = parsed;
+    if (!existsSync(loopEntryPath(root)))
+        throw new Error(`AI-DLC is not installed in ${root}`);
+    const daemon = daemonStatus(root);
+    const errors = daemon.running ? daemonHealth(root) : [];
+    const record = readUiRecord(root);
+    const ui = record ? { ...record, running: record.running && await dashboardReachable(record) } : undefined;
+    if (parsed.switches.has("--json")) {
+        const env = envReport(root, envOverlay(parsed), { json: true, capture: true });
+        let parsedEnv = null;
+        try {
+            parsedEnv = JSON.parse(env.stdout);
+        }
+        catch {
+            parsedEnv = null;
+        }
+        console.log(JSON.stringify({ daemon: { ...daemon, errors }, ui: ui ?? null, env: parsedEnv }, null, 2));
+        return;
+    }
+    console.log(daemon.running ? `Daemon    : running · pid ${daemon.pid}${daemon.startedAt ? ` · started ${daemon.startedAt}` : ""}` : "Daemon    : stopped (start it with: loop up)");
+    for (const error of errors)
+        console.log(`  error   : ${error.taskId ? `${error.taskId}: ` : "poll: "}${error.message}`);
+    console.log(ui?.running ? `Dashboard : ${ui.url} · pid ${ui.pid}` : "Dashboard : not running (loop up starts it)");
+    console.log(`Log       : ${daemonLogPath(root)}`);
+    console.log("");
+    envReport(root, envOverlay(parsed));
+};

package/dist/src/cli.js

@@ -2,6 +2,7 @@
 import { resolvedAdapters } from "./adapters.js";
 import { assertKnownOptions, flags, INIT_FLAGS, rootArg, UNINSTALL_FLAGS, UPGRADE_FLAGS, usage } from "./cli/argv.js";
 import { runDoctor, runLoopCommand, runMcp, runProfile, runStatus, runUi } from "./cli/commands.js";
+import { recordInstallerCli } from "./cli/loop-launcher.js";
 import { initOptions } from "./cli/options.js";
 import { chooseLoop, confirmGeneral, interactive } from "./cli/prompt.js";
 import { applyPlan, detectedAgents, formatPlan, planInit, planUninstall, selectAgents } from "./installer.js";
@@ -53,6 +54,7 @@ const runInit = async (args) => {
         applyPlan(options.root, plan);
         console.log("Installed local AI-DLC workflow assets.");
     }
+    recordInstallerCli(options.root);
 };
 const runUninstall = async (args) => {
     assertKnownOptions(args, UNINSTALL_FLAGS);
@@ -83,6 +85,7 @@ const runUpgrade = async (args) => {
         throw new Error("Upgrade confirmation did not match the target version");
     const result = applyUpgrade(root, plan);
     console.log(`Upgrade complete. Backup: ${result.backup}; changed: ${result.changed}`);
+    recordInstallerCli(root);
 };
 const runHelp = () => console.log(usage);
 const runVersion = () => console.log(packageVersion());

package/dist/src/installer.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { adapters, findAdapter, resolvedAdapters } from "./adapters.js";
 import { loadProjectConfig } from "./profiles.js";
@@ -7,7 +7,7 @@ import { planProjectLayoutMigration } from "./project-migration.js";
 import { legacyManagedMarker, managedBlock, removeManagedBlock } from "./managed-content.js";
 import { hasOwnedManifest, managedContentHash, planLoopSelection, planManagedWrites, readManifest, readManifestFile, splitInventoryKey } from "./managed-planning.js";
 import { resolveProjectPathWithoutSymlinks } from "./project-path.js";
-import { contentHash, coreWorkflowFiles, initialProjectFiles, manifestSpec, packageVersion } from "./workflow.js";
+import { contentHash, coreWorkflowFiles, initialProjectFiles, isExecutableAsset, manifestSpec, packageVersion } from "./workflow.js";
 /** Manifest reading lives in the managed-planning core; this export path stays stable for existing importers. */
 export { readManifest } from "./managed-planning.js";
 const shortHash = (content) => contentHash(content).slice(0, 12);
@@ -44,6 +44,8 @@ export const applyPlan = (root, plan) => {
         const target = safeTarget(root, write.path);
         mkdirSync(dirname(target), { recursive: true });
         writeFileSync(target, write.content, "utf8");
+        if (isExecutableAsset(write.path) && process.platform !== "win32")
+            chmodSync(target, 0o755);
     }
 };
 export const formatPlan = (plan) => plan.map((item) => `${item.action.padEnd(8)} ${item.path} (${item.reason}; sha=${shortHash(item.contentEncoding === "base64" ? Buffer.from(item.content, "base64") : item.content)})`).join("\n");

package/dist/src/model/records.d.ts

@@ -76,6 +76,10 @@ export interface TaskState {
     };
     predecessorTaskId?: string;
     successorTaskId?: string;
+    /** Repository HEAD when the task was created (lowercase hex SHA, 7-64 chars). */
+    baseCommit?: string;
+    /** Repository HEAD when the task reached done (lowercase hex SHA, 7-64 chars). */
+    finalCommit?: string;
     createdAt: string;
     updatedAt: string;
 }

package/dist/src/state/validate.js

@@ -3,6 +3,8 @@ import { assertTaskArtifactPath, idPattern, iso, text } from "./guards.js";
 import { readyTaskItems } from "./items.js";
 import { archiveRecordPath } from "./paths.js";
 const taskStatuses = ["active", "blocked_on_user", "paused", "done", "closed", "superseded"];
+const commitPattern = /^[0-9a-f]{7,64}$/;
+const commitFields = ["baseCommit", "finalCommit"];
 export const validateLesson = (taskId, lesson) => {
     if (!lesson)
         throw new Error(`Invalid lesson: ${taskId}`);
@@ -72,6 +74,9 @@ export const validateTask = (id, task) => {
         throw new Error(`Invalid task successor: ${id}`);
     if (task.predecessorTaskId !== undefined && !text(task.predecessorTaskId))
         throw new Error(`Invalid task predecessor: ${id}`);
+    for (const field of commitFields)
+        if (task[field] !== undefined && !(typeof task[field] === "string" && commitPattern.test(task[field])))
+            throw new Error(`Invalid task ${field}: ${id}`);
     for (const path of Object.values(task.artifacts))
         if (path)
             assertTaskArtifactPath(id, path);

package/dist/src/task-ui.d.ts

@@ -1,54 +1,33 @@
-import { type IncomingMessage, type ServerResponse, type Server } from "node:http";
-export type UiAuthorityMode = "local" | "fleet";
-export interface UiOptions {
-    root: string;
-    host: string;
-    port: number;
-    token?: string;
-    /** 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;
-}
-export declare const scrubbedEnv: (extra?: Record<string, string>) => NodeJS.ProcessEnv;
 /**
- * Fixed token from a file (`--token-file`, `--reviewer-token-file`) so the browser stays signed in across
- * UI restarts. 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 token is never passed to the daemon, lead, or workers.
+ * Local web UI for the AI-DLC loop and task status.
+ *
+ * Read-only over canonical local state (`.agents/data/state/aidlc-state.json`).
+ * Loop start/resume are thin facades that spawn the installed `loop-entry.mjs`
+ * exactly as `aidlc-kit loop` does; gate approval is a thin facade that spawns
+ * the same atomic `state.mjs gate approve` command, and gate feedback spawns the
+ * audited `state.mjs task status … --status active --mode audited` cancel (the
+ * task stays at its gate; the loop lead revises and re-presents it). This module
+ * never mutates lifecycle state itself and never bypasses the fail-closed gate
+ * channel.
+ *
+ * Built on `node:http` only; Bulma CSS, the dashboard theme layer, and the
+ * client scripts are vendored static assets (no CDN, no runtime npm dependency).
+ * The dashboard has no session credential (it runs on trusted local/LAN
+ * networks); mutating actions (loop start/resume, gate feedback, gate approve)
+ * are protected by request-shape guards instead: a pinned Host header, a
+ * matching Origin, Sec-Fetch-Site, and a custom request header that forces a
+ * CORS preflight (see `./ui/security.ts`). Fleet gate approval additionally
+ * needs the reviewer credential (`AIDLC_FLEET_REVIEWER_TOKEN` or
+ * `--reviewer-token-file`), which reaches only the approve child process.
+ *
+ * The implementation lives in `./ui/` (see `./ui/server.ts` for the route
+ * table); this module is the stable public entry point.
  */
-export declare const readUiTokenFile: (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;
-/** DNS-rebinding and CSRF guard: the Host header must name the bound address (any loopback name when
- * bound to loopback; a wildcard bind cannot be pinned and relies on the token and Origin check), and a
- * state-changing request that carries an Origin must be same-origin. */
-export declare const requestAllowed: (options: Pick<UiOptions, "host">, req: IncomingMessage) => {
-    ok: true;
-} | {
-    ok: false;
-    error: string;
-};
-export interface DaemonStatus {
-    running: boolean;
-    pid: number | null;
-    startedAt: string | null;
-}
-/** Reads the singleton loop daemon lock written by `loop-daemon.mjs`. */
-export declare const daemonStatus: (root: string) => DaemonStatus;
-/** Renders a small subset of Markdown to escaped HTML. Exported for tests. */
-export declare const markdownToHtml: (markdown: string) => string;
-/** On a fresh connection the SSE stream replays at most this many lines. */
-export declare const SSE_REPLAY_LINES = 200;
-/** Builds the request handler for the UI server (exported for unit tests). */
-export declare const createUiHandler: (options: UiOptions) => (req: IncomingMessage, res: ServerResponse) => void;
-/** Starts the UI HTTP server and resolves once it is listening. */
-export declare const startUiServer: (options: UiOptions) => Promise<{
-    server: Server;
-    port: number;
-    token: string;
-}>;
+export { openBrowser, readCredentialFile, resolveUiMode, scrubbedEnv, type UiAuthorityMode, type UiOptions } from "./ui/options.js";
+export { requestAllowed } from "./ui/security.js";
+export { daemonHealth, daemonStatus, stopDaemon, type DaemonError, type DaemonStatus, type StopResult } from "./ui/daemon.js";
+export { markdownToHtml } from "./ui/markdown.js";
+export { NOTIFY_PAGE } from "./ui/views/layout.js";
+export { DONE_COLUMN_LIMIT } from "./ui/views/board.js";
+export { SSE_REPLAY_LINES } from "./ui/sse.js";
+export { createUiHandler, startUiServer } from "./ui/server.js";