@linghun/tui 0.1.0

package/dist/chunk-B4GQTZMT.js

@@ -0,0 +1,607 @@
+import {
+  redactedPath
+} from "./chunk-RVY34HK4.js";
+import {
+  formatJobRunnerInline
+} from "./chunk-UDQT5CWK.js";
+import {
+  isRecord
+} from "./chunk-QLRTQHTR.js";
+import {
+  sanitizeDiagnosticText
+} from "./chunk-OMZYPQVA.js";
+
+// src/runner-runtime.ts
+import { spawn, spawnSync } from "child_process";
+import { constants, accessSync, existsSync } from "fs";
+import { mkdir, readFile } from "fs/promises";
+import { basename, dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+var NATIVE_RUNNER_VERSION_TIMEOUT_MS = 2e3;
+var NATIVE_RUNNER_START_STATE_WAIT_MS = 1500;
+var NATIVE_RUNNER_APPROVED_TASK_HEARTBEAT_MS = 100;
+var CLI_BUNDLED_ROOT_ENV = "LINGHUN_CLI_BUNDLED_ROOT";
+var NATIVE_RUNNER_BUNDLED_PLATFORM_ARCHES = /* @__PURE__ */ new Set([
+  "win32-x64",
+  "linux-x64",
+  "darwin-arm64",
+  "darwin-x64"
+]);
+var NATIVE_RUNNER_PROCESS_GUARD_CONTRACT = [
+  "Windows native runner SHOULD use a Job Object with kill-on-job-close for supervised children.",
+  "Unix native runner SHOULD create and manage a child process group, then kill that group on stop/exit.",
+  "Parent death cleanup is only proven by a real native runner smoke; Node tests do not prove orphan cleanup."
+];
+var _runnerPids = /* @__PURE__ */ new Map();
+var NATIVE_RUNNER_APPROVED_TASK_SCRIPT = [
+  "const durationMs = Number(process.argv[1] || '1000');",
+  "const heartbeatMs = 100;",
+  "const startedAt = Date.now();",
+  "let tick = 0;",
+  "console.log(JSON.stringify({ kind: 'linghun-approved-runner-task', status: 'started', tick, elapsedMs: 0 }));",
+  "const timer = setInterval(() => {",
+  "  tick += 1;",
+  "  const elapsedMs = Date.now() - startedAt;",
+  "  console.log(JSON.stringify({ kind: 'linghun-approved-runner-task', status: elapsedMs >= durationMs ? 'completed' : 'heartbeat', tick, elapsedMs }));",
+  "  if (elapsedMs >= durationMs) {",
+  "    clearInterval(timer);",
+  "    process.exitCode = 0;",
+  "  }",
+  "}, heartbeatMs);"
+].join("\n");
+function stringValue(value, fallback) {
+  return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+function resolveNativeRunner(config) {
+  const runner = config.nativeRunner;
+  const bundledCandidate = getBundledNativeRunnerCandidate();
+  const base = {
+    processGuardContract: NATIVE_RUNNER_PROCESS_GUARD_CONTRACT,
+    bundledCandidateRef: bundledCandidate.ref,
+    platform: process.platform,
+    arch: process.arch,
+    platformArch: bundledCandidate.platformArch,
+    nodeFallback: "available"
+  };
+  if (!runner.enabled) {
+    return {
+      status: "disabled",
+      enabled: false,
+      source: "disabled",
+      pathRef: "disabled",
+      ...base,
+      nextAction: "Native runner is disabled; Node/TUI remains the fallback for durable jobs."
+    };
+  }
+  const resolvedPath = resolveNativeRunnerPath(runner, bundledCandidate);
+  if (!resolvedPath) {
+    return {
+      status: "unavailable",
+      enabled: true,
+      source: runner.source,
+      pathRef: "missing",
+      ...base,
+      lastError: runner.source === "bundled" && !bundledCandidate.supported ? `bundled runner platform is not supported: ${bundledCandidate.platformArch}` : "runner path is not configured",
+      nextAction: runner.source === "bundled" ? "Install a Linghun package with a bundled runner for this platform, or keep using Node fallback." : "Configure a project-local/custom runner path for development, or keep using Node fallback."
+    };
+  }
+  if (!existsSync(resolvedPath) || !isExecutableNativeRunnerCandidate(resolvedPath)) {
+    return {
+      status: "unavailable",
+      enabled: true,
+      source: runner.source,
+      path: resolvedPath,
+      pathRef: redactedPath(resolvedPath),
+      ...base,
+      lastError: "runner binary is missing or not executable",
+      nextAction: runner.source === "bundled" ? "Bundled runner is unavailable; reinstall/repair Linghun or continue with Node fallback." : "Repair runner execution permissions or keep using Node fallback."
+    };
+  }
+  const versionCommand = createNativeRunnerCommand(resolvedPath, ["version"]);
+  const version = spawnSync(versionCommand.command, versionCommand.args, {
+    cwd: dirname(resolvedPath),
+    encoding: "utf8",
+    timeout: NATIVE_RUNNER_VERSION_TIMEOUT_MS,
+    windowsHide: true
+  });
+  const raw = `${version.stdout ?? ""}
+${version.stderr ?? ""}`.trim();
+  if (version.error || version.status !== 0) {
+    return {
+      status: "unavailable",
+      enabled: true,
+      source: runner.source,
+      path: resolvedPath,
+      pathRef: redactedPath(resolvedPath),
+      ...base,
+      lastError: sanitizeDiagnosticText(
+        version.error instanceof Error ? version.error.message : raw || "version probe failed"
+      ),
+      nextAction: "Repair runner execution permissions or keep using Node fallback."
+    };
+  }
+  const parsed = parseRunnerJson(raw);
+  const protocol = stringValue(parsed.protocol, "unknown");
+  const runnerVersion = stringValue(parsed.version, "unknown");
+  if (protocol !== runner.expectedProtocol) {
+    return {
+      status: "protocol_mismatch",
+      enabled: true,
+      source: runner.source,
+      path: resolvedPath,
+      pathRef: redactedPath(resolvedPath),
+      version: runnerVersion,
+      protocol,
+      ...base,
+      lastError: `protocol mismatch: expected ${runner.expectedProtocol}, got ${protocol}`,
+      nextAction: "Use a compatible bundled/project-local runner build, or continue with Node fallback."
+    };
+  }
+  return {
+    status: "available",
+    enabled: true,
+    source: runner.source,
+    path: resolvedPath,
+    pathRef: redactedPath(resolvedPath),
+    version: runnerVersion,
+    protocol,
+    ...base,
+    nextAction: "Native runner may supervise approved durable job specs; Node fallback remains available."
+  };
+}
+function resolveNativeRunnerPath(runner, bundledCandidate) {
+  if (runner.source === "bundled") {
+    return bundledCandidate.path;
+  }
+  if (runner.path) {
+    return resolve(runner.path);
+  }
+  return void 0;
+}
+function getBundledNativeRunnerCandidate() {
+  const platformArch = getNativeRunnerPlatformArch();
+  const supported = NATIVE_RUNNER_BUNDLED_PLATFORM_ARCHES.has(platformArch);
+  const targetPlatform = platformArch.split("-")[0];
+  const names = targetPlatform === "win32" ? ["linghun-native-runner.exe", "linghun-native-runner.cjs"] : ["linghun-native-runner", "linghun-native-runner.cjs"];
+  const rootCandidates = getBundledNativeRunnerRoots();
+  for (const root of rootCandidates) {
+    for (const name of names) {
+      const candidate = join(root, platformArch, name);
+      if (existsSync(candidate)) {
+        return {
+          path: candidate,
+          ref: `bundled:${platformArch}/${name}`,
+          platformArch,
+          supported
+        };
+      }
+    }
+  }
+  return {
+    path: supported && rootCandidates[0] ? join(rootCandidates[0], platformArch, names[0] ?? "linghun-native-runner") : void 0,
+    ref: `bundled:${platformArch}/${names[0] ?? "linghun-native-runner"}`,
+    platformArch,
+    supported
+  };
+}
+function getNativeRunnerPlatformArch() {
+  const override = process.env.LINGHUN_NATIVE_RUNNER_PLATFORM_ARCH_TEST;
+  if (override && NATIVE_RUNNER_BUNDLED_PLATFORM_ARCHES.has(override)) {
+    return override;
+  }
+  return `${process.platform}-${process.arch}`;
+}
+function getBundledNativeRunnerRoots() {
+  const roots = [];
+  if (process.env.LINGHUN_NATIVE_RUNNER_BUNDLED_DIR) {
+    roots.push(process.env.LINGHUN_NATIVE_RUNNER_BUNDLED_DIR);
+  }
+  if (process.env[CLI_BUNDLED_ROOT_ENV]) {
+    roots.push(join(process.env[CLI_BUNDLED_ROOT_ENV], "native-runner"));
+  }
+  const moduleDir = dirname(fileURLToPath(import.meta.url));
+  roots.push(join(moduleDir, "..", "bundled", "native-runner"));
+  roots.push(join(moduleDir, "bundled", "native-runner"));
+  roots.push(join(moduleDir, "..", "native-runner"));
+  roots.push(join(moduleDir, "native-runner"));
+  return roots;
+}
+function isExecutableNativeRunnerCandidate(path) {
+  try {
+    accessSync(
+      path,
+      process.platform === "win32" ? constants.R_OK : constants.R_OK | constants.X_OK
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+function parseRunnerJson(raw) {
+  for (const line of raw.split(/\r?\n/u).filter(Boolean).reverse()) {
+    try {
+      const parsed = JSON.parse(line);
+      if (isRecord(parsed)) return parsed;
+    } catch {
+    }
+  }
+  return {};
+}
+function createNativeRunnerCommand(runnerPath, args) {
+  if (runnerPath.endsWith(".js") || runnerPath.endsWith(".cjs") || runnerPath.endsWith(".mjs")) {
+    return { command: process.execPath, args: [runnerPath, ...args] };
+  }
+  return { command: runnerPath, args };
+}
+function formatNativeRunnerProcessGuardContract() {
+  return NATIVE_RUNNER_PROCESS_GUARD_CONTRACT.map(
+    (line) => `- process guard contract: ${line}`
+  ).join("\n");
+}
+function formatApprovedRunnerSpecLine(job) {
+  const spec = job.runner?.spec;
+  if (!spec) {
+    return `- approved spec: none
+${formatNativeRunnerProcessGuardContract()}`;
+  }
+  return [
+    `- approved spec: id=${spec.id}; taskKind=${spec.approvedTaskKind}; cwdRef=${redactedPath(spec.cwd)}; timeoutMs=${spec.timeoutMs}; expectedProtocol=${spec.expectedProtocol}; envAllowlist=${spec.envAllowlist.join(",") || "none"}; redactedEnvRefs=${spec.redactedEnvRefs.join(",") || "none"}; evidenceRefs=${spec.evidenceRefs.join(",") || "none"}; logRefs=state/stdout/stderr/jobLog/fullOutput/report`,
+    formatNativeRunnerProcessGuardContract()
+  ].join("\n");
+}
+function createApprovedRunnerJobSpec(context, job, resolution) {
+  const runnerRoot = join(dirname(job.logPath), "runner");
+  return {
+    id: job.id,
+    approvedTaskKind: "durable_job_supervisor",
+    cwd: context.projectPath,
+    envAllowlist: [],
+    redactedEnvRefs: ["PATH:runtime-only"],
+    timeoutMs: Math.min(job.timeoutMs, context.config.nativeRunner.timeoutMs),
+    logPaths: {
+      state: join(runnerRoot, job.id, "state.json"),
+      stdout: join(runnerRoot, job.id, "stdout.log"),
+      stderr: join(runnerRoot, job.id, "stderr.log"),
+      jobLog: job.logPath,
+      fullOutput: job.fullOutputPath,
+      report: job.reportPath
+    },
+    expectedProtocol: resolution.protocol ?? context.config.nativeRunner.expectedProtocol,
+    permissionRef: job.permissionPolicy,
+    evidenceRefs: job.evidenceRefs.map((item) => item.id),
+    runnerRoot
+  };
+}
+async function startRunnerForDurableJob(context, job, deps) {
+  const resolution = resolveNativeRunner(context.config);
+  const spec = createApprovedRunnerJobSpec(context, job, resolution);
+  const result = await startApprovedRunnerSpec(context, spec, resolution);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  job.runner = {
+    enabled: resolution.enabled,
+    status: result.status,
+    resolution: resolution.status,
+    adapter: result.adapter,
+    protocol: result.protocol ?? resolution.protocol,
+    version: result.version ?? resolution.version,
+    pathRef: resolution.pathRef,
+    spec,
+    startedAt: now,
+    updatedAt: now,
+    completedAt: result.status === "completed" || result.status === "node_fallback" ? now : void 0,
+    heartbeatAt: result.heartbeatAt,
+    logRefs: result.logRefs,
+    lastError: result.lastError,
+    fallbackReason: result.fallbackReason,
+    nextAction: result.status === "node_fallback" ? "Node/TUI fallback is active; runner fallback is non-PASS and visible in report/background." : result.status === "running" ? "Native runner is supervising an approved long-running task; verification remains partial until verified separately." : "Native runner reached a terminal lifecycle state; verification remains partial until verified separately."
+  };
+  await deps.appendJobLog(
+    job,
+    `runner adapter ${job.runner.adapter}; status ${job.runner.status}; resolution ${job.runner.resolution}; fallback ${job.runner.fallbackReason ?? "none"}`
+  );
+}
+async function startApprovedRunnerSpec(_context, spec, resolution) {
+  if (resolution.status !== "available" || !resolution.path) {
+    return {
+      status: "node_fallback",
+      adapter: "node",
+      protocol: resolution.protocol,
+      version: resolution.version,
+      lastError: resolution.lastError,
+      fallbackReason: resolution.status
+    };
+  }
+  await mkdir(spec.runnerRoot, { recursive: true });
+  const taskDurationMs = spec.timeoutMs <= NATIVE_RUNNER_APPROVED_TASK_HEARTBEAT_MS * 8 ? spec.timeoutMs + NATIVE_RUNNER_APPROVED_TASK_HEARTBEAT_MS * 5 : 1200;
+  const startCommand = createNativeRunnerCommand(resolution.path, [
+    "start",
+    "--id",
+    spec.id,
+    "--root",
+    spec.runnerRoot,
+    "--timeout-ms",
+    String(spec.timeoutMs),
+    "--heartbeat-ms",
+    String(NATIVE_RUNNER_APPROVED_TASK_HEARTBEAT_MS),
+    "--",
+    process.execPath,
+    "-e",
+    NATIVE_RUNNER_APPROVED_TASK_SCRIPT,
+    String(taskDurationMs)
+  ]);
+  let child;
+  let spawnError;
+  try {
+    child = spawn(startCommand.command, startCommand.args, {
+      cwd: spec.cwd,
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true
+    });
+    child.once("error", (error) => {
+      spawnError = sanitizeDiagnosticText(error instanceof Error ? error.message : String(error));
+    });
+    child.unref();
+    if (child.pid) _runnerPids.set(spec.id, child.pid);
+  } catch (error) {
+    return {
+      status: "node_fallback",
+      adapter: "node",
+      protocol: resolution.protocol,
+      version: resolution.version,
+      lastError: sanitizeDiagnosticText(error instanceof Error ? error.message : String(error)),
+      fallbackReason: "start_failed"
+    };
+  }
+  const state = await waitForRunnerState(spec, NATIVE_RUNNER_START_STATE_WAIT_MS);
+  if (!state) {
+    const failed = await new Promise((resolve2) => {
+      if (child.exitCode !== null) {
+        resolve2(true);
+        return;
+      }
+      child.once("exit", () => resolve2(true));
+      setTimeout(() => resolve2(false), 25);
+    });
+    return {
+      status: "node_fallback",
+      adapter: "node",
+      protocol: resolution.protocol,
+      version: resolution.version,
+      lastError: spawnError ? `runner spawn error: ${spawnError}` : failed ? "runner start failed before writing observable state" : "runner did not write observable state before startup timeout",
+      fallbackReason: "start_failed"
+    };
+  }
+  const status = mapNativeRunnerStatus(stringValue(state.status, "running"));
+  return {
+    status,
+    adapter: "native",
+    protocol: stringValue(state.protocol, resolution.protocol ?? "unknown"),
+    version: resolution.version,
+    heartbeatAt: runnerHeartbeatValue(state),
+    logRefs: runnerLogRefs(spec, state),
+    lastError: status === "failed" ? sanitizeDiagnosticText(stringValue(state.error, "runner start failed")) : void 0
+  };
+}
+async function waitForRunnerState(spec, timeoutMs) {
+  const started = Date.now();
+  while (Date.now() - started <= timeoutMs) {
+    const state = await readRunnerState(spec);
+    if (state) return state;
+    await new Promise((resolve2) => setTimeout(resolve2, 25));
+  }
+  return void 0;
+}
+async function readRunnerState(spec) {
+  try {
+    const parsed = JSON.parse(await readFile(spec.logPaths.state, "utf8"));
+    return isRecord(parsed) ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function runnerHeartbeatValue(state) {
+  const heartbeatAt = state.heartbeatAt;
+  if (typeof heartbeatAt === "number" || typeof heartbeatAt === "string") {
+    return String(heartbeatAt);
+  }
+  const updatedAt = state.updatedAt;
+  return typeof updatedAt === "number" || typeof updatedAt === "string" ? String(updatedAt) : void 0;
+}
+function runnerLogRefs(spec, state) {
+  return {
+    state: "state.json",
+    stdout: safeRunnerLogRef(state.stdoutPath, spec.logPaths.stdout),
+    stderr: safeRunnerLogRef(state.stderrPath, spec.logPaths.stderr)
+  };
+}
+function safeRunnerLogRef(value, fallbackPath) {
+  const fallback = basename(fallbackPath);
+  if (typeof value !== "string" || value.trim().length === 0) {
+    return isSafeRunnerRelativeLogRef(fallback) ? fallback : "log";
+  }
+  const ref = sanitizeDiagnosticText(value.trim());
+  if (isSafeRunnerRelativeLogRef(ref)) {
+    return ref;
+  }
+  const redactedBasename = ref.replaceAll("\\", "/").split("/").filter(Boolean).at(-1);
+  if (redactedBasename && isSafeRunnerRelativeLogRef(redactedBasename)) {
+    return `present:${redactedBasename}`;
+  }
+  return isSafeRunnerRelativeLogRef(fallback) ? `present:${fallback}` : "present:log";
+}
+function isSafeRunnerRelativeLogRef(ref) {
+  return /^[A-Za-z0-9._-]+$/u.test(ref) && !ref.includes("..") && !ref.includes(":");
+}
+function mapNativeRunnerStatus(status) {
+  if (status === "timeout") return "timeout";
+  if (status === "cancelled") return "cancelled";
+  if (status === "failed" || status === "duplicate" || status === "missing") return "failed";
+  if (status === "running") return "running";
+  if (status === "completed") return "completed";
+  return "failed";
+}
+function refreshRunnerStatusForJob(context, job, deps) {
+  if (!job.runner?.spec || job.runner.adapter !== "native") return;
+  const resolution = resolveNativeRunner(context.config);
+  if (resolution.status !== "available" || !resolution.path) {
+    markJobRunnerFallback(job, resolution.status, resolution.lastError ?? resolution.status);
+    return;
+  }
+  const statusCommand = createNativeRunnerCommand(resolution.path, [
+    "status",
+    "--id",
+    job.runner.spec.id,
+    "--root",
+    job.runner.spec.runnerRoot
+  ]);
+  const status = spawnSync(statusCommand.command, statusCommand.args, {
+    encoding: "utf8",
+    timeout: NATIVE_RUNNER_VERSION_TIMEOUT_MS,
+    windowsHide: true
+  });
+  const raw = `${status.stdout ?? ""}
+${status.stderr ?? ""}`.trim();
+  if (status.error || status.status !== 0) {
+    markJobRunnerFallback(job, "available", raw || "runner status failed", "status_failed");
+    return;
+  }
+  const parsed = parseRunnerJson(raw);
+  const mapped = mapNativeRunnerStatus(stringValue(parsed.status, job.runner.status));
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  job.runner.status = mapped;
+  job.runner.updatedAt = now;
+  job.runner.heartbeatAt = runnerHeartbeatValue(parsed) ?? job.runner.heartbeatAt;
+  job.runner.logRefs = runnerLogRefs(job.runner.spec, parsed);
+  if (mapped !== "running") job.runner.completedAt ??= now;
+  if (mapped === "timeout" || mapped === "cancelled" || mapped === "failed") {
+    job.status = mapped;
+    job.pauseReason = `runner_${mapped}`;
+    job.updatedAt = now;
+    job.endedAt = now;
+    job.result = {
+      status: mapped,
+      summary: `Native runner reported ${mapped}; no PASS evidence generated.`,
+      facts: [formatJobRunnerInline(job)],
+      evidenceRefs: job.evidenceRefs.map((item) => item.id),
+      generatedAt: now
+    };
+    deps.rescheduleDurableJobAgents(job);
+  }
+}
+async function stopRunnerForDurableJob(context, job, deps) {
+  if (!job.runner?.spec || job.runner.adapter !== "native") {
+    markJobRunnerTerminal(job, "cancelled", "node fallback or no native runner to stop");
+    return;
+  }
+  const resolution = resolveNativeRunner(context.config);
+  let stopRequested = false;
+  let fallbackKillAttempted = false;
+  if (resolution.status === "available" && resolution.path) {
+    const stopCommand = createNativeRunnerCommand(resolution.path, [
+      "stop",
+      "--id",
+      job.runner.spec.id,
+      "--root",
+      job.runner.spec.runnerRoot
+    ]);
+    spawnSync(stopCommand.command, stopCommand.args, {
+      encoding: "utf8",
+      timeout: NATIVE_RUNNER_VERSION_TIMEOUT_MS,
+      windowsHide: true
+    });
+    stopRequested = true;
+  } else {
+    const pid = _runnerPids.get(job.runner.spec.id);
+    if (pid !== void 0) {
+      try {
+        if (process.platform === "win32") {
+          spawnSync("taskkill", ["/pid", String(pid), "/t", "/f"], { windowsHide: true });
+        } else {
+          try {
+            process.kill(-pid, "SIGKILL");
+          } catch {
+            process.kill(pid, "SIGKILL");
+          }
+        }
+        fallbackKillAttempted = true;
+      } catch {
+      }
+    }
+  }
+  _runnerPids.delete(job.runner.spec.id);
+  markJobRunnerTerminal(job, "cancelled", "user_cancelled");
+  await deps.appendJobLog(
+    job,
+    stopRequested ? "runner stop --id requested; cancelled is non-PASS" : fallbackKillAttempted ? "runner binary unavailable; fallback pid/taskkill used; cancelled is non-PASS" : "runner stop unavailable; no pid/taskkill fallback available; cancelled is non-PASS"
+  );
+}
+function markJobRunnerTerminal(job, status, reason) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const shouldSyncActiveJob = job.status === "created" || job.status === "running" || job.status === "sleeping";
+  if (shouldSyncActiveJob && (status === "cancelled" || status === "timeout" || status === "failed" || status === "stale")) {
+    job.status = status;
+    job.pauseReason = `runner_${status}`;
+    job.updatedAt = now;
+    job.endedAt = now;
+    job.result = {
+      status,
+      summary: `Native runner moved to ${status}; no PASS evidence generated.`,
+      facts: [sanitizeDiagnosticText(reason), formatJobRunnerInline(job)],
+      evidenceRefs: job.evidenceRefs.map((item) => item.id),
+      generatedAt: now
+    };
+  }
+  job.runner = {
+    enabled: job.runner?.enabled ?? false,
+    status,
+    resolution: job.runner?.resolution ?? "unavailable",
+    adapter: job.runner?.adapter ?? "node",
+    protocol: job.runner?.protocol,
+    version: job.runner?.version,
+    pathRef: job.runner?.pathRef,
+    spec: job.runner?.spec,
+    startedAt: job.runner?.startedAt,
+    updatedAt: now,
+    completedAt: now,
+    heartbeatAt: job.runner?.heartbeatAt,
+    logRefs: job.runner?.logRefs,
+    lastError: sanitizeDiagnosticText(reason),
+    fallbackReason: job.runner?.fallbackReason,
+    nextAction: "Inspect /job report and logs; runner terminal states are not verification PASS."
+  };
+}
+function markJobRunnerFallback(job, resolution, reason, fallbackReason = resolution) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  job.runner = {
+    enabled: job.runner?.enabled ?? true,
+    status: "node_fallback",
+    resolution,
+    adapter: "node",
+    protocol: job.runner?.protocol,
+    version: job.runner?.version,
+    pathRef: job.runner?.pathRef,
+    spec: job.runner?.spec,
+    startedAt: job.runner?.startedAt,
+    updatedAt: now,
+    completedAt: now,
+    heartbeatAt: job.runner?.heartbeatAt,
+    logRefs: job.runner?.logRefs,
+    lastError: sanitizeDiagnosticText(reason),
+    fallbackReason,
+    nextAction: "Node/TUI fallback is active; runner fallback is non-PASS and visible in report/background."
+  };
+}
+
+export {
+  NATIVE_RUNNER_PROCESS_GUARD_CONTRACT,
+  resolveNativeRunner,
+  formatNativeRunnerProcessGuardContract,
+  formatApprovedRunnerSpecLine,
+  createApprovedRunnerJobSpec,
+  startRunnerForDurableJob,
+  refreshRunnerStatusForJob,
+  stopRunnerForDurableJob,
+  markJobRunnerTerminal,
+  markJobRunnerFallback
+};

package/dist/chunk-BFVPLGAC.js

@@ -0,0 +1,93 @@
+// src/index-tool-runtime.ts
+var INDEX_STATUS_INSPECT = "IndexStatusInspect";
+var INDEX_REFRESH = "IndexRefresh";
+var INDEX_REPAIR = "IndexRepair";
+var INDEX_TOOL_NAMES = [
+  INDEX_STATUS_INSPECT,
+  INDEX_REFRESH,
+  INDEX_REPAIR
+];
+function isIndexToolName(name) {
+  return INDEX_TOOL_NAMES.includes(name);
+}
+function isMutatingIndexTool(name) {
+  return name === INDEX_REFRESH || name === INDEX_REPAIR;
+}
+function createIndexToolDefinitions() {
+  return [
+    {
+      name: INDEX_STATUS_INSPECT,
+      description: "Inspect the current codebase-memory index status for this project (refreshes the status read, but does NOT rebuild the index). Read-only and safe to call without confirmation. Returns enabled/status/projectName/nodes/edges. Use this when the user asks whether the index is ready or what its current state is. Do NOT claim the index was refreshed \u2014 this only reads status.",
+      inputSchema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          reason: { type: "string" }
+        }
+      }
+    },
+    {
+      name: INDEX_REFRESH,
+      description: "Refresh (rebuild) the codebase-memory index for this project, reusing the controlled /index refresh path. This writes workspace-local index artifacts and runs the index runtime. Permission behavior: default asks for confirmation; auto-review may directly run an ordinary workspace refresh; plan refuses mutating execution; dangerous repair, persistent ignore changes, path-boundary, shell/network/install/delete risks still go through the permission pipeline. Call this tool to actually refresh the index when the user asks to update/refresh/rebuild the index. Do NOT claim the index was refreshed unless this tool returns success.",
+      inputSchema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          force: { type: "boolean" },
+          reason: { type: "string" }
+        }
+      }
+    },
+    {
+      name: INDEX_REPAIR,
+      description: "Persist index skip suggestions after a refresh automatically skipped large/generated files: append the missing ignore entries (.linghunignore/.cbmignore) and then refresh, reusing the controlled /index repair path. Permission behavior: default asks before writing; auto-review can proceed only when the workspace-local ignore/index write is low risk; plan refuses mutating execution; dangerous or path-boundary changes still ask/deny through the permission pipeline. Only meaningful when skip suggestions exist. Call this tool to actually repair-and-refresh; do NOT claim it succeeded without a success result.",
+      inputSchema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          reason: { type: "string" }
+        }
+      }
+    }
+  ];
+}
+function asRecord(input) {
+  return input && typeof input === "object" && !Array.isArray(input) ? input : {};
+}
+function parseIndexRefreshInput(input) {
+  const obj = asRecord(input);
+  return {
+    force: typeof obj.force === "boolean" ? obj.force : void 0,
+    reason: typeof obj.reason === "string" ? obj.reason : void 0
+  };
+}
+function summarizeIndexStatusInspect(status, projectName, nodes, edges, language) {
+  const isEn = language === "en-US";
+  const project = projectName ?? (isEn ? "(not selected)" : "\uFF08\u672A\u9009\u4E2D\uFF09");
+  const counts = nodes !== void 0 || edges !== void 0 ? isEn ? `; graph ${nodes ?? "-"} node(s), ${edges ?? "-"} edge(s)` : `\uFF1B\u56FE ${nodes ?? "-"} \u4E2A\u8282\u70B9\u3001${edges ?? "-"} \u6761\u8FB9` : "";
+  return isEn ? `Index status inspected (not refreshed): status ${status}; project ${project}${counts}.` : `\u5DF2\u68C0\u67E5\u7D22\u5F15\u72B6\u6001\uFF08\u672A\u5237\u65B0\uFF09\uFF1A\u72B6\u6001 ${status}\uFF1B\u9879\u76EE ${project}${counts}\u3002`;
+}
+function summarizeIndexRefreshOutcome(action, status, language) {
+  const isEn = language === "en-US";
+  if (status === "stale") {
+    if (action === "repair") {
+      return isEn ? "Index repair ran and refresh was attempted; current status is still stale." : "\u7D22\u5F15\u4FEE\u590D\u5DF2\u6267\u884C\u5E76\u5C1D\u8BD5\u5237\u65B0\uFF1B\u5F53\u524D\u72B6\u6001\u4ECD\u4E3A stale\u3002";
+    }
+    return isEn ? "Index refresh ran; current status is still stale." : "\u7D22\u5F15\u5237\u65B0\u5DF2\u6267\u884C\uFF1B\u5F53\u524D\u72B6\u6001\u4ECD\u4E3A stale\u3002";
+  }
+  const label = action === "repair" ? isEn ? "repaired and refreshed" : "\u5DF2\u4FEE\u590D\u5E76\u5237\u65B0" : isEn ? "refreshed" : "\u5DF2\u5237\u65B0";
+  return isEn ? `Index ${label}: status ${status}.` : `\u7D22\u5F15${label}\uFF1A\u72B6\u6001 ${status}\u3002`;
+}
+
+export {
+  INDEX_STATUS_INSPECT,
+  INDEX_REFRESH,
+  INDEX_REPAIR,
+  INDEX_TOOL_NAMES,
+  isIndexToolName,
+  isMutatingIndexTool,
+  createIndexToolDefinitions,
+  parseIndexRefreshInput,
+  summarizeIndexStatusInspect,
+  summarizeIndexRefreshOutcome
+};