@mutagent/evaluator 0.1.0-alpha.4 → 0.1.0-alpha.6

package/bin/mutagent-cli.mjs

@@ -5045,8 +5045,12 @@ var SpanSchema = Type.Object({
   role: Type.Optional(RoleSchema),
   toolName: Type.Optional(Type.String()),
   toolCallId: Type.Optional(Type.String()),
-  input: Type.Optional(Type.Unknown()),
-  output: Type.Optional(Type.Unknown()),
+  input: Type.Optional(Type.Unknown({
+    description: "Message text for the INPUT-side layers (role user\xB7system\xB7tool = user-input / system-input / tool-call arguments), or a chat-messages array on a multi-layer LLM span. See the field-per-layer rule; enforced by checkFieldConformance()."
+  })),
+  output: Type.Optional(Type.Unknown({
+    description: "Message text for the OUTPUT-side layers (role assistant\xB7toolResult = assistant-output / tool-result). See the field-per-layer rule; enforced by checkFieldConformance()."
+  })),
   tokens: Type.Optional(TokensSchema),
   costUsd: Type.Optional(Type.Number()),
   attributes: Type.Optional(Type.Record(Type.String(), Type.Unknown()))
@@ -6527,7 +6531,7 @@ function normalizeRecords(records, malformedIn) {
           if (ev.timestamp)
             span.startTime = ev.timestamp;
           if (text)
-            span.output = text;
+            span.input = text;
           spans.push(span);
           spanIdx++;
         }
@@ -6542,7 +6546,7 @@ function normalizeRecords(records, malformedIn) {
         if (ev.timestamp)
           span.startTime = ev.timestamp;
         if (typeof content === "string" && content)
-          span.output = content;
+          span.input = content;
         spans.push(span);
         spanIdx++;
       }
@@ -6797,7 +6801,7 @@ function normalizeRecords2(records, malformedIn) {
           span.startTime = ts;
         const msg = str2(p, "message");
         if (msg)
-          span.output = msg;
+          span.input = msg;
         spans.push(span);
         spanIdx++;
       } else if (pType === "agent_message") {
@@ -9255,8 +9259,645 @@ function runSelect(flags, io) {
   return 0;
 }
 
-// ../mutagent-tools/src/cli/index.ts
+// ../mutagent-tools/src/cli/apply.ts
+import { spawnSync } from "child_process";
+import { createHash as createHash3, randomUUID } from "crypto";
+import {
+  existsSync as existsSync4,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync4,
+  rmSync,
+  writeFileSync as writeFileSync2
+} from "fs";
+import { dirname as dirname2 } from "path";
+
+// ../mutagent-tools/src/apply/registry.ts
+var REGISTRY2 = new Map;
+function registerTargetAdapter(adapter) {
+  REGISTRY2.set(adapter.id, adapter);
+}
+function getTargetAdapter(id) {
+  const a = REGISTRY2.get(id);
+  if (!a) {
+    const known = [...REGISTRY2.keys()].sort().join(", ") || "(none registered)";
+    throw new Error(`no target adapter registered for id '${id}'. Registered: ${known}.`);
+  }
+  return a;
+}
+function clearTargetAdapters() {
+  REGISTRY2.clear();
+}
+
+// ../mutagent-tools/src/apply/types.ts
+var AdapterId = {
+  WorktreePr: "worktree-pr",
+  Rest: "rest",
+  VendorCli: "vendor-cli",
+  ReportOnly: "report-only"
+};
+var ApplyKind = {
+  CodePr: "code-pr",
+  Markdown: "markdown",
+  CloudDeploy: "cloud-deploy",
+  ReportOnly: "report-only"
+};
+
+// ../mutagent-tools/src/apply/binding.ts
+function adapterIdForKind(kind, opts) {
+  switch (kind) {
+    case ApplyKind.CodePr:
+    case ApplyKind.Markdown:
+      return AdapterId.WorktreePr;
+    case ApplyKind.CloudDeploy:
+      return opts?.platformTransport === "vendor-cli" ? AdapterId.VendorCli : AdapterId.Rest;
+    case ApplyKind.ReportOnly:
+      return AdapterId.ReportOnly;
+    default: {
+      const _never = kind;
+      throw new Error(`no adapter bound for apply.kind '${String(_never)}'`);
+    }
+  }
+}
+function kindRunsBuild(kind) {
+  return kind === ApplyKind.CodePr;
+}
+
+// ../mutagent-tools/src/apply/audit.ts
+function auditPath(projectRoot, applyId) {
+  return `${projectRoot}/.mutagent/apply/${applyId}/apply-audit.json`;
+}
+var REQUIRED_FIELDS = [
+  "applyId",
+  "transport",
+  "kind",
+  "mode",
+  "fromRev",
+  "toRev",
+  "staleHash",
+  "revertToken",
+  "producedAt"
+];
+function missingAuditFields(record) {
+  return REQUIRED_FIELDS.filter((f) => {
+    const v = record[f];
+    return v === undefined || v === null || v === "";
+  });
+}
+function writeAudit(record, ctx) {
+  const missing = missingAuditFields(record);
+  if (missing.length > 0) {
+    throw new Error(`apply-audit is incomplete \u2014 missing: ${missing.join(", ")} (0-blind-writes contract, V-O6)`);
+  }
+  const path = auditPath(ctx.projectRoot, record.applyId);
+  ctx.io.mkdirp(`${ctx.projectRoot}/.mutagent/apply/${record.applyId}`);
+  ctx.io.writeFile(path, JSON.stringify(record, null, 2) + `
+`);
+}
+
+// ../mutagent-tools/src/apply/diff.ts
+function edorderKey(edits) {
+  return [...edits].sort((a, b) => a.path.localeCompare(b.path));
+}
+function concatCurrent(edits, read) {
+  return edorderKey(edits).map((e) => `=== ${e.path} ===
+${read(e.path) ?? ""}`).join(`
+`);
+}
+function concatProposed(edits) {
+  return edorderKey(edits).map((e) => `=== ${e.path} ===
+${e.contents ?? "<deleted>"}`).join(`
+`);
+}
+function lineDiff(current, proposed) {
+  const a = current.split(`
+`);
+  const b = proposed.split(`
+`);
+  const out = [];
+  const max = Math.max(a.length, b.length);
+  for (let i = 0;i < max; i++) {
+    const cur = a[i];
+    const prop = b[i];
+    if (cur === prop)
+      continue;
+    if (cur !== undefined)
+      out.push(`- ${cur}`);
+    if (prop !== undefined)
+      out.push(`+ ${prop}`);
+  }
+  return out.join(`
+`);
+}
+function fileChangeDiff(change, read) {
+  const edits = change.edits ?? [];
+  const current = concatCurrent(edits, read);
+  const proposed = concatProposed(edits);
+  return { current, proposed, diff: lineDiff(current, proposed) };
+}
+
+// ../mutagent-tools/src/apply/adapters/report-only.ts
+var reportOnlyAdapter = {
+  id: AdapterId.ReportOnly,
+  live: true,
+  async read(change, ctx) {
+    const content = (change.edits ?? []).map((e) => ctx.io.readFile(`${change.targetRoot}/${e.path}`) ?? "").join(`
+`);
+    return { rev: "report-only", content, hash: ctx.io.hash(content), exists: true };
+  },
+  async dryRun(change, current, ctx) {
+    const { diff } = fileChangeDiff(change, (p) => ctx.io.readFile(`${change.targetRoot}/${p}`));
+    return {
+      diff,
+      staleHash: current.hash,
+      wouldWrite: false,
+      notes: ["report-only: no write will be performed"]
+    };
+  },
+  async apply(change, current, ctx) {
+    const applyId = ctx.io.uid();
+    return { applyId, newRev: current.rev, notes: ["report-only: no write performed"] };
+  },
+  async rollback(audit) {
+    return {
+      applyId: audit.applyId,
+      restoredRev: audit.fromRev,
+      notes: ["report-only: nothing to roll back"]
+    };
+  },
+  emitAudit(record, ctx) {
+    writeAudit(record, ctx);
+  }
+};
+
+// ../mutagent-tools/src/apply/adapters/worktree-pr.ts
+function sh(ctx, cmd, args, cwd, input) {
+  const r = ctx.io.shell(cmd, args, { cwd, input });
+  if (r.code !== 0) {
+    throw new Error(`\`${cmd} ${args.join(" ")}\` failed (exit ${r.code}): ${r.stderr.trim() || r.stdout.trim()}`);
+  }
+  return r;
+}
+function headRev(ctx, cwd) {
+  const r = ctx.io.shell("git", ["rev-parse", "HEAD"], { cwd });
+  return r.code === 0 ? r.stdout.trim() : "unknown";
+}
+function parsePrUrl(stdout) {
+  const m = stdout.match(/https?:\/\/\S+/);
+  return m ? m[0] : undefined;
+}
+var worktreePrAdapter = {
+  id: AdapterId.WorktreePr,
+  live: true,
+  async read(change, ctx) {
+    const edits = change.edits ?? [];
+    const content = concatCurrent(edits, (p) => ctx.io.readFile(`${change.targetRoot}/${p}`));
+    const exists = edits.some((e) => ctx.io.exists(`${change.targetRoot}/${e.path}`));
+    return { rev: headRev(ctx, change.targetRoot), content, hash: ctx.io.hash(content), exists };
+  },
+  async dryRun(change, current, ctx) {
+    const { diff } = fileChangeDiff(change, (p) => ctx.io.readFile(`${change.targetRoot}/${p}`));
+    const proposed = concatProposed(change.edits ?? []);
+    return {
+      diff,
+      staleHash: current.hash,
+      wouldWrite: proposed !== current.content,
+      notes: kindRunsBuild(change.kind) ? ["code-pr: lint + typecheck will run in the worktree"] : ["markdown: no build step"]
+    };
+  },
+  async apply(change, current, ctx) {
+    const edits = change.edits ?? [];
+    if (edits.length === 0)
+      throw new Error("worktree-PR apply: no edits provided");
+    const now = concatCurrent(edits, (p) => ctx.io.readFile(`${change.targetRoot}/${p}`));
+    if (ctx.io.hash(now) !== current.hash) {
+      throw new Error("worktree-PR apply: target changed since read (stale-hash mismatch) \u2014 re-run dryRun");
+    }
+    const applyId = ctx.io.uid();
+    const branch = `apply/${applyId}`;
+    const wtdir = `${ctx.projectRoot}/.mutagent/apply/${applyId}/worktree`;
+    ctx.io.mkdirp(`${ctx.projectRoot}/.mutagent/apply/${applyId}`);
+    sh(ctx, "git", ["worktree", "add", "-b", branch, wtdir, "HEAD"], change.targetRoot);
+    try {
+      for (const e of edits) {
+        const target = `${wtdir}/${e.path}`;
+        if (e.contents === null)
+          ctx.io.deleteFile(target);
+        else {
+          ctx.io.mkdirp(dirOf(target));
+          ctx.io.writeFile(target, e.contents);
+        }
+      }
+      if (kindRunsBuild(change.kind)) {
+        sh(ctx, "bun", ["run", "lint"], wtdir);
+        sh(ctx, "bun", ["run", "typecheck"], wtdir);
+      }
+      sh(ctx, "git", ["add", "-A"], wtdir);
+      sh(ctx, "git", ["commit", "-m", change.title], wtdir);
+      const newRev = headRev(ctx, wtdir);
+      sh(ctx, "git", ["push", "-u", "origin", branch], wtdir);
+      const pr = sh(ctx, "gh", ["pr", "create", "--base", "main", "--title", change.title, "--body", change.body ?? change.title], wtdir);
+      return { applyId, newRev, ref: parsePrUrl(pr.stdout), notes: [`branch ${branch}`] };
+    } finally {
+      ctx.io.shell("git", ["worktree", "remove", "--force", wtdir], { cwd: change.targetRoot });
+    }
+  },
+  async rollback(audit, ctx) {
+    const branch = `rollback/${audit.applyId}`;
+    const repoRoot = ctx.projectRoot;
+    const wtdir = `${ctx.projectRoot}/.mutagent/apply/${audit.applyId}/rollback-worktree`;
+    ctx.io.mkdirp(`${ctx.projectRoot}/.mutagent/apply/${audit.applyId}`);
+    sh(ctx, "git", ["worktree", "add", "-b", branch, wtdir, "HEAD"], repoRoot);
+    try {
+      sh(ctx, "git", ["revert", "--no-edit", audit.revertToken], wtdir);
+      const restoredRev = headRev(ctx, wtdir);
+      sh(ctx, "git", ["push", "-u", "origin", branch], wtdir);
+      const pr = sh(ctx, "gh", ["pr", "create", "--base", "main", "--title", `Revert ${audit.applyId}`, "--body", `Reverts ${audit.toRev}`], wtdir);
+      return { applyId: audit.applyId, restoredRev, ref: parsePrUrl(pr.stdout), notes: [`revert of ${audit.toRev}`] };
+    } finally {
+      ctx.io.shell("git", ["worktree", "remove", "--force", wtdir], { cwd: repoRoot });
+    }
+  },
+  emitAudit(record, ctx) {
+    writeAudit(record, ctx);
+  }
+};
+function dirOf(path) {
+  const i = path.lastIndexOf("/");
+  return i <= 0 ? path : path.slice(0, i);
+}
+
+// ../mutagent-tools/src/apply/adapters/rest.ts
+function authHeaders(change) {
+  const h = { "content-type": "application/json" };
+  if (change.credentialToken)
+    h["authorization"] = `Bearer ${change.credentialToken}`;
+  return h;
+}
+function assertOk(r, what) {
+  if (r.status < 200 || r.status >= 300) {
+    throw new Error(`REST ${what} failed (HTTP ${r.status}): ${r.body.slice(0, 200)}`);
+  }
+  return r;
+}
+function extractRev(body) {
+  try {
+    const j = JSON.parse(body);
+    for (const k of ["activeRev", "rev", "revision", "version", "id"]) {
+      const v = j[k];
+      if (typeof v === "string" && v)
+        return v;
+      if (typeof v === "number")
+        return String(v);
+    }
+  } catch {}
+  return "";
+}
+var restAdapter = {
+  id: AdapterId.Rest,
+  live: true,
+  async read(change, ctx) {
+    const r = assertOk(await ctx.io.http("GET", change.targetRoot, { headers: authHeaders(change) }), "GET");
+    const rev = extractRev(r.body) || "unknown";
+    return { rev, content: r.body, hash: ctx.io.hash(r.body), exists: r.status !== 404 };
+  },
+  async dryRun(change, current, ctx) {
+    const proposed = JSON.stringify(change.config ?? {}, null, 2);
+    return {
+      diff: lineDiff(current.content, proposed),
+      staleHash: current.hash,
+      wouldWrite: ctx.io.hash(proposed) !== current.hash,
+      notes: ["cloud-rest: non-destructive create-rev + activate"]
+    };
+  },
+  async apply(change, current, ctx) {
+    const applyId = ctx.io.uid();
+    const created = assertOk(await ctx.io.http("POST", `${change.targetRoot}/revisions`, {
+      headers: authHeaders(change),
+      body: JSON.stringify(change.config ?? {})
+    }), "POST create-rev");
+    const newRev = extractRev(created.body);
+    if (!newRev)
+      throw new Error("REST apply: create-rev returned no rev id");
+    assertOk(await ctx.io.http("PATCH", change.targetRoot, {
+      headers: authHeaders(change),
+      body: JSON.stringify({ activeRev: newRev })
+    }), "PATCH activate");
+    return { applyId, newRev, ref: newRev, notes: [`activated ${newRev} (prior ${current.rev} retained)`] };
+  },
+  async rollback(audit, ctx) {
+    if (!audit.target)
+      throw new Error("REST rollback: audit has no target url");
+    assertOk(await ctx.io.http("PATCH", audit.target, {
+      body: JSON.stringify({ activeRev: audit.revertToken }),
+      headers: { "content-type": "application/json" }
+    }), "PATCH re-activate");
+    return {
+      applyId: audit.applyId,
+      restoredRev: audit.revertToken,
+      ref: audit.revertToken,
+      notes: [`re-activated ${audit.revertToken}; ${audit.toRev} retained`]
+    };
+  },
+  emitAudit(record, ctx) {
+    writeAudit(record, ctx);
+  }
+};
+
+// ../mutagent-tools/src/apply/adapters/vendor-cli.ts
+function sh2(ctx, cmd, args) {
+  const r = ctx.io.shell(cmd, args);
+  if (r.code !== 0) {
+    throw new Error(`\`${cmd} ${args.join(" ")}\` failed (exit ${r.code}): ${r.stderr.trim() || r.stdout.trim()}`);
+  }
+  return r;
+}
+function parseHandle(stdout) {
+  const m = stdout.match(/(?:version|rev|revision|handle)[:=\s]+(\S+)/i) ?? stdout.match(/\bv\d+\b/) ?? stdout.trim().split(`
+`).pop()?.match(/(\S+)$/);
+  return (Array.isArray(m) ? m[1] ?? m[0] : "") || "";
+}
+function vendorBin(change) {
+  if (!change.vendorBin)
+    throw new Error("vendor-CLI: change.vendorBin is required (the deploy binary name)");
+  return change.vendorBin;
+}
+var vendorCliAdapter = {
+  id: AdapterId.VendorCli,
+  live: true,
+  async read(change, ctx) {
+    const bin = vendorBin(change);
+    const r = ctx.io.shell(bin, ["get", change.targetRoot]);
+    const content = r.stdout;
+    return { rev: parseHandle(content) || "unknown", content, hash: ctx.io.hash(content), exists: r.code === 0 };
+  },
+  async dryRun(change, current, ctx) {
+    const proposed = JSON.stringify(change.config ?? {}, null, 2);
+    return {
+      diff: lineDiff(current.content, proposed),
+      staleHash: current.hash,
+      wouldWrite: ctx.io.hash(proposed) !== current.hash,
+      notes: [`vendor-CLI (${change.vendorBin ?? "?"}): shell deploy \u2192 new version handle`]
+    };
+  },
+  async apply(change, current, ctx) {
+    const applyId = ctx.io.uid();
+    const bin = vendorBin(change);
+    const cfgPath = `${ctx.projectRoot}/.mutagent/apply/${applyId}/deploy-config.json`;
+    ctx.io.mkdirp(`${ctx.projectRoot}/.mutagent/apply/${applyId}`);
+    ctx.io.writeFile(cfgPath, JSON.stringify(change.config ?? {}, null, 2));
+    const r = sh2(ctx, bin, ["deploy", change.targetRoot, "--config", cfgPath]);
+    const newRev = parseHandle(r.stdout);
+    if (!newRev)
+      throw new Error("vendor-CLI apply: deploy returned no version handle");
+    return { applyId, newRev, ref: newRev, notes: [`deployed ${newRev} (prior ${current.rev} retained)`] };
+  },
+  async rollback(audit, ctx) {
+    const bin = (audit.note ?? "").match(/vendor-CLI \(([^)]+)\)/)?.[1];
+    const [binName, target] = (audit.target ?? "").split("|");
+    const resolvedBin = bin && bin !== "?" ? bin : binName;
+    if (!resolvedBin || !target)
+      throw new Error("vendor-CLI rollback: audit.target must be 'bin|url'");
+    sh2(ctx, resolvedBin, ["rollback", target, "--to", audit.revertToken]);
+    return {
+      applyId: audit.applyId,
+      restoredRev: audit.revertToken,
+      ref: audit.revertToken,
+      notes: [`vendor rollback to ${audit.revertToken}; ${audit.toRev} retained`]
+    };
+  },
+  emitAudit(record, ctx) {
+    writeAudit(record, ctx);
+  }
+};
+// ../mutagent-tools/src/apply/target-select.ts
+var TargetSelectionOutcome = {
+  Resolved: "resolved",
+  NeedsDisambiguation: "needs-disambiguation",
+  NoTarget: "no-target"
+};
+function selectApplyTarget(candidates, pick) {
+  const uniq = [...new Set(candidates.filter((c) => c.trim().length > 0))];
+  if (uniq.length === 0) {
+    return { outcome: TargetSelectionOutcome.NoTarget };
+  }
+  if (uniq.length === 1) {
+    return { outcome: TargetSelectionOutcome.Resolved, target: uniq[0] };
+  }
+  if (pick !== undefined && uniq.includes(pick)) {
+    return { outcome: TargetSelectionOutcome.Resolved, target: pick };
+  }
+  return {
+    outcome: TargetSelectionOutcome.NeedsDisambiguation,
+    candidates: uniq,
+    reason: pick !== undefined ? `--pick '${pick}' is not one of the ${uniq.length} candidate targets` : `${uniq.length} candidate targets present and no explicit --pick \u2014 refusing to default`
+  };
+}
+
+// ../mutagent-tools/src/apply/index.ts
+function registerBuiltinAdapters2() {
+  clearTargetAdapters();
+  registerTargetAdapter(reportOnlyAdapter);
+  registerTargetAdapter(worktreePrAdapter);
+  registerTargetAdapter(restAdapter);
+  registerTargetAdapter(vendorCliAdapter);
+}
+async function runApplyFlow(change, ctx, mode) {
+  const adapterId = adapterIdForKind(change.kind, { platformTransport: change.platformTransport });
+  const adapter = getTargetAdapter(adapterId);
+  const read = await adapter.read(change, ctx);
+  const dryRun = await adapter.dryRun(change, read, ctx);
+  if (mode === "dry-run") {
+    return { adapterId, read, dryRun };
+  }
+  const applyResult = await adapter.apply(change, read, ctx);
+  const audit = {
+    applyId: applyResult.applyId,
+    transport: adapterId,
+    kind: change.kind,
+    subject: change.subject,
+    target: change.targetRoot,
+    mode: change.kind === ApplyKind.ReportOnly ? "report-only" : "apply",
+    fromRev: read.rev,
+    toRev: applyResult.newRev,
+    staleHash: dryRun.staleHash,
+    revertToken: read.rev,
+    ref: applyResult.ref,
+    producedAt: ctx.io.producedAt,
+    note: (applyResult.notes ?? []).join("; ") || undefined
+  };
+  adapter.emitAudit(audit, ctx);
+  return { adapterId, read, dryRun, applyResult, audit };
+}
+async function runRollbackFlow(audit, ctx) {
+  const adapter = getTargetAdapter(audit.transport);
+  const rollback = await adapter.rollback(audit, ctx);
+  const record = {
+    applyId: `${audit.applyId}-rollback`,
+    transport: audit.transport,
+    kind: audit.kind,
+    subject: audit.subject,
+    target: audit.target,
+    mode: "rollback",
+    fromRev: audit.toRev,
+    toRev: rollback.restoredRev,
+    staleHash: audit.staleHash,
+    revertToken: audit.toRev,
+    ref: rollback.ref,
+    producedAt: ctx.io.producedAt,
+    note: (rollback.notes ?? []).join("; ") || undefined
+  };
+  adapter.emitAudit(record, ctx);
+  return { rollback, audit: record };
+}
+
+// ../mutagent-tools/src/cli/apply.ts
 function usage(err) {
+  err("mutagent-cli apply \u2014 shared write transport (worktree-PR \xB7 REST \xB7 vendor-CLI)");
+  err("");
+  err("usage: mutagent-cli apply --kind <code-pr|markdown|cloud-deploy|report-only> --target <root>");
+  err("         (--edit <relpath>=<srcfile>)... | --edits-json <file>   # file transports");
+  err("         [--config-json <file>]                                   # platform transports");
+  err("         --title <t> [--body <b>] [--subject <name>]");
+  err("         [--platform-transport rest|vendor-cli] [--vendor-bin <bin>] [--token-ref <ENV>]");
+  err("         [--dry-run | --commit]                                   # default: --dry-run");
+  err("       mutagent-cli apply --rollback <apply-audit.json>");
+  err("");
+  err("  read() + dryRun() are always safe. apply() writes ONLY on --commit, AFTER the caller's gate.");
+}
+function buildApplyIo(base) {
+  return {
+    now: base.now,
+    producedAt: base.producedAt,
+    out: base.out,
+    err: base.err,
+    readFile: (p) => existsSync4(p) ? readFileSync4(p, "utf8") : undefined,
+    writeFile: (p, c) => {
+      mkdirSync2(dirname2(p), { recursive: true });
+      writeFileSync2(p, c);
+    },
+    deleteFile: (p) => {
+      if (existsSync4(p))
+        rmSync(p, { force: true });
+    },
+    exists: (p) => existsSync4(p),
+    mkdirp: (p) => mkdirSync2(p, { recursive: true }),
+    shell: (cmd, args, opts) => {
+      const r = spawnSync(cmd, args, {
+        cwd: opts?.cwd,
+        input: opts?.input,
+        encoding: "utf8"
+      });
+      return {
+        stdout: r.stdout ?? "",
+        stderr: r.stderr ?? (r.error ? r.error.message : ""),
+        code: r.status ?? (r.error ? 1 : 0)
+      };
+    },
+    http: async (method, url, opts) => {
+      const res = await fetch(url, { method, headers: opts?.headers, body: opts?.body });
+      const body = await res.text();
+      return { status: res.status, body };
+    },
+    hash: (s) => createHash3("sha256").update(s).digest("hex").slice(0, 16),
+    uid: () => randomUUID().slice(0, 8)
+  };
+}
+function buildEdits(flags, cwd) {
+  const editsJson = getStr(flags, "edits-json");
+  if (editsJson) {
+    const raw = readFileSync4(resolveRel(editsJson, cwd), "utf8");
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed))
+      throw new Error("--edits-json must be a JSON array of {path, contents}");
+    return parsed;
+  }
+  const specs = getList(flags, "edit") ?? [];
+  return specs.map((spec) => {
+    const eq = spec.indexOf("=");
+    if (eq < 0)
+      throw new Error(`--edit expects '<relpath>=<srcfile>' (got '${spec}')`);
+    const path = spec.slice(0, eq);
+    const src = spec.slice(eq + 1);
+    return { path, contents: readFileSync4(resolveRel(src, cwd), "utf8") };
+  });
+}
+function resolveRel(p, cwd) {
+  return p.startsWith("/") ? p : `${cwd}/${p}`;
+}
+var VALID_KINDS = new Set(Object.values(ApplyKind));
+async function runApply(argv, base, cwd) {
+  const { flags } = parseArgs(argv);
+  if (getBool(flags, "help") || argv.length === 0) {
+    usage(base.err);
+    return argv.length === 0 ? 1 : 0;
+  }
+  registerBuiltinAdapters2();
+  const io = buildApplyIo(base);
+  const ctx = { io, projectRoot: cwd };
+  const rollbackPath = getStr(flags, "rollback");
+  if (rollbackPath) {
+    const auditRaw = readFileSync4(resolveRel(rollbackPath, cwd), "utf8");
+    const audit = JSON.parse(auditRaw);
+    const { rollback, audit: record } = await runRollbackFlow(audit, ctx);
+    base.out(`\u2705 rollback: restored ${rollback.restoredRev}${rollback.ref ? ` (${rollback.ref})` : ""}`);
+    base.out(`   audit: .mutagent/apply/${record.applyId}/apply-audit.json`);
+    return 0;
+  }
+  const kind = getStr(flags, "kind");
+  if (!kind || !VALID_KINDS.has(kind)) {
+    base.err(`apply: --kind must be one of ${[...VALID_KINDS].join(" | ")}`);
+    return 1;
+  }
+  const candidates = getList(flags, "target") ?? [];
+  const selection = selectApplyTarget(candidates, getStr(flags, "pick"));
+  if (selection.outcome === TargetSelectionOutcome.NoTarget) {
+    base.err("apply: --target is required");
+    return 1;
+  }
+  if (selection.outcome === TargetSelectionOutcome.NeedsDisambiguation) {
+    base.err(`apply: ambiguous target \u2014 ${selection.reason}`);
+    base.err(`  candidates: ${selection.candidates.join(", ")}`);
+    base.err("  re-run with an explicit --pick <target> (the session must confirm which target to bind)");
+    return 2;
+  }
+  const target = selection.target;
+  const title = getStr(flags, "title") ?? "mutagent apply";
+  const tokenRef = getStr(flags, "token-ref");
+  const change = {
+    kind,
+    targetRoot: target,
+    title,
+    body: getStr(flags, "body"),
+    subject: getStr(flags, "subject"),
+    platformTransport: getStr(flags, "platform-transport"),
+    vendorBin: getStr(flags, "vendor-bin"),
+    credentialToken: tokenRef ? process.env[tokenRef] : undefined
+  };
+  if (kind === ApplyKind.CodePr || kind === ApplyKind.Markdown || kind === ApplyKind.ReportOnly) {
+    change.edits = buildEdits(flags, cwd);
+  }
+  const configJson = getStr(flags, "config-json");
+  if (configJson)
+    change.config = JSON.parse(readFileSync4(resolveRel(configJson, cwd), "utf8"));
+  const mode = getBool(flags, "commit") ? "commit" : "dry-run";
+  const result = await runApplyFlow(change, ctx, mode);
+  base.out(`transport: ${result.adapterId} \xB7 kind: ${kind} \xB7 from-rev: ${result.read.rev}`);
+  base.out(`dry-run: ${result.dryRun.wouldWrite ? "WOULD write" : "no change"} \xB7 stale-hash: ${result.dryRun.staleHash}`);
+  if (result.dryRun.diff)
+    base.out(`--- diff ---
+${result.dryRun.diff}`);
+  if (mode === "dry-run") {
+    base.out("(dry-run \u2014 no write; re-run with --commit after the caller's gate)");
+    return 0;
+  }
+  const a = result.audit;
+  base.out(`\u2705 applied: ${a?.fromRev} \u2192 ${a?.toRev}${result.applyResult?.ref ? ` (${result.applyResult.ref})` : ""}`);
+  base.out(`   audit: .mutagent/apply/${a?.applyId}/apply-audit.json (revert-token: ${a?.revertToken})`);
+  return 0;
+}
+
+// ../mutagent-tools/src/cli/index.ts
+function usage2(err) {
   err("mutagent-cli \u2014 MutagenT infra CLI");
   err("");
   err("usage: mutagent-cli <command> [args]");
@@ -9273,6 +9914,13 @@ function usage(err) {
   err("  trace select <--in <unitf.jsonl>|-> [--select <preset>] [--signal <flags>]");
   err("        [--signal-mode and|or] [--min-worthiness <0..1>] [--export <path.jsonl>]");
   err("");
+  err("  apply --kind <code-pr|markdown|cloud-deploy|report-only> --target <root>");
+  err("        (--edit <relpath>=<src>)... | --edits-json <f> | --config-json <f>");
+  err("        --title <t> [--body <b>] [--subject <n>] [--platform-transport rest|vendor-cli]");
+  err("        [--vendor-bin <bin>] [--token-ref <ENV>] [--dry-run | --commit]");
+  err("  apply --rollback <apply-audit.json>");
+  err("        the SHARED write transport \u2014 the caller gates BEFORE --commit (no approval logic here).");
+  err("");
   err("  see references/TRACES-CLI.md for the full contract + UniTF format.");
 }
 async function main() {
@@ -9290,14 +9938,17 @@ async function main() {
     err
   };
   if (command === undefined || command === "--help" || command === "-h" || command === "help") {
-    usage(err);
+    usage2(err);
     return command === undefined ? 1 : 0;
   }
   if (command === "trace") {
     return runTrace(rest, io, process.cwd());
   }
+  if (command === "apply") {
+    return runApply(rest, io, process.cwd());
+  }
   err(`mutagent-cli: unknown command '${command}'`);
-  usage(err);
+  usage2(err);
   return 1;
 }
 main().then((code) => process.exit(code)).catch((e) => {