@kontextmind/kxm 0.7.91 → 0.7.93

package/plugins/kxm/src/engine.ts

@@ -25,12 +25,22 @@ import {
   KXM_RUN_PLAN_SCHEMA,
   freezeKxmCompiledPlan,
   hashKxmRunPlanEnvelope,
+  kxmAttemptFinalOutcome,
+  kxmStepAskSha256,
   loadKxmRunPlanEnvelope,
   parseGateDefinition,
   rehydrateKxmCompiledPlanFromStore,
   type KxmPinnedGates,
   type KxmRunPlanEnvelope,
 } from "./engine-plan.ts";
+import {
+  EMPTY_DISPATCH_SOURCES,
+  NOT_LOADED_DISPATCH_SOURCES,
+  assembleDispatchContext,
+  dispatchContextPresent,
+  loadDispatchContextSources,
+  type DispatchContextSources,
+} from "./dispatch-context.ts";
 import { gateRegistryHash } from "./gate-hash.ts";
 import {
   admitKxmRun,
@@ -100,6 +110,7 @@ import {
   type KxmGateObservationInput,
 } from "./engine-gate-records.ts";
 import {
+  MAX_PROVIDER_METADATA_FIELDS,
   ROUTING_RECORD_V2_SCHEMA,
   type RoutingRecordV2,
   parseRoutingRecordV2,
@@ -916,8 +927,38 @@ export interface KxmGateDispatchSeams {
 
 export const kxmGateDispatchSeams: KxmGateDispatchSeams = {};
 
+/**
+ * Load the dispatch context for the step this drive is about to enter. Every
+ * git check, hash and file read happens here, before the IMMEDIATE transaction.
+ * A project with no authored memory and no promoted skill is detected by a
+ * directory probe alone and loads nothing. When the peek cannot see an agent
+ * step about to be entered, the sources are marked not loaded, so a birth that
+ * races the peek records a gap instead of dispatching unchecked context.
+ */
+function peekDispatchContextSources(context: KxmRuntimeContext, runId: string): DispatchContextSources {
+  if (!dispatchContextPresent(context.projectRoot)) return EMPTY_DISPATCH_SOURCES;
+  let run: KxmRunRecord;
+  try {
+    run = requireRun(context, runId);
+    const state = foldStoredKxmRun(context, run);
+    const plan = rehydrateKxmCompiledPlanFromStore(context.eventStore, run);
+    if (state.status !== "running" || state.currentStep) return NOT_LOADED_DISPATCH_SOURCES;
+    const next = plan.steps[state.pendingStepId ?? plan.entryStepId];
+    if (next?.kind !== "agent" && next?.kind !== "moa") return NOT_LOADED_DISPATCH_SOURCES;
+  } catch {
+    // prepareDispatch reads the same run and raises the authoritative error.
+    return NOT_LOADED_DISPATCH_SOURCES;
+  }
+  return loadDispatchContextSources({
+    projectRoot: context.projectRoot,
+    projectId: run.projectId,
+    pinnedMemoryRevision: run.memoryRevision,
+  });
+}
+
 async function stepLocked(context: KxmRuntimeContext, runId: string, producer: KxmProducer, token: string): Promise<KxmRunDriveResult> {
-  const prepared = context.eventStore.transaction(() => prepareDispatch(context, runId, producer.id));
+  const dispatchSources = peekDispatchContextSources(context, runId);
+  const prepared = context.eventStore.transaction(() => prepareDispatch(context, runId, producer.id, dispatchSources));
   if (prepared.kind === "return") {
     return prepared.handoff ? { state: prepared.state, handoff: prepared.handoff } : { state: prepared.state };
   }
@@ -1263,6 +1304,8 @@ interface PreparedPanel {
   maxParallel: number;
   first: PreparedDispatch;
   state: KxmRunState;
+  /** One snapshot shared by every member born for this step attempt. */
+  dispatchSources: DispatchContextSources;
 }
 
 export interface KxmPanelMemberHook {
@@ -1397,7 +1440,8 @@ function resolveProducerRoute(
 function prepareDispatch(
   context: KxmRuntimeContext,
   runId: string,
-  producerId?: "driver-simulated" | "pi" | string,
+  producerId: "driver-simulated" | "pi" | string | undefined,
+  dispatchSources: DispatchContextSources,
 ): { kind: "panel"; panel: PreparedPanel } | { kind: "return"; state: KxmRunState; handoff?: KxmRunHandoff } | ({ kind: "gate" } & KxmPreparedGateDispatch) {
   const run = requireRun(context, runId);
   const plan = rehydrateKxmCompiledPlanFromStore(context.eventStore, run);
@@ -1584,6 +1628,7 @@ function prepareDispatch(
     enterRunning: true,
     producerId,
     resolvedRoute,
+    dispatchSources,
   });
   return {
     kind: "panel",
@@ -1597,6 +1642,7 @@ function prepareDispatch(
       maxParallel: step.assignments.maxParallel,
       first,
       state: first.state,
+      dispatchSources,
     },
   };
 }
@@ -1643,6 +1689,7 @@ function birthMember(
     enterRunning?: boolean | undefined;
     producerId?: ("driver-simulated" | "pi" | string) | undefined;
     resolvedRoute?: { provider: string; model: string; selector: string } | undefined;
+    dispatchSources: DispatchContextSources;
   },
 ): PreparedDispatch {
   const run = requireRun(context, input.run.runId);
@@ -1671,6 +1718,15 @@ function birthMember(
       resolvedRoute = routeResult;
     }
   }
+  const dispatchContext = assembleDispatchContext(input.dispatchSources, {
+    projectId: run.projectId,
+    runId: run.runId,
+    stepId: input.stepId,
+    agentId,
+    task: [input.step.instructions, promptText]
+      .filter((part): part is string => typeof part === "string" && part.trim().length > 0)
+      .join("\n\n"),
+  });
   const assignmentId = newKxmAssignmentId();
   const attemptId = newKxmAttemptId();
   const minted = mintCapabilitySecret();
@@ -1738,6 +1794,8 @@ function birthMember(
       totalSteps: input.plan.order.length,
       settledDecisions: [],
     },
+    ...(dispatchContext.items.length > 0 ? { arbitratedItems: dispatchContext.items } : {}),
+    ...(dispatchContext.unresolvedGaps.length > 0 ? { unresolvedGaps: dispatchContext.unresolvedGaps } : {}),
   });
   const { packet: contextPacket } = pruneContextPacket(rawContextPacket);
   const generatedPrompt = formatContextPacketForPrompt(contextPacket);
@@ -1773,6 +1831,28 @@ function birthMember(
     controller,
     state: next,
   };
+  if (input.dispatchSources.present && context.logger) {
+    // Ids and counts only: never the task, the request, or any summary.
+    try {
+      context.logger({
+        event: "dispatch_context_assembled",
+        runId: run.runId,
+        stepId: input.stepId,
+        stepAttempt: input.stepAttempt,
+        agentId,
+        role: dispatchContext.role,
+        deliveredIds: dispatchContext.deliveredIds,
+        renderDeferred: dispatchContext.renderDeferred,
+        provenanceSummary: dispatchContext.audit?.provenanceSummary ?? {},
+        estimatedTokens: dispatchContext.audit?.estimatedTokens ?? 0,
+        budgetTokens: dispatchContext.audit?.budgetTokens ?? null,
+        skippedUnboundScopes: input.dispatchSources.skippedUnboundScopes,
+        unresolvedGaps: dispatchContext.unresolvedGaps,
+      });
+    } catch {
+      // Logging is best effort and never fails a birth.
+    }
+  }
   kxmPanelDispatchSeams.afterBirth?.(member);
   return member;
 }
@@ -1941,6 +2021,7 @@ async function drivePanel(
         stepId: panel.stepId,
         stepAttempt: panel.stepAttempt,
         producerId: producer.id,
+        dispatchSources: panel.dispatchSources,
       });
     });
   };
