@iris-eval/mcp-server 0.5.0 → 0.6.0

package/dist/self-test.js

@@ -11,10 +11,20 @@
  *
  * Isolation is the load-bearing property. The diagnostic creates its own
  * scratch IRIS_HOME and scrubs every IRIS_* env var that feeds
- * loadConfig(), so it NEVER opens (or migrates!) the user's real iris.db,
- * never reads their config.json, and never honours an IRIS_API_KEY that
- * would 401 its own probes. The scratch home is removed and the env
- * restored before returning — pass or fail.
+ * loadConfig(), so it never MIGRATES or writes rows into the user's real
+ * iris.db, never reads their config.json, and never honours an
+ * IRIS_API_KEY that would 401 its own probes. The scratch home is removed
+ * and the env restored before returning — pass or fail.
+ *
+ * Isolation is not the same as ignorance, though. The first check runs
+ * BEFORE the scrub, against the CONFIGURED home: it creates the directory
+ * the server would create, proves it can write there, and — when the real
+ * database already exists — opens it and takes (then releases) a write
+ * lock without changing a byte. #371: the diagnostic used to print PASS
+ * against an IRIS_HOME the server could not write, because every check
+ * ran in the temp home; the real server then died on startup with a raw
+ * EPERM stack. A diagnostic that cannot fail the way the product fails is
+ * not a diagnostic.
  *
  * Budget: everything is in-process or loopback. No LLM calls, no network
  * beyond 127.0.0.1, and the whole sequence completes in well under the
@@ -23,11 +33,13 @@
  * Exit contract: 0 = every check passed, 1 = any check failed. index.ts
  * runs this BEFORE loadConfig() so the normal boot path never executes.
  */
-import { mkdtempSync, rmSync } from 'node:fs';
+import { existsSync, mkdtempSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { randomBytes } from 'node:crypto';
 import { request as httpRequest } from 'node:http';
-import { loadConfig } from './config/index.js';
+import Database from 'better-sqlite3';
+import { ensureIrisDirectory, loadConfig } from './config/index.js';
 import { PKG_VERSION } from './config/defaults.js';
 import { createStorage } from './storage/index.js';
 import { createDashboardServer } from './dashboard/server.js';
@@ -44,6 +56,7 @@ const CROSS = '✗';
  * files, per the usual drift rule.
  */
 export const SELF_TEST_STEPS = {
+    configuredHome: 'configured IRIS_HOME is writable',
     tempHome: 'create isolated temp home',
     storage: 'initialize storage',
     trace: 'log a trace',
@@ -114,16 +127,77 @@ function probe(port, path, headers = {}) {
     });
 }
 const stdoutLine = (line) => process.stdout.write(`${line}\n`);
