@mandipadk7/kavi 0.1.2 → 0.1.3

package/README.md

@@ -3,11 +3,12 @@
 Kavi is a local terminal control plane for managed Codex and Claude collaboration.
 
 Current capabilities:
-- `kavi init`: create repo-local `.kavi` config, prompt files, and ignore rules.
+- `kavi init`: create repo-local `.kavi` config, prompt files, ignore rules, and bootstrap git if the folder is not already a repository.
 - `kavi init --home`: also scaffold the user-local config file used for binary overrides.
+- `kavi init --no-commit`: skip the bootstrap commit and let `kavi open` or `kavi start` create the first base commit later.
 - `kavi doctor`: verify Node, Codex, Claude, git worktree support, and local readiness.
 - `kavi start`: start a managed session without attaching the TUI.
-- `kavi open`: create a managed session with separate Codex and Claude worktrees and open the full-screen operator console.
+- `kavi open`: create a managed session with separate Codex and Claude worktrees and open the full-screen operator console, even from an empty folder or a repo with no `HEAD` yet.
 - `kavi resume`: reopen the operator console for the current repo session.
 - `kavi status`: inspect session health and task counts from any terminal.
 - `kavi paths`: inspect resolved repo-local, user-local, worktree, and runtime paths.
@@ -16,6 +17,7 @@ Current capabilities:
 - `kavi task-output`: inspect the normalized envelope and raw output for a completed task.
 - `kavi decisions`: inspect the persisted routing, approval, task, and integration decisions.
 - `kavi claims`: inspect active or historical path claims.
+- `kavi reviews`: inspect persisted operator review threads and linked follow-up tasks.
 - `kavi approvals`: inspect the approval inbox.
 - `kavi approve` and `kavi deny`: resolve a pending approval request, optionally with `--remember`.
 - `kavi events`: inspect recent daemon and task events.
@@ -29,11 +31,13 @@ Runtime model:
 - User-local runtime overrides live in `~/.config/kavi/config.toml` and can point Kavi at custom `node`, `codex`, and `claude` binaries.
 - The operator surface talks to the daemon over a local control socket under the machine-local state root.
 - SQLite event mirroring is opt-in with `KAVI_ENABLE_SQLITE_HISTORY=1`; the default event log is JSONL under `.kavi/state/events.jsonl`.
-- The operator console exposes a task board, dual agent lanes, a live inspector pane, approval actions, inline task composition, and worktree diff review with file and hunk navigation.
+- The operator console exposes a task board, dual agent lanes, a live inspector pane, approval actions, inline task composition, worktree diff review with file and hunk navigation, and persisted operator review threads on files or hunks.
 
 Development:
 
 ```bash
+# works in an empty folder; Kavi will initialize git and create the
+# bootstrap commit it needs for managed worktrees
 node bin/kavi.js init --home
 node bin/kavi.js doctor --json
 node bin/kavi.js paths
@@ -44,17 +48,20 @@ node bin/kavi.js tasks
 node bin/kavi.js task-output latest
 node bin/kavi.js decisions
 node bin/kavi.js claims
+node bin/kavi.js reviews
 node bin/kavi.js approvals
 node bin/kavi.js open
 npm test
 ```
 
 Notes:
+- `kavi init` and `kavi open` now support the "empty folder to first managed session" path. If no git repo exists, Kavi initializes one; if git exists but no `HEAD` exists yet, Kavi creates the bootstrap commit it needs for worktrees.
 - Codex runs through `codex app-server` in managed mode, so Codex-side approvals now land in the same Kavi inbox as Claude hook approvals.
 - Claude still runs through the installed `claude` CLI with Kavi-managed hooks and approval decisions.
 - The dashboard and operator commands now use the daemon's local RPC socket instead of editing session files directly, and the TUI stays updated from pushed daemon snapshots rather than polling.
 - The socket is machine-local rather than repo-local to avoid Unix socket path-length issues in deep repos and temp directories.
-- The console is keyboard-driven: `1-7` switch views, `j/k` move selection, `[` and `]` cycle task detail sections, `,` and `.` cycle changed files, `{` and `}` cycle patch hunks, `y/n` resolve approvals, and `c` opens the inline task composer.
+- The console is keyboard-driven: `1-7` switch views, `j/k` move selection, `[` and `]` cycle task detail sections, `,` and `.` cycle changed files, `{` and `}` cycle patch hunks, `A/C/Q/M` add review notes, `o/O` cycle existing threads, `T` reply, `E` edit, `R` resolve or reopen, `F` queue a fix task, `H` queue a handoff task, `y/n` resolve approvals, and `c` opens the inline task composer.
+- Successful follow-up tasks now auto-resolve linked open review threads, landed follow-up work marks those resolved threads as landed, and replying to a resolved thread reopens it.
 
 Local install options:
 

