@kontextmind/kxm 0.7.0 → 0.7.10

package/plugins/kxm/src/vnext-oneshot-evidence.ts

@@ -3,10 +3,37 @@ import { lstat, mkdir, open, rename } from "node:fs/promises";
 import { join } from "node:path";
 import type { VnextOneShotProcessResult } from "./vnext-oneshot-process.ts";
 
+export const ONESHOT_EVIDENCE_SCHEMA = "kxm.oneshot-evidence.v2" as const;
+const RETIRED_ONESHOT_EVIDENCE_SCHEMAS = new Set(["kxm.oneshot-evidence.v1"]);
+
 const TEXT_LIMIT = 4 * 1024 * 1024;
+const ARGV_LIMIT = 64 * 1024;
 const RECORD_LIMIT = 16 * 1024 * 1024;
 const digest = (value: string): string => `sha256:${createHash("sha256").update(value).digest("hex")}`;
 
+export interface OneShotEvidenceRecord {
+  schema: typeof ONESHOT_EVIDENCE_SCHEMA;
+  [key: string]: unknown;
+}
+
+/** Brake: retired and unknown persisted schema ids are never aliased or upgraded. */
+export function parseOneShotEvidenceRecord(bytes: string): OneShotEvidenceRecord {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(bytes) as unknown;
+  } catch {
+    throw new Error("oneshot_evidence_record_invalid");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("oneshot_evidence_record_invalid");
+  }
+  const schema = (parsed as { schema?: unknown }).schema;
+  if (typeof schema !== "string") throw new Error("oneshot_evidence_record_invalid");
+  if (RETIRED_ONESHOT_EVIDENCE_SCHEMAS.has(schema)) throw new Error("oneshot_evidence_schema_retired");
+  if (schema !== ONESHOT_EVIDENCE_SCHEMA) throw new Error("oneshot_evidence_schema_unknown");
+  return parsed as OneShotEvidenceRecord;
+}
+
 /** Private diagnostic evidence, never a peer reply or acceptance authority.
  * Retained until operator archival; no automatic deletion of failed attempts.
  * Each record is bounded; inability to reserve/write evidence fails closed.
@@ -32,11 +59,13 @@ export async function beginOneShotEvidence(root: string, intent: {
   const redact = (value: string): string => {
     let text = value;
     for (const secret of secrets) text = text.replaceAll(secret, "[REDACTED]");
-    return text.replace(/(\b(?:authorization|api[_-]?key|access[_-]?token|refresh[_-]?token|password|secret)\b["']?\s*[:=]\s*["']?)(?:Bearer\s+)?[^\s"',;}]+/gi, "$1[REDACTED]");
+    return text
+      .replace(/(\b(?:authorization|api[_-]?key|access[_-]?token|refresh[_-]?token|password|secret)\b["']?\s*[:=]\s*["']?)(?:Bearer\s+)?[^\s"',;}]+/gi, "$1[REDACTED]")
+      .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [REDACTED]");
   };
-  const bounded = (value: string): { text: string; truncated: boolean; sha256: string } => {
+  const bounded = (value: string, max = TEXT_LIMIT): { text: string; truncated: boolean; sha256: string } => {
     const bytes = Buffer.from(redact(value));
-    return { text: bytes.subarray(0, TEXT_LIMIT).toString("utf8"), truncated: bytes.length > TEXT_LIMIT, sha256: digest(value) };
+    return { text: bytes.subarray(0, max).toString("utf8"), truncated: bytes.length > max, sha256: digest(redact(value)) };
   };
   const write = async (name: string, value: unknown): Promise<string> => {
     const current = await lstat(dir);
@@ -46,6 +75,7 @@ export async function beginOneShotEvidence(root: string, intent: {
     }
     const bytes = JSON.stringify(value);
     if (Buffer.byteLength(bytes) > RECORD_LIMIT) throw new Error("oneshot_evidence_record_limit");
+    parseOneShotEvidenceRecord(bytes);
     const target = join(dir, name);
     const partial = `${target}.partial`;
     const file = await open(partial, "wx", 0o600);
@@ -59,11 +89,12 @@ export async function beginOneShotEvidence(root: string, intent: {
     return digest(bytes);
   };
   await write("intent.json", {
-    schema: "kxm.oneshot-evidence.v1", id, recordedAt: new Date().toISOString(),
+    schema: ONESHOT_EVIDENCE_SCHEMA, id, recordedAt: new Date().toISOString(),
     runId: intent.runId, stepId: intent.stepId, attemptId: intent.attemptId, assignmentId: intent.assignmentId,
     harness: intent.harness, provider: intent.provider, requestedModel: intent.model,
-    cwd: intent.cwd, command: intent.command,
-    argv: bounded(JSON.stringify(intent.args)), stdin: intent.input === undefined ? null : bounded(intent.input),
+    cwd: intent.cwd, command: redact(intent.command),
+    argv: bounded(JSON.stringify(intent.args), ARGV_LIMIT), stdin: intent.input === undefined ? null : bounded(intent.input),
+    env: null,
     acceptance: false,
   });
   let finished = false;
@@ -73,10 +104,11 @@ export async function beginOneShotEvidence(root: string, intent: {
       if (finished) throw new Error("oneshot_evidence_already_finished");
       finished = true;
       return write("result.json", {
-        schema: "kxm.oneshot-evidence.v1", id, recordedAt: new Date().toISOString(),
+        schema: ONESHOT_EVIDENCE_SCHEMA, id, recordedAt: new Date().toISOString(),
         stdout: bounded(result.stdout), stderr: bounded(result.stderr),
         code: result.code, signal: result.signal ?? null, started: result.started ?? null,
         observedChildExit: result.observedChildExit ?? null, terminationRequested: result.terminationRequested ?? null,
+        unverifiedDescendants: result.unverifiedDescendants ?? null,
         error: result.error ? bounded(result.error.message) : null,
         observation: bounded(JSON.stringify(observation)), acceptance: false,
       });

package/plugins/kxm/src/vnext-oneshot-process.ts

@@ -9,6 +9,11 @@ export interface VnextOneShotProcessResult {
   started?: boolean | undefined;
   /** Stop was requested; direct-child reaping cannot attest escaped descendants. */
   terminationRequested?: boolean | undefined;
