@kontextmind/kxm 0.6.0

package/plugins/kxm/src/price-calc.ts

@@ -0,0 +1,87 @@
+export const PRICES_SCHEMA = "kxm.prices.v1";
+
+export interface PriceTier {
+  readonly upToContextTokens?: number | null | undefined;
+  readonly inputPerMillion: number;
+  readonly outputPerMillion: number;
+  readonly cacheReadPerMillion?: number | null | undefined;
+  readonly cacheWritePerMillion?: number | null | undefined;
+}
+
+export interface ModelPriceRow {
+  readonly id: string;
+  readonly provider: string;
+  readonly model: string;
+  readonly aliases?: readonly string[] | undefined;
+  readonly tiers: readonly PriceTier[];
+}
+
+export interface PriceCatalog {
+  readonly schema: typeof PRICES_SCHEMA;
+  readonly date: string;
+  readonly sha256: string;
+  readonly currency?: string | undefined;
+  readonly models: readonly ModelPriceRow[];
+}
+
+export function findModelPrice(catalog: PriceCatalog, model: string, provider?: string): ModelPriceRow | undefined {
+  const normalizedModel = model.trim().toLowerCase();
+  const normalizedProvider = provider?.trim().toLowerCase();
+
+  for (const entry of catalog.models) {
+    if (normalizedProvider && entry.provider.toLowerCase() !== normalizedProvider) {
+      const matchesAlias = entry.aliases?.some((a) => a.toLowerCase() === normalizedModel);
+      if (!matchesAlias) continue;
+    }
+    if (entry.id.toLowerCase() === normalizedModel || entry.model.toLowerCase() === normalizedModel) {
+      return entry;
+    }
+    if (entry.aliases?.some((a) => a.toLowerCase() === normalizedModel)) {
+      return entry;
+    }
+  }
+  return undefined;
+}
+
+export function calculateModelCost(
+  catalog: PriceCatalog,
+  params: {
+    model: string;
+    provider?: string;
+    tokensIn?: number | null;
+    tokensOut?: number | null;
+    cacheReadTokens?: number | null;
+    cacheWriteTokens?: number | null;
+    contextTokens?: number | null;
+  },
+): { costUsd: number; priceRef: string } | undefined {
+  const row = findModelPrice(catalog, params.model, params.provider);
+  if (!row || row.tiers.length === 0) return undefined;
+
+  const context = params.contextTokens ?? params.tokensIn ?? 0;
+  let selectedTier = row.tiers[0]!;
+  for (const tier of row.tiers) {
+    if (tier.upToContextTokens !== undefined && tier.upToContextTokens !== null && context > tier.upToContextTokens) {
+      continue;
+    }
+    selectedTier = tier;
+    break;
+  }
+
+  const tokensIn = params.tokensIn ?? 0;
+  const tokensOut = params.tokensOut ?? 0;
+  const cacheRead = params.cacheReadTokens ?? 0;
+  const cacheWrite = params.cacheWriteTokens ?? 0;
+
+  const cost =
+    (tokensIn / 1_000_000) * selectedTier.inputPerMillion +
+    (tokensOut / 1_000_000) * selectedTier.outputPerMillion +
+    (cacheRead / 1_000_000) * (selectedTier.cacheReadPerMillion ?? 0) +
+    (cacheWrite / 1_000_000) * (selectedTier.cacheWritePerMillion ?? 0);
+
+  const priceRef = `${catalog.date}#${row.id}`;
+  return {
+    costUsd: Math.round(cost * 1_000_000) / 1_000_000,
+    priceRef,
+  };
+}

package/plugins/kxm/src/prices.ts

