@holmes-lab/holmes-kit 0.19.5 → 0.20.0

package/dist/holmes/mcp/handlers/maintenance-evidence.js

@@ -0,0 +1,104 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMaintenanceEvidenceHandlers = createMaintenanceEvidenceHandlers;
+// @implements A-SPEC-603
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const maintenance_evidence_1 = require("../maintenance-evidence");
+const impact_gate_1 = require("../../guardrail/impact-gate");
+const root_1 = require("../../project/root");
+/** Raw handlers: the public facade attaches basis exactly once. */
+function createMaintenanceEvidenceHandlers(context) {
+    return {
+        // @implements A-SPEC-268
+        async maintenance_outcome(a) {
+            const foreign = context.foreignRootReason(a.root);
+            if (foreign)
+                throw context.refusal(foreign);
+            const root = context.projectRootOf(a.root);
+            return (0, maintenance_evidence_1.recordOutcome)(path.join(root, maintenance_evidence_1.EVIDENCE_DIR), a.digest, {
+                actualFiles: a.actualFiles,
+                actualSymbols: a.actualSymbols,
+                actualTests: a.actualTests,
+                actualClassification: a.actualClassification,
+            }, new Date().toISOString());
+        },
+        // @implements A-SPEC-277
+        async impact_gate_check(a) {
+            const foreign = context.foreignRootReason(a.root);
+            if (foreign)
+                throw context.refusal(foreign);
+            const root = context.projectRootOf(a.root);
+            let head = '';
+            try {
+                head = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+            }
+            catch { /* non-git */ }
+            let artifact = null;
+            if (a.digest) {
+                const file = path.join(root, maintenance_evidence_1.EVIDENCE_DIR, (0, maintenance_evidence_1.digestFilename)(a.digest));
+                // A digest naming an artifact this project never stored is NOT the same as no evidence at
+                // all — say which one happened rather than collapsing both into "refused".
+                if (!fs.existsSync(file))
+                    throw context.refusal(`이 프로젝트에 저장된 분석이 아닙니다: ${a.digest}`);
+                artifact = JSON.parse(fs.readFileSync(file, 'utf8'));
+            }
+            return (0, impact_gate_1.evaluateEditEvidence)({
+                target: a.target.replace(/\\/g, '/'),
+                artifact,
+                currentHead: head,
+                currentTargetDigest: context.fileDigestOf(root, a.target),
+            });
+        },
+        // @implements A-SPEC-268
+        async maintenance_calibration(a) {
+            const foreign = context.foreignRootReason(a.root);
+            if (foreign)
+                throw context.refusal(foreign);
+            const root = context.projectRootOf(a.root);
+            const read = (0, maintenance_evidence_1.readArtifacts)(path.join(root, maintenance_evidence_1.EVIDENCE_DIR));
+            // Corrupt and off-schema records travel WITH the score. A calibration that quietly dropped
+            // them would report a clean number over an unstated subset of the evidence.
+            return {
+                ...(0, maintenance_evidence_1.computeCalibration)(read.artifacts, { minSamples: a.minSamples }),
+                artifacts: read.artifacts.length,
+                unreadable: read.unreadable,
+                skippedSchema: read.skippedSchema,
+            };
+        },
+    };
+}

package/dist/holmes/mcp/handlers/operator-inspection.d.ts

