@kontextmind/kxm 0.7.123 → 0.7.125

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.123",
+  "version": "0.7.125",
   "private": true,
   "type": "module",
   "engines": {

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

@@ -7,6 +7,7 @@ import { print, type Runtime } from "./types.ts";
 export interface LandOptions {
   pr?: string;
   stage?: string;
+  title?: string;
   bodyFile?: string;
 }
 
@@ -35,6 +36,7 @@ export function cmdLand(runtime: Runtime, options: LandOptions = {}): Promise<nu
   const args = [script];
   if (options.pr) args.push("--pr", options.pr);
   if (options.stage) args.push("--stage", options.stage);
+  if (options.title) args.push("--title", options.title);
   if (options.bodyFile) args.push("--body-file", options.bodyFile);
   if (runtime.json) args.push("--json");
   if (runtime.dryRun) args.push("--dry-run");

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

@@ -522,7 +522,12 @@ interface KxmStatusDrive {
   mode?: string;
   openedAt?: string;
   receipt?: {
-    settlement?: { kind?: string; status?: string; reason?: string };
+    settlement?: {
+      kind?: string;
+      status?: string;
+      reason?: string;
+      handoff?: { reason?: string; attemptId?: string };
+    };
   } | null;
   verified?: boolean;
   divergence?: string;
@@ -568,7 +573,14 @@ function formatRunStatusLine(
   drive: KxmStatusDrive | undefined,
 ): string {
   const reason = typeof drive?.receipt?.settlement?.reason === "string" ? drive.receipt.settlement.reason : "";
-  const statusLabel = run.status === "cancelled" ? formatCancelledStatus(reason) : run.status;
+  const handoff = drive?.receipt?.settlement?.handoff;
+  const attemptId = typeof handoff?.attemptId === "string" ? handoff.attemptId : "";
+  const handoffReason = typeof handoff?.reason === "string" ? handoff.reason : "";
+  const statusLabel = run.status === "cancelled"
+    ? formatCancelledStatus(reason)
+    : run.status === "cancelling" && attemptId.length > 0 && handoffReason.length > 0
+      ? `cancelling (attempt ${attemptId}, ${handoffReason})`
+      : run.status;
   return `run ${run.runId}: ${statusLabel} (workflow ${run.workflowId}, updated ${run.updatedAt})`;
 }
 

package/plugins/kxm/src/cli.ts

@@ -31,6 +31,7 @@ import { projectRuntimeOwnsRun } from "./runtime-store.ts";
 
 // Submodule imports
 import {
+  CLI_RESULT_SCHEMA,
   print,
   refuseDryRun,
   runtimeFrom,
@@ -400,7 +401,7 @@ async function dispatchAgentCliCommand(
   }
 }
 
-function createProgram(ctx: CliContext, result: { code: number }): Command {
+function createProgram(ctx: CliContext, result: { code: number }, argv: readonly string[]): Command {
   const bind = (action: (runtime: Runtime, ...args: never[]) => Promise<number>) => {
     return async function commandAction(this: Command, ...args: unknown[]) {
       const command = args.at(-1) instanceof Command ? args.at(-1) as Command : this;
@@ -415,7 +416,11 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
     .exitOverride()
     .configureOutput({
       writeOut: (text) => ctx.io.stdout(text),
-      writeErr: (text) => ctx.io.stderr(text),
+      // Subcommands inherit this object by reference (copyInheritedSettings).
+      writeErr: (text) => {
+        if (hasJsonFlag(argv)) return;
+        ctx.io.stderr(text);
+      },
     })
     .helpCommand("help", "Show help");
   addGlobalOptions(program);
@@ -496,11 +501,13 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
   addGlobalOptions(program.command("land").description("Land the current branch: verify, regenerate docs, push, pull request, rebase, unblock, squash-merge, release, and milestone"))
     .option("--pr <n>", "Existing pull request number")
     .option("--stage <name>", "Run one stage: verify, docs, push, pr, rebase, unblock, merge, release, or milestone")
+    .option("--title <text>", "Pull request title. Default is the subject of the first commit on the branch")
     .option("--body-file <path>", "Pull request body file used when creating a pull request")
-    .action(async function landAction(this: Command, options: { pr?: string; stage?: string; bodyFile?: string }) {
+    .action(async function landAction(this: Command, options: { pr?: string; stage?: string; title?: string; bodyFile?: string }) {
       result.code = await cmdLand(runtimeFrom(ctx, this), {
         ...(options.pr !== undefined ? { pr: options.pr } : {}),
         ...(options.stage !== undefined ? { stage: options.stage } : {}),
+        ...(options.title !== undefined ? { title: options.title } : {}),
         ...(options.bodyFile !== undefined ? { bodyFile: options.bodyFile } : {}),
       });
     });
@@ -1434,10 +1441,57 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
   return program;
 }
 
-function mapCommanderError(error: CommanderError): number {
+function hasJsonFlag(argv: readonly string[]): boolean {
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]!;
+    if (arg === "--") break;
+    if (arg === "--json") return true;
+  }
+  return false;
+}
+
+function commandWords(argv: readonly string[]): string[] {
+  const words: string[] = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]!;
+    if (arg === "--") break;
+    if (!arg.startsWith("-")) {
+      words.push(arg);
+      continue;
+    }
+    if (arg.includes("=") || arg === "--json" || arg === "--dry-run" || arg === "-h" || arg === "--help" || arg === "-V" || arg === "--version") continue;
+    const next = argv[index + 1];
+    if (next !== undefined && !next.startsWith("-")) index += 1;
+  }
+  return words;
+}
+
+function commandPathFromArgv(program: Command, argv: readonly string[]): string {
+  const names: string[] = [];
+  let current: Command = program;
+  for (const word of commandWords(argv)) {
+    const next = current.commands.find((command) => command.name() === word || command.aliases().includes(word));
+    if (!next) break;
+    names.push(next.name());
+    current = next;
+  }
+  return names.join(" ");
+}
+
+function mapCommanderError(error: CommanderError, argv: readonly string[], program: Command, io: CliIo): number {
   if (error.exitCode === 0) return 0;
-  if (USAGE_ERROR_CODES.has(error.code)) return 2;
-  return error.exitCode || 1;
+  const code = USAGE_ERROR_CODES.has(error.code) ? 2 : (error.exitCode || 1);
+  if (code === 2 && hasJsonFlag(argv)) {
+    const command = commandPathFromArgv(program, argv);
+    io.stdout(`${JSON.stringify({
+      schema: CLI_RESULT_SCHEMA,
+      ok: false,
+      command: command || "kxm",
+      error: "usage_error",
+      detail: error.message,
+    })}\n`);
+  }
+  return code;
 }
 
 const MESH_REMOVED_TEXT = "kxm mesh was removed. Use kxm init, kxm hub start|view|stop, and node scripts/smoke-multi-pi.mjs (KXM_SMOKE=1).";
@@ -1486,12 +1540,12 @@ export async function runCli(
     return 2;
   }
   const result = { code: 0 };
-  const program = createProgram({ env, io, cwd }, result);
+  const program = createProgram({ env, io, cwd }, result, argv);
   try {
     await program.parseAsync(argv, { from: "user" });
     return result.code;
   } catch (error) {
-    if (error instanceof CommanderError) return mapCommanderError(error);
+    if (error instanceof CommanderError) return mapCommanderError(error, argv, program, io);
     if (error instanceof DryRunRefused) return error.code;
     throw error;
   }

package/plugins/kxm/src/engine-fold.ts

@@ -158,6 +158,7 @@ interface MutableAttempt {
   status: string;
   resultClass?: string | undefined;
   outcome?: string | undefined;
+  producerError?: string | undefined;
 }
 
 interface MutableAssignment {
@@ -317,7 +318,7 @@ function authorizedCancelStep(state: MutableState, step: KxmCompiledStep, curren
   if (status !== "cancelled" || !state.cancelRequested) return false;
   if (createdOnlySingletonCancel(state, step, current, status)) return true;
   if (!panelIssuedAttemptsTerminal(current) || !panelAssignmentsTerminal(current)) return false;
-  const members: Array<{ resultClass: string; outcome: string | undefined }> = [];
+  const members: Array<{ resultClass: string; outcome: string | undefined; producerError: string | undefined }> = [];
   for (const assignmentId of current.panel.order) {
     const assignment = current.panel.assignments[assignmentId];
     if (!assignment) return false;
@@ -328,9 +329,12 @@ function authorizedCancelStep(state: MutableState, step: KxmCompiledStep, curren
     }
     const currentAttempt = currentAttemptOf(assignment);
     if (!currentAttempt?.resultClass) return false;
-    members.push({ resultClass: currentAttempt.resultClass, outcome: currentAttempt.outcome });
+    members.push({ resultClass: currentAttempt.resultClass, outcome: currentAttempt.outcome, producerError: currentAttempt.producerError });
   }
   if (members.some((member) => member.resultClass === "outcome_unknown" || member.resultClass === "producer_rejected")) {
+    if (members.every((member) => member.resultClass === "producer_rejected" && member.producerError === "executing_unrecorded")) {
+      return true;
+    }
     return false;
   }
   const declared = members.filter((member) => member.resultClass === "outcome");
@@ -343,8 +347,8 @@ function authorizedCancelStep(state: MutableState, step: KxmCompiledStep, curren
 
 function currentAttemptOf(assignment: {
   currentAttemptId?: string | undefined;
-  attempts: { readonly [id: string]: { resultClass?: string | undefined; outcome?: string | undefined } | undefined };
-}): { resultClass?: string | undefined; outcome?: string | undefined } | undefined {
+  attempts: { readonly [id: string]: { resultClass?: string | undefined; outcome?: string | undefined; producerError?: string | undefined } | undefined };
+}): { resultClass?: string | undefined; outcome?: string | undefined; producerError?: string | undefined } | undefined {
   const attemptId = assignment.currentAttemptId;
   return attemptId ? assignment.attempts[attemptId] : undefined;
 }
@@ -735,8 +739,8 @@ function isProvenFailure(state: MutableState, plan: KxmCompiledPlan | undefined)
 }
 
 function foldDriveOpened(state: MutableState, event: KxmRunEvent): void {
-  if (state.status !== "running" && state.status !== "blocked_uncertain") {
-    throw runtimeError("run_events_illegal", state.runId, "run.drive_opened is only legal while running or blocked_uncertain");
+  if (state.status !== "running" && state.status !== "blocked_uncertain" && state.status !== "cancelling") {
+    throw runtimeError("run_events_illegal", state.runId, "run.drive_opened is only legal while running, blocked_uncertain, or cancelling");
   }
   const driveId = stringPayload(event, "driveId");
   const mode = stringPayload(event, "mode");
@@ -1093,9 +1097,13 @@ function foldAssignmentAdvance(state: MutableState, plan: KxmCompiledPlan, event
         }
       }
       if (attemptId && attempt) {
+        const producerError = typeof event.payload.producerError === "string" ? event.payload.producerError : undefined;
         nextAssignment = {
           ...nextAssignment,
-          attempts: { ...nextAssignment.attempts, [attemptId]: { ...attempt, resultClass } },
+          attempts: {
+            ...nextAssignment.attempts,
+            [attemptId]: { ...attempt, resultClass, ...(producerError !== undefined ? { producerError } : {}) },
+          },
         };
       }
     }

package/plugins/kxm/src/engine-plan.ts

@@ -31,7 +31,7 @@ const CONTROL_ROOT_REQUIRED = ["repositoryId", "projectKey"] as const;
 const GATE_REGISTRY_SCHEMA = "kxm.gate-registry.v1";
 const REVISION_REQUIRED = ["config", "executorPolicy", "toolPolicy", "memory"] as const;
 const PROJECT_LIMIT_REQUIRED = ["maxConcurrentRuns"] as const;
-const PROJECT_LIMIT_OPTIONAL = ["maxRunDurationMs", "maxAgentTimeMs"] as const;
+const PROJECT_LIMIT_OPTIONAL = ["maxRunDurationMs", "maxAgentTimeMs", "agentStepTimeoutMs"] as const;
 const PLAN_REQUIRED = ["schema", "workflowId", "coordinator", "limits", "transitionBudget", "hasBackEdges", "entryStepId", "order", "steps", "requirePlanHash"] as const;
 const PLAN_OPTIONAL = ["sourcePath", "reproOracle", "planHash"] as const;
 const LIMIT_OPTIONAL = ["maxTransitions", "maxRunDurationMs", "maxAgentTimeMs", "maxModelCost", "currency"] as const;
@@ -85,6 +85,7 @@ export interface KxmRunPlanEnvelope {
     readonly maxConcurrentRuns: number;
     readonly maxRunDurationMs?: number;
     readonly maxAgentTimeMs?: number;
+    readonly agentStepTimeoutMs?: number;
   };
   readonly plan: KxmCompiledPlan;
   readonly gates: KxmPinnedGates;
@@ -252,6 +253,7 @@ function parseEnvelope(parsed: unknown, run: KxmRunRecord): KxmRunPlanEnvelope {
     maxConcurrentRuns: asCount(limitsValue.maxConcurrentRuns, run.runId, "projectLimits.maxConcurrentRuns"),
     ...(limitsValue.maxRunDurationMs !== undefined ? { maxRunDurationMs: asDuration(limitsValue.maxRunDurationMs, run.runId, "projectLimits.maxRunDurationMs") } : {}),
     ...(limitsValue.maxAgentTimeMs !== undefined ? { maxAgentTimeMs: asDuration(limitsValue.maxAgentTimeMs, run.runId, "projectLimits.maxAgentTimeMs") } : {}),
+    ...(limitsValue.agentStepTimeoutMs !== undefined ? { agentStepTimeoutMs: asAgentStepTimeout(limitsValue.agentStepTimeoutMs, run.runId, "projectLimits.agentStepTimeoutMs") } : {}),
   };
   const plan = freezeKxmCompiledPlan(parseCompiledPlan(value.plan, run.runId));
   return {
@@ -698,6 +700,13 @@ function asDuration(value: unknown, runId: string, label: string): number {
   return value;
 }
 
+function asAgentStepTimeout(value: unknown, runId: string, label: string): number {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 60_000) {
+    throw runtimeError("run_plan_corrupt", runId, `${label} is below 60000`);
+  }
+  return value;
+}
+
 function asCost(value: unknown, runId: string, label: string): number {
   if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
     throw runtimeError("run_plan_corrupt", runId, `${label} is not a positive cost`);

package/plugins/kxm/src/engine.ts

@@ -14,6 +14,7 @@ import {
 } from "./context-packet.ts";
 import { compileKxmWorkflow, type KxmCompiledPlan, type KxmCompiledStep } from "./engine-compile.ts";
 import { BUILTIN_HARNESSES, oneShotPermissionArgs, oneShotWriterArgs, validateHarnessModelPair } from "./harness.ts";
+import { readOneShotObservedChildExit } from "./oneshot-evidence.ts";
 import {
   effectiveRunDurationBudget,
   isTerminalRunStatus,
@@ -75,6 +76,7 @@ import {
   kxmIncrementMonotonicNs,
   kxmMonotonicNs,
   kxmPolicyRevisions,
+  KXM_DEFAULT_AGENT_STEP_TIMEOUT_MS,
   kxmProjectAdmissionLimits,
   type KxmMemoryRevisionOptions,
   type KxmRuntimeContext,
@@ -157,6 +159,8 @@ export interface KxmProducerRequest {
   readonly harness?: string | undefined;
   /** Live producers select an audited argv profile from this ceiling. */
   readonly permission?: "read-only" | "edit" | undefined;
+  /** Agent and moa steps only. Absent means the producer options, then the process default. */
+  readonly timeoutMs?: number | undefined;
   readonly contextPacket?: FormalContextPacketV2 | undefined;
   readonly handoffManifest?: HandoffManifestV1 | undefined;
 }
@@ -405,6 +409,10 @@ async function driveAdmitted(
     if (started.handoff || isTerminalRunStatus(started.state.status)) return started;
   }
   let latest: KxmRunDriveResult = { state: foldStoredKxmRun(context, requireRun(context, runId)) };
+  if (latest.state.status === "cancelling") {
+    latest = await stepLocked(context, runId, producer, token);
+    if (latest.handoff || isTerminalRunStatus(latest.state.status)) return latest;
+  }
   while (latest.state.status === "running") {
     const overBudget = cancelRunDurationIfExceeded(context, runId);
     if (overBudget) return overBudget;
@@ -487,6 +495,7 @@ function receiptHandoff(handoff: KxmRunHandoff): KxmDriveReceiptHandoff {
     detail: handoff.detail,
     ...(handoff.field !== undefined ? { field: handoff.field } : {}),
     ...(handoff.stepId !== undefined ? { stepId: handoff.stepId } : {}),
+    ...(handoff.attemptId !== undefined ? { attemptId: handoff.attemptId } : {}),
   };
 }
 
@@ -557,6 +566,9 @@ export function recordDriveReceipt(
       producer: { id: closeInfo.producerId, closed: closeInfo.producerClosed },
     };
     context.eventStore.insertDriveReceipt(receipt);
+    if (closeInfo.kind === "handoff") {
+      releaseKxmRun(context.eventStore.path, session.runId, session.token);
+    }
   } catch {
     // The drive result governs; a missing receipt is visible on poll.
   }
@@ -719,7 +731,7 @@ export class KxmRunScheduler {
     }
     try {
       const run = requireRun(this.context, runId);
-      if (isTerminalRunStatus(run.status) || run.status === "cancelling") {
+      if (isTerminalRunStatus(run.status)) {
         return Promise.reject(runtimeError("run_busy", runId, `run ${runId} is already ${run.status}`));
       }
     } catch (error) {
@@ -1441,6 +1453,74 @@ function resolveProducerRoute(
   return { provider, model, selector };
 }
 
+function projectAgentStepTimeoutMs(context: KxmRuntimeContext, run: KxmRunRecord): number {
+  return loadKxmRunPlanEnvelope(context.eventStore, run).projectLimits.agentStepTimeoutMs ?? KXM_DEFAULT_AGENT_STEP_TIMEOUT_MS;
+}
+
+function unsupportedAgentStepTimeout(step: KxmCompiledStep, limitMs: number): Omit<KxmRunHandoff, "stepId"> | undefined {
+  if (step.kind !== "agent" && step.kind !== "moa") return undefined;
+  if (step.timeoutMs === undefined || step.timeoutMs <= limitMs) return undefined;
+  return {
+    reason: "step_unsupported",
+    field: "timeoutMs",
+    detail: "step timeoutMs is wider than project limits.agentStepTimeoutMs",
+  };
+}
+
+function executingSingletonAttempt(
+  plan: KxmCompiledPlan,
+  state: KxmRunState,
+): { stepId: string; assignmentId: string; attemptId: string } | undefined {
+  const current = state.currentStep;
+  if (!current || current.panel.order.length !== 1) return undefined;
+  const step = plan.steps[current.stepId];
+  if (!step || (step.kind !== "agent" && step.kind !== "moa") || step.assignments.maximum > 1) return undefined;
+  const attemptId = unreconciledPanelAttemptId(state);
+  if (!attemptId) return undefined;
+  const located = kxmFoldPanelAttempt(current, attemptId);
+  if (located?.attempt.status !== "executing") return undefined;
+  return { stepId: current.stepId, assignmentId: located.assignmentId, attemptId };
+}
+
+function settleExitedExecutingAttempt(
+  context: KxmRuntimeContext,
+  run: KxmRunRecord,
+  executing: { stepId: string; assignmentId: string; attemptId: string },
+): KxmRunState {
+  const now = new Date().toISOString();
+  let sequence = context.eventStore.nextSequence(run.runId);
+  let mono = kxmMonotonicNs();
+  const events: KxmRunEvent[] = [];
+  const push = (eventType: string, payload: Record<string, unknown>): void => {
+    events.push({
+      ...kxmEventBase(context, run, now, mono),
+      eventId: newKxmEventId(),
+      eventType,
+      sequence: sequence++,
+      payload,
+    });
+    mono = kxmIncrementMonotonicNs(mono);
+  };
+  push("attempt.status_changed", { attemptId: executing.attemptId, status: "settling" });
+  push("assignment.result_recorded", {
+    assignmentId: executing.assignmentId,
+    resultClass: "producer_rejected",
+    status: "result_recorded",
+    producerError: "executing_unrecorded",
+    reason: "executing_unrecorded",
+  });
+  push("attempt.status_changed", { attemptId: executing.attemptId, status: "terminal" });
+  push("assignment.terminal", { assignmentId: executing.assignmentId, outcome: "failed", status: "terminal" });
+  push("step.status_changed", { stepId: executing.stepId, status: "cancelled", previousStatus: "running" });
+  push("run.status_changed", { status: "cancelled", reason: cancelReasonFromLog(context, run.runId) });
+  for (const event of events) context.eventStore.appendEvent(event);
+  context.eventStore.settleCapability(executing.attemptId, "settled");
+  const next = foldStoredKxmRun(context, run);
+  persistKxmRunState(context, run.runId, next, events[events.length - 1]!.sequence);
+  context.eventStore.updateRunStatus(run.runId, "cancelled", now);
+  return next;
+}
+
 function prepareDispatch(
   context: KxmRuntimeContext,
   runId: string,
@@ -1454,6 +1534,23 @@ function prepareDispatch(
     return { kind: "return", state };
   }
   if (state.status === "cancelling" && kxmAttemptControllers(context.eventStore.path, runId).length === 0) {
+    const executing = executingSingletonAttempt(plan, state);
+    if (executing) {
+      const exited = readOneShotObservedChildExit(runId, executing.attemptId);
+      if (exited === true) {
+        return { kind: "return", state: settleExitedExecutingAttempt(context, run, executing) };
+      }
+      return {
+        kind: "return",
+        state,
+        handoff: {
+          reason: "attempt_unreconciled",
+          stepId: executing.stepId,
+          attemptId: executing.attemptId,
+          detail: "issued attempt is not held by this process",
+        },
+      };
+    }
     return {
       kind: "return",
       state,
@@ -1585,6 +1682,8 @@ function prepareDispatch(
 
   const unsupported = unsupportedStep(plan, step, producerId);
   if (unsupported) return { kind: "return", state, handoff: { ...unsupported, stepId } };
+  const wideTimeout = unsupportedAgentStepTimeout(step, projectAgentStepTimeoutMs(context, run));
+  if (wideTimeout) return { kind: "return", state, handoff: { ...wideTimeout, stepId } };
 
   let resolvedRoute: { provider: string; model: string; selector: string } | undefined;
   if (producerId !== "driver-simulated") {
@@ -1838,6 +1937,9 @@ function birthMember(
       prompt: input.step.instructions ? `${input.step.instructions}\n\n${generatedPrompt}` : generatedPrompt,
       thinking: input.stepAttempt <= 1 ? "low" : "medium",
       permission: Object.values(input.step.repositories).some((access) => access === "write") ? "edit" : "read-only",
+      ...((input.step.kind === "agent" || input.step.kind === "moa") && input.step.timeoutMs !== undefined
+        ? { timeoutMs: input.step.timeoutMs }
+        : {}),
       contextPacket,
       ...(resolvedRoute ? { provider: resolvedRoute.provider, model: resolvedRoute.model } : {}),
     },
@@ -2716,9 +2818,10 @@ export function kxmLiveRunPrerequisites(
     for (const transition of Object.values(step.transitions)) {
       if (transition.to === "step") pending.push(transition.target);
     }
+    const limitMs = envelope.projectLimits.agentStepTimeoutMs ?? KXM_DEFAULT_AGENT_STEP_TIMEOUT_MS;
     const unsupported = step.kind === "gate"
       ? unsupportedGateStep(plan, step, envelope, { projectRoot }) ?? starterGatePrerequisite(step, envelope.gates, projectRoot)
-      : unsupportedStep(plan, step, "oneshot");
+      : unsupportedAgentStepTimeout(step, limitMs) ?? unsupportedStep(plan, step, "oneshot");
     if (unsupported) {
       prerequisites.push({ ...unsupported, stepId });
       continue;

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.123";
+const VERSION = "0.7.125";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();

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

@@ -1,6 +1,8 @@
 import { createHash, randomUUID } from "node:crypto";
+import { lstatSync, readdirSync, readFileSync } from "node:fs";
 import { lstat, mkdir, open, rename } from "node:fs/promises";
 import { join } from "node:path";
+import { kxmUserStateRoot } from "./bindings.ts";
 import type { KxmOneShotProcessResult } from "./oneshot-process.ts";
 
 export const ONESHOT_EVIDENCE_SCHEMA = "kxm.oneshot-evidence.v2" as const;
@@ -34,6 +36,46 @@ export function parseOneShotEvidenceRecord(bytes: string): OneShotEvidenceRecord
   return parsed as OneShotEvidenceRecord;
 }
 
+/** Where live one-shot spawns write `intent.json` and `result.json`. */
+export function oneShotEvidenceRoot(): string {
+  return join(kxmUserStateRoot(), "runtime", "oneshot-evidence");
+}
+
+/**
+ * Whether the one-shot evidence for this attempt says the direct child exited.
+ * Missing, unreadable, or unfinished evidence is `undefined` (do not settle).
+ * A recorded `false` stays `false`.
+ */
+export function readOneShotObservedChildExit(runId: string, attemptId: string, root = oneShotEvidenceRoot()): boolean | undefined {
+  let names: string[];
+  try {
+    names = readdirSync(root);
+  } catch {
+    return undefined;
+  }
+  let seenTrue = false;
+  let seenFalse = false;
+  const capped = names.slice(0, 4096);
+  for (const name of capped) {
+    if (!name.startsWith("evd_")) continue;
+    const dir = join(root, name);
+    try {
+      const info = lstatSync(dir);
+      if (!info.isDirectory() || info.isSymbolicLink()) continue;
+      const intent = parseOneShotEvidenceRecord(readFileSync(join(dir, "intent.json"), "utf8"));
+      if (intent.runId !== runId || intent.attemptId !== attemptId) continue;
+      const result = parseOneShotEvidenceRecord(readFileSync(join(dir, "result.json"), "utf8"));
+      if (result.observedChildExit === true) seenTrue = true;
+      else if (result.observedChildExit === false) seenFalse = true;
+    } catch {
+      // An unreadable or unfinished record is not evidence that the child exited.
+    }
+  }
+  if (seenFalse) return false;
+  if (seenTrue) return true;
+  return undefined;
+}
+
 /** 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.
@@ -42,6 +84,7 @@ export async function beginOneShotEvidence(root: string, intent: {
   runId: string; stepId: string; attemptId: string; assignmentId: string;
   harness: string; provider: string; model: string; cwd: string;
   command: string; args: readonly string[]; input?: string | undefined;
+  timeoutMs?: number | undefined;
 }, sensitive: readonly string[]): Promise<{
   id: string;
   finish(result: KxmOneShotProcessResult, observation: unknown): Promise<string>;
@@ -92,6 +135,7 @@ export async function beginOneShotEvidence(root: string, intent: {
     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,
+    ...(intent.timeoutMs !== undefined ? { timeoutMs: intent.timeoutMs } : {}),
     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,

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

@@ -1,6 +1,4 @@
-import { join } from "node:path";
-import { beginOneShotEvidence } from "./oneshot-evidence.ts";
-import { kxmUserStateRoot } from "./bindings.ts";
+import { beginOneShotEvidence, oneShotEvidenceRoot } from "./oneshot-evidence.ts";
 import { defaultSpawn, type KxmOneShotProcessResult, type KxmOneShotSpawn } from "./oneshot-process.ts";
 export { defaultSpawn, type KxmOneShotProcessResult, type KxmOneShotSpawn } from "./oneshot-process.ts";
 import {
@@ -260,15 +258,17 @@ export function createKxmOneShotProducer(options: KxmOneShotProducerOptions = {}
 
       const spawnFn = options.spawnProcess ?? defaultSpawn;
       const cwd = options.projectRoot ?? process.cwd();
-      const evidence = await beginOneShotEvidence(options.evidenceRoot ?? join(kxmUserStateRoot(), "runtime", "oneshot-evidence"), {
+      const timeoutMs = request.timeoutMs ?? options.timeoutMs;
+      const evidence = await beginOneShotEvidence(options.evidenceRoot ?? oneShotEvidenceRoot(), {
         runId: request.runId, stepId: request.stepId, attemptId: request.attemptId, assignmentId: request.assignmentId,
         harness, provider: resolved.provider, model: resolved.model, cwd, command, args, input,
+        timeoutMs: timeoutMs ?? 120_000,
       }, [request.capability, ...Object.entries(env).filter(([key]) => /TOKEN|KEY|SECRET|PASSWORD|COOKIE|AUTH/i.test(key)).map(([, value]) => value ?? "")]);
       let procResult: KxmOneShotProcessResult;
       try {
         procResult = request.signal.aborted
           ? { stdout: "", stderr: "", code: null, started: false, observedChildExit: false, error: new Error("process_aborted") }
-          : await spawnFn(command, args, { cwd, env, input, timeoutMs: options.timeoutMs ?? 120_000, signal: request.signal });
+          : await spawnFn(command, args, { cwd, env, input, timeoutMs, signal: request.signal });
       } catch (error) {
         // A rejected adapter promise is not proof that no process/effect started.
         procResult = { stdout: "", stderr: "", code: null, observedChildExit: false, error: error instanceof Error ? error : new Error("process_adapter_error") };

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

@@ -195,19 +195,29 @@ export function kxmDeclaredExecutorIds(bundle: KxmProjectBundle): string[] {
   ].filter((value): value is string => value !== undefined))].sort();
 }
 
+/** Wall-clock bound for one live agent or moa step when the step omits `timeoutMs`. */
+export const KXM_DEFAULT_AGENT_STEP_TIMEOUT_MS = 3_600_000;
+export const KXM_MIN_AGENT_STEP_TIMEOUT_MS = 60_000;
+
 export function kxmProjectAdmissionLimits(bundle: KxmProjectBundle): {
   maxConcurrentRuns: number;
   maxRunDurationMs?: number;
   maxAgentTimeMs?: number;
+  agentStepTimeoutMs: number;
 } {
   const limits = objectValue(bundle.project.value.limits);
   const maxConcurrentRuns = typeof limits?.maxConcurrentRuns === "number" && Number.isInteger(limits.maxConcurrentRuns) && limits.maxConcurrentRuns >= 1
     ? limits.maxConcurrentRuns
     : 1;
+  const declared = limits?.agentStepTimeoutMs;
+  const agentStepTimeoutMs = typeof declared === "number" && Number.isInteger(declared) && declared >= KXM_MIN_AGENT_STEP_TIMEOUT_MS
+    ? declared
+    : KXM_DEFAULT_AGENT_STEP_TIMEOUT_MS;
   return {
     maxConcurrentRuns,
     ...(typeof limits?.maxRunDurationMs === "number" ? { maxRunDurationMs: limits.maxRunDurationMs } : {}),
     ...(typeof limits?.maxAgentTimeMs === "number" ? { maxAgentTimeMs: limits.maxAgentTimeMs } : {}),
+    agentStepTimeoutMs,
   };
 }
 

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

@@ -371,6 +371,7 @@ export interface KxmDriveReceiptHandoff {
   reason: string;
   field?: string;
   stepId?: string;
+  attemptId?: string;
   detail: string;
 }
 

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

@@ -23,6 +23,7 @@ import {
   closeKxmRuntimeContext,
   foldStoredKxmRun,
   openKxmRuntimeContext,
+  kxmProjectAdmissionLimits,
   projectKxmRunReadOnly,
   type KxmRuntimeContext,
 } from "./runtime-service.ts";
@@ -836,6 +837,7 @@ async function startKxmRuntimeSupervisorInner(
             const createProducer = () => body.mode === "live"
               ? createKxmOneShotProducer({
                   projectRoot,
+                  timeoutMs: kxmProjectAdmissionLimits(bundle).agentStepTimeoutMs,
                   defaultHarness: String(bundle.project.value.defaultHarness ?? "pi"),
                   resolveHarness: (agentId) => {
                     const agent = bundle.agents.get(agentId);

package/schemas/drive-receipt.schema.json

@@ -87,6 +87,7 @@
         "reason": { "type": "string", "minLength": 1, "maxLength": 80 },
         "field": { "type": "string", "minLength": 1, "maxLength": 128 },
         "stepId": { "$ref": "common.schema.json#/$defs/identifier" },
+        "attemptId": { "$ref": "common.schema.json#/$defs/opaqueId" },
         "detail": { "type": "string", "minLength": 1, "maxLength": 4000 }
       },
       "additionalProperties": false

package/schemas/project.schema.json

@@ -76,7 +76,8 @@
       "properties": {
         "maxConcurrentRuns": { "type": "integer", "minimum": 1, "maximum": 128 },
         "maxRunDurationMs": { "$ref": "common.schema.json#/$defs/durationMs" },
-        "maxAgentTimeMs": { "$ref": "common.schema.json#/$defs/durationMs" }
+        "maxAgentTimeMs": { "$ref": "common.schema.json#/$defs/durationMs" },
+        "agentStepTimeoutMs": { "type": "integer", "minimum": 60000, "maximum": 31536000000 }
       },
       "additionalProperties": false
     }