muonroi-cli 1.8.4 → 1.9.0

package/dist/src/tools/git-safety.js

@@ -24,6 +24,7 @@
  *
  * Override the push gate with `MUONROI_ALLOW_PUSH_ON_RED=1`.
  */
+import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { isVerificationCommand } from "../orchestrator/tool-args-hash.js";
@@ -216,6 +217,173 @@ export function checkSensitiveStaging(cwd) {
         "To bypass this gate (not recommended), set MUONROI_ALLOW_BROAD_STAGE=1.";
     return { blocked: true, sensitive, message };
 }
+// ── Destructive-op guard (2026-07-12) ──────────────────────────────────────
+//
+// Motivation: an autonomous /ideal plan-adherence fix sub-agent ran
+// `git checkout -- <files>` + committed the result, silently discarding the
+// user's UNCOMMITTED, unrelated working-tree changes (a whole set of harness
+// fixes). No existing guard caught it. This guard classifies commands that
+// irreversibly discard uncommitted work and blocks them PRE-EXECUTION when
+// there is actually work at risk. Routed as the `destructive-revert` safety
+// kind: interactive → askcard (allow-once/block, never auto-allow even in
+// yolo); headless/autonomous → hard-block. Escape hatch:
+// MUONROI_ALLOW_DESTRUCTIVE_REVERT=1 (user-set, logged like the other gates).
+// `git checkout … -- ` (discard paths) OR `git checkout .` (discard all).
+const CHECKOUT_DISCARD_RE = /\bgit\b[^|&;\n]*[ \t]checkout\b(?:[^|&;\n]*[ \t]--(?:[ \t]|$)|[ \t]+\.(?=[ \t]|$))/;
+// `git restore …` discards the working tree by default. `git restore --staged`
+// WITHOUT `--worktree`/`-W` only unstages (non-destructive) — exempt that.
+const RESTORE_RE = /\bgit\b[^|&;\n]*[ \t]restore\b/;
+const RESTORE_STAGED_RE = /[ \t]--staged\b/;
+const RESTORE_WORKTREE_RE = /[ \t](?:--worktree\b|-[a-z]*W)/;
+// `git reset --hard` throws away all uncommitted changes.
+const RESET_HARD_RE = /\bgit\b[^|&;\n]*[ \t]reset\b[^|&;\n]*[ \t]--hard\b/;
+// `git clean -f[d][x]` deletes untracked files.
+const CLEAN_FORCE_RE = /\bgit\b[^|&;\n]*[ \t]clean\b[^|&;\n]*[ \t]-[a-eg-wyz]*f/;
+// `git stash drop` / `git stash clear` destroy stashed work.
+const STASH_DROP_RE = /\bgit\b[^|&;\n]*[ \t]stash[ \t]+(?:drop|clear)\b/;
+// `rm` (not rmdir) — targets checked against git tracking below.
+const RM_RE = /(?:^|[|&;\n]|\s)rm\b(?!dir)/;
+export function analyzeDestructiveGit(command) {
+    const c = stripQuoted(command);
+    if (RESET_HARD_RE.test(c))
+        return { kind: "reset-hard", untrackedRisk: false };
+    if (CHECKOUT_DISCARD_RE.test(c))
+        return { kind: "checkout-discard", untrackedRisk: false };
+    if (RESTORE_RE.test(c)) {
+        const stagedOnly = RESTORE_STAGED_RE.test(c) && !RESTORE_WORKTREE_RE.test(c);
+        if (!stagedOnly)
+            return { kind: "restore", untrackedRisk: false };
+    }
+    if (CLEAN_FORCE_RE.test(c))
+        return { kind: "clean", untrackedRisk: true };
+    if (STASH_DROP_RE.test(c))
+        return { kind: "stash-drop", untrackedRisk: false };
+    return { kind: null, untrackedRisk: false };
+}
+function git(cwd, args) {
+    try {
+        const r = spawnSync("git", args, { cwd, encoding: "utf8", timeout: 8000, maxBuffer: 8 * 1024 * 1024 });
+        return (r.stdout ?? "").trim();
+    }
+    catch {
+        return "";
+    }
+}
+/** Working-tree paths that a destructive command would discard (best-effort). */
+function atRiskPaths(cwd, untrackedRisk) {
+    // NOTE: read raw stdout — do NOT trim the whole output. Porcelain v1 lines
+    // are "XY<space>PATH" where XY is 2 chars; a global trim would eat the leading
+    // space of a " M file" line and shift the path parse by one character.
+    let raw;
+    try {
+        const r = spawnSync("git", ["status", "--porcelain"], {
+            cwd,
+            encoding: "utf8",
+            timeout: 8000,
+            maxBuffer: 8 * 1024 * 1024,
+        });
+        raw = r.stdout ?? "";
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (line.length < 4)
+            continue;
+        const xy = line.slice(0, 2);
+        const file = line.slice(3).trim();
+        const isUntracked = xy === "??";
+        if (untrackedRisk ? isUntracked : !isUntracked && xy !== "!!")
+            out.push(file);
+    }
+    return out;
+}
+/** Extract rm target tokens (non-flag args) from a single-clause rm command. */
+function rmTargets(command) {
+    const c = stripQuoted(command);
+    const m = c.match(/(?:^|[|&;\n]|\s)rm\b(?!dir)([^|&;\n]*)/);
+    if (!m)
+        return [];
+    return m[1]
+        .split(/\s+/)
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0 && !t.startsWith("-") && t !== '""' && t !== "''");
+}
+/** rm targets that are git-tracked (file directly, or a dir containing tracked files). */
+function rmTrackedTargets(cwd, command) {
+    const targets = rmTargets(command);
+    const tracked = [];
+    for (const t of targets) {
+        // Tracked file?
+        const asFile = spawnSync("git", ["ls-files", "--error-unmatch", t], {
+            cwd,
+            encoding: "utf8",
+            timeout: 6000,
+        });
+        if (asFile.status === 0) {
+            tracked.push(t);
+            continue;
+        }
+        // Directory containing tracked files?
+        const underDir = git(cwd, ["ls-files", "--", t]);
+        if (underDir)
+            tracked.push(t);
+    }
+    return tracked;
+}
+/**
+ * Pre-execution guard: block a working-tree-destroying command when it would
+ * actually discard uncommitted work. Returns blocked=false (no message) when
+ * the command is non-destructive, when nothing is at risk, or when the user set
+ * the escape hatch. Deterministic + cheap (a couple of git plumbing calls).
+ */
+export function checkDestructiveOp(command, cwd) {
+    if (process.env.MUONROI_ALLOW_DESTRUCTIVE_REVERT === "1") {
+        return { blocked: false, kind: null, message: "" };
+    }
+    const shape = analyzeDestructiveGit(command);
+    if (shape.kind) {
+        let atRisk;
+        if (shape.kind === "stash-drop") {
+            atRisk = git(cwd, ["stash", "list"]).split("\n").filter(Boolean);
+        }
+        else {
+            atRisk = atRiskPaths(cwd, shape.untrackedRisk);
+        }
+        if (atRisk.length === 0)
+            return { blocked: false, kind: shape.kind, message: "" };
+        return { blocked: true, kind: shape.kind, message: destructiveMessage(shape.kind, atRisk) };
+    }
+    if (RM_RE.test(stripQuoted(command))) {
+        const tracked = rmTrackedTargets(cwd, command);
+        if (tracked.length > 0) {
+            return { blocked: true, kind: "rm-tracked", message: destructiveMessage("rm-tracked", tracked) };
+        }
+    }
+    return { blocked: false, kind: null, message: "" };
+}
+function destructiveMessage(kind, items) {
+    const list = items
+        .slice(0, 30)
+        .map((n) => `  • ${n}`)
+        .join("\n");
+    const more = items.length > 30 ? `\n  … and ${items.length - 30} more` : "";
+    const verb = {
+        "checkout-discard": "`git checkout` discarding working-tree changes",
+        restore: "`git restore` discarding working-tree changes",
+        "reset-hard": "`git reset --hard` discarding ALL uncommitted changes",
+        clean: "`git clean` deleting untracked files",
+        "stash-drop": "`git stash drop/clear` destroying stashed work",
+        "rm-tracked": "`rm` deleting git-tracked file(s)",
+    };
+    return (`BLOCKED: refusing ${verb[kind]} — this irreversibly discards uncommitted work:\n` +
+        `${list}${more}\n\n` +
+        "These changes are NOT committed and cannot be recovered once discarded. If you did " +
+        "not intend to destroy them, leave them alone (they may be the user's unrelated work). " +
+        "To keep them, `git add` + `git commit` (or `git stash`) FIRST, then retry. To bypass " +
+        "this guard for a genuine, intentional discard, set MUONROI_ALLOW_DESTRUCTIVE_REVERT=1.");
+}
 /**
  * @deprecated Use checkSensitiveStaging() for hard-blocking.
  * Kept for call sites that emit a trailing warning (non-broad-stage contexts).

package/dist/src/tools/native-tools.d.ts

@@ -20,7 +20,7 @@
  */
 import { type ToolSet } from "ai";
 /** The native tool names this module registers — used by the MCP-twin dedup. */