@@ -0,0 +1,167 @@
+import { Spec } from '../../spec/spec-parser';
+import { SpecStore } from '../../spec/spec-store';
+import type { Approval } from '../../guardrail/risk-gate';
+export interface OperatorInspectionContext {
+    listSpecs(): Promise<Spec[]>;
+    readSpec: SpecStore['read'];
+    specsRoot(): unknown;
+    assertStoreReachable(tool: string, root: unknown): void;
+    resolver(specs: Spec[]): (id: string) => Spec | null;
+    resolveLedgerRoot(root?: string): {
+        ok: true;
+        root: string;
+    } | {
+        ok: false;
+        reason: string;
+    };
+    fetchJson(url: string): Promise<any>;
+    /** A-SPEC-642 — the shared approval channel and queue hint, for the reconciliation act. */
+    resolveHandlerApproval(root: string | undefined, approval: Approval | undefined, action: {
+        kind: string;
+        target: string;
+    }, now: string): {
+        approval: Approval;
+        source: 'env' | 'grant';
+        root?: string;
+    } | undefined;
+    refusalQueueHint(root: string | undefined, request: {
+        kind: string;
+        target: string;
+        why: string;
+    }): string;
+}
+export declare function createOperatorInspectionHandlers(context: OperatorInspectionContext): {
+    /**
+     * @implements A-SPEC-538.2
+     * Read-only: report a spec's approval/seal state — sealed?, approved_digest, each parent's seal
+     * state, and the concrete blockers still standing between it and approval — so a caller need not
+     * parse files to ask "what is the approval state right now". Reuses `sealOf` and `approvalBlockers`
+     * (the same predicates the code gate and spec_approve read) so the report cannot drift from the
+     * acts it describes. No writes, no ledger append.
+     */
+    approval_status(a: {
+        root?: string;
+        id: string;
+    }): Promise<{
+        ok: boolean;
+        reason: string;
+    } | {
+        graphPreview?: {
+            impact?: import("../../rtm/impact-advisory").ImpactAdvisory;
+            density?: Array<import("../../rtm/anchor-density").AnchorDensityFinding>;
+            cycles?: {
+                findings: Array<import("../../cpg/cycle-detect").CycleFinding>;
+                note: string;
+            };
+            architecture?: Array<import("../../cpg/arch-observe").ArchObservation>;
+            graphAsOf?: string;
+            graph?: {
+                status: "current" | "stale" | "unverified";
+                sourceCommit: string | null;
+                head: string | null;
+            };
+            unavailable?: "empty" | "unreadable";
+        } | undefined;
+        id: string;
+        type?: string;
+        status: string;
+        sealed: boolean;
+        approvedDigest?: string;
+        parents: import("../../spec/approval-status").ParentApproval[];
+        blockers: string[];
+        resealBlockers: string[];
+        ok: boolean;
+        reason?: undefined;
+    }>;
+    /**
+     * @implements A-SPEC-538.3
+     * Read-only: return the provenance ledger's events in time order (optionally narrowed to one
+     * spec) so the governance history — approved / unsealed / retired / review-needed … — is legible
+     * at a glance without reading raw JSONL. Reuses FileLedgerStore.loadAll(); the ordering/filtering/
+     * projection is the pure `timelineFrom`. No writes. An absent ledger is an empty history, not an
+     * error.
+     */
+    ledger_timeline(a: {
+        root?: string;
+        id?: string;
+    }): Promise<{
+        ok: boolean;
+        reason: string;
+        events?: undefined;
+    } | {
+        ok: boolean;
+        events: import("../../governance/ledger-timeline").TimelineEntry[];
+        reason?: undefined;
+    }>;
+    /**
+     * @implements A-SPEC-642
+     * The one exit from a merged cross-replica double-spend. Under out-of-band authority of kind
+     * `ledger-reconcile` for that nonce, append `nonce-double-spend-reconciled` on THIS replica's chain
+     * naming the nonce and every consuming event's hash; `verifyAll`, the Stop hook, baseline trust and
+     * the ledger-conflict refusals then clear. Nothing is erased: both consumptions stay in their
+     * chains, and a later consumption of the same nonce is a new, open double-spend. Refuses to extend
+     * a broken chain, because a reconciliation that itself cannot be verified lifts nothing.
+     */
+    ledger_reconcile(a: {
+        root?: string;
+        nonce: string;
+        rationale?: string;
+    }): Promise<{
+        ok: boolean;
+        reason: string;
+        reconciled?: undefined;
+        nonce?: undefined;
+        pending?: undefined;
+        code?: undefined;
+        events?: undefined;
+        remaining?: undefined;
+    } | {
+        ok: boolean;
+        reconciled: boolean;
+        nonce: string;
+        pending: string[];
+        reason: string;
+        code?: undefined;
+        events?: undefined;
+        remaining?: undefined;
+    } | {
+        ok: boolean;
+        code: string;
+        reason: string;
+        reconciled?: undefined;
+        nonce?: undefined;
+        pending?: undefined;
+        events?: undefined;
+        remaining?: undefined;
+    } | {
+        ok: boolean;
+        reconciled: boolean;
+        nonce: string;
+        events: {
+            replicaId: string | null;
+            seq: number;
+            hash: string;
+            ts: string;
+        }[];
+        remaining: string[];
+        reason?: undefined;
+        pending?: undefined;
+        code?: undefined;
+    }>;
+    rtm_dashboard(a: {
+        root?: string;
+        port?: number;
+    }): Promise<{
+        ok: boolean;
+        reason: string;
+        url?: undefined;
+        running?: undefined;
+        census?: undefined;
+    } | {
+        ok: boolean;
+        url: string;
+        running: boolean;
+        census: import("../../server/dashboard-launcher").DashboardCensus;
+        reason?: undefined;
+    }>;
+};

