snipara-companion 3.2.31 → 3.2.32

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Release notes for `snipara-companion`, newest first.
 
+## New In 3.2.32
+
+- Promotes a Hosted MCP `servedJudgmentId` into the first-class Project
+  Intelligence brief so `run` can persist Advisor Influence receipts without a
+  fragile nested lookup or manual flag when the hosted brief already supplies
+  the identity.
+- Adds an explicit Advisor measurement funnel to JSON and text output:
+  identity linked/missing, targeted versus unscoped, acknowledged, applied,
+  verified, blocked, unmeasured, and receipt coverage.
+- Stores a bounded measurement state with each first-party receipt so a runtime
+  acknowledgement is never presented as recommendation-scoped application.
+- Emits one stable `project-intelligence.judgment-run-envelope.v1` per `run`
+  invocation. It reuses a bounded Snipara or Codex session id when available,
+  otherwise generates an opaque run id, and attaches the same envelope to every
+  first-party Advisor receipt.
+
 ## New In 3.2.31
 
 - Sends phase commits, final commits, and Team Sync handoffs to project-scoped

package/dist/index.d.ts

@@ -2086,6 +2086,7 @@ interface ProjectIntelligenceBriefOptions {
 interface ProjectIntelligenceBrief {
     version: "project-intelligence-brief-v1";
     generatedAt: string;
+    servedJudgmentId?: string;
     branch?: string;
     task?: string;
     changedFiles: string[];
@@ -2616,10 +2617,27 @@ interface ProjectRunAdvisorReceiptWrite {
     agentDecision?: AdvisorInfluenceAgentDecision;
     changedBecauseOfRecommendation?: boolean;
     lifecycleState?: AdvisorInfluenceLifecycleState;
+    measurementState?: ProjectRunAdvisorMeasurementState;
+    targeted?: boolean;
     result?: RecordAdvisorInfluenceReceiptResult;
     reason?: ProjectRunAdvisorReceiptSkipReason;
     error?: string;
 }
+type ProjectRunAdvisorMeasurementState = "unmeasured" | "acknowledged_unscoped" | "acknowledged" | "applied" | "verified" | "blocked";
+interface ProjectRunAdvisorMeasurementCoverage {
+    version: "project-intelligence.advisor-measurement-coverage.v1";
+    identityStatus: "linked" | "missing";
+    recommendationCount: number;
+    recordedCount: number;
+    targetedCount: number;
+    unscopedCount: number;
+    acknowledgedCount: number;
+    appliedCount: number;
+    verifiedCount: number;
+    blockedCount: number;
+    unmeasuredCount: number;
+    receiptCoverage: number | null;
+}
 type ProjectRunAdvisorReceiptSkipReason = "explicitly_skipped" | "no_advisor_recommendations" | "missing_served_judgment_id" | "no_plan_adaptation" | "write_limit_exceeded";
 interface ProjectRunAdvisorReceiptCapture {
     status: "skipped" | "recorded" | "partial" | "error";
@@ -2630,11 +2648,13 @@ interface ProjectRunAdvisorReceiptCapture {
     recordedCount: number;
     skippedCount: number;
     writes: ProjectRunAdvisorReceiptWrite[];
+    measurement: ProjectRunAdvisorMeasurementCoverage;
     reason?: ProjectRunAdvisorReceiptSkipReason;
 }
 interface ProjectIntelligenceRunResult {
     version: "project-intelligence.production-run.v1";
     generatedAt: string;
+    runEnvelope: ProjectIntelligenceRunEnvelope;
     release: boolean;
     brief: ProjectIntelligenceBrief;
     guard?: ProjectRunGuardResult;
@@ -2646,6 +2666,12 @@ interface ProjectIntelligenceRunResult {
     judgmentCard: ProjectIntelligenceJudgmentCard;
     suggestedCommands: string[];
 }
+interface ProjectIntelligenceRunEnvelope {
+    version: "project-intelligence.judgment-run-envelope.v1";
+    runId: string;
+    identitySource: "snipara_session" | "codex_session" | "generated";
+    startedAt: string;
+}
 interface ProjectRunPolicyDecisionRequests {
     version: "project-intelligence.policy-decision-requests.v1";
     emitted: boolean;

package/dist/index.js

@@ -32860,6 +32860,32 @@ async function verifyCommand(options) {
 }
 
 // src/commands/intelligence.ts
+function servedJudgmentIdFromContext(value, depth = 0) {
+  if (depth > 5 || value === null || value === void 0) return void 0;
+  if (Array.isArray(value)) {
+    for (const item of value.slice(0, 12)) {
+      const found = servedJudgmentIdFromContext(item, depth + 1);
+      if (found) return found;
+    }
+    return void 0;
+  }
+  if (!isRecord16(value)) return void 0;
+  const direct = value.servedJudgmentId ?? value.served_judgment_id;
+  if (typeof direct === "string" && direct.trim()) return direct.trim();
+  for (const key of [
+    "projectIntelligence",
+    "project_intelligence",
+    "brief",
+    "judgment",
+    "resumeContext",
+    "resume_context",
+    "data"
+  ]) {
+    const found = servedJudgmentIdFromContext(value[key], depth + 1);
+    if (found) return found;
+  }
+  return void 0;
+}
 function isRecord16(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -33082,6 +33108,8 @@ async function buildProjectIntelligenceBrief(options) {
       ...changedFiles.length > 0 ? { changedFiles } : {},
       max_tokens: options.maxTokens ?? 4e3
     });
+    const servedJudgmentId = servedJudgmentIdFromContext(brief.resumeContext);
+    if (servedJudgmentId) brief.servedJudgmentId = servedJudgmentId;
   } catch (error) {
     errors.push({
       surface: "resume_context",
@@ -34686,6 +34714,7 @@ async function referencesIngestCommand(options) {
 
 // src/commands/run.ts
 var import_node_child_process15 = require("child_process");
+var import_node_crypto10 = require("crypto");
 var fs33 = __toESM(require("fs"));
 var path33 = __toESM(require("path"));
 var import_chalk14 = __toESM(require("chalk"));
@@ -35116,6 +35145,16 @@ function formatPolicyGateDecision(gateDecision) {
 var GUARD_MAX_BUFFER_BYTES = 16 * 1024 * 1024;
 var RAW_OUTPUT_PREVIEW_BYTES = 64e3;
 var ADVISOR_RECEIPT_WRITE_LIMIT = 6;
+function buildProjectIntelligenceRunEnvelope(startedAt = /* @__PURE__ */ new Date()) {
+  const sniparaSessionId = stringValue14(process.env.SNIPARA_SESSION_ID)?.slice(0, 200);
+  const codexSessionId = stringValue14(process.env.CODEX_SESSION_ID)?.slice(0, 200);
+  return {
+    version: "project-intelligence.judgment-run-envelope.v1",
+    runId: sniparaSessionId ?? codexSessionId ?? `judgment-run:${(0, import_node_crypto10.randomUUID)()}`,
+    identitySource: sniparaSessionId ? "snipara_session" : codexSessionId ? "codex_session" : "generated",
+    startedAt: startedAt.toISOString()
+  };
+}
 function normalizeStringList6(values) {
   return [...new Set((values ?? []).map((value) => value.trim()).filter(Boolean))];
 }
@@ -35171,39 +35210,32 @@ function outputPreview(value) {
 function stringValue14(value) {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
 }
-function servedJudgmentIdFromUnknown(value, depth = 0) {
-  if (depth > 5 || value === null || value === void 0) {
-    return void 0;
-  }
-  if (!isRecord18(value)) {
-    if (Array.isArray(value)) {
-      for (const item of value.slice(0, 12)) {
-        const found = servedJudgmentIdFromUnknown(item, depth + 1);
-        if (found) return found;
-      }
-    }
-    return void 0;
-  }
-  const direct = stringValue14(value.servedJudgmentId) ?? stringValue14(value.served_judgment_id);
-  if (direct) {
-    return direct;
-  }
-  for (const key of [
-    "projectIntelligence",
-    "project_intelligence",
-    "brief",
-    "judgment",
-    "resumeContext",
-    "resume_context",
-    "data"
-  ]) {
-    const found = servedJudgmentIdFromUnknown(value[key], depth + 1);
-    if (found) return found;
-  }
-  return void 0;
-}
 function servedJudgmentIdForRun(options, brief) {
-  return stringValue14(options.servedJudgmentId) ?? servedJudgmentIdFromUnknown(brief.resumeContext) ?? servedJudgmentIdFromUnknown(brief.verificationPlan);
+  return stringValue14(options.servedJudgmentId) ?? stringValue14(brief.servedJudgmentId) ?? servedJudgmentIdFromContext(brief.resumeContext) ?? servedJudgmentIdFromContext(brief.verificationPlan);
+}
+function advisorMeasurementState(args) {
+  if (args.agentDecision === "blocked") return "blocked";
+  if (args.lifecycle.state === "verified") return "verified";
+  if (args.lifecycle.state === "applied") return "applied";
+  return args.planScope.targeted ? "acknowledged" : "acknowledged_unscoped";
+}
+function advisorMeasurementCoverage(args) {
+  const states = args.writes.map((write) => write.measurementState ?? "unmeasured");
+  const recordedCount = args.writes.filter((write) => write.status === "recorded").length;
+  return {
+    version: "project-intelligence.advisor-measurement-coverage.v1",
+    identityStatus: args.servedJudgmentId ? "linked" : "missing",
+    recommendationCount: args.recommendationCount,
+    recordedCount,
+    targetedCount: args.writes.filter((write) => write.targeted === true).length,
+    unscopedCount: states.filter((state) => state === "acknowledged_unscoped").length,
+    acknowledgedCount: states.filter((state) => state === "acknowledged").length,
+    appliedCount: states.filter((state) => state === "applied").length,
+    verifiedCount: states.filter((state) => state === "verified").length,
+    blockedCount: states.filter((state) => state === "blocked").length,
+    unmeasuredCount: Math.max(0, args.recommendationCount - recordedCount),
+    receiptCoverage: args.recommendationCount > 0 ? recordedCount / args.recommendationCount : null
+  };
 }
 function normalizeAdvisorSource(value) {
   if (value === "judgment" || value === "outcome_calibration" || value === "historical_impact" || value === "safety" || value === "verification" || value === "context_quality") {
@@ -35351,7 +35383,8 @@ function advisorReceiptMetadata(args) {
     source: "snipara-companion:run",
     firstParty: true,
     runVersion: "project-intelligence.production-run.v1",
-    runId: process.env.SNIPARA_SESSION_ID ?? process.env.CODEX_SESSION_ID ?? null,
+    runId: args.runEnvelope.runId,
+    runEnvelope: args.runEnvelope,
     generatedAt: args.judgmentCard.generatedAt,
     release: Boolean(args.options.release),
     task: args.brief.task ?? args.options.task ?? null,
@@ -35363,6 +35396,12 @@ function advisorReceiptMetadata(args) {
     changedBecauseOfRecommendation: args.lifecycle.planChange.changed,
     advisorInfluenceLifecycle: args.lifecycle,
     advisorPlanScope: args.planScope,
+    advisorMeasurement: {
+      version: "project-intelligence.advisor-measurement.v1",
+      state: args.measurementState,
+      targeted: args.planScope.targeted,
+      identityLinked: true
+    },
     toolActions,
     humanOverride: null,
     judgmentState: args.judgmentCard.state,
@@ -35504,7 +35543,9 @@ function emitPolicyDecisionRequests(run) {
 }
 async function recordFirstPartyAdvisorReceipts(args) {
   const allRecommendations = args.judgmentCard.advisorRecommendations;
+  const servedJudgmentId = servedJudgmentIdForRun(args.options, args.brief);
   if (args.options.skipAdvisorReceipts) {
+    const writes2 = [];
     return {
       status: "skipped",
       totalRecommendationCount: allRecommendations.length,
@@ -35512,11 +35553,17 @@ async function recordFirstPartyAdvisorReceipts(args) {
       attemptedCount: 0,
       recordedCount: 0,
       skippedCount: allRecommendations.length,
-      writes: [],
+      writes: writes2,
+      measurement: advisorMeasurementCoverage({
+        servedJudgmentId,
+        recommendationCount: allRecommendations.length,
+        writes: writes2
+      }),
       reason: "explicitly_skipped"
     };
   }
   if (allRecommendations.length === 0) {
+    const writes2 = [];
     return {
       status: "skipped",
       totalRecommendationCount: 0,
@@ -35524,11 +35571,11 @@ async function recordFirstPartyAdvisorReceipts(args) {
       attemptedCount: 0,
       recordedCount: 0,
       skippedCount: 0,
-      writes: [],
+      writes: writes2,
+      measurement: advisorMeasurementCoverage({ servedJudgmentId, recommendationCount: 0, writes: writes2 }),
       reason: "no_advisor_recommendations"
     };
   }
-  const servedJudgmentId = servedJudgmentIdForRun(args.options, args.brief);
   if (!servedJudgmentId) {
     const writes2 = allRecommendations.slice(0, ADVISOR_RECEIPT_WRITE_LIMIT).map(
       (recommendation) => skippedAdvisorReceiptWrite(recommendation, "missing_served_judgment_id")
@@ -35541,6 +35588,10 @@ async function recordFirstPartyAdvisorReceipts(args) {
       recordedCount: 0,
       skippedCount: writes2.length,
       writes: writes2,
+      measurement: advisorMeasurementCoverage({
+        recommendationCount: allRecommendations.length,
+        writes: writes2
+      }),
       reason: "missing_served_judgment_id"
     };
   }
@@ -35576,6 +35627,11 @@ async function recordFirstPartyAdvisorReceipts(args) {
           );
           const changedBecauseOfRecommendation = lifecycle.planChange.changed;
           const verificationExecuted = verificationExecutedFromLifecycle(lifecycle);
+          const measurementState = advisorMeasurementState({
+            agentDecision,
+            lifecycle,
+            planScope
+          });
           try {
             const behaviorChange = advisorReceiptBehaviorChange({
               recommendation,
@@ -35600,7 +35656,9 @@ async function recordFirstPartyAdvisorReceipts(args) {
                 totalRecommendations: allRecommendations.length,
                 verificationEvidence,
                 lifecycle,
-                planScope
+                planScope,
+                measurementState,
+                runEnvelope: args.runEnvelope
               })
             });
             return {
@@ -35609,6 +35667,8 @@ async function recordFirstPartyAdvisorReceipts(args) {
               agentDecision,
               changedBecauseOfRecommendation,
               lifecycleState: lifecycle.state,
+              measurementState,
+              targeted: planScope.targeted,
               result
             };
           } catch (error) {
@@ -35618,6 +35678,8 @@ async function recordFirstPartyAdvisorReceipts(args) {
               agentDecision,
               changedBecauseOfRecommendation,
               lifecycleState: lifecycle.state,
+              measurementState: "unmeasured",
+              targeted: planScope.targeted,
               error: error instanceof Error ? error.message : String(error)
             };
           }
@@ -35643,7 +35705,12 @@ async function recordFirstPartyAdvisorReceipts(args) {
     attemptedCount: eligibleCount,
     recordedCount,
     skippedCount,
-    writes
+    writes,
+    measurement: advisorMeasurementCoverage({
+      servedJudgmentId,
+      recommendationCount: allRecommendations.length,
+      writes
+    })
   };
 }
 function runGuard(options, changedFiles) {
@@ -35721,6 +35788,7 @@ function runPackageReview(options) {
   }
 }
 async function buildProjectIntelligenceRun(options) {
+  const runEnvelope = buildProjectIntelligenceRunEnvelope();
   const changedFiles = normalizeStringList6(options.changedFiles);
   const brief = await buildProjectIntelligenceBrief({
     task: options.task,
@@ -35803,7 +35871,8 @@ async function buildProjectIntelligenceRun(options) {
     brief,
     judgmentCard,
     verificationEvidence,
-    outcomeReceipts
+    outcomeReceipts,
+    runEnvelope
   });
   const suggestedCommands3 = [
     ...brief.suggestedCommands,
@@ -35815,7 +35884,8 @@ async function buildProjectIntelligenceRun(options) {
   ];
   const result = {
     version: "project-intelligence.production-run.v1",
-    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    generatedAt: runEnvelope.startedAt,
+    runEnvelope,
     release: Boolean(options.release),
     brief,
     ...guard ? { guard } : {},
@@ -35841,6 +35911,7 @@ async function projectIntelligenceRunCommand(options) {
       console.log(`Task: ${result.brief.task}`);
     }
     console.log(`Release: ${result.release ? "yes" : "no"}`);
+    console.log(`Run: ${result.runEnvelope.runId} (${result.runEnvelope.identitySource})`);
     console.log("");
     console.log(import_chalk14.default.bold("Project Judgment"));
     for (const line of formatProjectJudgmentCard(result.judgmentCard)) {
@@ -35888,6 +35959,10 @@ async function projectIntelligenceRunCommand(options) {
       console.log(
         `Recorded: ${result.advisorReceiptCapture.recordedCount}/${result.advisorReceiptCapture.attemptedCount}`
       );
+      const measurement = result.advisorReceiptCapture.measurement;
+      console.log(
+        `Measurement: ${measurement.identityStatus}; targeted ${measurement.targetedCount}, unscoped ${measurement.unscopedCount}, applied ${measurement.appliedCount}, verified ${measurement.verifiedCount}, unmeasured ${measurement.unmeasuredCount}`
+      );
       if (result.advisorReceiptCapture.skippedCount > 0) {
         console.log(`Skipped: ${result.advisorReceiptCapture.skippedCount}`);
       }

package/docs/FULL_REFERENCE.md

@@ -1240,8 +1240,11 @@ snipara-companion run \
 package-surface review, verification plan, and final Judgment Card. Review-only
 guard findings can be acknowledged with the printed guard action card command;
 blocking conflicts still make the release judgment non-proceedable.
-When a served judgment id is available, add `--served-judgment-id` so `run` can
-write first-party Advisor Influence receipts. Receipts now follow an explicit
+When Hosted MCP returns a served judgment id, Companion promotes it to the
+first-class `brief.servedJudgmentId` field and uses it automatically. The
+`--served-judgment-id` option remains an explicit override and compatibility
+path. Without either identity, receipt capture remains fail-closed and reports
+`missing_served_judgment_id`. Receipts follow an explicit
 `proposed -> acknowledged -> applied -> verified` lifecycle. A served
 recommendation is only `acknowledged` by default: its `expectedBehaviorChange`,
 severity, required actions, and recommended checks never prove adaptation.
@@ -1266,6 +1269,21 @@ plan changed. Without a selector, or when the selector matches none of them,
 every recommendation remains `acknowledged`; one global plan diff is never
 credited to all recommendations.
 
+The `advisorReceiptCapture.measurement` object makes that boundary measurable.
+It reports linked or missing judgment identity, targeted and unscoped receipt
+counts, acknowledged/applied/verified/blocked states, unmeasured
+recommendations, and total receipt coverage. An unscoped acknowledgement proves
+only that the first-party runtime saw the recommendation; it does not prove the
+agent selected, applied, or verified it.
+
+Every invocation also emits one
+`project-intelligence.judgment-run-envelope.v1` at top-level. The envelope
+contains a bounded opaque `runId`, its identity source, and `startedAt`; the
+same object is attached to every first-party Advisor receipt created by that
+invocation. A hosted Snipara session id wins, then a Codex session id, with a
+generated UUID fallback. This makes execution-level funnels available even
+when the caller did not inject a session environment variable.
+
 Missing, partial, or hash-identical snapshots remain `acknowledged`. An applied
 receipt becomes `verified` only when `--outcome-receipts` supplies a receipt
 whose `decision.advisorRecommendationIds` contains that recommendation id and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snipara-companion",
-  "version": "3.2.31",
+  "version": "3.2.32",
   "description": "Local-first CLI that asks your repo what breaks before an AI coding agent edits it.",
   "main": "dist/index.js",
   "bin": {