otacon 0.1.0 → 0.1.2

package/dist/daemon/app.js

@@ -11,13 +11,13 @@
 // 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 { CONFIG_SCHEMA, loadConfig, readScopeValues, validateScopeInput, } from "../shared/config.js";
+import { 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 { composeArtifact, localDate, pickArtifactRelPath } from "./approve.js";
+import { composeArtifact, localDate, pickHomePath, pickProjectRelPath } from "./approve.js";
 import { createDesktopNotifier } from "./desktop-notify.js";
 import { diffPlans } from "./diff.js";
 import { lint } from "./linter/index.js";
@@ -25,7 +25,7 @@ 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 { answerQuestion, appendThreads, applyRevisionToThreads, commentThreadStates, openCommentThreads, 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. */
@@ -41,6 +41,21 @@ const timeoutEvent = (c) => c.json({ event: "timeout" });
 // `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);
+// `implementing` is non-terminal so it slips past sessionOver, but a build is
+// under way: submit would clobber the approved plan, and a re-approve would
+// re-write the artifact. Both verbs refuse with this shared 409.
+const alreadyImplementing = (c, id) => c.json({ error: { code: "E_ALREADY_IMPLEMENTING", message: `session ${id} is already implementing` } }, 409);
+// `finalizing` is non-terminal (the agent's fold-in submit must still mutate),
+// but it is a locked window: only that solo fold-in pass may touch the session.
+// A reviewer comment here would clobber the status back to `revising` while
+// `pendingApproval` stayed armed (a later clean submit would then silently
+// finalize) and hand the agent an un-swept thread that wedges L5. Refuse it.
+const alreadyFinalizing = (c, id) => c.json({
+    error: {
+        code: "E_ALREADY_FINALIZING",
+        message: `session ${id} is finalizing; the agent is folding in comments`,
+    },
+}, 409);
 async function readJsonBody(c) {
     try {
         const parsed = await c.req.json();
@@ -236,6 +251,52 @@ export function createApp(options) {
         }
         return c.json(event.payload);
     }
+    /**
+     * Finalize an approval (DESIGN.md §6 step 6/7, §12). 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).
+     * 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.
+     * 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
+     * every path. Returns the event's `path` and absolute `home`.
+     */
+    const finalizeApproval = (session, opts) => {
+        const artifact = composeArtifact(opts.markdown, {
+            revision: opts.revision,
+            entries: readTranscript(store.transcriptPath(session.id)),
+            reviewNotes: opts.reviewNotes,
+        });
+        const date = localDate();
+        const home = pickHomePath(session.id, session.title, date);
+        writeFileAtomic(home, artifact);
+        // Save writes a project copy and reports it; Implement builds from home, so
+        // nothing is written into the project and `path` is the home copy.
+        let path = home;
+        if (!opts.implement) {
+            const plansDir = loadConfig(session.repo).plans.dir;
+            const relPath = pickProjectRelPath(session.repo, plansDir, session.title, date);
+            writeFileAtomic(join(session.repo, relPath), artifact);
+            path = relPath;
+        }
+        const updated = store.updateSession(session.id, {
+            status: opts.implement ? "implementing" : "approved",
+        });
+        // 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).
+        store.clearPendingApproval(session.id);
+        const payload = opts.implement
+            ? { event: "approved", session: session.id, path, home, implement: true }
+            : { event: "approved", session: session.id, path, home };
+        queueFor(session.id).enqueue(payload, store.bumpCounter(session.id, "eventSeq"));
+        publishSession(updated); // after the enqueue, so the summary carries the fresh pending count
+        return { path, home };
+    };
     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
@@ -252,6 +313,58 @@ 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
+    // 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/
+    // non-absolute `repo` omits them (matching the isAbsolute guard POST applies
+    // to the write). `project` is the team-shared <repo>/.otacon/config.json;
+    // `project.local` is the personal <repo>/.otacon/config.local.json override.
+    app.get("/api/config", (c) => {
+        const repo = c.req.query("repo");
+        const scopes = {
+            user: { path: globalConfigPath(), values: readScopeValues(globalConfigPath()) },
+        };
+        if (repo !== undefined && repo !== "" && isAbsolute(repo)) {
+            const projectPath = repoConfigPath(repo);
+            const localPath = repoLocalConfigPath(repo);
+            scopes.project = { path: projectPath, values: readScopeValues(projectPath), repo };
+            scopes["project.local"] = { path: localPath, values: readScopeValues(localPath), repo };
+        }
+        return c.json({ schema: CONFIG_SCHEMA, scopes });
+    });
+    // POST replaces one scope file with the sanitized sparse values
+    // (DECISIONS.md "Config POST replaces"). A field the UI cleared is absent
+    // from `values` and so is dropped from the file — it reverts to inherited.
+    // `scope` must be "user", "project", or "project.local"; both project scopes
+    // require a `repo` (400 otherwise). Validation failures return 422 with
+    // per-field errors and write nothing. The same-origin guard above (covering
+    // every non-GET /api/*) protects this mutating call.
+    app.post("/api/config", async (c) => {
+        const body = (await readJsonBody(c)) ?? {};
+        const { scope, repo } = body;
+        if (scope !== "user" && scope !== "project" && scope !== "project.local") {
+            return badRequest(c, 'scope must be "user", "project", or "project.local"');
+        }
+        let path;
+        if (scope === "user") {
+            path = globalConfigPath();
+        }
+        else {
+            if (typeof repo !== "string" || !isAbsolute(repo)) {
+                return badRequest(c, "project scope requires an absolute repo path");
+            }
+            path = scope === "project" ? repoConfigPath(repo) : repoLocalConfigPath(repo);
+        }
+        const result = validateScopeInput(body.values);
+        if (result.errors.length > 0) {
+            return c.json({ fieldErrors: result.errors }, 422);
+        }
+        // Replace, don't merge: writeFileAtomic mkdir -p's the parent, so the
+        // already-present .otacon/ (or a missing ~/.otacon/) is handled either way.
+        writeFileAtomic(path, JSON.stringify(result.values, null, 2));
+        return c.json({ values: result.values });
+    });
     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
@@ -291,11 +404,12 @@ 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 it
-    // has committed value (DESIGN.md §6, §12). **Terminal** (approved, plus
+    // 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 committed under docs/plans/, so the working dir is *archived* to
-    // .otacon/archive/ (recoverable) — `otacon clean` and the UI's delete of an
+    // 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
@@ -408,6 +522,16 @@ export function createApp(options) {
         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
+        // 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
+        // submit racing it is refused here (an `approved` finalize is caught by
+        // sessionEnded above instead).
+        if (store.getSession(session.id)?.status === "implementing") {
+            return alreadyImplementing(c, session.id);
+        }
         bumpContact(session.id);
         let resolutions = {};
         if (c.req.header("content-type")?.includes("json")) {
@@ -461,15 +585,60 @@ export function createApp(options) {
             replies,
             revision,
         });
+        // The accepted revision and its settled threads go out the same way on both
+        // the fold-in and the ordinary path — but at different points relative to the
+        // status flip (finalizeApproval vs publishSession), so each branch fires this.
+        const publishRevision = () => {
+            notifier.publish({
+                type: "revision",
+                session: session.id,
+                data: { session: session.id, revision, changelog },
+            });
+            for (const thread of changedThreads)
+                publishThread(session.id, thread);
+        };
+        // Deferred approval (comment & approve, DESIGN.md §6, §12): 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
+        // returning to in_review. The swept threads (re-read post-resolution) become
+        // the committed `## Review notes`, so the unreviewed fold-in stays auditable.
+        const pending = state.pendingApproval;
+        if (pending) {
+            const swept = new Set(pending.threads);
+            const reviewNotes = readThreads(store.threadsPath(session.id))
+                .filter((t) => t.kind === "comment" && swept.has(t.id))
+                .map((t) => ({
+                thread: t.id,
+                section: t.anchor?.section ?? null,
+                body: t.body,
+                resolution: t.resolution?.body ?? "",
+            }));
+            const { path, home } = finalizeApproval(session, {
+                revision,
+                markdown: content,
+                implement: pending.implement,
+                reviewNotes,
+            });
+            // The fold-in produced a real revision and resolved threads; publish them
+            // so the rail/diff stay honest (the implement variant keeps the screen
+            // live, a plain finalize flips it to the approved notice).
+            publishRevision();
+            return c.json({
+                ok: true,
+                session: session.id,
+                revision,
+                status: pending.implement ? "implementing" : "approved",
+                path,
+                home,
+                finalized: true,
+                warnings: result.warnings,
+                resolved: Object.keys(replies),
+            });
+        }
         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);
+        publishRevision();
         // The ball is back in the user's court: a fresh revision awaits review.
         maybeNotify(session, { kind: "revision", revision });
         return c.json({
@@ -562,6 +731,12 @@ export function createApp(options) {
         const body = (await readJsonBody(c)) ?? {};
         if (sessionEnded(session.id))
             return sessionOver(c, session.id);
+        // A `finalizing` session is locked to the agent's solo fold-in pass — a new
+        // comment here would clobber it back to `revising` with `pendingApproval`
+        // still armed and hand the agent an un-swept thread that wedges L5 (D7).
+        if (store.getSession(session.id)?.status === "finalizing") {
+            return alreadyFinalizing(c, session.id);
+        }
         bumpContact(session.id);
         const rawItems = body.items;
         if (!Array.isArray(rawItems) || rawItems.length === 0) {
@@ -908,15 +1083,26 @@ export function createApp(options) {
         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}.
+    // Approve ends the planning session (DESIGN.md §6 step 6/7, §12). 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
+    // writes a project copy under the repo's `plans.dir` and sets the event `path`
+    // there; the session flips to `approved` (terminal) and the agent reports where
+    // the plan landed before it stops.
+    // **Implement** ({implement:true}) writes the home copy only, sets `path`=home,
+    // flips to the non-terminal `implementing`, and the agent builds from the home
+    // copy. The event always carries `home` (the absolute canonical path).
+    //
+    // Unresolved threads refuse 409 carrying the count; the UI's warn stage then
+    // offers two ways past it: **{force:true}** finalizes now and drops the open
+    // threads (today's behavior), or **comment & approve** — {sendOpenComments:true}
+    // — defers the finalize, flipping to the non-terminal `finalizing` and handing
+    // the agent every open comment thread (a `final:true` comments batch) for one
+    // solo fold-in pass; its next clean submit finalizes (carrying the implement
+    // choice). Mid-finalize, a fresh {sendOpenComments} is refused E_ALREADY_FINALIZING,
+    // but {force:true} stays open as the manual escape (force-drop the current
+    // revision).
     app.post("/api/sessions/:id/approve", async (c) => {
         const session = sessionFor(c);
         if (!session)
@@ -928,17 +1114,13 @@ export function createApp(options) {
         // and refuses instead of writing a second (-2 suffixed) artifact.
         if (sessionEnded(session.id))
             return sessionOver(c, session.id);
+        const currentStatus = store.getSession(session.id)?.status;
         // `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 (currentStatus === "implementing") {
+            return alreadyImplementing(c, session.id);
         }
         if (body.force !== undefined && typeof body.force !== "boolean") {
             return badRequest(c, "force must be a boolean");
@@ -946,7 +1128,21 @@ export function createApp(options) {
         if (body.implement !== undefined && typeof body.implement !== "boolean") {
             return badRequest(c, "implement must be a boolean");
         }
-        const implement = body.implement === true;
+        if (body.sendOpenComments !== undefined && typeof body.sendOpenComments !== "boolean") {
+            return badRequest(c, "sendOpenComments must be a boolean");
+        }
+        const force = body.force === true;
+        const sendOpenComments = body.sendOpenComments === true;
+        // A second send-to-agent while the fold-in is in flight is refused; "Commit
+        // anyway" (force) stays open as the manual escape from a hung finalize (D7).
+        if (currentStatus === "finalizing" && !force) {
+            return c.json({
+                error: {
+                    code: "E_ALREADY_FINALIZING",
+                    message: `session ${session.id} is already finalizing; approve with {"force":true} to commit anyway`,
+                },
+            }, 409);
+        }
         const state = store.readState(session.id);
         if (state.revision === 0) {
             return c.json({
@@ -956,42 +1152,73 @@ export function createApp(options) {
                 },
             }, 409);
         }
+        // A force escape mid-finalize honors the variant the user originally chose
+        // (carried on pendingApproval); a fresh approve reads the body's flag.
+        const implement = currentStatus === "finalizing"
+            ? (state.pendingApproval?.implement ?? false)
+            : 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. 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) {
+        // answer — the same open items the rail shows.
+        const unresolved = threads.filter((t) => t.kind === "comment" ? t.resolution === undefined : t.answer === undefined).length;
+        // 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
+        // falls through to the escape below).
+        if (sendOpenComments && currentStatus !== "finalizing" && openComments.length > 0) {
+            const counters = store.bumpCounters(session.id, { batch: 1, eventSeq: 1 });
+            const batch = `b${counters.batch}`;
+            const items = openComments.map((t) => ({
+                thread: t.id,
+                anchor: t.anchor,
+                body: t.body,
+            }));
+            store.setPendingApproval(session.id, { implement, threads: items.map((i) => i.thread) });
+            const updated = store.updateSession(session.id, { status: "finalizing" });
+            const payload = {
+                event: "comments",
+                session: session.id,
+                batch,
+                items,
+                final: true,
+            };
+            queue.enqueue(payload, counters.eventSeq);
+            publishSession(updated); // after the enqueue, so the summary carries the fresh pending count
+            return c.json({
+                ok: true,
+                session: session.id,
+                finalizing: true,
+                sent: items.map((i) => i.thread),
+                implement,
+            });
+        }
+        // The 409 carries both counts: `unresolved` (the warning's total) and
+        // `openComments` (whether comment & approve has anything to fold in, so the
+        // UI can offer "Send to agent" only when it would do something).
+        if (unresolved > 0 && !force) {
             return c.json({
                 error: {
                     code: "E_UNRESOLVED_THREADS",
-                    message: `session has ${unresolved} unresolved thread(s); approve with {"force":true} to override`,
+                    message: `session has ${unresolved} unresolved thread(s); approve with {"force":true} to override, or {"sendOpenComments":true} to fold open comments in`,
                 },
                 unresolved,
+                openComments: openComments.length,
             }, 409);
         }
-        const artifact = composeArtifact(store.readRevision(session.id, state.revision), {
+        // Finalize now (plain/force approve, or the force escape mid-finalize): no
+        // review notes — a force drop leaves the open threads unaddressed.
+        const { path, home } = finalizeApproval(session, {
             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",
+            markdown: store.readRevision(session.id, state.revision),
+            implement,
         });
-        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,
+            path,
+            home,
             unresolved,
             implement,
         });