blun-king-cli 9.1.567 → 9.1.570

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

@@ -0,0 +1,257 @@
+import {
+  inspectPremortemState,
+  preparePremortemRequirement,
+  recordPremortemWriteIntent,
+  recordPremortemWrite,
+  verifyPremortemBeforeWrite,
+  verifyPremortemStop
+} from "./delivery-premortem.js";
+import { consumeDeliveryAgentUse, deliveryAgentUseGuidance,
+  removeDeliveryAgentUse, verifyDeliveryAgentUse } from "./delivery-agent-usage.js";
+import { deliveryToolActions, verifyDeliveryStop } from "./delivery-verification.js";
+import { boundedId } from "./hook-context.js";
+import { auditGuard } from "./hook-protection.js";
+import { comparablePath, projectId as localProjectId } from "./paths.js";
+import { resolveFinalAssistantMessage } from "./hook-final-message.js";
+import { assignmentPremortemBinding, beginDeliveryAssignment, continueDeliveryAssignment,
+  resolveDeliveryAssignment } from "./delivery-assignment.js";
+import { deliveryWriteIdDigest } from "./delivery-premortem-binding.js";
+
+export function premortemBinding(input, scope, root = null) {
+  return {
+    host: scope?.host || null,
+    sessionId: boundedId(input?.session_id ?? input?.sessionId, "sessionId"),
+    entityId: scope?.entityId || null,
+    groupId: scope?.groupId || null,
+    projectId: scope?.projectId || (root ? `project:${localProjectId(comparablePath(root))}` : null),
+    taskId: scope?.goalId || scope?.queueId ? null : scope?.currentTaskId || null,
+    assignmentId: input?.assignment_id || input?.assignmentId || null,
+    goalId: scope?.goalId || null,
+    goalStepId: scope?.goalStepId || null,
+    queueId: scope?.queueId || null,
+    planDefinitionsDigest: scope?.planDefinitionsDigest || null,
+    gatewayAttempt: scope?.gatewayAttempt || null
+  };
+}
+
+async function exactBinding(input, scope, root, begin = false) {
+  if (input?.assignment_id && input?.assignmentId && input.assignment_id !== input.assignmentId) {
+    return { status: "foreign-assignment", blocked: true,
+      reason: "Conflicting assignment_id and assignmentId cannot select a delivery." };
+  }
+  const binding = premortemBinding(input, scope, root);
+  if (begin && binding.assignmentId) {
+    return continueDeliveryAssignment({ root, binding, assignmentId: binding.assignmentId });
+  }
+  const suppliedEventId = input?.event_id ?? input?.hook_event_id ?? input?.turn_id;
+  const promptEventId = suppliedEventId
+    ? boundedId(suppliedEventId, "eventId")
+    : `prompt:${deliveryWriteIdDigest({ tool_input: input?.prompt ?? input?.user_prompt
+      ?? input?.message ?? input?.input ?? null })}`;
+  const assignment = begin
+    ? await beginDeliveryAssignment({ root, binding,
+      eventId: promptEventId,
+      now: input.timestamp || new Date() })
+    : await resolveDeliveryAssignment({ root, binding, assignmentId: binding.assignmentId });
+  return assignment.blocked ? assignment : {
+    ...assignment, binding: assignmentPremortemBinding(binding, assignment)
+  };
+}
+
+export function isPremortemWrite(input) {
+  return deliveryToolActions(input).some((item) => item.kind === "write");
+}
+
+async function diagnostic(input, phase, result) {
+  if (result?.status === "degraded") await auditGuard(input, phase, result);
+  return result;
+}
+
+function degraded(error, path) {
+  return {
+    status: "degraded", blocked: false, path,
+    reason: String(error?.message || error || "premortem state unavailable").slice(0, 2048)
+  };
+}
+
+function invalidWriteSession(error, path) {
+  return {
+    status: "invalid-session", blocked: true, path,
+    reason: "AgentSpine denied this write before mutation because a valid host session_id is required: "
+      + String(error?.message || error || "sessionId is missing").slice(0, 400)
+  };
+}
+
+function withRegistrationGuidance(result, root, assignmentId = null) {
+  const requirementId = result.requirementId || result.requirement?.requirementId || null;
+  const registration = { tool: "record_delivery_premortem", root, requirementId };
+  const agentSpineUse = deliveryAgentUseGuidance(root, requirementId);
+  return {
+    ...result, assignmentId, registration, agentSpineUse,
+    instruction: [
+      "Advisory preparation; never blocks authorized coding or replies. Bind calls to session, assignment and step:",
+      "Reuse the host-verified briefing; delivery_knowledge_query and record_delivery_premortem need no second briefing fetch.",
+      `Use registration.root; Requirement: ${requirementId || "<unavailable; continue the authorized task>"}.`,
+      "Premortem: exactly baseline-environment, contract-tests, delivery-path; each `this delivery fails because ` statement needs a concrete check.",
+      "Context only; no authority. Never reset receipts or repeat tests merely to dismiss a warning.",
+      "Host continuation: UserPromptSubmit assignmentId; omit for new work. Chat cannot select continuation.",
+      "After observed tests: ordinary assignments use complete_delivery; goals retain checkpoints/outcomes. Legacy closure:",
+      "`Premortem closure sha256 <64hex>`, `Premortem latest write sha256 <64hex>`, and:",
+      "- <category> <checkId>: PASS — <nonempty result>"
+    ].join("\n")
+  };
+}
+
+export async function prepareHookPremortem({ input, root, scope }) {
+  try {
+    const exact = await exactBinding(input, scope, root, true);
+    if (exact.blocked) return withRegistrationGuidance(exact, root, exact.assignmentId);
+    if (exact.status === "degraded") {
+      await diagnostic(input, "premortem-prepare", exact);
+      return withRegistrationGuidance(exact, root);
+    }
+    if (exact.status === "continued") return withRegistrationGuidance({
+      status: "required", blocked: false, requirementId: exact.requirementId,
+      requirement: exact.requirement, continuation: true
+    }, root, exact.assignmentId);
+    const result = await preparePremortemRequirement({
+      root, binding: exact.binding, now: input.timestamp || new Date()
+    });
+    await diagnostic(input, "premortem-prepare", result);
+    return withRegistrationGuidance(result, root, exact.assignmentId);
+  } catch (error) {
+    const result = degraded(error, root);
+    await diagnostic(input, "premortem-prepare", result);
+    return withRegistrationGuidance(result, root);
+  }
+}
+
+export async function verifyHookPremortemWrite({ input, root, scope }) {
+  if (!isPremortemWrite(input)) return { status: "not-applicable", blocked: false };
+  try {
+    if (!boundedId(input?.session_id ?? input?.sessionId, "sessionId")) {
+      throw new Error("sessionId is missing");
+    }
+  } catch (error) {
+    return invalidWriteSession(error, root);
+  }
+  try {
+    const exact = await exactBinding(input, scope, root);
+    if (exact.blocked) return exact;
+    const binding = exact.binding;
+    const result = await diagnostic(input, "premortem-before-write", await verifyPremortemBeforeWrite({
+      root, binding, now: input.timestamp || new Date()
+    }));
+    let requirement = null;
+    if (result.status === "missing") {
+      requirement = await diagnostic(input, "premortem-prepare-on-write", await preparePremortemRequirement({
+        root, binding, now: input.timestamp || new Date()
+      }));
+      if (requirement.status === "degraded") return withRegistrationGuidance(requirement, root);
+      if (requirement.blocked) return requirement;
+    }
+    if (result.blocked && new Set(["conflict", "late", "finalized", "mismatch"]).has(result.status)) {
+      const recovery = result.status === "conflict" ? {
+        tool: "recover_delivery_premortem", root,
+        predecessorRequirementId: result.requirementId,
+        instruction: "Recover into a fresh assignment-bound requirement, then run all three preflight calls again. History is preserved; recovery grants no authority."
+      } : null;
+      return { ...result, recovery,
+        reason: `${result.reason}\nPremortem status: ${result.status}.${recovery ? `\n${recovery.instruction}` : ""}` };
+    }
+    const requirementId = requirement?.requirementId || result.requirementId;
+    if (requirementId?.split(":").length === 3) {
+      const usage = await diagnostic(input, "delivery-agent-use-before-write",
+        await verifyDeliveryAgentUse({ root, requirementId }));
+      if (usage.blocked) {
+        const guidance = withRegistrationGuidance(requirement || result, root);
+        return { ...usage, reason: `${usage.reason}\n${guidance.instruction}` };
+      }
+      if (!result.blocked) return { ...result, agentSpineUse: usage };
+    } else if (!result.blocked) return result;
+    const named = `${result.reason}\nPremortem status: ${result.status}.`;
+    const guided = requirement ? withRegistrationGuidance(requirement, root) : null;
+    return result.status === "missing"
+      ? { ...result, requirementId: guided.requirementId, registration: guided.registration,
+        reason: `${named}\n${guided.instruction}` }
+      : { ...result, reason: named };
+  } catch (error) {
+    return diagnostic(input, "premortem-before-write", degraded(error, root));
+  }
+}
+
+export async function recordHookPremortemWrite({ input, root, scope, success }) {
+  if (!isPremortemWrite(input)) return { status: "not-applicable", blocked: false };
+  if (success !== true) return { status: "write-failed", blocked: false };
+  try {
+    const exact = await exactBinding(input, scope, root);
+    if (exact.blocked) return exact;
+    const result = await diagnostic(input, "premortem-write", await recordPremortemWrite({
+      root, binding: exact.binding, input,
+      now: input.timestamp || new Date()
+    }));
+    return result.status === "duplicate" ? { ...result, status: "write-recorded" } : result;
+  } catch (error) {
+    return diagnostic(input, "premortem-write", degraded(error, root));
+  }
+}
+
+export async function recordHookPremortemWriteIntent({ input, root, scope }) {
+  if (!isPremortemWrite(input)) return { status: "not-applicable", blocked: false };
+  try {
+    const exact = await exactBinding(input, scope, root);
+    if (exact.blocked) return exact;
+    return await diagnostic(input, "premortem-write-intent", await recordPremortemWriteIntent({
+      root, binding: exact.binding, input, now: input.timestamp || new Date()
+    }));
+  } catch (error) {
+    return diagnostic(input, "premortem-write-intent", degraded(error, root));
+  }
+}
+
+export async function verifyHookPremortemStop({ input, root, scope, paused = false,
+  consume = false }) {
+  if (paused) return { status: "paused-job", blocked: false };
+  try {
+    const message = resolveFinalAssistantMessage(input);
+    if (!message.known) {
+      return diagnostic(input, "premortem-stop", degraded(new Error(`premortem ${message.reason}`), root));
+    }
+    const exact = await exactBinding(input, scope, root);
+    if (exact.blocked) return exact;
+    const binding = exact.binding;
+    const inspection = await diagnostic(input, "premortem-stop-inspect",
+      await inspectPremortemState({ root, binding }));
+    let usage = null;
+    if (inspection.hasWrite && inspection.requirementId) {
+      usage = await diagnostic(input, "delivery-agent-use-stop",
+        await verifyDeliveryAgentUse({ root, requirementId: inspection.requirementId }));
+      if (usage.blocked) return usage;
+    }
+    let allowStoredCompletion = false;
+    if (inspection.completionSource === "mcp") {
+      const tested = await verifyDeliveryStop({ root, host: binding.host,
+        sessionId: binding.sessionId, scope });
+      if (tested.blocked) return diagnostic(input, "completion-test-check", tested);
+      allowStoredCompletion = tested.status === "verified";
+    }
+    const result = await diagnostic(input, "premortem-stop", await verifyPremortemStop({
+      root, binding, message: message.text,
+      allowStoredCompletion,
+      now: input.timestamp || new Date()
+    }));
+    if (!inspection.hasWrite && inspection.requirementId) {
+      await diagnostic(input, "delivery-agent-use-read-only-cleanup",
+        await removeDeliveryAgentUse({ root, requirementId: inspection.requirementId }));
+    }
+    if (consume && result.status === "closed" && usage && inspection.requirementId) {
+      const consumed = await diagnostic(input, "delivery-agent-use-consume",
+        await consumeDeliveryAgentUse({ root, requirementId: inspection.requirementId,
+          now: input.timestamp || new Date() }));
+      return { ...result, agentSpineUse: { ...usage, consumption: consumed } };
+    }
+    return result;
+  } catch (error) {
+    return diagnostic(input, "premortem-stop", degraded(error, root));
+  }
+}

