@mandipadk7/kavi 0.1.6 → 1.0.0

package/README.md

@@ -3,18 +3,26 @@
 Kavi is a local terminal control plane for managed Codex and Claude collaboration.
 
 Current capabilities:
+- `kavi version` and `kavi --version`: print the installed package version.
 - `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 update`: check for and install a newer published Kavi package from npm.
 - `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, even from an empty folder or a repo with no `HEAD` yet.
 - `kavi resume`: reopen the operator console for the current repo session.
+- `kavi summary`: show a cohesive session-level view of progress, current changes, recent activity, and landing readiness.
+- `kavi result`: show the current or latest landed outcome as one cohesive result surface, including per-agent output and merged landing details.
 - `kavi status`: inspect session health, task counts, and configured routing ownership rules from any terminal.
+- `kavi activity`: show the session as a linear activity stream instead of raw daemon events.
 - `kavi route`: preview how Kavi would route a prompt before enqueuing it.
 - `kavi routes`: inspect recent task routing decisions with strategy, confidence, and metadata.
 - `kavi paths`: inspect resolved repo-local, user-local, worktree, and runtime paths.
 - `kavi task`: enqueue a task for `codex`, `claude`, or `auto` routing.
+- `kavi recommend`: inspect integration, handoff, and ownership-configuration recommendations derived from live claims, reviews, and routing state, with filters for kind, target agent, and active vs dismissed status.
+- `kavi recommend-apply`: turn an actionable handoff or integration recommendation into a queued managed task.
+- `kavi recommend-dismiss` and `kavi recommend-restore`: manage the recommendation inbox without losing the underlying session context.
 - `kavi tasks`: inspect the session task list with summaries and artifact availability.
 - `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.
@@ -33,8 +41,10 @@ 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, worktree diff review with file and hunk navigation, and persisted operator review threads on files or hunks.
+- Landed result reports are persisted under `.kavi/state/reports/`, so the latest merged outcome remains inspectable after the landing command exits.
+- The operator console now opens on an activity-first view so the session reads like a linear progress log, while still exposing dedicated results, task board, dual agent lanes, approvals, diff review, and persisted operator review threads when you need to drill in.
 - Routing can now use explicit path ownership rules from `.kavi/config.toml` via `[routing].codex_paths` and `[routing].claude_paths`, so known parts of the tree can bypass looser keyword or AI routing.
+- Validation is optional by default for new repos. Set `validation_command` in `.kavi/config.toml` once the project has a real test or build command you want Kavi to enforce during `land`.
 - Ownership routing now prefers the strongest matching rule, not just the side with the most raw glob hits, and route metadata records the winning rule when one exists.
 - Diff-based path claims now release older overlapping same-agent claims automatically, so the active claim set stays closer to each managed worktree's current unlanded surface.
 
@@ -47,20 +57,29 @@ Notes:
 - `kavi doctor` now also flags overlapping cross-agent ownership rules that do not produce a clear specificity winner.
 - 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, `A/C/Q/M` add review notes, `o/O` cycle existing threads, `T` reply, `E` edit, `R` resolve or reopen, `a` cycle thread assignee, `w` mark a thread as won't-fix, `x` mark it as accepted-risk, `F` queue a fix task, `H` queue a handoff task, `y/n` resolve approvals, and `c` opens the inline task composer with live route preview diagnostics.
+- The console is keyboard-driven: `1-9` 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, `a` cycle thread assignee, `w` mark a thread as won't-fix, `x` mark it as accepted-risk, `F` queue a fix task, `H` queue a handoff task, `y/n` resolve approvals, and `c` opens the inline task composer with live route preview diagnostics.
 - Review filters are available both in the CLI and the TUI: `kavi reviews --assignee operator --status open`, and inside the console use `u`, `v`, and `d` to cycle assignee, status, and disposition filters for the active diff context.
 - The claims inspector now shows active overlap hotspots and ownership-rule conflicts so routing pressure points are visible directly in the operator surface.
