@mandipadk7/kavi 0.1.5 → 0.1.7

package/README.md

@@ -3,16 +3,22 @@
 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 status`: inspect session health, task counts, and configured routing ownership rules from any terminal.
+- `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.
+- `kavi recommend-apply`: turn an actionable handoff or integration recommendation into a queued managed task.
 - `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,6 +39,7 @@ Runtime model:
 - 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.
 - 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.
+- 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.
 
 Notes:
@@ -41,12 +48,16 @@ Notes:
 - Claude still runs through the installed `claude` CLI with Kavi-managed hooks and approval decisions.
 - `kavi doctor` now checks Claude auth readiness with `claude auth status`, and startup blocks if Claude is installed but not authenticated.
 - `kavi doctor` also validates ownership path rules for duplicates, repo escapes, and absolute-path mistakes before those rules affect routing.
+- `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.
+- 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.
 - 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.
 - 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.
 
 Install commands for testers:
 

package/dist/adapters/shared.js

@@ -4,11 +4,13 @@ function formatDecisionLine(summary, detail) {
     return detail.trim() ? `- ${summary}: ${detail}` : `- ${summary}`;
 }
 export function buildDecisionReplay(session, task, agent) {
+    const winningRule = task.routeMetadata?.winningRule && typeof task.routeMetadata.winningRule === "object" && !Array.isArray(task.routeMetadata.winningRule) && typeof task.routeMetadata.winningRule.pattern === "string" ? String(task.routeMetadata.winningRule.pattern) : null;
     const taskDecisions = session.decisions.filter((decision)=>decision.taskId === task.id).slice(-6).map((decision)=>formatDecisionLine(`[${decision.kind}] ${decision.summary}`, decision.detail));
     const sharedDecisions = session.decisions.filter((decision)=>decision.taskId !== task.id && (decision.agent === agent || decision.agent === null)).slice(-4).map((decision)=>formatDecisionLine(`[${decision.kind}] ${decision.summary}`, decision.detail));
     const relevantClaims = session.pathClaims.filter((claim)=>claim.status === "active" && (claim.taskId === task.id || claim.agent !== agent)).slice(-6).map((claim)=>`- ${claim.agent} ${claim.source} claim on ${claim.paths.join(", ")}${claim.note ? `: ${claim.note}` : ""}`);
     const replay = [
         `- Current route reason: ${task.routeReason ?? "not recorded"}`,
+        `- Winning ownership rule: ${winningRule ?? "none"}`,
         `- Current claimed paths: ${task.claimedPaths.join(", ") || "none"}`,
         ...taskDecisions,
         ...sharedDecisions,

package/dist/daemon.js

@@ -1002,7 +1002,10 @@ export class KaviDaemon {
             return;
         }
         const changedPaths = await listWorktreeChangedPaths(worktree.path, this.session.baseCommit);
-        const hadClaimedSurface = task.claimedPaths.length > 0 || this.session.pathClaims.some((claim)=>claim.taskId === task.id && claim.status === "active");
+        const previousClaimedPaths = [
+            ...task.claimedPaths
+        ];
+        const hadClaimedSurface = previousClaimedPaths.length > 0 || this.session.pathClaims.some((claim)=>claim.taskId === task.id && claim.status === "active");
         task.claimedPaths = changedPaths;
         const claim = upsertPathClaim(this.session, {
             taskId: task.id,
@@ -1031,6 +1034,14 @@ export class KaviDaemon {
                         supersededByPaths: changedPaths
                     }
                 });
+                await recordEvent(this.paths, this.session.id, "claim.superseded", {
+                    claimId: releasedClaim.id,
+                    taskId: releasedClaim.taskId,
+                    agent: releasedClaim.agent,
+                    paths: releasedClaim.paths,
+                    supersededByTaskId: task.id,
+                    supersededByPaths: changedPaths
+                });
             }
             return;
         }
@@ -1045,6 +1056,12 @@ export class KaviDaemon {
                     releaseReason: "empty-diff-claim"
                 }
             });
+            await recordEvent(this.paths, this.session.id, "claim.released", {
+                taskId: task.id,
+                agent: task.owner,
+                paths: previousClaimedPaths,
+                reason: "empty-diff-claim"
+            });
         }
     }
 }

package/dist/decision-ledger.js