package/dist/daemon.js

@@ -9,6 +9,7 @@ import { listApprovalRequests, resolveApprovalRequest } from "./approvals.js";
 import { addDecisionRecord, upsertPathClaim } from "./decision-ledger.js";
 import { getWorktreeDiffReview, listWorktreeChangedPaths } from "./git.js";
 import { nowIso } from "./paths.js";
+import { addReviewReply, addReviewNote, autoResolveReviewNotesForCompletedTask, linkReviewFollowUpTask, reviewNotesForTask, setReviewNoteStatus, updateReviewNote } from "./reviews.js";
 import { buildAdHocTask, buildKickoffTasks } from "./router.js";
 import { loadSessionRecord, readRecentEvents, recordEvent, saveSessionRecord } from "./session.js";
 import { loadTaskArtifact, saveTaskArtifact } from "./task-artifacts.js";
@@ -191,6 +192,41 @@ export class KaviDaemon {
                         ok: true
                     }
                 };
+            case "addReviewNote":
+                await this.addReviewNoteFromRpc(params);
+                return {
+                    result: {
+                        ok: true
+                    }
+                };
+            case "updateReviewNote":
+                await this.updateReviewNoteFromRpc(params);
+                return {
+                    result: {
+                        ok: true
+                    }
+                };
+            case "addReviewReply":
+                await this.addReviewReplyFromRpc(params);
+                return {
+                    result: {
+                        ok: true
+                    }
+                };
+            case "setReviewNoteStatus":
+                await this.setReviewNoteStatusFromRpc(params);
+                return {
+                    result: {
+                        ok: true
+                    }
+                };
+            case "enqueueReviewFollowUp":
+                await this.enqueueReviewFollowUpFromRpc(params);
+                return {
+                    result: {
+                        ok: true
+                    }
+                };
             default:
                 throw new Error(`Unknown RPC method: ${method}`);
         }
@@ -351,6 +387,264 @@ export class KaviDaemon {
         }
         return await getWorktreeDiffReview(agent, worktree.path, this.session.baseCommit, filePath);
     }
