blun-king-cli 9.1.587 → 9.1.588

package/agent-spine-plugin/src/lib/gateway-group-response.js

@@ -0,0 +1,128 @@
+import { channelRuntimeFindings, claimChannelEvent, completeChannelEvent, loadChannelPolicy, loadChannelRuntime } from "./channel-runtime.js";
+import { loadGraph } from "./graph.js";
+import { emptyPolicy, emptyRuntime, exactId, sha256, timestamp } from "./gateway-common.js";
+import { assertActivePersona, exactReplyBinding } from "./gateway-runtime-identity.js";
+import { appendReceipt } from "./gateway-runtime-records.js";
+import { normalizePolicy, normalizeRuntime, pathsFor, readJson, withLock } from "./gateway-state.js";
+import { loadPersonaRuntime } from "./persona-runtime.js";
+
+const SCHEMA = "agentspine.group-response/v1";
+const CONTRIBUTIONS = new Set(["idea", "error", "improvement"]);
+
+// This is a host result contract, not a permission or an objective evaluation.
+export function groupResponseContract(event) {
+  if (!event?.groupId) return null;
+  return { schema: SCHEMA, defaultKind: "silence", kinds: ["silence", "answer", ...CONTRIBUTIONS],
+    eventId: event.eventId, sessionKey: event.sessionKey, groupId: event.groupId,
+    authority: "context-only", directAddressVerified: false,
+    instruction: "Without a direct request, stay silent unless contributing a relevant idea, concrete error, or improvement. Return groupResponse with this schema and kind; silence has no text. Contributions need a stable subjectId. Answer direct requests normally. Suggestions are not verified facts. Do not echo bot status messages." };
+}
+
+export function reviewGroupResponse({ result, text, event, item, runtime, current }) {
+  if (result?.groupResponse === undefined) return null; // Preserve the legacy reply contract.
+  const response = result.groupResponse;
+  if (!event?.groupId || event.privacy !== "group" || event.groupId !== item.groupId
+    || event.projectId !== item.projectId || event.agentId !== item.agentId) {
+    throw new Error("group response requires the exact group channel work item");
+  }
+  if (!response || Array.isArray(response) || response.schema !== SCHEMA
+    || !["silence", "answer", ...CONTRIBUTIONS].includes(response.kind)) {
+    throw new Error("unknown group response contract or kind");
+  }
+  const contribution = CONTRIBUTIONS.has(response.kind);
+  const keys = contribution ? ["schema", "kind", "subjectId"] : ["schema", "kind"];
+  if (Object.keys(response).length !== keys.length || Object.keys(response).some((key) => !keys.includes(key))) {
+    throw new Error("group response fields do not match its kind");
+  }
+  if (response.kind === "silence" && result.text !== undefined && result.text !== null && result.text !== "") {
+    throw new Error("silent group response must not contain text or a visible placeholder");
+  }
+  if (response.kind !== "silence" && !text) throw new Error("group contribution or answer requires text");
+  let contributionDigest = null;
+  let duplicate = false;
+  if (contribution) {
+    const subjectId = exactId(response.subjectId, "groupResponse.subjectId");
+    // The gateway derives the digest. Changing an event ID cannot repeat the same
+    // contribution; different private routes and sessions never share dedupe state.
+    contributionDigest = sha256(JSON.stringify([event.provider, event.tenantId, event.accountId,
+      event.bindingId, event.agentId, event.projectId, event.groupId, event.chatId, event.threadId,
+      event.sessionKey, subjectId, text]));
+    duplicate = runtime.receipts.some((receipt) => receipt.kind === "group-contribution-prepared"
+      && receipt.details.schema === SCHEMA && receipt.details.contributionDigest === contributionDigest);
+  }
+  const suppressed = response.kind === "silence" || duplicate;
+  if (suppressed || contribution) appendReceipt(runtime,
+    suppressed ? "group-response-suppressed" : "group-contribution-prepared", item.queueId, current,
+    { schema: SCHEMA, eventId: event.eventId, bindingId: event.bindingId,
+      kind: response.kind, reason: duplicate ? "duplicate" : response.kind,
+      contributionDigest, deliveryConfirmed: false, completionVerified: false });
+  return { schema: SCHEMA, kind: response.kind, suppressed, duplicate,
+    deliveryConfirmed: false, completionVerified: false };
+}
+
+// Recover the local acknowledgement after the gateway transaction commits.
+// No adapter, outbox or delivery receipt is involved. A crash between claim and
+// completion resumes the same lease, or reacquires it after its original expiry.
+export async function settleSuppressedGroupEvents({ root = process.cwd(), now = new Date() } = {}) {
+  const paths = await pathsFor(root);
+  return withLock(paths, async () => {
+    const [policy, runtime, channelPolicy, channel, personas] = await Promise.all([
+      readJson(paths.gatewayPolicyPath, paths.catalog.root, normalizePolicy, emptyPolicy),
+      readJson(paths.gatewayRuntimePath, paths.catalog.root, normalizeRuntime, emptyRuntime),
+      loadChannelPolicy(paths.catalog.root, paths.catalog), loadChannelRuntime(paths.catalog.root, paths.catalog),
+      loadPersonaRuntime(paths.catalog.root, paths.catalog)
+    ]);
+    if (!policy.enabled || policy.killSwitch) return { settled: 0 };
+    const current = timestamp(now);
+    let settled = 0; let deferred = 0;
+    const pending = runtime.receipts.filter((receipt) => receipt.kind === "group-response-suppressed"
+      && channel.runtime.events.some((event) => event.eventId === receipt.details.eventId
+        && !["completed", "cancelled"].includes(event.status)));
+    if (pending.length) {
+      const { graph } = await loadGraph(paths.catalog.root, paths.catalog);
+      if (channelRuntimeFindings(channel.runtime, channelPolicy.policy, graph).length) {
+        throw new Error("suppressed channel event integrity mismatch");
+      }
+    }
+    for (const receipt of pending) {
+      if (settled >= 20) break;
+      if (receipt.details.schema !== SCHEMA) throw new Error("unknown group response receipt version");
+      const item = runtime.queue.find((entry) => entry.queueId === receipt.objectId);
+      const event = channel.runtime.events.find((entry) => entry.eventId === receipt.details.eventId);
+      if (!item || item.status !== "completed" || item.channelEventId !== event.eventId
+        || item.groupId !== event.groupId || item.agentId !== event.agentId || item.projectId !== event.projectId
+        || !event.groupId || receipt.details.bindingId !== event.bindingId
+        || runtime.outbox.some((entry) => entry.queueId === item.queueId)) {
+        throw new Error("suppressed group response lost its exact no-delivery binding");
+      }
+      try {
+        assertActivePersona(personas.policy, personas.runtime, item.agentId, item.projectId, item.groupId);
+        exactReplyBinding(channelPolicy.policy, event);
+      } catch {
+        // Revocation keeps this event untouched, without stopping other work.
+        deferred += 1;
+        continue;
+      }
+      const workerId = "group-silence:" + sha256(item.queueId).slice(0, 32);
+      try {
+        if (event.status === "leased" && new Date(event.lease.expiresAt) > new Date(current)) {
+          if (event.lease.workerId !== workerId) { deferred += 1; continue; }
+        } else {
+          const claim = await claimChannelEvent({ root: paths.catalog.root, agentId: event.agentId,
+            projectId: event.projectId, groupId: event.groupId, provider: event.provider,
+            eventId: event.eventId, workerId, now: current, catalog: paths.catalog });
+          if (!claim.event) { deferred += 1; continue; }
+        }
+        await completeChannelEvent({ root: paths.catalog.root, eventId: event.eventId,
+          workerId, status: "completed", now: current });
+        settled += 1;
+      } catch {
+        // Local acknowledgement is recoverable bookkeeping, not a new work gate.
+        // Keep the durable suppression and do not claim acknowledgement succeeded.
+        deferred += 1;
+        break; // Do not repeat the same unavailable channel service in this tick.
+      }
+    }
+    return { settled, deferred };
+  });
+}

