@kontextmind/kxm 0.7.104 → 0.7.106

package/plugins/kxm/src/cli/tasks.ts

@@ -9,7 +9,6 @@ import {
   listGoals,
   listTasks,
   getTask,
-  updateTaskStatus,
   syncTaskWithTracker,
   goalFilePath,
   taskFilePath,
@@ -27,40 +26,71 @@ import { readSessionTokenFromDisk } from "../commands.ts";
 import { print, printPlan, type Runtime } from "./types.ts";
 import { cmdKxmRun, resolveKxmRunTarget } from "./project.ts";
 
-export async function cmdSuggest(runtime: Runtime, promptParts: string[]): Promise<number> {
+export async function cmdSuggest(
+  runtime: Runtime,
+  promptParts: string[],
+  probeHarnesses = probeHarnessesAsync,
+): Promise<number> {
   try {
     const prompt = promptParts.join(" ").trim();
     if (!prompt) {
-      runtime.io.stderr("prompt must be non-empty\n");
+      print(runtime.io, runtime.json, { ok: false, command: "suggest", error: "prompt_required" }, "prompt must be non-empty");
       return 2;
     }
-    const inventory = await probeHarnessesAsync({ env: runtime.env });
-    const availableHarnesses = inventory.harnesses.map((h) => ({
-      harness: h.id,
-      auth: h.authenticated === true ? "authenticated" : "unauthenticated",
-    }));
-    const suggestion = suggestWorkflowAndRoles(prompt, { availableHarnesses });
-
+    // Native authentication probes may initialize state. A dry run must not invoke them.
+    const inventory = runtime.dryRun ? undefined : await probeHarnesses({ env: runtime.env });
+    const suggestion = suggestWorkflowAndRoles(prompt, { availableHarnesses: inventory?.harnesses });
+    if (suggestion.execution.supported && [".yaml", ".yml"].some((extension) =>
+      existsSync(join(runtime.cwd, ".kxm", "workflows", `${suggestion.workflowId}${extension}`)))) {
+      suggestion.roles = [];
+      suggestion.execution = {
+        supported: false,
+        error: "workflow_already_exists",
+        reason: `Workflow ${suggestion.workflowId} already exists; its agents and permissions may differ from the recommended template.`,
+        nextSteps: ["Review the existing definition and every agent's harness/model before running it, or install the recommended template under a fresh flat ID. No existing workflow is overwritten or recommended for execution."],
+      };
+    }
+    const execution = suggestion.execution;
     const text = [
       `Suggested Workflow: ${suggestion.workflowId} (${suggestion.area})`,
+      `Template: ${suggestion.template}`,
       `Confidence: ${(suggestion.confidence * 100).toFixed(0)}%`,
       `Reasons: ${suggestion.reasons.join("; ")}`,
       `Suggested Skills: ${suggestion.suggestedSkills.join(", ") || "none"}`,
-      `Roles:`,
-      `  Planner:     ${suggestion.roles.planner.harness} (${suggestion.roles.planner.model})`,
-      `  Writer:      ${suggestion.roles.writer.harness} (${suggestion.roles.writer.model})`,
-      `  Critics:     ${suggestion.roles.critics.map((c) => `${c.harness}:${c.model}`).join(", ")}`,
-      `  Verifier:    ${suggestion.roles.verifier.command}`,
-      ``,
-      `Execute with:`,
+      "",
+      "Install definition only (requires kxm init; does not execute):",
       `  ${suggestion.suggestedCommand}`,
+      "",
+      ...(execution.supported ? [
+        "Suggested agent routing (not applied):",
+        ...suggestion.roles.map((role) => `  ${role.agent}: ${role.harness} (${role.role}; use a configured compatible model)`),
+        "Prerequisites:",
+        ...execution.prerequisites.map((step) => `  ${step}`),
+        `Create a run only (${execution.shell}; does not execute steps):`,
+        `  ${execution.createCommand}`,
+        "Then drive the returned run ID with live calls and inspect its result:",
+        `  ${execution.driveCommand}`,
+        `  ${execution.statusCommand}`,
+        `  ${execution.receiptCommand}`,
+      ] : [
+        `Execution unavailable: ${execution.reason}`,
+        ...execution.nextSteps.map((step) => `  ${step}`),
+        ...(runtime.dryRun ? ["Harness authentication was not probed during --dry-run."] : []),
+      ]),
     ].join("\n");
 
-    print(runtime.io, runtime.json, { ok: true, command: "suggest", prompt, ...suggestion }, text);
-    return 0;
+    print(runtime.io, runtime.json, {
+      ok: execution.supported,
+      command: "suggest",
+      prompt,
+      ...suggestion,
+      ...(runtime.dryRun ? { dryRun: true } : {}),
+      ...(!execution.supported ? { error: execution.error } : {}),
+    }, text);
+    return execution.supported ? 0 : 1;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`suggest failed: ${message}\n`);
+    print(runtime.io, runtime.json, { ok: false, command: "suggest", error: "suggest_failed", detail: message }, `suggest failed: ${message}`);
     return 1;
   }
 }
@@ -196,27 +226,21 @@ export async function cmdTaskRun(runtime: Runtime, taskId: string): Promise<numb
       runtime.io.stderr(`Task ${taskId} not found\n`);
       return 1;
     }