+  /**
+   * Direct-child close/reap is not descendant death. Unobserved process-group
+   * members stay unverified: never success, never a forged descendant failure.
+   */
+  unverifiedDescendants?: boolean | undefined;
   error?: Error | undefined;
 }
 
@@ -18,6 +23,8 @@ export interface VnextOneShotSpawnOptions {
   input?: string | undefined;
   timeoutMs?: number | undefined;
   signal?: AbortSignal | undefined;
+  /** Only allowlisted Windows `.cmd` probes may set this; never a user string. */
+  shell?: boolean | undefined;
 }
 export type VnextOneShotSpawn = (command: string, args: readonly string[], options: VnextOneShotSpawnOptions) => Promise<VnextOneShotProcessResult>;
 
@@ -26,6 +33,26 @@ const KILL_GRACE_MS = 250;
 const DRAIN_GRACE_MS = 500;
 const REAP_GRACE_MS = 1000;
 
+/**
+ * POSIX process-group tree kill with fallback to direct child kill.
+ * Ensures orphaned subshells, test workers, and background daemons are pruned on cancellation/timeout.
+ */
+export function killProcessTree(child: ReturnType<typeof spawn>, signal: NodeJS.Signals = "SIGKILL"): void {
+  if (process.platform !== "win32" && child.pid) {
+    try {
+      process.kill(-child.pid, signal);
+      return;
+    } catch {
+      // Fall through to direct child kill if process group is unavailable
+    }
+  }
+  try {
+    child.kill(signal);
+  } catch {
+    // Direct kill error if child already exited
+  }
+}
+
 /** Bound both execution and pipe drain. Observing exit is not proof of descendant death. */
 export function defaultSpawn(command: string, args: readonly string[], options: VnextOneShotSpawnOptions): Promise<VnextOneShotProcessResult> {
   if (options.signal?.aborted) {
@@ -51,6 +78,9 @@ export function defaultSpawn(command: string, args: readonly string[], options:
     let child: ReturnType<typeof spawn>;
     const finish = (): void => {
       if (finished) return;
+      // Direct-child close must not cancel SIGTERM → SIGKILL. Refuse to settle
+      // until the group kill has been sent, then reap on the existing timers.
+      if (stopping && !killSent) return;
       finished = true;
       for (const timer of [wallTimer, killTimer, drainTimer, reapTimer]) clearTimeout(timer);
       options.signal?.removeEventListener("abort", onAbort);
@@ -60,13 +90,21 @@ export function defaultSpawn(command: string, args: readonly string[], options:
       child?.unref();
       const started = Boolean(child?.pid);
       if (started && !observedChildExit) error ??= new Error("process_exit_unobserved");
-      resolve({ stdout: Buffer.concat(stdout).toString("utf8"), stderr: Buffer.concat(stderr).toString("utf8"), code, signal, started, observedChildExit, terminationRequested: stopping, ...(error ? { error } : {}) });
+      const unverifiedDescendants = stopping || (started && !observedChildExit);
+      resolve({
+        stdout: Buffer.concat(stdout).toString("utf8"),
+        stderr: Buffer.concat(stderr).toString("utf8"),
+        code,
+        signal,
+        started,
+        observedChildExit,
+        terminationRequested: stopping,
+        ...(unverifiedDescendants ? { unverifiedDescendants: true } : {}),
+        ...(error ? { error } : {}),
+      });
     };
     const kill = (requested: NodeJS.Signals): void => {
-      try {
-        if (process.platform !== "win32" && child.pid) process.kill(-child.pid, requested);
-        else child.kill(requested);
-      } catch { /* Reaping, not kill() success, establishes direct-child exit. */ }
+      killProcessTree(child, requested);
     };
     const stop = (reason: string): void => {
       if (finished) return;
@@ -91,7 +129,7 @@ export function defaultSpawn(command: string, args: readonly string[], options:
         cwd: options.cwd,
         env: options.env ?? process.env,
         stdio: ["pipe", "pipe", "pipe"],
-        shell: false,
+        shell: options.shell === true,
         windowsHide: true,
         detached: process.platform !== "win32",
       });
@@ -136,8 +174,8 @@ export function defaultSpawn(command: string, args: readonly string[], options:
       code = exitCode;
       signal = exitSignal;
       // The leader can exit and close its pipes while a descendant ignores TERM.
-      // Never cancel the pending group escalation just because close arrived.
-      if (!stopping || killSent) finish();
+      // finish() no-ops until SIGKILL when escalation is in flight.
+      finish();
     });
     options.signal?.addEventListener("abort", onAbort, { once: true });
     if (options.signal?.aborted) onAbort();

package/plugins/kxm/src/vnext-oneshot-producer.ts

@@ -195,6 +195,24 @@ export function createVnextOneShotProducer(options: VnextOneShotProducerOptions
         args = ["--model", resolved.model,
           ...(resolved.thinking ? ["--reasoning-effort", resolved.thinking] : []),
           ...permissionArgs, "--output-format", "json"];
+      } else if (harness === "agy") {
+        args = [
+          "-m",
+          resolved.model,
+          ...permissionArgs,
+          "--output-format",
+          "json",
+          "-p",
+        ];
+      } else if (harness === "kimi") {
+        args = [
+          "-m",
+          resolved.model,
+          ...permissionArgs,
+          "--output-format",
+          "stream-json",
+          "-p",
+        ];
       } else {
         throw new Error(`oneshot_harness_unsupported: ${harness} permission_profile_unaudited`);
       }
@@ -234,9 +252,11 @@ export function createVnextOneShotProducer(options: VnextOneShotProducerOptions
       const aborted = request.signal.aborted || procResult.error?.message === "process_aborted";
       // Process groups are cleanup, not containment. A detached descendant or
       // provider leader may outlive the client; interrupted effects need recovery.
-      const effectUncertain = procResult.terminationRequested === true || Boolean(procResult.signal)
+      const unverifiedDescendants = procResult.unverifiedDescendants === true
+        || procResult.terminationRequested === true
         || procResult.error?.message === "process_exit_unobserved"
         || (procResult.observedChildExit === false && procResult.started !== false);
+      const effectUncertain = unverifiedDescendants || Boolean(procResult.signal);
       const transportFailed = procResult.code !== 0 || Boolean(procResult.error) || effectUncertain;
       const outcome = aborted ? "cancelled" : transportFailed || parsed.isError ? "failed"
         : determineOutcome(parsed.text, request.allowedOutcomes);
@@ -249,6 +269,7 @@ export function createVnextOneShotProducer(options: VnextOneShotProducerOptions
       if (procResult.observedChildExit !== undefined) providerMetadata.observedChildExit = procResult.observedChildExit;
       if (procResult.started !== undefined) providerMetadata.processStarted = procResult.started;
       if (procResult.terminationRequested !== undefined) providerMetadata.terminationRequested = procResult.terminationRequested;
+      if (unverifiedDescendants) providerMetadata.descendantEffects = "unverified";
       if (procResult.error) {
         const reason = procResult.error.message;
         providerMetadata.processError = /^process_(aborted|timeout|output_limit|stdin_error|stdio_error|stdio_unclosed|exit_unobserved)$/.test(reason) ? reason : "process_error";

package/plugins/kxm/src/vnext-pi-producer.ts

@@ -8,8 +8,10 @@ import {
   type VnextProducerResult,
 } from "./vnext-engine.ts";
 import {
-  probeHarnessAssignment,
+  probeHarnessAssignmentAsync,
+  type HarnessAssignmentProbeOptions,
   type HarnessInventory,
+  type HarnessStatus,
 } from "./vnext-harness.ts";
 import {
   calculateModelCost,
@@ -386,7 +388,7 @@ export interface VnextPiProducerOptions {
   priceCatalog?: PriceCatalog | undefined;
   env?: NodeJS.ProcessEnv | undefined;
   spawnProcess?: ((command: string, args: readonly string[], options: Record<string, unknown>) => PiRpcProcess) | undefined;
-  probeHarness?: typeof probeHarnessAssignment | undefined;
+  probeHarness?: ((options: Omit<HarnessAssignmentProbeOptions, "runCommand"> & { signal?: AbortSignal | undefined }) => HarnessStatus | Promise<HarnessStatus>) | undefined;
   resolveModel?: ((agentId: string, runId: string) => { provider?: string | undefined; model?: string | undefined; thinking?: string | undefined } | undefined) | undefined;
   defaultModel?: string | undefined;
   defaultProvider?: string | undefined;
@@ -438,7 +440,7 @@ export function createVnextPiProducer(options: VnextPiProducerOptions = {}): Vne
     return { provider: parsed.provider, model: parsed.model };
   }
 
-  function checkPiAuth(provider: string, model: string): void {
+  async function checkPiAuth(provider: string, model: string, signal: AbortSignal): Promise<void> {
     if (options.inventory) {
       const piEntry = options.inventory.harnesses.find((h) => h.id === "pi");
       if (!piEntry || !piEntry.detected || piEntry.authenticated === false) {
@@ -446,12 +448,14 @@ export function createVnextPiProducer(options: VnextPiProducerOptions = {}): Vne
       }
     }
 
-    const probeFn = options.probeHarness ?? probeHarnessAssignment;
-    const probe = probeFn({
+    const probeFn = options.probeHarness ?? probeHarnessAssignmentAsync;
+    const probe = await probeFn({
       harness: "pi",
       provider,
       model,
       env: options.env,
+      signal,
+      timeoutMs: 10_000,
     });
 
     if (!probe.detected) {
@@ -538,8 +542,8 @@ export function createVnextPiProducer(options: VnextPiProducerOptions = {}): Vne
       const startTime = Date.now();
       const resolved = resolveModelForRequest(request);
 
-      // Preflight auth check - fails closed
-      checkPiAuth(resolved.provider, resolved.model);
+      // Preflight auth check - fails closed via the async bounded probe
+      await checkPiAuth(resolved.provider, resolved.model, request.signal);
 
       // Get or create session
       const session = await getOrCreateSession(request, resolved.model);

package/plugins/kxm/src/vnext-runtime-store.ts

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { DatabaseSync } from "node:sqlite";
+import { DatabaseSync } from "./sqlite.ts";
 import { VnextConfigError, validateRunEvent, vnextCanonicalJson, type JsonValue, type VnextConfigIssue, type VnextConfigOptions } from "./vnext-config.ts";
 import { vnextUserStateRoot } from "./vnext-bindings.ts";
 

package/plugins/kxm/src/vnext-runtime-supervisor.ts

@@ -476,7 +476,7 @@ async function startVnextRuntimeSupervisorInner(
                   });
                 })();
 
-            let drivePromise: Promise<unknown>;
+            let drivePromise: Promise<unknown> | undefined;
             let earlyError: unknown;
             try {
               const scheduler = VnextRunScheduler.for(context, bundle);
@@ -484,7 +484,6 @@ async function startVnextRuntimeSupervisorInner(
               drivePromise.catch((err) => { earlyError = err; });
             } catch (err) {
               earlyError = err;
-              drivePromise = Promise.reject(err);
             }
 
             // Yield microtask to catch synchronous duplicate queue check (e.g. run_busy)
@@ -503,11 +502,14 @@ async function startVnextRuntimeSupervisorInner(
               throw earlyError;
             }
 
-            void drivePromise.finally(async () => {
+            void drivePromise!.finally(async () => {
               cleanupActive();
               if ("close" in producer && typeof producer.close === "function") {
                 try { await producer.close(); } catch { /* ignore */ }
               }
+            }).catch(() => {
+              // Derived finally() re-rejects when the admitted drive or cleanup
+              // throws; void does not consume that. Keep the request 202.
             });
 
             sendJson(response, 202, {

package/plugins/kxm/src/workflow-tui.ts

@@ -5,7 +5,7 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { DatabaseSync } from "node:sqlite";
+import { DatabaseSync } from "./sqlite.ts";
 import { repoConfigDirectory } from "./config.ts";
 import { readRoutingRecords, telemetryPath } from "./telemetry.ts";
 

package/plugins/kxm/src/workflow.ts

@@ -3,11 +3,17 @@ import {
   MAX_MESSAGE_TTL_MS,
   MIN_MESSAGE_TTL_MS,
   ProtocolError,
+  TERMINAL_RECEIPT_SCHEMA,
   newId,
   requireString,
+  validateTerminalReceipt,
   type ImprovementArea,
   type JournalCategory,
   type MessageRecord,
+  type TerminalReceipt,
+  type TerminalReceiptEvidence,
+  type TerminalReceiptMetrics,
+  type TerminalReceiptStatus,
   type WorkflowCheckpointStatus,
   type WorkflowEvidenceInput,
   type WorkflowEvidenceReference,
@@ -18,11 +24,16 @@ import {
 export type {
   ImprovementArea,
   JournalCategory,
+  TerminalReceipt,
+  TerminalReceiptEvidence,
+  TerminalReceiptMetrics,
+  TerminalReceiptStatus,
   WorkflowCheckpointStatus,
   WorkflowEvidenceInput,
   WorkflowEvidenceReference,
   WorkflowEvidenceReferenceInput,
 } from "./protocol.ts";
+export { TERMINAL_RECEIPT_SCHEMA, validateTerminalReceipt } from "./protocol.ts";
 
 export type WorkflowRunStatus = "running" | "waiting" | "completed" | "failed";
 export type WorkflowStageStatus = "pending" | "in_progress" | "waiting" | WorkflowCheckpointStatus;
@@ -153,6 +164,8 @@ export interface WorkflowStageDefinition {
   instructions: string;
   requiredEvidence: string[];
   maxAttempts: number;
+  /** Bounded in-place retry limit before audit escalation (default: 2). */
+  autoResumeLimit?: number;
   area?: ImprovementArea;
   evidencePolicies?: WorkflowEvidencePolicies;
   /** Typed outcome map (v0.5). Keys are outcome identities ("passed",
@@ -250,6 +263,13 @@ export interface WorkflowStageState extends WorkflowStageDefinition {
   startedAt?: string;
   completedAt?: string;
   updatedAt?: string;
+  receipt?: TerminalReceipt;
+  auditEscalation?: {
+    reason: string;
+    timestamp: string;
+    ruling?: string;
+    receipt?: TerminalReceipt;
+  };
 }
 
 export interface CapturedOracle {
@@ -1003,12 +1023,18 @@ export function parseWorkflowDefinitions(
         && (!Number.isInteger(stageMaxTransitions) || (stageMaxTransitions as number) < 1 || (stageMaxTransitions as number) > 100)) {
         throw new Error(`stage ${stageId} maxTransitions must be an integer between 1 and 100`);
       }
+      const autoResumeLimit = stage.autoResumeLimit;
+      if (autoResumeLimit !== undefined
+        && (!Number.isInteger(autoResumeLimit) || (autoResumeLimit as number) < 1 || (autoResumeLimit as number) > 20)) {
+        throw new Error(`stage ${stageId} autoResumeLimit must be an integer between 1 and 20`);
+      }
       return {
         id: stageId,
         label: requireString(stage.label ?? stageId, "stage.label", { max: 128 }),
         instructions: requireString(stage.instructions, "stage.instructions", { max: 4_000 }),
         requiredEvidence,
         maxAttempts: maxAttempts as number,
+        ...(autoResumeLimit !== undefined ? { autoResumeLimit: autoResumeLimit as number } : {}),
         ...(area ? { area } : {}),
         ...(evidencePolicies ? { evidencePolicies } : {}),
         ...(on ? { on } : {}),
@@ -1377,6 +1403,31 @@ export function checkpointRun(
       delete run.currentStage;
       return { retry: false, completed: false, run };
     }
+    if (stage.autoResumeLimit !== undefined && stage.attempts >= stage.autoResumeLimit) {
+      stage.status = "in_progress";
+      const reason = summary || `autoResumeLimit of ${stage.autoResumeLimit} reached on stage ${stage.id}`;
+      const receipt = validateTerminalReceipt({
+        schema: TERMINAL_RECEIPT_SCHEMA,
+        status: "audit_escalation",
+        seat: stage.id,
+        runId: run.id,
+        stageId: stage.id,
+        timestamp,
+        host: "pi",
+        model: "default",
+        escalationReason: reason,
+      });
+      const expiresAt = new Date(Date.parse(timestamp) + 24 * 60 * 60 * 1000).toISOString();
+      waitForWorkflowSignal(run, stage.id, "audit_escalation", reason, timestamp, expiresAt);
+      stage.receipt = receipt;
+      stage.auditEscalation = {
+        reason,
+        timestamp,
+        receipt,
+      };
+      return { retry: false, completed: false, run };
+    }
+    stage.status = status;
     // Declared failure outcomes create typed transitions (bounded); the
     // outcome identity defaults to the checkpoint status.
     const outcomeKey = outcome ?? status;
@@ -1546,3 +1597,96 @@ export function approveWorkflowDegradation(
   run.updatedAt = timestamp;
   return { run, approval, created: true };
 }
+
+export function escalateWorkflowStage(
+  run: WorkflowRun,
+  stageId: string,
+  reason: string,
+  timestamp: string,
+  options: {
+    seat?: string;
+    host?: string;
+    model?: string;
+    evidence?: TerminalReceiptEvidence;
+    metrics?: TerminalReceiptMetrics;
+  } = {},
+): { run: WorkflowRun; receipt: TerminalReceipt } {
+  if (run.status !== "running") throw new ProtocolError(409, `workflow is ${run.status}`, "workflow_terminal");
+  const stage = run.stages.find((s) => s.id === stageId);
+  if (!stage) throw new ProtocolError(404, `workflow stage not found: ${stageId}`, "workflow_stage_not_found");
+  if (stage.id !== run.currentStage || stage.status !== "in_progress") {
+    throw new ProtocolError(409, `stage ${stageId} is not currently active`, "workflow_stage_out_of_order");
+  }
+
+  const receipt: TerminalReceipt = validateTerminalReceipt({
+    schema: TERMINAL_RECEIPT_SCHEMA,
+    status: "audit_escalation",
+    seat: options.seat ?? stage.id,
+    runId: run.id,
+    stageId,
+    timestamp,
+    host: options.host ?? "pi",
+    model: options.model ?? "default",
+    escalationReason: reason,
+    ...(options.evidence ? { evidence: options.evidence } : {}),
+    ...(options.metrics ? { metrics: options.metrics } : {}),
+  });
+
+  const expiresAt = new Date(Date.parse(timestamp) + 24 * 60 * 60 * 1000).toISOString();
+  waitForWorkflowSignal(run, stageId, "audit_escalation", reason, timestamp, expiresAt);
+
+  stage.receipt = receipt;
+  stage.auditEscalation = {
+    reason,
+    timestamp,
+    receipt,
+  };
+
+  return { run, receipt };
+}
+
+export function resumeWorkflowFromRuling(
+  run: WorkflowRun,
+  ruling: string,
+  timestamp: string,
+  options: {
+    status?: WorkflowCheckpointStatus;
+    evidence?: WorkflowEvidenceInput;
+  } = {},
+): { retry: boolean; completed: boolean; run: WorkflowRun; stageId: string } {
+  if (run.status !== "waiting" || !run.waiting) {
+    throw new ProtocolError(409, `workflow is ${run.status}`, "workflow_not_waiting");
+  }
+  if (run.waiting.signalKey !== "audit_escalation") {
+    throw new ProtocolError(
+      409,
+      `workflow is waiting for signal '${run.waiting.signalKey}', not 'audit_escalation'`,
+      "workflow_signal_mismatch",
+    );
+  }
+
+  const stageId = run.waiting.stageId;
+  const stage = run.stages.find((s) => s.id === stageId);
+  if (!stage) throw new ProtocolError(404, `workflow stage not found: ${stageId}`, "workflow_stage_not_found");
+
+  const status = options.status ?? "passed";
+  const evidence = options.evidence ?? {};
+
+  if (stage.auditEscalation) {
+    stage.auditEscalation.ruling = ruling;
+    if (stage.auditEscalation.receipt) {
+      stage.auditEscalation.receipt.ruling = ruling;
+    }
+  }
+  stage.summary = `Resumed by operator ruling: ${ruling}`;
+
+  return resumeWorkflowFromSignal(
+    run,
+    "audit_escalation",
+    status,
+    `Resumed: ${ruling}`,
+    evidence,
+    timestamp,
+  );
+}
+

package/schemas/vnext/modes.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kxm.dev/vnext/modes.schema.json",
+  "title": "KXM Modes Configuration",
+  "description": "Declarative major modes and domain modules for selective tool loading and context scoping",
+  "type": "object",
+  "required": ["schema", "majorModes"],
+  "properties": {
+    "schema": { "const": "kxm.modes.v1" },
+    "majorModes": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["baseTools"],
+        "properties": {
+          "description": { "type": "string" },
+          "baseTools": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "contextFiles": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "thinkingLevel": {
+            "type": "string",
+            "enum": ["low", "medium", "high", "xhigh"]
+          },
+          "model": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "domains": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["tools"],
+        "properties": {
+          "description": { "type": "string" },
+          "tools": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "contextFiles": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "promptSnippet": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}