@mandipadk7/kavi 0.1.6 → 0.1.7

package/README.md

@@ -3,10 +3,12 @@
 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.
@@ -15,6 +17,8 @@ Current capabilities:
 - `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.
@@ -50,8 +54,10 @@ Notes:
 - 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/main.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import fs from "node:fs/promises";
+import readline from "node:readline/promises";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { createApprovalRequest, describeToolUse, findApprovalRule, listApprovalRequests, resolveApprovalRequest, waitForApprovalDecision } from "./approvals.js";
@@ -10,9 +11,11 @@ import { addDecisionRecord, buildClaimHotspots, releasePathClaims, upsertPathCla
 import { runDoctor } from "./doctor.js";
 import { writeJson } from "./fs.js";
 import { createGitignoreEntries, detectRepoRoot, ensureBootstrapCommit, ensureGitRepository, ensureWorktrees, findRepoRoot, findOverlappingWorktreePaths, landBranches, resolveTargetBranch } from "./git.js";
+import { loadPackageInfo } from "./package-info.js";
 import { buildSessionId, resolveAppPaths } from "./paths.js";
-import { isProcessAlive, spawnDetachedNode } from "./process.js";
+import { isProcessAlive, runCommand, runInteractiveCommand, spawnDetachedNode } from "./process.js";
 import { pingRpc, readSnapshot, rpcEnqueueTask, rpcNotifyExternalUpdate, rpcKickoff, rpcRecentEvents, rpcResolveApproval, rpcShutdown, rpcTaskArtifact } from "./rpc.js";
+import { buildOperatorRecommendations } from "./recommendations.js";
 import { findOwnershipRuleConflicts } from "./ownership.js";
 import { filterReviewNotes, markReviewNotesLandedForTasks } from "./reviews.js";
 import { resolveSessionRuntime } from "./runtime.js";
@@ -20,6 +23,7 @@ import { buildAdHocTask, extractPromptPathHints, previewRouteDecision, routeTask
 import { createSessionRecord, loadSessionRecord, readRecentEvents, recordEvent, saveSessionRecord, sessionExists, sessionHeartbeatAgeMs } from "./session.js";
 import { listTaskArtifacts, loadTaskArtifact, saveTaskArtifact } from "./task-artifacts.js";
 import { attachTui } from "./tui.js";
+import { buildUpdatePlan, parseRegistryVersion } from "./update.js";
 const HEARTBEAT_STALE_MS = 10_000;
 const CLAUDE_AUTO_ALLOW_TOOLS = new Set([
     "Read",
@@ -65,11 +69,29 @@ async function readStdinText() {
     }
     return content;
 }
+async function confirmAction(prompt) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        return false;
+    }
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    try {
+        const answer = await rl.question(`${prompt} [y/N]: `);
+        const normalized = answer.trim().toLowerCase();
+        return normalized === "y" || normalized === "yes";
+    } finally{
+        rl.close();
+    }
+}
 function renderUsage() {
     return [
         "Usage:",
+        "  kavi version",
         "  kavi init [--home] [--no-commit]",
         "  kavi doctor [--json]",
+        "  kavi update [--check] [--dry-run] [--yes] [--tag latest|beta] [--version X.Y.Z]",
         "  kavi start [--goal \"...\"]",
         "  kavi open [--goal \"...\"]",
         "  kavi resume",
@@ -78,6 +100,8 @@ function renderUsage() {
         "  kavi routes [--json] [--limit N]",
         "  kavi paths [--json]",
         "  kavi task [--agent codex|claude|auto] <prompt>",
+        "  kavi recommend [--json]",
+        "  kavi recommend-apply <recommendation-id>",
         "  kavi tasks [--json]",
         "  kavi task-output <task-id|latest> [--json]",
         "  kavi decisions [--json] [--limit N]",
@@ -92,6 +116,19 @@ function renderUsage() {
         "  kavi help"
     ].join("\n");
 }
+async function commandVersion(args) {
+    const packageInfo = await loadPackageInfo();
+    const payload = {
+        name: packageInfo.name,
+        version: packageInfo.version,
+        node: process.version
+    };
+    if (args.includes("--json")) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+    }
+    console.log(`${packageInfo.name} ${packageInfo.version}`);
+}
 function isSessionLive(session) {
     if (session.status !== "running") {
         return false;
@@ -196,6 +233,108 @@ async function commandDoctor(cwd, args) {
     }
     process.exitCode = failed ? 1 : 0;
 }
+async function commandUpdate(cwd, args) {
+    const packageInfo = await loadPackageInfo();
+    const tag = getOptionalFilter(args, "--tag");
+    const version = getOptionalFilter(args, "--version");
+    const plan = buildUpdatePlan(packageInfo.name, {
+        tag,
+        version
+    });
+    const repoRoot = await findRepoRoot(cwd) ?? cwd;
+    const paths = resolveAppPaths(repoRoot);
+    const hasSession = await sessionExists(paths);
+    const session = hasSession ? await loadSessionRecord(paths) : null;
+    const registry = await runCommand("npm", plan.viewArgs, {
+        cwd: repoRoot
+    });
+    if (registry.code !== 0) {
+        const detail = registry.stderr.trim() || registry.stdout.trim() || "npm view failed";
+        if (session) {
+            await recordEvent(paths, session.id, "update.failed", {
+                packageName: packageInfo.name,
+                targetSpecifier: plan.targetSpecifier,
+                detail
+            });
+        }
+        throw new Error(`Unable to resolve update target for ${packageInfo.name}@${plan.targetSpecifier}: ${detail}`);
+    }
+    const targetVersion = parseRegistryVersion(registry.stdout);
+    if (!targetVersion) {
+        throw new Error(`Unable to parse npm registry version for ${packageInfo.name}@${plan.targetSpecifier}.`);
+    }
+    if (session) {
+        await recordEvent(paths, session.id, "update.checked", {
+            packageName: packageInfo.name,
+            currentVersion: packageInfo.version,
+            targetVersion,
+            targetSpecifier: plan.targetSpecifier
+        });
+    }
+    const payload = {
+        packageName: packageInfo.name,
+        currentVersion: packageInfo.version,
+        targetVersion,
+        targetSpecifier: plan.targetSpecifier,
+        command: [
+            "npm",
+            ...plan.installArgs
+        ]
+    };
+    if (args.includes("--check") || args.includes("--dry-run")) {
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(payload, null, 2));
+            return;
+        }
+        console.log(`Package: ${payload.packageName}`);
+        console.log(`Current version: ${payload.currentVersion}`);
+        console.log(`Target version: ${payload.targetVersion}`);
+        console.log(`Target specifier: ${payload.targetSpecifier}`);
+        console.log(`Command: ${payload.command.join(" ")}`);
+        return;
+    }
+    if (targetVersion === packageInfo.version) {
+        console.log(`${packageInfo.name} is already at ${packageInfo.version}.`);
+        return;
+    }
+    const confirmed = args.includes("--yes") || await confirmAction(`Update ${packageInfo.name} from ${packageInfo.version} to ${targetVersion} using npm?`);
+    if (!confirmed) {
+        console.log("Update cancelled.");
+        return;
+    }
+    if (session) {
+        await recordEvent(paths, session.id, "update.started", {
+            packageName: packageInfo.name,
+            currentVersion: packageInfo.version,
+            targetVersion,
+            targetSpecifier: plan.targetSpecifier
+        });
+    }
+    const exitCode = await runInteractiveCommand("npm", plan.installArgs, {
+        cwd: repoRoot
+    });
+    if (exitCode !== 0) {
+        if (session) {
+            await recordEvent(paths, session.id, "update.failed", {
+                packageName: packageInfo.name,
+                currentVersion: packageInfo.version,
+                targetVersion,
+                targetSpecifier: plan.targetSpecifier,
+                exitCode
+            });
+        }
+        throw new Error(`npm install returned exit code ${exitCode}.`);
+    }
+    if (session) {
+        await recordEvent(paths, session.id, "update.completed", {
+            packageName: packageInfo.name,
+            previousVersion: packageInfo.version,
+            targetVersion,
+            targetSpecifier: plan.targetSpecifier
+        });
+    }
+    console.log(`Updated ${packageInfo.name} from ${packageInfo.version} to ${targetVersion}.`);
+}
 async function startOrAttachSession(cwd, goal) {
     const prepared = await prepareProjectContext(cwd, {
         createRepository: true,
@@ -348,6 +487,7 @@ async function commandStatus(cwd, args) {
     const routeAnalytics = buildRouteAnalytics(session.tasks);
     const ownershipConflicts = findOwnershipRuleConflicts(session.config);
     const claimHotspots = buildClaimHotspots(session);
+    const recommendations = buildOperatorRecommendations(session);
     const payload = {
         id: session.id,
         status: session.status,
@@ -381,6 +521,12 @@ async function commandStatus(cwd, args) {
         pathClaimCounts: {
             active: session.pathClaims.filter((claim)=>claim.status === "active").length
         },
+        recommendationCounts: {
+            total: recommendations.length,
+            integration: recommendations.filter((item)=>item.kind === "integration").length,
+            handoff: recommendations.filter((item)=>item.kind === "handoff").length,
+            ownershipConfig: recommendations.filter((item)=>item.kind === "ownership-config").length
+        },
         routeCounts: routeAnalytics,
         ownershipConflicts: ownershipConflicts.length,
         claimHotspots: claimHotspots.length,
@@ -407,6 +553,7 @@ async function commandStatus(cwd, args) {
     console.log(`Reviews: open=${payload.reviewCounts.open} total=${payload.reviewCounts.total}`);
     console.log(`Decisions: total=${payload.decisionCounts.total}`);
     console.log(`Path claims: active=${payload.pathClaimCounts.active}`);
+    console.log(`Recommendations: total=${payload.recommendationCounts.total} integration=${payload.recommendationCounts.integration} handoff=${payload.recommendationCounts.handoff} ownership-config=${payload.recommendationCounts.ownershipConfig}`);
     console.log(`Routes: codex=${payload.routeCounts.byOwner.codex} claude=${payload.routeCounts.byOwner.claude} | strategies=${Object.entries(payload.routeCounts.byStrategy).map(([strategy, count])=>`${strategy}:${count}`).join(", ") || "-"}`);
     console.log(`Ownership conflicts: ${payload.ownershipConflicts} | Claim hotspots: ${payload.claimHotspots}`);
     console.log(`Routing ownership: codex=${payload.routingOwnership.codexPaths.join(", ") || "-"} | claude=${payload.routingOwnership.claudePaths.join(", ") || "-"}`);
@@ -431,6 +578,16 @@ async function commandRoute(cwd, args) {
         mode: allowAi && session ? "live" : "preview",
         route: routeDecision
     };
+    if (session) {
+        await recordEvent(paths, session.id, "route.previewed", {
+            prompt,
+            mode: payload.mode,
+            owner: routeDecision.owner,
+            strategy: routeDecision.strategy,
+            confidence: routeDecision.confidence,
+            claimedPaths: routeDecision.claimedPaths
+        });
+    }
     if (args.includes("--json")) {
         console.log(JSON.stringify(payload, null, 2));
         return;
@@ -484,6 +641,94 @@ async function commandRoutes(cwd, args) {
         }
     }
 }
+async function commandRecommend(cwd, args) {
+    const { paths } = await requireSession(cwd);
+    const rpcSnapshot = await tryRpcSnapshot(paths);
+    const session = rpcSnapshot?.session ?? await loadSessionRecord(paths);
+    const recommendations = buildOperatorRecommendations(session);
+    if (args.includes("--json")) {
+        console.log(JSON.stringify(recommendations, null, 2));
+        return;
+    }
+    if (recommendations.length === 0) {
+        console.log("No operator recommendations right now.");
+        return;
+    }
+    for (const recommendation of recommendations){
+        console.log(`${recommendation.id} | ${recommendation.kind} | ${recommendation.targetAgent ?? "-"}`);
+        console.log(`  title: ${recommendation.title}`);
+        console.log(`  detail: ${recommendation.detail}`);
+        console.log(`  command: ${recommendation.commandHint}`);
+    }
+}
+async function commandRecommendApply(cwd, args) {
+    const { paths } = await requireSession(cwd);
+    const rpcSnapshot = await tryRpcSnapshot(paths);
+    const session = rpcSnapshot?.session ?? await loadSessionRecord(paths);
+    const recommendationId = args.find((arg)=>!arg.startsWith("--"));
+    if (!recommendationId) {
+        throw new Error("A recommendation id is required. Example: kavi recommend-apply integration:src/ui/App.tsx");
+    }
+    const recommendation = buildOperatorRecommendations(session).find((item)=>item.id === recommendationId);
+    if (!recommendation) {
+        throw new Error(`Recommendation ${recommendationId} was not found.`);
+    }
+    if (recommendation.kind === "ownership-config") {
+        throw new Error(`Recommendation ${recommendation.id} is advisory only. Run "${recommendation.commandHint}" and update the config manually.`);
+    }
+    const owner = recommendation.targetAgent === "operator" || recommendation.targetAgent === null ? "codex" : recommendation.targetAgent;
+    const prompt = recommendation.kind === "integration" ? [
+        "Coordinate and resolve overlapping agent work before landing.",
+        recommendation.detail,
+        recommendation.filePath ? `Primary hotspot: ${recommendation.filePath}` : null
+    ].filter(Boolean).join("\n") : [
+        "Pick up ownership-aware handoff work from Kavi.",
+        recommendation.detail,
+        recommendation.filePath ? `Focus path: ${recommendation.filePath}` : null
+    ].filter(Boolean).join("\n");
+    const routeDecision = {
+        owner,
+        strategy: "manual",
+        confidence: 1,
+        reason: `Queued from Kavi recommendation ${recommendation.id}.`,
+        claimedPaths: recommendation.filePath ? [
+            recommendation.filePath
+        ] : [],
+        metadata: {
+            recommendationId: recommendation.id,
+            recommendationKind: recommendation.kind
+        }
+    };
+    if (rpcSnapshot) {
+        await rpcEnqueueTask(paths, {
+            owner: routeDecision.owner,
+            prompt,
+            routeReason: routeDecision.reason,
+            routeMetadata: routeDecision.metadata,
+            claimedPaths: routeDecision.claimedPaths,
+            routeStrategy: routeDecision.strategy,
+            routeConfidence: routeDecision.confidence
+        });
+    } else {
+        await appendCommand(paths, "enqueue", {
+            owner: routeDecision.owner,
+            prompt,
+            routeReason: routeDecision.reason,
+            routeMetadata: routeDecision.metadata,
+            claimedPaths: routeDecision.claimedPaths,
+            routeStrategy: routeDecision.strategy,
+            routeConfidence: routeDecision.confidence
+        });
+    }
+    await recordEvent(paths, session.id, "recommendation.applied", {
+        recommendationId: recommendation.id,
+        recommendationKind: recommendation.kind,
+        owner,
+        filePath: recommendation.filePath
+    });
+    await notifyOperatorSurface(paths, "recommendation.applied");
+    console.log(`Queued ${owner} task from recommendation ${recommendation.id}.`);
+}
 async function commandPaths(cwd, args) {
     const repoRoot = await findRepoRoot(cwd) ?? cwd;
     const paths = resolveAppPaths(repoRoot);
@@ -1113,6 +1358,11 @@ async function main() {
     const [command = "open", ...args] = process.argv.slice(2);
     const cwd = process.cwd();
     switch(command){
+        case "version":
+        case "--version":
+        case "-v":
+            await commandVersion(args);
+            break;
         case "help":
         case "--help":
         case "-h":
@@ -1124,6 +1374,9 @@ async function main() {
         case "doctor":
             await commandDoctor(cwd, args);
             break;
+        case "update":
+            await commandUpdate(cwd, args);
+            break;
         case "start":
             await commandStart(cwd, args);
             break;
@@ -1148,6 +1401,12 @@ async function main() {
         case "task":
             await commandTask(cwd, args);
             break;
+        case "recommend":
+            await commandRecommend(cwd, args);
+            break;
+        case "recommend-apply":
+            await commandRecommendApply(cwd, args);
+            break;
         case "tasks":
             await commandTasks(cwd, args);
             break;

package/dist/package-info.js

@@ -0,0 +1,15 @@
+import fs from "node:fs/promises";
+const packageJsonUrl = new URL("../package.json", import.meta.url);
+export async function loadPackageInfo() {
+    const raw = await fs.readFile(packageJsonUrl, "utf8");
+    const parsed = JSON.parse(raw);
+    return {
+        name: typeof parsed.name === "string" ? parsed.name : "kavi",
+        version: typeof parsed.version === "string" ? parsed.version : "0.0.0",
+        description: typeof parsed.description === "string" ? parsed.description : "",
+        homepage: typeof parsed.homepage === "string" ? parsed.homepage : null
+    };
+}
+
+
+//# sourceURL=package-info.ts

package/dist/process.js

@@ -44,6 +44,22 @@ export async function runCommand(command, args, options = {}) {
         });
     });
 }
+export async function runInteractiveCommand(command, args, options = {}) {
+    return await new Promise((resolve, reject)=>{
+        const child = spawn(command, args, {
+            ...options,
+            stdio: "inherit"
+        });
+        child.on("error", reject);
+        child.on("close", (code, signal)=>{
+            if (signal) {
+                reject(new Error(`${command} ${args.join(" ")} exited on signal ${signal}`));
+                return;
+            }
+            resolve(code ?? 1);
+        });
+    });
+}
 export function spawnDetachedNode(nodeExecutable, args, cwd) {
     const child = spawn(nodeExecutable, [
         "--experimental-strip-types",

package/dist/recommendations.js

@@ -0,0 +1,139 @@
+import { buildClaimHotspots } from "./decision-ledger.js";
+import { findOwnershipRuleConflicts } from "./ownership.js";
+function normalizePath(value) {
+    return value.trim().replaceAll("\\", "/").replace(/^\.\/+/, "").replace(/\/+$/, "");
+}
+function pathMatchesScope(scope, filePath) {
+    const normalizedScope = normalizePath(scope);
+    const normalizedFile = normalizePath(filePath);
+    return normalizedScope === normalizedFile || normalizedScope.startsWith(`${normalizedFile}/`) || normalizedFile.startsWith(`${normalizedScope}/`);
+}
+function otherAgent(agent) {
+    return agent === "codex" ? "claude" : "codex";
+}
+export function buildOperatorRecommendations(session) {
+    const recommendations = [];
+    const hotspots = buildClaimHotspots(session);
+    const ownershipConflicts = findOwnershipRuleConflicts(session.config);
+    const openReviewNotes = session.reviewNotes.filter((note)=>note.status === "open");
+    for (const hotspot of hotspots){
+        const relatedNotes = openReviewNotes.filter((note)=>pathMatchesScope(hotspot.path, note.filePath));
+        recommendations.push({
+            id: `integration:${hotspot.path}`,
+            kind: "integration",
+            title: `Coordinate overlapping work on ${hotspot.path}`,
+            detail: relatedNotes.length > 0 ? `Multiple agents are touching ${hotspot.path}, and ${relatedNotes.length} open review note(s) are still active there.` : `Multiple agents still claim overlapping work on ${hotspot.path}.`,
+            targetAgent: "codex",
+            filePath: hotspot.path,
+            taskIds: hotspot.taskIds,
+            reviewNoteIds: relatedNotes.map((note)=>note.id),
+            commandHint: `kavi recommend-apply integration:${hotspot.path}`,
+            metadata: {
+                hotspot
+            }
+        });
+    }
+    for (const note of openReviewNotes){
+        if (!note.assignee || note.assignee === "operator" || note.assignee === note.agent) {
+            continue;
+        }
+        recommendations.push({
+            id: `handoff:${note.id}:${note.assignee}`,
+            kind: "handoff",
+            title: `Hand off ${note.filePath} review work to ${note.assignee}`,
+            detail: `Review note ${note.id} is assigned to ${note.assignee} even though it originated from ${note.agent}.`,
+            targetAgent: note.assignee,
+            filePath: note.filePath,
+            taskIds: note.taskId ? [
+                note.taskId
+            ] : [],
+            reviewNoteIds: [
+                note.id
+            ],
+            commandHint: `kavi recommend-apply handoff:${note.id}:${note.assignee}`,
+            metadata: {
+                reviewNoteId: note.id,
+                sourceAgent: note.agent,
+                targetAgent: note.assignee
+            }
+        });
+    }
+    for (const hotspot of hotspots){
+        const hotspotAgents = new Set(hotspot.agents);
+        for (const note of openReviewNotes){
+            if (!pathMatchesScope(hotspot.path, note.filePath)) {
+                continue;
+            }
+            const targetAgent = note.assignee && note.assignee !== "operator" ? note.assignee : otherAgent(note.agent);
+            if (hotspotAgents.has(targetAgent)) {
+                recommendations.push({
+                    id: `handoff:${note.id}:${targetAgent}`,
+                    kind: "handoff",
+                    title: `Ask ${targetAgent} to address ${note.filePath}`,
+                    detail: `Active hotspot pressure on ${hotspot.path} overlaps review note ${note.id}.`,
+                    targetAgent,
+                    filePath: note.filePath,
+                    taskIds: note.taskId ? [
+                        note.taskId
+                    ] : hotspot.taskIds,
+                    reviewNoteIds: [
+                        note.id
+                    ],
+                    commandHint: `kavi recommend-apply handoff:${note.id}:${targetAgent}`,
+                    metadata: {
+                        hotspotPath: hotspot.path,
+                        reviewNoteId: note.id,
+                        sourceAgent: note.agent,
+                        targetAgent
+                    }
+                });
+            }
+        }
+    }
+    for (const conflict of ownershipConflicts){
+        recommendations.push({
+            id: `ownership:${conflict.leftPattern}:${conflict.rightPattern}`,
+            kind: "ownership-config",
+            title: "Resolve overlapping ownership rules",
+            detail: conflict.detail,
+            targetAgent: "operator",
+            filePath: null,
+            taskIds: [],
+            reviewNoteIds: [],
+            commandHint: "kavi doctor",
+            metadata: {
+                conflict
+            }
+        });
+    }
+    const deduped = new Map();
+    for (const recommendation of recommendations){
+        if (!deduped.has(recommendation.id)) {
+            deduped.set(recommendation.id, recommendation);
+        }
+    }
+    const priority = (kind)=>{
+        switch(kind){
+            case "integration":
+                return 0;
+            case "handoff":
+                return 1;
+            case "ownership-config":
+                return 2;
+            default:
+                return 3;
+        }
+    };
+    return [
+        ...deduped.values()
+    ].sort((left, right)=>{
+        const kindDelta = priority(left.kind) - priority(right.kind);
+        if (kindDelta !== 0) {
+            return kindDelta;
+        }
+        return left.title.localeCompare(right.title);
+    });
+}
+
+
+//# sourceURL=recommendations.ts

package/dist/tui.js

@@ -3,6 +3,7 @@ import readline from "node:readline";
 import process from "node:process";
 import { buildClaimHotspots } from "./decision-ledger.js";
 import { findOwnershipRuleConflicts } from "./ownership.js";
+import { buildOperatorRecommendations } from "./recommendations.js";
 import { cycleReviewAssignee, reviewNoteMatchesFilters } from "./reviews.js";
 import { extractPromptPathHints, previewRouteDecision, routeTask } from "./router.js";
 import { pingRpc, rpcAddReviewNote, rpcAddReviewReply, rpcEnqueueReviewFollowUp, readSnapshot, rpcEnqueueTask, rpcResolveApproval, rpcSetReviewNoteStatus, rpcShutdown, rpcTaskArtifact, rpcUpdateReviewNote, rpcWorktreeDiff, subscribeSnapshotRpc } from "./rpc.js";
@@ -670,6 +671,18 @@ function composerRoutePreview(snapshot, composer) {
         }
     };
 }
+function recommendationsForClaim(snapshot, claim) {
+    if (!snapshot || !claim) {
+        return [];
+    }
+    return buildOperatorRecommendations(snapshot.session).filter((recommendation)=>recommendation.taskIds.includes(claim.taskId) || claim.paths.length > 0 && recommendation.filePath !== null && claim.paths.some((filePath)=>recommendation.filePath === filePath || recommendation.filePath.startsWith(`${filePath}/`) || filePath.startsWith(`${recommendation.filePath}/`)));
+}
+function recommendationsForDecision(snapshot, decision) {
+    if (!snapshot || !decision) {
+        return [];
+    }
+    return buildOperatorRecommendations(snapshot.session).filter((recommendation)=>decision.taskId !== null && recommendation.taskIds.includes(decision.taskId) || typeof decision.metadata?.hotspot === "string" && recommendation.filePath === decision.metadata.hotspot);
+}
 function syncSelectedReviewNote(snapshot, ui) {
     const notes = reviewNotesForContext(snapshot, activeReviewContext(snapshot, ui), ui.reviewFilters);
     ui.selectedReviewNoteId = notes.some((note)=>note.id === ui.selectedReviewNoteId) ? ui.selectedReviewNoteId : notes[0]?.id ?? null;
@@ -969,6 +982,7 @@ function renderClaimInspector(snapshot, claim, width, height) {
     const innerWidth = Math.max(16, width - 2);
     const hotspots = snapshot ? buildClaimHotspots(snapshot.session) : [];
     const ownershipConflicts = snapshot ? findOwnershipRuleConflicts(snapshot.session.config) : [];
+    const recommendations = recommendationsForClaim(snapshot, claim);
     const lines = [];
     if (claim) {
         lines.push(...section("Claim", [
@@ -993,17 +1007,21 @@ function renderClaimInspector(snapshot, claim, width, height) {
     ]), ...section("Ownership Conflicts", ownershipConflicts.length > 0 ? ownershipConflicts.slice(0, 6).flatMap((conflict)=>wrapText(`- [${conflict.kind}] ${conflict.leftOwner}:${conflict.leftPattern} <> ${conflict.rightOwner}:${conflict.rightPattern}`, innerWidth)) : [
         "- none"
     ]));
+    lines.push(...section("Recommended Actions", recommendations.length > 0 ? recommendations.slice(0, 4).flatMap((recommendation)=>wrapText(`- ${recommendation.title} | ${recommendation.commandHint}`, innerWidth)) : [
+        "- none"
+    ]));
     return renderPanel("Inspector | Claim", width, height, lines, {
         focused: true
     });
 }
-function renderDecisionInspector(decision, width, height) {
+function renderDecisionInspector(snapshot, decision, width, height) {
     if (!decision) {
         return renderPanel("Inspector | Decision", width, height, [
             styleLine("No decision selected.", "muted")
         ]);
     }
     const innerWidth = Math.max(16, width - 2);
+    const recommendations = recommendationsForDecision(snapshot, decision);
     const lines = [
         ...section("Decision", [
             `Id: ${decision.id}`,
@@ -1014,7 +1032,10 @@ function renderDecisionInspector(decision, width, height) {
             `Summary: ${decision.summary}`,
             `Detail: ${decision.detail}`
         ].flatMap((line)=>wrapText(line, innerWidth))),
-        ...section("Metadata", formatJson(decision.metadata, innerWidth))
+        ...section("Metadata", formatJson(decision.metadata, innerWidth)),
+        ...section("Recommended Actions", recommendations.length > 0 ? recommendations.slice(0, 4).flatMap((recommendation)=>wrapText(`- ${recommendation.title} | ${recommendation.commandHint}`, innerWidth)) : [
+            "- none"
+        ])
     ];
     return renderPanel("Inspector | Decision", width, height, lines, {
         focused: true
@@ -1138,7 +1159,7 @@ function renderInspector(snapshot, ui, width, height) {
         case "claims":
             return renderClaimInspector(snapshot, selectedClaim(snapshot, ui), width, height);
         case "decisions":
-            return renderDecisionInspector(selectedDecision(snapshot, ui), width, height);
+            return renderDecisionInspector(snapshot, selectedDecision(snapshot, ui), width, height);
         case "events":
             return renderEventInspector(selectedEvent(snapshot, ui), width, height);
         case "messages":

package/dist/update.js

@@ -0,0 +1,36 @@
+export function buildUpdatePlan(packageName, options = {}) {
+    const targetSpecifier = options.version ?? options.tag ?? "latest";
+    return {
+        targetSpecifier,
+        installArgs: [
+            "install",
+            "-g",
+            `${packageName}@${targetSpecifier}`
+        ],
+        viewArgs: [
+            "view",
+            `${packageName}@${targetSpecifier}`,
+            "version",
+            "--json"
+        ]
+    };
+}
+export function parseRegistryVersion(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (typeof parsed === "string") {
+            return parsed;
+        }
+        if (Array.isArray(parsed) && typeof parsed[0] === "string") {
+            return parsed[0];
+        }
+    } catch  {}
+    return trimmed.replaceAll(/^"+|"+$/g, "");
+}
+
+
+//# sourceURL=update.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandipadk7/kavi",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Managed Codex + Claude collaboration TUI",
   "type": "module",
   "preferGlobal": true,