+- The claims and decision inspectors now also show recommendation-driven next actions, so hotspots, cross-agent review pressure, and ownership-config problems can be turned into follow-up tasks directly from the operator surface.
+- Recommendations now have a persisted lifecycle of their own: they can be dismissed, restored, and tracked across follow-up tasks, and repeated applies are guarded when an open follow-up task already exists.
 - Review threads now carry explicit assignees and richer dispositions, including `accepted risk` and `won't fix`, instead of relying only on free-form note text.
 - 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.
+- `kavi update --check` reports newer published builds without installing them, and `kavi update` can apply a chosen `latest`, `beta`, or exact version after confirmation.
+- The operator console now includes a dedicated recommendations view. Use `8` to switch there, `Enter` to apply a recommendation, `P` to force an additional follow-up task when one is already open, `z` to dismiss, and `Z` to restore.
+- `kavi land` now prints a clearer merged-result summary, including the pre-land change surface by agent, validation status, and how many review threads were landed as part of the merge.
+- After `kavi land`, run `kavi result` to inspect the persisted merged-result report and the latest per-agent outcome in one place.
 
-Install commands for testers:
+Install commands:
 
 ```bash
+# stable
+npm install -g @mandipadk7/kavi
+
 # beta channel
 npm install -g @mandipadk7/kavi@beta
 
 # one-off
-npx @mandipadk7/kavi@beta help
+npx @mandipadk7/kavi help
 ```
 
 User-local config example:

package/dist/adapters/claude.js

@@ -202,9 +202,12 @@ export async function writeClaudeSettings(paths, session) {
     };
     await fs.writeFile(paths.claudeSettingsFile, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
 }
