@kontextmind/kxm 0.7.5 → 0.7.7

package/plugins/kxm/dist/runtime.js

@@ -2986,7 +2986,7 @@ var require_compile = __commonJS({
       const schOrFunc = root.refs[ref];
       if (schOrFunc)
         return schOrFunc;
-      let _sch = resolve8.call(this, root, ref);
+      let _sch = resolve9.call(this, root, ref);
       if (_sch === void 0) {
         const schema = (_a = root.localRefs) === null || _a === void 0 ? void 0 : _a[ref];
         const { schemaId } = this.opts;
@@ -3013,7 +3013,7 @@ var require_compile = __commonJS({
     function sameSchemaEnv(s1, s2) {
       return s1.schema === s2.schema && s1.root === s2.root && s1.baseId === s2.baseId;
     }
-    function resolve8(root, ref) {
+    function resolve9(root, ref) {
       let sch;
       while (typeof (sch = this.refs[ref]) == "string")
         ref = sch;
@@ -3834,11 +3834,11 @@ var require_fast_uri = __commonJS({
         normalizeString(uri, options);
       } else if (typeof uri === "object") {
         uri = /** @type {T} */
-        parse5(serialize(uri, options), options);
+        parse6(serialize(uri, options), options);
       }
       return uri;
     }
-    function resolve8(baseURI, relativeURI, options) {
+    function resolve9(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
       const {
         parsed: baseParsed,
@@ -3874,8 +3874,8 @@ var require_fast_uri = __commonJS({
     function resolveComponent(base, relative5, options, skipNormalization) {
       const target = {};
       if (!skipNormalization) {
-        base = parse5(serialize(base, options), options);
-        relative5 = parse5(serialize(relative5, options), options);
+        base = parse6(serialize(base, options), options);
+        relative5 = parse6(serialize(relative5, options), options);
       }
       options = options || {};
       if (!options.tolerant && relative5.scheme) {
@@ -4167,7 +4167,7 @@ var require_fast_uri = __commonJS({
       }
       return { parsed, malformedAuthorityOrPort, malformedPercentEncoding, malformedSchemeSpecific, malformedHost, malformedScheme };
     }
-    function parse5(uri, opts) {
+    function parse6(uri, opts) {
       return parseWithStatus(uri, opts).parsed;
     }
     function normalizeString(uri, opts) {
@@ -4200,11 +4200,11 @@ var require_fast_uri = __commonJS({
     var fastUri = {
       SCHEMES,
       normalize,
-      resolve: resolve8,
+      resolve: resolve9,
       resolveComponent,
       equal,
       serialize,
-      parse: parse5
+      parse: parse6
     };
     module.exports = fastUri;
     module.exports.default = fastUri;
@@ -14674,7 +14674,7 @@ var require_public_api = __commonJS({
       }
       return doc;
     }
-    function parse5(src, reviver, options) {
+    function parse6(src, reviver, options) {
       let _reviver = void 0;
       if (typeof reviver === "function") {
         _reviver = reviver;
@@ -14715,7 +14715,7 @@ var require_public_api = __commonJS({
         return value.toString(options);
       return new Document.Document(value, _replacer, options).toString(options);
     }
-    exports.parse = parse5;
+    exports.parse = parse6;
     exports.parseAllDocuments = parseAllDocuments;
     exports.parseDocument = parseDocument2;
     exports.stringify = stringify3;
@@ -15139,7 +15139,7 @@ function defaultSpawn(command, args, options) {
   if (options.signal?.aborted) {
     return Promise.resolve({ stdout: "", stderr: "", code: null, started: false, observedChildExit: false, error: new Error("process_aborted") });
   }
-  return new Promise((resolve8) => {
+  return new Promise((resolve9) => {
     const stdout = [];
     const stderr = [];
     let outputBytes = 0;
@@ -15168,7 +15168,7 @@ function defaultSpawn(command, args, options) {
       child?.unref();
       const started = Boolean(child?.pid);
       if (started && !observedChildExit) error ??= new Error("process_exit_unobserved");
-      resolve8({ stdout: Buffer.concat(stdout).toString("utf8"), stderr: Buffer.concat(stderr).toString("utf8"), code, signal, started, observedChildExit, terminationRequested: stopping, ...error ? { error } : {} });
+      resolve9({ stdout: Buffer.concat(stdout).toString("utf8"), stderr: Buffer.concat(stderr).toString("utf8"), code, signal, started, observedChildExit, terminationRequested: stopping, ...error ? { error } : {} });
     };
     const kill = (requested) => {
       killProcessTree(child, requested);
@@ -16925,8 +16925,8 @@ function validateWorkflow(workflow, agents, models, repositories, gates, issues)
       const writable = Object.values(objectValue(step.repositories) ?? {}).filter((access) => access === "write").length;
       if (maxWriteRepositories > writable) issues.push(issue2("semantic", "write_repository_bound_invalid", file, `${stepId} maxWriteRepositories exceeds writable repository scope`));
     }
-    const join15 = objectValue(step.join);
-    const minimumPassed = join15 && typeof join15.minimumPassed === "number" ? join15.minimumPassed : void 0;
+    const join17 = objectValue(step.join);
+    const minimumPassed = join17 && typeof join17.minimumPassed === "number" ? join17.minimumPassed : void 0;
     if (minimumPassed !== void 0 && minimumPassed > maximum) issues.push(issue2("semantic", "join_impossible", file, `${stepId} minimumPassed exceeds assignment maximum`));
     const distinctBy = names(assignment?.distinctBy);
     if (distinctBy.length > 0) {
@@ -20454,7 +20454,7 @@ function compileStep(step, index, stepIndex, requirePlanHash, sink) {
   const maxAttempts = compileCountField(step.maxAttempts, 1, `${id}.maxAttempts`, id, sink);
   const timeoutMs = compileOptionalDuration(step.timeoutMs, `${id}.timeoutMs`, id, sink);
   const assignments = compileAssignments(step, id, agent, sink);
-  const join15 = compileJoin(step, id, sink);
+  const join17 = compileJoin(step, id, sink);
   const requiredEvidence = compileEvidence(step, id, sink);
   const transitions = compileTransitions(step, id, index, stepIndex, sink);
   const outcomes = Object.keys(transitions).sort(compareCodeUnits4);
@@ -20482,7 +20482,7 @@ function compileStep(step, index, stepIndex, requirePlanHash, sink) {
     transitions: orderedTransitions,
     requiresPlanHash: requirePlanHash.includes(id),
     assignments,
-    join: join15
+    join: join17
   };
   if (kind === "agent" || kind === "moa") {
     if (!agent) return void 0;
@@ -20532,15 +20532,15 @@ function compileAssignments(step, stepId, primaryAgentId, sink) {
   };
 }
 function compileJoin(step, stepId, sink) {
-  const join15 = objectValue2(step.join);
-  if (!join15) return { strategy: "all" };
-  const declared = stringValue2(join15.strategy);
+  const join17 = objectValue2(step.join);
+  if (!join17) return { strategy: "all" };
+  const declared = stringValue2(join17.strategy);
   const strategy = declared && JOIN_STRATEGIES.has(declared) ? declared : "all";
-  const minimumPassed = compileOptionalCount(join15.minimumPassed, `${stepId}.join.minimumPassed`, stepId, sink);
+  const minimumPassed = compileOptionalCount(join17.minimumPassed, `${stepId}.join.minimumPassed`, stepId, sink);
   const compiled = {
     strategy,
     ...minimumPassed !== void 0 ? { minimumPassed } : {},
-    ...typeof join15.cancelRemaining === "boolean" ? { cancelRemaining: join15.cancelRemaining } : {}
+    ...typeof join17.cancelRemaining === "boolean" ? { cancelRemaining: join17.cancelRemaining } : {}
   };
   return compiled;
 }
@@ -21835,12 +21835,12 @@ function enqueueVnextScheduledRun(storePath, runId, configRevision, bound, start
   if (owner.admitted.has(runId) || owner.queue.some((item) => item.runId === runId)) {
     return Promise.reject(runtimeError("run_busy", runId, `run ${runId} is already admitted or queued`));
   }
-  return new Promise((resolve8, reject) => {
+  return new Promise((resolve9, reject) => {
     owner.queue.push({
       runId,
       configRevision,
       bound,
-      start: (token) => start(token).then(resolve8, reject),
+      start: (token) => start(token).then(resolve9, reject),
       fail: (error) => reject(error)
     });
     pump(storePath, owner);
@@ -23013,6 +23013,17 @@ var INSECURE_SSH_HOST_KEY_PATTERNS = Object.freeze([
   /StrictHostKeyChecking=(accept-new|no|off)/i,
   /UserKnownHostsFile=\/dev\/null/i
 ]);
+function assertPinnedSshHostKeyPolicy(sshArgs) {
+  for (const arg of sshArgs) {
+    for (const pattern of INSECURE_SSH_HOST_KEY_PATTERNS) {
+      if (pattern.test(arg)) {
+        throw new Error(
+          `Insecure SSH host key policy rejected: "${arg}". KXM headless SSH requires pinned host keys with StrictHostKeyChecking=yes and BatchMode=yes.`
+        );
+      }
+    }
+  }
+}
 
 // plugins/kxm/src/vnext-engine-command.ts
 var MAX_DIRECT_TIMER_MS = 2147483647;
@@ -23100,8 +23111,8 @@ var CommandObserver = class {
     this.requestStop("error", "lost-close");
   }
   run() {
-    return new Promise((resolve8) => {
-      this.resolveOutcome = resolve8;
+    return new Promise((resolve9) => {
+      this.resolveOutcome = resolve9;
       try {
         this.start();
       } catch (error) {
@@ -26532,8 +26543,8 @@ async function startVnextRuntimeSupervisorInner(paths, requestedPortOption, now)
             }
             let releaseActive = () => {
             };
-            const activePromise = new Promise((resolve8) => {
-              releaseActive = resolve8;
+            const activePromise = new Promise((resolve9) => {
+              releaseActive = resolve9;
             });
             activeDrives.set(runId, activePromise);
             const cleanupActive = () => {
@@ -26989,8 +27000,8 @@ var PiSession = class {
     }
     const id = `cmd_${++this.commandCounter}`;
     const payload = { ...command, id };
-    return new Promise((resolve8, reject) => {
-      this.pendingCommands.set(id, { resolve: resolve8, reject });
+    return new Promise((resolve9, reject) => {
+      this.pendingCommands.set(id, { resolve: resolve9, reject });
       try {
         this.process.stdin.write(JSON.stringify(payload) + "\n");
       } catch (err) {
@@ -27011,7 +27022,7 @@ var PiSession = class {
       return { outcome, text: "aborted", usage: {} };
     }
     this.status = "busy";
-    return new Promise((resolve8, reject) => {
+    return new Promise((resolve9, reject) => {
       let signalCleanup;
       if (signal) {
         const onAbort = () => {
@@ -27025,7 +27036,7 @@ var PiSession = class {
         signalCleanup = () => signal.removeEventListener("abort", onAbort);
       }
       this.activePrompt = {
-        resolve: resolve8,
+        resolve: resolve9,
         reject,
         allowedOutcomes,
         text: "",
@@ -28173,16 +28184,652 @@ Instructions for Operator:
     return orphaned;
   }
 };
+
+// plugins/kxm/src/modes.ts
+var import_yaml6 = __toESM(require_dist(), 1);
+import { existsSync as existsSync12, readFileSync as readFileSync10 } from "node:fs";
+import { join as join15 } from "node:path";
+var DEFAULT_MODES_CONFIG = Object.freeze({
+  schema: "kxm.modes.v1",
+  majorModes: {
+    coder: {
+      description: "First-pass implementation, bug fixing, and test authoring",
+      baseTools: ["read", "edit", "write", "bash"],
+      contextFiles: ["AGENTS.md"],
+      thinkingLevel: "medium",
+      model: "grok/grok-4.6"
+    },
+    planner: {
+      description: "High-level architectural planning, scoping, and decomposition",
+      baseTools: ["read", "grep", "find"],
+      contextFiles: ["plans/implementation-plan.md"],
+      thinkingLevel: "high",
+      model: "claude/fable"
+    },
+    auditor: {
+      description: "Security, compliance, and code quality verification",
+      baseTools: ["read", "grep"],
+      contextFiles: ["SECURITY.md"],
+      thinkingLevel: "high",
+      model: "codex/gpt-5.6-sol"
+    },
+    browser: {
+      description: "Web application exploration, screenshotting, and UI testing",
+      baseTools: ["read", "bash"],
+      contextFiles: ["docs/browser-automation.md"],
+      thinkingLevel: "medium",
+      model: "grok/grok-4.6"
+    }
+  },
+  domains: {
+    git: {
+      description: "Git version control operations",
+      tools: ["git_status", "git_diff", "git_commit"],
+      promptSnippet: "Follow git branch conventions; never commit directly to main."
+    },
+    k8s: {
+      description: "Kubernetes cluster inspection and deployment",
+      tools: ["kubectl_get", "kubectl_describe"],
+      promptSnippet: "Target local dev cluster; verify namespaces before mutating."
+    },
+    database: {
+      description: "Database queries and schema verification",
+      tools: ["sqlite_query", "sqlite_schema"],
+      promptSnippet: "Database is SQLite at .kxm/state/kxm.db; use read-only queries."
+    },
+    browser: {
+      description: "Remote Steel browser sessions and visual testing",
+      tools: ["steel_session", "steel_scrape", "steel_screenshot"],
+      promptSnippet: "Use Steel on DOKS for browser automation; invoke takeover on MFA."
+    }
+  }
+});
+function estimateTokens(charCount) {
+  return Math.ceil(charCount / 3.8);
+}
+function loadModesConfig(projectRoot) {
+  if (!projectRoot) {
+    return DEFAULT_MODES_CONFIG;
+  }
+  const modesPath = join15(projectRoot, ".kxm", "modes.yaml");
+  if (!existsSync12(modesPath)) {
+    return DEFAULT_MODES_CONFIG;
+  }
+  try {
+    const raw = readFileSync10(modesPath, "utf8");
+    const parsed = (0, import_yaml6.parse)(raw);
+    if (parsed && parsed.schema === "kxm.modes.v1" && parsed.majorModes) {
+      return {
+        schema: "kxm.modes.v1",
+        majorModes: { ...DEFAULT_MODES_CONFIG.majorModes, ...parsed.majorModes },
+        domains: { ...DEFAULT_MODES_CONFIG.domains, ...parsed.domains }
+      };
+    }
+  } catch {
+  }
+  return DEFAULT_MODES_CONFIG;
+}
+function resolveActiveMode(config, majorModeName = "coder", domainNames = []) {
+  const major = config.majorModes[majorModeName] || config.majorModes["coder"] || DEFAULT_MODES_CONFIG.majorModes["coder"];
+  const tools = new Set(major.baseTools);
+  const contextFiles = new Set(major.contextFiles || []);
+  const promptSnippets = [];
+  const enabledDomains = [];
+  if (config.domains) {
+    for (const dName of domainNames) {
+      const d = config.domains[dName.toLowerCase().trim()];
+      if (d) {
+        enabledDomains.push(dName.toLowerCase().trim());
+        d.tools.forEach((t) => tools.add(t));
+        (d.contextFiles || []).forEach((f) => contextFiles.add(f));
+        if (d.promptSnippet) {
+          promptSnippets.push(d.promptSnippet);
+        }
+      }
+    }
+  }
+  return {
+    majorMode: majorModeName,
+    enabledDomains,
+    tools: Array.from(tools),
+    contextFiles: Array.from(contextFiles),
+    promptSnippets,
+    thinkingLevel: major.thinkingLevel,
+    model: major.model || "grok/grok-4.6"
+  };
+}
+function calculatePromptFootprint(resolved, projectRoot = process.cwd(), catalog) {
+  const breakdown = [];
+  const baseSystemPromptChars = 3200;
+  breakdown.push({
+    name: `Base System Prompt (${resolved.majorMode})`,
+    chars: baseSystemPromptChars,
+    estimatedTokens: estimateTokens(baseSystemPromptChars)
+  });
+  for (const relPath of resolved.contextFiles) {
+    const fullPath = join15(projectRoot, relPath);
+    let chars = 0;
+    if (existsSync12(fullPath)) {
+      try {
+        chars = readFileSync10(fullPath, "utf8").length;
+      } catch {
+        chars = 0;
+      }
+    }
+    if (chars === 0) {
+      chars = 1500;
+    }
+    breakdown.push({
+      name: `Context File: ${relPath}`,
+      chars,
+      estimatedTokens: estimateTokens(chars)
+    });
+  }
+  if (resolved.promptSnippets.length > 0) {
+    const snippetChars = resolved.promptSnippets.join("\n").length;
+    breakdown.push({
+      name: `Domain Prompts (${resolved.enabledDomains.join(", ")})`,
+      chars: snippetChars,
+      estimatedTokens: estimateTokens(snippetChars)
+    });
+  }
+  const toolSchemaChars = resolved.tools.length * 650;
+  breakdown.push({
+    name: `Tool Schemas (${resolved.tools.length} active tools)`,
+    chars: toolSchemaChars,
+    estimatedTokens: estimateTokens(toolSchemaChars)
+  });
+  const totalChars = breakdown.reduce((sum, item) => sum + item.chars, 0);
+  const totalTokens = breakdown.reduce((sum, item) => sum + item.estimatedTokens, 0);
+  const maxContextWindow = 2e5;
+  const contextWindowRatio = Math.round(totalTokens / maxContextWindow * 1e3) / 10;
+  const cat = catalog || loadPriceCatalog(projectRoot);
+  const rawModel = resolved.model || "grok/grok-4.6";
+  const [prov, mod] = rawModel.includes("/") ? rawModel.split("/", 2) : [void 0, rawModel];
+  const inputCost = cat ? calculateModelCost(cat, {
+    model: mod || rawModel,
+    ...prov !== void 0 ? { provider: prov } : {},
+    tokensIn: totalTokens,
+    tokensOut: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0
+  }) : void 0;
+  const cacheReadCost = cat ? calculateModelCost(cat, {
+    model: mod || rawModel,
+    ...prov !== void 0 ? { provider: prov } : {},
+    tokensIn: 0,
+    tokensOut: 0,
+    cacheReadTokens: totalTokens,
+    cacheWriteTokens: 0
+  }) : void 0;
+  const outputEstimateCost = cat ? calculateModelCost(cat, {
+    model: mod || rawModel,
+    ...prov !== void 0 ? { provider: prov } : {},
+    tokensIn: 0,
+    tokensOut: 1e3,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0
+  }) : void 0;
+  return {
+    majorMode: resolved.majorMode,
+    enabledDomains: resolved.enabledDomains,
+    model: resolved.model || "grok/grok-4.6",
+    breakdown,
+    totalChars,
+    totalTokens,
+    contextWindowRatio,
+    projectedCost: {
+      inputCostUsd: inputCost?.costUsd ?? null,
+      cacheReadCostUsd: cacheReadCost?.costUsd ?? null,
+      outputCostEstimateUsd: outputEstimateCost?.costUsd ?? null
+    }
+  };
+}
+function formatModesExplainReport(footprint) {
+  const divider = "\u2550".repeat(60);
+  const subDivider = "\u2500".repeat(60);
+  let out = `
+${divider}
+`;
+  out += `KXM PRE-FLIGHT CONTEXT EXPLAIN
+`;
+  out += `${divider}
+`;
+  out += `Major Mode:       ${footprint.majorMode}
+`;
+  out += `Enabled Domains:  ${footprint.enabledDomains.length > 0 ? footprint.enabledDomains.join(", ") : "(none)"}
+`;
+  out += `Target Model:     ${footprint.model}
+
+`;
+  out += `CONTEXT BREAKDOWN:
+`;
+  for (const item of footprint.breakdown) {
+    const padName = item.name.padEnd(38, " ");
+    const tokenStr = `${item.estimatedTokens.toLocaleString()} tokens`.padStart(16, " ");
+    out += `  \u2022 ${padName} ${tokenStr}
+`;
+  }
+  out += `${subDivider}
+`;
+  const totalPad = `TOTAL PROMPT FOOTPRINT:`.padEnd(38, " ");
+  const totalStr = `${footprint.totalTokens.toLocaleString()} tokens`.padStart(16, " ");
+  out += `  ${totalPad} ${totalStr} (${footprint.contextWindowRatio}% of 200k window)
+
+`;
+  out += `PROJECTED COSTS (per turn):
+`;
+  out += `  \u2022 Initial Turn Input Cost:   ${footprint.projectedCost.inputCostUsd !== null ? `$${footprint.projectedCost.inputCostUsd.toFixed(4)}` : "unmetered/unknown"}
+`;
+  out += `  \u2022 Subsequent Cache-Read Cost: ${footprint.projectedCost.cacheReadCostUsd !== null ? `$${footprint.projectedCost.cacheReadCostUsd.toFixed(4)} (approx 90% savings)` : "unmetered/unknown"}
+`;
+  out += `  \u2022 Output Estimate (1k tokens): ${footprint.projectedCost.outputCostEstimateUsd !== null ? `$${footprint.projectedCost.outputCostEstimateUsd.toFixed(4)}` : "unmetered/unknown"}
+`;
+  out += `${divider}
+`;
+  return out;
+}
+
+// plugins/kxm/src/ssh-remote.ts
+import { spawnSync as spawnSync3 } from "node:child_process";
+import { existsSync as existsSync13, mkdirSync as mkdirSync7, readFileSync as readFileSync11, readdirSync as readdirSync5, rmSync as rmSync2, statSync as statSync4 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { join as join16, resolve as resolve8 } from "node:path";
+var MAX_SSH_OUTPUT_BYTES = 50 * 1024;
+var MAX_SSH_OUTPUT_LINES = 2e3;
+var DEFAULT_SOCKET_DIR = ".kxm/run/ssh-sockets";
+var DEFAULT_CONTROL_PERSIST = "10m";
+function truncateSshOutput(raw) {
+  let text = raw;
+  let truncated = false;
+  if (Buffer.byteLength(text, "utf-8") > MAX_SSH_OUTPUT_BYTES) {
+    const buf = Buffer.from(text, "utf-8");
+    text = buf.subarray(0, MAX_SSH_OUTPUT_BYTES).toString("utf-8");
+    truncated = true;
+  }
+  const lines = text.split("\n");
+  if (lines.length > MAX_SSH_OUTPUT_LINES) {
+    text = lines.slice(0, MAX_SSH_OUTPUT_LINES).join("\n");
+    truncated = true;
+  }
+  if (truncated) {
+    text += `
+
+[kxm: ssh output truncated to ${MAX_SSH_OUTPUT_BYTES / 1024}KB / ${MAX_SSH_OUTPUT_LINES} lines]`;
+  }
+  return { text, truncated };
+}
+function parseSshConfig(configPath) {
+  const targetPath = configPath ?? join16(homedir2(), ".ssh", "config");
+  if (!existsSync13(targetPath)) {
+    return [];
+  }
+  try {
+    const content = readFileSync11(targetPath, "utf-8");
+    const lines = content.split("\n");
+    const hosts = [];
+    let currentHosts = [];
+    for (const rawLine of lines) {
+      const line = rawLine.trim();
+      if (!line || line.startsWith("#")) continue;
+      const spaceIdx = line.search(/\s/);
+      if (spaceIdx === -1) continue;
+      const key = line.slice(0, spaceIdx).trim().toLowerCase();
+      const value = line.slice(spaceIdx + 1).trim();
+      if (key === "host") {
+        const aliases = value.split(/\s+/).filter((a) => a !== "*");
+        currentHosts = [];
+        for (const alias of aliases) {
+          const entry = { alias, identityFiles: [] };
+          currentHosts.push(entry);
+          hosts.push(entry);
+        }
+      } else if (currentHosts.length > 0) {
+        for (const currentHost of currentHosts) {
+          if (key === "hostname") {
+            currentHost.hostName = value;
+          } else if (key === "user") {
+            currentHost.user = value;
+          } else if (key === "port") {
+            const p = Number.parseInt(value, 10);
+            if (!Number.isNaN(p)) currentHost.port = p;
+          } else if (key === "proxyjump") {
+            currentHost.proxyJump = value;
+          } else if (key === "identityfile") {
+            currentHost.identityFiles = currentHost.identityFiles ?? [];
+            currentHost.identityFiles.push(value);
+          }
+        }
+      }
+    }
+    return hosts;
+  } catch {
+    return [];
+  }
+}
+function resolveSshHostG(host, execFn = spawnSync3) {
+  try {
+    const result = execFn("ssh", ["-G", host], { encoding: "utf-8" });
+    if (result.status !== 0 || !result.stdout) {
+      return { alias: host, hostName: host };
+    }
+    const lines = String(result.stdout).split("\n");
+    const info = { alias: host, identityFiles: [] };
+    for (const rawLine of lines) {
+      const line = rawLine.trim();
+      if (!line) continue;
+      const spaceIdx = line.indexOf(" ");
+      if (spaceIdx === -1) continue;
+      const key = line.slice(0, spaceIdx).toLowerCase();
+      const value = line.slice(spaceIdx + 1).trim();
+      if (key === "hostname") {
+        info.hostName = value;
+      } else if (key === "user") {
+        info.user = value;
+      } else if (key === "port") {
+        const p = Number.parseInt(value, 10);
+        if (!Number.isNaN(p)) info.port = p;
+      } else if (key === "proxyjump") {
+        if (value && value !== "none") info.proxyJump = value;
+      } else if (key === "identityfile") {
+        info.identityFiles = info.identityFiles ?? [];
+        info.identityFiles.push(value);
+      }
+    }
+    return info;
+  } catch {
+    return { alias: host, hostName: host };
+  }
+}
+function ensureSocketDir(socketDir = DEFAULT_SOCKET_DIR) {
+  const resolved = resolve8(socketDir);
+  if (!existsSync13(resolved)) {
+    mkdirSync7(resolved, { recursive: true, mode: 448 });
+  }
+  return resolved;
+}
+function buildSshArgs(options) {
+  const socketDir = ensureSocketDir(options.socketDir ?? DEFAULT_SOCKET_DIR);
+  const controlPath = join16(socketDir, "%C");
+  const persist2 = options.controlPersist ?? DEFAULT_CONTROL_PERSIST;
+  const args = [
+    "-o",
+    `ControlMaster=auto`,
+    "-o",
+    `ControlPath=${controlPath}`,
+    "-o",
+    `ControlPersist=${persist2}`
+  ];
+  if (options.batchMode !== false) {
+    args.push("-o", "BatchMode=yes");
+  }
+  if (options.strictHostKey !== false) {
+    args.push("-o", "StrictHostKeyChecking=yes");
+  }
+  if (options.extraArgs) {
+    args.push(...options.extraArgs);
+  }
+  assertPinnedSshHostKeyPolicy(args);
+  args.push(options.host);
+  return args;
+}
+function checkControlSocket(host, socketDir = DEFAULT_SOCKET_DIR, execFn = spawnSync3) {
+  const resolvedDir = ensureSocketDir(socketDir);
+  const controlPath = join16(resolvedDir, "%C");
+  try {
+    const result = execFn("ssh", ["-O", "check", "-o", `ControlPath=${controlPath}`, host], {
+      encoding: "utf-8"
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+function closeControlSocket(host, socketDir = DEFAULT_SOCKET_DIR, execFn = spawnSync3) {
+  const resolvedDir = ensureSocketDir(socketDir);
+  const controlPath = join16(resolvedDir, "%C");
+  try {
+    const result = execFn("ssh", ["-O", "stop", "-o", `ControlPath=${controlPath}`, host], {
+      encoding: "utf-8"
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+function pruneSocketDir(socketDir = DEFAULT_SOCKET_DIR) {
+  const resolvedDir = ensureSocketDir(socketDir);
+  let removed = 0;
+  try {
+    const entries = readdirSync5(resolvedDir);
+    for (const entry of entries) {
+      const fullPath = join16(resolvedDir, entry);
+      try {
+        const stat = statSync4(fullPath);
+        if (stat.isSocket()) {
+          rmSync2(fullPath, { force: true });
+          removed++;
+        }
+      } catch {
+      }
+    }
+  } catch {
+  }
+  return removed;
+}
+function executeSshRun(params) {
+  const startTime = Date.now();
+  const execSyncFn = params.execFn ?? spawnSync3;
+  if (params.action === "info") {
+    if (params.host) {
+      const hostInfo = resolveSshHostG(params.host, execSyncFn);
+      return {
+        ok: true,
+        action: "info",
+        host: params.host,
+        resolvedHost: hostInfo.hostName ?? params.host,
+        user: hostInfo.user,
+        port: hostInfo.port,
+        hosts: [hostInfo],
+        durationMs: Date.now() - startTime
+      };
+    }
+    const discovered = parseSshConfig();
+    return {
+      ok: true,
+      action: "info",
+      hosts: discovered,
+      durationMs: Date.now() - startTime
+    };
+  }
+  if (!params.host) {
+    return {
+      ok: false,
+      action: params.action,
+      error: 'Parameter "host" is required for command and file actions.',
+      durationMs: Date.now() - startTime
+    };
+  }
+  const host = params.host;
+  const socketDir = params.socket_dir ?? DEFAULT_SOCKET_DIR;
+  const wasSocketActive = checkControlSocket(host, socketDir, execSyncFn);
+  if (params.action === "command") {
+    if (!params.command) {
+      return {
+        ok: false,
+        action: "command",
+        host,
+        error: 'Parameter "command" is required for command action.',
+        durationMs: Date.now() - startTime
+      };
+    }
+    try {
+      assertCommandSeatbelt(params.command);
+    } catch (err) {
+      return {
+        ok: false,
+        action: "command",
+        host,
+        error: err.message,
+        durationMs: Date.now() - startTime
+      };
+    }
+    let remoteCommand = params.command;
+    let inputStdin = void 0;
+    if (params.sudo) {
+      const sudoPwd = params.sudo_password ?? params.password;
+      if (sudoPwd) {
+        inputStdin = `${sudoPwd}
+`;
+        remoteCommand = `sudo -S -p '' -- sh -c ${JSON.stringify(params.command)}`;
+      } else {
+        remoteCommand = `sudo -- sh -c ${JSON.stringify(params.command)}`;
+      }
+    }
+    const useSshPass = Boolean(params.password);
+    const sshArgs = buildSshArgs({
+      host,
+      socketDir,
+      controlPersist: params.control_persist,
+      batchMode: !useSshPass,
+      strictHostKey: params.strict_host_key
+    });
+    sshArgs.push("--", remoteCommand);
+    const spawnEnv = { ...process.env };
+    let binary = "ssh";
+    let finalArgs = sshArgs;
+    if (useSshPass && params.password) {
+      binary = "sshpass";
+      finalArgs = ["-e", "ssh", ...sshArgs];
+      spawnEnv.SSHPASS = params.password;
+    }
+    try {
+      const result = execSyncFn(binary, finalArgs, {
+        encoding: "utf-8",
+        env: spawnEnv,
+        input: inputStdin,
+        timeout: params.timeout_ms ?? 12e4,
+        maxBuffer: 10 * 1024 * 1024
+      });
+      const stdoutRaw = String(result.stdout || "");
+      const stderrRaw = String(result.stderr || "");
+      const sanitizedStderr = stderrRaw.replace(/\[sudo\] password for [^:]+:\s*/gi, "");
+      const stdoutTrunc = truncateSshOutput(stdoutRaw);
+      const stderrTrunc = truncateSshOutput(sanitizedStderr);
+      return {
+        ok: result.status === 0,
+        action: "command",
+        host,
+        exitCode: result.status ?? 1,
+        stdout: stdoutTrunc.text,
+        stderr: stderrTrunc.text,
+        truncated: stdoutTrunc.truncated || stderrTrunc.truncated,
+        socketReused: wasSocketActive,
+        durationMs: Date.now() - startTime,
+        error: result.error ? result.error.message : void 0
+      };
+    } catch (err) {
+      return {
+        ok: false,
+        action: "command",
+        host,
+        error: err.message,
+        durationMs: Date.now() - startTime
+      };
+    }
+  }
+  if (params.action === "file") {
+    if (!params.file_path) {
+      return {
+        ok: false,
+        action: "file",
+        host,
+        error: 'Parameter "file_path" is required for file action.',
+        durationMs: Date.now() - startTime
+      };
+    }
+    const filePath = params.file_path;
+    const op = params.file_op ?? "write";
+    if (op === "read") {
+      const readCmd = params.sudo ? `sudo cat ${JSON.stringify(filePath)}` : `cat ${JSON.stringify(filePath)}`;
+      return executeSshRun({
+        ...params,
+        action: "command",
+        command: readCmd
+      });
+    }
+    const content = params.file_content ?? "";
+    const redirectOp = op === "append" ? ">>" : ">";
+    const writeCmd = params.sudo ? `sudo tee ${op === "append" ? "-a " : ""}${JSON.stringify(filePath)} > /dev/null` : `cat ${redirectOp} ${JSON.stringify(filePath)}`;
+    const useSshPass = Boolean(params.password);
+    const sshArgs = buildSshArgs({
+      host,
+      socketDir,
+      controlPersist: params.control_persist,
+      batchMode: !useSshPass,
+      strictHostKey: params.strict_host_key
+    });
+    sshArgs.push("--", writeCmd);
+    const spawnEnv = { ...process.env };
+    let binary = "ssh";
+    let finalArgs = sshArgs;
+    if (useSshPass && params.password) {
+      binary = "sshpass";
+      finalArgs = ["-e", "ssh", ...sshArgs];
+      spawnEnv.SSHPASS = params.password;
+    }
+    try {
+      const result = execSyncFn(binary, finalArgs, {
+        encoding: "utf-8",
+        env: spawnEnv,
+        input: content,
+        timeout: params.timeout_ms ?? 6e4
+      });
+      return {
+        ok: result.status === 0,
+        action: "file",
+        host,
+        exitCode: result.status ?? 1,
+        stdout: String(result.stdout || ""),
+        stderr: String(result.stderr || ""),
+        fileProcessed: filePath,
+        bytesProcessed: Buffer.byteLength(content, "utf-8"),
+        socketReused: wasSocketActive,
+        durationMs: Date.now() - startTime,
+        error: result.error ? result.error.message : void 0
+      };
+    } catch (err) {
+      return {
+        ok: false,
+        action: "file",
+        host,
+        error: err.message,
+        durationMs: Date.now() - startTime
+      };
+    }
+  }
+  return {
+    ok: false,
+    action: params.action,
+    error: `Unknown action: ${params.action}`,
+    durationMs: Date.now() - startTime
+  };
+}
 export {
   BUILTIN_HARNESSES,
   BUILTIN_HARNESS_IDS,
   CANDIDATE_SCHEMA,
+  DEFAULT_CONTROL_PERSIST,
   DEFAULT_HARNESS,
   DEFAULT_LOG_MAX_BYTES,
   DEFAULT_LOG_MAX_FILES,
+  DEFAULT_MODES_CONFIG,
+  DEFAULT_SOCKET_DIR,
   IMPROVEMENT_REPORT_SCHEMA,
   IMPROVEMENT_REPORT_V1_SCHEMA,
   LOG_LEVEL_PRIORITY,
+  MAX_SSH_OUTPUT_BYTES,
+  MAX_SSH_OUTPUT_LINES,
   NATIVE_HARNESS_PROVIDERS,
   PI_ALLOWED_PROVIDERS,
   PI_NATIVE_BRAKE_PROVIDERS,
@@ -28202,12 +28849,16 @@ export {
   assertVnextConfigError,
   backupDatabaseFile,
   buildImprovementReport,
+  buildSshArgs,
+  calculatePromptFootprint,
   cancelVnextRun,
+  checkControlSocket,
   checkIntegrity,
   checkMemoryRevisionDrift,
   checkedParent,
   checkpointWal,
   classifyCandidateKind,
+  closeControlSocket,
   closeVnextRuntimeContext,
   computeGateEvidenceOutcome,
   computeVnextMemoryRevision,
@@ -28220,9 +28871,12 @@ export {
   defaultSpawn,
   discoverProjectStores,
   eligibleHarnesses,
+  ensureSocketDir,
   ensureVnextSupervisor,
   ensureWalJournalMode,
+  estimateTokens,
   evaluatePromotionPolicy,
+  executeSshRun,
   fileSha256,
   findWinNpmInnerExe,
   foldStoredVnextRun,
@@ -28231,6 +28885,7 @@ export {
   formatHarnessInventory,
   formatHarnessUpdate,
   formatImprovementReport,
+  formatModesExplainReport,
   formatPiSessionDisplayName,
   formatPiSessionKey,
   gateRowContentHash,
@@ -28242,6 +28897,7 @@ export {
   isKnownHarnessId,
   isVnextRuntimeContextClosed,
   isWindowsHarnessShim,
+  loadModesConfig,
   newVnextAssignmentId,
   newVnextAttemptId,
   newVnextCommandId,
@@ -28259,6 +28915,7 @@ export {
   parseGenericOneShotUsage,
   parseGrokOneShotUsage,
   parseKimiOneShotUsage,
+  parseSshConfig,
   persistVnextRunState,
   planHarnessUpdate,
   probeHarnessAssignment,
@@ -28266,13 +28923,16 @@ export {
   probeHarnesses,
   probeHarnessesForModel,
   projectRuntimeKey,
+  pruneSocketDir,
   readVnextRunStatus,
   readVnextSupervisorToken,
   rebuildVnextRunProjection,
   redactLogValue,
   registerVnextRuntimeCloseHook,
+  resolveActiveMode,
   resolveDispatchStatus,
   resolvePassCliApiKey,
+  resolveSshHostG,
   resolveSteelConfig,
   resolveViewportDimensions,
   restoreBackup,
@@ -28283,6 +28943,7 @@ export {
   sanitizeLogOutput,
   startVnextRuntimeSupervisor,
   tableColumns,
+  truncateSshOutput,
   userTables,
   validateHarnessModelPair,
   verifyExpectedTables,