otacon 0.1.3 → 0.1.4

package/dist/daemon/app.js

@@ -1,4 +1,4 @@
-// otacond's HTTP surface (DESIGN.md §6 "HTTP API sketch"), as a Hono app
+// otacond's HTTP surface (review loop and daemon API), 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"):
@@ -12,28 +12,34 @@
 import { Hono } from "hono";
 import { isAbsolute, join } from "node:path";
 import { CONFIG_SCHEMA, loadConfig, readScopeValues, validateScopeInput, } from "../shared/config.js";
-import { globalConfigPath, otaconPort, repoConfigPath, repoLocalConfigPath, } from "../shared/paths.js";
+import { expandTilde, globalConfigPath, otaconPort, repoConfigPath, repoLocalConfigPath, } 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 { normalize } from "./capture/normalize.js";
+import { appendStreamEvents, readStream, StreamSeq } from "./capture/stream-store.js";
+import { Tailer } from "./capture/tailer.js";
 import { composeArtifact, localDate, pickHomePath, pickProjectRelPath } from "./approve.js";
 import { createDesktopNotifier } from "./desktop-notify.js";
+import { validateDiagrams } from "./diagrams.js";
 import { diffPlans } from "./diff.js";
 import { lint } from "./linter/index.js";
+import { slugify } from "./linter/parse.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, openCommentThreads, readThreads, } from "./threads.js";
+import { answerQuestion, appendThreads, applyRevisionToThreads, commentThreadStates, openCommentThreads, readThreads, resolveThread, } from "./threads.js";
 import { answerEntry, appendEntries, appendEntry, readTranscript } from "./transcript.js";
 import { registerUiRoutes } from "./ui.js";
