@felixdotgo/aidlc-kit 0.2.0 → 0.3.0

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

@@ -0,0 +1,71 @@
+import { type UiOptions } from "./options.js";
+/** Canonical id pattern shared by task, assignment, item, and worker ids (`loop-worker-log.mjs`). */
+export declare const ID_PATTERN: RegExp;
+export declare const DEFAULT_TAIL_BYTES: number;
+export declare const MAX_TAIL_BYTES: number;
+export declare const TRUNCATED_PREFIX = "\u2026 (earlier output truncated)\n";
+/** How long one `docker ps` answer is shared per task (live polling runs every ~1.5 s). */
+export declare const DOCKER_PS_MAX_AGE_MS = 1500;
+/** One recorded container turn as written by the loop (`index.json`). */
+export interface WorkerIndexEntry {
+    name: string;
+    assignmentId: string;
+    itemId?: string;
+    workerId?: string;
+    agent?: string;
+    mode?: "local" | "fleet";
+    host?: string;
+    turn?: number;
+    startedAt: string;
+    endedAt?: string;
+    /** Exit code; null when the container ended by signal or was finalized without one. */
+    exitCode?: number | null;
+    log?: string;
+}
+export interface ContainerEntry extends WorkerIndexEntry {
+    /** Still running: no `endedAt` and docker lists the name (or docker is unavailable). */
+    running: boolean;
+    /** Recorded on this host, so its log file can be served from this checkout. */
+    local: boolean;
+}
+export interface ContainersPayload {
+    ok: true;
+    docker: "ok" | "unavailable";
+    host: string;
+    containers: ContainerEntry[];
+}
+export type ContainersResult = {
+    status: 200;
+    payload: ContainersPayload;
+} | {
+    status: 400 | 404;
+    payload: {
+        ok: false;
+        error: string;
+    };
+};
+export interface ContainerLogResult {
+    status: 200 | 400 | 404;
+    body: string;
+    contentType: "text/plain; charset=utf-8";
+    truncated: boolean;
+    size: number;
+}
+/** `.agents/data/tasks/<taskId>/runtime/workers`, every component checked for symlinks. */
+export declare const workerLogDirectory: (root: string, taskId: string) => string;
+export declare const workerIndexPath: (root: string, taskId: string) => string;
+export declare const workerLogPath: (root: string, taskId: string, assignmentId: string, generation?: number) => string;
+/** The task's container index; missing, corrupt, or symlinked reads as empty. */
+export declare const readWorkerIndex: (root: string, taskId: string) => WorkerIndexEntry[];
+/**
+ * The task's recorded containers with `running` and `local`. 400 for a malformed id,
+ * 404 for an unknown task; a missing or corrupt index is an empty list, never an error.
+ */
+export declare const taskContainers: (options: UiOptions, taskId: string) => Promise<ContainersResult>;
+/**
+ * The last `tailBytes` of one assignment's raw log (default 64 KiB, at most 1 MiB; a
+ * larger request is clamped). A tail that cut the file starts at the first complete
+ * line after the cut, prefixed with one `… (earlier output truncated)` line. When the
+ * current log is missing but a rotated `.log.1` exists, that generation is served.
+ */
+export declare const containerLog: (options: UiOptions, taskId: string, assignmentId: string, tailBytes?: number) => Promise<ContainerLogResult>;

package/dist/src/ui/containers.js