package/agent-spine-plugin/src/lib/hook-process-advisory.js

@@ -0,0 +1,37 @@
+import { recordHookScanAudit } from "./hook-audit.js";
+
+// This is deliberately called only for process evidence and code-quality
+// findings, after effect authorization. It must never wrap access denials.
+export async function processAdvisory(input, payload, root, scope, details) {
+  const event = input.hook_event_name || input.event_name;
+  const status = details.premortem?.status || details.deliveryVerification?.status || details.artifactGuard?.status;
+  const diagnostic = {
+    schema: "agentspine.process-advisory/v1", presentation: "internal-only",
+    status: /^[a-z-]{1,64}$/.test(status || "") ? status : "unavailable",
+    completionVerified: false, action: "continue-authorized-task", automaticRetry: false,
+    authority: "context-only",
+    instruction: "Do not quote this diagnostic. Continue working or answer normally. "
+      + "Mention only relevant evidence-backed limitations in the user's language; never invent a risk or a passed test. "
+      + "Ask only for a consequential user decision. Do not reset receipts or repeat work to satisfy process bookkeeping."
+  };
+  const fresh = await recordHookScanAudit({
+    event,
+    phase: "process-advisory",
+    error: { code: "UNVERIFIED_DELIVERY", message: JSON.stringify(diagnostic) },
+    onceKey: JSON.stringify(["process-advisory", root, scope,
+      input.session_id || input.sessionId, input.assignment_id || input.assignmentId || null]),
+  });
+  const result = {
+    ...details,
+    blocked: false,
+    advisory: true,
+    completionVerified: false,
+    diagnostic: fresh ? diagnostic : null
+  };
+  if (payload) return result;
+  const field = process.env.BLUN_PLUGIN_ROOT ? "message" : "additionalContext";
+  const output = fresh ? { hookSpecificOutput: {
+    hookEventName: event, [field]: JSON.stringify(diagnostic)
+  } } : {};
+  process.stdout.write(`${JSON.stringify(output)}\n`);
+}

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

