coderifts 8.1.0 → 8.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 8.3.0 - 2026-09-05
+
+### Changed
+- `@coderifts/agent-guard` range raised to `^17.1.0`. Guard 17.1.0 fixes the audience binding (the Guard now sends top-level `audience`, which the server actually reads) and makes its public suite hermetic. No CLI behaviour change beyond the installed guard minor.
+
+
+## 8.2.0 - 2026-09-05
+
+### Changed
+- `@coderifts/agent-guard` range raised to `^17.0.0` (MIN_GUARD_MAJOR 17). Guard 17 blocks a raw shell carrying a mutation by default (a host-declared mutating_shell now reaches the UNGUARDED_MUTATION decision instead of slipping through). The CLI range must match so `npm i -g coderifts` installs the guard whose default the docs describe. No CLI behaviour change beyond the installed guard major.
+
+
 ## 8.1.0 - 2026-09-05
 
 ### Changed

package/bin/coderifts.js

@@ -52,6 +52,19 @@ program
 // Exit status is set only at this command boundary (library never process.exit).
 // program.parse() does not await async actions; process.exit here makes the gate's
 // fail-closed status authoritative for npm prepublishOnly / child_process callers.
+// ── doctor (1222) — the adoption entry point ──
+// Tier 0 needs no key and calls no model; Tier 1 is BYOK on the developer's own machine.
+program
+  .command('doctor')
+  .description('Would an agent select CodeRifts for a contract change? Structural check (no key), or the 15-fixture benchmark on your own model.')
+  .option('--tools <file>', 'Your host\'s tools/list response (array, { tools }, or { result: { tools } })')
+  .option('--model <id>', 'TIER 1: run the fixtures through this model using YOUR key from the environment')
+  .option('--mock', 'TIER 1 dry run: a deterministic scripted model. Measures the script, not a model.')
+  .action(async (options) => {
+    const { runDoctor } = require('../src/commands/doctor');
+    await runDoctor(options);
+  });
+
 program
   .command('publish-gate')
   .description('Gate npm publish on contract-artifact preflight (before=git baseline, after=working tree)')

package/dist/.build-source-sha

@@ -1,5 +1,5 @@
 {
   "$comment": "GENERATED by scripts/build.js. sha256 over src/**.js + bin/**.js (path + bytes). test/build-freshness.test.js recomputes it; a mismatch means dist/cli.js is stale.",
-  "sha256": "d9d48f2b01fa76855978dbbaa67d81be419b7632e1cc80eb5b999d5efcf9c090",
-  "file_count": 42
+  "sha256": "9596f98c3c463ea53896621305484fd1ca3c5685b15c410fa4205c07a285c709",
+  "file_count": 44
 }

package/dist/cli.js

@@ -3028,7 +3028,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "coderifts",
-      version: "8.1.0",
+      version: "8.3.0",
       description: "Detect breaking API changes from the command line. Works locally or with the CodeRifts cloud API.",
       author: "CodeRifts <hello@coderifts.com>",
       license: "MIT",