@@ -0,0 +1,214 @@
+/**
+ * Worker containers of one task for `/api/tasks/:id/containers` and the Containers
+ * panel, and the raw container log tail for `/api/tasks/:id/containers/:assignment/log`.
+ *
+ * The source of truth is the task's own runtime record, written by the loop
+ * (`loop-worker-log.mjs`) identically in local and fleet mode:
+ *
+ *   .agents/data/tasks/<taskId>/runtime/workers/index.json       one entry per container turn
+ *   .agents/data/tasks/<taskId>/runtime/workers/<assignmentId>.log  raw output (rotated once to .log.1)
+ *
+ * Docker only enriches `running`: `docker ps --filter label=aidlc.task=<id>` runs via
+ * `execFile` (no shell, allow-listed environment, 4 s timeout) and its result is shared
+ * for a short time so live polling does not spawn docker on every tick. When docker is
+ * missing, slow, or failing the index still answers and `docker` reads `unavailable`.
+ * Every path component is validated against the canonical id pattern and refused when
+ * it crosses a symlink (the same rule as the assignment records in ./changes.ts).
+ */
+import { execFile } from "node:child_process";
+import { lstatSync, readFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { join, resolve } from "node:path";
+import { readUiState, readUiTask } from "./data.js";
+import { readRange } from "./files.js";
+import { TASK_ID_PATTERN } from "./options.js";
+/** Canonical id pattern shared by task, assignment, item, and worker ids (`loop-worker-log.mjs`). */
+export const ID_PATTERN = TASK_ID_PATTERN;
+export const DEFAULT_TAIL_BYTES = 64 * 1024;
+export const MAX_TAIL_BYTES = 1024 * 1024;
+export const TRUNCATED_PREFIX = "… (earlier output truncated)\n";
+/** How long one `docker ps` answer is shared per task (live polling runs every ~1.5 s). */
+export const DOCKER_PS_MAX_AGE_MS = 1500;
+const DOCKER_TIMEOUT_MS = 4000;
+/** The only variables the docker CLI receives: where the binary is and how to reach the daemon. */
+const DOCKER_ENV = ["PATH", "HOME", "DOCKER_HOST", "DOCKER_CONTEXT", "DOCKER_CONFIG", "DOCKER_CERT_PATH", "DOCKER_TLS_VERIFY", "USERPROFILE", "SystemRoot", "TEMP", "TMP"];
+/* ---------------------------------------------------------------------------
+ * Paths (mirrors `workerLogDirectory` / `workerLogPath` in loop-worker-log.mjs)
+ * ------------------------------------------------------------------------- */
+class SymlinkRefused extends Error {
+}
+/** `lstat` that reads a missing entry as undefined and refuses a symlink. */
+const lstatNoFollow = (path) => {
+    try {
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink())
+            throw new SymlinkRefused(`Path crosses a symlink: ${path}`);
+        return stat;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+};
+/** `.agents/data/tasks/<taskId>/runtime/workers`, every component checked for symlinks. */
+export const workerLogDirectory = (root, taskId) => {
+    if (!ID_PATTERN.test(taskId))
+        throw new Error("Invalid task id");
+    let path = resolve(root);
+    for (const part of [".agents", "data", "tasks", taskId, "runtime", "workers"]) {
+        path = join(path, part);
+        lstatNoFollow(path);
+    }
+    return path;
+};
+export const workerIndexPath = (root, taskId) => join(workerLogDirectory(root, taskId), "index.json");
+export const workerLogPath = (root, taskId, assignmentId, generation = 0) => {
+    if (!ID_PATTERN.test(assignmentId))
+        throw new Error("Invalid assignment id");
+    return join(workerLogDirectory(root, taskId), `${assignmentId}.log${generation ? `.${generation}` : ""}`);
+};
+const validEntry = (entry) => entry !== null && typeof entry === "object" && !Array.isArray(entry)
+    && typeof entry.name === "string" && ID_PATTERN.test(entry.name)
+    && typeof entry.assignmentId === "string" && ID_PATTERN.test(entry.assignmentId)
+    && typeof entry.startedAt === "string";
+/** The task's container index; missing, corrupt, or symlinked reads as empty. */
+export const readWorkerIndex = (root, taskId) => {
+    let raw;
+    try {
+        const path = workerIndexPath(root, taskId);
+        if (!lstatNoFollow(path)?.isFile())
+            return [];
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return [];
+    }
+    try {
+        const value = JSON.parse(raw);
+        return Array.isArray(value) ? value.filter(validEntry) : [];
+    }
+    catch {
+        return [];
+    }
+};
+/* ---------------------------------------------------------------------------
+ * docker ps
+ * ------------------------------------------------------------------------- */
+const dockerEnv = () => {
+    const env = {};
+    for (const name of DOCKER_ENV) {
+        const value = process.env[name];
+        if (value !== undefined)
+            env[name] = value;
+    }
+    return env;
+};
+/** Names of the task's running containers, or undefined when docker cannot answer. */
+const dockerRunning = (taskId) => new Promise((done) => {
+    try {
+        execFile("docker", ["ps", "--filter", `label=aidlc.task=${taskId}`, "--format", "{{.Names}}"], { shell: false, env: dockerEnv(), timeout: DOCKER_TIMEOUT_MS, maxBuffer: 1024 * 1024, windowsHide: true, encoding: "utf8" }, (error, stdout) => {
+            if (error)
+                return done(undefined);
+            done(new Set(String(stdout).split(/\r?\n/).map((line) => line.trim()).filter(Boolean)));
+        });
+    }
+    catch {
+        done(undefined);
+    }
+});
+const dockerReads = new Map();
+/** One `docker ps` per task per DOCKER_PS_MAX_AGE_MS, shared by concurrent requests. */
+const sharedDockerRunning = (root, taskId) => {
+    const key = `${root}\0${taskId}`;
+    const now = Date.now();
+    const cached = dockerReads.get(key);
+    if (cached && now - cached.at < DOCKER_PS_MAX_AGE_MS)
+        return cached.value;
+    const value = dockerRunning(taskId);
+    dockerReads.set(key, { at: now, value });
+    if (dockerReads.size > 64) {
+        for (const [name, entry] of dockerReads)
+            if (now - entry.at >= DOCKER_PS_MAX_AGE_MS)
+                dockerReads.delete(name);
+    }
+    return value;
+};
+/* ---------------------------------------------------------------------------
+ * Public entry points
+ * ------------------------------------------------------------------------- */
+/**
+ * The task's recorded containers with `running` and `local`. 400 for a malformed id,
+ * 404 for an unknown task; a missing or corrupt index is an empty list, never an error.
+ */
+export const taskContainers = async (options, taskId) => {
+    if (!ID_PATTERN.test(taskId))
+        return { status: 400, payload: { ok: false, error: "Invalid task id" } };
+    const task = readUiTask(options, taskId, await readUiState(options));
+    if (!task)
+        return { status: 404, payload: { ok: false, error: `Task not found: ${taskId}` } };
+    const entries = readWorkerIndex(options.root, taskId);
+    const live = await sharedDockerRunning(options.root, taskId);
+    const host = hostname();
+    const containers = entries.map((entry) => ({
+        ...entry,
+        running: !entry.endedAt && (live === undefined || live.has(entry.name)),
+        local: entry.host === host,
+    }));
+    return { status: 200, payload: { ok: true, docker: live === undefined ? "unavailable" : "ok", host, containers } };
+};
+/**
+ * The last `tailBytes` of one assignment's raw log (default 64 KiB, at most 1 MiB; a
+ * larger request is clamped). A tail that cut the file starts at the first complete
+ * line after the cut, prefixed with one `… (earlier output truncated)` line. When the
+ * current log is missing but a rotated `.log.1` exists, that generation is served.
+ */
+export const containerLog = async (options, taskId, assignmentId, tailBytes = DEFAULT_TAIL_BYTES) => {
+    const contentType = "text/plain; charset=utf-8";
+    const fail = (status, body) => ({ status, body, contentType, truncated: false, size: 0 });
+    if (!ID_PATTERN.test(taskId))
+        return fail(400, "Invalid task id");
+    if (!ID_PATTERN.test(assignmentId))
+        return fail(400, "Invalid assignment id");
+    if (!Number.isSafeInteger(tailBytes) || tailBytes < 1)
+        return fail(400, "Invalid tail: expected a positive number of bytes");
+    const tail = Math.min(tailBytes, MAX_TAIL_BYTES);
+    const task = readUiTask(options, taskId, await readUiState(options));
+    if (!task)
+        return fail(404, `Task not found: ${taskId}`);
+    let path;
+    let size = 0;
+    try {
+        for (const generation of [0, 1]) {
+            const candidate = workerLogPath(options.root, taskId, assignmentId, generation);
+            const stat = lstatNoFollow(candidate);
+            if (stat?.isFile()) {
+                path = candidate;
+                size = stat.size;
+                break;
+            }
+        }
+    }
+    catch {
+        return fail(404, "Container log not found");
+    }
+    if (path === undefined)
+        return fail(404, "Container log not found");
+    const truncated = size > tail;
+    let buffer;
+    try {
+        buffer = readRange(path, truncated ? size - tail : 0, size, true);
+    }
+    catch {
+        return fail(404, "Container log not found");
+    }
+    let body = buffer.toString("utf8");
+    if (truncated) {
+        // Drop the partial first line; a tail with no newline at all is kept as is.
+        const newline = body.indexOf("\n");
+        if (newline >= 0)
+            body = body.slice(newline + 1);
+        body = TRUNCATED_PREFIX + body;
+    }
+    return { status: 200, body, contentType, truncated, size };
+};

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

@@ -0,0 +1,75 @@
+/** Runs an installed workflow script with the current Node binary without
+ * blocking the event loop; rejects with the child's stderr attached. */
+export declare const runNode: (root: string, args: string[], options: {
+    input?: string;
+    timeout: number;
+    env?: Record<string, string>;
+}) => Promise<string>;
+/** The child's structured error message (or stderr) for a failed `runNode`. */
+export declare const childError: (error: unknown) => string;
+export interface DaemonStatus {
+    running: boolean;
+    pid: number | null;
+    startedAt: string | null;
+    host?: string;
+}
+export declare const pidAlive: (pid: number) => boolean;
+/**
+ * Reads the singleton loop daemon lock written by `loop-daemon.mjs`. A lease whose
+ * `expiresAt` has passed is stale (the daemon renews it every 15 s), so a crashed
+ * daemon's reused pid is not mistaken for a live daemon. `host` names the machine
+ * that holds it (a shared filesystem can show another host's daemon).
+ */
+export declare const daemonStatus: (root: string) => DaemonStatus;
+export interface DaemonError {
+    taskId?: string;
+    message: string;
+    at?: string;
+    failures?: number;
+    retryInMs?: number;
+}
+/**
+ * Unresolved daemon errors from the tail of the event-log sidecar: a task's
+ * `daemon_turn_error` stays open until a later `daemon_turn` for that task, a
+ * poll that no longer lists it as actionable, or a daemon restart; a
+ * `daemon_poll_error` stays open until the next successful poll.
+ */
+export declare const daemonHealth: (root: string) => DaemonError[];
+/** Starts the local daemon unless a live one already holds the singleton lock.
+ * The daemon's stderr goes to `daemon.log` so start-up failures are visible.
+ * `extraEnv` (e.g. `AIDLC_ENV_FILE`) is added to the daemon's environment; the
+ * daemon itself loads the AIDLC env file and derives provider settings. */
+export declare const ensureDaemon: (root: string, extraEnv?: Record<string, string>) => {
+    pid: number | null;
+    started: boolean;
+};
+export interface StopResult {
+    wasRunning: boolean;
+    stopped: boolean;
+    pid: number | null;
+}
+/**
+ * Stops the local daemon through its staged shutdown: one SIGTERM finishes the current
+ * agent turn, a second (`now`) cancels it. The daemon counts signals and exits hard on the
+ * third, so the stage already requested is recorded in `daemon.stop` and repeated calls
+ * (`stop`, then `stop --now`, or `stop` twice) send only the missing signals and never a
+ * third. Waits up to `timeoutMs`; on Windows the signal ends the process immediately.
+ */
+export declare const stopDaemon: (root: string, { now, timeoutMs, pollMs }?: {
+    now?: boolean;
+    timeoutMs?: number;
+    pollMs?: number;
+}) => Promise<StopResult>;
+export declare const intakeTask: (root: string, requirement: string) => Promise<{
+    taskId: string;
+    title: string;
+}>;
+export declare const activateTask: (root: string, taskId: string) => Promise<unknown>;
+export declare const loopStatusJson: (root: string, taskId: string) => Promise<unknown>;
+export declare const approveGate: (root: string, taskId: string, gate: string, source: string) => Promise<unknown>;
+/** Human feedback keeps the task at its current gate. The audited status cancel
+ * records `Cancelled gate wait at <gate>: <feedback>` evidence and sets the task
+ * `active`; the loop runtime turns that into a "revise the review artifact, then
+ * re-present the gate" prompt — the same mechanism as typing feedback in the
+ * trusted terminal (`loop-gate.mjs`). It never approves anything. */
+export declare const feedbackGate: (root: string, taskId: string, feedback: string, source: string) => Promise<unknown>;

package/dist/src/ui/daemon.js

@@ -0,0 +1,232 @@
+/**
+ * Loop daemon status/health and the thin facades that spawn installed workflow scripts
+ * (`loop-entry.mjs`, `state.mjs`). This module never mutates lifecycle state itself.
+ */
+import { execFile, spawn } from "node:child_process";
+import { closeSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { readRange } from "./files.js";
+import { daemonLockPath, daemonLogPath, eventsLogPath, loopArgs, loopDataDir, scrubbedEnv, stateScriptPath } from "./options.js";
+/** Runs an installed workflow script with the current Node binary without
+ * blocking the event loop; rejects with the child's stderr attached. */
+export const runNode = (root, args, options) => new Promise((resolveRun, rejectRun) => {
+    const child = execFile(process.execPath, args, { cwd: root, encoding: "utf8", maxBuffer: 8 * 1024 * 1024, timeout: options.timeout, env: scrubbedEnv(options.env) }, (error, stdout, stderr) => {
+        if (error) {
+            rejectRun(Object.assign(error, { stderr }));
+            return;
+        }
+        resolveRun(stdout);
+    });
+    child.stdin?.end(options.input ?? "");
+});
+/** The child's structured error message (or stderr) for a failed `runNode`. */
+export const childError = (error) => {
+    if (error && typeof error === "object" && "stderr" in error) {
+        const stderr = String(error.stderr ?? "").trim();
+        try {
+            const parsed = JSON.parse(stderr);
+            if (parsed.error?.message)
+                return parsed.error.message;
+        }
+        catch { /* not JSON */ }
+        if (stderr)
+            return stderr;
+    }
+    return error instanceof Error ? error.message : String(error);
+};
+export const pidAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+};
+/**
+ * Reads the singleton loop daemon lock written by `loop-daemon.mjs`. A lease whose
+ * `expiresAt` has passed is stale (the daemon renews it every 15 s), so a crashed
+ * daemon's reused pid is not mistaken for a live daemon. `host` names the machine
+ * that holds it (a shared filesystem can show another host's daemon).
+ */
+export const daemonStatus = (root) => {
+    try {
+        const lock = JSON.parse(readFileSync(daemonLockPath(root), "utf8"));
+        const pid = typeof lock.pid === "number" && Number.isSafeInteger(lock.pid) && lock.pid > 0 ? lock.pid : null;
+        const host = typeof lock.host === "string" && lock.host ? lock.host : undefined;
+        const expired = typeof lock.expiresAt === "string" && Date.parse(lock.expiresAt) < Date.now();
+        const local = !host || host === hostname();
+        const running = pid !== null && !expired && (local ? pidAlive(pid) : true);
+        return { running, pid, startedAt: typeof lock.startedAt === "string" ? lock.startedAt : null, ...(host ? { host } : {}) };
+    }
+    catch {
+        return { running: false, pid: null, startedAt: null };
+    }
+};
+/** How much of the event-log tail the daemon health check scans. */
+const HEALTH_TAIL_BYTES = 64 * 1024;
+/**
+ * Unresolved daemon errors from the tail of the event-log sidecar: a task's
+ * `daemon_turn_error` stays open until a later `daemon_turn` for that task, a
+ * poll that no longer lists it as actionable, or a daemon restart; a
+ * `daemon_poll_error` stays open until the next successful poll.
+ */
+export const daemonHealth = (root) => {
+    const path = eventsLogPath(root);
+    let text = "";
+    try {
+        const size = statSync(path).size;
+        const start = Math.max(0, size - HEALTH_TAIL_BYTES);
+        text = readRange(path, start, size).toString("utf8");
+        if (start > 0)
+            text = text.slice(text.indexOf("\n") + 1);
+    }
+    catch {
+        return [];
+    }
+    const turnErrors = new Map();
+    let pollError = null;
+    for (const line of text.split("\n")) {
+        if (!line)
+            continue;
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!event || typeof event !== "object")
+            continue;
+        const taskId = typeof event.taskId === "string" ? event.taskId : undefined;
+        const record = () => ({
+            ...(taskId ? { taskId } : {}),
+            message: typeof event.message === "string" ? event.message : "error",
+            ...(typeof event.at === "string" ? { at: event.at } : {}),
+            ...(typeof event.failures === "number" ? { failures: event.failures } : {}),
+            ...(typeof event.retryInMs === "number" ? { retryInMs: event.retryInMs } : {}),
+        });
+        switch (event.type) {
+            case "daemon_start":
+                turnErrors.clear();
+                pollError = null;
+                break;
+            case "daemon_poll_error":
+                pollError = record();
+                break;
+            case "daemon_poll": {
+                pollError = null;
+                const actionable = Array.isArray(event.actionable) ? event.actionable : [];
+                for (const id of [...turnErrors.keys()])
+                    if (!actionable.includes(id))
+                        turnErrors.delete(id);
+                break;
+            }
+            case "daemon_turn":
+                if (taskId)
+                    turnErrors.delete(taskId);
+                break;
+            case "daemon_turn_error":
+                if (taskId)
+                    turnErrors.set(taskId, record());
+                break;
+            default: break;
+        }
+    }
+    return [...(pollError ? [pollError] : []), ...turnErrors.values()];
+};
+/** Starts the local daemon unless a live one already holds the singleton lock.
+ * The daemon's stderr goes to `daemon.log` so start-up failures are visible.
+ * `extraEnv` (e.g. `AIDLC_ENV_FILE`) is added to the daemon's environment; the
+ * daemon itself loads the AIDLC env file and derives provider settings. */
+export const ensureDaemon = (root, extraEnv = {}) => {
+    const current = daemonStatus(root);
+    if (current.running)
+        return { pid: current.pid, started: false };
+    mkdirSync(loopDataDir(root), { recursive: true });
+    rmSync(stopMarkerPath(root), { force: true }); // a new run starts with no stop requested
+    const log = openSync(daemonLogPath(root), "a");
+    try {
+        const child = spawn(process.execPath, loopArgs(root, "start"), {
+            cwd: root,
+            detached: true,
+            stdio: ["ignore", log, log],
+            // The daemon (and every lead/worker it spawns) never sees UI or reviewer credentials.
+            env: scrubbedEnv({ AIDLC_LOOP_EVENT_LOG: eventsLogPath(root), ...extraEnv }),
+        });
+        // Without a listener a spawn failure would be an unhandled 'error' event and
+        // crash the UI server; the daemon's own start-up errors go to daemon.log.
+        child.on("error", () => { });
+        child.unref();
+        return { pid: child.pid ?? null, started: true };
+    }
+    finally {
+        closeSync(log);
+    }
+};
+/** Shutdown stage already requested of a daemon pid: 1 = finish the turn, 2 = cancel it. */
+const stopMarkerPath = (root) => join(loopDataDir(root), "daemon.stop");
+/** The marker belongs to one daemon run (pid + lease start), so a later daemon that reuses
+ * the pid starts from stage 0. Signals sent outside `stopDaemon` (a terminal Ctrl-C on a
+ * foreground `loop start`) are not counted. */
+const requestedStage = (root, status) => {
+    try {
+        const marker = JSON.parse(readFileSync(stopMarkerPath(root), "utf8"));
+        return marker.pid === status.pid && marker.startedAt === status.startedAt && typeof marker.stage === "number" ? marker.stage : 0;
+    }
+    catch {
+        return 0;
+    }
+};
+/**
+ * Stops the local daemon through its staged shutdown: one SIGTERM finishes the current
+ * agent turn, a second (`now`) cancels it. The daemon counts signals and exits hard on the
+ * third, so the stage already requested is recorded in `daemon.stop` and repeated calls
+ * (`stop`, then `stop --now`, or `stop` twice) send only the missing signals and never a
+ * third. Waits up to `timeoutMs`; on Windows the signal ends the process immediately.
+ */
+export const stopDaemon = async (root, { now = false, timeoutMs = 15000, pollMs = 200 } = {}) => {
+    const status = daemonStatus(root);
+    if (!status.running || status.pid === null) {
+        rmSync(stopMarkerPath(root), { force: true });
+        return { wasRunning: false, stopped: true, pid: status.pid };
+    }
+    if (status.host && status.host !== hostname())
+        throw new Error(`The loop daemon runs on host ${status.host} (pid ${status.pid}); stop it there`);
+    const pid = status.pid;
+    const target = now ? 2 : 1;
+    for (let stage = requestedStage(root, status); stage < target; stage += 1) {
+        try {
+            process.kill(pid, "SIGTERM");
+        }
+        catch {
+            break; /* already exited */
+        }
+        writeFileSync(stopMarkerPath(root), `${JSON.stringify({ pid, startedAt: status.startedAt, stage: stage + 1, at: new Date().toISOString() })}\n`);
+        if (stage + 1 < target)
+            await new Promise((resolveWait) => setTimeout(resolveWait, 100));
+    }
+    for (let waited = 0; waited < timeoutMs && pidAlive(pid); waited += pollMs)
+        await new Promise((resolveWait) => setTimeout(resolveWait, pollMs));
+    const stopped = !pidAlive(pid);
+    if (stopped)
+        rmSync(stopMarkerPath(root), { force: true });
+    return { wasRunning: true, stopped, pid };
+};
+export const intakeTask = async (root, requirement) => {
+    const output = await runNode(root, loopArgs(root, "intake"), { input: requirement, timeout: 30000 });
+    const parsed = JSON.parse(output);
+    if (typeof parsed.taskId !== "string" || typeof parsed.title !== "string")
+        throw new Error("loop intake returned no task id");
+    return { taskId: parsed.taskId, title: parsed.title };
+};
+export const activateTask = async (root, taskId) => JSON.parse(await runNode(root, [stateScriptPath(root), "task", "status", taskId, "--status", "active", "--root", root], { timeout: 30000 }));
+export const loopStatusJson = async (root, taskId) => JSON.parse(await runNode(root, loopArgs(root, "status", taskId), { timeout: 5000 }));
+export const approveGate = async (root, taskId, gate, source) => JSON.parse(await runNode(root, [stateScriptPath(root), "gate", "approve", taskId, "--gate", gate, "--source", source, "--root", root], { timeout: 30000 }));
+/** Human feedback keeps the task at its current gate. The audited status cancel
+ * records `Cancelled gate wait at <gate>: <feedback>` evidence and sets the task
+ * `active`; the loop runtime turns that into a "revise the review artifact, then
+ * re-present the gate" prompt — the same mechanism as typing feedback in the
+ * trusted terminal (`loop-gate.mjs`). It never approves anything. */
+export const feedbackGate = async (root, taskId, feedback, source) => JSON.parse(await runNode(root, [stateScriptPath(root), "task", "status", taskId, "--status", "active", "--mode", "audited", "--reason", feedback, "--source", source, "--root", root], { timeout: 30000 }));

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