@@ -0,0 +1,95 @@
+import { isAbsolute, relative } from "node:path";
+import { deliveryToolActions } from "./delivery-command-actions.js";
+import { recordHookScanAudit } from "./hook-audit.js";
+
+export function candidatePaths(value, output = []) {
+  if (!value) return output;
+  if (typeof value === "string") {
+    for (const match of value.matchAll(/^\*\*\* (?:Add|Update|Delete) File: (.+)$/gm)) output.push(match[1].trim());
+    return output;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) candidatePaths(item, output);
+    return output;
+  }
+  for (const [key, item] of Object.entries(value)) {
+    if (["path", "file_path", "target_file", "filename"].includes(key) && typeof item === "string") output.push(item);
+    else candidatePaths(item, output);
+  }
+  return output;
+}
+
+export function isMutationTool(name = "") {
+  return /(^|__)(apply_patch|edit|write|delete|move|rename|bash|exec_command|shell|powershell|pwsh)(_|$)/i.test(name);
+}
+
+export function isScanFailOpenTool(name = "") {
+  return /(^|__)(apply_patch|edit|write|bash|exec_command|shell|powershell|pwsh)(_|$)/i.test(name);
+}
+
+function filesystemScanError(error) {
+  return Boolean(error && (error.code === "AGENTSPINE_SCAN_INCOMPLETE" || error.agentSpineScan === true));
+}
+
+export function hookScanFailureFailsOpen(error) {
+  return filesystemScanError(error) || (["EPERM", "EACCES"].includes(error?.code)
+    && ["opendir", "readdir", "scandir"].includes(error?.syscall));
+}
+
+export async function auditSkippedScans(input, phase, skipped = []) {
+  const item = skipped.find((entry) => entry.code === "AGENTSPINE_SCAN_INCOMPLETE") || skipped[0];
+  if (!item) return;
+  await recordHookScanAudit({
+    event: "PreToolUse", toolName: input.tool_name || null, phase,
+    error: { code: item.code, message: item.message || `${item.code}: ${item.operation} skipped ${item.path}` },
+    path: item.path, operation: item.operation, now: input.timestamp || new Date()
+  });
+}
+
+export async function auditGuard(input, phase, result, once = false) {
+  await recordHookScanAudit({
+    event: input.hook_event_name || input.event_name || "unknown", toolName: input.tool_name || null,
+    phase, error: { code: result.status || "GUARD_ERROR", message: result.reason || result.status },
+    path: result.path || input.cwd || process.cwd(), operation: "verify",
+    onceKey: once ? `${phase}\0${result.status}\0${result.path || input.cwd || ""}` : null,
+    now: input.timestamp || new Date()
+  });
+}
+
+async function allowScanFailure(input, phase, error) {
+  const event = input.hook_event_name || input.event_name || "unknown";
+  await recordHookScanAudit({
+    event, toolName: input.tool_name || null, phase, error,
+    path: error?.path || input.cwd || process.cwd(), now: input.timestamp || new Date()
+  });
+  return { blocked: false, scanFailedOpen: true, event, phase, error: error.message };
+}
+
+export async function finishScanFailure(input, payload, phase, error) {
+  const allowed = await allowScanFailure(input, phase, error);
+  if (payload) return allowed;
+  process.stdout.write("{}\n");
+  return undefined;
+}
+
+function stringValues(value, output = []) {
+  if (typeof value === "string") output.push(value);
+  else if (Array.isArray(value)) value.forEach((item) => stringValues(item, output));
+  else if (value && typeof value === "object") Object.values(value).forEach((item) => stringValues(item, output));
+  return output;
+}
+
+export function shellTargetsProtected(input, documents, cwd, root) {
+  if (!/(bash|exec_command|shell|powershell|pwsh)/i.test(input.tool_name || "")) return null;
+  const command = stringValues(input.tool_input || input.tool_args).join("\n").replaceAll("\\", "/");
+  if (!deliveryToolActions(input).some((item) => item.kind === "write")) return null;
+  for (const document of documents) {
+    const forms = new Set([document.path.replaceAll("\\", "/"), document.relativePath]);
+    for (const base of [cwd, root]) {
+      const candidate = relative(base, document.path);
+      if (candidate && !candidate.startsWith("..") && !isAbsolute(candidate)) forms.add(candidate.replaceAll("\\", "/"));
+    }
+    if ([...forms].some((form) => form && command.includes(form))) return document;
+  }
+  return null;
+}