+export function resolveClaudeSessionId(session) {
+    return session.agentStatus.claude.sessionId ?? session.id;
+}
 export async function runClaudeTask(session, task, paths) {
     const worktree = findWorktree(session, "claude");
-    const claudeSessionId = session.agentStatus.claude.sessionId ?? `${session.id}-claude`;
+    const claudeSessionId = resolveClaudeSessionId(session);
     await writeClaudeSettings(paths, session);
     const repoPrompt = await loadAgentPrompt(paths, "claude");
     const prompt = [

package/dist/config.js

@@ -4,7 +4,7 @@ import { ensureDir, fileExists } from "./fs.js";
 import { parseToml } from "./toml.js";
 const DEFAULT_CONFIG = `version = 1
 base_branch = "main"
-validation_command = "npm test"
+validation_command = ""
 message_limit = 6
 
 [routing]
@@ -57,7 +57,7 @@ export function defaultConfig() {
     return {
         version: 1,
         baseBranch: "main",
-        validationCommand: "npm test",
+        validationCommand: "",
         messageLimit: 6,
         routing: {
             frontendKeywords: [
@@ -109,6 +109,7 @@ export async function ensureProjectScaffold(paths) {
     await ensureDir(paths.kaviDir);
     await ensureDir(paths.promptsDir);
     await ensureDir(paths.stateDir);
+    await ensureDir(paths.reportsDir);
     await ensureDir(paths.runtimeDir);
     await ensureDir(paths.runsDir);
     if (!await fileExists(paths.configFile)) {
@@ -140,7 +141,7 @@ export async function loadConfig(paths) {
     return {
         version: asNumber(parsed.version, 1),
         baseBranch: asString(parsed.base_branch, "main"),
-        validationCommand: asString(parsed.validation_command, "npm test"),
+        validationCommand: asString(parsed.validation_command, ""),
         messageLimit: asNumber(parsed.message_limit, 6),
         routing: {
             frontendKeywords: asStringArray(routing.frontend_keywords, defaultConfig().routing.frontendKeywords),

package/dist/daemon.js

@@ -9,6 +9,8 @@ import { listApprovalRequests, resolveApprovalRequest } from "./approvals.js";
 import { addDecisionRecord, releaseSupersededClaims, upsertPathClaim } from "./decision-ledger.js";
 import { getWorktreeDiffReview, listWorktreeChangedPaths } from "./git.js";
 import { nowIso } from "./paths.js";
+import { dismissOperatorRecommendation, recordRecommendationApplied, restoreOperatorRecommendation } from "./recommendations.js";
+import { loadLatestLandReport } from "./reports.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";
@@ -171,6 +173,20 @@ export class KaviDaemon {
                         ok: true
                     }
                 };
+            case "dismissRecommendation":
+                await this.dismissRecommendationFromRpc(params);
+                return {
+                    result: {
+                        ok: true
+                    }
+                };
+            case "restoreRecommendation":
+                await this.restoreRecommendationFromRpc(params);
+                return {
+                    result: {
+                        ok: true
+                    }
+                };
             case "shutdown":
                 return {
                     result: {
@@ -253,11 +269,13 @@ export class KaviDaemon {
                 agent: worktree.agent,
                 paths: await listWorktreeChangedPaths(worktree.path, session.baseCommit).catch(()=>[])
             })));
+        const latestLandReport = await loadLatestLandReport(this.paths);
         return {
             session,
             events,
             approvals,
-            worktreeDiffs
+            worktreeDiffs,
+            latestLandReport
         };
     }
     async runMutation(fn) {
@@ -310,14 +328,58 @@ export class KaviDaemon {
                 paths: task.claimedPaths,
                 note: task.routeReason
             });
+            if (typeof params.recommendationId === "string") {
+                recordRecommendationApplied(this.session, params.recommendationId, taskId);
+            }
             await saveSessionRecord(this.paths, this.session);
             await recordEvent(this.paths, this.session.id, "task.enqueued", {
                 owner,
-                via: "rpc"
+                via: "rpc",
+                recommendationId: typeof params.recommendationId === "string" ? params.recommendationId : null
             });
+            if (typeof params.recommendationId === "string" && (params.recommendationKind === "handoff" || params.recommendationKind === "integration" || params.recommendationKind === "ownership-config")) {
+                await recordEvent(this.paths, this.session.id, "recommendation.applied", {
+                    recommendationId: params.recommendationId,
+                    recommendationKind: params.recommendationKind,
+                    owner,
+                    taskId
+                });
+            }
             await this.publishSnapshot("task.enqueued");
         });
     }
+    async dismissRecommendationFromRpc(params) {
+        await this.runMutation(async ()=>{
+            const recommendationId = typeof params.recommendationId === "string" ? params.recommendationId : "";
+            if (!recommendationId) {
+                throw new Error("dismissRecommendation requires a recommendationId.");
+            }
+            const reason = typeof params.reason === "string" ? params.reason : null;
+            const recommendation = dismissOperatorRecommendation(this.session, recommendationId, reason);
+            await saveSessionRecord(this.paths, this.session);
+            await recordEvent(this.paths, this.session.id, "recommendation.dismissed", {
+                recommendationId,
+                kind: recommendation.kind,
+                reason
+            });
+            await this.publishSnapshot("recommendation.dismissed");
+        });
+    }
+    async restoreRecommendationFromRpc(params) {
+        await this.runMutation(async ()=>{
+            const recommendationId = typeof params.recommendationId === "string" ? params.recommendationId : "";
+            if (!recommendationId) {
+                throw new Error("restoreRecommendation requires a recommendationId.");
+            }
+            const recommendation = restoreOperatorRecommendation(this.session, recommendationId);
+            await saveSessionRecord(this.paths, this.session);
+            await recordEvent(this.paths, this.session.id, "recommendation.restored", {
+                recommendationId,
+                kind: recommendation.kind
+            });
+            await this.publishSnapshot("recommendation.restored");
+        });
+    }
     async kickoffFromRpc(params) {
         await this.runMutation(async ()=>{
             const prompt = typeof params.prompt === "string" ? params.prompt : "";
@@ -823,10 +885,22 @@ export class KaviDaemon {
                     paths: task.claimedPaths,
                     note: task.routeReason
                 });
+                if (typeof command.payload.recommendationId === "string") {
+                    recordRecommendationApplied(this.session, command.payload.recommendationId, taskId);
+                }
                 await saveSessionRecord(this.paths, this.session);
                 await recordEvent(this.paths, this.session.id, "task.enqueued", {
-                    owner
+                    owner,
+                    recommendationId: typeof command.payload.recommendationId === "string" ? command.payload.recommendationId : null
                 });
+                if (typeof command.payload.recommendationId === "string" && (command.payload.recommendationKind === "handoff" || command.payload.recommendationKind === "integration" || command.payload.recommendationKind === "ownership-config")) {
+                    await recordEvent(this.paths, this.session.id, "recommendation.applied", {
+                        recommendationId: command.payload.recommendationId,
+                        recommendationKind: command.payload.recommendationKind,
+                        owner,
+                        taskId
+                    });
+                }
                 await this.publishSnapshot("task.enqueued");
             }
         }

package/dist/git.js

@@ -342,6 +342,32 @@ export async function listWorktreeChangedPaths(worktreePath, baseCommit) {
         ...parsePathList(untracked.stdout)
     ]);
 }
+export async function resolveValidationPlan(integrationPath, validationCommand) {
+    const trimmed = validationCommand.trim();
+    if (!trimmed) {
+        return {
+            command: "",
+            status: "not_configured",
+            detail: "No validation command was configured."
+        };
+    }
+    if (trimmed === "npm test") {
+        try {
+            await fs.access(path.join(integrationPath, "package.json"));
+        } catch  {
+            return {
+                command: trimmed,
+                status: "skipped",
+                detail: 'Skipped default validation command "npm test" because package.json is not present yet.'
+            };
+        }
+    }
+    return {
+        command: trimmed,
+        status: "ran",
+        detail: `Validation ran with "${trimmed}".`
+    };
+}
 export async function getWorktreeDiffReview(agent, worktreePath, baseCommit, filePath) {
     const changedPaths = await listWorktreeChangedPaths(worktreePath, baseCommit);
     const selectedPath = filePath && changedPaths.includes(filePath) ? filePath : changedPaths[0] ?? null;
@@ -461,16 +487,20 @@ export async function landBranches(repoRoot, targetBranch, worktrees, validation
             throw new Error(merge.stderr.trim() || `Unable to merge branch ${worktree.branch} into integration branch ${integrationBranch}.`);
         }
     }
-    if (validationCommand.trim()) {
-        const validation = await runCommand("zsh", [
+    const validation = await resolveValidationPlan(integrationPath, validationCommand);
+    if (validation.status === "skipped") {
+        commandsRun.push(`SKIP ${validation.command} (${validation.detail})`);
+    }
+    if (validation.status === "ran") {
+        const validationRun = await runCommand("zsh", [
             "-lc",
-            validationCommand
+            validation.command
         ], {
             cwd: integrationPath
         });
-        commandsRun.push(validationCommand);
-        if (validation.code !== 0) {
-            throw new Error(`Validation command failed.\n${validation.stdout}\n${validation.stderr}`.trim());
+        commandsRun.push(validation.command);
+        if (validationRun.code !== 0) {
+            throw new Error(`Validation command failed.\n${validationRun.stdout}\n${validationRun.stderr}`.trim());
         }
     }
     const currentBranch = await getCurrentBranch(repoRoot).catch(()=>"");
@@ -500,10 +530,35 @@ export async function landBranches(repoRoot, targetBranch, worktrees, validation
             throw new Error(updateRef.stderr.trim() || `Unable to advance ${targetBranch}; it changed while landing was in progress.`);
         }
     }
+    const landedHead = await getBranchCommit(repoRoot, targetBranch);
+    for (const worktree of worktrees){
+        const reset = await runCommand("git", [
+            "reset",
+            "--hard",
+            landedHead
+        ], {
+            cwd: worktree.path
+        });
+        commandsRun.push(`git -C ${worktree.path} reset --hard ${landedHead}`);
+        if (reset.code !== 0) {
+            throw new Error(reset.stderr.trim() || `Unable to reset managed worktree ${worktree.path} to landed head ${landedHead}.`);
+        }
+        const clean = await runCommand("git", [
+            "clean",
+            "-fd"
+        ], {
+            cwd: worktree.path
+        });
+        commandsRun.push(`git -C ${worktree.path} clean -fd`);
+        if (clean.code !== 0) {
+            throw new Error(clean.stderr.trim() || `Unable to clean managed worktree ${worktree.path}.`);
+        }
+    }
     return {
         commandsRun,
         integrationBranch,
         integrationPath,
+        validation,
         snapshotCommits
     };
 }