-    const workflow = task.assignedWorkflow ?? "default";
+    const workflow = task.assignedWorkflow;
     if (runtime.dryRun) {
-      const target = resolveKxmRunTarget(runtime, workflow);
+      const target = resolveKxmRunTarget(runtime, workflow, true);
       if (typeof target === "number") return target;
-      const started = updateTaskStatus(runtime.cwd, taskId, "in_progress", { dryRun: true });
       printPlan(
         runtime,
-        { command: "task run", taskId, ...target, status: started.status },
+        { command: "task run", taskId, ...target, status: task.status, execution: { status: "not_started", mode: "live" } },
         [
           { action: "request", target: "POST kxm-runtime /v1/runs (starts the Runtime supervisor if it is not running)" },
-          { action: "write", target: taskFilePath(runtime.cwd, taskId) },
         ],
-        `run workflow ${workflow} for task ${taskId}, then mark it ${started.status}`,
+        `create workflow ${target.workflowId} for task ${taskId}; task status stays ${task.status} until work actually starts`,
       );
       return 0;
     }
-    const exitCode = await cmdKxmRun(runtime, workflow, [task.objective]);
-    if (exitCode === 0) {
-      updateTaskStatus(runtime.cwd, taskId, "in_progress");
-    }
-    return exitCode;
+    return await cmdKxmRun(runtime, workflow, [task.objective], true);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     runtime.io.stderr(`task run failed: ${message}\n`);

package/plugins/kxm/src/cli/workflows.ts

@@ -11,7 +11,6 @@ import {
   addWorkflowDefinition,
   removeWorkflowDefinition,
   modifyWorkflowDefinition,
-  parseWorkflowFile,
   scaffoldWorkflowDefinition,
   WORKFLOW_TEMPLATES,
 } from "../workflow-manager.ts";
@@ -23,7 +22,7 @@ import {
   type WorkflowJournalEntry,
   type WorkflowRun,
 } from "../workflow.ts";
-import { discoverKxmProjectRoot, kxmWorkflowWriteIssues } from "../project-config.ts";
+import { discoverKxmProjectRoot, kxmWorkflowWriteIssues, parseRestrictedYaml } from "../project-config.ts";
 import { ensureKxmSupervisor, kxmRuntimeRequest } from "../runtime-supervisor.ts";
 import { projectRuntimeOwnsRun } from "../runtime-store.ts";
 import type { WorkerOutcome } from "../envelope.ts";