-export declare const NATIVE_MUONROI_TOOL_NAMES: readonly ["ee_health", "ee_feedback", "ee_write", "usage_forensics", "lsp_query", "setup_guide", "selfverify_start", "selfverify_status", "selfverify_result", "selfverify_list", "selfverify_cancel"];
+export declare const NATIVE_MUONROI_TOOL_NAMES: readonly ["ee_health", "ee_feedback", "ee_write", "usage_forensics", "lsp_query", "wait_for_diagnostics", "impact_of_change", "lsp_mutation_preview", "setup_guide", "selfverify_start", "selfverify_status", "selfverify_result", "selfverify_list", "selfverify_cancel"];
 export interface NativeToolOpts {
     /** Workspace cwd for lsp_query. Defaults to process.cwd(). */
     cwd?: string;

package/dist/src/tools/native-tools.js

@@ -19,9 +19,22 @@
  * identical across the two surfaces.
  */
 import { dynamicTool, jsonSchema } from "ai";
-import { LSP_TOOL_OPERATIONS } from "../lsp/types.js";
+import { LSP_TOOL_OPERATIONS, LspError } from "../lsp/types.js";
 import { getSelfVerifyJobManager } from "../mcp/self-verify-runner.js";
 import { SETUP_GUIDE_TEXT } from "../mcp/setup-guide-text.js";
+/** Map a thrown error to the LspError tagged-union shape. */
+function mapLspError(e) {
+    if (e instanceof LspError)
+        return e;
+    if (e && typeof e === "object" && "kind" in e && "message" in e) {
+        return new LspError(e.kind, e.message);
+    }
+    return new LspError("unknown", e instanceof Error ? e.message : String(e));
+}
+function lspErrLine(e) {
+    const err = mapLspError(e);
+    return JSON.stringify({ error: err.kind, message: err.message });
+}
 /** The native tool names this module registers — used by the MCP-twin dedup. */
 export const NATIVE_MUONROI_TOOL_NAMES = [
     "ee_health",
@@ -29,6 +42,9 @@ export const NATIVE_MUONROI_TOOL_NAMES = [
     "ee_write",
     "usage_forensics",
     "lsp_query",
+    "wait_for_diagnostics",
+    "impact_of_change",
+    "lsp_mutation_preview",
     "setup_guide",
     "selfverify_start",
     "selfverify_status",
@@ -86,6 +102,10 @@ export function registerNativeMuonroiTools(tools, opts = {}) {
                 const { feedbackEE } = await import("../ee/search.js");
                 const { sessionRecallLedger } = await import("../ee/recall-ledger.js");
                 const result = await feedbackEE(id, collection, verdict, reason);
+                // A queued result (brain unreachable → durably enqueued) counts as success:
+                // the agent has discharged its rating, so clear the ledger regardless. This
+                // is what stops the mandatory-rating gate from looping while the brain is
+                // down — the previous "return early, don't clear" path re-nagged every turn.
                 if (!result.ok)
                     return errLine("feedback_failed", result.error ?? "feedback POST failed");
                 const clearedId = result.resolvedId ?? id;
@@ -96,6 +116,7 @@ export function registerNativeMuonroiTools(tools, opts = {}) {
                     id: clearedId,
                     verdict: result.verdict,
                     ...(result.reason ? { reason: result.reason } : {}),
+                    ...(result.queued ? { queued: true } : {}),
                     pendingRemaining: sessionRecallLedger.pendingCount(),
                 });
             }
@@ -214,6 +235,65 @@ export function registerNativeMuonroiTools(tools, opts = {}) {
             }
         },
     });