package/agent-spine-plugin/src/lib/hook-stop-verification.js

@@ -0,0 +1,84 @@
+import { deliveryActorSession, recordDeliveryPause, verifyDeliveryStop } from "./delivery-verification.js";
+import { blockStop } from "./hook-output.js";
+import { verifyHookPremortemStop } from "./hook-premortem.js";
+
+function explicitStopEventId(input) {
+  for (const candidate of [input?.event_id, input?.hook_event_id]) {
+    if (typeof candidate === "string" && candidate) return candidate;
+  }
+  return null;
+}
+
+function stopArguments(input, root, scope) {
+  return {
+    root,
+    host: scope.host,
+    sessionId: deliveryActorSession(input),
+    scope,
+    // Timestamps identify neither a host event nor a pause: two distinct Stop
+    // deliveries may share one. Only an explicit host-provided event id can
+    // make a pause idempotent or be honored by a later completion.
+    eventId: explicitStopEventId(input)
+  };
+}
+
+function blockedResult(deliveryVerification, premortem = null) {
+  return {
+    blocked: true,
+    reason: deliveryVerification.reason,
+    deliveryVerification,
+    premortem
+  };
+}
+
+export function denyHookStop(payload, event, reason, details) {
+  if (payload) return { blocked: true, reason, ...details };
+  blockStop(event, reason);
+}
+
+export async function verifyHookStopContracts({ input, root, scope, recordPause = false,
+  completionFence = false, afterDeliveryVerification = null,
+  afterPremortemVerification = null }) {
+  const argumentsForStop = stopArguments(input, root, scope);
+  const deliveryVerification = recordPause
+    ? await recordDeliveryPause(argumentsForStop)
+    : await verifyDeliveryStop(argumentsForStop);
+  if (deliveryVerification.blocked) return blockedResult(deliveryVerification);
+  if (typeof afterDeliveryVerification === "function") await afterDeliveryVerification();
+
+  const premortem = await verifyHookPremortemStop({
+    input,
+    root,
+    scope,
+    paused: deliveryVerification.status === "paused-job",
+    consume: completionFence
+  });
+  if (premortem.blocked) {
+    return { blocked: true, reason: premortem.reason, deliveryVerification, premortem };
+  }
+  if (typeof afterPremortemVerification === "function") await afterPremortemVerification();
+
+  const finalDeliveryVerification = completionFence
+    ? await verifyDeliveryStop(argumentsForStop)
+    : deliveryVerification;
+  if (finalDeliveryVerification.blocked) {
+    return blockedResult(finalDeliveryVerification, premortem);
+  }
+  const digestPattern = /^[a-f0-9]{64}$/;
+  if (completionFence && digestPattern.test(deliveryVerification.stateDigest || "")
+    && digestPattern.test(finalDeliveryVerification.stateDigest || "")
+    && deliveryVerification.stateDigest !== finalDeliveryVerification.stateDigest) {
+    return blockedResult({
+      ...finalDeliveryVerification,
+      status: "changed",
+      blocked: true,
+      reason: "AgentSpine delivery evidence changed during Stop; retry completion against the latest state."
+    }, premortem);
+  }
+  return {
+    blocked: false,
+    reason: null,
+    deliveryVerification: finalDeliveryVerification,
+    premortem
+  };
+}

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

