mergen-server 1.4.0

package/dist/intelligence/rollback.js

@@ -0,0 +1,137 @@
+import { executeRemediation } from "./autonomy.js";
+import logger from "../sensor/logger.js";
+function deriveRollback(command, stdout) {
+  const cmd = command.trim();
+  const kubectlRestart = cmd.match(/^kubectl\s+rollout\s+restart\s+(deploy(?:ment)?\/\S+)/i);
+  if (kubectlRestart) {
+    return { type: "command", command: `kubectl rollout undo ${kubectlRestart[1]}` };
+  }
+  const kubectlRestartNs = cmd.match(/^kubectl\s+rollout\s+restart\s+(?:-n\s+\S+\s+)(deploy(?:ment)?\/\S+)/i);
+  if (kubectlRestartNs) {
+    const nsMatch = cmd.match(/-n\s+(\S+)/);
+    const ns = nsMatch ? ` -n ${nsMatch[1]}` : "";
+    return { type: "command", command: `kubectl rollout undo${ns} ${kubectlRestartNs[1]}` };
+  }
+  const kubectlSetImage = cmd.match(/^kubectl\s+set\s+image\s+(?:deploy(?:ment)?\/)?(\S+)/i);
+  if (kubectlSetImage) {
+    return { type: "command", command: `kubectl rollout undo deploy/${kubectlSetImage[1]}` };
+  }
+  const helmUpgrade = cmd.match(/^helm\s+upgrade\s+(\S+)/i);
+  if (helmUpgrade) {
+    return { type: "command", command: `helm rollback ${helmUpgrade[1]}` };
+  }
+  const npmInstall = cmd.match(/^npm\s+install\s+(\S+)@(\S+)/i);
+  if (npmInstall) {
+    const [, pkg, ver] = npmInstall;
+    const prevMatch = stdout.match(new RegExp(`removed.*${escapeRegex(pkg)}@(\\S+)`, "i"));
+    if (prevMatch) {
+      return { type: "command", command: `npm install ${pkg}@${prevMatch[1]}` };
+    }
+    return { type: "none", reason: `can't determine prior ${pkg} version \u2014 check package-lock.json and revert manually` };
+  }
+  const pipInstall = cmd.match(/^pip\s+install\s+(\S+)==(\S+)/i);
+  if (pipInstall) {
+    const [, pkg] = pipInstall;
+    return { type: "none", reason: `can't determine prior ${pkg} version \u2014 revert requirements.txt and run pip install manually` };
+  }
+  const yarnAdd = cmd.match(/^yarn\s+add\s+(\S+)@(\S+)/i);
+  if (yarnAdd) {
+    const [, pkg] = yarnAdd;
+    return { type: "none", reason: `can't determine prior ${pkg} version \u2014 check yarn.lock and revert manually` };
+  }
+  if (cmd.startsWith("git revert")) {
+    return { type: "command", command: "git revert HEAD --no-edit" };
+  }
+  const dockerComposeUp = cmd.match(/^docker-compose\s+up\b(.*)$/i);
+  if (dockerComposeUp) {
+    const serviceArg = dockerComposeUp[1].trim().split(/\s+/).filter((a) => a && !a.startsWith("-")).pop();
+    return { type: "command", command: serviceArg ? `docker-compose stop ${serviceArg}` : "docker-compose down" };
+  }
+  if (/^docker-compose\s+down\b/i.test(cmd)) {
+    return { type: "none", reason: "docker-compose down already tore down state \u2014 nothing to roll back to; redeploy manually if this was unintended" };
+  }
+  const systemctlEnable = cmd.match(/^systemctl\s+enable\s+(\S+)/i);
+  if (systemctlEnable) {
+    return { type: "command", command: `systemctl disable ${systemctlEnable[1]}` };
+  }
+  const systemctlDisable = cmd.match(/^systemctl\s+disable\s+(\S+)/i);
+  if (systemctlDisable) {
+    return { type: "command", command: `systemctl enable ${systemctlDisable[1]}` };
+  }
+  if (/^(pm2|systemctl|service|docker|supervisorctl)\s/.test(cmd) || /^kill\s+-[1H]/.test(cmd) || /^pkill\s+-[1H]/.test(cmd)) {
+    return { type: "none", reason: "restart commands are stateless \u2014 re-run the fix or restart manually" };
+  }
+  const backupMatch = cmd.match(/\b(?:cp|mv)\s+(\S+)\s+(\1\.bak\S*)/i);
+  if (backupMatch) {
+    const [, original, backupPath] = backupMatch;
+    return { type: "command", command: `mv ${backupPath} ${original}` };
+  }
+  return { type: "none", reason: "no rollback strategy known for this command type \u2014 revert manually" };
+}
+async function executeRollback(strategy, opts) {
+  if (strategy.type === "none") {
+    return { ok: false, message: strategy.reason };
+  }
+  logger.info({ command: strategy.command }, "rollback: executing");
+  const result = await executeRemediation(strategy.command, {
+    cwd: opts?.cwd,
+    actor: opts?.actor ?? "autopilot-rollback"
+  });
+  if (result.blocked) {
+    return { ok: false, message: `rollback blocked: ${result.blockReason}` };
+  }
+  if (!result.ok) {
+    return { ok: false, message: `rollback exited ${result.exitCode}: ${result.stderr.slice(0, 200)}` };
+  }
+  return { ok: true, message: strategy.command };
+}
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function generateRollbackPlan(intent) {
+  const { files, commands = [], featureFlag = null } = intent;
+  const anticipatedRollbackCommands = [];
+  for (const cmd of commands) {
+    const strategy = deriveRollback(cmd, "");
+    if (strategy.type === "command") {
+      anticipatedRollbackCommands.push(strategy.command);
+    }
+  }
+  const canAutoRollback = featureFlag !== null || anticipatedRollbackCommands.length > 0 && anticipatedRollbackCommands.length === commands.length;
+  const rollbackProcedure = [];
+  if (featureFlag) {
+    rollbackProcedure.push(`Disable feature flag: ${featureFlag}`);
+    rollbackProcedure.push("Verify error rates return to baseline via validate_fix or GET /validate");
+  }
+  if (anticipatedRollbackCommands.length > 0) {
+    rollbackProcedure.push("Execute rollback commands:");
+    for (const cmd of anticipatedRollbackCommands) {
+      rollbackProcedure.push(`  ${cmd}`);
+    }
+    rollbackProcedure.push("Validate recovery: call validate_fix or check GET /validate after 60 s");
+  }
+  if (files.length > 0 && anticipatedRollbackCommands.length === 0 && !featureFlag) {
+    rollbackProcedure.push("Revert the following files using git:");
+    for (const f of files) rollbackProcedure.push(`  git checkout HEAD -- ${f}`);
+    rollbackProcedure.push("Or use: git revert HEAD --no-edit");
+    rollbackProcedure.push("Redeploy / restart the service after revert");
+  }
+  if (rollbackProcedure.length === 0) {
+    rollbackProcedure.push("No automated rollback available \u2014 manual intervention required");
+    rollbackProcedure.push("Document the issue in the override corpus before proceeding");
+  }
+  const estimatedRollbackMs = featureFlag ? 1e4 : anticipatedRollbackCommands.length > 0 ? 6e4 : 12e4;
+  return {
+    filesModified: files,
+    featureFlag,
+    rollbackProcedure,
+    canAutoRollback,
+    estimatedRollbackMs,
+    anticipatedRollbackCommands
+  };
+}
+export {
+  deriveRollback,
+  executeRollback,
+  generateRollbackPlan
+};