@@ -21,6 +21,17 @@ function pathOverlaps(left, right) {
     }
     return leftPath === rightPath || leftPath.startsWith(`${rightPath}/`) || rightPath.startsWith(`${leftPath}/`);
 }
+function overlapPath(left, right) {
+    const leftPath = normalizePath(left);
+    const rightPath = normalizePath(right);
+    if (!pathOverlaps(leftPath, rightPath)) {
+        return null;
+    }
+    if (leftPath === rightPath) {
+        return leftPath;
+    }
+    return leftPath.startsWith(`${rightPath}/`) ? leftPath : rightPath;
+}
 export function addDecisionRecord(session, input) {
     const record = {
         id: randomUUID(),
@@ -126,6 +137,85 @@ export function findClaimConflicts(session, owner, claimedPaths) {
     }
     return activePathClaims(session).filter((claim)=>claim.agent !== owner && claim.paths.some((item)=>normalizedPaths.some((candidate)=>pathOverlaps(item, candidate))));
 }
+export function buildClaimHotspots(session) {
+    const hotspots = new Map();
+    const claims = activePathClaims(session);
+    for(let index = 0; index < claims.length; index += 1){
+        const left = claims[index];
+        if (!left) {
+            continue;
+        }
+        for(let inner = index + 1; inner < claims.length; inner += 1){
+            const right = claims[inner];
+            if (!right || left.taskId === right.taskId) {
+                continue;
+            }
+            const overlappingPaths = left.paths.flatMap((leftPath)=>right.paths.map((rightPath)=>overlapPath(leftPath, rightPath)).filter((value)=>Boolean(value)));
+            if (overlappingPaths.length === 0) {
+                continue;
+            }
+            for (const hotspotPath of overlappingPaths){
+                const existing = hotspots.get(hotspotPath);
+                if (existing) {
+                    existing.overlapCount += 1;
+                    existing.agents = [
+                        ...new Set([
+                            ...existing.agents,
+                            left.agent,
+                            right.agent
+                        ])
+                    ];
+                    existing.taskIds = [
+                        ...new Set([
+                            ...existing.taskIds,
+                            left.taskId,
+                            right.taskId
+                        ])
+                    ];
+                    existing.claimIds = [
+                        ...new Set([
+                            ...existing.claimIds,
+                            left.id,
+                            right.id
+                        ])
+                    ];
+                    continue;
+                }
+                hotspots.set(hotspotPath, {
+                    path: hotspotPath,
+                    agents: [
+                        ...new Set([
+                            left.agent,
+                            right.agent
+                        ])
+                    ],
+                    taskIds: [
+                        ...new Set([
+                            left.taskId,
+                            right.taskId
+                        ])
+                    ],
+                    claimIds: [
+                        ...new Set([
+                            left.id,
+                            right.id
+                        ])
+                    ],
+                    overlapCount: 1
+                });
+            }
+        }
+    }
+    return [
+        ...hotspots.values()
+    ].sort((left, right)=>{
+        const overlapDelta = right.overlapCount - left.overlapCount;
+        if (overlapDelta !== 0) {
+            return overlapDelta;
+        }
+        return left.path.localeCompare(right.path);
+    });
+}
 
 
 //# sourceURL=decision-ledger.ts

package/dist/doctor.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { loadConfig } from "./config.js";
 import { fileExists } from "./fs.js";
+import { findOwnershipRuleConflicts } from "./ownership.js";
 import { runCommand } from "./process.js";
 import { hasSupportedNode, minimumNodeMajor, resolveSessionRuntime } from "./runtime.js";
 export function parseClaudeAuthStatus(output) {
@@ -87,6 +88,10 @@ export function validateRoutingPathRules(config) {
             ...new Set(overlappingRules)
         ].join(", ")}`);
     }
+    const ambiguousConflicts = findOwnershipRuleConflicts(config).filter((conflict)=>conflict.kind === "ambiguous-overlap").map((conflict)=>`${conflict.leftOwner}:${conflict.leftPattern} <> ${conflict.rightOwner}:${conflict.rightPattern}`);
+    if (ambiguousConflicts.length > 0) {
+        issues.push(`Ownership rules have ambiguous overlaps without a specificity winner: ${ambiguousConflicts.join(", ")}`);
+    }
     return issues;
 }
 function normalizeVersion(output) {