@kontextmind/kxm 0.7.91 → 0.7.93

package/plugins/kxm/src/commands.ts

@@ -3,6 +3,8 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSy
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { HubClient, HubHttpError } from "./client.ts";
+import { IMPROVEMENT_AREAS } from "./protocol.ts";
+import { JOURNAL_CATEGORIES } from "./workflow.ts";
 import type {
   DeliveryMode,
   ImprovementArea,
@@ -484,7 +486,7 @@ export const AGENT_COMMANDS: readonly AgentCommand[] = [
     group: "workflow",
     verb: "run",
     label: "Get workflow run",
-    description: "Get a workflow's stages and journal of plans, decisions, contradictions, errors, and lessons.",
+    description: "Get a workflow's stages and its learning journal (plans, decisions, contradictions, errors, lessons, and the other journal categories).",
     parameters: {
       type: "object",
       properties: {
@@ -563,20 +565,25 @@ export const AGENT_COMMANDS: readonly AgentCommand[] = [
     group: "workflow",
     verb: "record",
     label: "Record workflow journal entry",
-    description: "Record a plan, decision, contradiction, error, or lesson for continuous improvement.",
+    description:
+      "Record a plan, decision, contradiction, error, lesson, observation, hypothesis, experiment, state-change, or skill-candidate for continuous improvement. Pass stageId to bind the entry to that stage: the hub derives the attempt, and area defaults to the stage's declared area. Lessons and skill-candidates require evidence.",
     parameters: {
       type: "object",
       properties: {
         runId: { type: "string", description: "Active durable workflow run ID" },
         category: {
           type: "string",
-          enum: ["plan", "decision", "contradiction", "error", "lesson"],
+          enum: [...JOURNAL_CATEGORIES],
           description: "Category of journal entry",
         },
         area: {
           type: "string",
-          enum: ["harness", "gates", "implementation", "workflow", "documentation", "security", "other"],
-          description: "System area",
+          enum: [...IMPROVEMENT_AREAS],
+          description: "System area; required unless stageId names a stage that declares an area",
+        },
+        stageId: {
+          type: "string",
+          description: "Stage the entry belongs to; the hub binds the attempt from the stage's state",
         },
         severity: {
           type: "string",
@@ -599,13 +606,14 @@ export const AGENT_COMMANDS: readonly AgentCommand[] = [
           description: "Related previous journal entry IDs",
         },
       },
-      required: ["runId", "category", "area", "summary"],
+      required: ["runId", "category", "summary"],
       additionalProperties: false,
     },
     async execute(client, args) {
       return await client.recordWorkflowEntry(requiredString(args.runId, "runId"), {
         category: requiredString(args.category, "category") as JournalCategory,
-        area: requiredString(args.area, "area") as ImprovementArea,
+        ...(optionalString(args.area) ? { area: optionalString(args.area) as ImprovementArea } : {}),
+        ...(optionalString(args.stageId) ? { stageId: optionalString(args.stageId)! } : {}),
         ...(optionalString(args.severity)
           ? { severity: optionalString(args.severity) as "info" | "warning" | "error" }
           : {}),
@@ -689,7 +697,8 @@ export const AGENT_COMMANDS: readonly AgentCommand[] = [
     group: "workflow",
     verb: "improve-report",
     label: "Summarize improvement report",
-    description: "Summarize workflow errors, contradictions, and lessons by improvement area.",
+    description:
+      "Summarize workflow errors, contradictions, lessons, and skill candidates by improvement area, plus ranked cross-run signals: duplicates merged across runs and scored by frequency x severity x run-attempt cost x evidence confidence, security first, with redacted text.",
     parameters: {
       type: "object",
       properties: {},
@@ -744,7 +753,8 @@ export const AGENT_COMMANDS: readonly AgentCommand[] = [
     group: "context",
     verb: "recall",
     label: "Recall context metadata",
-    description: "Search durable context records for a project by query; returns bounded metadata only.",
+    description:
+      "Search durable context records for a project by query. Ranks exact-phrase matches first, then token relevance, then id; returns bounded metadata with a numeric relevance per item, never summaries.",
     parameters: {
       type: "object",
       properties: {

package/plugins/kxm/src/config.ts

@@ -55,14 +55,17 @@ export interface KxmHubConfig {
 
 export type ImprovementPromotionPolicy = "manual_pr" | "critic_quorum" | "auto_threshold";
 
+const IMPROVEMENT_PROMOTION_POLICIES: readonly ImprovementPromotionPolicy[] = ["manual_pr", "critic_quorum", "auto_threshold"];
+
+/** Normalized on load: every field is present and in range. */
 export interface KxmImprovementConfig {
   promotionPolicy: ImprovementPromotionPolicy;
-  telemetryHalfLifeDays?: number | undefined;
-  autoThreshold?: {
-    minRuns?: number | undefined;
-    minPassRate?: number | undefined;
-    minCostSavings?: number | undefined;
-  } | undefined;
+  telemetryHalfLifeDays: number;
+  autoThreshold: {
+    minRuns: number;
+    minPassRate: number;
+    minCostSavings: number;
+  };
 }
 
 export interface KxmShadowExecutionConfig {
@@ -195,6 +198,38 @@ function normalizeHubConfig(raw: unknown): KxmHubConfig {
   return { autoStart: autoStart === "off" || autoStart === "background" ? autoStart : DEFAULT_KXM_CONFIG.hub.autoStart };
 }
 
+function recordOf(raw: unknown): Record<string, unknown> {
+  return raw && typeof raw === "object" && !Array.isArray(raw) ? raw as Record<string, unknown> : {};
+}
+
+function finiteNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+/** `improvement.*` values fail closed to the defaults field by field, so a typo
+ * never turns review readiness into something else. None of these values can
+ * authorize a promotion; they only shape the readiness `kxm improve` reports. */
+function normalizeImprovementConfig(raw: unknown): KxmImprovementConfig {
+  const value = recordOf(raw);
+  const threshold = recordOf(value.autoThreshold);
+  const policy = value.promotionPolicy;
+  const halfLife = finiteNumber(value.telemetryHalfLifeDays);
+  const minRuns = finiteNumber(threshold.minRuns);
+  const minPassRate = finiteNumber(threshold.minPassRate);
+  const minCostSavings = finiteNumber(threshold.minCostSavings);
+  return {
+    promotionPolicy: IMPROVEMENT_PROMOTION_POLICIES.includes(policy as ImprovementPromotionPolicy)
+      ? policy as ImprovementPromotionPolicy
+      : "manual_pr",
+    telemetryHalfLifeDays: halfLife !== undefined && halfLife > 0 && halfLife <= 3650 ? halfLife : 14,
+    autoThreshold: {
+      minRuns: minRuns !== undefined && Number.isInteger(minRuns) && minRuns >= 1 && minRuns <= 1_000_000 ? minRuns : 10,
+      minPassRate: minPassRate !== undefined && minPassRate >= 0 && minPassRate <= 1 ? minPassRate : 0.95,
+      minCostSavings: minCostSavings !== undefined && minCostSavings >= 0 ? minCostSavings : 0.5,
+    },
+  };
+}
+
 export function loadKxmConfig(
   repoRoot = process.cwd(),
   options: { userConfigDir?: string } = {},
@@ -241,7 +276,7 @@ export function loadKxmConfig(
     dash: (mergedAll.dash as KxmDashConfig) ?? {},
     sync: (mergedAll.sync as KxmSyncTrackerConfig) ?? {},
     hub: normalizeHubConfig(mergedAll.hub),
-    improvement: (mergedAll.improvement as KxmImprovementConfig) ?? DEFAULT_KXM_CONFIG.improvement,
+    improvement: normalizeImprovementConfig(mergedAll.improvement),
     routing: (mergedAll.routing as KxmRoutingConfig) ?? DEFAULT_KXM_CONFIG.routing,
     telemetry: (mergedAll.telemetry as KxmTelemetryConfig) ?? DEFAULT_KXM_CONFIG.telemetry,
     loadedFrom: {

package/plugins/kxm/src/context-packet.ts

@@ -142,6 +142,7 @@ export function buildFormalContextPacket(input: {
   environment?: Partial<ContextPacketEnvironment> | undefined;
   tokenBudget?: number | undefined;
   arbitratedItems?: ContextItem[] | undefined;
+  unresolvedGaps?: string[] | undefined;
 }): FormalContextPacketV2 {
   const packetId = `ctxpkt_${randomUUID().replaceAll("-", "").slice(0, 16)}`;
   const now = new Date().toISOString();
@@ -208,7 +209,7 @@ export function buildFormalContextPacket(input: {
     budget: {
       allocatedTokens,
       estimatedTokens,
-      unresolvedGaps: [],
+      unresolvedGaps: [...(input.unresolvedGaps ?? [])],
       provenanceSummary,
     },
   };
@@ -265,7 +266,12 @@ export function formatContextPacketForPrompt(packet: FormalContextPacketV2): str
     sections.push("");
   }
 
-  if (packet.environment.projectKnowledge.length > 0 || packet.environment.sharedDefaults.length > 0) {
+  if (
+    packet.environment.projectKnowledge.length > 0
+    || packet.environment.sharedDefaults.length > 0
+    || packet.environment.activeSkills.length > 0
+    || packet.environment.contradictions.length > 0
+  ) {
     sections.push(`## 5. Environment & Memory`);
     if (packet.environment.sharedDefaults.length > 0) {
       sections.push(`### Shared Defaults`);
@@ -279,6 +285,12 @@ export function formatContextPacketForPrompt(packet: FormalContextPacketV2): str
         sections.push(`- [${k.authority}] ${k.summary}`);
       }
     }
+    if (packet.environment.activeSkills.length > 0) {
+      sections.push(`### Active Skills`);
+      for (const skill of packet.environment.activeSkills) {
+        sections.push(`- ${skill.summary} (${skill.provenance.sourceRef ?? skill.id})`);
+      }
+    }
     if (packet.environment.contradictions.length > 0) {
       sections.push(`### Active Contradictions`);
       for (const c of packet.environment.contradictions) {

package/plugins/kxm/src/context.ts

@@ -150,6 +150,7 @@ export interface ContextPacket {
   workingState: Record<string, unknown>;
   currentState: ContextItem[];
   knowledge: ContextItem[];
+  evidence: ContextItem[];
   episodes: ContextItem[];
   skills: ContextItem[];
   contradictions: ContextItem[];
@@ -334,7 +335,14 @@ export function parseContextRequest(value: unknown): ContextRequest {
 /** Validate that a packet only contains items matching the request's project
  * and requested kinds. Cross-project content fails closed. */
 export function validateContextPacketContents(request: ContextRequest, packet: ContextPacket): void {
-  const items = [...packet.currentState, ...packet.knowledge, ...packet.episodes, ...packet.skills, ...packet.contradictions];
+  const items = [
+    ...packet.currentState,
+    ...packet.knowledge,
+    ...packet.evidence,
+    ...packet.episodes,
+    ...packet.skills,
+    ...packet.contradictions,
+  ];
   if (items.length > MAX_CONTEXT_ITEMS) {
     throw new ProtocolError(400, `context packet exceeds ${MAX_CONTEXT_ITEMS} items`, "context_limits_exceeded");
   }
@@ -357,14 +365,17 @@ export function validateContextPacketContents(request: ContextRequest, packet: C
   }
 }
 
+/** Serialized size of one item as the token estimate counts it: summary, id,
+ * kind, and provenance sourceRef characters. */
+export function contextItemCharacters(item: ContextItem): number {
+  return item.summary.length + item.id.length + item.kind.length + (item.provenance.sourceRef?.length ?? 0);
+}
+
 /** Deterministic, dependency-free token estimate. Roughly 4 characters per
  * token; used for budget enforcement, never for billing. */
 export function estimateContextTokens(items: ContextItem[]): number {
   let characters = 0;
-  for (const item of items) {
-    characters += item.summary.length + item.id.length + item.kind.length;
-    if (item.provenance.sourceRef) characters += item.provenance.sourceRef.length;
-  }
+  for (const item of items) characters += contextItemCharacters(item);
   return Math.ceil(characters / 4);
 }
 

package/plugins/kxm/src/dispatch-context.ts

@@ -0,0 +1,286 @@
+import { spawnSync } from "node:child_process";
+import { readdirSync } from "node:fs";
+import { extname, join } from "node:path";
+import { arbitrate, memoryRecordToContextItem, rolePolicy, type ArbiterOutcome } from "./arbiter.ts";
+import { CONTEXT_ROLES, MAX_CONTEXT_TASK_CHARS, type ContextItem } from "./context.ts";
+import { loadAuthoredMemory, type MemoryRecord } from "./memory.ts";
+import { computeKxmMemoryRevision } from "./runtime-service.ts";
+import { SkillLifecycle, type SkillCandidateMetadata } from "./skills.ts";
+
+/**
+ * Runtime dispatch context (Q-K).
+ *
+ * A Runtime-dispatched agent receives the project's authored memory (active
+ * records with project or operator scope; candidates are never read) and its
+ * hash-verified promoted skills, selected by the same deterministic arbiter the
+ * hub uses. Delivery happens only when those files are committed and clean at
+ * HEAD and still match the run's pinned memory revision; otherwise the context
+ * is withheld and a `dispatch_context_*` gap says why. Only local git and the
+ * project tree are read: no hub source is fetched, so dispatch stays offline.
+ *
+ * Loading (git, hashing, file reads) happens outside the engine's IMMEDIATE
+ * transaction; assembly is pure and runs at birth.
+ */
+
+export const DISPATCH_CONTEXT_BUDGET_TOKENS = 4_000;
+/** The prompt formatter renders at most this many project knowledge items. */
+export const DISPATCH_CONTEXT_MAX_PROJECT_ITEMS = 5;
+
+const GAP_NOT_LOADED = "dispatch_context_not_loaded";
+const GAP_FAILED = "dispatch_context_failed";
+const GAP_GIT_UNAVAILABLE = "dispatch_context_withheld:git_unavailable";
+const GAP_UNCOMMITTED = "dispatch_context_withheld:uncommitted";
+const GAP_DRIFT = "dispatch_context_withheld:memory_revision_drift";
+const GAP_MEMORY_UNREADABLE = "dispatch_context_memory_unreadable";
+const GAP_SKILLS_UNREADABLE = "dispatch_context_skills_unreadable";
+
+/** Only the files the memory and skill loaders read. */
+const DISPATCH_CONTEXT_PATHSPEC = [
+  ":(glob).kxm/memory/*.md",
+  ":(glob).kxm/skills/promoted/*/SKILL.md",
+  ":(glob).kxm/skills/promoted/*/metadata.json",
+] as const;
+const GIT_STATUS_TIMEOUT_MS = 5_000;
+
+export interface DispatchContextSources {
+  readonly present: boolean;
+  readonly pool: readonly ContextItem[];
+  readonly promoted: readonly SkillCandidateMetadata[];
+  readonly gaps: readonly string[];
+  /** Authored records with agent or run scope, which dispatch cannot bind. */
+  readonly skippedUnboundScopes: number;
+}
+
+export const EMPTY_DISPATCH_SOURCES: DispatchContextSources = Object.freeze({
+  present: false,
+  pool: Object.freeze([]),
+  promoted: Object.freeze([]),
+  gaps: Object.freeze([]),
+  skippedUnboundScopes: 0,
+});
+
+export const NOT_LOADED_DISPATCH_SOURCES: DispatchContextSources = Object.freeze({
+  present: true,
+  pool: Object.freeze([]),
+  promoted: Object.freeze([]),
+  gaps: Object.freeze([GAP_NOT_LOADED]),
+  skippedUnboundScopes: 0,
+});
+
+export interface DispatchContextAssembly {
+  /** Arbitrated items to deliver, in rank order. */
+  readonly items: ContextItem[];
+  readonly deliveredIds: string[];
+  /** Selected project items the prompt formatter would not render. */
+  readonly renderDeferred: number;
+  readonly role: string;
+  readonly unresolvedGaps: string[];
+  readonly audit?: ArbiterOutcome["audit"];
+}
+
+/** Map an agent id to a context role: an exact role, else the first role the
+ * id is prefixed by (`critic-arch` is a critic), else the id itself, which the
+ * arbiter's role policy falls back on. */
+export function contextRoleForAgent(agentId: string): string {
+  if (CONTEXT_ROLES.includes(agentId)) return agentId;
+  for (const role of CONTEXT_ROLES) {
+    if (agentId.startsWith(`${role}-`)) return role;
+  }
+  return agentId;
+}
+
+/** Cheap presence probe: a top-level markdown file in `.kxm/memory` or any
+ * entry in `.kxm/skills/promoted`. No git and no hashing; a missing directory
+ * or a read error counts as absent. */
+export function dispatchContextPresent(projectRoot: string): boolean {
+  return hasTopLevelMarkdown(join(projectRoot, ".kxm", "memory"))
+    || hasAnyEntry(join(projectRoot, ".kxm", "skills", "promoted"));
+}
+
+function hasTopLevelMarkdown(dir: string): boolean {
+  try {
+    return readdirSync(dir, { withFileTypes: true }).some((entry) => entry.isFile() && extname(entry.name) === ".md");
+  } catch {
+    return false;
+  }
+}
+
+function hasAnyEntry(dir: string): boolean {
+  try {
+    return readdirSync(dir).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+function gitEnvironment(): NodeJS.ProcessEnv {
+  return Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.toUpperCase().startsWith("GIT_")));
+}
+
+/** Invariant 12: only committed, clean content is delivered. `--no-optional-locks`
+ * keeps `.git/index.lock` free for command gates running in the same root. */
+function committedGateGap(projectRoot: string): string | undefined {
+  const result = spawnSync("git", [
+    "--no-optional-locks",
+    "-C",
+    projectRoot,
+    "status",
+    "--porcelain=v1",
+    "--untracked-files=all",
+    "--ignored=matching",
+    "--",
+    ...DISPATCH_CONTEXT_PATHSPEC,
+  ], {
+    encoding: "utf8",
+    env: gitEnvironment(),
+    timeout: GIT_STATUS_TIMEOUT_MS,
+    windowsHide: true,
+  });
+  if (result.error || result.status !== 0) return GAP_GIT_UNAVAILABLE;
+  if (typeof result.stdout !== "string" || result.stdout.length > 0) return GAP_UNCOMMITTED;
+  return undefined;
+}
+
+/** A gap names ids only. An id that is not a plain identifier (skill metadata
+ * is file content) is not echoed. */
+function gapId(value: unknown): string {
+  return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(value) ? value : "invalid";
+}
+
+function withheld(gaps: readonly string[]): DispatchContextSources {
+  return { present: true, pool: [], promoted: [], gaps: [...gaps], skippedUnboundScopes: 0 };
+}
+
+/** Load the dispatch pool: every file read, git check and hash happens here, so
+ * callers run it outside any SQLite transaction. Total: it never throws. */
+export function loadDispatchContextSources(input: {
+  projectRoot: string;
+  projectId: string;
+  pinnedMemoryRevision: string;
+}): DispatchContextSources {
+  try {
+    const { projectRoot, projectId, pinnedMemoryRevision } = input;
+    if (!dispatchContextPresent(projectRoot)) return EMPTY_DISPATCH_SOURCES;
+
+    const gateGap = committedGateGap(projectRoot);
+    if (gateGap !== undefined) return withheld([gateGap]);
+    if (computeKxmMemoryRevision({ projectRoot }) !== pinnedMemoryRevision) return withheld([GAP_DRIFT]);
+
+    const gaps: string[] = [];
+    let records: MemoryRecord[];
+    try {
+      records = loadAuthoredMemory(projectRoot);
+    } catch {
+      gaps.push(GAP_MEMORY_UNREADABLE);
+      records = [];
+    }
+
+    const pool: ContextItem[] = [];
+    let skippedUnboundScopes = 0;
+    for (const record of records) {
+      if (record.scope !== "project" && record.scope !== "operator") {
+        skippedUnboundScopes += 1;
+        continue;
+      }
+      try {
+        pool.push(memoryRecordToContextItem(record, projectId));
+      } catch {
+        gaps.push(`dispatch_context_memory_rejected:${gapId(record.id)}`);
+      }
+    }
+
+    const promoted: SkillCandidateMetadata[] = [];
+    try {
+      const lifecycle = new SkillLifecycle(join(projectRoot, ".kxm", "skills"));
+      for (const metadata of lifecycle.list("promoted")) {
+        try {
+          promoted.push(lifecycle.verify("promoted", metadata.id));
+        } catch {
+          gaps.push(`dispatch_context_skill_unverified:${gapId(metadata.id)}`);
+        }
+      }
+    } catch {
+      gaps.push(GAP_SKILLS_UNREADABLE);
+    }
+
+    // The tree may have moved while it was read: what was read is only
+    // delivered when the revision still matches the pin.
+    if (computeKxmMemoryRevision({ projectRoot }) !== pinnedMemoryRevision) return withheld([...gaps, GAP_DRIFT]);
+
+    return { present: true, pool, promoted, gaps, skippedUnboundScopes };
+  } catch {
+    return withheld([GAP_FAILED]);
+  }
+}
+
+/** Arbitrate the loaded sources for one dispatched agent. Pure: no file I/O,
+ * never throws. Delivered project items are capped at what the prompt
+ * formatter renders; the overflow is reported as a gap. */
+export function assembleDispatchContext(
+  sources: DispatchContextSources,
+  input: { projectId: string; runId: string; stepId: string; agentId: string; task: string },
+): DispatchContextAssembly {
+  const role = contextRoleForAgent(input.agentId);
+  try {
+    if (sources.pool.length === 0 && sources.promoted.length === 0) {
+      return { items: [], deliveredIds: [], renderDeferred: 0, role, unresolvedGaps: [...sources.gaps] };
+    }
+    const task = (input.task.trim() || input.stepId).slice(0, MAX_CONTEXT_TASK_CHARS);
+    const promoted = sources.promoted;
+    const snapshot: Pick<SkillLifecycle, "list" | "verify"> = {
+      list: (state) => (state === "promoted" ? [...promoted] : []),
+      verify: (state, id) => {
+        const found = state === "promoted" ? promoted.find((metadata) => metadata.id === id) : undefined;
+        if (!found) throw new Error("skill is not in the verified dispatch snapshot");
+        return found;
+      },
+    };
+    const { packet, audit } = arbitrate(
+      {
+        project: input.projectId,
+        role,
+        task,
+        workflowRunId: input.runId,
+        stageId: input.stepId,
+        budgetTokens: Math.min(rolePolicy(role).budgetTokens, DISPATCH_CONTEXT_BUDGET_TOKENS),
+      },
+      [...sources.pool],
+      promoted.length > 0 ? { skillLifecycle: snapshot } : {},
+    );
+
+    const byId = new Map<string, ContextItem>();
+    for (const section of [packet.currentState, packet.knowledge, packet.evidence, packet.episodes, packet.skills, packet.contradictions]) {
+      for (const item of section) byId.set(item.id, item);
+    }
+    const items: ContextItem[] = [];
+    let projectItems = 0;
+    let renderDeferred = 0;
+    for (const id of audit.selectedIds) {
+      const item = byId.get(id);
+      if (!item) continue;
+      const projectRouted = item.project !== "_shared" && item.kind !== "state" && item.kind !== "episode" && item.kind !== "skill";
+      if (projectRouted) {
+        if (projectItems >= DISPATCH_CONTEXT_MAX_PROJECT_ITEMS) {
+          renderDeferred += 1;
+          continue;
+        }
+        projectItems += 1;
+      }
+      items.push(item);
+    }
+    return {
+      items,
+      deliveredIds: items.map((item) => item.id),
+      renderDeferred,
+      role,
+      unresolvedGaps: [
+        ...sources.gaps,
+        ...packet.unresolvedGaps,
+        ...(renderDeferred > 0 ? [`dispatch_context_render_deferred:${renderDeferred}`] : []),
+      ],
+      audit,
+    };
+  } catch {
+    return { items: [], deliveredIds: [], renderDeferred: 0, role, unresolvedGaps: [...sources.gaps, GAP_FAILED] };
+  }
+}

package/plugins/kxm/src/engine-plan.ts

@@ -94,6 +94,46 @@ export function kxmSha256(input: string): string {
   return `sha256:${createHash("sha256").update(input, "utf8").digest("hex")}`;
 }
 
+/**
+ * Stable identity of what one step asks of one agent. It is equal across runs
+ * of the same compiled step and agent, and it excludes the run, assignment and
+ * attempt ids, the run objective, repositories, model and the context packet,
+ * so a repeated ask is recognisable whatever the run was asked to do.
+ */
+export function kxmStepAskSha256(plan: KxmCompiledPlan, stepId: string, agentId: string): string {
+  const step = Object.hasOwn(plan.steps, stepId) ? plan.steps[stepId] : undefined;
+  if (!step) throw runtimeError("run_plan_corrupt", plan.workflowId, `compiled plan is missing step ${stepId}`);
+  return kxmSha256(kxmCanonicalJson({
+    v: 1,
+    workflowId: plan.workflowId,
+    stepId,
+    kind: step.kind,
+    agentId,
+    instructions: step.instructions ?? null,
+    outcomes: [...step.outcomes],
+    requiredEvidence: step.requiredEvidence.map((entry) => entry.key),
+  }));
+}
+
+/**
+ * The record-time verdict of one settled attempt. Only gate-negative results
+ * are known when the attempt settles: a back edge is 'blocked', and a producer
+ * error, an unknown outcome or a terminal failure is 'failed'. A forward edge
+ * or a completed terminal is undecided here; acceptance is resolved later from
+ * the event log, so this never returns 'accepted'.
+ */
+export function kxmAttemptFinalOutcome(
+  step: Pick<KxmCompiledStep, "transitions">,
+  settled: { readonly resultClass: string; readonly outcome?: string | undefined },
+): "blocked" | "failed" | undefined {
+  if (settled.resultClass !== "outcome") return "failed";
+  const outcome = settled.outcome;
+  const transition = outcome !== undefined && Object.hasOwn(step.transitions, outcome) ? step.transitions[outcome] : undefined;
+  if (!transition) return "failed";
+  if (transition.to === "terminal") return transition.terminalStatus === "completed" ? undefined : "failed";
+  return transition.edge === "back" ? "blocked" : undefined;
+}
+
 export function hashKxmRunPlanEnvelope(envelope: KxmRunPlanEnvelope): string {
   return kxmSha256(kxmCanonicalJson(envelope as unknown as JsonValue));
 }