+    // ── Sprint 1: readiness contract tools ─────────────────────────────────────
+    tools.wait_for_diagnostics = dynamicTool({
+        description: "Wait for LSP diagnostics on a file, with timeout clamping (default 1500ms, max 5000ms). " +
+            "Returns { diagnostics: LspDiagnostic[], lspStatus: 'ok'|'partial'|'unavailable', clean: boolean, metadata: { tokenBudgetUsed } }. " +
+            "clean=true means zero error-level diagnostics. Grep fallback is allowed when lspStatus !== 'ok'.",
+        inputSchema: jsonSchema({
+            type: "object",
+            properties: {
+                filePath: { type: "string", description: "Absolute or workspace-relative path" },
+                timeout: { type: "number", description: "Timeout in ms (default 1500, max 5000)", optional: true },
+            },
+            required: ["filePath"],
+        }),
+        execute: async (input) => {
+            const cwd = opts.cwd ?? process.cwd();
+            try {
+                const { getOrCreateManager } = await import("../lsp/runtime.js");
+                return json(await getOrCreateManager(cwd).waitForDiagnostics(input.filePath, input.timeout ?? 1500));
+            }
+            catch (e) {
+                return lspErrLine(e);
+            }
+        },
+    });
+    tools.impact_of_change = dynamicTool({
+        description: "Analyse impact of a change: returns { references, diagnostics, referencesComplete, safeToRename, clean, " +
+            "suggestedGuard, degraded, lspStatus, metadata }. Safe for use as lsp-before-grep gate: grep fallback is " +
+            "allowed when lspStatus !== 'ok'; safeToRename is true only when refs are complete and the union is clean.",
+        inputSchema: jsonSchema({
+            type: "object",
+            properties: {
+                filePath: { type: "string", description: "Absolute or workspace-relative path" },
+                query: { type: "string", description: "Optional symbol query", optional: true },
+            },
+            required: ["filePath"],
+        }),
+        execute: async (input) => {
+            const cwd = opts.cwd ?? process.cwd();
+            const { getOrCreateManager } = await import("../lsp/runtime.js");
+            return json(await getOrCreateManager(cwd).impactOfChange(input.filePath, input.query));
+        },
+    });
+    tools.lsp_mutation_preview = dynamicTool({
+        description: "Preview a mutation (stub — no real edits). Returns { op: 'allowlist', dryRunResult: { proposedEdits: [], " +
+            "tokenEstimate: 0 }, schemaVersion: '1.0' }. MUTATION_TOOLS gating applies; no apply path in Sprint 1.",
+        inputSchema: jsonSchema({
+            type: "object",
+            properties: {
+                filePath: { type: "string", description: "File path" },
+                change: { type: "string", description: "Change specification (stub)" },
+            },
+            required: ["filePath", "change"],
+        }),
+        execute: async (input) => {
+            const cwd = opts.cwd ?? process.cwd();
+            const { getOrCreateManager } = await import("../lsp/runtime.js");
+            return json(await getOrCreateManager(cwd).lspMutationPreview(input.filePath, input.change));
+        },
+    });
     // ── Onboarding: setup_guide ───────────────────────────────────────────────
     tools.setup_guide = dynamicTool({
         description: "Returns the up-to-date setup / install / first-run / MCP wiring / verify guide for muonroi-cli. Call this " +

package/dist/src/tools/registry.d.ts

@@ -6,6 +6,7 @@
  * is sent to the API for all providers (including DeepSeek, Gemini, etc.).
  */
 import { type ToolSet } from "ai";
+import type { AskUserAskInfo } from "../orchestrator/ask-user.js";
 import type { AgentMode, TaskRequest, ToolResult } from "../types/index.js";
 import type { BashTool } from "./bash.js";
 interface ToolRegistryOpts {
@@ -15,6 +16,8 @@ interface ToolRegistryOpts {
     listDelegations?: () => Promise<ToolResult>;
     killDelegation?: (id: string) => Promise<ToolResult>;
     modelId?: string;
+    /** L1 model depth tier — gates gsd_plan_review registration. */
+    depthTier?: "quick" | "standard" | "heavy";
     consultParentSession?: (question: string) => Promise<string>;
     /**
      * When false, the 3 vision-proxy tools (analyze_image, ask_vision_proxy,
@@ -31,6 +34,23 @@ interface ToolRegistryOpts {
      * isolated state (legacy per-closure behaviour).
      */
     sessionId?: string;
+    runDebate?: (topic: string) => Promise<string>;
+    /**
+     * When true, the `convene_council` tool is registered so the agent can
+     * convene the multi-model council on demand mid-turn. Set by the tool-engine
+     * only when the council is actually usable for this session
+     * (`configuredRoleCount >= getAutoCouncilMinRoles()`); omitted/false → the
+     * tool is absent so the model never calls a council that cannot convene.
+     */
+    councilConfigured?: boolean;
+    /**
+     * When provided, the `ask_user` tool is registered so the agent can ask the
+     * human a question mid-turn and receive their answer AS the tool result. The
+     * handler blocks until the human responds (or dismisses). Omitted (headless
+     * with no answerer) → the tool is absent, so the model never calls a card
+     * that can never be answered.
+     */
+    askUser?: (info: AskUserAskInfo) => Promise<string>;
 }
 /**
  * Phase 4R: session-scoped bash repeat detector state.