+import { Viewers } from "./viewers.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):
+// A session in a terminal state is over according to the 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
@@ -86,7 +92,7 @@ function parseAnchor(raw) {
     return anchor;
 }
 /**
- * Validate the submit body's `resolutions` (DESIGN.md §6): an object with
+ * Validate the submit body's `resolutions` (review loop and daemon API): 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.
@@ -161,7 +167,7 @@ export function createApp(options) {
         const status = store.getSession(id)?.status;
         return status !== undefined && TERMINAL_STATUSES.includes(status);
     };
-    // Agent presence (DESIGN.md §6): ephemeral, in-memory liveness only — the
+    // Agent presence (review loop and daemon API): 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
@@ -190,25 +196,98 @@ export function createApp(options) {
     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
+    const publishStream = (id, events) => notifier.publish({ type: "stream", session: id, data: { session: id, events } });
+    // Monotonic per-session seq source for the live-activity stream (the
+    // automatic, cross-agent activity stream): one StreamSeq per session id,
+    // seeded lazily from stream.jsonl's max seq so a daemon restart never re-mints
+    // a live seq, then incremented in memory. The daemon owns the single writer.
+    const streamSeqs = new Map();
+    const nextStreamSeq = (id) => {
+        let seq = streamSeqs.get(id);
+        if (seq === undefined) {
+            seq = new StreamSeq();
+            streamSeqs.set(id, seq);
+        }
+        return seq.next(store.streamPath(id));
+    };
+    // How many newest stream events the per-session SSE snapshot serves: the
+    // session's configured cap (so a repo override applies). The store already
+    // bounds the file at the cap on append, so this is belt-and-suspenders — but
+    // it keeps the snapshot honest if the cap was lowered since the last trim.
+    const loadStreamCap = (id) => {
+        const repo = store.getSession(id)?.repo;
+        return (repo ? loadConfig(repo) : loadConfig()).stream.cap;
+    };
+    // Per-session transcript tailers (the automatic, cross-agent activity stream):
+    // while a session is active, its tailer watches the coding agent's own
+    // transcript and feeds new tool/text/thinking activity through the SAME Phase
+    // 1 pipeline the progress route uses — `nextStreamSeq` for the seq,
+    // `appendStreamEvents` (capped), and `publishStream` for the SSE frame — so a
+    // captured event and a manual `otacon progress` highlight are indistinguishable
+    // downstream. A repo whose agent has no adapter attaches no tailer and runs on
+    // the progress floor (the registry returns null). Tailers are injectable via
+    // options.makeTailer so a test can drive `tick()` without a real fs poll.
+    const tailers = new Map();
+    const makeTailer = options.makeTailer ?? ((deps) => new Tailer(deps));
+    const startTailer = (session) => {
+        if (tailers.has(session.id))
+            return; // idempotent — already watching
+        if (TERMINAL_STATUSES.includes(session.status))
+            return; // over: nothing to tail
+        const tailer = makeTailer({
+            repoRoot: session.repo,
+            nextSeq: () => nextStreamSeq(session.id),
+            append: (events) => appendStreamEvents(store.streamPath(session.id), events, loadStreamCap(session.id)),
+            publish: (events) => publishStream(session.id, events),
+            config: () => loadConfig(session.repo).stream,
+        });
+        tailers.set(session.id, tailer);
+        tailer.start();
+    };
+    const stopTailer = (id) => {
+        const tailer = tailers.get(id);
+        if (tailer === undefined)
+            return;
+        tailer.stop();
+        tailers.delete(id);
+    };
+    // Re-attach tailers to sessions that were already active when the daemon
+    // started (a restart mid-build): the registry survives the restart, so the
+    // live transcript is still being written. New sessions wire their tailer at
+    // creation; terminal ones are skipped by startTailer's guard.
+    for (const session of store.listSessions())
+        startTailer(session);
+    // Desktop attention banners (review loop and daemon API). 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();
+    // Live browser tabs watching this daemon (any session or the index), tracked
+    // by an explicit SPA heartbeat with a TTL so `otacon open` can skip launching a
+    // duplicate tab (DECISIONS.md "reuse an existing open tab"). A heartbeat rather
+    // than an SSE-connection count because the dogfood daemon runs under Bun, whose
+    // node:http does not detect a client disconnect, so a connection count leaks;
+    // the TTL self-heals a closed/crashed tab under both Node and Bun. Ephemeral,
+    // in-memory: a restart starts at 0, and live tabs re-beat on their next ping.
+    const viewers = options.viewers ?? new Viewers();
     /**
      * 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).
+     * — it is swallowed to stderr (this is a local OS call, so the zero model-network-call
+     * invariant is untouched).
      */
     const maybeNotify = (session, moment) => {
         try {
-            if (!loadConfig(session.repo).notifications.desktop)
+            if (!loadConfig(session.repo).notifications.desktop) {
+                process.stderr.write(`otacond: notify skip session=${session.id} reason=config-disabled\n`);
                 return;
-            if (presence.isWatched(session.id))
+            }
+            if (presence.isWatched(session.id)) {
+                process.stderr.write(`otacond: notify skip session=${session.id} reason=watched\n`);
                 return;
+            }
             const message = moment.kind === "revision"
                 ? `Revision r${moment.revision} ready for review`
                 : moment.kind === "questions"
@@ -216,6 +295,7 @@ export function createApp(options) {
                     : moment.text.length > 80
                         ? `${moment.text.slice(0, 79)}…`
                         : moment.text;
+            process.stderr.write(`otacond: notify dispatch session=${session.id} kind=${moment.kind} title=${JSON.stringify(session.title)} message=${JSON.stringify(message)}\n`);
             notify({
                 title: session.title,
                 message,
@@ -252,14 +332,16 @@ export function createApp(options) {
         return c.json(event.payload);
     }
     /**
-     * Finalize an approval (DESIGN.md §6 step 6/7, §12). Writes the composed
+     * Finalize an approval. Writes the composed
      * artifact (with the comment-&-approve `## Review notes` when `reviewNotes` are
      * present). It ALWAYS writes the canonical home copy
-     * (`~/.otacon/sessions/<id>/`, the permanent archive).
+     * (`~/.otacon/sessions/<id>/`, the session's home dir: removed when the
+     * session is deleted, so not a durable archive).
      * On **Save** (implement=false) it ALSO writes a project copy under the repo's
-     * configured `plans.dir`, and the event `path` points there. On **Implement**
-     * (implement=true) it writes home only, and `path` equals `home`. The home
-     * write is the crash-safe finalize point — file(s) before the status flip.
+     * configured `plans.dir` (the durable copy), and the event `path` points
+     * there. On **Implement** (implement=true) it writes home only, and `path`
+     * equals `home` (the durable copy then rides in the PR). The home write is the
+     * crash-safe finalize point: file(s) before the status flip.
      * Then flip the session to `approved` or `implementing`, disarm any deferred
      * approval, and queue the `approved` wake-up. Shared by plain/force approve and
      * the deferred fold-in submit so the artifact and event shapes are identical on
@@ -283,9 +365,27 @@ export function createApp(options) {
             writeFileAtomic(join(session.repo, relPath), artifact);
             path = relPath;
         }
+        // On Implement, record the build's worktree + branch in the same write that
+        // flips to `implementing` (one registry write). Deterministic from the
+        // title slug + the configured worktree.dir, so a later `/otacon` run from
+        // inside that worktree can match it back to this session and reopen it.
+        let implPatch = {};
+        if (opts.implement) {
+            const slug = slugify(session.title) || "plan";
+            const wtDir = expandTilde(loadConfig(session.repo).worktree.dir);
+            const worktree = join(wtDir, slug);
+            const branch = `otacon/impl-${slug}`;
+            implPatch = { impl: { worktree, branch } };
+        }
         const updated = store.updateSession(session.id, {
             status: opts.implement ? "implementing" : "approved",
+            ...implPatch,
         });
+        // Save (approved) is terminal — the agent stops, so tear the tailer down.
+        // Implement keeps the session live (`implementing`), so the tailer keeps
+        // streaming the build's activity until implement-done flips it terminal.
+        if (!opts.implement)
+            stopTailer(session.id);
         // Disarm after the flip: a crash between them leaves a stale flag on an
         // already-terminal/building session (harmless — no further submit finalizes),
         // never a finalizing session that lost its flag (which would re-open review).
@@ -312,8 +412,8 @@ export function createApp(options) {
     });
     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 }));
-    // The Settings UI's config surface (DESIGN.md §6). GET returns the full
+    app.get("/api/health", (c) => c.json({ app: "otacond", version: VERSION, pid: process.pid, viewers: viewers.count() }));
+    // The Settings UI's config surface (review loop and daemon API). GET returns the full
     // schema plus each scope's current sparse, coerced values. The `user` scope
     // (~/.otacon/config.json) is always present; the project scopes only when an
     // absolute `repo` is named — User config needs no repo, so an absent/empty/
@@ -395,6 +495,10 @@ export function createApp(options) {
             return badRequest(c, "quick must be a boolean");
         }
         const session = store.createSession({ title, repo, branch, quick });
+        // Attach the transcript tailer now: the agent is already working in `repo`,
+        // so its live transcript may already exist (and if not, the tailer re-locates
+        // until it appears). A repo whose agent has no adapter attaches nothing.
+        startTailer(session);
         publishSession(session);
         return c.json(session, 201);
     });
@@ -404,51 +508,46 @@ export function createApp(options) {
             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 its
-    // plan is already preserved (DESIGN.md §6, §12). **Terminal** (approved, plus
-    // implemented/implement_failed once a build finishes): its plan + transcript
-    // are in the home archive (~/.otacon/sessions/<id>/, never touched here), 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).
+    // DELETE permanently removes a session: it deregisters from the registry and
+    // `rmSync`s its home dir `~/.otacon/sessions/<id>/` outright, for ALL statuses
+    // (UI delete and `otacon clean` both drive this route). No archive: nothing
+    // is recoverable from otacon itself; the durable copies are the Save copy
+    // under the project's `plans.dir` and (for Implement plans) the PR. The only
+    // status branch left is waking a parked agent: a live (non-terminal) session
+    // may have an agent parked on `wait`, so it is woken with a terminal `deleted`
+    // event before deregistering, so its loop stops cleanly. Both branches publish
+    // the same terminal `removed` frame.
     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;
+        stopTailer(session.id); // the session is going away — stop watching its transcript
         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.
+            // fact still registered. Close the evicted instance before the removal so
+            // a late in-flight ack cannot recreate ~/.otacon/sessions/<id>/.
             store.deleteSession(session.id);
             queue.close();
             queues.delete(session.id);
-            archivedTo = store.archiveSessionDir(session.repo, session.id);
+            store.removeSessionDir(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).
+            // first, so the removal below can't be recreated by a late ack. Then
+            // deregister and permanently drop the home dir.
             queue.closeWith({ event: "deleted", session: session.id });
             queues.delete(session.id);
             store.deleteSession(session.id);
-            store.removeSessionDir(session.repo, session.id);
+            store.removeSessionDir(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 });
+        return c.json({ ok: true, session: session.id, repo: session.repo, pendingEvents });
     });
     app.get("/api/sessions/:id/events", (c) => {
         const session = sessionFor(c);
@@ -505,7 +604,7 @@ export function createApp(options) {
             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).
+                // UI within one park slice (review loop and daemon API).
                 publishSession(session);
                 timer = setTimeout(() => settle(timeoutEvent(c)), waitSeconds * 1000);
                 signal.addEventListener("abort", onAbort);
@@ -517,13 +616,13 @@ export function createApp(options) {
         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
+        // CLI sends resolutions.json's content along (review loop and daemon API). 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);
         // A submit cannot land mid-build. `implementing` is non-terminal (it re-opens
-        // progress/ask/wait/answer, DESIGN.md §6) so it slips past sessionEnded — but
+        // progress/ask/wait/answer, review loop and daemon API) so it slips past sessionEnded — but
         // submit is not in that verb set, and a revision here would clobber the
         // approved plan. This also serializes the double-finalize race: a comment-&-
         // approve fold-in that flips to `implementing` is the winner, and a second
@@ -572,14 +671,19 @@ export function createApp(options) {
                 changelog: resolutions.changelog,
             },
         });
-        if (!result.ok) {
-            return c.json({ ok: false, errors: result.errors, warnings: result.warnings }, 422);
+        // L8 diagram render gate runs alongside the structural linter so the agent
+        // gets diagram + structural failures in one pass (fewer round-trips). It
+        // fails open, so it only ever adds errors — never blocks on its own infra.
+        const diagramErrors = await validateDiagrams(content);
+        const errors = [...result.errors, ...diagramErrors];
+        if (errors.length > 0) {
+            return c.json({ ok: false, 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.
+        // (plan structure, lint, and anchoring, threaded review and revision). SSE upserts keep the rail live.
         const changedThreads = applyRevisionToThreads(store.threadsPath(session.id), {
             plan: content,
             replies,
@@ -597,7 +701,7 @@ export function createApp(options) {
             for (const thread of changedThreads)
                 publishThread(session.id, thread);
         };
-        // Deferred approval (comment & approve, DESIGN.md §6, §12): a send-to-agent
+        // Deferred approval (comment & approve): a send-to-agent
         // approve armed `pendingApproval` and parked the session in `finalizing`.
         // This clean submit is the agent's fold-in pass — L5 has just vouched that
         // every open comment carries a resolution — so finalize now instead of
@@ -612,7 +716,7 @@ export function createApp(options) {
                 thread: t.id,
                 section: t.anchor?.section ?? null,
                 body: t.body,
-                resolution: t.resolution?.body ?? "",
+                reply: t.reply?.body ?? "",
             }));
             const { path, home } = finalizeApproval(session, {
                 revision,
@@ -650,7 +754,7 @@ export function createApp(options) {
             resolved: Object.keys(replies),
         });
     });
-    // The user's side of re-review bookkeeping (DESIGN.md §9 layer 3): the UI's
+    // The user's side of re-review bookkeeping (threaded review and revision 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) => {
@@ -670,7 +774,56 @@ export function createApp(options) {
         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}
+    // Reopen a finished (terminal) session for another review round
+    // (resurrect-plan-amend): a `/otacon` run from inside the build worktree flips
+    // the session back to `revising` so the agent amends the approved plan in
+    // place instead of spawning a second worktree. The baseline is pinned at the
+    // approved revision (markReviewed → lastReviewedRevision = revision), so the
+    // next submit diffs against what was approved. `prUrl` and `impl` are kept
+    // intact: the amendment still belongs to the same build. A non-terminal
+    // session is refused E_NOT_REOPENABLE (there is nothing finished to reopen).
+    app.post("/api/sessions/:id/reopen", (c) => {
+        const session = sessionFor(c);
+        if (!session)
+            return notFound(c, `unknown session: ${c.req.param("id")}`);
+        // Agent-driven verb (a `/otacon` run): bump liveness like its siblings so the
+        // reopened session reads live, not offline-until-next-call.
+        bumpContact(session.id);
+        if (!TERMINAL_STATUSES.includes(session.status)) {
+            return c.json({
+                error: {
+                    code: "E_NOT_REOPENABLE",
+                    message: `session ${session.id} is ${session.status}, not reopenable (must be a finished session)`,
+                },
+            }, 409);
+        }
+        const state = store.readState(session.id);
+        const revision = state.revision;
+        if (revision === 0) {
+            // A terminal session always has an approved revision; guard anyway.
+            return c.json({
+                error: {
+                    code: "E_NOT_REOPENABLE",
+                    message: `session ${session.id} has no revisions to reopen`,
+                },
+            }, 409);
+        }
+        // Pin the diff baseline at the approved revision (monotonic), so the next
+        // submit shows just the amendment.
+        store.markReviewed(session.id, revision);
+        const updated = store.updateSession(session.id, { status: "revising" });
+        publishSession(updated); // the index + an open tab move it back to active
+        return c.json({
+            ok: true,
+            session: session.id,
+            status: "revising",
+            revision,
+            lastReviewedRevision: revision,
+            impl: updated.impl ?? null,
+            prUrl: updated.prUrl ?? null,
+        });
+    });
+    // The review screen reports its visibility here (review loop and daemon API): {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
@@ -690,7 +843,24 @@ export function createApp(options) {
             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).
+    // A browser tab reports its liveness here (open-tab reuse, DECISIONS.md "reuse
+    // an existing open tab"): one beat per tab on mount and a ~30s heartbeat, plus
+    // a `gone:true` beacon on tab close. Daemon-wide (NOT session-scoped): one tab,
+    // via the app-shell sidebar, reaches every session, so `otacon open` only needs
+    // to know whether ANY tab from this daemon is live. The 90s TTL self-expires a
+    // crashed/closed tab whose `gone` beacon never arrived.
+    app.post("/api/viewers/heartbeat", async (c) => {
+        const body = (await readJsonBody(c)) ?? {};
+        if (typeof body.clientId !== "string" || body.clientId.length === 0) {
+            return badRequest(c, "clientId must be a non-empty string");
+        }
+        if (body.gone)
+            viewers.drop(body.clientId);
+        else
+            viewers.beat(body.clientId);
+        return c.json({ ok: true });
+    });
+    // Structural diff between two stored revisions, defaulting to the last-reviewed baseline.
     // 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) => {
@@ -742,13 +912,49 @@ export function createApp(options) {
         if (!Array.isArray(rawItems) || rawItems.length === 0) {
             return badRequest(c, "items must be a non-empty array");
         }
+        // A batch may mix new comments and follow-ups: an item with `replyTo` (a
+        // comment thread id) continues that conversation INSTEAD of carrying its own
+        // anchor — it inherits the root's anchor and orphan state, and a client
+        // anchor on it is ignored; an item without `replyTo` parses its own anchor.
+        const existing = readThreads(store.threadsPath(session.id));
         const drafts = [];
         for (const raw of rawItems) {
-            const anchor = parseAnchor(raw?.anchor);
-            if (typeof raw?.body !== "string" || raw.body.trim() === "" || anchor === undefined) {
+            if (typeof raw?.body !== "string" || raw.body.trim() === "") {
                 return badRequest(c, "each item needs a non-empty body and a valid anchor (or null)");
             }
-            drafts.push({ anchor, body: raw.body });
+            const replyToRaw = raw.replyTo;
+            if (replyToRaw === undefined) {
+                const anchor = parseAnchor(raw.anchor);
+                if (anchor === undefined) {
+                    return badRequest(c, "each item needs a non-empty body and a valid anchor (or null)");
+                }
+                drafts.push({ anchor, body: raw.body });
+                continue;
+            }
+            if (typeof replyToRaw !== "string" || replyToRaw === "") {
+                return badRequest(c, "replyTo must name a comment thread id (t<n>)");
+            }
+            const parent = existing.find((t) => t.id === replyToRaw && t.kind === "comment");
+            if (!parent) {
+                return c.json({
+                    error: {
+                        code: "E_UNKNOWN_COMMENT",
+                        message: `session ${session.id} has no comment ${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 === "comment");
+            const source = root ?? parent;
+            drafts.push({
+                anchor: source.anchor,
+                ...(source.anchorState === "orphaned" ? { anchorState: "orphaned" } : {}),
+                replyTo: rootId,
+                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.
@@ -760,23 +966,27 @@ export function createApp(options) {
         const firstThread = counters.thread - drafts.length;
         const items = drafts.map((draft, i) => ({
             thread: `t${firstThread + i + 1}`,
-            ...draft,
+            anchor: draft.anchor,
+            body: draft.body,
+            ...(draft.replyTo !== undefined ? { replyTo: draft.replyTo } : {}),
         }));
         const batch = `b${counters.batch}`;
-        // Each item becomes a persistent thread (DESIGN.md §9) — the rail's
+        // Each item becomes a persistent thread (threaded review and revision) — 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,
+        const threads = drafts.map((draft, i) => ({
+            id: `t${firstThread + i + 1}`,
             kind: "comment",
             batch,
-            anchor: item.anchor,
-            body: item.body,
+            anchor: draft.anchor,
+            ...(draft.anchorState === "orphaned" ? { anchorState: "orphaned" } : {}),
+            body: draft.body,
             createdAt,
+            ...(draft.replyTo !== undefined ? { replyTo: draft.replyTo } : {}),
         }));
         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.
+        // (threaded review and revision 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.
@@ -800,7 +1010,7 @@ export function createApp(options) {
         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`
+        // A follow-up (threaded review and revision) 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;
@@ -850,7 +1060,7 @@ export function createApp(options) {
             ...(replyTo !== undefined ? { replyTo } : {}),
         };
         appendThreads(store.threadsPath(session.id), [thread]);
-        // Questions leave the plan — and the status — untouched (DESIGN.md §9).
+        // Questions leave the plan — and the status — untouched (threaded review and revision).
         const payload = {
             event: "question",
             session: session.id,
@@ -864,7 +1074,7 @@ export function createApp(options) {
         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 agent's side of a user question (`otacon answer`):
     // 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) => {
@@ -896,17 +1106,46 @@ export function createApp(options) {
             answeredAt: thread.answer.answeredAt,
         });
     });
+    // The reviewer's side of closing a thread (the Resolve verb): {resolved:true}
+    // stamps the close (carrying the session's current revision) on the conversation
+    // root, {resolved:false} reopens it. Resolve doubles as the comment-withdraw
+    // path — a resolved comment no longer owes a reply (L5 skips it) and no longer
+    // counts unresolved at approve. Refused on a terminal session (like the
+    // questions route); 404 on an unknown thread id.
+    app.post("/api/sessions/:id/threads/:tid/resolve", 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);
+        if (typeof body.resolved !== "boolean") {
+            return badRequest(c, "resolved must be a boolean");
+        }
+        const tid = c.req.param("tid") ?? "";
+        const thread = resolveThread(store.threadsPath(session.id), tid, body.resolved, store.readState(session.id).revision);
+        if (!thread) {
+            return c.json({
+                error: {
+                    code: "E_UNKNOWN_THREAD",
+                    message: `session ${session.id} has no thread ${tid}`,
+                },
+            }, 404);
+        }
+        publishThread(session.id, thread);
+        return c.json({ ok: true }, 202);
+    });
     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 agent's grill question (`otacon ask`): 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
+    // questions — independent siblings the agent posts in one call (interview questions); they
     // render as ordinary cards, each answered instantly.
     app.post("/api/sessions/:id/ask", async (c) => {
         const session = sessionFor(c);
@@ -939,7 +1178,7 @@ export function createApp(options) {
             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).
+            // A batch coalesces to one banner — N questions need answering (review loop and daemon API).
             maybeNotify(session, entries.length === 1
                 ? { kind: "question", text: specs[0].question }
                 : { kind: "questions", count: entries.length });
@@ -958,7 +1197,7 @@ export function createApp(options) {
         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
+    // The user's side of a grill question: 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);
@@ -987,12 +1226,12 @@ export function createApp(options) {
         // 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
+        // (native-AskUserQuestion "Other" parity, interview questions) — 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
+            // "Other" parity (interview questions): 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) {
@@ -1027,6 +1266,10 @@ export function createApp(options) {
             ...(customText ? { text: text } : {}),
             answeredAt: new Date().toISOString(),
         };
+        // Snapshot the pre-overwrite answer BEFORE answerEntry mutates the entry: a
+        // re-answer carries `revised` + `prior` so the agent reconciles supersession.
+        const prior = asked.answer;
+        const wasAnswered = prior !== undefined;
         // 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);
@@ -1037,6 +1280,16 @@ export function createApp(options) {
             ...(answer.choice !== undefined ? { choice: answer.choice } : {}),
             ...(answer.choices !== undefined ? { choices: answer.choices } : {}),
             ...(answer.text !== undefined ? { text: answer.text } : {}),
+            ...(wasAnswered
+                ? {
+                    revised: true,
+                    prior: {
+                        ...(prior.choice !== undefined ? { choice: prior.choice } : {}),
+                        ...(prior.choices !== undefined ? { choices: prior.choices } : {}),
+                        ...(prior.text !== undefined ? { text: prior.text } : {}),
+                    },
+                }
+                : {}),
         };
         queue.enqueue(payload, store.bumpCounter(session.id, "eventSeq"));
         publishQueue(session.id, queue.size);
@@ -1055,12 +1308,16 @@ export function createApp(options) {
             transcript: readTranscript(store.transcriptPath(session.id)),
         });
     });
-    // The agent's narration (otacon progress, DESIGN.md §6, §8): a non-blocking
+    // The agent's narration (`otacon progress`): 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.
+    // chip's latestActivity). The same note is ALSO normalized into a `highlight`
+    // StreamEvent and appended to the live-activity stream (the automatic,
+    // cross-agent activity stream) so a manual narration sits inline with the
+    // captured activity; a `stream` frame pushes it to the UI. 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)
@@ -1072,18 +1329,26 @@ export function createApp(options) {
         if (typeof raw !== "string" || raw.trim() === "") {
             return badRequest(c, "note must be a non-empty string");
         }
-        const { activity } = loadConfig(session.repo);
+        const { activity, stream } = loadConfig(session.repo);
         const trimmed = raw.trim();
+        const at = new Date().toISOString();
         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());
+        const note = appendActivity(store.activityPath(session.id), text, activity.cap, at);
+        // The same note flows into the new stream as a `highlight` event: the
+        // normalizer redacts + truncates the body (its own caps), the daemon stamps
+        // seq and `at`. The activity-feed text above keeps its own (shorter) cap —
+        // the index draft chip still reads `latestActivity`.
+        const event = normalize({ kind: "highlight", label: trimmed, detail: trimmed }, stream, nextStreamSeq(session.id), at);
+        appendStreamEvents(store.streamPath(session.id), [event], stream.cap);
         bumpContact(session.id);
         notifier.publish({ type: "activity", session: session.id, data: { session: session.id, note } });
+        publishStream(session.id, [event]);
         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/7, §12). Writes the
+    // Approve ends the planning session. Writes the
     // composed artifact (final revision, status: approved, grill transcript
     // appended). The canonical copy ALWAYS lands in the home store
     // (~/.otacon/sessions/<id>/). **Save** (plain Approve, implement=false) ALSO
@@ -1159,9 +1424,30 @@ export function createApp(options) {
             : body.implement === true;
         const threads = readThreads(store.threadsPath(session.id));
         const openComments = openCommentThreads(threads);
-        // Unresolved = comment threads with no resolution + user questions with no
-        // answer — the same open items the rail shows.
-        const unresolved = threads.filter((t) => t.kind === "comment" ? t.resolution === undefined : t.answer === undefined).length;
+        // Unresolved is counted **per conversation**, not per turn: a multi-turn
+        // comment or question conversation contributes at most 1. Both kinds carry
+        // `replyTo` (a follow-up keys on its root). A conversation is unresolved when
+        // its root is not reviewer-`resolved` AND it still owes attention — a
+        // **comment** conversation always owes it (you must Resolve it; a landed
+        // reply is a response, not a close), a **question** conversation owes it only
+        // while some turn is unanswered. So: a responded-but-unresolved comment
+        // conversation counts (once); a reviewer-resolved one does not; an unanswered
+        // ask counts; an unanswered-but-resolved ask does not.
+        const resolvedRoots = new Set(threads.filter((t) => t.resolved).map((t) => t.id));
+        const rootOf = (t) => t.replyTo ?? t.id;
+        const roots = new Set(threads.map(rootOf));
+        let unresolved = 0;
+        for (const root of roots) {
+            if (resolvedRoots.has(root))
+                continue;
+            const turns = threads.filter((t) => rootOf(t) === root);
+            const isComment = turns.some((t) => t.kind === "comment");
+            const owesAttention = isComment
+                ? true
+                : turns.some((t) => t.kind === "question" && t.answer === undefined);
+            if (owesAttention)
+                unresolved += 1;
+        }
         // Comment & approve: defer the finalize and hand the agent every open comment
         // thread for one solo fold-in pass — its next clean submit finalizes. Only
         // when there is something to fold in, and not already finalizing (a force then
@@ -1223,7 +1509,7 @@ export function createApp(options) {
             implement,
         });
     });
-    // Approve & Implement's outcome report (DESIGN.md §6, §12): once the agent has
+    // Approve & Implement's outcome report: 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.
@@ -1257,6 +1543,7 @@ export function createApp(options) {
             status,
             ...(typeof pr === "string" ? { prUrl: pr } : {}),
         });
+        stopTailer(session.id); // build is over (both outcomes terminal): stop tailing
         publishSession(updated); // the chip flips + the PR link appears live
         return c.json({ ok: true, session: updated, status, prUrl: updated.prUrl });
     });
@@ -1273,7 +1560,7 @@ export function createApp(options) {
         }
         // 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).
+        // was accepted with alongside it (review loop and daemon API).
         if (c.req.header("accept")?.toLowerCase().includes("application/json")) {
             const payload = {
                 session: session.id,
@@ -1300,6 +1587,7 @@ export function createApp(options) {
         getThreads: (id) => readThreads(store.threadsPath(id)),
         getTranscript: (id) => readTranscript(store.transcriptPath(id)),
         getActivity: (id) => readActivity(store.activityPath(id)),
+        getStream: (id) => readStream(store.streamPath(id), loadStreamCap(id)),
         uiDir: options.uiDir,
         heartbeatMs: options.sseHeartbeatMs,
     });