+function errorCode(err) {
+    const code = err?.code;
+    return typeof code === 'string' ? code : err instanceof Error ? err.message : String(err);
+}
+/**
+ * The configured-home probe (#371). Exercises the exact calls the real
+ * server makes at startup, in order: create IRIS_HOME (same helper and
+ * mode as loadConfig), create the database directory when IRIS_DB_PATH
+ * points elsewhere, write-and-unlink a probe file in each, and — only if
+ * the real database already exists — open it and take a write lock
+ * (BEGIN IMMEDIATE … ROLLBACK), which fails on a read-only file or a
+ * non-database exactly as the first INSERT would, without migrating or
+ * changing anything. A missing database is not created: the server
+ * creates it on first run, and the writable-directory probe is what
+ * proves that it can.
+ */
+export function probeConfiguredHome(home, dbPath) {
+    ensureIrisDirectory(home, 'IRIS_HOME');
+    probeWritable(home, 'IRIS_HOME');
+    const dbDir = dirname(dbPath);
+    if (dbDir !== home) {
+        ensureIrisDirectory(dbDir, 'the database directory (IRIS_DB_PATH / --db-path)');
+        probeWritable(dbDir, 'the database directory');
+    }
+    if (!existsSync(dbPath)) {
+        return `${home} (database ${dbPath} will be created on first run)`;
+    }
+    let db;
+    try {
+        db = new Database(dbPath, { fileMustExist: true });
+        db.exec('BEGIN IMMEDIATE');
+        db.exec('ROLLBACK');
+    }
+    catch (err) {
+        throw new Error(`database "${dbPath}" exists but cannot be opened for writing (${errorCode(err)}) — the server would fail ` +
+            'at startup with the same error. Fix the file permissions, or point IRIS_DB_PATH / --db-path at a writable location.');
+    }
+    finally {
+        db?.close();
+    }
+    return `${home} (database ${dbPath} opens for writing)`;
+}
+function probeWritable(dir, what) {
+    const probeFile = join(dir, `.iris-self-test-${randomBytes(4).toString('hex')}`);
+    try {
+        writeFileSync(probeFile, 'iris self-test write probe\n', { mode: 0o600 });
+    }
+    catch (err) {
+        throw new Error(`${what} "${dir}" is not writable (${errorCode(err)}) — the server would fail at startup with the same error. ` +
+            'Point IRIS_HOME at a directory this user can write, or fix the permissions on that path.');
+    }
+    try {
+        unlinkSync(probeFile);
+    }
+    catch {
+        // Written but not removable: unusual (sticky bit, AV lock). Not a
+        // startup blocker, so not a failure; the file is tiny and named for
+        // what it is.
+    }
+}
 export async function runSelfTest(write = stdoutLine) {
     write(`Iris self-test v${PKG_VERSION}`);
     write('');
     /*
      * Resolved BEFORE the env scrub: this is where a normal (non-self-test)
      * run of this install would keep its data, which is the line the user
-     * actually wants from a diagnostic. The self-test itself never touches
-     * this path.
+     * actually wants from a diagnostic — and the target of the configured-
+     * home probe below. The isolated checks never touch these paths.
      */
-    const userStoragePath = process.env.IRIS_DB_PATH ?? join(irisHome(), 'iris.db');
+    const userHome = irisHome();
+    const userStoragePath = process.env.IRIS_DB_PATH ?? join(userHome, 'iris.db');
     const savedEnv = {};
     for (const key of SCRUBBED_ENV_VARS) {
         savedEnv[key] = process.env[key];
@@ -137,14 +211,18 @@ export async function runSelfTest(write = stdoutLine) {
     let traceId = '';
     const insertedIds = [];
     const failedSteps = [];
+    let halted = false;
     /*
      * Steps run strictly in order and stop at the first failure — each one
      * depends on the state the previous one built, so a cascade of
      * follow-on crosses would only bury the real cause. Cleanup runs
-     * unconditionally afterwards.
+     * unconditionally afterwards. A step marked `independent` still fails
+     * the run but does not halt it: the configured-home probe has no
+     * successors that depend on it, and the user is better served by ALSO
+     * learning whether the install itself works.
      */
-    const step = async (label, fn) => {
-        if (failedSteps.length > 0)
+    const step = async (label, fn, opts) => {
+        if (halted)
             return;
         try {
             const detail = await fn();
@@ -152,9 +230,14 @@ export async function runSelfTest(write = stdoutLine) {
         }
         catch (err) {
             failedSteps.push(label);
+            if (!opts?.independent)
+                halted = true;
             write(`${CROSS} ${label} — ${err instanceof Error ? err.message : String(err)}`);
         }
     };
+    await step(SELF_TEST_STEPS.configuredHome, () => probeConfiguredHome(userHome, userStoragePath), {
+        independent: true,
+    });
     await step(SELF_TEST_STEPS.tempHome, () => {
         tempHome = mkdtempSync(join(tmpdir(), 'iris-self-test-'));
         for (const key of SCRUBBED_ENV_VARS) {
@@ -321,6 +404,7 @@ export async function runSelfTest(write = stdoutLine) {
     }
     write('');
     write(`version   ${PKG_VERSION}`);
+    write(`home      ${userHome}`);
     write(`storage   ${userStoragePath}`);
     write(failedSteps.length === 0
         ? SELF_TEST_PASS_VERDICT

package/dist/storage/demo-guard.d.ts

@@ -0,0 +1,8 @@
+import type { IStorageAdapter } from '../types/query.js';
+export declare const DEMO_INGEST_REFUSED_MESSAGE: string;
+export declare class DemoIngestRefusedError extends Error {
+    /** Read by the dashboard's error handler: a client fault, not a server one. */
+    readonly status = 403;
+    constructor();
+}
+export declare function withDemoIngestGuard(storage: IStorageAdapter): IStorageAdapter;

package/dist/storage/demo-guard.js

@@ -0,0 +1,53 @@
+/*
+ * Demo mode must not quietly become someone's production store.
+ *
+ * `--demo` serves the dashboard — and with it POST /api/v1/traces — against
+ * demo.db, a seeded, DISPOSABLE database that `--demo-clear` deletes
+ * outright. A reader following the README top to bottom could start the
+ * demo, point their capture client at the port it printed, watch real
+ * traces land beside the fake ones, and later lose all of them to the
+ * cleanup command the banner recommends. Nothing warned at any step.
+ *
+ * The guard wraps the demo store so every WRITE of trace or eval data is
+ * refused with a message that says what demo mode is and where real
+ * traces go. Reads and the demo's own seeded content are untouched — the
+ * dashboard keeps working exactly as before. Rule deploys are not storage
+ * writes (they go to the demo-scoped rule store) and stay allowed; they
+ * are part of what the demo exists to show.
+ *
+ * Implemented as a Proxy over the adapter rather than a subclass or a
+ * hand-written delegate: any method added to IStorageAdapter later
+ * delegates automatically instead of silently bypassing the guard.
+ */
+export const DEMO_INGEST_REFUSED_MESSAGE = 'Demo mode does not accept trace ingest. `--demo` serves a seeded, disposable database (demo.db) — ' +
+    '`--demo-clear` deletes everything in it, so real traces stored here would be lost. ' +
+    'Start the real server to store traces: `iris-mcp --dashboard` for HTTP ingest on POST /api/v1/traces, ' +
+    'or the MCP transport for log_trace.';
+const REFUSED_METHODS = new Set([
+    'insertTrace',
+    'insertSpan',
+    'insertEvalResult',
+]);
+export class DemoIngestRefusedError extends Error {
+    /** Read by the dashboard's error handler: a client fault, not a server one. */
+    status = 403;
+    constructor() {
+        super(DEMO_INGEST_REFUSED_MESSAGE);
+        this.name = 'DemoIngestRefusedError';
+    }
+}
+export function withDemoIngestGuard(storage) {
+    return new Proxy(storage, {
+        get(target, prop, receiver) {
+            if (typeof prop === 'string' && REFUSED_METHODS.has(prop)) {
+                return async () => {
+                    throw new DemoIngestRefusedError();
+                };
+            }
+            const value = Reflect.get(target, prop, receiver);
+            // Class methods live on the prototype and read private fields off
+            // `this`; bind them to the real adapter so `this.db` resolves.
+            return typeof value === 'function' ? value.bind(target) : value;
+        },
+    });
+}

package/dist/storage/migrations/006-eval-critical-failures.d.ts

@@ -0,0 +1,3 @@
+import type Database from 'better-sqlite3';
+export declare const id = "006-eval-critical-failures";
+export declare function up(db: Database.Database): void;

package/dist/storage/migrations/006-eval-critical-failures.js

@@ -0,0 +1,23 @@
+export const id = '006-eval-critical-failures';
+/*
+ * v0.5.0's headline feature — the critical-rule veto — was response-only.
+ * `critical_failures` was returned to the caller and then dropped on the
+ * floor: `insertEvalResult` never wrote it, so once an evaluation was
+ * stored, a vetoed eval was indistinguishable from one that simply scored
+ * below the threshold. Nothing downstream could filter, count or badge the
+ * flagship behaviour, and the dashboard showed "safety · fail  score 0.92"
+ * with no way to say WHY it failed.
+ *
+ * JSON text rather than a join table: it mirrors how rule_results and
+ * suggestions are already stored, keeps the read path a single row, and the
+ * array is small and read-only after write.
+ *
+ * NULL for every row written before this migration, which is honest — those
+ * evaluations predate the veto, so "no recorded veto" is the truth rather
+ * than an empty array asserting there was none.
+ */
+export function up(db) {
+    db.exec(`
+    ALTER TABLE eval_results ADD COLUMN critical_failures TEXT;
+  `);
+}

package/dist/storage/migrations/index.js

@@ -3,12 +3,14 @@ import * as migration002 from './002-eval-skip-fields.js';
 import * as migration003 from './003-eval-passed-index.js';
 import * as migration004 from './004-tenant-id.js';
 import * as migration005 from './005-normalize-created-at.js';
+import * as migration006 from './006-eval-critical-failures.js';
 const migrations = [
     migration001,
     migration002,
     migration003,
     migration004,
     migration005,
+    migration006,
 ];
 export function runMigrations(db) {
     db.exec(`

package/dist/storage/sqlite-adapter.d.ts

@@ -34,6 +34,12 @@ export declare class SqliteAdapter implements IStorageAdapter {
     getEvalStatsRules(tenantId: TenantId, period: EvalStatsPeriod): Promise<EvalStatsRuleBreakdown[]>;
     getEvalStatsFailures(tenantId: TenantId, period: EvalStatsPeriod, limit: number): Promise<EvalStatsFailure[]>;
     deleteTracesOlderThan(tenantId: TenantId, days: number): Promise<number>;
+    deleteEvalResultsOlderThan(tenantId: TenantId, days: number): Promise<number>;
+    purge(tenantId: TenantId): Promise<{
+        traces: number;
+        evalResults: number;
+    }>;
+    checkpoint(): Promise<void>;
     deleteTrace(tenantId: TenantId, traceId: string): Promise<boolean>;
     getDistinctValues(tenantId: TenantId, column: string): Promise<string[]>;
     private rowToTrace;

package/dist/storage/sqlite-adapter.js

@@ -45,6 +45,16 @@ export class SqliteAdapter {
         this.db.pragma('journal_mode = WAL');
         this.db.pragma('busy_timeout = 5000');
         this.db.pragma('foreign_keys = ON');
+        /*
+         * secure_delete overwrites freed content with zeros instead of leaving
+         * it in place until the page is reused. Without it, a DELETE — the
+         * retention sweep, delete_trace, --purge — removed the row from every
+         * query while the text stayed byte-for-byte readable in the file with
+         * `strings iris.db`. Deletes are rare here (startup sweep, explicit
+         * deletes), so the write cost is negligible; the privacy cost of the
+         * alternative is the whole point of #372.
+         */
+        this.db.pragma('secure_delete = ON');
         runMigrations(this.db);
         /*
          * iris.db holds agent inputs and outputs verbatim, and a tool that
@@ -185,10 +195,18 @@ export class SqliteAdapter {
          * calendar date matched the boundary's date was dropped from the
          * window. Migration 005 rewrites rows written before this line existed.
          */
+        /*
+         * critical_failures is PERSISTED (migration 006) because the veto is a
+         * verdict, not a presentation detail. It used to live only in the live
+         * tool response, so the moment an evaluation was stored a vetoed eval
+         * became indistinguishable from one that merely scored below threshold —
+         * no surface could filter, count, or explain the release's flagship
+         * behaviour. NULL when nothing vetoed.
+         */
         this.db.prepare(`
-      INSERT INTO eval_results (tenant_id, id, trace_id, eval_type, output_text, expected_text, score, passed, rule_results, suggestions, rules_evaluated, rules_skipped, insufficient_data, created_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(tenantId, result.id, result.trace_id ?? null, result.eval_type, result.output_text, result.expected_text ?? null, result.score, result.passed ? 1 : 0, JSON.stringify(result.rule_results), JSON.stringify(result.suggestions), result.rules_evaluated ?? null, result.rules_skipped ?? null, result.insufficient_data ? 1 : 0, new Date().toISOString());
+      INSERT INTO eval_results (tenant_id, id, trace_id, eval_type, output_text, expected_text, score, passed, rule_results, suggestions, rules_evaluated, rules_skipped, insufficient_data, critical_failures, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(tenantId, result.id, result.trace_id ?? null, result.eval_type, result.output_text, result.expected_text ?? null, result.score, result.passed ? 1 : 0, JSON.stringify(result.rule_results), JSON.stringify(result.suggestions), result.rules_evaluated ?? null, result.rules_skipped ?? null, result.insufficient_data ? 1 : 0, result.critical_failures?.length ? JSON.stringify(result.critical_failures) : null, new Date().toISOString());
     }
     async getEvalsByTraceId(tenantId, traceId) {
         assertTenant(tenantId);
@@ -344,11 +362,18 @@ export class SqliteAdapter {
          * skips rules that passed, so scanning every safety eval in the window
          * is both correct and sufficient.
          */
+        /*
+         * eval_type IN ('safety', 'all'): an eval_type="all" run carries the
+         * whole safety bundle inside its rule_results, and a PII leak caught
+         * there is exactly as real as one caught by a safety-only run. The
+         * per-rule loop below keys on rule NAMES, so the wider filter cannot
+         * over-count.
+         */
         const safetyRows = this.db.prepare(`
       SELECT rule_results
       FROM eval_results
       WHERE tenant_id = ? AND created_at >= ?
-        AND eval_type = 'safety'
+        AND eval_type IN ('safety', 'all')
     `).all(tenantId, since);
         const violations = { pii: 0, injection: 0, hallucination: 0 };
         for (const row of safetyRows) {
@@ -484,6 +509,55 @@ export class SqliteAdapter {
             .run(tenantId, cutoff);
         return result.changes;
     }
+    async deleteEvalResultsOlderThan(tenantId, days) {
+        assertTenant(tenantId);
+        const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
+        /*
+         * created_at, not the linked trace's timestamp: an unlinked eval has
+         * no trace, and a linked one whose trace was already swept has a NULL
+         * trace_id — either way the eval's own age is the only age it has.
+         * Rows are ISO-8601 here (write path + migration 005), so the string
+         * comparison against an ISO cutoff is exact.
+         */
+        const result = this.db
+            .prepare('DELETE FROM eval_results WHERE tenant_id = ? AND created_at < ?')
+            .run(tenantId, cutoff);
+        return result.changes;
+    }
+    async purge(tenantId) {
+        assertTenant(tenantId);
+        const deleteAll = this.db.transaction(() => {
+            const evalResults = this.db.prepare('DELETE FROM eval_results WHERE tenant_id = ?').run(tenantId).changes;
+            // spans cascade (FK ON DELETE CASCADE).
+            const traces = this.db.prepare('DELETE FROM traces WHERE tenant_id = ?').run(tenantId).changes;
+            return { traces, evalResults };
+        });
+        const counts = deleteAll();
+        /*
+         * VACUUM rebuilds the file from the live rows only — the freed pages
+         * (already zeroed by secure_delete) are dropped rather than kept as
+         * free-list slack — and the TRUNCATE checkpoint then folds the WAL into
+         * the main file and cuts it to zero bytes, so neither iris.db nor
+         * iris.db-wal keeps a copy of what was just deleted. Skipped for
+         * :memory: (nothing on disk to clean).
+         */
+        if (this.dbPath !== ':memory:') {
+            this.db.exec('VACUUM');
+        }
+        await this.checkpoint();
+        return counts;
+    }
+    async checkpoint() {
+        if (this.dbPath === ':memory:')
+            return;
+        try {
+            this.db.pragma('wal_checkpoint(TRUNCATE)');
+        }
+        catch {
+            // Best effort: a checkpoint can be refused while another connection
+            // holds a read transaction. The next one will pick the pages up.
+        }
+    }
     async deleteTrace(tenantId, traceId) {
         assertTenant(tenantId);
         // Tenant-scoped: a trace id owned by a different tenant is
@@ -543,6 +617,11 @@ export class SqliteAdapter {
             id: row.id,
             trace_id: row.trace_id,
             eval_type: row.eval_type,
+            /*
+             * `categories` is not a column: an eval_type="all" row carries a
+             * `category` on every rule_results entry instead, so a reader can
+             * regroup the per-bundle breakdown from what IS stored.
+             */
             output_text: row.output_text,
             expected_text: row.expected_text,
             score: row.score,
@@ -553,6 +632,14 @@ export class SqliteAdapter {
             rules_evaluated: row.rules_evaluated,
             rules_skipped: row.rules_skipped,
             insufficient_data: row.insufficient_data != null ? row.insufficient_data === 1 : undefined,
+            /*
+             * Absent, not [], when NULL. Rows written before migration 006 never
+             * captured the field, and returning an empty array would assert "no
+             * critical rule failed" about an evaluation that never recorded one.
+             */
+            ...(row.critical_failures != null
+                ? { critical_failures: JSON.parse(row.critical_failures) }
+                : {}),
         };
     }
 }

package/dist/tools/delete-rule.js

@@ -1,43 +1,56 @@
 /*
- * delete_rule MCP tool — remove a deployed custom rule.
+ * delete_rule MCP tool — remove a deployed custom rule, or disable /
+ * re-enable one without removing it.
  *
  * Destructive counterpart to deploy_rule. Removes the rule from
  * ~/.iris/custom-rules.json AND unregisters it from the live eval
  * engine, so it stops firing on the very next evaluate_output call —
  * no restart needed. Appends a `rule.delete` entry to the audit log.
  *
+ * With `enabled` present the call is a TOGGLE instead: the rule stays in
+ * the store with its history and provenance, is unregistered from (or
+ * re-registered with) the live engine, and a `rule.toggle` audit row is
+ * written. The descriptions used to point at "the dashboard's toggle
+ * affordance" for this — which did not exist on any surface; the store
+ * had setEnabled() and nothing called it. This is the MCP path to it.
+ *
  * Past eval_results that referenced this rule stay intact — the
  * history is preserved even after the rule is removed. The audit
  * log row is the permanent record that the rule ever existed.
  */
 import { z } from 'zod';
+import { createCustomRule } from '../eval/rules/custom.js';
 import { LOCAL_TENANT } from '../types/tenant.js';
 import { strictInput } from './strict-input.js';
 const inputSchema = {
     rule_id: z
         .string()
         .regex(/^rule-[a-z0-9]+$/)
-        .describe('Rule id to delete (format: rule-<hex>); obtained from list_rules or deploy_rule response'),
+        .describe('Rule id to delete or toggle (format: rule-<hex>); obtained from list_rules or deploy_rule response'),
+    enabled: z
+        .boolean()
+        .optional()
+        .describe('When present the rule is NOT deleted: false DISABLES it (kept in the store, stops firing immediately, history and provenance preserved); true RE-ENABLES a disabled rule. Omit to delete'),
 };
 export function registerDeleteRuleTool(server, customRuleStore, evalEngine) {
     server.registerTool('delete_rule', {
-        title: 'Delete Custom Rule',
+        title: 'Delete or Disable Custom Rule',
         description: [
-            'Remove a deployed custom evaluation rule. The rule stops firing on future evaluate_output calls; past eval_results that referenced it are preserved.',
+            'Remove a deployed custom evaluation rule — or, with `enabled`, disable / re-enable it without removing it. Either way the change takes effect on the next evaluate_output call; past eval_results that referenced the rule are preserved.',
             '',
-            'Sibling tools — deploy_rule adds custom rules, list_rules enumerates them, evaluate_output runs them. delete_trace handles trace deletion (separate concern); log_trace / get_traces handle trace I/O. delete_rule is the DESTRUCTIVE remove path for the custom-rule store; it does NOT touch traces, eval_results, or built-in (non-custom) rules.',
+            'Sibling tools — deploy_rule adds custom rules, list_rules enumerates them (including disabled ones, with `enabled: false`), evaluate_output runs them. delete_trace handles trace deletion (separate concern); log_trace / get_traces handle trace I/O. delete_rule is the DESTRUCTIVE remove path for the custom-rule store and the only MCP path that toggles a rule; it does NOT touch traces, eval_results, or built-in (non-custom) rules.',
             '',
-            'Behavior. DESTRUCTIVE — rewrites ~/.iris/custom-rules.json without the deleted row and appends a `rule.delete` entry to the audit log (~/.iris/audit.log). Not idempotent: deleting an already-deleted rule returns `deleted: false` rather than re-emitting the audit row. The rule stops firing immediately on the live process. Historical eval_results that reference this rule_id stay in the database — drift analytics + audit trail remain valid. Tenant-scoped in Cloud tier; OSS operates on LOCAL_TENANT. Rate-limited to 20 req/min on HTTP MCP.',
+            'Behavior. Without `enabled`: DESTRUCTIVE — rewrites ~/.iris/custom-rules.json without the deleted row and appends a `rule.delete` entry to the audit log (~/.iris/audit.log). Not idempotent: deleting an already-deleted rule returns `deleted: false` rather than re-emitting the audit row. The rule stops firing immediately on the live process. With `enabled`: NOT destructive — the rule row stays, its `enabled` flag and `updatedAt` change, a `rule.toggle` audit entry is appended (none if the flag was already in that state), and the live engine unregisters (false) or re-registers (true) the rule so the change is immediate; a disabled rule is not loaded at the next boot either. Historical eval_results that reference this rule_id stay in the database — drift analytics + audit trail remain valid. Tenant-scoped in Cloud tier; OSS operates on LOCAL_TENANT. Rate-limited to 20 req/min on HTTP MCP.',
             '',
-            'Output shape. Returns JSON: `{ "deleted": boolean, "rule_id": string }`. `deleted=true` if a row was removed; `deleted=false` if no rule with that id existed.',
+            'Output shape. Delete: `{ "deleted": boolean, "rule_id": string }` — `deleted=true` if a row was removed; `deleted=false` if no rule with that id existed. Toggle (enabled given): `{ "deleted": false, "toggled": boolean, "rule_id": string, "enabled"?: boolean, "rule"?: { ...the rule } }` — `toggled=true` with the rule\'s current state when the id exists (also when it was already in the requested state), `toggled=false` and no `rule` when it does not.',
             '',
-            "Use when a custom rule is obsolete (behavior changed, false positives unacceptable, replaced by a better rule). Typical flow: list_rules → identify the stale one → delete_rule(id). Combine with deploy_rule to replace: delete_rule(oldId) + deploy_rule(newDefinition). To temporarily disable a rule WITHOUT deletion, use the dashboard's toggle affordance instead — delete is permanent in intent (rule is gone; re-adding requires a new id).",
+            "Use when a custom rule is obsolete (behavior changed, false positives unacceptable, replaced by a better rule). Typical flow: list_rules → identify the stale one → delete_rule(id). Combine with deploy_rule to replace: delete_rule(oldId) + deploy_rule(newDefinition), or deploy_rule with the same name and replace:true. To temporarily PAUSE a rule — false positives to investigate, a rollout to stage — pass `enabled: false` instead of deleting; it keeps the id, the provenance and the history, and `enabled: true` brings it back with the same id.",
             '',
-            "Don't use to pause a rule (toggle in the dashboard preserves history better). Don't use on built-in (non-custom) rules — the rule_id format checks for `rule-<hex>` custom ids; built-ins aren't in the store. Don't use to delete a trace or eval result (use delete_trace for traces; eval_results deletion is not exposed in v0.4 — they fall under data retention).",
+            "Don't use on built-in (non-custom) rules — the rule_id format checks for `rule-<hex>` custom ids; built-ins aren't in the store. Don't use to delete a trace or eval result (use delete_trace for traces; eval_results deletion is not exposed per row — they fall under data retention and `--purge`).",
             '',
-            'Parameters. rule_id is the only parameter; must match `rule-<lowercase-hex>` format (Zod regex). Format mismatch fails Zod with 400 BEFORE the store is touched. Cross-tenant rule_ids return `deleted: false` silently — they\'re invisible to the caller\'s tenant rather than producing a not-found error (prevents enumeration attacks). The rule_id you pass is exactly what list_rules returned in `id` or what deploy_rule returned in `rule.id`.',
+            'Parameters. rule_id must match `rule-<lowercase-hex>` format (Zod regex). Format mismatch fails Zod with 400 BEFORE the store is touched. Cross-tenant rule_ids return `deleted: false` / `toggled: false` silently — they\'re invisible to the caller\'s tenant rather than producing a not-found error (prevents enumeration attacks). The rule_id you pass is exactly what list_rules returned in `id` or what deploy_rule returned in `rule.id`. enabled is optional: omit to delete, false to disable, true to re-enable.',
             '',
-            "Error modes. Throws 400 on malformed rule_id (wrong prefix). Returns `{deleted: false}` if rule_id doesn't match any deployed rule (not an error — idempotent-ish). Returns 429 on HTTP rate limit. File-write failures propagate as 500.",
+            "Error modes. Throws 400 on malformed rule_id (wrong prefix) or an unknown argument. Returns `{deleted: false}` (or `{toggled: false}`) if rule_id doesn't match any deployed rule (not an error — idempotent-ish). Returns 429 on HTTP rate limit. File-write failures propagate as 500.",
         ].join('\n'),
         inputSchema: strictInput(inputSchema),
         annotations: {
@@ -48,6 +61,31 @@ export function registerDeleteRuleTool(server, customRuleStore, evalEngine) {
         },
     }, async (args) => {
         // OSS: MCP tools operate under LOCAL_TENANT. See list-rules.ts for context.
+        if (args.enabled !== undefined) {
+            const rule = customRuleStore.setEnabled(LOCAL_TENANT, args.rule_id, args.enabled, 'mcp');
+            if (!rule) {
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ deleted: false, toggled: false, rule_id: args.rule_id }) }],
+                };
+            }
+            // Mirror the store in the live engine, so the toggle is immediate
+            // (registerRule is idempotent by id — re-enabling an already-live
+            // rule does not stack a second copy).
+            if (rule.enabled) {
+                evalEngine.registerRule(rule.evalType, createCustomRule(rule.definition, rule.severity), rule.id);
+            }
+            else {
+                evalEngine.unregisterRule(rule.id);
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ deleted: false, toggled: true, rule_id: args.rule_id, enabled: rule.enabled, rule }),
+                    },
+                ],
+            };
+        }
         const deleted = customRuleStore.delete(LOCAL_TENANT, args.rule_id, 'mcp');
         if (deleted) {
             // Hot-remove from the live engine so the rule stops firing on the

package/dist/tools/deploy-rule.d.ts

@@ -1,4 +1,37 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { CustomRuleStore } from '../custom-rule-store.js';
 import type { EvalEngine } from '../eval/engine.js';
+import type { DeployedCustomRule } from '../types/custom-rule.js';
+import { type TenantId } from '../types/tenant.js';
+/**
+ * A rule with this name is already deployed and the caller did not ask to
+ * replace it. Carries the existing rule(s) so an HTTP surface can answer
+ * 409 with them beside the same message the MCP tool throws.
+ */
+export declare class DuplicateRuleNameError extends Error {
+    readonly existing: DeployedCustomRule[];
+    constructor(name: string, existing: DeployedCustomRule[]);
+}
+/** One rule retired by a `replace: true` deploy. */
+export interface ReplacedRule {
+    id: string;
+    evalType: string;
+    severity: string;
+}
+/**
+ * Same-name redeploy (#373). Two rules with one name both fire, and their
+ * rule_results used to be indistinguishable — the same ruleName showing
+ * PASS and FAIL in one response. Refuse by default; with replace:true,
+ * retire the earlier rule(s) first so the name means one thing again. The
+ * store keeps the audit trail either way.
+ *
+ * One function for both deploy surfaces — the `deploy_rule` tool and the
+ * dashboard's `POST /api/v1/rules/custom` — so the semantics and the
+ * wording cannot drift between them. Returns the rules it retired (empty
+ * when the name was free); throws DuplicateRuleNameError when the name is
+ * taken and `replace` is false. Nothing is deployed by this function.
+ */
+export declare function retireSameNamedRules(store: CustomRuleStore, engine: EvalEngine, tenantId: TenantId, name: string, replace: boolean, user: string): ReplacedRule[];
+/** The `warning` both deploy surfaces attach when a replace retired rules. */
+export declare function replacedRulesWarning(name: string, replaced: ReplacedRule[]): string;
 export declare function registerDeployRuleTool(server: McpServer, customRuleStore: CustomRuleStore, evalEngine: EvalEngine): void;