@@ -0,0 +1,121 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+
+export * from "./price-calc.ts";
+import type { PriceCatalog, ModelPriceRow, PriceTier } from "./price-calc.ts";
+import { PRICES_SCHEMA } from "./price-calc.ts";
+
+export function hashPriceCatalog(catalog: Omit<PriceCatalog, "sha256">): string {
+  const canonical = {
+    schema: catalog.schema,
+    date: catalog.date,
+    currency: catalog.currency ?? "USD",
+    models: catalog.models.map((m) => ({
+      id: m.id,
+      provider: m.provider,
+      model: m.model,
+      aliases: m.aliases ? [...m.aliases].sort() : [],
+      tiers: m.tiers.map((t) => ({
+        upToContextTokens: t.upToContextTokens ?? null,
+        inputPerMillion: t.inputPerMillion,
+        outputPerMillion: t.outputPerMillion,
+        cacheReadPerMillion: t.cacheReadPerMillion ?? null,
+        cacheWritePerMillion: t.cacheWritePerMillion ?? null,
+      })),
+    })).sort((a, b) => a.id.localeCompare(b.id)),
+  };
+  return createHash("sha256").update(JSON.stringify(canonical), "utf8").digest("hex");
+}
+
+export function parsePriceCatalog(text: string): PriceCatalog {
+  const parsed = parse(text) as Record<string, unknown>;
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("price catalog must be an object");
+  }
+  if (parsed.schema !== PRICES_SCHEMA) {
+    throw new Error(`price catalog schema must be ${PRICES_SCHEMA}`);
+  }
+  if (typeof parsed.date !== "string" || !/^[0-9]{4}-[0-9]{2}-[0-9]{2}$/.test(parsed.date)) {
+    throw new Error("price catalog date must be YYYY-MM-DD");
+  }
+  if (typeof parsed.sha256 !== "string" || !/^(?:sha256:)?[a-f0-9]{64}$/.test(parsed.sha256)) {
+    throw new Error("price catalog sha256 must be a 64-character hex digest");
+  }
+  if (!Array.isArray(parsed.models) || parsed.models.length === 0) {
+    throw new Error("price catalog models must be a non-empty array");
+  }
+  const models: ModelPriceRow[] = parsed.models.map((item, index) => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      throw new Error(`price catalog model at index ${index} must be an object`);
+    }
+    const m = item as Record<string, unknown>;
+    if (typeof m.id !== "string" || !m.id) {
+      throw new Error(`price catalog model at index ${index} must have a non-empty id`);
+    }
+    if (typeof m.provider !== "string" || !m.provider) {
+      throw new Error(`price catalog model at index ${index} must have a non-empty provider`);
+    }
+    if (typeof m.model !== "string" || !m.model) {
+      throw new Error(`price catalog model at index ${index} must have a non-empty model`);
+    }
+    const aliases = Array.isArray(m.aliases)
+      ? m.aliases.filter((a): a is string => typeof a === "string" && Boolean(a))
+      : undefined;
+    if (!Array.isArray(m.tiers) || m.tiers.length === 0) {
+      throw new Error(`price catalog model ${m.id} must have at least one tier`);
+    }
+    const tiers: PriceTier[] = m.tiers.map((tItem, tIndex) => {
+      if (!tItem || typeof tItem !== "object" || Array.isArray(tItem)) {
+        throw new Error(`tier at index ${tIndex} for model ${m.id} must be an object`);
+      }
+      const t = tItem as Record<string, unknown>;
+      const inputRate = typeof t.inputPerMillion === "number" ? t.inputPerMillion : (typeof t.input === "number" ? t.input : undefined);
+      const outputRate = typeof t.outputPerMillion === "number" ? t.outputPerMillion : (typeof t.output === "number" ? t.output : undefined);
+      if (inputRate === undefined || inputRate < 0) {
+        throw new Error(`tier at index ${tIndex} for model ${m.id} must have a non-negative inputPerMillion`);
+      }
+      if (outputRate === undefined || outputRate < 0) {
+        throw new Error(`tier at index ${tIndex} for model ${m.id} must have a non-negative outputPerMillion`);
+      }
+      return {
+        upToContextTokens: typeof t.upToContextTokens === "number" ? t.upToContextTokens : null,
+        inputPerMillion: inputRate,
+        outputPerMillion: outputRate,
+        cacheReadPerMillion: typeof t.cacheReadPerMillion === "number" ? t.cacheReadPerMillion : (typeof t.cacheRead === "number" ? t.cacheRead : null),
+        cacheWritePerMillion: typeof t.cacheWritePerMillion === "number" ? t.cacheWritePerMillion : (typeof t.cacheWrite === "number" ? t.cacheWrite : null),
+      };
+    });
+    return {
+      id: m.id,
+      provider: m.provider,
+      model: m.model,
+      aliases,
+      tiers,
+    };
+  });
+
+  return {
+    schema: PRICES_SCHEMA,
+    date: parsed.date,
+    sha256: parsed.sha256.replace(/^sha256:/, ""),
+    currency: typeof parsed.currency === "string" ? parsed.currency : "USD",
+    models,
+  };
+}
+
+export function loadPriceCatalog(rootOrPath: string): PriceCatalog | undefined {
+  const candidatePath = existsSync(join(rootOrPath, ".kxm", "prices.yaml"))
+    ? join(rootOrPath, ".kxm", "prices.yaml")
+    : (existsSync(join(rootOrPath, "prices.yaml"))
+      ? join(rootOrPath, "prices.yaml")
+      : (existsSync(rootOrPath) && !rootOrPath.endsWith("/") ? rootOrPath : undefined));
+
+  if (!candidatePath || !existsSync(candidatePath)) {
+    return undefined;
+  }
+  const content = readFileSync(candidatePath, "utf8");
+  return parsePriceCatalog(content);
+}
+