@@ -0,0 +1,91 @@
+import { sessionTimelineLifecycleHint } from "./session-timeline.js";
+import { issueHostTranscriptReceipt } from "./session-timeline-enrollment.js";
+import { consumeTimelineHostOrigin } from "./session-timeline-host-origin.js";
+import {
+  timelineHostForRuntime, timelineHostHome, timelineProtocolFromRuntime, timelineSourceFromRuntime
+} from "./session-timeline-provider.js";
+
+const AUTHORITY = "context-only";
+
+function unavailable(reason) {
+  return { schema: "agentspine.session-timeline/v1", status: "unavailable", reason, authority: AUTHORITY };
+}
+
+function hasRawTimelineGroupSignal(input) {
+  try {
+    if (!input || typeof input !== "object" || Array.isArray(input)) return false;
+    const nested = input.agent_spine_scope;
+    const values = [input.groupId, input.group_id];
+    if (nested && typeof nested === "object" && !Array.isArray(nested)) {
+      values.push(nested.groupId, nested.group_id);
+    }
+    return values.some((value) => value !== undefined && value !== null && value !== "");
+  } catch {
+    // Parser-shaped uncertainty must not turn a lifecycle hint into a denial.
+    return false;
+  }
+}
+
+function groupSuppressed(reason) {
+  return { schema: "agentspine.session-timeline/v1", status: "group-suppressed", reason, authority: AUTHORITY };
+}
+
+function receiptObservation(receipt) {
+  return { schema: "agentspine.session-timeline-host-receipt/v1",
+    status: receipt.status === "pending" ? "pending" : "unavailable", reason: receipt.reason || null,
+    expiresAt: receipt.expiresAt || null, authority: AUTHORITY };
+}
+
+// This observes a provider hook payload but never returns the
+// opaque enrollment token through model-visible context.
+export async function observeHostTranscriptReceipt({ root, event, input, scope, hostHome, hostOrigin = null, clock = null }) {
+  if (event !== "UserPromptSubmit") return receiptObservation({ status: "not-applicable" });
+  if (hasRawTimelineGroupSignal(input)) return receiptObservation({ status: "unavailable", reason: "raw-group-scope" });
+  if (!scope || scope.groupId !== null) return receiptObservation({ status: "unavailable", reason: "computed-group-scope" });
+  const host = timelineHostForRuntime(scope.host, process.env);
+  const receipt = await issueHostTranscriptReceipt({ root, host, sessionId: input.session_id ?? input.sessionId,
+    scope, transcriptPath: timelineSourceFromRuntime(host, input), hostHome: timelineHostHome(host) ?? hostHome,
+    event, eventId: input.event_id ?? input.hook_event_id,
+    hostOrigin, clock, environment: process.env });
+  return receiptObservation(receipt);
+}
+
+export async function captureSessionTimelineLifecycle({ root, event, input, scope, hostHome, hostOrigin = null, clock = null }) {
+  if (hasRawTimelineGroupSignal(input)) return groupSuppressed("raw-group-scope");
+  if (!scope || scope.groupId !== null) return groupSuppressed("computed-group-scope");
+  let hostReceipt = null;
+  if (event === "UserPromptSubmit" && hostOrigin) {
+    try { hostReceipt = await observeHostTranscriptReceipt({ root, event, input, scope, hostHome, hostOrigin, clock }); }
+    catch (error) {
+      hostReceipt = { schema: "agentspine.session-timeline-host-receipt/v1", status: "degraded", reason: error.message,
+        expiresAt: null, authority: AUTHORITY };
+    }
+  }
+  const result = (value) => hostReceipt ? { ...value, hostReceipt } : value;
+  const host = timelineHostForRuntime(scope.host, process.env);
+  if (!host || (host === "king" && !timelineProtocolFromRuntime(host))) return unavailable("host-not-supported");
+  return result(await sessionTimelineLifecycleHint({ root, host,
+    sessionId: input.session_id ?? input.sessionId, scope, environment: process.env }));
+}
+
+// The calling hook performs this only at its final pre-answer boundary.  The
+// origin helper consumes the exact signed preflight receipt before this can
+// touch timeline receipt state. Failure to form a timeline origin is optional
+// and yields no opaque receipt; failure to consume preflight remains blocking.
+export async function finalizeUserPromptSessionTimeline({
+  root, input, scope, resolvedSources, preflight, prompt, now = new Date()
+}) {
+  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") };
+  try {
+    return { preflightConsumed: true, timeline: await captureSessionTimelineLifecycle({
+      root, event: "UserPromptSubmit", input, scope, hostHome: resolvedSources.hostHome,
+      hostOrigin: consumed.origin, clock: () => new Date(now)
+    }) };
+  } catch (error) {
+    return { preflightConsumed: true, timeline: {
+      schema: "agentspine.session-timeline/v1", status: "degraded", reason: error.message, authority: AUTHORITY
+    } };
+  }
+}