package/agent-spine-plugin/src/lib/gateway-runs.js

@@ -1,4 +1,5 @@
 import { loadChannelPolicy, loadChannelRuntime } from "./channel-runtime.js";
+import { reviewGroupResponse } from "./gateway-group-response.js";
 import {
   assertGatewayCompletionMode, exactGatewayLeaseGeneration, failGatewayLane,
   markHostStarted, newGatewayLease, normalizeGatewayExecutionMode,
@@ -156,26 +157,35 @@ export async function completeGatewayRun({ root = process.cwd(), queueId, worker
       executionReview = { passed: false, outcome: null, reason: "Execution outcome history is full." };
     }
     const text = result?.text ? safeText(result.text, "result.text", 16000) : null;
+    if (result?.groupResponse !== undefined && !item.channelEventId) {
+      throw new Error("group response requires channel work");
+    }
+    let communication = null;
     let clarification = null; let exploration = null; let selfHelp = null; let selfHelpRequired = null;
     preserve(runtime, "queue", item, "run-completed", current);
     if (item.channelEventId) {
-      if (!text) throw new Error("a channel obligation requires a non-empty response");
-      const voice = evaluateVoiceOutput(text);
-      if (!voice.ok) throw new Error("channel response contains a prohibited attachment or consciousness claim");
       const event = channelRuntime.runtime.events.find((entry) => entry.eventId === item.channelEventId);
       if (!event) throw new Error("channel event disappeared before delivery preparation");
       const binding = exactReplyBinding(channelPolicy.policy, event);
-      const idempotencyKey = "delivery:" + sha256([event.eventId, binding.id, event.chatId, event.threadId || "", event.replyTo || ""].join("\0")).slice(0, 32);
-      let outbox = runtime.outbox.find((entry) => entry.idempotencyKey === idempotencyKey);
-      if (!outbox) {
-        outbox = { outboxId: "gateway-outbox:" + sha256(idempotencyKey).slice(0, 32), queueId: item.queueId,
-          idempotencyKey, bindingId: binding.id, eventId: event.eventId, provider: event.provider, tenantId: event.tenantId,
-          accountId: event.accountId, chatId: event.chatId, threadId: event.threadId, replyTo: event.replyTo,
-          text, status: "prepared", attempts: 0, nextAttemptAt: current, createdAt: current, updatedAt: current,
-          deliveredAt: null, adapterReceipt: null, lastError: null, authority: "delivery-state-only" };
-        runtime.outbox.push(outbox);
+      communication = reviewGroupResponse({ result, text, event, item, runtime, current });
+      if (communication?.suppressed) {
+        item.status = "completed"; item.completedAt = current;
+      } else {
+        if (!text) throw new Error("a channel obligation requires a non-empty response");
+        const voice = evaluateVoiceOutput(text);
+        if (!voice.ok) throw new Error("channel response contains a prohibited attachment or consciousness claim");
+        const idempotencyKey = "delivery:" + sha256([event.eventId, binding.id, event.chatId, event.threadId || "", event.replyTo || ""].join("\0")).slice(0, 32);
+        let outbox = runtime.outbox.find((entry) => entry.idempotencyKey === idempotencyKey);
+        if (!outbox) {
+          outbox = { outboxId: "gateway-outbox:" + sha256(idempotencyKey).slice(0, 32), queueId: item.queueId,
+            idempotencyKey, bindingId: binding.id, eventId: event.eventId, provider: event.provider, tenantId: event.tenantId,
+            accountId: event.accountId, chatId: event.chatId, threadId: event.threadId, replyTo: event.replyTo,
+            text, status: "prepared", attempts: 0, nextAttemptAt: current, createdAt: current, updatedAt: current,
+            deliveredAt: null, adapterReceipt: null, lastError: null, authority: "delivery-state-only" };
+          runtime.outbox.push(outbox);
+        }
+        item.status = "awaiting-delivery";
       }
-      item.status = "awaiting-delivery";
     } else {
       item.status = result?.blocked || knowledgeGapRequest || premortemReview?.blocked || (executionReview && !executionReview.passed)
         ? "blocked" : "completed"; item.completedAt = current;
@@ -270,7 +280,7 @@ export async function completeGatewayRun({ root = process.cwd(), queueId, worker
     appendReceipt(runtime, "run-terminal", item.queueId, current, { status: item.status, goalStepId: item.goalStepId || null }); runtime.revision += 1;
     await writeGatewayStatePair(policy, runtime);
     return { item, outbox: runtime.outbox.find((entry) => entry.queueId === item.queueId) || null,
-      clarification, exploration, selfHelp, selfHelpRequired, executionReview, premortemReview };
+      clarification, exploration, selfHelp, selfHelpRequired, executionReview, premortemReview, communication };
   });
 }
 
@@ -297,4 +307,3 @@ export async function failGatewayRun({ root = process.cwd(), queueId, workerId,
     return { item, receipt: failure.receipt, policyEnabled: policy.enabled && !policy.killSwitch };
   });
 }
-

package/agent-spine-plugin/src/lib/hook-briefing-use.js

@@ -29,7 +29,16 @@ function unverified(reason) {
     automaticRetry: false, completionVerified: false, authority: "context-only" };
 }
 