@@ -215,63 +214,63 @@ export async function cmdWorkflowAdd(
   },
 ): Promise<number> {
   const scope = options.scope ?? "local";
-  const refuse = (error: string, text: string): number => {
-    print(runtime.io, runtime.json, { ok: false, command: "workflow add", error }, `workflow add failed: ${text}`);
-    return 2;
+  const refuse = (error: string, message: string, code = 2): number => {
+    print(runtime.io, runtime.json, { ok: false, command: "workflow add", error, message }, `workflow add failed: ${message}`);
+    return code;
   };
-  let content: Record<string, unknown> | string | undefined;
-  if (options.template !== undefined) {
-    if (options.file !== undefined || options.pick !== undefined) {
-      return refuse("workflow_add_conflict", "--template cannot be combined with --file or --pick");
-    }
-    if (!workflowId) return refuse("workflow_id_required", "usage: kxm workflow add <workflowId> --template <name>");
-    const template = Object.hasOwn(WORKFLOW_TEMPLATES, options.template) ? WORKFLOW_TEMPLATES[options.template] : undefined;
-    if (!template) {
-      return refuse("workflow_template_unknown", `unknown template ${options.template}; choose ${Object.keys(WORKFLOW_TEMPLATES).join(", ")}`);
-    }
-    content = { ...template, ...(options.description ? { description: options.description } : {}) };
-  } else if (!workflowId || options.pick) {
-    const candidates: PickCandidate[] = Object.entries(WORKFLOW_TEMPLATES).map(([id, tmpl]) => ({
-      id,
-      description: String(tmpl.description ?? id),
-      label: "template",
-      payload: tmpl,
-    }));
-    if (scope === "local") {
-      const globalDefs = listWorkflowDefinitions({ scope: "global", userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
-      for (const gd of globalDefs) {
-        // Read the listed file itself: it may be `.yml`, which a lookup by `<id>.yaml` misses.
-        const definition = parseWorkflowFile(gd.filePath);
-        if (definition && !candidates.some((c) => c.id === gd.id)) {
-          candidates.push({ id: gd.id, description: gd.description, label: "global", payload: definition });
+  try {
+    let content: Record<string, unknown> | string | undefined;
+    if (options.template !== undefined) {
+      if (options.file !== undefined || options.pick !== undefined) {
+        return refuse("workflow_add_conflict", "--template cannot be combined with --file or --pick");
+      }
+      if (!workflowId) return refuse("workflow_id_required", "usage: kxm workflow add <workflowId> --template <name>");
+      const template = Object.hasOwn(WORKFLOW_TEMPLATES, options.template) ? WORKFLOW_TEMPLATES[options.template] : undefined;
+      if (!template) {
+        return refuse("workflow_template_unknown", `unknown template ${options.template}; choose ${Object.keys(WORKFLOW_TEMPLATES).join(", ")}`);
+      }
+      content = { ...template, ...(options.description !== undefined ? { description: options.description } : {}) };
+    } else if (!workflowId || options.pick) {
+      const candidates: PickCandidate[] = Object.entries(WORKFLOW_TEMPLATES).map(([id, tmpl]) => ({
+        id,
+        description: String(tmpl.description ?? id),
+        label: "template",
+        payload: tmpl,
+      }));
+      if (scope === "local") {
+        const globalDefs = listWorkflowDefinitions({ scope: "global", userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
+        for (const gd of globalDefs) {
+          // Read the listed path when selected: globals may use `.yml`, not only `.yaml`.
+          if (!candidates.some((c) => c.id === gd.id)) {
+            candidates.push({ id: gd.id, description: gd.description, label: "global", payload: gd.filePath });
+          }
         }
       }
-    }
-    const picked = await resolvePickItem(runtime.io, `Select a workflow template to add (${scope})`, candidates, options.pick, runtime.env);
-    if (!picked) {
-      if (!workflowId) {
-        runtime.io.stderr("workflow add failed: missing workflowId or pick selection\n");
-        return 1;
+      const picked = await resolvePickItem(runtime.io, `Select a workflow template to add (${scope})`, candidates, options.pick, runtime.env);
+      if (!picked) {
+        return refuse("workflow_id_required", "provide a workflowId or select an available workflow with --pick <id>", 1);
       }
-    } else {
-      workflowId = picked.id;
-      if (!options.file && picked.payload) {
-        content = {
-          ...picked.payload,
-          ...(options.description ? { description: options.description } : {}),
-        };
+      workflowId ??= picked.id;
+      if (options.file === undefined) {
+        const pickedContent = typeof picked.payload === "string"
+          ? readFileSync(picked.payload, "utf8")
+          : picked.payload;
+        content = options.description !== undefined
+          ? {
+            ...(typeof pickedContent === "string" ? parseRestrictedYaml(pickedContent, String(picked.payload)) : pickedContent),
+            description: options.description,
+          }
+          : pickedContent;
       }
     }
-  }
 
-  if (options.file) {
-    const filePath = resolve(runtime.cwd, options.file);
-    content = readFileSync(filePath, "utf8");
-  } else if (!content) {
-    content = scaffoldWorkflowDefinition(options.description || `Workflow ${workflowId}`);
-  }
+    if (options.file !== undefined) {
+      const filePath = resolve(runtime.cwd, options.file);
+      content = readFileSync(filePath, "utf8");
+    } else if (!content) {
+      content = scaffoldWorkflowDefinition(options.description || `Workflow ${workflowId}`);
+    }
 
-  try {
     const document = typeof content === "string" ? content : stringify(content);
     // A local workflow is read by the project loader, which refuses the whole
     // project over one bad file, so it is checked by that loader before it lands.
@@ -286,7 +285,7 @@ export async function cmdWorkflowAdd(
         print(
           runtime.io,
           runtime.json,
-          { ok: false, command: "workflow add", error: "workflow_invalid", issues },
+          { ok: false, command: "workflow add", error: "workflow_invalid", message: "with this workflow the project would not load, so nothing was written", issues },
           `workflow add failed: with this workflow the project would not load, so nothing was written\n${issues.map((entry) => `  ${entry.file}: ${entry.code}: ${entry.message}`).join("\n")}`,
         );
         return 2;
@@ -312,8 +311,7 @@ export async function cmdWorkflowAdd(
     );
     return 0;
   } catch (err: unknown) {
-    runtime.io.stderr(`workflow add failed: ${(err as Error).message}\n`);
-    return 1;
+    return refuse("workflow_add_failed", err instanceof Error ? err.message : String(err), 1);
   }
 }
 

package/plugins/kxm/src/cli.ts

@@ -432,7 +432,7 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       result.code = await cmdRestore(runtimeFrom(ctx, this), manifest, options);
     });
 
-  addGlobalOptions(program.command("run").description("Create a KXM run (offline-first; kxm runs drive <runId> --simulated executes it model-free)")
+  addGlobalOptions(program.command("run").description("Create a KXM run without executing steps; follow its prerequisites, then kxm runs drive <runId> --wait")
     .argument("[workflow]", "Workflow id to run")
     .argument("[prompt...]", "Run prompt (events keep its hash; the full text is kept in a local 0600 sidecar file)")
     .action(async function runAction(this: Command, workflow: string | undefined, promptParts: string[]) {

package/plugins/kxm/src/engine.ts

@@ -3,7 +3,6 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { parse } from "yaml";
 import { isRouteAdmitted, listRoleBindings } from "./routes.ts";
-import { oneShotWriterArgs } from "./harness.ts";
 import { applyAuthoringWitness, captureWorktreeWitness } from "./worktree-witness.ts";
 import {
   buildFormalContextPacket,
@@ -14,6 +13,7 @@ import {
   type HandoffManifestV1,
 } from "./context-packet.ts";
 import { compileKxmWorkflow, type KxmCompiledPlan, type KxmCompiledStep } from "./engine-compile.ts";
+import { BUILTIN_HARNESSES, oneShotPermissionArgs, oneShotWriterArgs, validateHarnessModelPair } from "./harness.ts";
 import {
   effectiveRunDurationBudget,
   isTerminalRunStatus,
@@ -2693,7 +2693,83 @@ function armRunDurationBudgetTimer(context: KxmRuntimeContext, runId: string): (
   };
 }
 
-function unsupportedLimit(envelope: KxmRunPlanEnvelope): KxmRunHandoff | undefined {
+/** Read-only admission guidance for a live run, using the same policies as dispatch. */
+export function kxmLiveRunPrerequisites(
+  bundle: KxmProjectBundle,
+  workflowId: string,
+  projectRoot: string,
+): KxmRunHandoff[] {
+  const workflow = bundle.workflows.get(workflowId);
+  if (!workflow) throw runtimeError("run_workflow_unknown", workflowId, `workflow ${workflowId} does not exist in this project`);
+  const plan = compileKxmWorkflow({ id: workflowId, value: workflow.value, logicalPath: workflow.logicalPath });
+  const envelope = { plan, projectLimits: kxmProjectAdmissionLimits(bundle), gates: pinnedGatesForCompiledPlan(plan, bundle, projectRoot) };
+  const prerequisites: KxmRunHandoff[] = [];
+  const limit = unsupportedLimit(envelope);
+  if (limit) prerequisites.push(limit);
+  const visited = new Set<string>();
+  const pending = [plan.entryStepId];
+  while (pending.length > 0) {
+    const stepId = pending.pop()!;
+    if (visited.has(stepId)) continue;
+    visited.add(stepId);
+    const step = plan.steps[stepId]!;
+    for (const transition of Object.values(step.transitions)) {
+      if (transition.to === "step") pending.push(transition.target);
+    }
+    const unsupported = step.kind === "gate"
+      ? unsupportedGateStep(plan, step, envelope, { projectRoot }) ?? starterGatePrerequisite(step, envelope.gates, projectRoot)
+      : unsupportedStep(plan, step, "oneshot");
+    if (unsupported) {
+      prerequisites.push({ ...unsupported, stepId });
+      continue;
+    }
+    if (step.kind !== "agent" && step.kind !== "moa") continue;
+    const agentIds = step.assignments.allowedAgents.length > 0 ? step.assignments.allowedAgents : [step.agent];
+    for (const agentId of agentIds) {
+      const agent = bundle.agents.get(agentId);
+      const harness = String(agent?.value.harness ?? bundle.project.value.defaultHarness ?? "pi");
+      const permission = Object.values(step.repositories).includes("write") ? "edit" : "read-only";
+      if (!BUILTIN_HARNESSES.some((entry) => entry.id === harness && entry.oneShot) || !oneShotPermissionArgs(harness, permission)) {
+        prerequisites.push({ reason: "step_unsupported", stepId, field: "harness", detail: `${agentId}: ${harness} has no audited ${permission} one-shot profile; use a supported workflow or execute this work directly in ${harness}, without substituting another harness` });
+        continue;
+      }
+      const route = resolveProducerRoute(projectRoot, step, agentId);
+      if ("error" in route) {
+        prerequisites.push({ ...route.error, stepId, detail: `${agentId}: ${route.error.detail}; configure its model in .kxm/agents/${agentId}.yaml and admit the installed model with kxm routes admit --model <provider/model>` });
+        continue;
+      }
+      const writeRefusal = unsupportedLiveWrite(projectRoot, step, agentId, route.selector, envelope.projectLimits.maxConcurrentRuns);
+      if (writeRefusal) {
+        prerequisites.push({ ...writeRefusal, stepId });
+        continue;
+      }
+      const compatible = validateHarnessModelPair(harness, route);
+      if (!compatible.valid) {
+        prerequisites.push({ reason: "step_unsupported", stepId, field: "model", detail: `${agentId}: ${compatible.message ?? `${harness} cannot run ${route.selector}`}; configure a model supported by ${harness} in .kxm/agents/${agentId}.yaml` });
+      }
+    }
+  }
+  return prerequisites;
+}
+
+function starterGatePrerequisite(step: KxmCompiledStep & { kind: "gate" }, gates: KxmPinnedGates, projectRoot: string): Omit<KxmRunHandoff, "stepId"> | undefined {
+  const definition = gates.definitions[step.gate];
+  if (!definition || definition.kind !== "command" || definition.argv.length !== 2 || definition.argv[0] !== "npm" || definition.argv[1] !== "test") return undefined;
+  let testScript: unknown;
+  try {
+    const manifest: unknown = JSON.parse(readFileSync(join(projectRoot, "package.json"), "utf8"));
+    if (manifest && typeof manifest === "object" && "scripts" in manifest) {
+      const scripts = manifest.scripts;
+      if (scripts && typeof scripts === "object" && "test" in scripts) testScript = scripts.test;
+    }
+  } catch { /* A missing or unreadable manifest cannot satisfy the starter gate. */ }
+  if (typeof testScript !== "string" || testScript.trim().length === 0) {
+    return { reason: "gate_unsupported", field: `gates.${step.gate}.argv`, detail: `gate ${step.gate} runs npm test but this repository has no readable package.json with scripts.test; configure .kxm/gates.yaml gates.${step.gate}.argv for the repository's actual test runner before driving this workflow` };
+  }
+  return undefined;
+}
+
+function unsupportedLimit(envelope: Pick<KxmRunPlanEnvelope, "plan" | "projectLimits">): KxmRunHandoff | undefined {
   if (envelope.plan.limits.maxAgentTimeMs !== undefined) {
     return { reason: "limit_unsupported", field: "limits.maxAgentTimeMs", detail: "agent-time budget enforcement is not available in this slice" };
   }
@@ -2847,7 +2923,7 @@ function unsupportedLiveWrite(
   return undefined;
 }
 
-function unsupportedGateStep(plan: KxmCompiledPlan, step: KxmCompiledStep & { kind: "gate" }, envelope: KxmRunPlanEnvelope, context?: { projectRoot: string }): Omit<KxmRunHandoff, "stepId"> | undefined {
+function unsupportedGateStep(plan: KxmCompiledPlan, step: KxmCompiledStep & { kind: "gate" }, envelope: Pick<KxmRunPlanEnvelope, "gates">, context?: { projectRoot: string }): Omit<KxmRunHandoff, "stepId"> | undefined {
   if (!step.gate) return { reason: "step_unsupported", field: "gate", detail: "gate step is missing gate id" };
   if (envelope.gates.registry === null) {
     return { reason: "step_unsupported", field: "gate", detail: `step ${step.id} refers to a gate but registry is null` };

package/plugins/kxm/src/harness.ts

@@ -62,6 +62,7 @@ export type HarnessRunCommand = (command: string, args: readonly string[], timeo
 export type HarnessRunCommandAsync = (command: string, args: readonly string[], timeoutMs: number) => HarnessCommandResult | Promise<HarnessCommandResult>;
 
 export interface HarnessProbeOptions {
+  defaultHarness?: string | undefined;
   env?: NodeJS.ProcessEnv | undefined;
   runCommand?: HarnessRunCommand | undefined;
   timeoutMs?: number | undefined;
@@ -96,7 +97,7 @@ export interface HarnessStatus {
 }
 
 export interface HarnessInventory {
-  defaultHarness: typeof DEFAULT_HARNESS;
+  defaultHarness: string;
   harnesses: readonly HarnessStatus[];
 }
 
@@ -958,7 +959,7 @@ function probeEntry(
   runCommand: (command: string, args: readonly string[], timeoutMs: number) => HarnessCommandResult,
   timeoutMs: number,
   platform: NodeJS.Platform,
-  probe: Pick<HarnessProbeOptions, "env" | "existsSync"> = {},
+  probe: Pick<HarnessProbeOptions, "env" | "existsSync" | "defaultHarness"> = {},
 ): HarnessStatus {
   const issues: string[] = [];
   const found = detectHarnessCommand(entry, runCommand, timeoutMs, platform, probe);
@@ -987,7 +988,7 @@ function probeEntry(
   return {
     id: entry.id,
     label: entry.label,
-    default: entry.default,
+    default: entry.id === (probe.defaultHarness ?? DEFAULT_HARNESS),
     mode: entry.mode,
     detected,
     authenticated,
@@ -1009,7 +1010,7 @@ export function probeHarnesses(options: HarnessProbeOptions = {}): HarnessInvent
   const runCommand = options.runCommand ?? defaultRunner(options.env ?? process.env);
   const platform = options.platform ?? process.platform;
   return {
-    defaultHarness: DEFAULT_HARNESS,
+    defaultHarness: options.defaultHarness ?? DEFAULT_HARNESS,
     harnesses: BUILTIN_HARNESSES.map((entry) => probeEntry(entry, runCommand, timeoutMs, platform, options)),
   };
 }
@@ -1508,7 +1509,7 @@ export function formatHarnessInventory(inventory: HarnessInventory): string {
     ].join(" ");
   });
   return [
-    `default harness: ${inventory.defaultHarness} (omit agent harness: to use headless Pi)`,
+    `default harness: ${inventory.defaultHarness} (used when an agent omits harness:)`,
     "enable/disable = Git YAML (.kxm/agents, .kxm/models) or the harness's own plugin CLI",
     "governed kxm skills are not auto-updated",
     header,

package/plugins/kxm/src/mcp-server.ts

@@ -11,7 +11,7 @@ import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 import { sessionTokenFixHint } from "./session-token-hint.ts";
 
-const VERSION = "0.7.104";
+const VERSION = "0.7.106";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();

package/plugins/kxm/src/project-config.ts

@@ -1124,6 +1124,7 @@ function validateBundle(
   options: KxmConfigOptions,
   gateRegistry?: KxmResource,
   projectRoot?: string,
+  writerRole?: string,
 ): KxmConfigIssue[] {
   const issues: KxmConfigIssue[] = [];
   const entries = valuesOf(project.value, "repositories").map((candidate) => objectValue(candidate)).filter((candidate): candidate is JsonObject => Boolean(candidate));
@@ -1200,9 +1201,9 @@ function validateBundle(
   if (projectRoot) {
     const writerRolePath = join(projectRoot, ".kxm", "roles", "writer.yaml");
     const implementerAgent = agents.get("implementer") ?? agents.get("writer");
-    if (existsSync(writerRolePath) && implementerAgent) {
+    if ((writerRole !== undefined || existsSync(writerRolePath)) && implementerAgent) {
       try {
-        const rawRole = parseRestrictedYaml(readFileSync(writerRolePath, "utf8"));
+        const rawRole = parseRestrictedYaml(writerRole ?? readFileSync(writerRolePath, "utf8"));
         const roleObj = objectValue(rawRole);
         const rosterEntries = valuesOf(roleObj ?? {}, "roster")
           .map((candidate) => objectValue(candidate))
@@ -1304,8 +1305,32 @@ export function kxmWorkflowWriteIssues(
   document: string,
   options: KxmConfigOptions = {},
 ): readonly KxmConfigIssue[] {
+  return candidateIssues(projectRoot, options, { kind: "workflow", id: workflowId, document });
+}
+
+/**
+ * What `loadKxmProject` would refuse once `.kxm/roles/<roleId>.yaml` held `document`,
+ * found without writing it. The loader reads only the writer role, so for any other
+ * id this is the project's load as it stands.
+ */
+export function kxmRoleWriteIssues(
+  projectRoot: string,
+  roleId: string,
+  document: string,
+  options: KxmConfigOptions = {},
+): readonly KxmConfigIssue[] {
+  return candidateIssues(projectRoot, options, { kind: "role", id: roleId, document });
+}
+
+interface WriteCandidate {
+  kind: "workflow" | "role";
+  id: string;
+  document: string;
+}
+
+function candidateIssues(projectRoot: string, options: KxmConfigOptions, candidate: WriteCandidate): readonly KxmConfigIssue[] {
   try {
-    loadProjectBundle(projectRoot, options, { id: workflowId, document });
+    loadProjectBundle(projectRoot, options, candidate);
     return [];
   } catch (error) {
     if (error instanceof KxmConfigError) return error.issues;
@@ -1316,8 +1341,11 @@ export function kxmWorkflowWriteIssues(
 function loadProjectBundle(
   projectRoot: string,
   options: KxmConfigOptions,
-  workflowCandidate?: { id: string; document: string },
+  candidate?: WriteCandidate,
 ): KxmProjectBundle {
+  const workflowCandidate = candidate?.kind === "workflow" ? candidate : undefined;
+  // A case-insensitive filesystem serves `Writer.yaml` to the loader's `writer.yaml` lookup.
+  const writerRole = candidate?.kind === "role" && candidate.id.toLocaleLowerCase("en-US") === "writer" ? candidate.document : undefined;
   assertNoRegisteredGates(options);
   const root = resolve(projectRoot);
   const legacyPresent = legacyConfigFilesAt(root);
@@ -1484,7 +1512,7 @@ function loadProjectBundle(
   }
   if (loadIssues.length > 0) throw new KxmConfigError(loadIssues);
 
-  const issues = validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, root);
+  const issues = validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, root, writerRole);
   if (issues.length > 0) throw new KxmConfigError(issues);
   const resources = [project, ...repositories.values(), ...agents.values(), ...models.values(), ...workflows.values(), ...environments, ...(gateRegistry ? [gateRegistry] : [])]
     .sort((left, right) => compareCodeUnits(left.logicalPath, right.logicalPath));