package/dist/intelligence/runbook-updater.js

@@ -0,0 +1,143 @@
+import fs from "fs";
+import path from "path";
+import { USER_RUNBOOKS_DIR, zeroRetentionMode } from "../sensor/paths.js";
+import { postmortemStore } from "./postmortem-store.js";
+import logger from "../sensor/logger.js";
+function fmtMs(ms) {
+  if (ms < 6e4) return `${Math.round(ms / 1e3)}s`;
+  const min = Math.floor(ms / 6e4);
+  const sec = Math.round(ms % 6e4 / 1e3);
+  return sec > 0 ? `${min}m ${sec}s` : `${min}m`;
+}
+function tagToSlug(tag) {
+  return tag.replace(/^infra_/, "").replace(/_/g, "-");
+}
+function tagToTitle(tag) {
+  return tag.replace(/^infra_/, "").replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function aggregateFixStats(postmortems) {
+  const map = /* @__PURE__ */ new Map();
+  for (const pm of postmortems) {
+    if (!pm.fixCommand) continue;
+    const entry = map.get(pm.fixCommand) ?? { applied: 0, resolved: 0, mttrSamples: [] };
+    entry.applied++;
+    if (pm.causallyCorrect) entry.resolved++;
+    if (pm.mttrMs != null) entry.mttrSamples.push(pm.mttrMs);
+    map.set(pm.fixCommand, entry);
+  }
+  return [...map.entries()].map(([cmd, s]) => ({
+    command: cmd,
+    timesApplied: s.applied,
+    timesResolved: s.resolved,
+    successRate: s.applied > 0 ? Math.round(s.resolved / s.applied * 100) : 0,
+    avgMttrMs: s.mttrSamples.length > 0 ? s.mttrSamples.reduce((a, b) => a + b, 0) / s.mttrSamples.length : null
+  })).sort((a, b) => b.timesApplied - a.timesApplied || b.successRate - a.successRate).slice(0, 5);
+}
+function yamlStr(value) {
+  if (/[:#,\[\]{}&*!|>'"%@`]/.test(value) || value.includes("\n")) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  }
+  return value;
+}
+function buildRunbookYaml(tag, postmortems, fixes) {
+  const total = postmortems.length;
+  const autoCount = postmortems.filter((pm) => pm.resolvedAutonomously).length;
+  const autoRate = total > 0 ? Math.round(autoCount / total * 100) : 0;
+  const mttrSamples = postmortems.filter((pm) => pm.mttrMs != null).map((pm) => pm.mttrMs);
+  const avgMttr = mttrSamples.length > 0 ? fmtMs(mttrSamples.reduce((a, b) => a + b, 0) / mttrSamples.length) : "unknown";
+  const topFix = fixes[0]?.command ?? null;
+  const slug = tagToSlug(tag);
+  const title = tagToTitle(tag);
+  const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const services = [...new Set(postmortems.map((pm) => pm.service))].slice(0, 5);
+  const lines = [
+    `# Auto-generated by Mergen \u2014 do not edit manually.`,
+    `# Source: ${total} incident postmortems. Re-generated on every resolution.`,
+    `name: ${yamlStr(slug)}`,
+    `title: ${yamlStr(title)}`,
+    `description: ${yamlStr(`Auto-generated runbook for ${title} \u2014 based on ${total} real incidents.`)}`,
+    ``,
+    `corpus_stats:`,
+    `  last_updated: ${yamlStr(date)}`,
+    `  total_incidents: ${total}`,
+    `  avg_mttr: ${yamlStr(avgMttr)}`,
+    `  autonomous_rate_pct: ${autoRate}`,
+    `  services: [${services.map(yamlStr).join(", ")}]`,
+    `  top_fix: ${topFix ? yamlStr(topFix) : "null"}`,
+    ``
+  ];
+  if (fixes.length > 0) {
+    lines.push(`verified_fixes:`);
+    for (const f of fixes) {
+      const mttr = f.avgMttrMs != null ? fmtMs(f.avgMttrMs) : "unknown";
+      lines.push(`  - command: ${yamlStr(f.command)}`);
+      lines.push(`    times_applied: ${f.timesApplied}`);
+      lines.push(`    success_rate_pct: ${f.successRate}`);
+      lines.push(`    avg_mttr: ${yamlStr(mttr)}`);
+    }
+    lines.push(``);
+  }
+  const rootCauses = [...new Set(
+    postmortems.map((pm) => pm.rootCause.split(".")[0].trim()).filter(Boolean)
+  )].slice(0, 3);
+  if (rootCauses.length > 0) {
+    lines.push(`common_root_causes:`);
+    for (const rc of rootCauses) {
+      lines.push(`  - ${yamlStr(rc)}`);
+    }
+    lines.push(``);
+  }
+  lines.push(`steps:`);
+  lines.push(`  - name: Confirm current error state`);
+  lines.push(`    tool: analyze_runtime`);
+  lines.push(``);
+  lines.push(`  - name: Search for similar past incidents`);
+  lines.push(`    tool: search_postmortems`);
+  lines.push(`    params:`);
+  lines.push(`      query: ${yamlStr(slug.replace(/-/g, " "))}`);
+  lines.push(``);
+  if (topFix) {
+    lines.push(`  - name: Check fix history before applying`);
+    lines.push(`    tool: check_fix_history`);
+    lines.push(`    params:`);
+    lines.push(`      command: ${yamlStr(topFix)}`);
+    lines.push(``);
+    lines.push(`  - name: Apply top verified fix (${fixes[0].successRate}% success rate)`);
+    lines.push(`    tool: execute_fix`);
+    lines.push(`    params:`);
+    lines.push(`      command: ${yamlStr(topFix)}`);
+    lines.push(`      confirm: true`);
+    lines.push(``);
+  }
+  lines.push(`  - name: Validate resolution`);
+  lines.push(`    tool: validate_fix`);
+  lines.push(``);
+  lines.push(`  - name: Suggest follow-up actions`);
+  lines.push(`    tool: suggest_followups`);
+  lines.push(``);
+  return lines.join("\n");
+}
+function updateRunbookFromPostmortem(pm) {
+  if (zeroRetentionMode()) return;
+  try {
+    const related = postmortemStore.getByTag(pm.tag, 100);
+    if (related.length < 2) return;
+    const fixes = aggregateFixStats(related);
+    const yaml = buildRunbookYaml(pm.tag, related, fixes);
+    const slug = tagToSlug(pm.tag);
+    const outPath = path.join(USER_RUNBOOKS_DIR, `${slug}.yaml`);
+    fs.mkdirSync(USER_RUNBOOKS_DIR, { recursive: true });
+    const tmp = `${outPath}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, yaml, "utf8");
+    fs.renameSync(tmp, outPath);
+    logger.info(
+      { tag: pm.tag, incidents: related.length, fixes: fixes.length, path: outPath },
+      "runbook-updater: runbook updated"
+    );
+  } catch (err) {
+    logger.warn({ err, tag: pm.tag }, "runbook-updater: failed to update runbook");
+  }
+}
+export {
+  updateRunbookFromPostmortem
+};

package/dist/intelligence/sandbox.js

@@ -0,0 +1,194 @@
+import { spawn, execFile } from "child_process";
+import { promisify } from "util";
+import { realpathSync } from "fs";
+import { tmpdir } from "os";
+import logger from "../sensor/logger.js";
+const execFileAsync = promisify(execFile);
+function getRequestedSandboxBackend() {
+  const v = process.env.MERGEN_SANDBOX;
+  return v === "docker" || v === "seatbelt" ? v : null;
+}
+function isSandboxRequested() {
+  return getRequestedSandboxBackend() !== null;
+}
+function resolveAllowNetwork(requested) {
+  const raw = requested ?? process.env.MERGEN_SANDBOX_NETWORK ?? "none";
+  if (raw === "bridge") return true;
+  if (raw !== "none") {
+    logger.warn(
+      { value: raw },
+      `sandbox: MERGEN_SANDBOX_NETWORK="${raw}" is not a recognized value ('none' or 'bridge') \u2014 failing closed to no network access.`
+    );
+  }
+  return false;
+}
+async function isDockerAvailable() {
+  try {
+    await execFileAsync("docker", ["info", "--format", "{{.ServerVersion}}"], { timeout: 5e3 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function isDockerRuntimeAvailable(runtime) {
+  try {
+    const { stdout } = await execFileAsync("docker", ["info", "--format", "{{json .Runtimes}}"], { timeout: 5e3 });
+    const runtimes = JSON.parse(stdout || "{}");
+    return runtime in runtimes;
+  } catch {
+    return false;
+  }
+}
+async function isMacSandboxAvailable() {
+  if (process.platform !== "darwin") return false;
+  try {
+    await execFileAsync("sandbox-exec", ["-p", "(version 1)(allow default)", "/usr/bin/true"], { timeout: 5e3 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function getMacSandboxCapability() {
+  const requested = getRequestedSandboxBackend() === "seatbelt";
+  return { requested, platform: process.platform, supported: requested && process.platform === "darwin" };
+}
+function sbplStringLiteral(s) {
+  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function resolvePathForProfile(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+function buildSeatbeltProfile(opts) {
+  const writeAllows = opts.writablePaths.map(resolvePathForProfile).map((p) => `  (subpath "${sbplStringLiteral(p)}")`).join("\n");
+  return [
+    "(version 1)",
+    "(deny default)",
+    "(allow file-read*)",
+    "(allow process-fork)",
+    "(allow process-exec)",
+    "(allow signal (target self))",
+    "(allow sysctl-read)",
+    "(allow mach-lookup)",
+    "(allow iokit-open)",
+    // Almost every real invocation redirects stdout/stderr or a sink
+    // argument through /dev/null at some point (`cmd > /dev/null 2>&1`,
+    // `curl -o /dev/null`, ...) — without this, file-write* alone leaves
+    // /dev/null unwritable and such commands fail with a confusing
+    // "Operation not permitted" that has nothing to do with the actual
+    // workspace boundary being enforced. Not a meaningful security
+    // boundary either way, so it's unconditional rather than tied to
+    // writablePaths.
+    '(allow file-write-data (literal "/dev/null"))',
+    "(allow file-write*",
+    writeAllows,
+    ")",
+    opts.allowNetwork ? "(allow network*)" : ";; network denied by default (MERGEN_SANDBOX_NETWORK=bridge to allow)"
+  ].filter(Boolean).join("\n");
+}
+function extraWritablePathsFromEnv() {
+  return (process.env.MERGEN_SANDBOX_EXTRA_WRITE_PATHS ?? "").split(",").map((p) => p.trim()).filter(Boolean);
+}
+function directSpawn(cmd, args, opts) {
+  return {
+    child: spawn(cmd, args, { stdio: opts.stdio ?? "inherit", shell: false, cwd: opts.cwd, env: opts.env }),
+    sandboxed: false,
+    backend: null
+  };
+}
+async function spawnSandboxed(cmd, args, opts) {
+  const backend = getRequestedSandboxBackend();
+  if (!backend) return directSpawn(cmd, args, opts);
+  if (backend === "docker") {
+    const available2 = await isDockerAvailable();
+    if (!available2) {
+      logger.warn(
+        "sandbox: MERGEN_SANDBOX=docker is set but Docker is not available (not installed or daemon not running) \u2014 falling back to direct host execution, UNSANDBOXED. Start Docker to get the isolation you opted into."
+      );
+      return directSpawn(cmd, args, opts);
+    }
+    const image = opts.image ?? process.env.MERGEN_SANDBOX_IMAGE ?? "alpine:3.20";
+    const network = resolveAllowNetwork(opts.network) ? "bridge" : "none";
+    const capArgs = ["--cap-drop=ALL"];
+    const requestedRuntime = opts.dockerRuntime ?? process.env.MERGEN_SANDBOX_DOCKER_RUNTIME;
+    const runtimeArgs = [];
+    if (requestedRuntime) {
+      if (await isDockerRuntimeAvailable(requestedRuntime)) {
+        runtimeArgs.push("--runtime", requestedRuntime);
+      } else {
+        logger.warn(
+          { requestedRuntime },
+          `sandbox: MERGEN_SANDBOX_DOCKER_RUNTIME=${requestedRuntime} is not registered with this Docker daemon \u2014 running under the default runtime (runc) instead. Install gVisor and register it as a Docker runtime to use it.`
+        );
+      }
+    }
+    const envArgs = [];
+    for (const [key, value] of Object.entries(opts.env ?? {})) {
+      if (value === void 0) continue;
+      envArgs.push("-e", `${key}=${value}`);
+    }
+    const dockerArgs = [
+      "run",
+      "--rm",
+      "--read-only",
+      "--network",
+      network,
+      ...capArgs,
+      ...runtimeArgs,
+      ...envArgs,
+      "-v",
+      `${opts.cwd}:/workspace`,
+      "-w",
+      "/workspace",
+      image,
+      cmd,
+      ...args
+    ];
+    logger.info({ image, network, runtime: requestedRuntime && runtimeArgs.length > 0 ? requestedRuntime : "runc", cmd }, "sandbox: running command inside Docker container");
+    return {
+      child: spawn("docker", dockerArgs, { stdio: opts.stdio ?? "inherit", shell: false, env: opts.env }),
+      sandboxed: true,
+      backend: "docker"
+    };
+  }
+  if (process.platform !== "darwin") {
+    logger.warn(
+      "sandbox: MERGEN_SANDBOX=seatbelt is set but this is not macOS \u2014 sandbox-exec is a macOS-only tool. Falling back to direct host execution, UNSANDBOXED."
+    );
+    return directSpawn(cmd, args, opts);
+  }
+  const available = await isMacSandboxAvailable();
+  if (!available) {
+    logger.warn(
+      "sandbox: MERGEN_SANDBOX=seatbelt is set but sandbox-exec is not usable on this machine (missing, or blocked by an MDM/system policy). Falling back to direct host execution, UNSANDBOXED."
+    );
+    return directSpawn(cmd, args, opts);
+  }
+  const allowNetwork = resolveAllowNetwork(opts.network);
+  const writablePaths = [opts.cwd, tmpdir(), ...opts.extraWritablePaths ?? extraWritablePathsFromEnv()];
+  const profile = buildSeatbeltProfile({ writablePaths, allowNetwork });
+  logger.info({ network: allowNetwork ? "bridge" : "none", cmd, writablePaths }, "sandbox: running command inside macOS Seatbelt (sandbox-exec)");
+  return {
+    child: spawn("sandbox-exec", ["-p", profile, cmd, ...args], {
+      stdio: opts.stdio ?? "inherit",
+      shell: false,
+      cwd: opts.cwd,
+      env: opts.env
+    }),
+    sandboxed: true,
+    backend: "seatbelt"
+  };
+}
+export {
+  buildSeatbeltProfile,
+  getMacSandboxCapability,
+  getRequestedSandboxBackend,
+  isDockerAvailable,
+  isDockerRuntimeAvailable,
+  isMacSandboxAvailable,
+  isSandboxRequested,
+  spawnSandboxed
+};

package/dist/intelligence/script-trust.js

@@ -0,0 +1,104 @@
+import fs from "fs";
+import path from "path";
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { createHash } from "crypto";
+const execFileAsync = promisify(execFile);
+const _gitTrackedCache = /* @__PURE__ */ new Map();
+const GIT_TRACKED_CACHE_TTL_MS = 3e4;
+const INLINE_CODE_FLAGS = /* @__PURE__ */ new Set(["-c", "-e", "-r", "-m"]);
+const SCRIPT_INTERPRETERS = /* @__PURE__ */ new Set([
+  "bash",
+  "sh",
+  "zsh",
+  "ksh",
+  "dash",
+  "python",
+  "python3",
+  "python2",
+  "node",
+  "ruby",
+  "perl",
+  "php",
+  "pwsh",
+  "powershell"
+]);
+function recentModificationWindowMs() {
+  const envValue = process.env.MERGEN_SCRIPT_TRUST_WINDOW_SECONDS;
+  if (envValue === void 0) return 3e4;
+  const raw = Number(envValue);
+  return (Number.isFinite(raw) && raw >= 0 ? raw : 30) * 1e3;
+}
+function detectScriptInvocation(cmd) {
+  const interpreter = path.basename(cmd.name).toLowerCase();
+  if (!SCRIPT_INTERPRETERS.has(interpreter)) return null;
+  if (cmd.args.some((a) => INLINE_CODE_FLAGS.has(a))) return null;
+  const firstNonFlag = cmd.args.find((a) => !a.startsWith("-"));
+  if (!firstNonFlag) return null;
+  return { interpreter, scriptPath: firstNonFlag };
+}
+function detectScriptInvocationFromRawText(raw) {
+  const segments = raw.split(/[;&|()\n]+/);
+  for (const segment of segments) {
+    const tokens = segment.trim().split(/\s+/).filter(Boolean);
+    for (let i = 0; i < tokens.length; i++) {
+      const interpreter = path.basename(tokens[i]).toLowerCase();
+      if (!SCRIPT_INTERPRETERS.has(interpreter)) continue;
+      const rest = tokens.slice(i + 1);
+      if (rest.some((t) => INLINE_CODE_FLAGS.has(t))) continue;
+      const firstNonFlag = rest.find((t) => !t.startsWith("-"));
+      if (firstNonFlag) return { interpreter, scriptPath: firstNonFlag };
+    }
+  }
+  return null;
+}
+async function evaluateScriptTrust(scriptPath, cwd) {
+  const reasons = [];
+  const resolved = path.resolve(cwd, scriptPath);
+  const relativeToRoot = path.relative(cwd, resolved);
+  if (relativeToRoot.startsWith("..") || path.isAbsolute(relativeToRoot)) {
+    reasons.push(`script path resolves outside the working directory: ${resolved}`);
+  }
+  let contentHash = null;
+  try {
+    const stat = await fs.promises.stat(resolved);
+    const ageMs = Date.now() - stat.mtimeMs;
+    const windowMs = recentModificationWindowMs();
+    if (ageMs < windowMs) {
+      reasons.push(`script was modified ${Math.max(0, Math.round(ageMs / 1e3))}s ago \u2014 inside the ${Math.round(windowMs / 1e3)}s "just generated" window`);
+    }
+    const buf = await fs.promises.readFile(resolved);
+    contentHash = createHash("sha256").update(buf).digest("hex");
+  } catch {
+    reasons.push(`script file could not be found or read: ${resolved}`);
+  }
+  const cacheKey = contentHash !== null ? `${resolved}:${contentHash}` : null;
+  const cached = cacheKey !== null ? _gitTrackedCache.get(cacheKey) : void 0;
+  if (cached && cached.expiresAt > Date.now()) {
+    if (cached.untrackedReason) reasons.push(cached.untrackedReason);
+  } else {
+    let untrackedReason = null;
+    try {
+      await execFileAsync("git", ["ls-files", "--error-unmatch", resolved], { cwd, timeout: 5e3 });
+    } catch {
+      untrackedReason = "script is not tracked by git (untracked file, or not inside a git repository)";
+    }
+    if (!untrackedReason) {
+      try {
+        await execFileAsync("git", ["diff", "--quiet", "HEAD", "--", resolved], { cwd, timeout: 5e3 });
+      } catch {
+        untrackedReason = "script content differs from the git HEAD version (uncommitted or unreviewed edit)";
+      }
+    }
+    if (untrackedReason) reasons.push(untrackedReason);
+    if (cacheKey !== null) {
+      _gitTrackedCache.set(cacheKey, { untrackedReason, expiresAt: Date.now() + GIT_TRACKED_CACHE_TTL_MS });
+    }
+  }
+  return { trusted: reasons.length === 0, reasons };
+}
+export {
+  detectScriptInvocation,
+  detectScriptInvocationFromRawText,
+  evaluateScriptTrust
+};

package/dist/intelligence/session-metrics.js

@@ -0,0 +1,67 @@
+import fs from "fs";
+import path from "path";
+import { DATA_DIR } from "../sensor/paths.js";
+const METRICS_FILE = path.join(DATA_DIR, "session-metrics.json");
+const MAX_SESSIONS = 500;
+let _sessions = [];
+let _loaded = false;
+function load() {
+  if (_loaded) return;
+  _loaded = true;
+  try {
+    if (!fs.existsSync(METRICS_FILE)) return;
+    const parsed = JSON.parse(fs.readFileSync(METRICS_FILE, "utf8"));
+    if (parsed?.version === 1 && Array.isArray(parsed.sessions)) {
+      _sessions = parsed.sessions.slice(-MAX_SESSIONS);
+    }
+  } catch {
+  }
+}
+function persist() {
+  try {
+    fs.mkdirSync(DATA_DIR, { recursive: true });
+    fs.writeFileSync(METRICS_FILE, JSON.stringify({ version: 1, sessions: _sessions }), "utf8");
+  } catch {
+  }
+}
+function startSession(pid, tag) {
+  load();
+  if (_sessions.some((s) => s.pid === pid)) return;
+  _sessions.push({ pid, tag, startedAt: Date.now() });
+  if (_sessions.length > MAX_SESSIONS) _sessions = _sessions.slice(-MAX_SESSIONS);
+  persist();
+}
+function closeSession(pid, outcome) {
+  load();
+  const session = _sessions.find((s) => s.pid === pid && !s.firstOutcome);
+  if (!session) return;
+  session.firstValidateAt = Date.now();
+  session.firstOutcome = outcome;
+  persist();
+}
+function getSessionMetrics() {
+  load();
+  const withOutcome = _sessions.filter((s) => s.firstOutcome);
+  const resolved = withOutcome.filter((s) => s.firstOutcome === "resolved").length;
+  const partial = withOutcome.filter((s) => s.firstOutcome === "partial").length;
+  const unresolved = withOutcome.filter((s) => s.firstOutcome === "unresolved").length;
+  return {
+    total: _sessions.length,
+    withOutcome: withOutcome.length,
+    firstAttemptResolved: resolved,
+    firstAttemptPartial: partial,
+    firstAttemptUnresolved: unresolved,
+    firstAttemptSuccessRate: withOutcome.length >= 3 ? (resolved + partial * 0.5) / withOutcome.length : null,
+    recentSessions: _sessions.filter((s) => s.firstOutcome).slice(-10).reverse().map((s) => ({ tag: s.tag, outcome: s.firstOutcome, startedAt: s.startedAt }))
+  };
+}
+function _resetSessionMetricsForTesting() {
+  _sessions = [];
+  _loaded = true;
+}
+export {
+  _resetSessionMetricsForTesting,
+  closeSession,
+  getSessionMetrics,
+  startSession
+};