-export async function recordHookBriefingUse({ origin, root, now = new Date() }) {
+function validHandoff(value) {
+  return value?.schema === "agentspine.host-context-handoff/v1"
+    && ["additionalContext", "message"].includes(value.field)
+    && ["claude", "codex", "generic", "king"].includes(value.host)
+    && Number.isSafeInteger(value.bytes) && value.bytes > 0
+    && /^[a-f0-9]{64}$/.test(value.digest || "");
+}
+
+export async function recordHookBriefingUse({ origin, root, handoff, now = new Date() }) {
+  if (!validHandoff(handoff)) return unverified("host-context-handoff-unavailable");
   const proof = verified.get(origin);
   if (!verified.delete(origin)) return unverified("host-briefing-origin-unavailable");
   try {
@@ -51,10 +60,11 @@ export async function recordHookBriefingUse({ origin, root, now = new Date() })
       return unverified("host-briefing-binding-mismatch");
     }
     const usage = await recordDeliveryBriefingUse({ root, requirementId,
-      preserveConsumed: true, verifiedHostBriefing: true,
+      preserveConsumed: true, verifiedHostHandoff: true,
       input: { origin: "verified-host-preflight", receiptId: receipt.id,
         promptDigest: receipt.promptDigest, requirementId },
-      result: { briefingDigest: receipt.briefingDigest, sourceSnapshotDigest: receipt.bodyDigest }, now });
+      result: { briefingDigest: receipt.briefingDigest, sourceSnapshotDigest: receipt.bodyDigest,
+        handoff: structuredClone(handoff) }, now });
     return { ...usage, verified: ["recorded", "duplicate"].includes(usage.status),
       automaticRetry: false, completionVerified: false };
   } catch { return unverified("host-briefing-service-unavailable"); }

package/agent-spine-plugin/src/lib/hook-context.js