+    async addReviewNoteFromRpc(params) {
+        await this.runMutation(async ()=>{
+            const agent = params.agent === "claude" ? "claude" : "codex";
+            const filePath = typeof params.filePath === "string" ? params.filePath.trim() : "";
+            const disposition = params.disposition === "approve" || params.disposition === "concern" || params.disposition === "question" ? params.disposition : "note";
+            const body = typeof params.body === "string" ? params.body.trim() : "";
+            const taskId = typeof params.taskId === "string" ? params.taskId : null;
+            const hunkIndex = typeof params.hunkIndex === "number" ? params.hunkIndex : null;
+            const hunkHeader = typeof params.hunkHeader === "string" ? params.hunkHeader : null;
+            if (!filePath) {
+                throw new Error("addReviewNote requires a filePath.");
+            }
+            if (!body) {
+                throw new Error("addReviewNote requires a note body.");
+            }
+            const note = addReviewNote(this.session, {
+                agent,
+                taskId,
+                filePath,
+                hunkIndex,
+                hunkHeader,
+                disposition,
+                body
+            });
+            addDecisionRecord(this.session, {
+                kind: "review",
+                agent,
+                taskId,
+                summary: note.summary,
+                detail: note.body,
+                metadata: {
+                    filePath: note.filePath,
+                    hunkIndex: note.hunkIndex,
+                    hunkHeader: note.hunkHeader,
+                    disposition: note.disposition,
+                    reviewNoteId: note.id
+                }
+            });
+            await saveSessionRecord(this.paths, this.session);
+            if (taskId) {
+                await this.refreshTaskArtifactReviewNotes(taskId);
+            }
+            await recordEvent(this.paths, this.session.id, "review.note_added", {
+                reviewNoteId: note.id,
+                agent: note.agent,
+                taskId: note.taskId,
+                filePath: note.filePath,
+                hunkIndex: note.hunkIndex,
+                disposition: note.disposition
+            });
+            await this.publishSnapshot("review.note_added");
+        });
+    }
+    async updateReviewNoteFromRpc(params) {
+        await this.runMutation(async ()=>{
+            const noteId = typeof params.noteId === "string" ? params.noteId : "";
+            const body = typeof params.body === "string" ? params.body.trim() : "";
+            if (!noteId) {
+                throw new Error("updateReviewNote requires a noteId.");
+            }
+            if (!body) {
+                throw new Error("updateReviewNote requires a note body.");
+            }
+            const note = updateReviewNote(this.session, noteId, {
+                body
+            });
+            if (!note) {
+                throw new Error(`Review note ${noteId} was not found.`);
+            }
+            addDecisionRecord(this.session, {
+                kind: "review",
+                agent: note.agent,
+                taskId: note.taskId,
+                summary: `Edited review note ${note.id}`,
+                detail: note.body,
+                metadata: {
+                    reviewNoteId: note.id,
+                    filePath: note.filePath,
+                    hunkIndex: note.hunkIndex
+                }
+            });
+            await saveSessionRecord(this.paths, this.session);
+            if (note.taskId) {
+                await this.refreshTaskArtifactReviewNotes(note.taskId);
+            }
+            await recordEvent(this.paths, this.session.id, "review.note_updated", {
+                reviewNoteId: note.id,
+                taskId: note.taskId,
+                agent: note.agent,
+                filePath: note.filePath
+            });
+            await this.publishSnapshot("review.note_updated");
+        });
+    }
+    async addReviewReplyFromRpc(params) {
+        await this.runMutation(async ()=>{
+            const noteId = typeof params.noteId === "string" ? params.noteId : "";
+            const body = typeof params.body === "string" ? params.body.trim() : "";
+            if (!noteId) {
+                throw new Error("addReviewReply requires a noteId.");
+            }
+            if (!body) {
+                throw new Error("addReviewReply requires a reply body.");
+            }
+            const note = addReviewReply(this.session, noteId, body);
+            if (!note) {
+                throw new Error(`Review note ${noteId} was not found.`);
+            }
+            addDecisionRecord(this.session, {
+                kind: "review",
+                agent: note.agent,
+                taskId: note.taskId,
+                summary: `Replied to review note ${note.id}`,
+                detail: body,
+                metadata: {
+                    reviewNoteId: note.id,
+                    filePath: note.filePath,
+                    hunkIndex: note.hunkIndex,
+                    replyCount: note.comments.length
+                }
+            });
+            await saveSessionRecord(this.paths, this.session);
+            if (note.taskId) {
+                await this.refreshTaskArtifactReviewNotes(note.taskId);
+            }
+            await recordEvent(this.paths, this.session.id, "review.reply_added", {
+                reviewNoteId: note.id,
+                taskId: note.taskId,
+                agent: note.agent,
+                filePath: note.filePath,
+                replyCount: note.comments.length
+            });
+            await this.publishSnapshot("review.reply_added");
+        });
+    }
+    async setReviewNoteStatusFromRpc(params) {
+        await this.runMutation(async ()=>{
+            const noteId = typeof params.noteId === "string" ? params.noteId : "";
+            const status = params.status === "resolved" ? "resolved" : "open";
+            if (!noteId) {
+                throw new Error("setReviewNoteStatus requires a noteId.");
+            }
+            const note = setReviewNoteStatus(this.session, noteId, status);
+            if (!note) {
+                throw new Error(`Review note ${noteId} was not found.`);
+            }
+            addDecisionRecord(this.session, {
+                kind: "review",
+                agent: note.agent,
+                taskId: note.taskId,
+                summary: `${status === "resolved" ? "Resolved" : "Reopened"} review note ${note.id}`,
+                detail: note.summary,
+                metadata: {
+                    reviewNoteId: note.id,
+                    status,
+                    filePath: note.filePath,
+                    hunkIndex: note.hunkIndex
+                }
+            });
+            await saveSessionRecord(this.paths, this.session);
+            if (note.taskId) {
+                await this.refreshTaskArtifactReviewNotes(note.taskId);
+            }
+            await recordEvent(this.paths, this.session.id, "review.note_status_changed", {
+                reviewNoteId: note.id,
+                taskId: note.taskId,
+                agent: note.agent,
+                filePath: note.filePath,
+                status: note.status
+            });
+            await this.publishSnapshot("review.note_status_changed");
+        });
+    }
+    async enqueueReviewFollowUpFromRpc(params) {
+        await this.runMutation(async ()=>{
+            const noteId = typeof params.noteId === "string" ? params.noteId : "";
+            const owner = params.owner === "claude" ? "claude" : "codex";
+            const mode = params.mode === "handoff" ? "handoff" : "fix";
+            if (!noteId) {
+                throw new Error("enqueueReviewFollowUp requires a noteId.");
+            }
+            const note = this.session.reviewNotes.find((item)=>item.id === noteId) ?? null;
+            if (!note) {
+                throw new Error(`Review note ${noteId} was not found.`);
+            }
+            const taskId = `task-review-${Date.now()}`;
+            const scope = note.hunkHeader ? `${note.filePath} ${note.hunkHeader}` : note.filePath;
+            const promptLines = [
+                `${mode === "handoff" ? "Handle a review handoff" : "Address a review note"} for ${scope}.`,
+                `Disposition: ${note.disposition}.`,
+                `Review note: ${note.body}`
+            ];
+            if (note.taskId) {
+                promptLines.push(`Originating task: ${note.taskId}.`);
+            }
+            if (mode === "handoff") {
+                promptLines.push(`This was handed off from ${note.agent} work to ${owner}.`);
+            }
+            promptLines.push(`Focus the change in ${note.filePath} and update the managed worktree accordingly.`);
+            const task = buildAdHocTask(owner, promptLines.join(" "), taskId, {
+                routeReason: mode === "handoff" ? `Operator handed off review note ${note.id} to ${owner}.` : `Operator created a follow-up task from review note ${note.id}.`,
+                claimedPaths: [
+                    note.filePath
+                ]
+            });
+            this.session.tasks.push(task);
+            linkReviewFollowUpTask(this.session, note.id, taskId);
+            upsertPathClaim(this.session, {
+                taskId,
+                agent: owner,
+                source: "route",
+                paths: task.claimedPaths,
+                note: task.routeReason
+            });
+            addDecisionRecord(this.session, {
+                kind: "review",
+                agent: owner,
+                taskId,
+                summary: `Queued ${mode} follow-up from review note ${note.id}`,
+                detail: note.body,
+                metadata: {
+                    reviewNoteId: note.id,
+                    owner,
+                    mode,
+                    filePath: note.filePath,
+                    sourceAgent: note.agent
+                }
+            });
+            await saveSessionRecord(this.paths, this.session);
+            if (note.taskId) {
+                await this.refreshTaskArtifactReviewNotes(note.taskId);
+            }
+            await recordEvent(this.paths, this.session.id, "review.followup_queued", {
+                reviewNoteId: note.id,
+                followUpTaskId: taskId,
+                owner,
+                mode,
+                filePath: note.filePath
+            });
+            await this.publishSnapshot("review.followup_queued");
+        });
+    }
+    async refreshTaskArtifactReviewNotes(taskId) {
+        const artifact = await loadTaskArtifact(this.paths, taskId);
+        if (!artifact) {
+            return;
+        }
+        artifact.reviewNotes = reviewNotesForTask(this.session, taskId);
+        await saveTaskArtifact(this.paths, artifact);
+    }
+    async refreshReviewArtifactsForNotes(notes) {
+        const taskIds = [
+            ...new Set(notes.map((note)=>note.taskId).filter((value)=>Boolean(value)))
+        ];
+        for (const taskId of taskIds){
+            await this.refreshTaskArtifactReviewNotes(taskId);
+        }
+    }
     async publishSnapshot(reason) {
         if (this.subscribers.size === 0) {
             return;
@@ -545,6 +839,22 @@ export class KaviDaemon {
                     claimedPaths: task.claimedPaths
                 }
             });