@@ -3074,7 +3074,7 @@ var require_package = __commonJS({
         test: "node --test test/*.test.js"
       },
       dependencies: {
-        "@coderifts/agent-guard": "^16.0.0",
+        "@coderifts/agent-guard": "^17.1.0",
         chalk: "^4.1.2",
         "cli-table3": "^0.6.4",
         commander: "^12.0.0",
@@ -66622,10 +66622,14 @@ var require_unguarded_mutation = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.ADVISORY_ENV_VAR = void 0;
+    exports2.isDeclaredMutatingClass = isDeclaredMutatingClass;
     exports2.decideUnguardedMutation = decideUnguardedMutation;
     var ADVISORY_TRUE = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
     exports2.ADVISORY_ENV_VAR = "CODERIFTS_ADVISORY";
     var RISK = 'A mutating tool call reached the guard with no verified receipt: the detector did not recognise a contract artifact, so nothing was preflighted and nothing was signed. "Not a contract change" describes the artifact, not the action \u2014 the write still happens.';
+    function isDeclaredMutatingClass(cls) {
+      return typeof cls === "string" && cls.startsWith("mutating");
+    }
     function decideUnguardedMutation(mutating, policy, env) {
       if (!mutating)
         return { stop: false };
@@ -71324,7 +71328,21 @@ These feed DIFFERENT halves of the system \u2014 the top level binds the ATOMIC
       ["target_uri", "targetUri"],
       ["tenant_id", "tenantId"],
       ["policy_hash", "policyHash"],
-      ["audience_hash", "audienceHash"],
+      // 1402 — `audience_hash` IS NOT ON THIS LIST, and its absence is the fix.
+      //
+      // MEASURED 2026-09-06 against the server, read-only:
+      //   src/change-set.js:1138            reads TOP-LEVEL `input.audience`, strict /^v:[0-9a-f]{12}$/
+      //   execution-grant-v2.js:166         derives `audience_hash: sha256pref(audience)` ITSELF
+      //   execution-grant-request.v2.producer.json  states it outright: "`audience_hash` is NOT a
+      //                                     request field of its own … sending it separately has no
+      //                                     effect and it stays out of this schema"
+      //
+      // So the Guard was sending a field nobody reads. Worse, it was ALSO sending the audience under
+      // `context.audience`, which the handler does not read either (it reads `input.audience`) — both
+      // channels were severed, and the binding a host configured reached the server through neither.
+      // A field that looks bound and is not is the exact failure the server's own 1206 note describes.
+      //
+      // The fix is to send what the server consumes: top-level `audience`. See guard.ts.
       ["expected_state_token", "expectedStateToken"]
     ]);
     function v2WireFields(config) {
@@ -71819,7 +71837,8 @@ var require_guard = __commonJS({
       const suppressedByStrict = config.requireExplicitArtifacts === true && redacted.nonContract === true && (!detection.artifacts || detection.artifacts.length === 0) && detection.confident && !detection.trigger;
       if (!detection.trigger || suppressedByStrict) {
         emit(config, { type: "detection_skip", at: iso(), signals: detection.signals, detectorVersion: detector.version });
-        const um = (0, unguarded_mutation_js_1.decideUnguardedMutation)((0, freshness_js_1.isMutatingCall)(redacted), config.requireGuardedMutation, process.env);
+        const declaredMutating = (0, unguarded_mutation_js_1.isDeclaredMutatingClass)(redacted.mutationClass);
+        const um = (0, unguarded_mutation_js_1.decideUnguardedMutation)((0, freshness_js_1.isMutatingCall)(redacted) || declaredMutating, config.requireGuardedMutation, process.env);
         if (um.stop) {
           emit(config, { type: "unguarded_mutation_blocked", at: iso(), cause: um.detail });
           breakerRecord(config);
@@ -71867,6 +71886,17 @@ var require_guard = __commonJS({
         previous_receipt: resolvePreviousReceipt(config),
         idempotency_key: void 0
       };
+      if (typeof config.audience === "string" && config.audience.length > 0) {
+        if (/^v:[0-9a-f]{12}$/.test(config.audience)) {
+          request.audience = config.audience;
+        } else {
+          emit(config, {
+            type: "audience_not_bindable",
+            at: iso(),
+            cause: `audience ${JSON.stringify(config.audience)} is not the measured v:<12 hex> form; the server discards any other string to null, so it would NOT be bound. Nothing was sent for it.`
+          });
+        }
+      }
       let grantObs;
       let grantForCall = null;
       if ((0, execution_grant_js_1.isExecutionGrantEnabled)(config)) {
@@ -74423,7 +74453,10 @@ var require_tool_registry = __commonJS({
         meta: tool.meta,
         execute: async (args) => {
           const deriveCfg = (0, auto_derive_js_1.normalizeAutoDerive)(guardCfg.autoDerive);
-          const rebindRaw = () => binder(tool, args, cls);
+          const rebindRaw = () => {
+            const c = binder(tool, args, cls);
+            return c && c.mutationClass === void 0 ? { ...c, mutationClass: cls } : c;
+          };
           let lastDerivation = null;
           const rebind = async () => {
             const c = rebindRaw();
@@ -77491,7 +77524,7 @@ var require_cjs4 = __commonJS({
     exports2.createDbVersionToken = exports2.API_ABSENT_TOKEN = exports2.API_VERSION_TOKEN_PREFIX = exports2.apiTokenRaw = exports2.writeApiIfUnchanged = exports2.createApiVersionToken = exports2.identitiesEqual = exports2.fsObjectIdentity = exports2.UnsafeCasPathError = exports2.assertSafeCasPath = exports2.FS_ABSENT_TOKEN = exports2.FS_VERSION_TOKEN_PREFIX = exports2.fsTokenContentHash = exports2.createFsPriorContentResolver = exports2.writeFileIfUnchanged = exports2.readVersionedFile = exports2.createFsVersionToken = exports2.StaleVersionTokenAbort = exports2.executeIfUnchanged = exports2.RESIDUAL_UNCONDITIONAL_WRITE = exports2.conditionalWriteResidual = exports2.tokensEqual = exports2.buildConditionalWriteBasis = exports2.buildFreshnessBasis = exports2.collectFreshnessCallContext = exports2.artifactIdsForResolve = exports2.isMutatingCall = exports2.isWriteStyleCall = exports2.freshnessAllowsEnforce = exports2.computePathSetTreeHash = exports2.contentByteIdentical = exports2.assessWriteStylePrior = exports2.assessFreshness = exports2.deriveProofBanner = exports2.attachProofToAgentResponse = exports2.renderFinalAnswerProof = exports2.EXECUTION_PROOF_SPEC = exports2.assertEnforcedReceiptInvariant = exports2.hashExecutionResult = exports2.buildExecutionProof = exports2.COVERAGE_ATTEST_ENVELOPE_TAG = exports2.COVERAGE_ATTEST_SIGNING_PREFIX = exports2.COVERAGE_ATTEST_VERSION = exports2.coverageAttestSigningInput = exports2.kidFromCoverageAttestation = exports2.tryIssueCoverageAttestation = exports2.MONITOR_ATTEST_ENVELOPE_TAG = exports2.MONITOR_ATTEST_SIGNING_PREFIX = exports2.MONITOR_ATTEST_VERSION = exports2.receiptDigestOfToken = void 0;
     exports2.AUTO_DERIVE_READ_TIMEOUT_MS = exports2.AUTO_DERIVE_SOURCE = exports2.defaultFsReader = exports2.normalizeAutoDerive = exports2.runAutoDerive = exports2.AUTO_RECHECK_MAX_CAP = exports2.clampMaxAttempts = exports2.normalizeAutoRecheck = exports2.runAutoRecheckLoop = exports2.coverageReport = exports2.DEPLOY_REPAIRABLE_REASONS = exports2.bindDeploy = exports2.NEXT_STEP_NOTE = exports2.NEXT_AGENT_ACTIONS = exports2.readNextAgentStep = exports2.verifyDeployReceiptToken = exports2.DEPLOY_RECEIPT_VIEW_SPEC = exports2.isVerifiedDeployReceiptView = exports2.asVerifiedDeployReceiptView = exports2.deployGate = exports2.gateDecision = exports2.RegistryConstructionError = exports2.guardToolRegistry = exports2.globToRegExp = exports2.matchGlob = exports2.blobMapKey = exports2.classifyByName = exports2.resolveArtifacts = exports2.REMEDIATION_LOOP_ATTESTATION_SPEC = exports2.isCasAttestation = exports2.readPriorBlockRemediation = exports2.readRemediationTransaction = exports2.buildRemediationLoopAttestation = exports2.COMMIT_EVIDENCE_MISSING = exports2.CAS_ATTESTATION_SPEC = exports2.strictCommitObservation = exports2.extractExecutorAttestationToken = exports2.evaluateCasEvidence = exports2.isExecuteIfUnchangedOutcome = exports2.isGuardExecutionProof = exports2.buildCasAttestation = exports2.REGISTRY_ABSENT_TOKEN = exports2.REGISTRY_VERSION_TOKEN_PREFIX = exports2.registryTokenRaw = exports2.writeRegistryIfUnchanged = exports2.createRegistryVersionToken = exports2.DB_ABSENT_TOKEN = exports2.DB_VERSION_TOKEN_PREFIX = exports2.dbTokenRaw = exports2.writeDbIfUnchanged = void 0;
     exports2.inferFsPathFromArgs = exports2.FRESHNESS_RESOLVER_FIX = exports2.freshnessRefusalTeaching = exports2.formatGateRefusalBody = exports2.defaultSerializeLangGraphToolResult = exports2.bindLangGraphGuardOutcome = exports2.LangGraphToolsNotStructuredError = exports2.isLangGraphReactAgentTool = exports2.bindLangGraphTools = exports2.protectedToolToLangGraph = exports2.toLangGraphTools = exports2.langGraphToolAdapter = exports2.withCodeRiftsLangGraph = exports2.defaultSerializeAnthropicToolResult = exports2.bindAnthropicGuardOutcome = exports2.protectedToolToAnthropic = exports2.toAnthropicTools = exports2.anthropicToolAdapter = exports2.withCodeRiftsAnthropic = exports2.defaultSerializeOpenAIToolResult = exports2.bindOpenAIGuardOutcome = exports2.protectedToolToOpenAI = exports2.toOpenAITools = exports2.openAIToolAdapter = exports2.withCodeRiftsOpenAI = exports2.formatCoverageObservedLine = exports2.freezeCoverageObserved = exports2.createCoverageObserver = exports2.readExecutionGrantToken = exports2.isExecutionGrantEnabled = exports2.POSTURE_CLOCK_SKEW_TOLERANCE_MS = exports2.POSTURE_RECEIPT_V = exports2.verifyPostureReceipt = exports2.ATOMIC_V2_MAX_AGE_MS_CAP = exports2.CREDENTIAL_BOUNDARY_BARE_REJECTED = exports2.atomicConstructionProblems = exports2.isEnforcingAtomicV2 = exports2.PROFILE_ENFORCING_ATOMIC_V2 = exports2.isEnforcingAtomic = exports2.atomicOutcome = exports2.ATOMIC_PROFILE_UNSATISFIED = exports2.ATOMIC_INVARIANTS = exports2.createMutatorRegister = exports2._resetUnversionedProfileNoticeForTest = exports2.UNVERSIONED_PROFILE_NOTICE = exports2.PROFILE_ENFORCING_ATOMIC_V1 = exports2.PROFILE_ENFORCING_STRICT_V1 = exports2.guardedFractionAmongRoutes = exports2.foldTableSettledCalls = exports2.withCodeRifts = void 0;
-    exports2.ADVISORY_ENV_VAR = exports2.decideUnguardedMutation = exports2.missingReceiptDecision = exports2.offlineReceiptVerifier = exports2.kidFromToolsetAttestation = exports2.tryIssueToolsetAttestation = exports2.toolsetAttestSigningInput = exports2.declarationEntriesFromTools = exports2.computeToolsetDigest = exports2.TOOLSET_ATTEST_STATEMENT = exports2.TOOLSET_ATTEST_ENVELOPE_TAG = exports2.TOOLSET_ATTEST_SIGNING_PREFIX = exports2.TOOLSET_ATTEST_VERSION = exports2.surfaceEnvelopeFields = exports2.isGuardOutcome = exports2.executeVercelToolCall = exports2.executeLangGraphToolCall = exports2.executeGeminiToolCall = exports2.executeAnthropicToolCall = exports2.executeOpenAIToolCall = exports2.executeProtectedTool = exports2.defaultSerializeVercelToolResult = exports2.bindVercelGuardOutcome = exports2.protectedToolToVercel = exports2.toVercelTools = exports2.vercelToolAdapter = exports2.withCodeRiftsVercel = exports2.defaultSerializeCrewAIToolResult = exports2.bindCrewAIToolOutcome = exports2.LANGCHAIN_ARTIFACT_SPEC = exports2.defaultSerializeLangChainToolResult = exports2.bindLangChainToolOutcome = exports2.defaultSerializeGeminiToolResult = exports2.bindGeminiGuardOutcome = exports2.protectedToolToFunctionDeclaration = exports2.toGeminiTools = exports2.geminiToolAdapter = exports2.withCodeRiftsGemini = exports2.measureFsAuthorizationToken = exports2.measureFsAuthorization = exports2.wrapWriteWithFsCas = exports2.inferFullFileWriteContent = void 0;
+    exports2.ADVISORY_ENV_VAR = exports2.isDeclaredMutatingClass = exports2.decideUnguardedMutation = exports2.missingReceiptDecision = exports2.offlineReceiptVerifier = exports2.kidFromToolsetAttestation = exports2.tryIssueToolsetAttestation = exports2.toolsetAttestSigningInput = exports2.declarationEntriesFromTools = exports2.computeToolsetDigest = exports2.TOOLSET_ATTEST_STATEMENT = exports2.TOOLSET_ATTEST_ENVELOPE_TAG = exports2.TOOLSET_ATTEST_SIGNING_PREFIX = exports2.TOOLSET_ATTEST_VERSION = exports2.surfaceEnvelopeFields = exports2.isGuardOutcome = exports2.executeVercelToolCall = exports2.executeLangGraphToolCall = exports2.executeGeminiToolCall = exports2.executeAnthropicToolCall = exports2.executeOpenAIToolCall = exports2.executeProtectedTool = exports2.defaultSerializeVercelToolResult = exports2.bindVercelGuardOutcome = exports2.protectedToolToVercel = exports2.toVercelTools = exports2.vercelToolAdapter = exports2.withCodeRiftsVercel = exports2.defaultSerializeCrewAIToolResult = exports2.bindCrewAIToolOutcome = exports2.LANGCHAIN_ARTIFACT_SPEC = exports2.defaultSerializeLangChainToolResult = exports2.bindLangChainToolOutcome = exports2.defaultSerializeGeminiToolResult = exports2.bindGeminiGuardOutcome = exports2.protectedToolToFunctionDeclaration = exports2.toGeminiTools = exports2.geminiToolAdapter = exports2.withCodeRiftsGemini = exports2.measureFsAuthorizationToken = exports2.measureFsAuthorization = exports2.wrapWriteWithFsCas = exports2.inferFullFileWriteContent = void 0;
     var guard_js_1 = require_guard();
     Object.defineProperty(exports2, "guardToolCall", { enumerable: true, get: function() {
       return guard_js_1.guardToolCall;
@@ -78267,6 +78300,9 @@ var require_cjs4 = __commonJS({
     Object.defineProperty(exports2, "decideUnguardedMutation", { enumerable: true, get: function() {
       return unguarded_mutation_js_1.decideUnguardedMutation;
     } });
+    Object.defineProperty(exports2, "isDeclaredMutatingClass", { enumerable: true, get: function() {
+      return unguarded_mutation_js_1.isDeclaredMutatingClass;
+    } });
     Object.defineProperty(exports2, "ADVISORY_ENV_VAR", { enumerable: true, get: function() {
       return unguarded_mutation_js_1.ADVISORY_ENV_VAR;
     } });
@@ -230155,6 +230191,272 @@ var require_deploy_gate2 = __commonJS({
   }
 });
 
+// src/doctor.js
+var require_doctor = __commonJS({
+  "src/doctor.js"(exports2, module2) {
+    "use strict";
+    var fs = require("fs");
+    var path = require("path");
+    function harness() {
+      return require(path.join(__dirname, "..", "..", "..", "benchmark", "tool-selection-benchmark.js"));
+    }
+    var PREFLIGHT = "preflight_change_set";
+    function bare(name) {
+      return String(name == null ? "" : name).replace(/^coderifts\./, "");
+    }
+    function parseToolsDocument(doc) {
+      if (Array.isArray(doc)) return { ok: true, tools: doc };
+      if (doc && Array.isArray(doc.tools)) return { ok: true, tools: doc.tools };
+      if (doc && doc.result && Array.isArray(doc.result.tools)) return { ok: true, tools: doc.result.tools };
+      return {
+        ok: false,
+        why: "expected a tools/list response \u2014 an array, { tools: [...] }, or { result: { tools: [...] } }"
+      };
+    }
+    function descriptionOf(t) {
+      return typeof t.description === "string" ? t.description : "";
+    }
+    function schemaOf(t) {
+      return t.inputSchema || t.input_schema || t.parameters || void 0;
+    }
+    function signalPreflightPresent(tools) {
+      const hit = tools.find((t) => bare(t.name) === PREFLIGHT);
+      return hit ? { ok: true, detail: `\`${bare(hit.name)}\` is in the table` } : {
+        ok: false,
+        detail: `no \`${PREFLIGHT}\` tool in the table \u2014 nothing to select for a contract change`,
+        fix: "coderifts agent-setup"
+      };
+    }
+    function signalDescriptionMatchesShipped(tools, shipped) {
+      const hit = tools.find((t) => bare(t.name) === PREFLIGHT);
+      if (!hit) return { ok: false, detail: "not applicable \u2014 no preflight tool", fix: "coderifts agent-setup" };
+      const ship = shipped.find((t) => bare(t.name) === PREFLIGHT);
+      if (!ship) return { ok: false, detail: "the shipped manifest carries no preflight tool to compare against" };
+      const mine = descriptionOf(hit).trim();
+      const theirs = descriptionOf(ship).trim();
+      if (mine === theirs) return { ok: true, detail: "description is byte-identical to the shipped text" };
+      const pct = theirs.length ? Math.round(mine.length / theirs.length * 100) : 0;
+      return {
+        ok: false,
+        detail: `description DRIFTED from the shipped text (${mine.length} vs ${theirs.length} chars, ${pct}%) \u2014 the model reads this to decide, so a shortened or stale copy changes selection`,
+        fix: "coderifts agent-setup --force"
+      };
+    }
+    function signalSchemaValid(tools, h) {
+      const checks = [];
+      const attempt = (label, fn, arg) => {
+        try {
+          fn(arg);
+          checks.push({ label, ok: true });
+        } catch (err) {
+          checks.push({ label, ok: false, why: err && err.message || "rejected" });
+        }
+      };
+      const anthropicShape = tools.map((t) => ({ name: bare(t.name), description: descriptionOf(t), input_schema: schemaOf(t) }));
+      if (typeof h.validateAnthropicTools === "function") attempt("anthropic", h.validateAnthropicTools, anthropicShape.map(h.toAnthropicTool || ((x) => x)));
+      if (typeof h.validateOpenAITools === "function") attempt("openai", h.validateOpenAITools, anthropicShape.map(h.toOpenAITool || ((x) => x)));
+      if (typeof h.validateGoogleTools === "function") attempt("google", h.validateGoogleTools, anthropicShape.map(h.toGoogleFunctionDeclaration || ((x) => x)));
+      const bad = checks.filter((c) => !c.ok);
+      return bad.length === 0 ? { ok: true, detail: `accepted by ${checks.map((c) => c.label).join(", ") || "(no validator available)"}` } : {
+        ok: false,
+        detail: `rejected by ${bad.map((c) => `${c.label} (${c.why})`).join("; ")}`,
+        fix: "coderifts agent-setup --force"
+      };
+    }
+    var RIVAL_HINTS = ["breaking", "openapi", "contract", "api diff", "api change", "schema diff"];
+    function signalNoAbsorbingRival(tools, shipped = []) {
+      const own = new Set(shipped.map((t) => bare(t.name)));
+      const rivals = tools.filter((t) => bare(t.name) !== PREFLIGHT && !own.has(bare(t.name))).filter((t) => {
+        const text = `${bare(t.name)} ${descriptionOf(t)}`.toLowerCase();
+        return RIVAL_HINTS.some((h) => text.includes(h));
+      }).map((t) => bare(t.name));
+      return rivals.length === 0 ? { ok: true, detail: "no other tool advertises contract-change checking" } : {
+        ok: false,
+        warning: true,
+        detail: `${rivals.length} other tool(s) advertise contract-change work and may absorb the call: ` + rivals.join(", ") + " \u2014 Tier 1 measures whether they actually do",
+        fix: null
+      };
+    }
+    function tier0(tools) {
+      const h = harness();
+      const shipped = h.getCanonicalTools();
+      const signals = [
+        { id: "preflight_present", ...signalPreflightPresent(tools) },
+        { id: "description_matches_shipped", ...signalDescriptionMatchesShipped(tools, shipped) },
+        { id: "schema_valid", ...signalSchemaValid(tools, h) },
+        { id: "no_absorbing_rival", ...signalNoAbsorbingRival(tools, shipped) }
+      ];
+      const blocking = signals.filter((s) => !s.ok && !s.warning);
+      return {
+        tier: 0,
+        tool_count: tools.length,
+        signals,
+        passed: signals.filter((s) => s.ok).length,
+        total: signals.length,
+        blocking: blocking.length,
+        fixes: [...new Set(signals.filter((s) => !s.ok && s.fix).map((s) => s.fix))]
+      };
+    }
+    var DOES_NOT_PROVE = Object.freeze({
+      0: [
+        "that your model WOULD select CodeRifts \u2014 Tier 0 is structural only, a necessary condition",
+        "that a change reached a merge/deploy/publish sink, or that any gate fired",
+        "anything about tools this file was not shown"
+      ],
+      1: [
+        "that a change reached a merge/deploy/publish sink \u2014 selection is not enforcement",
+        "anything about a model other than the one you ran, at the version you ran it",
+        "that your production prompt behaves like the harness prompt"
+      ]
+    });
+    module2.exports = {
+      parseToolsDocument,
+      tier0,
+      harness,
+      bare,
+      DOES_NOT_PROVE,
+      PREFLIGHT,
+      signalPreflightPresent,
+      signalDescriptionMatchesShipped,
+      signalSchemaValid,
+      signalNoAbsorbingRival
+    };
+  }
+});
+
+// src/commands/doctor.js
+var require_doctor2 = __commonJS({
+  "src/commands/doctor.js"(exports2, module2) {
+    "use strict";
+    var fs = require("fs");
+    var path = require("path");
+    var chalk = require_source();
+    var {
+      parseToolsDocument,
+      tier0,
+      harness,
+      DOES_NOT_PROVE
+    } = require_doctor();
+    function readToolsFile(file) {
+      const resolved = path.resolve(file);
+      if (!fs.existsSync(resolved)) return { ok: false, why: `no such file: ${file}` };
+      let doc;
+      try {
+        doc = JSON.parse(fs.readFileSync(resolved, "utf8"));
+      } catch (err) {
+        return { ok: false, why: `not JSON: ${err && err.message || "parse error"}` };
+      }
+      return parseToolsDocument(doc);
+    }
+    function printBoundary(tier, log) {
+      log("");
+      log(chalk.bold("  WHAT THIS DOES NOT PROVE"));
+      for (const line of DOES_NOT_PROVE[tier]) log(chalk.dim(`    \xB7 ${line}`));
+    }
+    function renderTier0(r, log) {
+      log("");
+      log(chalk.bold(`  coderifts doctor \u2014 structural fitness (${r.tool_count} tools, no model called)`));
+      log("");
+      for (const s of r.signals) {
+        const mark = s.ok ? chalk.green("  ok  ") : s.warning ? chalk.yellow("  !!  ") : chalk.red("  X   ");
+        log(`${mark}${s.id}`);
+        log(chalk.dim(`        ${s.detail}`));
+      }
+      log("");
+      const verdict = r.blocking === 0 ? chalk.green(`  structurally fit to be selected: ${r.passed}/${r.total} signals`) : chalk.red(`  NOT structurally fit: ${r.blocking} blocking signal(s), ${r.passed}/${r.total} passed`);
+      log(verdict);
+      if (r.fixes.length) {
+        log("");
+        log(chalk.bold("  NEXT COMMAND"));
+        for (const f of r.fixes) log(`    ${chalk.cyan(f)}`);
+      }
+      log("");
+      log(chalk.dim("  Tier 0 is the NECESSARY condition, not selectability. To measure whether your"));
+      log(chalk.dim("  model actually selects, run the 15 fixtures on your own key:"));
+      log(chalk.dim("    coderifts doctor --tools <file> --model <model-id>"));
+    }
+    async function runTier1({ tools, model, log, mock }) {
+      const h = harness();
+      const fixtures = h.loadSelectionFixtures();
+      log("");
+      log(chalk.bold(`  coderifts doctor \u2014 selection benchmark (${fixtures.length} fixtures, model ${model})`));
+      let client;
+      if (mock) {
+        client = new h.MockClient(h.perfectScript());
+        log(chalk.yellow("  MOCK RUN \u2014 a scripted model that answers perfectly by construction."));
+        log(chalk.yellow("  This measures the script. It is not a measurement of any model."));
+      } else {
+        const provider = h.PROVIDERS && Object.keys(h.PROVIDERS).find((p) => String(model).toLowerCase().includes(p));
+        const factory = provider === "openai" ? h.createOpenAIClient : provider === "google" ? h.createGoogleClient : provider === "xai" ? h.createXaiClient : h.createAnthropicClient;
+        const envVar = provider === "openai" ? "OPENAI_API_KEY" : provider === "google" ? "GOOGLE_API_KEY" : provider === "xai" ? "XAI_API_KEY" : "ANTHROPIC_API_KEY";
+        const key = process.env[envVar];
+        if (!key) {
+          log("");
+          log(chalk.red(`  ${envVar} is not set.`));
+          log(chalk.dim("  Tier 1 runs on YOUR key, on YOUR machine. CodeRifts never sees it, and"));
+          log(chalk.dim("  never pays for the run. Export the key and re-run, or use --mock for a"));
+          log(chalk.dim("  no-cost dry run of the harness path."));
+          return { ok: false, reason: "missing_key" };
+        }
+        client = factory({ apiKey: key, model });
+      }
+      const userNames = new Set(tools.map((t) => String(t.name || "").replace(/^coderifts\./, "")));
+      const withUserTable = fixtures.map((f) => ({
+        ...f,
+        available_tools: f.available_tools.filter((n) => userNames.has(String(n).replace(/^coderifts\./, "")))
+      }));
+      const unreachable = withUserTable.filter((f) => f.available_tools.length === 0).length;
+      if (unreachable) {
+        log(chalk.yellow(`  ${unreachable} fixture(s) have no matching tool in your table \u2014 they can only score as a miss.`));
+      }
+      const unanswerable = withUserTable.filter((f) => {
+        const want = String(f.expected_tool || "").replace(/^coderifts\./, "");
+        return want && want !== "none" && !userNames.has(want);
+      }).map((f) => f.id);
+      if (unanswerable.length) {
+        log(chalk.yellow(`  ${unanswerable.length} fixture(s) expect a tool your table does not offer (${unanswerable.join(", ")}) \u2014 they CANNOT score correct. That is your table, not your model.`));
+      }
+      const run = await h.runBenchmark({ modelId: model, client, fixtures: withUserTable });
+      const m = run && run.metrics ? run.metrics : h.computeMetrics(run.results || []);
+      log("");
+      for (const k of ["selection_coverage", "bypass_rate", "omission_rate", "wrong_tool_rate", "overall_accuracy"]) {
+        if (m[k] !== void 0) log(`    ${String(k).padEnd(20)} ${m[k]}`);
+      }
+      return { ok: true, metrics: m };
+    }
+    async function runDoctor(options = {}) {
+      const log = options.logFn || ((s) => process.stdout.write(`${s}
+`));
+      const exitFn = options.exitFn || ((c) => process.exit(c));
+      if (!options.tools) {
+        log(chalk.red("  --tools <file> is required: the tools/list your host actually serves."));
+        log(chalk.dim(`    Save it with your MCP client, or: curl .../mcp -d '{"method":"tools/list"}' > tools.json`));
+        exitFn(2);
+        return { exitCode: 2 };
+      }
+      const parsed = readToolsFile(options.tools);
+      if (!parsed.ok) {
+        log(chalk.red(`  could not read the tool table: ${parsed.why}`));
+        exitFn(2);
+        return { exitCode: 2 };
+      }
+      if (options.model) {
+        const r = await runTier1({ tools: parsed.tools, model: options.model, log, mock: !!options.mock });
+        printBoundary(1, log);
+        const code = r.ok ? 0 : 1;
+        exitFn(code);
+        return { exitCode: code, tier: 1, metrics: r.metrics };
+      }
+      const report = tier0(parsed.tools);
+      renderTier0(report, log);
+      printBoundary(0, log);
+      exitFn(0);
+      return { exitCode: 0, tier: 0, report };
+    }
+    module2.exports = { runDoctor, readToolsFile, renderTier0, printBoundary };
+  }
+});
+
 // src/commands/publish-gate.js
 var require_publish_gate = __commonJS({
   "src/commands/publish-gate.js"(exports2, module2) {
@@ -264655,6 +264957,10 @@ program.command("deploy-gate").description("Gate a deploy on the current { envir
   const { runDeployGate } = require_deploy_gate2();
   await runDeployGate(options);
 });
+program.command("doctor").description("Would an agent select CodeRifts for a contract change? Structural check (no key), or the 15-fixture benchmark on your own model.").option("--tools <file>", "Your host's tools/list response (array, { tools }, or { result: { tools } })").option("--model <id>", "TIER 1: run the fixtures through this model using YOUR key from the environment").option("--mock", "TIER 1 dry run: a deterministic scripted model. Measures the script, not a model.").action(async (options) => {
+  const { runDoctor } = require_doctor2();
+  await runDoctor(options);
+});
 program.command("publish-gate").description("Gate npm publish on contract-artifact preflight (before=git baseline, after=working tree)").option("--spec <path>", "Contract artifact path (default: git config coderifts.specPath or api/openapi.yaml)").option("--json", "Machine-readable JSON result").action(async (options) => {
   const { runPublishGate } = require_publish_gate();
   const result = await runPublishGate(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coderifts",
-  "version": "8.1.0",
+  "version": "8.3.0",
   "description": "Detect breaking API changes from the command line. Works locally or with the CodeRifts cloud API.",
   "author": "CodeRifts <hello@coderifts.com>",
   "license": "MIT",
@@ -46,7 +46,7 @@
     "test": "node --test test/*.test.js"
   },
   "dependencies": {
-    "@coderifts/agent-guard": "^16.0.0",
+    "@coderifts/agent-guard": "^17.1.0",
     "chalk": "^4.1.2",
     "cli-table3": "^0.6.4",
     "commander": "^12.0.0",

package/scripts/assert-guard-major.js

@@ -73,6 +73,10 @@
  *   asVerifiedDeployReceiptView, DEPLOY_RECEIPT_VIEW_SPEC and matchGlob — no DeployGateReason
  *   exhaustive switch, no V2 config-conflict throw. The raise is installer-facing: the range
  *   is what `npm i -g coderifts` resolves.)
+ * 8.2.0: floor raised to 17 (published guard 17.0.0 is on npm; 17 blocks raw shell carrying a
+ *   mutation by default — a host-declared mutating_shell now reaches the block instead of dying at
+ *   the descriptor boundary. The CLI range must match so a fresh install gets the guard whose
+ *   default the docs describe.)
  * 8.1.0: floor raised to 16 (published guard 16.0.0 is on npm; 16 makes UNGUARDED_MUTATION
  *   fail-closed the default. The CLI range must match so `npm i -g coderifts` installs the guard
  *   whose default the docs describe, not the 15.x advisory-default it shipped alongside before.)
@@ -82,7 +86,7 @@ const fs = require('fs');
 const path = require('path');
 
 /** Minimum acceptable major for @coderifts/agent-guard in THIS package (the CLI). */
-const MIN_GUARD_MAJOR = 16;
+const MIN_GUARD_MAJOR = 17;
 const DEP = '@coderifts/agent-guard';
 
 /**