@@ -58,6 +58,9 @@ export function hostFromInput(input) {
 
 export function gatewayEnvironmentContext(env = process.env) {
   if (env.AGENTSPINE_GATEWAY_CONTEXT !== "agentspine.gateway-start/v1") return null;
+  const portalRef = boundedId(env.AGENTSPINE_PORTAL_REF, "AGENTSPINE_PORTAL_REF");
+  const threadRef = boundedId(env.AGENTSPINE_THREAD_REF, "AGENTSPINE_THREAD_REF");
+  if (Boolean(portalRef) !== Boolean(threadRef)) throw new Error("gateway portal and thread references must be paired");
   return {
     host: boundedId(env.AGENTSPINE_HOST, "AGENTSPINE_HOST"),
     entityId: boundedId(env.AGENTSPINE_ENTITY_ID, "AGENTSPINE_ENTITY_ID"),
@@ -71,7 +74,8 @@ export function gatewayEnvironmentContext(env = process.env) {
       "AGENTSPINE_PLAN_DEFINITIONS_DIGEST"),
     gatewayAttempt: positiveInteger(env.AGENTSPINE_GATEWAY_ATTEMPT, "AGENTSPINE_GATEWAY_ATTEMPT"),
     eventId: boundedId(env.AGENTSPINE_CHANNEL_EVENT_ID, "AGENTSPINE_CHANNEL_EVENT_ID"),
-    provider: boundedId(env.AGENTSPINE_CHANNEL_PROVIDER, "AGENTSPINE_CHANNEL_PROVIDER")
+    provider: boundedId(env.AGENTSPINE_CHANNEL_PROVIDER, "AGENTSPINE_CHANNEL_PROVIDER"),
+    portalRef, threadRef
   };
 }
 
@@ -116,6 +120,11 @@ export async function runtimeScope(input, root, userStateRoot = null, catalog) {
   const gateway = gatewayEnvironmentContext();
   const suppliedAttempt = positiveInteger(supplied.gateway_attempt ?? supplied.gatewayAttempt,
     "gatewayAttempt");
+  const suppliedPortalRef = supplied.portal_ref ?? supplied.portalRef;
+  const suppliedThreadRef = supplied.thread_ref ?? supplied.threadRef;
+  if (!gateway && [suppliedPortalRef, suppliedThreadRef].some((value) => value !== undefined && value !== null && value !== "")) {
+    throw new Error("portal timeline scope requires an authenticated gateway binding");
+  }
   return {
     entityId: boundedId(gatewayBound(gateway, "entityId",
       supplied.entity_id ?? supplied.entityId, "entityId")
@@ -139,6 +148,8 @@ export async function runtimeScope(input, root, userStateRoot = null, catalog) {
       supplied.plan_definitions_digest ?? supplied.planDefinitionsDigest,
       "planDefinitionsDigest"), "planDefinitionsDigest"),
     gatewayAttempt: gatewayBound(gateway, "gatewayAttempt", suppliedAttempt, "gatewayAttempt"),
+    portalRef: boundedId(gatewayBound(gateway, "portalRef", suppliedPortalRef, "portalRef"), "portalRef"),
+    threadRef: boundedId(gatewayBound(gateway, "threadRef", suppliedThreadRef, "threadRef"), "threadRef"),
     host: gateway
       ? gatewayBound(gateway, "host", input.host ?? input.provider, "host")
       : hostFromInput(input),
@@ -214,7 +225,8 @@ export function renderContext(event, catalog, briefing, signal = null, attention
     sourceResolution: sourceDiagnostics,
     lessonRecall: lessonRecall?.status === "recalled" ? {
       status: "recalled", schema: lessonRecall.schema, receiptDigest: lessonRecall.receiptDigest,
-      items: lessonRecall.items, omitted: lessonRecall.omitted,
+      items: lessonRecall.items, learning: lessonRecall.learning || [],
+      learningDiagnostics: lessonRecall.learningDiagnostics || null, omitted: lessonRecall.omitted,
       instruction: lessonRecall.instruction, authority: "context-only"
     } : lessonRecall?.status === "group-suppressed" ? {
       status: "group-suppressed", items: [], authority: "context-only"
@@ -260,7 +272,8 @@ export function selfstarterInput(input) {
 
 function channelEventInput(input) {
   const gateway = gatewayEnvironmentContext();
-  const value = input.agent_spine_channel_event ?? (gateway?.eventId && gateway?.provider
+  const value = input.agent_spine_channel_event ?? (input.hook_event_name === "SessionStart"
+    && gateway?.eventId && gateway?.provider
     ? { event_id: gateway.eventId, provider: gateway.provider } : null);
   if (value === undefined || value === null) return null;
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("agent_spine_channel_event must be one object");

package/agent-spine-plugin/src/lib/hook-output.js

@@ -1,6 +1,116 @@
 const BLUN_MESSAGE_MAX_BYTES = 1200;
 const BLUN_BOUND_MARKER = "\n[optional runtime detail omitted: 1200-byte bound]";
 
+function byteSize(value) {
+  return Buffer.byteLength(JSON.stringify(value));
+}
+
+function addRecallField(packet, key, value, maximum = 1020) {
+  if (value === undefined || value === null) return;
+  packet[key] = value;
+  if (byteSize(packet) <= maximum) return true;
+  delete packet[key];
+  return false;
+}
+
+function sharedPrefix(values) {
+  let prefix = values[0] || "";
+  for (const value of values.slice(1)) {
+    while (prefix && !value.startsWith(prefix)) prefix = prefix.slice(0, -1);
+  }
+  return prefix.length >= 4 ? prefix : "";
+}
+
+function compactCandidateRows(packet, candidates) {
+  if (candidates.rows.length < 2) return;
+  if (!candidates.prefixes) {
+    const digest = candidates.fields.indexOf("digest");
+    if (digest >= 0 && candidates.rows.every((row) => row[digest] === candidates.rows[0][digest])) {
+      candidates.common = { ...(candidates.common || {}), digest: candidates.rows[0][digest] };
+      candidates.fields.splice(digest, 1);
+      for (const row of candidates.rows) row.splice(digest, 1);
+    }
+    candidates.prefixes = candidates.fields.map((field, index) => {
+      const values = candidates.rows.map((row) => row[index]);
+      const prefix = ["id", "message", "session"].includes(field) ? sharedPrefix(values)
+        : field === "at" && values.every((value) => /^\d{4}-\d{2}-\d{2}T\d{2}:/.test(value))
+          ? values[0].slice(0, 14) : "";
+      if (!prefix || !values.every((value) => value.startsWith(prefix))) return "";
+      for (const row of candidates.rows) row[index] = row[index].slice(prefix.length);
+      return prefix;
+    });
+  }
+  if (packet.task) {
+    delete packet.task.status;
+    if (packet.task.lastVerifiedStep) delete packet.task.lastVerifiedStep.result;
+  }
+  const review = packet.feedbackReview;
+  if (review?.modelClarification) packet.feedbackReview = {
+    status: review.status, completionVerified: false, target: review.targetAssertionId,
+    question: review.modelClarification.question, model: true
+  };
+}
+
+function compactFeedbackCandidates(packet) {
+  const candidates = packet.feedbackCandidates;
+  const proposal = packet.feedbackReview?.modelClarification;
+  if (proposal) for (const key of ["completionVerified", "provider", "replaces"]) delete proposal[key];
+  if (candidates && !Array.isArray(candidates)
+    && Array.isArray(candidates.fields) && Array.isArray(candidates.rows)) {
+    compactCandidateRows(packet, candidates);
+    return true;
+  }
+  if (!Array.isArray(candidates) || candidates.length < 2) return false;
+  const origins = ["provider", "session"];
+  const sharedKeys = origins.filter((key) =>
+    candidates.every((item) => item?.[key] === candidates[0]?.[key]));
+  const fields = ["id", "text", "digest", "message", "at",
+    ...origins.filter((key) => !sharedKeys.includes(key))];
+  packet.feedbackCandidates = {
+    fields,
+    ...(sharedKeys.length ? { common: Object.fromEntries(sharedKeys.map((key) =>
+      [key, candidates[0][key]])) } : {}),
+    rows: candidates.map((item) => fields.map((key) => item[key]))
+  };
+  compactCandidateRows(packet, packet.feedbackCandidates);
+  return true;
+}
+
+export function preAnswerRecallCapsule(detailed) {
+  if (detailed?.event !== "UserPromptSubmit" || !detailed.loaded) return null;
+  const briefing = detailed.briefing;
+  const preflight = detailed.preflight?.briefing;
+  if (!briefing || !preflight) return null;
+  if (briefing.scope?.groupId !== null && briefing.scope?.groupId !== undefined) return null;
+  const omitted = [];
+  const packet = briefing.preAnswerRecall ? { ...briefing.preAnswerRecall } : {
+    schema: "agentspine.pre-answer-recall/v1",
+    order: "review-before-claims-and-actions",
+    authority: "context-only"
+  };
+  const mustRemember = (preflight.mustRemember || []).map((item) => ({
+    id: item.id, claim: item.claim, checksum: item.checksum
+  }));
+  if (mustRemember.length && !addRecallField(packet, "mustRemember", mustRemember)) {
+    if (!compactFeedbackCandidates(packet)
+      || !addRecallField(packet, "mustRemember", mustRemember, BLUN_MESSAGE_MAX_BYTES)) {
+      omitted.push("mustRemember");
+    }
+  }
+  const retrieval = (preflight.retrieval || []).flatMap((provider) =>
+    (provider.items || []).map((item) => ({ providerId: provider.providerId,
+      id: item.id, revision: item.revision, claim: item.claim, source: item.source }))).slice(0, 3);
+  if (retrieval.length && !addRecallField(packet, "retrieval", retrieval)) {
+    if (!compactFeedbackCandidates(packet)
+      || !addRecallField(packet, "retrieval", retrieval, BLUN_MESSAGE_MAX_BYTES)) {
+      omitted.push("retrieval");
+    }
+  }
+  compactFeedbackCandidates(packet);
+  if (omitted.length && byteSize({ ...packet, omitted }) <= BLUN_MESSAGE_MAX_BYTES) packet.omitted = omitted;
+  return Object.keys(packet).length > 3 ? packet : null;
+}
+
 function compactPremortemRegistration(premortem, includeRoot = true) {
   const root = premortem?.registration?.root;
   const requirementId = premortem?.requirementId || premortem?.registration?.requirementId;
@@ -37,6 +147,8 @@ export function blunRuntimeContext(context) {
       : detailed.instruction,
     authority: "context-only"
   };
+  const recall = preAnswerRecallCapsule(detailed);
+  if (recall) runtime.preAnswerRecall = recall;
   if (detailed.signal && (detailed.signal.captured || detailed.signal.accepted || detailed.signal.reason)) {
     runtime.signal = detailed.signal;
   }
@@ -56,7 +168,9 @@ export function blunRuntimeMessage(context) {
   const runtime = JSON.parse(blunRuntimeContext(context));
   const warning = runtime.sourceResolution?.incomplete ? ` Warning: ${runtime.sourceResolution.warning}` : "";
   const base = runtime.loaded
-    ? `AgentSpine ready: ${runtime.indexedSources} sources indexed. Load detailed continuity only on demand through session_briefing.${warning}`
+    ? runtime.preAnswerRecall
+      ? `AgentSpine ready: ${runtime.indexedSources} sources indexed.${warning}`
+      : `AgentSpine ready: ${runtime.indexedSources} sources indexed. Load detailed continuity only on demand through session_briefing.${warning}`
     : `AgentSpine unavailable${runtime.sourceResolution?.reason ? `: ${runtime.sourceResolution.reason}` : ""}. ${runtime.instruction}`;
   const active = {};
   if (runtime.signal && (runtime.signal.captured || runtime.signal.accepted
@@ -72,16 +186,24 @@ export function blunRuntimeMessage(context) {
   const details = Object.keys(active).length === 0
     ? ""
     : `\nActive AgentSpine runtime data: ${JSON.stringify(active)}`;
+  const recall = runtime.preAnswerRecall
+    ? `\n${JSON.stringify(runtime.preAnswerRecall)}`
+    : "";
   const root = runtime.premortem?.registration?.root;
   const instruction = typeof root === "string"
     ? runtime.premortem?.instruction?.replace("registration.root", () => `root ${JSON.stringify(root)}`)
     : runtime.premortem?.instruction;
   const premortem = instruction ? `\n${instruction}` : "";
-  const message = `${base}${details}${premortem}`;
+  const message = `${base}${recall}${details}${premortem}`;
   if (Buffer.byteLength(message) <= BLUN_MESSAGE_MAX_BYTES) return message;
-  const compact = `${base}${BLUN_BOUND_MARKER}\n${compactPremortemRegistration(runtime.premortem)}`;
+  const compact = `${base}${recall}${BLUN_BOUND_MARKER}\n${compactPremortemRegistration(runtime.premortem)}`;
   if (Buffer.byteLength(compact) <= BLUN_MESSAGE_MAX_BYTES) return compact;
-  return `${base}${BLUN_BOUND_MARKER}\n${compactPremortemRegistration(runtime.premortem, false)}`;
+  if (!runtime.preAnswerRecall) {
+    return `${base}${BLUN_BOUND_MARKER}\n${compactPremortemRegistration(runtime.premortem, false)}`;
+  }
+  const recallOnly = `${base}${recall}${BLUN_BOUND_MARKER}`;
+  if (Buffer.byteLength(recallOnly) <= BLUN_MESSAGE_MAX_BYTES) return recallOnly;
+  return Buffer.byteLength(recall)<=BLUN_MESSAGE_MAX_BYTES+1?recall.slice(1):`${base}\nRecall unavailable.`;
 }
 
 export function hookOutput(event, context, env = process.env) {
@@ -130,7 +252,9 @@ export function lifecycleOutput(event, artifactGuard, premortem, deliveryVerific
   if (lessonRecall?.status === "recalled") {
     messages.push(JSON.stringify({
       schema: lessonRecall.schema, receiptDigest: lessonRecall.receiptDigest,
-      instruction: lessonRecall.instruction, items: lessonRecall.items, omitted: lessonRecall.omitted,
+      instruction: lessonRecall.instruction, items: lessonRecall.items,
+      learning: lessonRecall.learning || [], learningDiagnostics: lessonRecall.learningDiagnostics || null,
+      omitted: lessonRecall.omitted,
       authority: "context-only"
     }));
   }

package/agent-spine-plugin/src/lib/hook-timeline.js

@@ -77,14 +77,16 @@ export async function finalizeUserPromptSessionTimeline({
 }) {
   const consumed = await consumeTimelineHostOrigin({ event: "UserPromptSubmit", input, scope, resolvedSources,
     preflight, prompt, environment: process.env, now });
-  if (!consumed?.consumed) return { preflightConsumed: false, timeline: unavailable("preflight-receipt-unavailable") };
+  if (!consumed?.consumed) return { preflightConsumed: false, briefingOrigin: null,
+    timeline: unavailable("preflight-receipt-unavailable") };
   try {
-    return { preflightConsumed: true, timeline: await captureSessionTimelineLifecycle({
+    return { preflightConsumed: true, briefingOrigin: consumed.briefingOrigin,
+      timeline: await captureSessionTimelineLifecycle({
       root, event: "UserPromptSubmit", input, scope, hostHome: resolvedSources.hostHome,
       hostOrigin: consumed.origin, clock: () => new Date(now)
     }) };
   } catch (error) {
-    return { preflightConsumed: true, timeline: {
+    return { preflightConsumed: true, briefingOrigin: consumed.briefingOrigin, timeline: {
       schema: "agentspine.session-timeline/v1", status: "degraded", reason: error.message, authority: AUTHORITY
     } };
   }

package/agent-spine-plugin/src/lib/indexed-memory.js

@@ -247,7 +247,7 @@ export async function resolveIndexedMemory({ root, scope = {}, env = process.env
   diagnostics.cacheHits += Number(index.cacheHit);
   diagnostics.cacheMisses += Number(!index.cacheHit);
   const entries = parseMemoryIndex(index.buffer.toString("utf8"), index.path, canonicalRoot);
-  if (entries.length > MAX_INDEXED_LINKS) throw new Error(`Claude MEMORY.md indexes more than ${MAX_INDEXED_LINKS} direct files`);
+  if (entries.length > MAX_INDEXED_LINKS) throw new Error(`MEMORY.md indexes more than ${MAX_INDEXED_LINKS} direct files`);
   diagnostics.indexed = entries.length;
   const sources = [{ path: index.path, relativePath: "MEMORY.md", snapshot: index, relevance: "index" }];
   const selected = [];
@@ -279,7 +279,7 @@ export async function resolveIndexedMemory({ root, scope = {}, env = process.env
   }
   checkDeadline();
   const finalIndex = await safeIndexedSnapshot(canonicalRoot, "MEMORY.md", index.record, hooks);
-  if (finalIndex.rejected || finalIndex.metadata.sha256 !== index.metadata.sha256) throw new Error("Claude MEMORY.md changed during indexed resolution; retry the hook");
+  if (finalIndex.rejected || finalIndex.metadata.sha256 !== index.metadata.sha256) throw new Error("MEMORY.md changed during indexed resolution; retry the hook");
   await mutateCache(env, (value) => {
     const records = { "MEMORY.md": index.record };
     for (const source of sources.slice(1)) records[source.relativePath] = source.snapshot.record;

package/agent-spine-plugin/src/lib/learning-artifact-evaluator.js

@@ -0,0 +1,114 @@
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+import { performance } from "node:perf_hooks";
+import { randomUUID } from "node:crypto";
+import { targetSnapshot } from "./delivery-target.js";
+import { loadLearning } from "./learning-storage.js";
+import { digest, exactScope, normalizeScope, activeEvaluationBinding } from "./learning-scope-targets.js";
+import { recordLearningMeasurement } from "./learning-measurements.js";
+import { CATALOG_SCHEMA, catalogScanPolicy } from "./catalog.js";
+
+const SCHEMA = "agentspine.artifact-checks/v1";
+const PROTOCOL = "agentspine.artifact-evaluator/v1:sha256-or-absent:two-pass:16-cases:2-mib-per-file";
+const PROTOCOL_DIGEST = digest(PROTOCOL);
+// One implementation is ONE principal, even under different aliases or paths.
+const PRINCIPAL_DIGEST = digest({ implementation: PROTOCOL });
+const METRIC = { name: "artifact-check-pass-rate", direction: "higher" };
+
+export function artifactEvaluationPlan(spec) {
+  if (!spec || spec.schema !== SCHEMA || Object.keys(spec).some((key) => !["schema", "checks"].includes(key))
+    || !Array.isArray(spec.checks) || spec.checks.length < 1 || spec.checks.length > 16) {
+    throw new Error("artifact evaluation requires a known schema and 1 to 16 explicit checks");
+  }
+  const seen = new Set();
+  const checks = spec.checks.map((check) => {
+    if (!check || Object.keys(check).some((key) => !["path", "sha256", "blocking"].includes(key))
+      || typeof check.path !== "string" || check.path.length > 240
+      || !/^[A-Za-z0-9_-][A-Za-z0-9_./-]*$/.test(check.path)
+      || check.path.split("/").some((part) => !part || part === "." || part === "..")
+      || !(check.sha256 === null || /^[a-f0-9]{64}$/.test(check.sha256 || ""))
+      || typeof check.blocking !== "boolean") {
+      throw new Error("artifact checks require unique project-relative paths, SHA-256 or null, and explicit blocking flags");
+    }
+    const key = check.path.toLowerCase();
+    if (seen.has(key)) throw new Error("artifact check paths must be unique across platforms");
+    seen.add(key);
+    return { path: check.path, sha256: check.sha256, blocking: check.blocking };
+  }).sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  const normalized = { schema: SCHEMA, checks };
+  return { spec: normalized, datasetDigest: digest(normalized), protocolDigest: PROTOCOL_DIGEST,
+    principalDigest: PRINCIPAL_DIGEST, metric: { ...METRIC }, minCases: checks.length,
+    authority: "context-only" };
+}
+
+// Local evaluator only. No shell, model scores, automatic registration, source
+// discovery, outcome consumption, promotion or configuration changes.
+export async function measureLearningArtifacts({ root = process.cwd(), spec, id, learningId, evaluationId,
+  phase, scope, evaluatorId, runId, confirmLocalMeasurement = false } = {}) {
+  if (confirmLocalMeasurement !== true) throw new Error("artifact measurement requires explicit local confirmation");
+  const started = performance.now();
+  const plan = artifactEvaluationPlan(spec);
+  const canonical = await realpath(root);
+  if (canonical !== resolve(root)) throw new Error("artifact project root must be canonical and non-symbolic");
+  // State-only catalog: measurement contracts need no document discovery.
+  // Never take this catalog from the caller; its root is resolved above.
+  const catalog = { schema: CATALOG_SCHEMA, root: canonical, generatedAt: new Date().toISOString(),
+    scanPolicy: catalogScanPolicy(canonical), preservation: "source-files-are-read-only",
+    documents: [], conflicts: [], summary: { total: 0, protected: 0, conflicts: 0, byLayer: {} } };
+  const { learning } = await loadLearning(canonical, catalog);
+  const evaluation = learning.evaluations.find((entry) => entry.id === evaluationId && entry.learningId === learningId);
+  const binding = normalizeScope(scope);
+  if (!evaluation || !exactScope(evaluation.scope, binding) || !activeEvaluationBinding(learning, evaluation)) {
+    throw new Error("artifact evaluation requires an active exact-scope local contract");
+  }
+  if (evaluation.benchmark.datasetDigest !== plan.datasetDigest
+    || evaluation.benchmark.protocolDigest !== plan.protocolDigest
+    || evaluation.benchmark.minCases !== plan.minCases
+    || evaluation.metric.name !== METRIC.name || evaluation.metric.direction !== METRIC.direction) {
+    throw new Error("artifact checks or measurement protocol differ from the frozen evaluation");
+  }
+  if (!evaluation.evaluatorRoots.some((entry) => entry.evaluatorId === evaluatorId
+    && entry.principalDigest === PRINCIPAL_DIGEST)) {
+    throw new Error("artifact evaluator must use its single locally registered implementation principal");
+  }
+  const trial = evaluation.initialTrials?.[phase]?.find((entry) => entry.evaluatorId === evaluatorId);
+  if (!trial || trial.runId !== runId) throw new Error("artifact measurement requires the precommitted initial trial");
+  if (learning.measurements.some((entry) => entry.id === id
+    || (entry.measurement.evaluatorId === evaluatorId && entry.measurement.runId === runId))) {
+    throw new Error("artifact trial was already measured; it cannot be rerun or replaced");
+  }
+  const snapshots = [];
+  for (const check of plan.spec.checks) {
+    const snapshot = await targetSnapshot(canonical, check.path);
+    if (snapshot.omitted) throw new Error("artifact exceeds the bounded measurement budget");
+    snapshots.push(snapshot);
+  }
+  // Recheck the complete bounded cohort, not just each file during its own read.
+  for (let index = 0; index < snapshots.length; index++) {
+    const current = await targetSnapshot(canonical, plan.spec.checks[index].path);
+    if (JSON.stringify(current) !== JSON.stringify(snapshots[index])) {
+      throw new Error("artifact cohort changed during measurement");
+    }
+  }
+  const checks = plan.spec.checks.map((check, index) => ({
+    path: check.path, expectedDigest: check.sha256,
+    observedDigest: snapshots[index].sha256, bytes: snapshots[index].bytes,
+    passed: snapshots[index].sha256 === check.sha256, blocking: check.blocking
+  }));
+  const metric = { ...METRIC, value: checks.filter((check) => check.passed).length / checks.length,
+    blockingDefects: checks.filter((check) => !check.passed && check.blocking).length };
+  const measuredAt = new Date().toISOString();
+  const report = { schema: "agentspine.artifact-measurement/v1", observationId: randomUUID(), evaluationId, learningId,
+    scope: binding, evaluatorId, runId, phase, datasetDigest: plan.datasetDigest,
+    protocolDigest: PROTOCOL_DIGEST, measuredAt, checks, metric, authority: "context-only" };
+  const sourceDigest = digest(report);
+  const recorded = await recordLearningMeasurement({ root: canonical, id, learningId, evaluationId, phase,
+    scope: binding, metric, measurement: { kind: "objective", evaluatorId, runId, sourceDigest },
+    coverage: { datasetDigest: plan.datasetDigest, caseCount: checks.length },
+    measuredAt, confirmLocalMeasurement: true, catalog });
+  return { ...recorded, report, sourceDigest,
+    diagnostics: { elapsedMs: performance.now() - started,
+      inspectedFiles: checks.length, inspectedBytes: snapshots.reduce((sum, item) => sum + item.bytes, 0) * 2,
+      broadScan: false, commandsExecuted: 0 },
+    completionVerified: false, automaticRetry: false, authority: "context-only" };
+}