+            const autoResolvedNotes = autoResolveReviewNotesForCompletedTask(this.session, task.id);
+            for (const note of autoResolvedNotes){
+                addDecisionRecord(this.session, {
+                    kind: "review",
+                    agent: note.agent,
+                    taskId: note.taskId,
+                    summary: `Auto-resolved review note ${note.id}`,
+                    detail: `Closed because linked follow-up task ${task.id} completed successfully.`,
+                    metadata: {
+                        reviewNoteId: note.id,
+                        filePath: note.filePath,
+                        followUpTaskId: task.id,
+                        reason: "follow-up-task-completed"
+                    }
+                });
+            }
             this.session.peerMessages.push(...peerMessages);
             await saveSessionRecord(this.paths, this.session);
             const decisionReplay = buildDecisionReplay(this.session, task, task.owner === "claude" ? "claude" : "codex");
@@ -561,15 +871,26 @@ export class KaviDaemon {
                 rawOutput,
                 error: null,
                 envelope,
+                reviewNotes: reviewNotesForTask(this.session, task.id),
                 startedAt,
                 finishedAt: task.updatedAt
             });
+            await this.refreshReviewArtifactsForNotes(autoResolvedNotes);
             await recordEvent(this.paths, this.session.id, "task.completed", {
                 taskId: task.id,
                 owner: task.owner,
                 status: task.status,
                 peerMessages: peerMessages.length
             });
