@kontextmind/kxm 0.7.97 → 0.7.99

package/plugins/kxm/src/database.ts

@@ -12,6 +12,7 @@ import {
 } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { DatabaseSync } from "./sqlite.ts";
+import { kxmUserStateRoot } from "./bindings.ts";
 import { KxmConfigError, type KxmConfigIssue } from "./project-config.ts";
 
 export interface DatabaseSchemaSpec {
@@ -31,12 +32,24 @@ export interface BackupStoreRecord {
   integrity: "ok";
 }
 
+export interface BackupFileRecord {
+  id: string;
+  sourcePath: string;
+  backupFile: string;
+  sha256: string;
+  bytes: number;
+}
+
 export interface BackupManifest {
   schema: "kxm.backup-manifest.v1";
   backupId: string;
   createdAt: string;
   projectRoot?: string;
   stores: BackupStoreRecord[];
+  files?: BackupFileRecord[];
+  /** False when a discovered store or prompt sidecar was left out. Absent on legacy manifests. */
+  complete?: boolean;
+  omitted?: string[];
   manifestSha256?: string;
 }
 
@@ -607,46 +620,136 @@ export const KXM_BACKUP_CEILINGS = {
 } as const;
 
 export function kxmBackupCeiling(storeId: string): number {
+  if (storeId === "runtime-registry") return KXM_BACKUP_CEILINGS.registry;
   if (storeId.startsWith("events:")) return KXM_BACKUP_CEILINGS.events;
   // An id this build does not know keeps the ceiling restore has always defaulted to.
   return KXM_BACKUP_CEILINGS[storeId as keyof typeof KXM_BACKUP_CEILINGS] ?? KXM_BACKUP_CEILINGS["hub-store"];
 }
 
-export function discoverProjectStores(projectRoot: string, options: { hubDataPath?: string } = {}): Array<{ storeId: string; sourcePath: string; maxSupportedVersion: number }> {
+interface DiscoveredStore {
+  storeId: string;
+  sourcePath: string;
+  maxSupportedVersion: number;
+}
+
+interface DiscoveredFile {
+  id: string;
+  sourcePath: string;
+}
+
+function pushStore(stores: DiscoveredStore[], storeId: string, sourcePath: string): void {
+  if (stores.some((store) => store.storeId === storeId || store.sourcePath === sourcePath)) return;
+  stores.push({ storeId, sourcePath, maxSupportedVersion: kxmBackupCeiling(storeId) });
+}
+
+function discoverUserRuntime(env: NodeJS.ProcessEnv | undefined, stores: DiscoveredStore[], files: DiscoveredFile[]): void {
+  let stateRoot: string;
+  try {
+    stateRoot = kxmUserStateRoot(env ? { env } : {});
+  } catch {
+    return;
+  }
+  const runtimeDir = join(stateRoot, "runtime");
+  const registryPath = join(runtimeDir, "registry.db");
+  if (existsSync(registryPath)) {
+    const storeId = stores.some((store) => store.storeId === "registry") ? "runtime-registry" : "registry";
+    pushStore(stores, storeId, registryPath);
+  }
+  const projectsDir = join(runtimeDir, "projects");
+  if (!existsSync(projectsDir)) return;
+  let entries;
+  try {
+    entries = readdirSync(projectsDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const dbPath = join(projectsDir, entry.name, "run-events.db");
+    if (!existsSync(dbPath)) continue;
+    const safe = entry.name.replace(/[^a-zA-Z0-9_.-]/g, "_");
+    let storeId = `events:${safe}`;
+    if (stores.some((store) => store.storeId === storeId)) storeId = `events:runtime:${safe}`;
+    pushStore(stores, storeId, dbPath);
+    const sidecar = `${dbPath}.run-prompts.json`;
+    if (existsSync(sidecar)) {
+      const id = `${storeId}:run-prompts`;
+      if (!files.some((file) => file.id === id || file.sourcePath === sidecar)) {
+        files.push({ id, sourcePath: sidecar });
+      }
+    }
+  }
+}
+
+function discoverBackupSources(
+  projectRoot: string,
+  options: { hubDataPath?: string; env?: NodeJS.ProcessEnv } = {},
+): { stores: DiscoveredStore[]; files: DiscoveredFile[] } {
   const root = resolve(projectRoot);
-  const stores: Array<{ storeId: string; sourcePath: string; maxSupportedVersion: number }> = [];
+  const stores: DiscoveredStore[] = [];
+  const files: DiscoveredFile[] = [];
 
   const hubPath = options.hubDataPath ? resolve(options.hubDataPath) : join(root, ".kxm", "state", "kxm.db");
-  if (existsSync(hubPath)) {
-    stores.push({ storeId: "hub-store", sourcePath: hubPath, maxSupportedVersion: kxmBackupCeiling("hub-store") });
-  }
+  if (existsSync(hubPath)) pushStore(stores, "hub-store", hubPath);
 
   const registryPath = join(root, ".kxm", "runtime", "registry.db");
-  if (existsSync(registryPath)) {
-    stores.push({ storeId: "registry", sourcePath: registryPath, maxSupportedVersion: kxmBackupCeiling("registry") });
-  }
+  if (existsSync(registryPath)) pushStore(stores, "registry", registryPath);
 
   const bindingsPath = join(root, ".kxm", "runtime", "bindings.db");
-  if (existsSync(bindingsPath)) {
-    stores.push({ storeId: "binding-store", sourcePath: bindingsPath, maxSupportedVersion: kxmBackupCeiling("binding-store") });
-  }
+  if (existsSync(bindingsPath)) pushStore(stores, "binding-store", bindingsPath);
 
   const eventsDir = join(root, ".kxm", "runtime", "events");
   if (existsSync(eventsDir)) {
     const entries = readdirSync(eventsDir, { withFileTypes: true });
     for (const entry of entries) {
       if (entry.isFile() && entry.name.endsWith(".db")) {
-        const key = entry.name.replace(/\.db$/, "");
-        stores.push({
-          storeId: `events:${key}`,
-          sourcePath: join(eventsDir, entry.name),
-          maxSupportedVersion: kxmBackupCeiling(`events:${key}`),
-        });
+        const key = entry.name.replace(/\.db$/, "").replace(/[^a-zA-Z0-9_.-]/g, "_");
+        pushStore(stores, `events:${key}`, join(eventsDir, entry.name));
       }
     }
   }
 
-  return stores;
+  discoverUserRuntime(options.env, stores, files);
+  return { stores, files };
+}
+
+function backupPlainFile(sourcePath: string, targetPath: string, id: string): BackupFileRecord {
+  const resolvedSource = resolve(sourcePath);
+  const sourceStat = lstatSync(resolvedSource, { throwIfNoEntry: false });
+  if (!sourceStat || !sourceStat.isFile() || sourceStat.isSymbolicLink()) {
+    throw databaseError("runtime_path_invalid", resolvedSource, `backup file ${resolvedSource} must be a regular file, not a link or directory`);
+  }
+  checkedParent(targetPath, "backup target");
+  if (existsSync(targetPath)) unlinkSync(targetPath);
+  copyFileSync(resolvedSource, targetPath);
+  try { chmodSync(targetPath, 0o600); } catch { /* Windows */ }
+  return {
+    id,
+    sourcePath: resolvedSource,
+    backupFile: basename(targetPath),
+    sha256: fileSha256(targetPath),
+    bytes: sourceStat.size,
+  };
+}
+
+function backupFilename(sourcePath: string, id: string, used: Set<string>): string {
+  let filename = basename(sourcePath);
+  if (used.has(filename)) {
+    filename = `${id.replace(/[^a-zA-Z0-9_.-]/g, "_")}-${filename}`;
+  }
+  used.add(filename);
+  return filename;
+}
+
+function restorePlainFile(backupFilePath: string, targetPath: string): void {
+  checkedParent(targetPath, "restore target");
+  if (existsSync(targetPath)) unlinkSync(targetPath);
+  copyFileSync(backupFilePath, targetPath);
+  try { chmodSync(targetPath, 0o600); } catch { /* Windows */ }
+}
+
+export function discoverProjectStores(projectRoot: string, options: { hubDataPath?: string; env?: NodeJS.ProcessEnv } = {}): Array<{ storeId: string; sourcePath: string; maxSupportedVersion: number }> {
+  return discoverBackupSources(projectRoot, options).stores;
 }
 
 export interface BackupPlan {
@@ -654,21 +757,28 @@ export interface BackupPlan {
   outDir: string;
   createdAt: string;
   stores: Array<{ storeId: string; sourcePath: string; backupFile: string }>;
+  files: Array<{ id: string; sourcePath: string; backupFile: string }>;
+}
+
+function backupDiscoverOptions(options: { hubDataPath?: string; env?: NodeJS.ProcessEnv }): { hubDataPath?: string; env?: NodeJS.ProcessEnv } {
+  return {
+    ...(options.hubDataPath !== undefined ? { hubDataPath: options.hubDataPath } : {}),
+    ...(options.env !== undefined ? { env: options.env } : {}),
+  };
 }
 
-/** Which stores a backup would copy and where, without opening any of them.
+/** Which stores and files a backup would copy and where, without opening any of them.
  * Opening a source for backup checkpoints its WAL, so the plan stays at paths. */
 export function planBackup(options: {
   projectRoot?: string;
   outDir?: string;
   hubDataPath?: string;
+  env?: NodeJS.ProcessEnv;
 } = {}): BackupPlan {
   const projectRoot = options.projectRoot ? resolve(options.projectRoot) : process.cwd();
-  const stores = discoverProjectStores(projectRoot, {
-    ...(options.hubDataPath !== undefined ? { hubDataPath: options.hubDataPath } : {}),
-  });
+  const discovered = discoverBackupSources(projectRoot, backupDiscoverOptions(options));
 
-  if (stores.length === 0) {
+  if (discovered.stores.length === 0) {
     throw databaseError("backup_no_stores", projectRoot, "no existing SQLite stores found to backup");
   }
 
@@ -676,24 +786,26 @@ export function planBackup(options: {
   const timestamp = createdAt.replace(/[:.]/g, "-");
   const outDir = options.outDir ? resolve(options.outDir) : join(projectRoot, ".kxm", "backups", `backup-${timestamp}`);
   const usedFilenames = new Set<string>();
-  const planned = stores.map((store) => {
-    let filename = basename(store.sourcePath);
-    if (usedFilenames.has(filename)) {
-      const sanitizedId = store.storeId.replace(/[^a-zA-Z0-9_.-]/g, "_");
-      filename = `${sanitizedId}-${filename}`;
-    }
-    usedFilenames.add(filename);
-    return { storeId: store.storeId, sourcePath: store.sourcePath, backupFile: filename };
-  });
-  return { projectRoot, outDir, createdAt, stores: planned };
+  const stores = discovered.stores.map((store) => ({
+    storeId: store.storeId,
+    sourcePath: store.sourcePath,
+    backupFile: backupFilename(store.sourcePath, store.storeId, usedFilenames),
+  }));
+  const files = discovered.files.map((file) => ({
+    id: file.id,
+    sourcePath: file.sourcePath,
+    backupFile: backupFilename(file.sourcePath, file.id, usedFilenames),
+  }));
+  return { projectRoot, outDir, createdAt, stores, files };
 }
 
 export function createBackup(options: {
   projectRoot?: string;
   outDir?: string;
   hubDataPath?: string;
+  env?: NodeJS.ProcessEnv;
 } = {}): { manifest: BackupManifest; outDir: string } {
-  const { projectRoot, outDir, createdAt, stores } = planBackup(options);
+  const { projectRoot, outDir, createdAt, stores, files } = planBackup(options);
   const backupId = `bk_${randomBytes(8).toString("hex")}`;
 
   if (!existsSync(outDir)) {
@@ -701,8 +813,38 @@ export function createBackup(options: {
   }
 
   const backedUpStores: BackupStoreRecord[] = [];
+  const backedUpFiles: BackupFileRecord[] = [];
+  const omitted: string[] = [];
+
   for (const store of stores) {
-    backedUpStores.push(backupDatabaseFile(store.sourcePath, join(outDir, store.backupFile), store.storeId));
+    try {
+      backedUpStores.push(backupDatabaseFile(store.sourcePath, join(outDir, store.backupFile), store.storeId));
+    } catch {
+      omitted.push(store.storeId);
+    }
+  }
+  for (const file of files) {
+    try {
+      backedUpFiles.push(backupPlainFile(file.sourcePath, join(outDir, file.backupFile), file.id));
+    } catch {
+      omitted.push(file.id);
+    }
+  }
+
+  if (backedUpStores.length === 0) {
+    throw databaseError("backup_no_stores", projectRoot, "no SQLite store could be copied");
+  }
+
+  const again = discoverBackupSources(projectRoot, backupDiscoverOptions(options));
+  for (const store of again.stores) {
+    if (!backedUpStores.some((copied) => copied.storeId === store.storeId) && !omitted.includes(store.storeId)) {
+      omitted.push(store.storeId);
+    }
+  }
+  for (const file of again.files) {
+    if (!backedUpFiles.some((copied) => copied.id === file.id) && !omitted.includes(file.id)) {
+      omitted.push(file.id);
+    }
   }
 
   const manifest: BackupManifest = {
@@ -711,6 +853,9 @@ export function createBackup(options: {
     createdAt,
     projectRoot,
     stores: backedUpStores,
+    ...(backedUpFiles.length > 0 ? { files: backedUpFiles } : {}),
+    complete: omitted.length === 0,
+    ...(omitted.length > 0 ? { omitted } : {}),
   };
 
   const manifestJson = JSON.stringify(manifest, null, 2) + "\n";
@@ -728,6 +873,7 @@ export interface RestorePlan {
   manifestPath: string;
   backupId: string;
   stores: Array<{ storeId: string; backupFilePath: string; targetPath: string; schemaVersion: number; maxSupportedVersion: number }>;
+  files: Array<{ id: string; backupFilePath: string; targetPath: string }>;
 }
 
 /** Everything restore checks before it overwrites anything: the manifest, each
@@ -762,6 +908,9 @@ export function planRestore(
   if (manifest.schema !== "kxm.backup-manifest.v1" || !Array.isArray(manifest.stores) || manifest.stores.length === 0) {
     throw databaseError("restore_manifest_invalid", manifestPath, "manifest is not a valid kxm.backup-manifest.v1 document");
   }
+  if (manifest.complete === false) {
+    throw databaseError("restore_incomplete", manifestPath, "backup manifest is incomplete; refusing to restore a partial copy");
+  }
 
   const stores: RestorePlan["stores"] = [];
   for (const store of manifest.stores) {
@@ -796,7 +945,29 @@ export function planRestore(
     stores.push({ storeId: store.storeId, backupFilePath, targetPath, schemaVersion: store.schemaVersion, maxSupportedVersion });
   }
 
-  return { manifestPath, backupId: manifest.backupId, stores };
+  const files: RestorePlan["files"] = [];
+  for (const file of manifest.files ?? []) {
+    const backupFilePath = join(manifestDir, file.backupFile);
+    if (!existsSync(backupFilePath)) {
+      throw databaseError("restore_file_missing", backupFilePath, `backup file ${file.backupFile} missing from ${manifestDir}`);
+    }
+    const actualSha256 = fileSha256(backupFilePath);
+    if (actualSha256 !== file.sha256) {
+      throw databaseError(
+        "restore_manifest_digest_mismatch",
+        backupFilePath,
+        `backup file ${file.backupFile} sha256 ${actualSha256} does not match manifest hash ${file.sha256}`,
+      );
+    }
+    let targetPath = file.sourcePath;
+    if (options.projectRoot && manifest.projectRoot && targetPath.startsWith(manifest.projectRoot)) {
+      const rel = targetPath.slice(manifest.projectRoot.length).replace(/^[\\/]+/, "");
+      targetPath = join(resolve(options.projectRoot), rel);
+    }
+    files.push({ id: file.id, backupFilePath, targetPath });
+  }
+
+  return { manifestPath, backupId: manifest.backupId, stores, files };
 }
 
 export function restoreBackup(
@@ -811,6 +982,9 @@ export function restoreBackup(
     store.schemaVersion,
     store.maxSupportedVersion,
   ));
+  for (const file of plan.files) {
+    restorePlainFile(file.backupFilePath, file.targetPath);
+  }
   return {
     manifestPath: plan.manifestPath,
     backupId: plan.backupId,

package/plugins/kxm/src/engine.ts

@@ -3,6 +3,8 @@ 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,
   buildHandoffManifest,
@@ -153,6 +155,8 @@ export interface KxmProducerRequest {
   readonly thinking?: string | undefined;
   readonly agentRole?: string | undefined;
   readonly harness?: string | undefined;
+  /** Live producers select an audited argv profile from this ceiling. */
+  readonly permission?: "read-only" | "edit" | undefined;
   readonly contextPacket?: FormalContextPacketV2 | undefined;
   readonly handoffManifest?: HandoffManifestV1 | undefined;
 }
@@ -1593,6 +1597,14 @@ function prepareDispatch(
       return { kind: "return", state, handoff: { ...routeResult.error, stepId } };
     }
     resolvedRoute = routeResult;
+    const writeRefusal = unsupportedLiveWrite(
+      context.projectRoot,
+      step,
+      agentId,
+      resolvedRoute.selector,
+      loadKxmRunPlanEnvelope(context.eventStore, run).projectLimits.maxConcurrentRuns,
+    );
+    if (writeRefusal) return { kind: "return", state, handoff: { ...writeRefusal, stepId } };
   }
 
   const used = state.stepAttempts[stepId] ?? 0;
@@ -1825,6 +1837,7 @@ function birthMember(
       signal: controller.signal,
       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",
       contextPacket,
       ...(resolvedRoute ? { provider: resolvedRoute.provider, model: resolvedRoute.model } : {}),
     },
@@ -1998,7 +2011,18 @@ async function drivePanel(
         if (!executingBound()) return { attemptId: member.attemptId, invoked: false, skipped: true };
         kxmPanelDispatchSeams.beforeInvoke?.(member);
         if (!executingBound()) return { attemptId: member.attemptId, invoked: false, skipped: true };
+        const live = member.producerId !== "driver-simulated";
+        const writes = Object.values(member.step.repositories).some((access) => access === "write");
+        const before = live ? captureWorktreeWitness(context.projectRoot) : undefined;
         const produced = await invokeProducer(producer, member.request);
+        if (live && produced.result && before) {
+          const after = captureWorktreeWitness(context.projectRoot);
+          return {
+            attemptId: member.attemptId,
+            invoked: true,
+            produced: { ...produced, result: applyAuthoringWitness(produced.result, { writes, before, after }) },
+          };
+        }
         return { attemptId: member.attemptId, invoked: true, produced };
       } catch (error) {
         member.controller.abort();
@@ -2722,11 +2746,102 @@ function unsupportedStep(
       return { reason: "step_unsupported", field: "repositories", detail: `invalid repository access '${access}' on ${repoId}` };
     }
   }
-  if (producerId !== "driver-simulated" && Object.values(step.repositories).some((access) => access === "write")) {
+  return undefined;
+}
+
+function readYamlRecord(path: string): Record<string, unknown> | undefined {
+  if (!existsSync(path)) return undefined;
+  try {
+    const parsed = parse(readFileSync(path, "utf8")) as unknown;
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+function agentHarness(projectRoot: string, agentId: string): string | undefined {
+  const harness = readYamlRecord(join(projectRoot, ".kxm", "agents", `${agentId}.yaml`))?.harness;
+  return typeof harness === "string" && harness.length > 0 ? harness : undefined;
+}
+
+function projectDefaultHarness(projectRoot: string): string {
+  const harness = readYamlRecord(join(projectRoot, ".kxm", "project.yaml"))?.defaultHarness;
+  return typeof harness === "string" && harness.length > 0 ? harness : "pi";
+}
+
+/**
+ * Live write steps run only on an audited writer profile, and only when the
+ * developer roster (when present) lists that harness and model as an edit writer.
+ * A missing roster is a fresh project: route admission is the other gate.
+ *
+ * The authoring witness fingerprints the one project checkout around each
+ * spawn, so it can only attribute a change to a lone writer. A write step with
+ * more than one assignment would run several writers there (and member n runs
+ * as allowedAgents[n], which the writer check below never sees), and a
+ * project that admits concurrent runs lets another run's writer edit the tree
+ * mid-attempt. Both hand off.
+ */
+function unsupportedLiveWrite(
+  projectRoot: string,
+  step: KxmCompiledStep,
+  agentId: string,
+  selector: string,
+  maxConcurrentRuns: number,
+): Omit<KxmRunHandoff, "stepId"> | undefined {
+  if (!Object.values(step.repositories).some((access) => access === "write")) return undefined;
+  if (step.assignments.maximum !== 1) {
+    return {
+      reason: "step_unsupported",
+      field: "assignments.maximum",
+      detail: "live write steps run a single assignment; the checkout witness cannot attribute edits between writers",
+    };
+  }
+  if (maxConcurrentRuns !== 1) {
+    return {
+      reason: "step_unsupported",
+      field: "limits.maxConcurrentRuns",
+      detail: "live write steps require limits.maxConcurrentRuns of 1; concurrent runs share one checkout",
+    };
+  }
+  const harness = agentHarness(projectRoot, agentId) ?? projectDefaultHarness(projectRoot);
+  if (!oneShotWriterArgs(harness)) {
     return {
       reason: "step_unsupported",
       field: "repositories",
-      detail: "live write steps are unsupported until writer sandboxing witness passes",
+      detail: `live write steps require an audited writer profile; ${harness} has none`,
+    };
+  }
+  const rosterPath = join(projectRoot, ".kxm", "roster.yaml");
+  if (!existsSync(rosterPath)) return undefined;
+  const roster = readYamlRecord(rosterPath);
+  if (!roster || roster.schema !== "kxm.developer-roster.v1") {
+    return { reason: "step_unsupported", field: "model", detail: "live write steps require a readable kxm.developer-roster.v1" };
+  }
+  const routes = roster.routes;
+  const lineup = roster.lineup;
+  const writerIds = lineup && typeof lineup === "object" && !Array.isArray(lineup)
+    ? (lineup as Record<string, unknown>).writer
+    : undefined;
+  if (!routes || typeof routes !== "object" || Array.isArray(routes) || !Array.isArray(writerIds)) {
+    return { reason: "step_unsupported", field: "model", detail: "developer roster has no writer lineup" };
+  }
+  const allowed = writerIds.some((id) => {
+    if (typeof id !== "string") return false;
+    const route = (routes as Record<string, unknown>)[id];
+    if (!route || typeof route !== "object" || Array.isArray(route)) return false;
+    const record = route as Record<string, unknown>;
+    if (record.harness !== harness || record.status !== "admitted") return false;
+    if (!Array.isArray(record.permissions) || !record.permissions.includes("edit")) return false;
+    const model = typeof record.model === "string" ? record.model : "";
+    const vendor = typeof record.vendor === "string" ? record.vendor : "";
+    return model === selector || (vendor.length > 0 && `${vendor}/${model}` === selector);
+  });
+  if (!allowed) {
+    return {
+      reason: "step_unsupported",
+      field: "model",
+      detail: `live write route ${selector} on ${harness} is not on the developer roster writer lineup`,
     };
   }
   return undefined;

package/plugins/kxm/src/extension.ts

@@ -898,6 +898,7 @@ export default function piMeshExtension(pi: ExtensionAPI): void | Promise<void>
           throw new Error(`tool_policy_denied: ${policy.detail ?? policy.error}`);
         }
         // A request sent while handling the active inbound request continues its hop chain.
+        // No inbox and no hubInbox: `pending` owns activation, so kxm_inbox refuses here.
         const handling = activeInbound ? [activeInbound] : [];
         return result(
           await workflowCall(() =>

package/plugins/kxm/src/harness.ts

@@ -518,6 +518,35 @@ export function oneShotReadOnlyArgs(harness: string): readonly string[] | undefi
   return Object.hasOwn(READ_ONLY_ONESHOT_ARGS, harness) ? READ_ONLY_ONESHOT_ARGS[harness as keyof typeof READ_ONLY_ONESHOT_ARGS] : undefined;
 }
 
+/**
+ * Audited edit profiles. These are a writer containment, not read-only flags
+ * with the sandbox removed. They match the assignment helper
+ * (`scripts/harness-run.mjs` `buildArgv` for `permission: "edit"` with hooks
+ * and skills refused):
+ *
+ * - Pi: `-a` auto-approves tools so the process can edit the checkout, while
+ *   extensions, skills, prompt templates, and session persistence stay off.
+ *   `--no-tools` is the read-only profile and is not used here.
+ * - Grok: `--always-approve` so edits are not an interactive prompt, with
+ *   subagents and web search disabled. Grok has no audited read-only edit
+ *   mix; the read-only one-shot flags stay on the read-only profile.
+ *
+ * Claude, Codex, agy, and Kimi stay read-only. A live write step on a harness
+ * without an entry here hands off instead of spawning unconstrained.
+ */
+const WRITER_ONESHOT_ARGS = Object.freeze({
+  pi: Object.freeze(["-a", "--no-extensions", "--no-skills", "--no-prompt-templates", "--no-session"]),
+  grok: Object.freeze(["--always-approve", "--no-subagents", "--disable-web-search"]),
+});
+
+export function oneShotWriterArgs(harness: string): readonly string[] | undefined {
+  return Object.hasOwn(WRITER_ONESHOT_ARGS, harness) ? WRITER_ONESHOT_ARGS[harness as keyof typeof WRITER_ONESHOT_ARGS] : undefined;
+}
+
+export function oneShotPermissionArgs(harness: string, permission: "read-only" | "edit"): readonly string[] | undefined {
+  return permission === "edit" ? oneShotWriterArgs(harness) : oneShotReadOnlyArgs(harness);
+}
+
 export const BUILTIN_HARNESSES: readonly HarnessCatalogEntry[] = Object.freeze([
   {
     id: "pi",

package/plugins/kxm/src/hub.ts

@@ -2520,6 +2520,18 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
         return;
       }
 
+      // An agent's open inbound requests, queued or delivered, in delivery order. A read
+      // for a caller that holds no event-fed inbox of its own (a one-shot CLI call): it
+      // acknowledges nothing and moves no cursor, so push delivery is unchanged.
+      const inboxMatch = url.pathname.match(/^\/v1\/agents\/([^/]+)\/inbox$/);
+      if (method === "GET" && inboxMatch) {
+        const current = requireAgent(request, decodeURIComponent(inboxMatch[1]!));
+        requireProjectAuth(request, current.project);
+        expireMessages();
+        json(response, 200, { messages: store.getPendingMessages(current.id) });
+        return;
+      }
+
       const agentMatch = url.pathname.match(/^\/v1\/agents\/([^/]+)$/);
       if (method === "DELETE" && agentMatch) {
         const current = requireAgent(request, decodeURIComponent(agentMatch[1]!));