@kontextmind/kxm 0.7.103 → 0.7.105

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

@@ -1,34 +1,16 @@
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { DatabaseSync, openReadOnlyDatabase } from "./sqlite.ts";
 import { KxmConfigError, validateCoordinator, validateDriveReceipt, validateIntakeMessage, validateRunEvent, kxmCanonicalJson, type JsonValue, type KxmConfigIssue, type KxmConfigOptions } from "./project-config.ts";
-import { kxmUserStateRoot } from "./bindings.ts";
+import { kxmProjectRunEventsPath, projectRuntimeKey } from "./runtime-paths.ts";
 import { deriveKxmSyncEvent, kxmSyncEventBytes, KxmSyncRedactor } from "./sync-transform.ts";
 
 /* ------------------------------------------------------------------ *
  * Runtime registry (per-user, platform state root)
  * ------------------------------------------------------------------ */
 
-export interface KxmRuntimePaths {
-  stateRoot: string;
-  runtimeDir: string;
-  registryDb: string;
-  projectsDir: string;
-}
-
-export function kxmRuntimePaths(options: { stateRoot?: string; env?: NodeJS.ProcessEnv; homeDir?: string } = {}): KxmRuntimePaths {
-  const stateRoot = options.stateRoot
-    ? resolve(options.stateRoot)
-    : kxmUserStateRoot({ ...(options.env ? { env: options.env } : {}), ...(options.homeDir ? { homeDir: options.homeDir } : {}) });
-  const runtimeDir = join(stateRoot, "runtime");
-  return {
-    stateRoot,
-    runtimeDir,
-    registryDb: join(runtimeDir, "registry.db"),
-    projectsDir: join(runtimeDir, "projects"),
-  };
-}
+export { kxmRuntimePaths, projectRuntimeKey, kxmProjectRunEventsPath, type KxmRuntimePaths } from "./runtime-paths.ts";
 
 function runtimeIssue(phase: KxmConfigIssue["phase"], code: string, file: string, message: string): KxmConfigIssue {
   return { phase, code, file, message };
@@ -38,24 +20,6 @@ export function runtimeError(code: string, file: string, message: string): KxmCo
   return new KxmConfigError([runtimeIssue("semantic", code, file, message)]);
 }
 