package/plugins/kxm/src/protocol.ts

@@ -0,0 +1,172 @@
+import { randomUUID } from "node:crypto";
+
+export const DEFAULT_PORT = 7331;
+export const DEFAULT_STALE_AFTER_MS = 30_000;
+export const DEFAULT_MAX_HOPS = 5;
+export const DEFAULT_MESSAGE_TTL_MS = 24 * 60 * 60_000;
+export const MIN_MESSAGE_TTL_MS = 1_000;
+export const MAX_MESSAGE_TTL_MS = 7 * 24 * 60 * 60_000;
+export const DEFAULT_MESSAGE_RETENTION_MS = 7 * 24 * 60 * 60_000;
+export const MIN_MESSAGE_RETENTION_MS = 1_000;
+export const DEFAULT_RATE_LIMIT_MAX = 600;
+export const DEFAULT_RATE_LIMIT_WINDOW_MS = 60_000;
+export const MAX_BODY_BYTES = 256 * 1024;
+export const MAX_CONTENT_CHARS = 32_000;
+
+export type DeliveryMode = "steer" | "followUp" | "nextTurn";
+export type MessageStatus = "queued" | "delivered" | "replied" | "cancelled" | "expired" | "error";
+
+export interface AgentRecord {
+  id: string;
+  name: string;
+  purpose: string;
+  project: string;
+  model?: string;
+  connectedAt: string;
+  lastSeenAt: string;
+  online: boolean;
+}
+
+export interface MessageReply {
+  content: string;
+  createdAt: string;
+}
+
+/** Hub-authorized scope for a peer request that may later be cited as
+ * workflow evidence. Callers request this scope, but the hub validates it
+ * against the active run and persists the canonical value. */
+export interface WorkflowMessageContext {
+  schema: "pi-mesh.workflow-message-context.v1";
+  runId: string;
+  stageId: string;
+  requirementKey: string;
+  attempt: number;
+}
+
+export type WorkflowCheckpointStatus = "passed" | "warning" | "failed";
+export type JournalCategory =
+  | "plan"
+  | "decision"
+  | "contradiction"
+  | "error"
+  | "lesson"
+  | "observation"
+  | "hypothesis"
+  | "experiment"
+  | "state-change"
+  | "skill-candidate";
+export type ImprovementArea = "harness" | "gates" | "implementation" | "workflow" | "documentation" | "security" | "other";
+
+/** Evidence submitted for one checkpoint or external signal, keyed by a
+ * requirement from WorkflowStageDefinition.requiredEvidence. */
+export type WorkflowEvidenceInput = Record<string, string>;
+
+/** Callers cite durable message IDs only. Producer identity and the evidence
+ * snapshot are derived by the hub from the stored message. */
+export interface WorkflowEvidenceReference {
+  messageIds: string[];
+}
+
+export type WorkflowEvidenceReferenceInput = Record<string, WorkflowEvidenceReference>;
+
+export interface MessageRecord {
+  id: string;
+  project: string;
+  from: string;
+  fromName: string;
+  to: string;
+  toName: string;
+  content: string;
+  delivery: DeliveryMode;
+  hops: number;
+  maxHops: number;
+  correlationId?: string;
+  replyTo?: string;
+  idempotencyKey?: string;
+  seq?: number;
+  /** Hub-owned durable workflow affinity. Callers cannot establish this field
+   * directly; the hub derives it from an authorized workflow context or an
+   * internally-created workflow prompt. */
+  workflowRunId?: string;
+  workflowContext?: WorkflowMessageContext;
+  createdAt: string;
+  expiresAt: string;
+  deliveredAt?: string;
+  repliedAt?: string;
+  cancelledAt?: string;
+  status: MessageStatus;
+  reply?: MessageReply;
+  error?: string;
+}
+
+export type HubEvent =
+  | { type: "message"; message: MessageRecord }
+  | { type: "reply"; message: MessageRecord }
+  | { type: "cancelled"; message: MessageRecord }
+  | { type: "expired"; message: MessageRecord }
+  | { type: "presence"; agent: AgentRecord };
+
+export class ProtocolError extends Error {
+  readonly statusCode: number;
+  readonly code: string;
+  readonly extras?: Record<string, unknown>;
+
+  constructor(statusCode: number, message: string, code = "protocol_error", extras?: Record<string, unknown>) {
+    super(message);
+    this.name = "ProtocolError";
+    this.statusCode = statusCode;
+    this.code = code;
+    if (extras) this.extras = extras;
+  }
+}
+
+export function nowIso(): string {
+  return new Date().toISOString();
+}
+
+export function newId(prefix: string): string {
+  return `${prefix}_${randomUUID().replaceAll("-", "")}`;
+}
+
+export function requireString(
+  value: unknown,
+  field: string,
+  options: { max?: number; allowEmpty?: boolean } = {},
+): string {
+  if (typeof value !== "string") {
+    throw new ProtocolError(400, `${field} must be a string`);
+  }
+  const result = value.trim();
+  if (!options.allowEmpty && result.length === 0) {
+    throw new ProtocolError(400, `${field} cannot be empty`);
+  }
+  if (options.max !== undefined && result.length > options.max) {
+    throw new ProtocolError(400, `${field} exceeds ${options.max} characters`);
+  }
+  return result;
+}
+
+export function optionalString(value: unknown, field: string, max: number): string | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  return requireString(value, field, { max });
+}
+
+export function parseDeliveryMode(value: unknown): DeliveryMode {
+  if (value === undefined) return "followUp";
+  if (value === "steer" || value === "followUp" || value === "nextTurn") return value;
+  throw new ProtocolError(400, "delivery must be steer, followUp, or nextTurn");
+}
+
+export function parseBoundedInteger(
+  value: unknown,
+  field: string,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
+  if (value === undefined) return fallback;
+  if (!Number.isInteger(value) || (value as number) < min || (value as number) > max) {
+    throw new ProtocolError(400, `${field} must be an integer between ${min} and ${max}`);
+  }
+  return value as number;
+}