package/dist/holmes/mcp/handlers/operator-inspection.js

@@ -0,0 +1,284 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOperatorInspectionHandlers = createOperatorInspectionHandlers;
+// @implements A-SPEC-605, A-SPEC-605.1
+// @implements A-SPEC-642
+// @implements A-SPEC-631
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const spec_store_1 = require("../../spec/spec-store");
+const approval_status_1 = require("../../spec/approval-status");
+const ledger_store_1 = require("../../governance/ledger-store");
+const ledger_timeline_1 = require("../../governance/ledger-timeline");
+const provenance_ledger_1 = require("../../governance/provenance-ledger");
+const provenance_chain_1 = require("../../governance/provenance-chain");
+const approval_grants_1 = require("../../governance/approval-grants");
+function createOperatorInspectionHandlers(context) {
+    return {
+        /**
+         * @implements A-SPEC-538.2
+         * Read-only: report a spec's approval/seal state — sealed?, approved_digest, each parent's seal
+         * state, and the concrete blockers still standing between it and approval — so a caller need not
+         * parse files to ask "what is the approval state right now". Reuses `sealOf` and `approvalBlockers`
+         * (the same predicates the code gate and spec_approve read) so the report cannot drift from the
+         * acts it describes. No writes, no ledger append.
+         */
+        async approval_status(a) {
+            context.assertStoreReachable('approval_status', a.root); // @implements A-SPEC-419
+            const all = await context.listSpecs();
+            if (all.filter((s) => s.id === a.id).length > 1) {
+                return {
+                    ok: false,
+                    reason: `${a.id}이(가) 스토어에 두 번 이상 존재합니다 — 어느 사본의 상태를 물었는지 도구가 고를 수 없어 거부합니다.`,
+                };
+            }
+            const cur = await context.readSpec(a.id);
+            if (!cur) {
+                const dir = context.specsRoot();
+                const unreadable = typeof dir === 'string' ? (0, spec_store_1.unreadableSpecFiles)(dir) : [];
+                return { ok: false, reason: (0, spec_store_1.notFoundReason)(a.id, unreadable) };
+            }
+            // @implements A-SPEC-572.1
+            // The graph advisory, delivered at DESIGN time. Measured on our own work: A-SPEC-571.1's
+            // sealing advisory named the exact cluster three regressions then landed in — and by then
+            // the design was done. The calculation was never the gap; the delivery time was. So the
+            // read-only "what is blocking this right now" tool also answers "what will this scope leak,
+            // and where is it dense" — using the SAME functions spec_approve calls, so the preview can
+            // never disagree with the seal. Read-only stays read-only: no scan, no build, no ledger
+            // append (a query must not pollute the observation denominator), and every failure degrades
+            // to an absent field on an otherwise identical response.
+            let graphPreview;
+            try {
+                if (cur.spec.type === 'A-SPEC' && a.root) {
+                    const dbPath = path.join(a.root, '.ax', 'rtm.sqlite');
+                    // @implements A-SPEC-631 — non-mutating inspection of the live graph; an empty or
+                    // unreadable file is reported as such instead of previewing "no impact" from nothing.
+                    const { openPublishedGraph, headCommitOf } = require('../../rtm/graph-store');
+                    const { cleanSubprocessEnv } = require('../../project/root');
+                    const view = openPublishedGraph(dbPath, headCommitOf(a.root, cleanSubprocessEnv()));
+                    if (view.status === 'empty' || view.status === 'unreadable') {
+                        graphPreview = { unavailable: view.status, ...(view.graphAsOf ? { graphAsOf: view.graphAsOf } : {}) };
+                    }
+                    else if (view.graph !== null) {
+                        const { declaredImpactGap } = require('../../rtm/impact-advisory');
+                        const { anchorDensityFindings } = require('../../rtm/anchor-density');
+                        const { filesToTouch } = require('../../spec/compat-impact');
+                        const graph = view.graph;
+                        const condition = { status: view.status, sourceCommit: view.sourceCommit, head: view.head };
+                        try {
+                            const ftt = filesToTouch(cur.spec);
+                            const impact = declaredImpactGap(ftt, graph, (rel) => { try {
+                                return fs.readFileSync(path.join(a.root, rel), 'utf8');
+                            }
+                            catch {
+                                return null;
+                            } });
+                            const density = anchorDensityFindings(ftt, graph.implementsAnchorCounts());
+                            // @implements A-SPEC-574.2 — the computation lives in cycle-detect; this file holds
+                            // the wiring only (measured: 85 anchors here against a p90 of 7).
+                            const { cycleAdvisory, classifyEdgeByTarget, CYCLE_ADVISORY_NOTE } = require('../../cpg/cycle-detect');
+                            const readCache = new Map();
+                            const readSource = (rel) => {
+                                const hit = readCache.get(rel);
+                                if (hit !== undefined)
+                                    return hit;
+                                // A read failure degrades to the conservative kind rather than losing the finding.
+                                let text = '';
+                                try {
+                                    text = fs.readFileSync(path.join(a.root, rel), 'utf8');
+                                }
+                                catch {
+                                    text = '';
+                                }
+                                readCache.set(rel, text);
+                                return text;
+                            };
+                            const cycleFindings = cycleAdvisory(ftt, graph.importEdges().map((edge) => ({
+                                ...edge,
+                                kind: classifyEdgeByTarget(readSource(edge.from), edge.from, edge.to),
+                            })));
+                            // @implements A-SPEC-574.5 — the same import edges the cycle pass already read, plus
+                            // the parent-time symbol spans the graph already holds. No new scan, no new parse.
+                            const { architectureObservation } = require('../../cpg/arch-observe');
+                            const { TreeSitterTsParser } = require('../../cpg/language-parser');
+                            const { langForPath } = require('../../cpg/cpg-scanner');
+                            // Bounded to the DECLARED files, whose text is read once and used for both numbers.
+                            const archParser = new TreeSitterTsParser();
+                            const archText = new Map();
+                            const readArch = (f) => {
+                                if (!archText.has(f)) {
+                                    try {
+                                        archText.set(f, fs.readFileSync(path.join(a.root, f), 'utf8'));
+                                    }
+                                    catch {
+                                        archText.set(f, null);
+                                    }
+                                }
+                                return archText.get(f) ?? null;
+                            };
+                            const spans = new Map(ftt.map((f) => {
+                                const text = readArch(f);
+                                if (text === null)
+                                    return [f, []];
+                                try {
+                                    return [f, archParser.extractSymbols(text, langForPath(f))
+                                            .filter((sy) => sy.kind !== 'class')
+                                            .map((sy) => ({ startLine: sy.startLine, endLine: sy.endLine }))];
+                                }
+                                catch {
+                                    return [f, []];
+                                }
+                            }));
+                            const arch = architectureObservation(ftt, spans, graph.importEdges(), (f) => { const t = readArch(f); return t === null ? null : t.split('\n').length; });
+                            if (impact || density.length > 0 || cycleFindings.length > 0 || arch.length > 0) {
+                                const graphAsOf = (() => { try {
+                                    return fs.statSync(dbPath).mtime.toISOString();
+                                }
+                                catch {
+                                    return undefined;
+                                } })();
+                                graphPreview = {
+                                    graph: condition,
+                                    ...(impact ? { impact } : {}),
+                                    ...(density.length > 0 ? { density } : {}),
+                                    ...(cycleFindings.length > 0
+                                        ? { cycles: { findings: cycleFindings, note: CYCLE_ADVISORY_NOTE } } : {}),
+                                    ...(arch.length > 0 ? { architecture: arch } : {}),
+                                    ...(graphAsOf ? { graphAsOf } : {}),
+                                };
+                            }
+                        }
+                        finally {
+                            graph.close();
+                        }
+                    }
+                }
+            }
+            catch {
+                graphPreview = undefined;
+            }
+            return { ok: true, ...(0, approval_status_1.describeApproval)(cur.spec, context.resolver(all)), ...(graphPreview ? { graphPreview } : {}) };
+        },
+        /**
+         * @implements A-SPEC-538.3
+         * Read-only: return the provenance ledger's events in time order (optionally narrowed to one
+         * spec) so the governance history — approved / unsealed / retired / review-needed … — is legible
+         * at a glance without reading raw JSONL. Reuses FileLedgerStore.loadAll(); the ordering/filtering/
+         * projection is the pure `timelineFrom`. No writes. An absent ledger is an empty history, not an
+         * error.
+         */
+        async ledger_timeline(a) {
+            const dest = context.resolveLedgerRoot(a.root);
+            if (!dest.ok)
+                return { ok: false, reason: dest.reason };
+            const dir = path.join(dest.root, '.ax', 'ledger');
+            const events = fs.existsSync(dir) ? new ledger_store_1.FileLedgerStore(dir).loadAll() : [];
+            return { ok: true, events: (0, ledger_timeline_1.timelineFrom)(events, a.id) };
+        },
+        /**
+         * @implements A-SPEC-642
+         * The one exit from a merged cross-replica double-spend. Under out-of-band authority of kind
+         * `ledger-reconcile` for that nonce, append `nonce-double-spend-reconciled` on THIS replica's chain
+         * naming the nonce and every consuming event's hash; `verifyAll`, the Stop hook, baseline trust and
+         * the ledger-conflict refusals then clear. Nothing is erased: both consumptions stay in their
+         * chains, and a later consumption of the same nonce is a new, open double-spend. Refuses to extend
+         * a broken chain, because a reconciliation that itself cannot be verified lifts nothing.
+         */
+        async ledger_reconcile(a) {
+            const dest = context.resolveLedgerRoot(a.root);
+            if (!dest.ok)
+                return { ok: false, reason: dest.reason };
+            const nonce = typeof a.nonce === 'string' ? a.nonce.trim() : '';
+            if (!nonce)
+                return { ok: false, reason: 'ledger_reconcile: `nonce` is required — the nonce input exactly as verifyAll / doubleSpends names it (usually "nonce:<12 hex>").' };
+            const dir = path.join(dest.root, '.ax', 'ledger');
+            const store = new ledger_store_1.FileLedgerStore(dir);
+            const pending = store.doubleSpends();
+            const match = pending.find((d) => d.nonce === nonce);
+            if (!match) {
+                return { ok: true, reconciled: false, nonce, pending: pending.map((d) => d.nonce),
+                    reason: pending.length === 0 ? 'the merged ledger holds no unreconciled double-spend' : `${nonce} is not an unreconciled double-spend; pending: ${pending.map((d) => d.nonce).join(', ')}` };
+            }
+            const replicas = [...new Set(match.events.map((e) => e.replicaId ?? 'legacy'))];
+            let approval;
+            try {
+                approval = process.env.HOLMES_APPROVAL ? JSON.parse(process.env.HOLMES_APPROVAL) : undefined;
+            }
+            catch {
+                approval = undefined;
+            }
+            const now = new Date().toISOString();
+            const resolved = context.resolveHandlerApproval(dest.root, approval, { kind: 'ledger-reconcile', target: nonce }, now);
+            if (!resolved) {
+                return { ok: false, code: 'approval-required',
+                    reason: `ledger_reconcile requires an out-of-band HOLMES_APPROVAL (or grant) that COVERS kind "ledger-reconcile" for ${nonce} — accepting that ${match.events.length} consumptions on ${replicas.join(', ')} were intended is an operator decision, not the agent's.`
+                        + context.refusalQueueHint(dest.root, { kind: 'ledger-reconcile', target: nonce, why: `Reconcile the cross-replica double-spend of ${nonce} (${match.events.length} consumptions on ${replicas.join(', ')})` }) };
+            }
+            const chainBreaks = store.verifyAll().broken.filter((b) => b.kind === 'chain');
+            if (chainBreaks.length > 0) {
+                return { ok: false, code: 'audit-conflict', reason: 'ledger_reconcile cannot extend a broken chain: ' + chainBreaks.map((b) => `${b.replicaId ?? 'legacy'}: ${b.detail ?? 'broken'}`).join('; ') };
+            }
+            store.append({
+                ts: now, actor: resolved.approval.actor, kind: provenance_ledger_1.DOUBLE_SPEND_RECONCILED,
+                summary: `reconciled cross-replica double-spend of ${nonce}: ${match.events.length} consumptions on ${replicas.join(', ')}`.slice(0, 200),
+                inputs: [nonce, ...match.events.map((e) => 'event:' + e.hash), ...replicas.map((r) => 'replica:' + r)],
+                rationale: typeof a.rationale === 'string' && a.rationale.trim() !== '' ? a.rationale.trim() : resolved.approval.rationale,
+                authorization: (0, provenance_chain_1.authorizationRef)(resolved.approval.actor, resolved.approval.token),
+            });
+            if (resolved.source === 'grant' && resolved.approval.nonce)
+                (0, approval_grants_1.consumeGrantFile)(resolved.root ?? dest.root, String(resolved.approval.nonce));
+            return { ok: true, reconciled: true, nonce, events: match.events, remaining: store.doubleSpends().map((d) => d.nonce) };
+        },
+        // @implements A-SPEC-545.3 — "show me the RTM dashboard" launches (idempotently) the server the
+        // agent would otherwise start by hand, and returns its URL plus an honesty census of what it shows.
+        async rtm_dashboard(a) {
+            const dest = context.resolveLedgerRoot(a.root);
+            if (!dest.ok)
+                return { ok: false, reason: dest.reason };
+            try {
+                const { startDashboardServer } = await Promise.resolve().then(() => __importStar(require('../../server/dashboard')));
+                const { ensureDashboard, dashboardCensus } = await Promise.resolve().then(() => __importStar(require('../../server/dashboard-launcher')));
+                const launch = await ensureDashboard(dest.root, a.port, (opts) => startDashboardServer(opts));
+                const rtm = await context.fetchJson(`${launch.url}/api/rtm`);
+                const heatmap = await context.fetchJson(`${launch.url}/api/rtm/heatmap`);
+                return { ok: true, url: launch.url, running: launch.running, census: dashboardCensus(rtm, heatmap) };
+            }
+            catch (err) {
+                return { ok: false, reason: `대시보드 기동 실패: ${err?.message ?? String(err)}` };
+            }
+        },
+    };
+}

package/dist/holmes/mcp/handlers/phase-queries.d.ts

@@ -0,0 +1,34 @@
+import { Spec } from '../../spec/spec-parser';
+import { Action } from '../../guardrail/phase';
+export interface PhaseQueryContext {
+    listSpecs(): Promise<Spec[]>;
+    boundSpecsRoot(): string | undefined;
+    projectRootOf(root: string): string;
+}
+export declare function createPhaseQueryHandlers(context: PhaseQueryContext): {
+    phase_status(a: {
+        root?: string;
+    }): Promise<{
+        ok: boolean;
+        reason: string;
+        specs?: undefined;
+        note?: undefined;
+    } | {
+        specs: {
+            id: string;
+            type: import("../../spec/spec-types").SpecType;
+            status: "draft" | "review" | "approved" | "outdated";
+        }[];
+        note: string;
+        ok?: undefined;
+        reason?: undefined;
+    }>;
+    phase_check(a: {
+        action?: Action;
+        target: string;
+        targetAspecId?: string;
+    }): Promise<import("../../guardrail/phase").CheckResult | {
+        decision: string;
+        note: string;
+    }>;
+};