@@ -0,0 +1,42 @@
+import type { TaskState, WorkflowState } from "../model.js";
+import { type UiOptions } from "./options.js";
+export declare const ARTIFACT_NAMES: readonly ["intent", "design", "workplan"];
+/** Feedback entries not yet followed by a passing approval of that gate
+ * (mirrors `pendingFeedback` in the installed `loop-runtime.mjs`). */
+export declare const pendingFeedback: (task: Pick<TaskState, "evidence">) => Array<{
+    gate: string;
+    text: string;
+    recordedAt: string;
+}>;
+/** How stale a fleet read on the live-update path may be. Mutations always read fresh. */
+export declare const LIVE_FLEET_MAX_AGE_MS = 1000;
+export declare const readUiState: (options: UiOptions, maxAgeMs?: number) => Promise<WorkflowState>;
+export declare const readUiTask: (options: UiOptions, id: string, state: WorkflowState) => TaskState | undefined;
+export interface FleetGate {
+    ok?: boolean;
+    gate?: string;
+    status?: string;
+    checkpoint?: {
+        snapshotId?: string;
+        status?: string;
+    } | null;
+    snapshot?: {
+        id?: string;
+        reviewText?: string;
+        integrationCommit?: string | null;
+    } | null;
+}
+export declare const fleetGate: (options: UiOptions, id: string, maxAgeMs?: number) => Promise<FleetGate>;
+export declare const taskGatePayload: (options: UiOptions, id: string, known?: WorkflowState, maxAgeMs?: number) => Promise<{
+    ok: boolean;
+    error?: string;
+    gate?: string;
+    view?: unknown;
+    snapshot?: FleetGate["snapshot"];
+}>;
+export declare const artifactPayload: (root: string, id: string, name: string, task?: TaskState | undefined) => {
+    ok: boolean;
+    error?: string;
+    name?: string;
+    content?: string;
+};