package/plugins/kxm/src/recovery.ts

@@ -0,0 +1,211 @@
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { HubHttpError, type HubClient } from "./client.ts";
+import { classifyFailure, diagnosticEvidence } from "./diagnostics.ts";
+
+export interface WorkerRecoveryEnvelope {
+  version: 1;
+  reason: "missing_tool_result" | "unresumable_session" | "provider_error" | "tool_timeout" | "worker_signal";
+  agentName: string;
+  project: string;
+  workerKey?: string;
+  generation?: string;
+  previousContinue: boolean;
+  freshSession: boolean;
+  sessionBinding?: { kind: "default" } | { kind: "workflow"; runId: string };
+  failureClass?: "quota" | "provider_error" | "timeout";
+  signal?: string;
+  createdAt: string;
+  runId?: string | null;
+  stageId?: string | null;
+  activeMessageIds?: string[];
+  pendingMessageIds?: string[];
+  artifactPointers?: string[];
+  /** Runtime-only disposition; never written by the supervisor. */
+  peerLocal?: boolean;
+}
+
+export function workerStateKey(project: string, agentName: string): string {
+  const safeProject = project.replace(/[^A-Za-z0-9_.-]/g, "_").slice(0, 24) || "project";
+  const safeName = agentName.replace(/[^A-Za-z0-9_.-]/g, "_").slice(0, 32) || "agent";
+  const digest = createHash("sha256")
+    .update(JSON.stringify({ project, agentName }))
+    .digest("hex")
+    .slice(0, 24);
+  return `${safeProject}-${safeName}-${digest}`;
+}
+
+function legacyRecoveryEnvelopePath(stateDir: string, agentName: string): string {
+  const safeName = agentName.replace(/[^A-Za-z0-9_.-]/g, "_");
+  return join(stateDir, `worker-recovery-${safeName}.json`);
+}
+
+export function recoveryEnvelopePath(stateDir: string, agentName: string, project?: string): string {
+  return project
+    ? join(stateDir, `worker-recovery-${workerStateKey(project, agentName)}.json`)
+    : legacyRecoveryEnvelopePath(stateDir, agentName);
+}
+
+const recoveryReasons = new Set<WorkerRecoveryEnvelope["reason"]>([
+  "missing_tool_result", "unresumable_session", "provider_error", "tool_timeout", "worker_signal",
+]);
+const recoveryRunId = /^run_[a-f0-9]{32}$/;
+const recoveryMessageId = /^msg_[a-f0-9]{32}$/;
+
+function validBoundedStrings(value: unknown, maxItems: number, pattern?: RegExp): value is string[] {
+  return Array.isArray(value)
+    && value.length <= maxItems
+    && value.every((item) => typeof item === "string" && item.length > 0 && item.length <= 2_048 && !/[\0\r\n]/.test(item) && (!pattern || pattern.test(item)));
+}
+
+function parseRecoveryEnvelope(value: unknown, agentName: string, project?: string): WorkerRecoveryEnvelope {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("recovery envelope must be an object");
+  const parsed = value as Partial<WorkerRecoveryEnvelope>;
+  if (
+    parsed.version !== 1
+    || !recoveryReasons.has(parsed.reason as WorkerRecoveryEnvelope["reason"])
+    || parsed.agentName !== agentName
+    || typeof parsed.project !== "string"
+    || parsed.project.length < 1
+    || parsed.project.length > 128
+    || (project !== undefined && parsed.project !== project)
+    || typeof parsed.previousContinue !== "boolean"
+    || typeof parsed.freshSession !== "boolean"
+    || typeof parsed.createdAt !== "string"
+    || !Number.isFinite(Date.parse(parsed.createdAt))
+  ) throw new Error("recovery envelope identity or schema is invalid");
+  if (parsed.runId !== undefined && parsed.runId !== null && !recoveryRunId.test(parsed.runId)) {
+    throw new Error("recovery envelope run identity is invalid");
+  }
+  if (parsed.stageId !== undefined && parsed.stageId !== null && (typeof parsed.stageId !== "string" || !/^[A-Za-z0-9_.-]{1,128}$/.test(parsed.stageId))) {
+    throw new Error("recovery envelope stage identity is invalid");
+  }
+  if (parsed.activeMessageIds !== undefined && !validBoundedStrings(parsed.activeMessageIds, 3, recoveryMessageId)) {
+    throw new Error("recovery envelope active messages are invalid");
+  }
+  if (parsed.pendingMessageIds !== undefined && !validBoundedStrings(parsed.pendingMessageIds, 16, recoveryMessageId)) {
+    throw new Error("recovery envelope pending messages are invalid");
+  }
+  if (parsed.artifactPointers !== undefined && !validBoundedStrings(parsed.artifactPointers, 16)) {
+    throw new Error("recovery envelope artifact pointers are invalid");
+  }
+  if (parsed.failureClass !== undefined && parsed.failureClass !== "quota" && parsed.failureClass !== "provider_error" && parsed.failureClass !== "timeout") {
+    throw new Error("recovery envelope failure class is invalid");
+  }
+  if (parsed.signal !== undefined && (typeof parsed.signal !== "string" || parsed.signal.length > 64 || /[\0\r\n]/.test(parsed.signal))) {
+    throw new Error("recovery envelope signal is invalid");
+  }
+  if (parsed.sessionBinding !== undefined) {
+    const binding = parsed.sessionBinding;
+    if (
+      !binding
+      || typeof binding !== "object"
+      || (binding.kind === "default" && Object.keys(binding).some((key) => key !== "kind"))
+      || (binding.kind === "workflow" && !recoveryRunId.test(binding.runId))
+      || (binding.kind !== "default" && binding.kind !== "workflow")
+    ) throw new Error("recovery envelope session binding is invalid");
+  }
+  return parsed as WorkerRecoveryEnvelope;
+}
+
+function findWorkerRecoveryEnvelope(
+  stateDir: string,
+  agentName: string,
+  project?: string,
+): { envelope: WorkerRecoveryEnvelope; path: string } | undefined {
+  const candidates = project
+    ? [
+      { path: recoveryEnvelopePath(stateDir, agentName, project), quarantineInvalid: true },
+      { path: legacyRecoveryEnvelopePath(stateDir, agentName), quarantineInvalid: false },
+    ]
+    : [{ path: legacyRecoveryEnvelopePath(stateDir, agentName), quarantineInvalid: false }];
+  for (const candidate of candidates) {
+    try {
+      const stats = lstatSync(candidate.path);
+      if (!stats.isFile() || stats.isSymbolicLink() || stats.size > 128 * 1_024) {
+        throw new Error("recovery envelope is not a bounded regular file");
+      }
+      const envelope = parseRecoveryEnvelope(JSON.parse(readFileSync(candidate.path, "utf8")), agentName, project);
+      return { envelope, path: candidate.path };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException)?.code === "ENOENT") continue;
+      if (candidate.quarantineInvalid) {
+        try {
+          renameSync(candidate.path, `${candidate.path}.corrupt-${Date.now()}`);
+        } catch {
+          // Failure to quarantine leaves the envelope untouched for an operator.
+        }
+      }
+      // Try the legacy path after an absent or invalid collision-safe path.
+    }
+  }
+  return undefined;
+}
+
+export function readWorkerRecoveryEnvelope(stateDir: string, agentName: string, project?: string): WorkerRecoveryEnvelope | undefined {
+  return findWorkerRecoveryEnvelope(stateDir, agentName, project)?.envelope;
+}
+
+export async function consumeWorkerRecoveryEnvelope(client: HubClient, stateDir: string, agentName: string, project?: string): Promise<WorkerRecoveryEnvelope | undefined> {
+  const found = findWorkerRecoveryEnvelope(stateDir, agentName, project);
+  if (!found) return undefined;
+  const { envelope, path } = found;
+  let runId = envelope.runId ?? undefined;
+  let stageId = envelope.stageId ?? undefined;
+  let scopeMismatch = false;
+  if (envelope.sessionBinding) {
+    const boundRunId = envelope.sessionBinding.kind === "workflow" ? envelope.sessionBinding.runId : undefined;
+    if (runId !== boundRunId) {
+      // Never attach recovery from a default or sibling Pi session to this run.
+      scopeMismatch = true;
+      runId = undefined;
+      stageId = undefined;
+    }
+  }
+  if (!runId) {
+    // Recovery provenance is exact: an unbound worker event must never be
+    // attached to whichever workflow happens to be active in the project.
+    rmSync(path, { force: true });
+    return scopeMismatch ? { ...envelope, runId: null, stageId: null } : envelope;
+  }
+  const providerRecovery = envelope.reason === "provider_error";
+  const diagnostic = classifyFailure({
+    toolName: providerRecovery ? "provider" : envelope.reason === "tool_timeout" ? "tool" : "kxm_await",
+    ...(providerRecovery
+      ? { code: envelope.failureClass === "quota" ? "provider_quota" : "provider_error" }
+      : envelope.reason === "tool_timeout" ? {} : { code: "unresumable_session" }),
+    message: envelope.reason === "tool_timeout" ? "timed out" : envelope.reason,
+  });
+  try {
+    await client.recordWorkflowEntry(runId, {
+      category: "error",
+      area: "harness",
+      severity: "error",
+      summary: `Worker recovered with ${envelope.reason}`,
+      evidence: [
+        ...diagnosticEvidence(diagnostic),
+        `recovery:v1`,
+        `reason:${envelope.reason}`,
+        ...(envelope.sessionBinding?.kind === "workflow" ? [`session-scope:${envelope.sessionBinding.runId}`] : []),
+        ...(stageId ? [`stage:${stageId}`] : []),
+        ...(envelope.pendingMessageIds ?? []).slice(0, 8).map((id) => `message:${id}`),
+        ...(envelope.artifactPointers ?? []).slice(0, 16).map((pointer) => pointer.startsWith("artifact:") ? pointer : `artifact:${pointer}`),
+      ],
+    });
+    rmSync(path, { force: true });
+    return { ...envelope, runId, ...(stageId ? { stageId } : {}) };
+  } catch (error) {
+    if (error instanceof HubHttpError && error.statusCode === 403 && error.code === "workflow_forbidden") {
+      // Workflow-affine peers need the same local replay protection as the
+      // coordinator, but only the assigned coordinator may mutate the journal.
+      // Consume their local envelope instead of retrying an unauthorized write
+      // forever; the hub's durable message remains the recovery authority.
+      rmSync(path, { force: true });
+      return { ...envelope, runId, ...(stageId ? { stageId } : {}), peerLocal: true };
+    }
+    // Keep the envelope if an authorized journal write failed transiently so
+    // the next session can retry it.
+    return undefined;
+  }
+}