-export function projectRuntimeKey(projectRoot: string): string {
-  // Canonicalize through the filesystem like the repository binding store so
-  // reaching a project through a link cannot mint a second key for it.
-  let canonical: string;
-  try {
-    canonical = realpathSync.native(resolve(projectRoot));
-  } catch {
-    canonical = resolve(projectRoot);
-  }
-  const folded = process.platform === "win32" ? canonical.toLocaleLowerCase("en-US") : canonical;
-  return createHash("sha256").update(folded, "utf8").digest("hex").slice(0, 24);
-}
-
-/** The project's Runtime event store, derived exactly as the Runtime derives it. */
-export function kxmProjectRunEventsPath(projectRoot: string, env: NodeJS.ProcessEnv): string {
-  return join(kxmRuntimePaths({ env }).projectsDir, projectRuntimeKey(projectRoot), "run-events.db");
-}
-
 /**
  * Whether this project's Runtime event store holds `runId`. Hub workflow runs and Runtime
  * runs share the `run_<32 hex>` shape, so a command addressed by run id asks the owning
@@ -141,6 +105,24 @@ CREATE TABLE projects (
 ) STRICT;
 `;
 
+/** The supervisor singleton row, from any connection to a registry, including a read-only one. */
+export function readKxmSupervisorRecord(database: DatabaseSync): KxmSupervisorRecord | undefined {
+  const row = database.prepare("SELECT runtime_id, pid, port, token_hash, started_at, heartbeat_at, state FROM supervisor WHERE singleton_id = 1").get() as
+    | { runtime_id: string; pid: number; port: number; token_hash: string; started_at: string; heartbeat_at: string; state: KxmSupervisorRecord["state"] }
+    | undefined;
+  return row
+    ? {
+      runtimeId: row.runtime_id,
+      pid: row.pid,
+      port: row.port,
+      tokenHash: row.token_hash,
+      startedAt: row.started_at,
+      heartbeatAt: row.heartbeat_at,
+      state: row.state,
+    }
+    : undefined;
+}
+
 export class KxmRuntimeRegistry {
   readonly path: string;
   private readonly database: DatabaseSync;
@@ -228,20 +210,7 @@ export class KxmRuntimeRegistry {
   }
 
   private readSupervisorRow(): KxmSupervisorRecord | undefined {
-    const row = this.database.prepare("SELECT runtime_id, pid, port, token_hash, started_at, heartbeat_at, state FROM supervisor WHERE singleton_id = 1").get() as
-      | { runtime_id: string; pid: number; port: number; token_hash: string; started_at: string; heartbeat_at: string; state: KxmSupervisorRecord["state"] }
-      | undefined;
-    return row
-      ? {
-        runtimeId: row.runtime_id,
-        pid: row.pid,
-        port: row.port,
-        tokenHash: row.token_hash,
-        startedAt: row.started_at,
-        heartbeatAt: row.heartbeat_at,
-        state: row.state,
-      }
-      : undefined;
+    return readKxmSupervisorRecord(this.database);
   }
 
   supervisor(): KxmSupervisorRecord | undefined {

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

@@ -8,12 +8,15 @@ import { loadKxmProject, KxmConfigError, type KxmConfigOptions } from "./project
 import {
   KxmRuntimeRegistry,
   projectRuntimeKey,
+  readKxmSupervisorRecord,
   runtimeError,
   verifyKxmDriveReceipt,
   kxmRuntimePaths,
   type KxmRunEventStore,
   type KxmRuntimePaths,
+  type KxmSupervisorRecord,
 } from "./runtime-store.ts";
+import { openReadOnlyDatabase } from "./sqlite.ts";
 import {
   acceptKxmRun,
   cancelKxmRun,
@@ -122,26 +125,44 @@ function readRecentSupervisorError(paths: KxmRuntimePaths): string | undefined {
   }
 }
 
-export function kxmSupervisorStatus(paths: KxmRuntimePaths): KxmSupervisorStatus {
+function supervisorStatusOf(record: KxmSupervisorRecord | undefined): KxmSupervisorStatus {
+  if (!record) return { running: false };
+  // Pid-only liveness is not enough: after a crash the pid may be reused by
+  // an unrelated process. A stale heartbeat is authoritative.
+  const heartbeatAgeMs = Date.now() - Date.parse(record.heartbeatAt);
+  const fresh = Number.isFinite(heartbeatAgeMs) && heartbeatAgeMs < HEARTBEAT_STALE_MS;
+  const alive = record.state === "running" && fresh && processAlive(record.pid);
+  return {
+    running: alive,
+    runtimeId: record.runtimeId,
+    pid: record.pid,
+    port: record.port,
+    state: alive ? record.state : "dead",
+    heartbeatAt: record.heartbeatAt,
+    startedAt: record.startedAt,
+  };
+}
+
+/**
+ * Is the supervisor up? `readOnly` gives the same answer without opening the
+ * registry for writing: the ordinary open takes the write lock and, as the last
+ * connection, checkpoints the WAL on close. `kxm restore` asks this way, dry run
+ * or not, because a project-scoped restore never otherwise touches the registry.
+ */
+export function kxmSupervisorStatus(paths: KxmRuntimePaths, options: { readOnly?: boolean } = {}): KxmSupervisorStatus {
   if (!existsSync(paths.registryDb)) return { running: false };
+  if (options.readOnly) {
+    const database = openReadOnlyDatabase(paths.registryDb);
+    try {
+      database.exec("PRAGMA busy_timeout = 5000");
+      return supervisorStatusOf(readKxmSupervisorRecord(database));
+    } finally {
+      database.close();
+    }
+  }
   const registry = new KxmRuntimeRegistry(paths.registryDb);
   try {
-    const record = registry.supervisor();
-    if (!record) return { running: false };
-    // Pid-only liveness is not enough: after a crash the pid may be reused by
-    // an unrelated process. A stale heartbeat is authoritative.
-    const heartbeatAgeMs = Date.now() - Date.parse(record.heartbeatAt);
-    const fresh = Number.isFinite(heartbeatAgeMs) && heartbeatAgeMs < HEARTBEAT_STALE_MS;
-    const alive = record.state === "running" && fresh && processAlive(record.pid);
-    return {
-      running: alive,
-      runtimeId: record.runtimeId,
-      pid: record.pid,
-      port: record.port,
-      state: alive ? record.state : "dead",
-      heartbeatAt: record.heartbeatAt,
-      startedAt: record.startedAt,
-    };
+    return supervisorStatusOf(registry.supervisor());
   } finally {
     registry.close();
   }

package/plugins/kxm/src/suggest.ts

@@ -1,156 +1,209 @@
+import { BUILTIN_HARNESS_IDS, oneShotWriterArgs, type HarnessStatus } from "./harness.ts";
+import { WORKFLOW_TEMPLATES } from "./workflow-manager.ts";
+
 export interface RoleSpec {
+  agent: string;
   harness: string;
-  model: string;
   role: string;
 }
 
+export type SuggestionExecution = {
+  supported: true;
+  prerequisites: string[];
+  shell: "powershell" | "posix";
+  createCommand: string;
+  driveCommand: string;
+  statusCommand: string;
+  receiptCommand: string;
+} | {
+  supported: false;
+  error: "harness_unavailable" | "live_write_unsupported" | "workflow_already_exists";
+  reason: string;
+  nextSteps: string[];
+};
+
 export interface SuggestionResult {
   workflowId: string;
+  template: string;
   area: string;
   confidence: number;
   reasons: string[];
   suggestedSkills: string[];
-  roles: {
-    planner: RoleSpec;
-    writer: RoleSpec;
-    critics: RoleSpec[];
-    verifier: { kind: "witness"; command: string };
-  };
+  roles: RoleSpec[];
+  /** Installs a definition; it does not create or execute a run. */
   suggestedCommand: string;
+  execution: SuggestionExecution;
 }
 
 interface WorkflowPattern {
   id: string;
+  template: string;
   area: string;
   keywords: string[];
   skills: string[];
-  defaultCommand: (prompt: string) => string;
 }
 
 const WORKFLOW_PATTERNS: WorkflowPattern[] = [
   {
-    id: "software-engineering/bug-fix",
+    id: "bug-fix",
+    template: "implement-and-verify",
     area: "software-engineering",
     keywords: ["fix", "bug", "flaky", "failure", "timeout", "error", "repro", "crash", "broken", "hang"],
     skills: ["kxm-workflow", "kxm-runs", "kxm-context-memory"],
-    defaultCommand: (p) => `kxm run software-engineering/bug-fix "${p}"`,
   },
   {
-    id: "software-engineering/feature-implementation",
+    id: "feature-implementation",
+    template: "implement-and-verify",
     area: "software-engineering",
     keywords: ["feature", "implement", "add", "build", "create", "develop", "support", "endpoint", "ui", "tui"],
     skills: ["kxm-workflow", "kxm-peer", "kxm-context-memory"],
-    defaultCommand: (p) => `kxm run software-engineering/feature-implementation "${p}"`,
   },
   {
-    id: "software-engineering/refactoring",
+    id: "refactoring",
+    template: "dual-critic-review",
     area: "software-engineering",
     keywords: ["refactor", "cleanup", "reorganize", "modularize", "deduplicate", "split", "simplify", "deprecate"],
     skills: ["kxm-workflow", "kxm-runs"],
-    defaultCommand: (p) => `kxm run software-engineering/refactoring "${p}"`,
   },
   {
-    id: "security-reliability/vulnerability-remediation",
+    id: "vulnerability-remediation",
+    template: "dual-critic-review",
     area: "security-reliability",
     keywords: ["cve", "vulnerability", "security", "exploit", "sanitize", "leak", "secret", "injection", "redact", "auth"],
     skills: ["kxm-workflow", "kxm-definitions"],
-    defaultCommand: (p) => `kxm run security-reliability/vulnerability-remediation "${p}"`,
   },
   {
-    id: "security-reliability/reliability-hardening",
+    id: "reliability-hardening",
+    template: "dual-critic-review",
     area: "security-reliability",
     keywords: ["idempotency", "retry", "circuit-breaker", "cas", "lock", "concurrency", "deadlock", "race", "crash-recovery"],
     skills: ["kxm-workflow", "kxm-peer"],
-    defaultCommand: (p) => `kxm run security-reliability/reliability-hardening "${p}"`,
   },
   {
-    id: "data-analytics/pipeline-migration",
+    id: "pipeline-migration",
+    template: "implement-and-verify",
     area: "data-analytics",
     keywords: ["database", "sqlite", "migration", "pipeline", "schema", "transform", "table", "wal", "foreign", "cascading"],
     skills: ["kxm-runs", "kxm-context-memory"],
-    defaultCommand: (p) => `kxm run data-analytics/pipeline-migration "${p}"`,
   },
   {
-    id: "research-strategy/architecture-spike",
+    id: "architecture-spike",
+    template: "spec-and-plan",
     area: "research-strategy",
     keywords: ["spike", "investigate", "prototype", "research", "feasibility", "benchmark", "explore", "evaluate"],
     skills: ["kxm-session", "kxm-context-memory", "kxm-routing-improve"],
-    defaultCommand: (p) => `kxm run research-strategy/architecture-spike "${p}"`,
   },
 ];
 
+type TemplateStep = { id: string; kind: string; agent?: string; repositories?: Record<string, string> };
+type SuggestionHarness = Pick<HarnessStatus, "id" | "detected" | "authenticated" | "dispatch">;
+
 export function suggestWorkflowAndRoles(
   prompt: string,
-  options: {
-    availableHarnesses?: Array<{ harness: string; auth?: string | undefined }> | undefined;
-  } = {},
+  options: { availableHarnesses?: readonly SuggestionHarness[] | undefined } = {},
 ): SuggestionResult {
   const normalized = prompt.toLowerCase();
   const words = normalized.split(/\W+/).filter(Boolean);
-
-  let bestPattern: WorkflowPattern = WORKFLOW_PATTERNS[0]!;
-  let bestScore = -1;
-  const matchedReasons: string[] = [];
+  const claudeOnly = /\bclaude(?:\s+code)?(?:[\s-]+only|\s+exclusively)\b|\b(?:only|exclusively)(?:\s+(?:use|using|with|via))?\s+claude(?:\s+code)?\b/i.test(prompt);
+  let bestPattern: WorkflowPattern = WORKFLOW_PATTERNS[1]!;
+  let bestScore = 0;
+  const reasons: string[] = [];
 
   for (const pattern of WORKFLOW_PATTERNS) {
-    let score = 0;
-    const matchedWords: string[] = [];
-    for (const keyword of pattern.keywords) {
-      if (words.includes(keyword) || normalized.includes(keyword)) {
-        score += 1;
-        matchedWords.push(keyword);
-      }
-    }
-    if (score > bestScore) {
-      bestScore = score;
+    const matchedWords = pattern.keywords.filter((keyword) => words.includes(keyword) || normalized.includes(keyword));
+    if (matchedWords.length > bestScore) {
+      bestScore = matchedWords.length;
       bestPattern = pattern;
-      matchedReasons.length = 0;
-      matchedReasons.push(`Matched keywords: ${matchedWords.join(", ")}`);
+      reasons.length = 0;
+      reasons.push(`Matched keywords: ${matchedWords.join(", ")}`);
     }
   }
+  if (bestScore === 0) reasons.push("Default fallback: general feature implementation workflow");
+  if (claudeOnly) reasons.push("Explicit Claude-only constraint; other harnesses are excluded");
 
-  if (bestScore <= 0) {
-    bestPattern = WORKFLOW_PATTERNS[1]!;
-    matchedReasons.push("Default fallback: general feature implementation workflow");
-  }
-
-  const activeHarnesses = new Set(
-    (options.availableHarnesses ?? [])
-      .filter((h) => h.auth === "active" || h.auth === "ready" || h.auth === "configured")
-      .map((h) => h.harness.toLowerCase()),
-  );
-
-  const hasClaude = activeHarnesses.size === 0 || activeHarnesses.has("claude");
-  const hasGrok = activeHarnesses.size === 0 || activeHarnesses.has("grok");
-  const hasCodex = activeHarnesses.size === 0 || activeHarnesses.has("codex");
-
-  const planner: RoleSpec = hasClaude
-    ? { harness: "claude", model: "fable", role: "planner" }
-    : { harness: "codex", model: "gpt-5.6-sol", role: "planner" };
-
-  const writer: RoleSpec = hasGrok
-    ? { harness: "grok", model: "grok-4.6", role: "writer" }
-    : (activeHarnesses.has("agy")
-      ? { harness: "agy", model: "gemini-2.5-pro", role: "writer" }
-      : { harness: "pi", model: "qwen/qwen3-coder-plus", role: "writer" });
-
-  const critics: RoleSpec[] = [
-    { harness: "claude", model: "fable", role: "reviewer-arch" },
-    { harness: "codex", model: "gpt-5.6-sol", role: "reviewer-cli" },
-  ];
-
-  return {
+  const template = WORKFLOW_TEMPLATES[bestPattern.template]!;
+  const steps = template.steps as TemplateStep[];
+  const base = {
     workflowId: bestPattern.id,
+    template: bestPattern.template,
     area: bestPattern.area,
     confidence: bestScore > 0 ? Math.min(1, 0.5 + bestScore * 0.15) : 0.5,
-    reasons: matchedReasons,
+    reasons,
     suggestedSkills: bestPattern.skills,
-    roles: {
-      planner,
-      writer,
-      critics,
-      verifier: { kind: "witness", command: "npm run verify" },
+    suggestedCommand: `kxm workflow add ${bestPattern.id} --template ${bestPattern.template}`,
+  };
+  const writeStep = steps.find((step) => step.kind === "agent" && Object.values(step.repositories ?? {}).includes("write"));
+
+  const available = (options.availableHarnesses ?? []).filter((entry) =>
+    BUILTIN_HARNESS_IDS.includes(entry.id) && entry.detected && entry.authenticated === true
+    && entry.dispatch?.supported === true && entry.dispatch.status === "yes"
+    && (!claudeOnly || entry.id === "claude"));
+  const selected = available.find((entry) => entry.id === "claude") ?? available[0];
+  if (!selected) {
+    const relevant = (options.availableHarnesses ?? []).filter((entry) => !claudeOnly || entry.id === "claude");
+    const detail = relevant.map((entry) => `${entry.id}: ${entry.dispatch?.reason ?? (!entry.detected ? "not_detected" : entry.authenticated !== true ? "authentication_unverified" : "dispatch_unavailable")}`).join("; ");
+    return {
+      ...base,
+      roles: [],
+      execution: {
+        supported: false,
+        error: "harness_unavailable",
+        reason: `${claudeOnly ? "Claude-only execution requires Claude Code" : "Execution requires a supported harness"} detected, authenticated, and ready for dispatch. ${detail || "No verified harness inventory is available."}`,
+        nextSteps: claudeOnly
+          ? ["Install Claude Code if missing, authenticate with claude auth login, then confirm claude auth status and kxm harness list. Other harnesses will not be substituted."]
+          : ["Install and authenticate a supported harness, then run kxm harness list to check detection, authentication, and dispatch readiness. Pi requires a configured model/provider auth context."],
+      },
+    };
+  }
+
+  if (writeStep && !oneShotWriterArgs(selected.id)) {
+    return {
+      ...base,
+      roles: [],
+      execution: {
+        supported: false,
+        error: "live_write_unsupported",
+        reason: `${bestPattern.template} requires repository writes at step ${writeStep.id}, but the selected ${selected.id} harness has no audited live writer profile. No other harness will be substituted.`,
+        nextSteps: [
+          `Run the implementation directly in ${claudeOnly ? "Claude Code" : selected.id} in the target worktree, and run the repository's actual verification command.`,
+          `For read-only KXM planning, try kxm suggest "Investigate an architecture spike${claudeOnly ? " using Claude only" : ""}"; the shipped spec-and-plan template does not implement changes.`,
+          "Installing a definition or creating a run does not execute it. Simulation is not evidence of a bug fix or workflow completion.",
+        ],
+      },
+    };
+  }
+
+  const roles: RoleSpec[] = [];
+  for (const step of steps) {
+    if (!step.agent) continue;
+    const role = roles.find((entry) => entry.agent === step.agent);
+    if (role) role.role += `, ${step.id}`;
+    else roles.push({ agent: step.agent, harness: selected.id, role: step.id });
+  }
+  const shell = process.platform === "win32" ? "powershell" : "posix";
+  const quotedPrompt = shell === "powershell"
+    ? `'${prompt.replace(/['\u2018-\u201b]/g, "$&$&")}'`
+    : `'${prompt.replace(/'/g, "'\\''")}'`;
+  return {
+    ...base,
+    roles,
+    execution: {
+      supported: true,
+      prerequisites: [
+        "Run kxm init in the target repository if needed, then install the exact template with the suggested command. If that workflow ID already exists, stop and review it; the commands below apply only to a newly installed template, not an existing definition with potentially different agents or permissions.",
+        ...roles.map((role) => `Set harness: ${role.harness} and model: <your authenticated compatible model selector> in .kxm/agents/${role.agent}.yaml. Admit that exact selector in .kxm/routes.yaml and ensure it is not disabled; this recommendation does not choose a model or change routing.`),
+        ...(writeStep ? [
+          `Keep each writer step at assignments.maximum: 1 and set limits.maxConcurrentRuns: 1 in .kxm/project.yaml; the live ${selected.id} writer profile requires a lone writer in the checkout.`,
+          `If .kxm/roster.yaml exists, it must be readable kxm.developer-roster.v1 with a lineup.writer route matching harness: ${selected.id} and the selected writer model (model or vendor/model), status: admitted, and permissions containing edit.`,
+          "Configure the test gate in .kxm/gates.yaml with kind: command and argv for this repository's actual verification command. A scaffold/example command or simulation is not evidence that the implementation works.",
+        ] : []),
+        `Validate the installed workflow with kxm gate validate --file .kxm/workflows/${bestPattern.id}.yaml and the project configuration with kxm init --dry-run before creating a run.`,
+      ],
+      shell,
+      createCommand: `kxm run ${bestPattern.id} -- ${quotedPrompt}`,
+      driveCommand: "kxm runs drive <runId> --wait",
+      statusCommand: "kxm runs status <runId>",
+      receiptCommand: "kxm runs receipt <runId>",
     },
-    suggestedCommand: bestPattern.defaultCommand(prompt.replace(/"/g, '\\"')),
   };
 }

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

@@ -5,9 +5,28 @@
  */
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { parse, stringify } from "yaml";
+import { join } from "node:path";
+import { stringify } from "yaml";
 import { repoConfigDirectory, userConfigDirectory } from "./config.ts";
+import { compileKxmWorkflow } from "./engine-compile.ts";
+import { KxmConfigError, KxmSchemaRegistry, kxmResourceIdentifier, parseRestrictedYaml } from "./project-config.ts";
+
+function assertWorkflowId(workflowId: string): void {
+  if (!kxmResourceIdentifier(workflowId)) {
+    throw new Error(`workflow_id_invalid: '${workflowId}' must be a flat lowercase slug of at most 64 characters, starting with a letter and using letters, digits, single hyphens or underscores; paths and platform-reserved names are not allowed (use 'bug-fix', not 'software-engineering/bug-fix')`);
+  }
+}
+
+let workflowSchemaRegistry: KxmSchemaRegistry | undefined;
+
+function workflowPayload(workflowId: string, content: Record<string, unknown> | string, filePath: string): string {
+  const payload = typeof content === "string" ? content : stringify(content);
+  const value = parseRestrictedYaml(payload, filePath);
+  const issues = (workflowSchemaRegistry ??= new KxmSchemaRegistry()).validate("workflow", value, filePath);
+  if (issues.length > 0) throw new KxmConfigError(issues);
+  compileKxmWorkflow({ id: workflowId, value, logicalPath: filePath });
+  return payload;
+}
 
 export interface WorkflowDefSummary {
   id: string;
@@ -197,9 +216,7 @@ export function parseWorkflowFile(filePath: string): Record<string, unknown> | u
   if (!existsSync(filePath)) return undefined;
   try {
     const raw = readFileSync(filePath, "utf8");
-    const parsed = parse(raw) as Record<string, unknown>;
-    if (!parsed || typeof parsed !== "object") return undefined;
-    return parsed;
+    return parseRestrictedYaml(raw, filePath);
   } catch {
     return undefined;
   }
@@ -218,11 +235,11 @@ export function listWorkflowDefinitions(options: {
   const localDefs = new Map<string, { def: Record<string, unknown>; filePath: string }>();
   if (scopeFilter !== "global" && existsSync(localDir)) {
     for (const entry of readdirSync(localDir)) {
-      if (entry.endsWith(".yaml") || entry.endsWith(".yml")) {
+      const id = entry.endsWith(".yaml") ? entry.slice(0, -5) : entry.endsWith(".yml") ? entry.slice(0, -4) : undefined;
+      if (id && kxmResourceIdentifier(id)) {
         const filePath = join(localDir, entry);
         const def = parseWorkflowFile(filePath);
         if (def) {
-          const id = (def.id as string) || entry.replace(/\.ya?ml$/i, "");
           localDefs.set(id, { def, filePath });
         }
       }
@@ -232,11 +249,11 @@ export function listWorkflowDefinitions(options: {
   const globalDefs = new Map<string, { def: Record<string, unknown>; filePath: string }>();
   if (scopeFilter !== "local" && existsSync(globalDir)) {
     for (const entry of readdirSync(globalDir)) {
-      if (entry.endsWith(".yaml") || entry.endsWith(".yml")) {
+      const id = entry.endsWith(".yaml") ? entry.slice(0, -5) : entry.endsWith(".yml") ? entry.slice(0, -4) : undefined;
+      if (id && kxmResourceIdentifier(id)) {
         const filePath = join(globalDir, entry);
         const def = parseWorkflowFile(filePath);
         if (def) {
-          const id = (def.id as string) || entry.replace(/\.ya?ml$/i, "");
           globalDefs.set(id, { def, filePath });
         }
       }
@@ -248,7 +265,7 @@ export function listWorkflowDefinitions(options: {
     const steps = Array.isArray(def.steps) ? def.steps : [];
     for (const step of steps) {
       if (step && typeof step === "object") {
-        const role = (step as Record<string, unknown>).role || (step as Record<string, unknown>).agent;
+        const role = (step as Record<string, unknown>).agent;
         if (typeof role === "string" && !roles.includes(role)) {
           roles.push(role);
         }
@@ -298,6 +315,7 @@ export function getWorkflowDefinition(
     userConfigDir?: string | undefined;
   } = {},
 ): { workflow: Record<string, unknown>; scope: "global" | "local"; filePath: string } | undefined {
+  assertWorkflowId(workflowId);
   const scope = options.scope ?? "all";
   const repoRoot = options.repoRoot ?? process.cwd();
 
@@ -331,19 +349,21 @@ export function addWorkflowDefinition(
     dryRun?: boolean | undefined;
   } = {},
 ): { id: string; filePath: string; scope: "global" | "local" } {
+  assertWorkflowId(workflowId);
   const scope = options.scope ?? "local";
   const repoRoot = options.repoRoot ?? process.cwd();
-  const dir = options.dryRun
-    ? workflowsDirectory(scope, repoRoot, options.userConfigDir)
-    : ensureWorkflowsDirectory(scope, repoRoot, options.userConfigDir);
+  const dir = workflowsDirectory(scope, repoRoot, options.userConfigDir);
   const filePath = join(dir, `${workflowId}.yaml`);
 
   if (existsSync(filePath) && !options.overwrite) {
     throw new Error(`workflow_already_exists: workflow '${workflowId}' already exists at ${filePath}`);
   }
 
-  const payload = typeof content === "string" ? content : stringify(content);
-  if (!options.dryRun) writeFileSync(filePath, payload, "utf8");
+  const payload = workflowPayload(workflowId, content, filePath);
+  if (!options.dryRun) {
+    ensureWorkflowsDirectory(scope, repoRoot, options.userConfigDir);
+    writeFileSync(filePath, payload, "utf8");
+  }
   return { id: workflowId, filePath, scope };
 }
 
@@ -356,6 +376,7 @@ export function removeWorkflowDefinition(
     dryRun?: boolean | undefined;
   } = {},
 ): { id: string; removed: boolean; filePath: string; scope: "global" | "local" } {
+  assertWorkflowId(workflowId);
   const scope = options.scope ?? "local";
   const repoRoot = options.repoRoot ?? process.cwd();
   const dir = workflowsDirectory(scope, repoRoot, options.userConfigDir);
@@ -392,11 +413,13 @@ export function modifyWorkflowDefinition(
 
   const scope = options.scope ?? target.scope;
   const repoRoot = options.repoRoot ?? process.cwd();
-  const dir = options.dryRun
-    ? workflowsDirectory(scope, repoRoot, options.userConfigDir)
-    : ensureWorkflowsDirectory(scope, repoRoot, options.userConfigDir);
+  const dir = workflowsDirectory(scope, repoRoot, options.userConfigDir);
   const filePath = join(dir, `${workflowId}.yaml`);
 
-  if (!options.dryRun) writeFileSync(filePath, stringify(updated), "utf8");
+  const payload = workflowPayload(workflowId, updated, filePath);
+  if (!options.dryRun) {
+    ensureWorkflowsDirectory(scope, repoRoot, options.userConfigDir);
+    writeFileSync(filePath, payload, "utf8");
+  }
   return { id: workflowId, workflow: updated, filePath, scope };
 }

package/schemas/backup-manifest.schema.json

@@ -23,6 +23,21 @@
       "type": "string",
       "maxLength": 1024
     },
+    "scope": {
+      "description": "project: the checkout's stores and its own Runtime event store. all-projects: also the shared Runtime registry and every project's event store. Absent on manifests written before backups were scoped.",
+      "enum": ["project", "all-projects"]
+    },
+    "stateRoot": {
+      "description": "The user state root the Runtime stores were copied from.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024
+    },
+    "runtimeProjectKey": {
+      "description": "The Runtime store key of the checkout the backup ran from.",
+      "type": "string",
+      "pattern": "^[0-9a-f]{24}$"
+    },
     "stores": {
       "type": "array",
       "items": {