+            for (const note of autoResolvedNotes){
+                await recordEvent(this.paths, this.session.id, "review.note_auto_resolved", {
+                    reviewNoteId: note.id,
+                    taskId: note.taskId,
+                    followUpTaskId: task.id,
+                    agent: note.agent,
+                    filePath: note.filePath
+                });
+            }
             await this.publishSnapshot("task.completed");
         } catch (error) {
             task.status = "failed";
@@ -617,6 +938,7 @@ export class KaviDaemon {
                 rawOutput: null,
                 error: task.summary,
                 envelope: null,
+                reviewNotes: reviewNotesForTask(this.session, task.id),
                 startedAt,
                 finishedAt: task.updatedAt
             });

package/dist/git.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { ensureDir } from "./fs.js";
 import { buildSessionId } from "./paths.js";
 import { runCommand } from "./process.js";
-export async function detectRepoRoot(cwd) {
+export async function findRepoRoot(cwd) {
     const result = await runCommand("git", [
         "rev-parse",
         "--show-toplevel"
@@ -11,10 +11,17 @@ export async function detectRepoRoot(cwd) {
         cwd
     });
     if (result.code !== 0) {
-        throw new Error(result.stderr.trim() || "Not inside a git repository.");
+        return null;
     }
     return result.stdout.trim();
 }
+export async function detectRepoRoot(cwd) {
+    const repoRoot = await findRepoRoot(cwd);
+    if (!repoRoot) {
+        throw new Error("Not inside a git repository.");
+    }
+    return repoRoot;
+}
 export async function getHeadCommit(repoRoot) {
     const result = await runCommand("git", [
         "rev-parse",
@@ -27,6 +34,98 @@ export async function getHeadCommit(repoRoot) {
     }
     return result.stdout.trim();
 }
+async function initializeRepository(repoRoot) {
+    const preferred = await runCommand("git", [
+        "init",
+        "--initial-branch=main"
+    ], {
+        cwd: repoRoot
+    });
+    if (preferred.code === 0) {
+        return;
+    }
+    const fallback = await runCommand("git", [
+        "init"
+    ], {
+        cwd: repoRoot
+    });
+    if (fallback.code !== 0) {
+        throw new Error(fallback.stderr.trim() || preferred.stderr.trim() || `Unable to initialize git in ${repoRoot}.`);
+    }
+}
+export async function ensureGitRepository(cwd) {
+    const existing = await findRepoRoot(cwd);
+    if (existing) {
+        return {
+            repoRoot: existing,
+            createdRepository: false
+        };
+    }
+    await initializeRepository(cwd);
+    return {
+        repoRoot: await detectRepoRoot(cwd),
+        createdRepository: true
+    };
+}
+export async function hasHeadCommit(repoRoot) {
+    const result = await runCommand("git", [
+        "rev-parse",
+        "--verify",
+        "HEAD"
+    ], {
+        cwd: repoRoot
+    });
+    return result.code === 0;
+}
+export async function ensureBootstrapCommit(repoRoot, message = "kavi: bootstrap project") {
+    if (await hasHeadCommit(repoRoot)) {
+        return {
+            createdCommit: false,
+            commit: await getHeadCommit(repoRoot),
+            stagedPaths: []
+        };
+    }
+    const add = await runCommand("git", [
+        "add",
+        "-A"
+    ], {
+        cwd: repoRoot
+    });
+    if (add.code !== 0) {
+        throw new Error(add.stderr.trim() || `Unable to stage bootstrap files in ${repoRoot}.`);
+    }
+    const staged = await runCommand("git", [
+        "diff",
+        "--cached",
+        "--name-only",
+        "--diff-filter=ACMRTUXB"
+    ], {
+        cwd: repoRoot
+    });
+    if (staged.code !== 0) {
+        throw new Error(staged.stderr.trim() || `Unable to inspect staged bootstrap files in ${repoRoot}.`);
+    }
+    const commit = await runCommand("git", [
+        "-c",
+        "user.name=Kavi",
+        "-c",
+        "user.email=kavi@local.invalid",
+        "commit",
+        "--allow-empty",
+        "-m",
+        message
+    ], {
+        cwd: repoRoot
+    });
+    if (commit.code !== 0) {
+        throw new Error(commit.stderr.trim() || `Unable to create bootstrap commit in ${repoRoot}.`);
+    }
+    return {
+        createdCommit: true,
+        commit: await getHeadCommit(repoRoot),
+        stagedPaths: parsePathList(staged.stdout)
+    };
+}
 export async function getCurrentBranch(repoRoot) {
     const result = await runCommand("git", [
         "branch",