package/plugins/kxm/src/redact.ts

@@ -0,0 +1,26 @@
+const SECRET_PATTERNS: RegExp[] = [
+  /\bsk-[A-Za-z0-9_-]{8,}\b/g,
+  /\bghp_[A-Za-z0-9_]{20,}\b/g,
+  /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g,
+  /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/gi,
+  /\bBearer\s+[A-Za-z0-9._~+/=-]+\b/gi,
+  /\bKXM_[A-Z0-9_]*(TOKEN|SECRET|KEY)[A-Z0-9_]*=\S+/gi,
+  /\b(GITHUB_TOKEN|GH_TOKEN|KXM_AUTH_TOKEN|KXM_WORKFLOW_SIGNAL_SECRET)=\S+/gi,
+  /\b[A-Fa-f0-9]{64}\b/g,
+];
+
+export function redactSecrets(value: string): string {
+  let result = value;
+  for (const pattern of SECRET_PATTERNS) {
+    result = result.replace(pattern, "[redacted]");
+  }
+  return result;
+}
+
+export function looksLikeSecret(value: string): boolean {
+  return redactSecrets(value) !== value;
+}
+
+export function redactStringList(values: string[], maxItems = 32): string[] {
+  return values.slice(0, maxItems).map((value) => redactSecrets(value).slice(0, 500));
+}