otacon 0.1.0

package/dist/daemon/app.js

@@ -0,0 +1,1081 @@
+// otacond's HTTP surface (DESIGN.md §6 "HTTP API sketch"), as a Hono app
+// factory so tests drive it via app.request() with no socket.
+//
+// Long-poll delivery honors at-least-once (DECISIONS.md "SessionQueue API"):
+// an event is acked with queue.flush(event) only once the response bytes are
+// out. Under @hono/node-server the env carries the Node ServerResponse
+// (`outgoing`), whose "close" event fires exactly once per response —
+// writableFinished there distinguishes delivered (ack) from client-aborted
+// (requeue). Accessing c.req.raw.signal materializes node-server's lazy
+// AbortController, so a client that drops a *parked* poll aborts the signal
+// and the waiter is canceled without consuming anything.
+import { Hono } from "hono";
+import { isAbsolute, join } from "node:path";
+import { loadConfig } from "../shared/config.js";
+import { otaconPort } from "../shared/paths.js";
+import { parseQuestionSpec } from "../shared/question-spec.js";
+import { TERMINAL_STATUSES } from "../shared/types.js";
+import { VERSION } from "../shared/version.js";
+import { appendActivity, latestNote, readActivity } from "./activity.js";
+import { composeArtifact, localDate, pickArtifactRelPath } from "./approve.js";
+import { createDesktopNotifier } from "./desktop-notify.js";
+import { diffPlans } from "./diff.js";
+import { lint } from "./linter/index.js";
+import { Notifier } from "./notify.js";
+import { Presence } from "./presence.js";
+import { SessionQueue } from "./queue.js";
+import { writeFileAtomic } from "./store.js";
+import { answerQuestion, appendThreads, applyRevisionToThreads, commentThreadStates, readThreads, } from "./threads.js";
+import { answerEntry, appendEntries, appendEntry, readTranscript } from "./transcript.js";
+import { registerUiRoutes } from "./ui.js";
+/** Hard ceiling on ?wait= (seconds); agents ask for 540 under their 600s Bash cap. */
+const MAX_WAIT_SECONDS = 600;
+const badRequest = (c, message) => c.json({ error: { code: "E_BAD_REQUEST", message } }, 400);
+const notFound = (c, message) => c.json({ error: { code: "E_NOT_FOUND", message } }, 404);
+const timeoutEvent = (c) => c.json({ event: "timeout" });
+// A session in a terminal state is over (DESIGN.md §6, §12 status machine):
+// every state-mutating verb refuses — the CLI's pointer rules guard its side,
+// but curl/UI/--session calls must hit the same wall. Each route checks *after*
+// its body await (see sessionEnded in createApp): a pre-await snapshot goes
+// stale when a concurrent approve lands while the bytes stream in. (Note
+// `implementing` is non-terminal — it deliberately re-opens the mutating verbs
+// while the agent builds the approved plan, so it does NOT trip this wall.)
+const sessionOver = (c, id) => c.json({ error: { code: "E_SESSION_OVER", message: `session ${id} is over (terminal)` } }, 409);
+async function readJsonBody(c) {
+    try {
+        const parsed = await c.req.json();
+        return typeof parsed === "object" && parsed !== null
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** null/undefined = whole-plan; otherwise require {section} and keep known keys only. */
+function parseAnchor(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    if (typeof raw !== "object")
+        return undefined;
+    const { section, exact, prefix, suffix } = raw;
+    if (typeof section !== "string" || section === "")
+        return undefined;
+    const anchor = { section };
+    if (typeof exact === "string")
+        anchor.exact = exact;
+    if (typeof prefix === "string")
+        anchor.prefix = prefix;
+    if (typeof suffix === "string")
+        anchor.suffix = suffix;
+    return anchor;
+}
+/**
+ * Validate the submit body's `resolutions` (DESIGN.md §6): an object with
+ * only `changelog` (string) and `threads` (string → string). Strict — an
+ * unknown key is a typo that would silently drop resolutions, so it refuses.
+ * undefined/null = none provided ({}); any other bad shape = undefined.
+ */
+function parseResolutions(raw) {
+    if (raw === undefined || raw === null)
+        return {};
+    if (typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (key === "changelog" && typeof value === "string") {
+            out.changelog = value;
+        }
+        else if (key === "threads" && typeof value === "object" && value !== null && !Array.isArray(value)) {
+            // Null-prototype: JSON.parse can hand us an own "__proto__" key, and
+            // assigning it onto a plain object silently drops it — the strict shape
+            // must surface it to L5 (E_UNKNOWN_THREAD) instead.
+            const threads = Object.create(null);
+            for (const [id, reply] of Object.entries(value)) {
+                if (typeof reply !== "string")
+                    return undefined;
+                threads[id] = reply;
+            }
+            out.threads = threads;
+        }
+        else {
+            return undefined;
+        }
+    }
+    return out;
+}
+/** Build a transcript entry from a validated spec and its minted q<n> id. */
+function entryFromSpec(id, spec, askedAt) {
+    // `spec` is already normalized (no absent/false keys), so spreading it is the
+    // whole asked shape — keep this in lockstep with QuestionSpec, not field-wise.
+    return { id, ...spec, askedAt };
+}
+/** True when the Origin header names this daemon itself (the M2 web UI). */
+function sameOrigin(origin, host) {
+    try {
+        return host !== undefined && new URL(origin).host === host;
+    }
+    catch {
+        return false; // opaque origins ("null") and garbage are foreign
+    }
+}
+export function createApp(options) {
+    const { store } = options;
+    // One queue instance per session for the daemon's lifetime — every request
+    // must park on / enqueue into the same in-memory waiter list, and the
+    // SessionQueue constructor re-reads disk (it would resurrect unacked
+    // in-flight events if constructed per request).
+    const queues = new Map();
+    const queueFor = (id) => {
+        let queue = queues.get(id);
+        if (!queue) {
+            queue = new SessionQueue(store.eventsPath(id));
+            queues.set(id, queue);
+        }
+        return queue;
+    };
+    const sessionFor = (c) => store.getSession(c.req.param("id") ?? "");
+    // Mutating routes call this after their last await: reading the request
+    // body yields, and a concurrent approve can flip the session mid-read — a
+    // status captured before the await would let the stale handler mutate (or
+    // re-approve) an ended session. Everything from this re-check to the state
+    // writes is synchronous, so the answer cannot rot again. Gates on the
+    // terminal set (TERMINAL_STATUSES), so an `implementing` session — which
+    // re-opens the mutating verbs — sails through.
+    const sessionEnded = (id) => {
+        const status = store.getSession(id)?.status;
+        return status !== undefined && TERMINAL_STATUSES.includes(status);
+    };
+    // Agent presence (DESIGN.md §6): ephemeral, in-memory liveness only — the
+    // epoch-ms of each session's last agent contact. Every mutating verb and each
+    // `wait` park bumps it; the summary exposes it (plus `parked`) and the UI
+    // derives live/offline from its recency, so the daemon needs no timer. A
+    // restart starts empty (offline until the next call), which is correct.
+    const lastContact = new Map();
+    const bumpContact = (id) => {
+        lastContact.set(id, Date.now());
+    };
+    // UI pub/sub (DECISIONS.md "UI live updates"): every state mutation below
+    // publishes, and the SSE routes in ui.ts fan the events out to browsers.
+    const notifier = new Notifier();
+    const summarize = (session) => {
+        const state = store.readState(session.id);
+        return {
+            ...session,
+            revision: state.revision,
+            lastReviewedRevision: state.lastReviewedRevision,
+            pendingEvents: queueFor(session.id).size,
+            openQuestions: readTranscript(store.transcriptPath(session.id)).filter((e) => e.answer === undefined).length,
+            latestActivity: latestNote(store.activityPath(session.id)),
+            lastContactAt: lastContact.get(session.id),
+            parked: queueFor(session.id).waiterCount > 0,
+        };
+    };
+    const publishSession = (session) => notifier.publish({ type: "session", session: session.id, data: { session: summarize(session) } });
+    const publishQueue = (id, pending) => notifier.publish({ type: "queue", session: id, data: { session: id, pending } });
+    const publishThread = (id, thread) => notifier.publish({ type: "thread", session: id, data: { session: id, thread } });
+    const publishGrill = (id, entry) => notifier.publish({ type: "grill", session: id, data: { session: id, entry } });
+    // Desktop attention banners (DESIGN.md §6). Presence tracks which sessions
+    // have a *visible* review open; the notify sink fires the native macOS banner
+    // (a no-op off darwin). Both are injectable for tests.
+    const presence = options.presence ?? new Presence();
+    const notify = options.notify ?? createDesktopNotifier();
+    /**
+     * Fire a desktop banner for an attention moment unless the user is already
+     * watching this session's review (presence) or has disabled them (config,
+     * loaded fresh per session.repo so a repo override applies). The whole thing
+     * is wrapped: a spawn or config error must never break the submit/ask response
+     * — it is swallowed to stderr (DESIGN.md §13: zero-API-spend untouched; this
+     * is a local OS call).
+     */
+    const maybeNotify = (session, moment) => {
+        try {
+            if (!loadConfig(session.repo).notifications.desktop)
+                return;
+            if (presence.isWatched(session.id))
+                return;
+            const message = moment.kind === "revision"
+                ? `Revision r${moment.revision} ready for review`
+                : moment.kind === "questions"
+                    ? `${moment.count} questions need your answer`
+                    : moment.text.length > 80
+                        ? `${moment.text.slice(0, 79)}…`
+                        : moment.text;
+            notify({
+                title: session.title,
+                message,
+                url: `http://127.0.0.1:${otaconPort()}/s/${session.id}`,
+            });
+        }
+        catch (error) {
+            process.stderr.write(`otacond: desktop notification failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        }
+    };
+    /** Respond with the event; ack only after the bytes are out (see header comment). */
+    function respondEvent(c, queue, event) {
+        const session = event.payload.session;
+        const outgoing = c.env?.outgoing;
+        if (!outgoing) {
+            queue.flush(event); // app.request() test path: no socket to wait on
+            publishQueue(session, queue.size);
+        }
+        else if (outgoing.destroyed || outgoing.closed) {
+            // Client vanished before we built the response. The closed check matters:
+            // once "close" has fired, a listener added below would never run and the
+            // event would sit unacked-unrequeued in the in-flight list until restart.
+            queue.requeue(event);
+        }
+        else {
+            outgoing.once("close", () => {
+                if (outgoing.writableFinished)
+                    queue.flush(event);
+                else
+                    queue.requeue(event);
+                publishQueue(session, queue.size);
+            });
+        }
+        return c.json(event.payload);
+    }
+    const app = new Hono();
+    // Loopback binding doesn't stop a malicious webpage from firing fetch() at
+    // 127.0.0.1 (no-cors requests are delivered even though the response is
+    // opaque). Browsers always attach Origin to cross-origin POSTs; the CLI and
+    // curl send none, and the M2 web UI is same-origin — so a foreign Origin on
+    // a state-changing call is refused (DECISIONS.md "Foreign-Origin requests").
+    app.use("/api/*", async (c, next) => {
+        const origin = c.req.header("origin");
+        if (c.req.method !== "GET" && origin !== undefined && !sameOrigin(origin, c.req.header("host"))) {
+            return c.json({ error: { code: "E_FORBIDDEN", message: "cross-origin requests are refused" } }, 403);
+        }
+        await next();
+    });
+    app.onError((error, c) => c.json({ error: { code: "E_INTERNAL", message: error.message } }, 500));
+    app.notFound((c) => c.json({ error: { code: "E_NOT_FOUND", message: `no route: ${c.req.method} ${c.req.path}` } }, 404));
+    app.get("/api/health", (c) => c.json({ app: "otacond", version: VERSION, pid: process.pid }));
+    app.post("/api/shutdown", (c) => {
+        // Fire the hook only once the response is out (or the client is already
+        // gone): main.ts exits the process in it, and a timing guess would race
+        // the response flush.
+        const outgoing = c.env?.outgoing;
+        if (outgoing && !outgoing.destroyed && !outgoing.closed) {
+            outgoing.once("close", () => options.onShutdown?.());
+        }
+        else {
+            options.onShutdown?.();
+        }
+        return c.json({ ok: true });
+    });
+    app.get("/api/sessions", (c) => c.json({ sessions: store.listSessions() }));
+    app.post("/api/sessions", async (c) => {
+        const body = (await readJsonBody(c)) ?? {};
+        const { title, repo, branch, quick } = body;
+        if (typeof title !== "string" || title.trim() === "") {
+            return badRequest(c, "title must be a non-empty string");
+        }
+        if (typeof repo !== "string" || !isAbsolute(repo)) {
+            return badRequest(c, "repo must be an absolute path");
+        }
+        if (branch !== undefined && typeof branch !== "string") {
+            return badRequest(c, "branch must be a string");
+        }
+        if (quick !== undefined && typeof quick !== "boolean") {
+            return badRequest(c, "quick must be a boolean");
+        }
+        const session = store.createSession({ title, repo, branch, quick });
+        publishSession(session);
+        return c.json(session, 201);
+    });
+    app.get("/api/sessions/:id", (c) => {
+        const session = sessionFor(c);
+        if (!session)
+            return notFound(c, `unknown session: ${c.req.param("id")}`);
+        return c.json(summarize(session));
+    });
+    // DELETE removes a session from the registry, status-branched on whether it
+    // has committed value (DESIGN.md §6, §12). **Terminal** (approved, plus
+    // implemented/implement_failed once a build finishes): its plan + transcript
+    // are committed under docs/plans/, so the working dir is *archived* to
+    // .otacon/archive/ (recoverable) — `otacon clean` and the UI's delete of an
+    // over session both take this path. Gated on TERMINAL_STATUSES so this split
+    // agrees with the UI's `over` (which passes `approved={isOver(status)}` to the
+    // confirm sheet) — otherwise an `implemented` delete would promise archival
+    // and silently hard-delete. **Non-terminal** (draft/in_review/revising, and a
+    // live `implementing` build): the working dir is *hard-removed* (permanent),
+    // and any parked agent is woken with a terminal `deleted` event so its `wait`
+    // loop stops cleanly. Both publish the same terminal `removed` frame; the
+    // response carries `archivedTo` (the archive path, or null for a hard-delete).
+    app.delete("/api/sessions/:id", (c) => {
+        const session = sessionFor(c);
+        if (!session)
+            return notFound(c, `unknown session: ${c.req.param("id")}`);
+        const queue = queueFor(session.id);
+        const pendingEvents = queue.size;
+        let archivedTo = null;
+        if (TERMINAL_STATUSES.includes(session.status)) {
+            // Deregister first — it can throw (registry flush), and an early queue
+            // eviction would orphan in-flight ack tracking for a session that is in
+            // fact still registered. Close the evicted instance before the move so a
+            // late in-flight ack cannot recreate .otacon/<id>/ next to the archive.
+            store.deleteSession(session.id);
+            queue.close();
+            queues.delete(session.id);
+            archivedTo = store.archiveSessionDir(session.repo, session.id);
+        }
+        else {
+            // Wake any parked agent BEFORE deregistering so its respondEvent still
+            // resolves against a registered session; closeWith sets the queue closed
+            // first, so the hard-remove below can't be recreated by a late ack. Then
+            // deregister and permanently drop the working dir (no committed value).
+            queue.closeWith({ event: "deleted", session: session.id });
+            queues.delete(session.id);
+            store.deleteSession(session.id);
+            store.removeSessionDir(session.repo, session.id);
+        }
+        // Terminal frame: the index and switcher drop the session live, and an
+        // open review tab flips to its closed state instead of error-limbo.
+        notifier.publish({ type: "removed", session: session.id, data: { session: session.id } });
+        return c.json({ ok: true, session: session.id, repo: session.repo, pendingEvents, archivedTo });
+    });
+    app.get("/api/sessions/:id/events", (c) => {
+        const session = sessionFor(c);
+        if (!session)
+            return notFound(c, `unknown session: ${c.req.param("id")}`);
+        const queue = queueFor(session.id);
+        // Any events call is the agent on the line; bump presence before deciding
+        // whether to park (covers the fast-path and wait=0 drains too).
+        bumpContact(session.id);
+        const raw = Number(c.req.query("wait") ?? "0");
+        const waitSeconds = Number.isFinite(raw)
+            ? Math.min(Math.max(raw, 0), MAX_WAIT_SECONDS)
+            : 0;
+        // Fast path and parking are one synchronous block: no enqueue can slip
+        // between this take() and park() (DECISIONS.md "SessionQueue: synchronous").
+        const immediate = queue.take();
+        if (immediate)
+            return respondEvent(c, queue, immediate);
+        if (waitSeconds === 0)
+            return timeoutEvent(c);
+        const signal = c.req.raw.signal; // materializes node-server's AbortController
+        // node-server only aborts that controller if it existed when the socket's
+        // "close" fired. A client that vanished before this handler ran would
+        // otherwise park a zombie waiter for the full wait window.
+        const outgoing = c.env?.outgoing;
+        if (signal.aborted || outgoing?.destroyed || outgoing?.closed)
+            return timeoutEvent(c);
+        return new Promise((resolve) => {
+            let settled = false;
+            let timer;
+            let handle;
+            const settle = (response) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                handle?.cancel();
+                signal.removeEventListener("abort", onAbort);
+                // Leaving the park flips `parked` (the waiter is gone): broadcast a
+                // fresh summary so a dropped agent's dot can fall to offline instead
+                // of the last frame's parked=true sticking forever. Re-read the
+                // registry — the session may have flipped (approve) or vanished
+                // (clean) during the park.
+                const current = store.getSession(session.id);
+                if (current)
+                    publishSession(current);
+                resolve(response);
+            };
+            // Aborted while parked: cancel the waiter; queued events stay queued.
+            // (Aborted after wake-up is the respondEvent requeue path instead.)
+            const onAbort = () => settle(timeoutEvent(c));
+            handle = queue.park((event) => settle(respondEvent(c, queue, event)));
+            if (!settled) {
+                // Genuinely parked (the queue was empty at take()): broadcast
+                // parked=true + the refreshed lastContactAt so the live dot reaches the
+                // UI within one park slice (DESIGN.md §6).
+                publishSession(session);
+                timer = setTimeout(() => settle(timeoutEvent(c)), waitSeconds * 1000);
+                signal.addEventListener("abort", onAbort);
+            }
+        });
+    });
+    app.post("/api/sessions/:id/submit", async (c) => {
+        const session = sessionFor(c);
+        if (!session)
+            return notFound(c, `unknown session: ${c.req.param("id")}`);
+        // Raw markdown body, or {"plan": "...", "resolutions": {...}} JSON — the
+        // CLI sends resolutions.json's content along (DESIGN.md §6). The raw path
+        // carries no resolutions, so L5 still rejects it when threads are open.
+        let content = await c.req.text();
+        if (sessionEnded(session.id))
+            return sessionOver(c, session.id);
+        bumpContact(session.id);
+        let resolutions = {};
+        if (c.req.header("content-type")?.includes("json")) {
+            let body;
+            try {
+                body = JSON.parse(content);
+            }
+            catch {
+                body = undefined;
+            }
+            const plan = body?.plan;
+            if (typeof plan !== "string")
+                return badRequest(c, "JSON body must carry a string plan");
+            const parsed = parseResolutions(body.resolutions);
+            if (!parsed) {
+                return badRequest(c, 'resolutions must be {"changelog"?: string, "threads"?: {"t<n>": "reply"}}');
+            }
+            content = plan;
+            resolutions = parsed;
+        }
+        if (content.trim() === "")
+            return badRequest(c, "request body must be the plan markdown");
+        const state = store.readState(session.id);
+        const replies = resolutions.threads ?? {};
+        const result = lint(content, loadConfig(session.repo), {
+            session: session.id,
+            expectedRevision: state.revision + 1,
+            expectedStatus: "in_review",
+            // L3/L5 context is composed here: rules stay pure, the daemon does the I/O.
+            grill: {
+                quick: session.quick,
+                knownQuestions: readTranscript(store.transcriptPath(session.id)).map((e) => e.id),
+            },
+            resolutions: {
+                revision: state.revision + 1,
+                commentThreads: commentThreadStates(store.threadsPath(session.id)),
+                replies,
+                changelog: resolutions.changelog,
+            },
+        });
+        if (!result.ok) {
+            return c.json({ ok: false, errors: result.errors, warnings: result.warnings }, 422);
+        }
+        const changelog = (resolutions.changelog ?? "").trim() === "" ? null : resolutions.changelog;
+        const revision = store.saveRevision(session.id, content, result.warnings, changelog ?? undefined);
+        // The accepted revision settles its threads: resolutions land on their
+        // threads, every anchor is re-located in the new text, lost ones orphan
+        // (DESIGN.md §4, §9). SSE upserts keep the rail live.
+        const changedThreads = applyRevisionToThreads(store.threadsPath(session.id), {
+            plan: content,
+            replies,
+            revision,
+        });
+        const updated = store.updateSession(session.id, { status: "in_review" });
+        publishSession(updated);
+        notifier.publish({
+            type: "revision",
+            session: session.id,
+            data: { session: session.id, revision, changelog },
+        });
+        for (const thread of changedThreads)
+            publishThread(session.id, thread);
+        // The ball is back in the user's court: a fresh revision awaits review.
+        maybeNotify(session, { kind: "revision", revision });
+        return c.json({
+            ok: true,
+            session: session.id,
+            revision,
+            status: "in_review",
+            warnings: result.warnings,
+            resolved: Object.keys(replies),
+        });
+    });
+    // The user's side of re-review bookkeeping (DESIGN.md §9 layer 3): the UI's
+    // "mark reviewed" / banner-dismiss POSTs here; comment flushes mark it
+    // implicitly. Monotonic — see Store.markReviewed.
+    app.post("/api/sessions/:id/reviewed", async (c) => {
+        const session = sessionFor(c);
+        if (!session)
+            return notFound(c, `unknown session: ${c.req.param("id")}`);
+        const state = store.readState(session.id);
+        if (state.revision === 0) {
+            return badRequest(c, "session has no revisions to mark reviewed");
+        }
+        const body = (await readJsonBody(c)) ?? {};
+        const revision = body.revision ?? state.revision;
+        if (typeof revision !== "number" || !Number.isInteger(revision) || revision < 1 || revision > state.revision) {
+            return badRequest(c, `revision must be an integer 1..${state.revision}`);
+        }
+        const lastReviewedRevision = store.markReviewed(session.id, revision);
+        publishSession(session); // summary re-reads state, so the frame carries it
+        return c.json({ ok: true, session: session.id, lastReviewedRevision });
+    });
+    // The review screen reports its visibility here (DESIGN.md §6): {visible:true}
+    // when shown + on a heartbeat, {visible:false} on blur/unload. The daemon
+    // suppresses a desktop banner only while a review is visible — a hidden or
+    // backgrounded tab (its SSE stream still open) does NOT suppress. No status
+    // change, so it stays callable on an approved session (a closing tab still
+    // pings); presence is ephemeral, not persisted.
+    app.post("/api/sessions/:id/presence", async (c) => {
+        const session = sessionFor(c);
+        if (!session)
+            return notFound(c, `unknown session: ${c.req.param("id")}`);
+        const body = (await readJsonBody(c)) ?? {};
+        if (typeof body.visible !== "boolean") {
+            return badRequest(c, "visible must be a boolean");
+        }
+        if (body.visible)
+            presence.markVisible(session.id);
+        else
+            presence.markHidden(session.id);
+        return c.json({ ok: true, session: session.id, visible: body.visible });
+    });
+    // Structural diff between two stored revisions (DESIGN.md §6, §9 layer 3).
+    // Defaults: to = latest, from = last-reviewed (?from= selects any other
+    // baseline; 0 = the empty plan, so a never-reviewed session shows all-new).
+    app.get("/api/sessions/:id/diff", (c) => {
+        const session = sessionFor(c);
+        if (!session)
+            return notFound(c, `unknown session: ${c.req.param("id")}`);
+        const state = store.readState(session.id);
+        if (state.revision === 0) {
+            return notFound(c, `session ${session.id} has no revisions to diff`);
+        }
+        const parseRev = (raw, fallback) => {
+            if (raw === undefined || raw === "")
+                return fallback;
+            const n = Number(raw);
+            return Number.isInteger(n) ? n : undefined;
+        };
+        const to = parseRev(c.req.query("to"), state.revision);
+        const from = parseRev(c.req.query("from"), state.lastReviewedRevision);
+        if (to === undefined || to < 1 || to > state.revision) {
+            return badRequest(c, `to must be a revision number 1..${state.revision}`);
+        }
+        if (from === undefined || from < 0 || from > state.revision) {
+            return badRequest(c, `from must be a revision number 0..${state.revision} (0 = empty plan)`);
+        }
+        const payload = {
+            session: session.id,
+            from,
+            to,
+            sections: diffPlans(from === 0 ? "" : store.readRevision(session.id, from), store.readRevision(session.id, to)),
+        };
+        return c.json(payload);
+    });
+    app.post("/api/sessions/:id/comments", async (c) => {
+        const session = sessionFor(c);
+        if (!session)
+            return notFound(c, `unknown session: ${c.req.param("id")}`);
+        const queue = queueFor(session.id); // before any state write: can throw on a corrupt file
+        const body = (await readJsonBody(c)) ?? {};
+        if (sessionEnded(session.id))
+            return sessionOver(c, session.id);
+        bumpContact(session.id);
+        const rawItems = body.items;
+        if (!Array.isArray(rawItems) || rawItems.length === 0) {
+            return badRequest(c, "items must be a non-empty array");
+        }
+        const drafts = [];
+        for (const raw of rawItems) {
+            const anchor = parseAnchor(raw?.anchor);
+            if (typeof raw?.body !== "string" || raw.body.trim() === "" || anchor === undefined) {
+                return badRequest(c, "each item needs a non-empty body and a valid anchor (or null)");
+            }
+            drafts.push({ anchor, body: raw.body });
+        }
+        // Ids are minted only after the whole batch validates, in one counter
+        // write — a rejected batch burns neither ids nor disk writes.
+        const counters = store.bumpCounters(session.id, {
+            thread: drafts.length,
+            batch: 1,
+            eventSeq: 1,
+        });
+        const firstThread = counters.thread - drafts.length;
+        const items = drafts.map((draft, i) => ({
+            thread: `t${firstThread + i + 1}`,
+            ...draft,
+        }));
+        const batch = `b${counters.batch}`;
+        // Each item becomes a persistent thread (DESIGN.md §9) — the rail's
+        // source of truth; the queued event is only the agent's wake-up copy.
+        const createdAt = new Date().toISOString();
+        const threads = items.map((item) => ({
+            id: item.thread,
+            kind: "comment",
+            batch,
+            anchor: item.anchor,
+            body: item.body,
+            createdAt,
+        }));
+        appendThreads(store.threadsPath(session.id), threads);
+        // Flushing a batch is the implicit "I reviewed this revision" signal
+        // (DESIGN.md §9 layer 3) — the diff baseline moves with it.
+        store.markReviewed(session.id, store.readState(session.id).revision);
+        // Comments are revision requests (DECISIONS.md "Status transitions"); flip
+        // status before the enqueue wakes a parked agent.
+        const updated = store.updateSession(session.id, { status: "revising" });
+        const payload = { event: "comments", session: session.id, batch, items };
+        queue.enqueue(payload, counters.eventSeq);
+        publishSession(updated); // after the enqueue, so the summary carries the fresh pending count
+        for (const thread of threads)
+            publishThread(session.id, thread);
+        return c.json({ ok: true, batch, threads: items.map((i) => i.thread), seq: counters.eventSeq }, 202);
+    });
+    app.post("/api/sessions/:id/questions", async (c) => {
+        const session = sessionFor(c);
+        if (!session)
+            return notFound(c, `unknown session: ${c.req.param("id")}`);
+        const queue = queueFor(session.id); // before any state write: can throw on a corrupt file
+        const body = (await readJsonBody(c)) ?? {};
+        if (sessionEnded(session.id))
+            return sessionOver(c, session.id);
+        bumpContact(session.id);
+        if (typeof body.body !== "string" || body.body.trim() === "") {
+            return badRequest(c, "question needs a non-empty body");
+        }
+        // A follow-up (DESIGN.md §9) names the question it continues with `replyTo`
+        // and inherits that conversation's anchor — so a client anchor is ignored on
+        // a follow-up; a root question parses its own anchor (or null = whole-plan).
+        let anchor;
+        let replyTo;
+        let inheritOrphan = false;
+        const replyToRaw = body.replyTo;
+        if (replyToRaw === undefined) {
+            const parsed = parseAnchor(body.anchor);
+            if (parsed === undefined) {
+                return badRequest(c, "question needs a valid anchor (or null)");
+            }
+            anchor = parsed;
+        }
+        else {
+            if (typeof replyToRaw !== "string" || replyToRaw === "") {
+                return badRequest(c, "replyTo must name a question thread id (q<n>)");
+            }
+            const existing = readThreads(store.threadsPath(session.id));
+            const parent = existing.find((t) => t.id === replyToRaw && t.kind === "question");
+            if (!parent) {
+                return c.json({
+                    error: {
+                        code: "E_UNKNOWN_QUESTION",
+                        message: `session ${session.id} has no question ${replyToRaw}`,
+                    },
+                }, 404);
+            }
+            // Resolve the root so a whole chain shares one key — "follow up on a
+            // follow-up" collapses to the same root, whose anchor (and orphan state)
+            // the new turn inherits and travels with.
+            const rootId = parent.replyTo ?? parent.id;
+            const root = existing.find((t) => t.id === rootId && t.kind === "question");
+            const source = root ?? parent;
+            replyTo = rootId;
+            anchor = source.anchor;
+            inheritOrphan = source.anchorState === "orphaned";
+        }
+        const counters = store.bumpCounters(session.id, { question: 1, eventSeq: 1 });
+        const id = `q${counters.question}`;
+        const thread = {
+            id,
+            kind: "question",
+            anchor,
+            ...(inheritOrphan ? { anchorState: "orphaned" } : {}),
+            body: body.body,
+            createdAt: new Date().toISOString(),
+            ...(replyTo !== undefined ? { replyTo } : {}),
+        };
+        appendThreads(store.threadsPath(session.id), [thread]);
+        // Questions leave the plan — and the status — untouched (DESIGN.md §9).
+        const payload = {
+            event: "question",
+            session: session.id,
+            id,
+            anchor,
+            body: body.body,
+            ...(replyTo !== undefined ? { replyTo } : {}),
+        };
+        queue.enqueue(payload, counters.eventSeq);
+        publishQueue(session.id, queue.size);
+        publishThread(session.id, thread);
+        return c.json({ ok: true, id, seq: counters.eventSeq }, 202);
+    });
+    // The agent's side of a user question (otacon answer, DESIGN.md §6, §9):
+    // the answer lands on the thread — the plan and the status stay untouched —
+    // and the UI's "answering…" placeholder resolves over SSE.
+    app.post("/api/sessions/:id/questions/:qid/answer", async (c) => {
+        const session = sessionFor(c);
+        if (!session)
+            return notFound(c, `unknown session: ${c.req.param("id")}`);
+        const body = (await readJsonBody(c)) ?? {};
+        if (sessionEnded(session.id))
+            return sessionOver(c, session.id);
+        bumpContact(session.id);
+        if (typeof body.body !== "string" || body.body.trim() === "") {
+            return badRequest(c, "answer needs a non-empty body");
+        }
+        const qid = c.req.param("qid") ?? "";
+        const thread = answerQuestion(store.threadsPath(session.id), qid, body.body);
+        if (!thread) {
+            return c.json({
+                error: {
+                    code: "E_UNKNOWN_QUESTION",
+                    message: `session ${session.id} has no question ${qid}`,
+                },
+            }, 404);
+        }
+        publishThread(session.id, thread);
+        return c.json({
+            ok: true,
+            session: session.id,
+            question: qid,
+            answeredAt: thread.answer.answeredAt,
+        });
+    });
+    app.get("/api/sessions/:id/threads", (c) => {
+        const session = sessionFor(c);
+        if (!session)
+            return notFound(c, `unknown session: ${c.req.param("id")}`);
+        return c.json({ session: session.id, threads: readThreads(store.threadsPath(session.id)) });
+    });
+    // The agent's grill question (otacon ask, DESIGN.md §6, §8): persisted in
+    // the transcript and pushed to the UI as a card; no agent event is queued —
+    // the asker goes straight back to `otacon wait` for the answer. Accepts a
+    // single question body or a batch (`{questions:[…]}`) of independent
+    // questions — independent siblings the agent posts in one call (§8); they
+    // render as ordinary cards, each answered instantly.
+    app.post("/api/sessions/:id/ask", async (c) => {
+        const session = sessionFor(c);
+        if (!session)
+            return notFound(c, `unknown session: ${c.req.param("id")}`);
+        const body = (await readJsonBody(c)) ?? {};
+        if (sessionEnded(session.id))
+            return sessionOver(c, session.id);
+        bumpContact(session.id);
+        // Batch: validate every member first, then mint all ids in one counter
+        // bump and append them in one write — a malformed member fails the whole
+        // batch, so the queue never holds a partial set (DECISIONS.md).
+        if (body.questions !== undefined) {
+            const raw = body.questions;
+            if (!Array.isArray(raw) || raw.length === 0) {
+                return badRequest(c, "questions must be a non-empty array of question objects");
+            }
+            const specs = [];
+            for (let i = 0; i < raw.length; i++) {
+                const spec = parseQuestionSpec(raw[i]);
+                if (typeof spec === "string")
+                    return badRequest(c, `questions[${i}] ${spec}`);
+                specs.push(spec);
+            }
+            const counters = store.bumpCounters(session.id, { question: specs.length });
+            const first = counters.question - specs.length;
+            const askedAt = new Date().toISOString();
+            const entries = specs.map((spec, i) => entryFromSpec(`q${first + i + 1}`, spec, askedAt));
+            appendEntries(store.transcriptPath(session.id), entries);
+            for (const entry of entries)
+                publishGrill(session.id, entry);
+            publishSession(store.getSession(session.id) ?? session);
+            // A batch coalesces to one banner — N questions need answering (DESIGN.md §6).
+            maybeNotify(session, entries.length === 1
+                ? { kind: "question", text: specs[0].question }
+                : { kind: "questions", count: entries.length });
+            return c.json({ ok: true, session: session.id, ids: entries.map((e) => e.id) }, 201);
+        }
+        const spec = parseQuestionSpec(body);
+        if (typeof spec === "string")
+            return badRequest(c, spec);
+        const counters = store.bumpCounters(session.id, { question: 1 });
+        const entry = entryFromSpec(`q${counters.question}`, spec, new Date().toISOString());
+        appendEntry(store.transcriptPath(session.id), entry);
+        publishGrill(session.id, entry);
+        // The summary's openQuestions just moved: the index's "questions pending"
+        // chip rides session frames, so every transcript change publishes one.
+        publishSession(store.getSession(session.id) ?? session);
+        maybeNotify(session, { kind: "question", text: spec.question });
+        return c.json({ ok: true, session: session.id, id: entry.id }, 201);
+    });
+    // The user's side of a grill question (DESIGN.md §6, §8): the answer lands
+    // on the transcript entry and an `answer` event wakes the parked agent.
+    app.post("/api/sessions/:id/answers", async (c) => {
+        const session = sessionFor(c);
+        if (!session)
+            return notFound(c, `unknown session: ${c.req.param("id")}`);
+        const queue = queueFor(session.id); // before any state write: can throw on a corrupt file
+        const body = (await readJsonBody(c)) ?? {};
+        if (sessionEnded(session.id))
+            return sessionOver(c, session.id);
+        const { question, choice, choices, text } = body;
+        if (typeof question !== "string" || question === "") {
+            return badRequest(c, "question must name a transcript question id (q<n>)");
+        }
+        const asked = readTranscript(store.transcriptPath(session.id)).find((e) => e.id === question);
+        if (!asked) {
+            return c.json({
+                error: {
+                    code: "E_UNKNOWN_QUESTION",
+                    message: `session ${session.id} has no grill question ${question}`,
+                },
+            }, 404);
+        }
+        if (text !== undefined && typeof text !== "string") {
+            return badRequest(c, "text must be a string");
+        }
+        // The answer must fit the question's shape: chips for option questions
+        // (one chip, or 1+ under --multi), free text for optionless ones. A
+        // non-empty custom answer with no chip is valid on option questions too
+        // (native-AskUserQuestion "Other" parity, DESIGN.md §8) — and text may
+        // still ride a chosen chip as a note.
+        const customText = typeof text === "string" && text.trim() !== "";
+        const noChips = choice === undefined && choices === undefined;
+        if (noChips) {
+            // "Other" parity (DESIGN.md §8): a non-empty custom answer with no chip
+            // is valid on ANY question shape — the one branch-independent rule, so it
+            // lives here, not re-stated per shape. Only the hint names the shape.
+            if (!customText) {
+                const need = asked.options === undefined
+                    ? "a non-empty text answer"
+                    : asked.multi === true
+                        ? "chosen choices or a non-empty custom answer"
+                        : "a single choice from its options or a non-empty custom answer";
+                return badRequest(c, `${question} needs ${need}`);
+            }
+        }
+        else if (asked.options === undefined) {
+            return badRequest(c, `${question} has no options — answer with text only`);
+        }
+        else if (asked.multi === true) {
+            const ok = choice === undefined &&
+                Array.isArray(choices) &&
+                choices.length > 0 &&
+                choices.every((x) => typeof x === "string" && asked.options.includes(x)) &&
+                new Set(choices).size === choices.length;
+            if (!ok) {
+                return badRequest(c, `${question} is multi-choice — pass distinct choices from its options`);
+            }
+        }
+        else if (choices !== undefined || typeof choice !== "string" || !asked.options.includes(choice)) {
+            // Single-choice with a chip: exactly one valid `choice`, never `choices`.
+            return badRequest(c, `${question} needs a single choice from its options`);
+        }
+        const answer = {
+            ...(typeof choice === "string" ? { choice } : {}),
+            ...(Array.isArray(choices) ? { choices: choices } : {}),
+            ...(customText ? { text: text } : {}),
+            answeredAt: new Date().toISOString(),
+        };
+        // Re-answering overwrites (at-least-once: a duplicate POST is legitimate);
+        // the agent sees a second answer event with the same question id.
+        const updated = answerEntry(store.transcriptPath(session.id), question, answer);
+        const payload = {
+            event: "answer",
+            session: session.id,
+            question,
+            ...(answer.choice !== undefined ? { choice: answer.choice } : {}),
+            ...(answer.choices !== undefined ? { choices: answer.choices } : {}),
+            ...(answer.text !== undefined ? { text: answer.text } : {}),
+        };
+        queue.enqueue(payload, store.bumpCounter(session.id, "eventSeq"));
+        publishQueue(session.id, queue.size);
+        if (updated)
+            publishGrill(session.id, updated);
+        // openQuestions dropped (or held, on a re-answer) — keep the chip honest.
+        publishSession(store.getSession(session.id) ?? session);
+        return c.json({ ok: true, session: session.id, question }, 202);
+    });
+    app.get("/api/sessions/:id/transcript", (c) => {
+        const session = sessionFor(c);
+        if (!session)
+            return notFound(c, `unknown session: ${c.req.param("id")}`);
+        return c.json({
+            session: session.id,
+            transcript: readTranscript(store.transcriptPath(session.id)),
+        });
+    });
+    // The agent's narration (otacon progress, DESIGN.md §6, §8): a non-blocking
+    // progress note appended to the capped activity feed and pushed to the UI as
+    // an `activity` frame (the per-session log) plus a `session` frame (the
+    // chip's latestActivity). No agent event is queued — like `ask`, this is
+    // UI-only telemetry, never a wake-up. The note is trimmed to the configured
+    // max so long narration never fails or bloats payloads.
+    app.post("/api/sessions/:id/progress", async (c) => {
+        const session = sessionFor(c);
+        if (!session)
+            return notFound(c, `unknown session: ${c.req.param("id")}`);
+        const body = (await readJsonBody(c)) ?? {};
+        if (sessionEnded(session.id))
+            return sessionOver(c, session.id);
+        const raw = body.note;
+        if (typeof raw !== "string" || raw.trim() === "") {
+            return badRequest(c, "note must be a non-empty string");
+        }
+        const { activity } = loadConfig(session.repo);
+        const trimmed = raw.trim();
+        const text = trimmed.length > activity.noteMaxChars
+            ? `${trimmed.slice(0, Math.max(1, activity.noteMaxChars - 1)).trimEnd()}…`
+            : trimmed;
+        const note = appendActivity(store.activityPath(session.id), text, activity.cap, new Date().toISOString());
+        bumpContact(session.id);
+        notifier.publish({ type: "activity", session: session.id, data: { session: session.id, note } });
+        publishSession(session); // latestActivity for the chip; fresh contact for the dot
+        return c.json({ ok: true, session: session.id, note: text });
+    });
+    // Approve ends the planning session (DESIGN.md §6 step 6, §12): the daemon
+    // writes docs/plans/YYYY-MM-DD-<slug>.md (final revision, status: approved,
+    // grill transcript appended) and queues the `approved` event for the parked
+    // agent to commit the file. Plain Approve flips the session `approved` —
+    // terminal, every mutating verb then refuses. **Approve & Implement**
+    // ({implement:true}) instead flips it to the non-terminal `implementing` and
+    // sets `implement:true` on the event: the agent commits the plan exactly as
+    // plain Approve, then proceeds to build it (DESIGN.md §12). Unresolved
+    // threads refuse 409 unless {force}.
+    app.post("/api/sessions/:id/approve", async (c) => {
+        const session = sessionFor(c);
+        if (!session)
+            return notFound(c, `unknown session: ${c.req.param("id")}`);
+        const queue = queueFor(session.id); // before any state write: can throw on a corrupt file
+        const body = (await readJsonBody(c)) ?? {};
+        // Doubles as the double-approve guard: two concurrent approves both
+        // snapshot in_review, but the loser re-checks here after its body await
+        // and refuses instead of writing a second (-2 suffixed) artifact.
+        if (sessionEnded(session.id))
+            return sessionOver(c, session.id);
+        // `implementing` is non-terminal, so it slips past sessionEnded — but a
+        // build is already under way, and re-approving would re-write the artifact
+        // and re-queue the wake-up. Refuse it explicitly (the second tap on an
+        // Approve & Implement, or a stray approve while the agent builds).
+        if (store.getSession(session.id)?.status === "implementing") {
+            return c.json({
+                error: {
+                    code: "E_ALREADY_IMPLEMENTING",
+                    message: `session ${session.id} is already implementing`,
+                },
+            }, 409);
+        }
+        if (body.force !== undefined && typeof body.force !== "boolean") {
+            return badRequest(c, "force must be a boolean");
+        }
+        if (body.implement !== undefined && typeof body.implement !== "boolean") {
+            return badRequest(c, "implement must be a boolean");
+        }
+        const implement = body.implement === true;
+        const state = store.readState(session.id);
+        if (state.revision === 0) {
+            return c.json({
+                error: {
+                    code: "E_NO_REVISION",
+                    message: `session ${session.id} has no revisions to approve`,
+                },
+            }, 409);
+        }
+        // Unresolved = comment threads with no resolution + user questions with no
+        // answer — the same open items the rail shows. The 409 carries the count;
+        // the UI warns and retries with {force:true} on confirm.
+        const unresolved = readThreads(store.threadsPath(session.id)).filter((t) => t.kind === "comment" ? t.resolution === undefined : t.answer === undefined).length;
+        if (unresolved > 0 && body.force !== true) {
+            return c.json({
+                error: {
+                    code: "E_UNRESOLVED_THREADS",
+                    message: `session has ${unresolved} unresolved thread(s); approve with {"force":true} to override`,
+                },
+                unresolved,
+            }, 409);
+        }
+        const artifact = composeArtifact(store.readRevision(session.id, state.revision), {
+            revision: state.revision,
+            entries: readTranscript(store.transcriptPath(session.id)),
+        });
+        const relPath = pickArtifactRelPath(session.repo, session.title, localDate());
+        // Artifact on disk first, then the status flip (the registry is the commit
+        // point — same ordering argument as createSession), then the wake-up. The
+        // artifact + `path` are identical on both branches: the agent commits the
+        // plan the same way; `implement` only tells it whether to keep building.
+        writeFileAtomic(join(session.repo, relPath), artifact);
+        const updated = store.updateSession(session.id, {
+            status: implement ? "implementing" : "approved",
+        });
+        const payload = implement
+            ? { event: "approved", session: session.id, path: relPath, implement: true }
+            : { event: "approved", session: session.id, path: relPath };
+        queue.enqueue(payload, store.bumpCounter(session.id, "eventSeq"));
+        publishSession(updated); // after the enqueue, so the summary carries the fresh pending count
+        return c.json({
+            ok: true,
+            session: session.id,
+            revision: state.revision,
+            path: relPath,
+            unresolved,
+            implement,
+        });
+    });
+    // Approve & Implement's outcome report (DESIGN.md §6, §12): once the agent has
+    // built the approved plan it reports here. `failed:true` flips the session
+    // `implement_failed`, otherwise `implemented` (both terminal). A `pr` URL is
+    // persisted on the registry session so the home card can surface the link.
+    // The session must currently be `implementing` — that check runs FIRST, so a
+    // double-report (the second sees a terminal state) and a stray call on a
+    // never-implementing session both get a clear E_NOT_IMPLEMENTING instead of
+    // the generic terminal wall.
+    app.post("/api/sessions/:id/implement-done", async (c) => {
+        const session = sessionFor(c);
+        if (!session)
+            return notFound(c, `unknown session: ${c.req.param("id")}`);
+        const body = (await readJsonBody(c)) ?? {};
+        bumpContact(session.id);
+        if (store.getSession(session.id)?.status !== "implementing") {
+            return c.json({
+                error: {
+                    code: "E_NOT_IMPLEMENTING",
+                    message: `session ${session.id} is not implementing`,
+                },
+            }, 409);
+        }
+        const { pr, failed } = body;
+        if (pr !== undefined && (typeof pr !== "string" || pr.trim() === "")) {
+            return badRequest(c, "pr must be a non-empty string");
+        }
+        if (failed !== undefined && typeof failed !== "boolean") {
+            return badRequest(c, "failed must be a boolean");
+        }
+        const status = failed === true ? "implement_failed" : "implemented";
+        const updated = store.updateSession(session.id, {
+            status,
+            ...(typeof pr === "string" ? { prUrl: pr } : {}),
+        });
+        publishSession(updated); // the chip flips + the PR link appears live
+        return c.json({ ok: true, session: updated, status, prUrl: updated.prUrl });
+    });
+    app.get("/api/sessions/:id/revisions/:n", (c) => {
+        const session = sessionFor(c);
+        if (!session)
+            return notFound(c, `unknown session: ${c.req.param("id")}`);
+        const n = Number(c.req.param("n"));
+        if (!Number.isInteger(n) || n < 1) {
+            return badRequest(c, "revision must be a positive integer");
+        }
+        if (n > store.readState(session.id).revision) {
+            return notFound(c, `session ${session.id} has no revision ${n}`);
+        }
+        // Default is the raw markdown (byte-identical read-back; the CLI/curl
+        // path). The web UI asks for JSON to get the lint warnings the revision
+        // was accepted with alongside it (DESIGN.md §6).
+        if (c.req.header("accept")?.toLowerCase().includes("application/json")) {
+            const payload = {
+                session: session.id,
+                revision: n,
+                markdown: store.readRevision(session.id, n),
+                warnings: store.readRevisionWarnings(session.id, n),
+                changelog: store.readRevisionChangelog(session.id, n),
+            };
+            return c.json(payload);
+        }
+        return c.text(store.readRevision(session.id, n), 200, {
+            "content-type": "text/markdown; charset=utf-8",
+        });
+    });
+    // The SPA (GET /, GET /s/:id, /assets/*) and its SSE feeds (GET /api/stream,
+    // GET /api/sessions/:id/stream) — see ui.ts.
+    registerUiRoutes(app, {
+        notifier,
+        listSummaries: () => store.listSessions().map(summarize),
+        getSummary: (id) => {
+            const session = store.getSession(id);
+            return session ? summarize(session) : undefined;
+        },
+        getThreads: (id) => readThreads(store.threadsPath(id)),
+        getTranscript: (id) => readTranscript(store.transcriptPath(id)),
+        getActivity: (id) => readActivity(store.activityPath(id)),
+        uiDir: options.uiDir,
+        heartbeatMs: options.sseHeartbeatMs,
+    });
+    return app;
+}
+//# sourceMappingURL=app.js.map