@@ -2076,7 +2157,44 @@ async function drivePanel(
   }
 }
 
-function producerRoutingRecord(context: KxmRuntimeContext, dispatch: PreparedDispatch, result: KxmProducerResult, now: string): RoutingRecordV2 {
+/** Engine-reserved providerMetadata keys. The engine writes them last, so a
+ * producer can never spoof the ask identity of the attempt it reports on. */
+const ENGINE_ROUTING_METADATA_KEYS: ReadonlySet<string> = new Set(["workflowId", "askSha256", "objectiveSha256", "stepWrites"]);
+const MAX_PRODUCER_ROUTING_METADATA_FIELDS = MAX_PROVIDER_METADATA_FIELDS - ENGINE_ROUTING_METADATA_KEYS.size;
+
+function engineRoutingMetadata(
+  dispatch: PreparedDispatch,
+  producer?: Record<string, string | number | boolean>,
+): Record<string, string | number | boolean> {
+  const metadata: Record<string, string | number | boolean> = {};
+  // A null producer map reads as absent, as the routing parser always treated it.
+  if (producer !== undefined && producer !== null) {
+    if (typeof producer !== "object" || Array.isArray(producer)) {
+      throw new Error("routing providerMetadata must be an object");
+    }
+    let kept = 0;
+    for (const [key, value] of Object.entries(producer)) {
+      if (kept >= MAX_PRODUCER_ROUTING_METADATA_FIELDS) break;
+      if (ENGINE_ROUTING_METADATA_KEYS.has(key)) continue;
+      metadata[key] = value;
+      kept += 1;
+    }
+  }
+  metadata.workflowId = dispatch.plan.workflowId;
+  metadata.askSha256 = kxmStepAskSha256(dispatch.plan, dispatch.stepId, dispatch.agentId);
+  // Already `sha256:<hex>` from acceptance; the prompt text is never read here.
+  metadata.objectiveSha256 = dispatch.run.promptSha256;
+  metadata.stepWrites = Object.values(dispatch.step.repositories).some((access) => access === "write");
+  return metadata;
+}
+
+function producerRoutingRecord(
+  context: KxmRuntimeContext,
+  dispatch: PreparedDispatch,
+  result: KxmProducerResult,
+  now: string,
+  finalOutcome?: "blocked" | "failed",
+): RoutingRecordV2 {
   const run = requireRun(context, dispatch.run.runId);
   if (result.costBasis === undefined || result.costBasis === null) {
     throw runtimeError("settle_missing_cost_basis", run.runId, `attempt settlement rejected: missing required costBasis for attempt ${dispatch.attemptId}`);
@@ -2107,9 +2225,12 @@ function producerRoutingRecord(context: KxmRuntimeContext, dispatch: PreparedDis
     retries: Math.max(0, dispatch.stepAttempt - 1),
     thinking: result.thinking ?? dispatch.request.thinking,
   };
-  for (const field of ["agentRole", "contextTokens", "tokensIn", "tokensOut", "cacheReadTokens", "cacheWriteTokens", "priceRef", "providerMetadata"] as const) {
+  for (const field of ["contextTokens", "tokensIn", "tokensOut", "cacheReadTokens", "cacheWriteTokens", "priceRef"] as const) {
     if (result[field] !== undefined) record[field] = result[field];
   }
+  record.agentRole = result.agentRole ?? dispatch.agentId;
+  record.providerMetadata = engineRoutingMetadata(dispatch, result.providerMetadata);
+  if (finalOutcome !== undefined) record.finalOutcome = finalOutcome;
   return parseRoutingRecordV2(record);
 }
 
@@ -2185,6 +2306,9 @@ function settleMember(
       costBasis: "unknown",
       costUsd: null,
       retries: Math.max(0, dispatch.stepAttempt - 1),
+      agentRole: dispatch.agentId,
+      finalOutcome: "failed",
+      providerMetadata: engineRoutingMetadata(dispatch),
     };
     push("routing.attempt.recorded", { routing: parseRoutingRecordV2(routingRecord) });
 
@@ -2200,10 +2324,18 @@ function settleMember(
     if (!result) {
       throw runtimeError("settle_missing_cost_basis", run.runId, `attempt settlement rejected: missing required costBasis for attempt ${dispatch.attemptId}`);
     }
-    push("routing.attempt.recorded", { routing: producerRoutingRecord(context, dispatch, result, now) });
-
     const outcome = typeof result.outcome === "string" ? result.outcome : undefined;
     const known = outcome !== undefined && dispatch.step.outcomes.includes(outcome);
+    push("routing.attempt.recorded", {
+      routing: producerRoutingRecord(
+        context,
+        dispatch,
+        result,
+        now,
+        known ? kxmAttemptFinalOutcome(dispatch.step, { resultClass: "outcome", outcome }) : "failed",
+      ),
+    });
+
     if (!known) {
       push("assignment.result_recorded", {
         assignmentId: dispatch.assignmentId,

package/plugins/kxm/src/hub-env.ts

@@ -192,7 +192,7 @@ export function resolveHubCredentials(options: ResolveHubCredentialsOptions = {}
   };
 }
 
-/** Read-only token for one-shot hub clients (CLI, MCP server, dashboards).
+/** Read-only token for one-shot operator hub clients (CLI, runtime supervisor, dashboards).
  *
  * Precedence: explicit KXM_AUTH_TOKEN, then the persisted project token for
  * the resolved project, then the persisted admin token. Never generates or
@@ -235,6 +235,22 @@ export function resolveClientHubAuthToken(env: NodeJS.ProcessEnv, project: strin
   return record?.projectTokens?.[project]?.trim() || record?.authToken?.trim() || undefined;
 }
 
+/**
+ * Token an agent session (the Claude MCP server) registers with: explicit `KXM_AUTH_TOKEN`,
+ * else the persisted project token for `project`, else nothing. It never returns the
+ * persisted admin token. The hub accepts the admin token for any project missing from its
+ * project-token map, so an agent falling back to it would join a project nobody issued it a
+ * token for. Operator tools keep `resolveClientHubAuthToken`. Throws HubEnvError on a
+ * malformed persisted record, same as `resolveClientHubAuthToken`.
+ */
+export function resolveAgentHubAuthToken(env: NodeJS.ProcessEnv, project: string): string | undefined {
+  const envToken = env.KXM_AUTH_TOKEN?.trim();
+  if (envToken) return envToken;
+  const tokens = readHubEnvRecord(env)?.projectTokens;
+  if (!tokens || !Object.hasOwn(tokens, project)) return undefined;
+  return tokens[project]?.trim() || undefined;
+}
+
 /**
  * Admin-scoped hub reads (`/v1/ops/snapshot`, …) are rejected with 401 by a project token,
  * so this variant resolves the admin credential only: explicit `KXM_AUTH_TOKEN`, else the

package/plugins/kxm/src/hub.ts

@@ -11,6 +11,7 @@ import {
   DEFAULT_RATE_LIMIT_MAX,
   DEFAULT_RATE_LIMIT_WINDOW_MS,
   DEFAULT_STALE_AFTER_MS,
+  IMPROVEMENT_AREAS,
   MAX_AGENT_HOST_CHARS,
   MAX_BODY_BYTES,
   MAX_CONTENT_CHARS,
@@ -45,6 +46,7 @@ import { timingSafeStringCompare } from "./commands.ts";
 import { arbitrate, explainContextItem, journalEntryToContextItem, memoryRecordToContextItem, rolePolicy } from "./arbiter.ts";
 import { loadAuthoredMemory } from "./memory.ts";
 import { contextItemAuditMetadata, CONTEXT_AUTHORITIES, CONTEXT_CONFIDENCES, type ContextAuthority, type ContextConfidence, type ContextItem } from "./context.ts";
+import { rankRecall, relevanceTokens } from "./relevance.ts";
 import { NativeStateProvider } from "./state.ts";
 import { SkillLifecycle } from "./skills.ts";
 import { compileKnowledgeWiki, lintKnowledgeWiki, type WikiSourcePool } from "./wiki.ts";
@@ -56,8 +58,11 @@ import {
   checkpointRun,
   improvementReport,
   applyJournalPromotion,
+  JOURNAL_CATEGORIES,
+  journalAttemptFor,
   journalEvidenceRequired,
   parseJournalCategory,
+  rankImprovementSignals,
   renderWorkflowPrompt,
   resumeWorkflowFromSignal,
   valueAtPath,
@@ -1007,7 +1012,7 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
       "Execute these stages in order:",
       stageList,
       "",
-      "At every stage, record material plans, decisions, contradictions, errors, and lessons with kxm_workflow_record.",
+      `At every stage, record material knowledge with kxm_workflow_record in one of these categories: ${JOURNAL_CATEGORIES.join(", ")}. Pass the stageId the entry belongs to; the hub binds the attempt and, when you omit area, uses the stage's declared area.`,
       "Keep repository-local configuration in .kxm/config, logs in .kxm/logs, and durable workflow artifacts in .kxm/assets; never commit runtime logs, state, or secrets.",
       "Complete each stage with kxm_workflow_checkpoint. Supply evidence as an object whose keys exactly match the stage's required evidence keys. Unrelated keys never satisfy a requirement. A warning or failure must be corrected and checkpointed again until it passes or the attempt limit is reached.",
       "For a peer-evidence requirement, send or fan out with workflowContext containing this run ID, the exact stage ID, requirement key, and current 1-based attempt. At checkpoint, cite only the returned message IDs under evidenceRefs; the hub derives producer and reply provenance.",
@@ -1047,7 +1052,7 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
       `Evidence: ${workflowEvidenceStrings(evidence).join(", ") || "none supplied"}`,
       "",
       nextInstruction,
-      "Review the run with kxm_workflow_get and keep recording material plans, decisions, contradictions, errors, and lessons.",
+      "Review the run with kxm_workflow_get and keep recording material learning with kxm_workflow_record (any of its ten categories; pass stageId for stage-bound entries).",
       "Do not claim the workflow is complete until the checkpoint response reports completed=true.",
     ].join("\n"), "workflow resume prompt", { max: MAX_CONTENT_CHARS });
     const seq = store.nextAgentSequence(run.targetAgentId);
@@ -1103,6 +1108,7 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
         evidence: [`wait-created:${waiting.createdAt}`, `wait-expired:${waiting.expiresAt}`],
         relatedEntryIds: [],
         createdAt: timestamp,
+        ...(stage ? { stageId: stage.id, attempt: stage.attempts + 1 } : {}),
       };
       const definition = webhookWorkflows.get(transition.definitionId);
       const ttlMs = parseBoundedInteger(
@@ -1183,6 +1189,7 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
           (candidate) => candidate.messageId === message.id && candidate.status === "running",
         );
         if (run) {
+          const expiredStage = run.stages.find((candidate) => candidate.id === run.currentStage);
           run.status = "failed";
           delete run.currentStage;
           run.updatedAt = nowIso();
@@ -1199,6 +1206,7 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
             evidence: [`message:${message.id}`],
             relatedEntryIds: [],
             createdAt: run.updatedAt,
+            ...(expiredStage ? { stageId: expiredStage.id, attempt: expiredStage.attempts + 1 } : {}),
           };
           store.saveJournalEntry(entry);
           counters.journalEntries += 1;
@@ -1406,6 +1414,8 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
             evidence: workflowEvidenceStrings(evidence),
             relatedEntryIds: [],
             createdAt: receivedAt,
+            stageId: stage.id,
+            attempt: stage.attempts,
           };
         } else if (result.degraded) {
           const stage = transition.stages.find((candidate) => candidate.id === result.stageId)!;
@@ -1423,6 +1433,8 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
             ],
             relatedEntryIds: [],
             createdAt: receivedAt,
+            stageId: stage.id,
+            attempt: stage.attempts,
           };
         }
         if (transition.status === "running") {
@@ -1700,6 +1712,8 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
             ],
             relatedEntryIds: [],
             createdAt: timestamp,
+            stageId,
+            attempt: result.approval.attempt,
           };
           store.saveWorkflowTransition(transition, undefined, entry);
           publishOps(transition.project, "workflows");
@@ -1781,9 +1795,18 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
           ...(skillLifecycle ? { skillLifecycle } : {}),
         });
         counters.contextRequests += 1;
+        // Sizes, never the task text (Q-J). The caller still receives its own
+        // audit, request included, in the response below.
+        const assembledRequest = outcome.audit.request;
         logger({
           event: "context_packet_assembled",
-          ...outcome.audit.request,
+          project: assembledRequest.project,
+          role: assembledRequest.role,
+          ...(assembledRequest.workflowRunId !== undefined ? { workflowRunId: assembledRequest.workflowRunId } : {}),
+          ...(assembledRequest.stageId !== undefined ? { stageId: assembledRequest.stageId } : {}),
+          taskChars: assembledRequest.task.length,
+          taskTokens: outcome.audit.relevance.taskTokens,
+          matchedCandidates: outcome.audit.relevance.matchedCandidates,
           selectedIds: outcome.audit.selectedIds,
           provenanceSummary: outcome.audit.provenanceSummary,
           estimatedTokens: outcome.audit.estimatedTokens,
@@ -1799,21 +1822,30 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
       if (method === "POST" && contextRecallMatch) {
         const body = await readJson(request);
         const { project: callerProject, caller: callerId } = contextCallerProject(request, body.project);
-        const query = requireString(body.query ?? "", "query", { max: 500, allowEmpty: true }).toLowerCase();
+        const query = requireString(body.query ?? "", "query", { max: 500, allowEmpty: true });
         const kinds = Array.isArray(body.kinds)
           ? body.kinds.filter((kind: unknown): kind is string => typeof kind === "string")
           : undefined;
         const limit = parseBoundedInteger(body.limit, "limit", 25, 1, 100);
         const { pool } = projectContextPool(callerProject);
-        const recalled = pool
+        const live = pool
           .filter((item) => item.status !== "superseded" && item.status !== "rejected")
-          .filter((item) => kinds === undefined || kinds.includes(item.kind))
-          .filter((item) => query === "" || item.summary.toLowerCase().includes(query) || (item.stateKey ?? "").toLowerCase().includes(query))
-          .sort((left, right) => left.id.localeCompare(right.id))
-          .slice(0, limit);
+          .filter((item) => kinds === undefined || kinds.includes(item.kind));
+        // Exact-phrase hits, then any-token BM25 hits, then id.
+        const recalled = rankRecall(query, live, limit);
         counters.contextRequests += 1;
-        logger({ event: "context_recall", project: callerProject, query, limit, results: recalled.length });
-        json(response, 200, { items: recalled.map(contextItemAuditMetadata), unresolvedGaps: recalled.length === 0 ? ["no matching context records"] : [] });
+        logger({
+          event: "context_recall",
+          project: callerProject,
+          queryChars: query.length,
+          queryTokens: new Set(relevanceTokens(query)).size,
+          limit,
+          results: recalled.length,
+        });
+        json(response, 200, {
+          items: recalled.map(({ item, relevance }) => ({ ...contextItemAuditMetadata(item), relevance })),
+          unresolvedGaps: recalled.length === 0 ? ["no matching context records"] : [],
+        });
         return;
       }
 
@@ -1982,7 +2014,13 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
           nowIso(),
         );
         store.saveJournalEntry(updated);
-        publishOps(entry.runId, "workflows");
+        // Publish to the run's project (not its id) and refresh a terminal
+        // run's exported retrospective with the new promotion state.
+        const promotedRun = workflowRuns.get(entry.runId);
+        if (promotedRun) {
+          publishOps(promotedRun.project, "workflows");
+          exportTerminalRetrospective(promotedRun);
+        }
         logger({
           event: "journal_promotion_recorded",
           journalEntryId: entry.id,
@@ -2120,6 +2158,9 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
             : undefined,
         );
         const checkpointStage = transition.stages.find((candidate) => candidate.id === stageId)!;
+        // The attempt this checkpoint consumed. A self-edge transition re-enters
+        // the stage and resets its counter, so prefer the transition record.
+        const checkpointAttempt = result.transition?.attempt ?? checkpointStage.attempts;
         if (result.transition) {
           const transitionEntry: WorkflowJournalEntry = {
             id: newId("journal"),
@@ -2132,6 +2173,8 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
             evidence: result.transition.evidenceKeys.map((key) => `requirement:${key}`),
             relatedEntryIds: [],
             createdAt: timestamp,
+            stageId,
+            attempt: checkpointAttempt,
           };
           store.saveWorkflowTransition(transition, undefined, transitionEntry);
           counters.journalEntries += 1;
@@ -2148,6 +2191,8 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
             evidence: [`class:transition_budget_exhausted`, `stage:${stageId}`],
             relatedEntryIds: [],
             createdAt: timestamp,
+            stageId,
+            attempt: checkpointAttempt,
           };
           store.saveWorkflowTransition(transition, undefined, exhaustEntry);
           counters.journalEntries += 1;
@@ -2165,6 +2210,8 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
             evidence: workflowEvidenceStrings(evidence),
             relatedEntryIds: [],
             createdAt: transition.updatedAt,
+            stageId,
+            attempt: checkpointAttempt,
           };
         } else if (result.degraded) {
           entry = {
@@ -2181,6 +2228,8 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
             ],
             relatedEntryIds: [],
             createdAt: transition.updatedAt,
+            stageId,
+            attempt: checkpointAttempt,
           };
         }
         store.saveWorkflowTransition(transition, undefined, entry);
@@ -2226,10 +2275,25 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
           );
         }
         const category = parseJournalCategory(body.category);
-        const area = requireString(body.area, "area", { max: 24 }) as ImprovementArea;
-        if (!["harness", "gates", "implementation", "workflow", "documentation", "security", "other"].includes(area)) {
-          throw new ProtocolError(400, "invalid improvement area", "invalid_improvement_area");
+        // Stage provenance first: the stage supplies the default area, and
+        // the hub (never the caller) derives the attempt from its state.
+        let stage: WorkflowStageState | undefined;
+        if (body.stageId !== undefined && body.stageId !== null) {
+          const requestedStageId = requireString(body.stageId, "stageId", { max: 128 });
+          stage = run.stages.find((candidate) => candidate.id === requestedStageId);
+          if (!stage) {
+            throw new ProtocolError(400, `stageId ${requestedStageId} is not part of this workflow run`, "invalid_journal_relation");
+          }
         }
+        const area = (body.area == null ? stage?.area : requireString(body.area, "area", { max: 24 })) as ImprovementArea | undefined;
+        if (area === undefined || !IMPROVEMENT_AREAS.includes(area)) {
+          throw new ProtocolError(
+            400,
+            "area is required unless stageId names a stage that declares an area",
+            "invalid_improvement_area",
+          );
+        }
+        const attempt = stage ? journalAttemptFor(stage) : undefined;
         const severity = requireString(body.severity ?? "info", "severity", { max: 16 });
         if (severity !== "info" && severity !== "warning" && severity !== "error") {
           throw new ProtocolError(400, "severity must be info, warning, or error", "invalid_journal_severity");
@@ -2250,16 +2314,6 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
             "journal_evidence_required",
           );
         }
-        let stageId: string | undefined;
-        let attempt: number | undefined;
-        if (body.stageId !== undefined && body.stageId !== null) {
-          stageId = requireString(body.stageId, "stageId", { max: 128 });
-          const stage = run.stages.find((candidate) => candidate.id === stageId);
-          if (!stage) {
-            throw new ProtocolError(400, `stageId ${stageId} is not part of this workflow run`, "invalid_journal_relation");
-          }
-          attempt = stage.attempts + 1;
-        }
         const entry: WorkflowJournalEntry = {
           id: newId("journal"),
           runId: run.id,
@@ -2272,11 +2326,13 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
           evidence,
           relatedEntryIds,
           createdAt: nowIso(),
-          ...(stageId !== undefined ? { stageId } : {}),
+          ...(stage !== undefined ? { stageId: stage.id } : {}),
           ...(attempt !== undefined ? { attempt } : {}),
         };
         store.saveJournalEntry(entry);
         counters.journalEntries += 1;
+        // A late entry on a terminal run refreshes its exported retrospective.
+        exportTerminalRetrospective(run);
         logger({
           event: "workflow_journal_recorded",
           workflowRunId: run.id,
@@ -2292,13 +2348,18 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
       if (method === "GET" && url.pathname === "/v1/improvements") {
         const agent = requireAgent(request);
         requireProjectAuth(request, agent.project);
-        const visibleRuns = new Set(
+        const projectRuns = new Map(
           [...workflowRuns.values()]
             .filter((run) => run.project === agent.project)
-            .map((run) => run.id),
+            .map((run) => [run.id, run] as const),
         );
+        const visibleRuns = new Set(projectRuns.keys());
         const entries = [...journal.values()].filter((entry) => visibleRuns.has(entry.runId));
-        json(response, 200, { reports: improvementReport(entries), entries: entries.length });
+        json(response, 200, {
+          reports: improvementReport(entries),
+          signals: rankImprovementSignals(entries, projectRuns),
+          entries: entries.length,
+        });
         return;
       }
 
@@ -2755,6 +2816,7 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
         publishOps(message.project, "messages");
         const workflowRun = [...workflowRuns.values()].find((run) => run.messageId === message.id);
         if (workflowRun?.status === "running") {
+          const settledStage = workflowRun.stages.find((candidate) => candidate.id === workflowRun.currentStage);
           workflowRun.status = "failed";
           delete workflowRun.currentStage;
           workflowRun.updatedAt = message.repliedAt;
@@ -2771,6 +2833,7 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
             evidence: [`message:${message.id}`],
             relatedEntryIds: [],
             createdAt: message.repliedAt,
+            ...(settledStage ? { stageId: settledStage.id, attempt: settledStage.attempts + 1 } : {}),
           };
           store.saveJournalEntry(entry);
           counters.journalEntries += 1;