synartesis 0.6.11 → 0.6.13

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import {
+  IDEMPOTENCY_META_KEY,
   NOTHING_RECORDED_YET,
   WORDMARK,
   banner,
@@ -8,6 +9,7 @@ import {
   connectStdioUpstream,
   createPolicyResolver,
   createRouter,
+  describeStanding,
   findJournal,
   findManifest,
   labelFor,
@@ -16,18 +18,23 @@ import {
   openJournal,
   parseManifest,
   pathBinaryMatches,
+  pinBlock,
   planInverse,
   planRead,
   proxyCommand,
   qualify,
   resolvedRead,
   rule,
+  standing,
   style,
   toPayload,
   toResolvedRead,
+  toolShapes,
+  untested,
   verifyAgainstServers,
+  warnUntested,
   wasRefused
-} from "./chunk-DRDKIFD3.js";
+} from "./chunk-6X7GPUGJ.js";
 import {
   DriftConflict,
   ManifestError,
@@ -95,7 +102,14 @@ ${source}
 `,
       path
     ).tools;
-    return { key, rules, name: hit.manifest, source };
+    const claimed = /^\s*provenance:\s*(live|documented)\s*$/m.exec(text)?.[1];
+    return {
+      key,
+      rules,
+      name: hit.manifest,
+      source,
+      ...claimed === "live" || claimed === "documented" ? { provenance: claimed } : {}
+    };
   } catch {
     return void 0;
   }
@@ -254,12 +268,20 @@ async function draftManifest(options) {
       `${options.name} is already declared in the manifest; remove it first or choose another name`
     );
   }
+  const known = knownPolicyFor(options.command, options.args);
+  const claim = known?.provenance === void 0 ? [] : [
+    ...known.provenance === "documented" ? [
+      `    # This policy has never been run against the real server. Check it`,
+      `    # against your own setup before trusting undo on it.`
+    ] : [],
+    `    provenance: ${known.provenance}`
+  ];
   const server = [
     `  ${options.name}:`,
     `    command: ${quote(options.command)}`,
-    `    args: [${options.args.map(quote).join(", ")}]`
+    `    args: [${options.args.map(quote).join(", ")}]`,
+    ...claim
   ].join("\n");
-  const known = knownPolicyFor(options.command, options.args);
   const adopted = known === void 0 ? void 0 : adopt(known, options.name, tools);
   const policies = adopted?.source ?? tools.map((tool) => draftTool(options.name, tool)).join("\n\n");
   if (existing === void 0) {
@@ -284,10 +306,24 @@ async function draftManifest(options) {
       policies,
       ``
     ].join("\n");
-    return adopted === void 0 || known === void 0 ? { yaml } : { yaml, adopted: { server: known.name, tools: adopted.covered } };
+    return adopted === void 0 || known === void 0 ? { yaml } : {
+      yaml,
+      adopted: {
+        server: known.name,
+        tools: adopted.covered,
+        ...known.provenance === void 0 ? {} : { provenance: known.provenance }
+      }
+    };
   }
   const merged = mergeInto(existing, server, policies, options.name);
-  return adopted === void 0 || known === void 0 ? { yaml: merged } : { yaml: merged, adopted: { server: known.name, tools: adopted.covered } };
+  return adopted === void 0 || known === void 0 ? { yaml: merged } : {
+    yaml: merged,
+    adopted: {
+      server: known.name,
+      tools: adopted.covered,
+      ...known.provenance === void 0 ? {} : { provenance: known.provenance }
+    }
+  };
 }
 function mergeInto(existing, server, policies, name) {
   const serversAt2 = existing.indexOf("\nservers:");
@@ -312,7 +348,6 @@ function mergeInto(existing, server, policies, name) {
 
 // src/rollback/rollback.ts
 import { z as z2 } from "zod";
-var IDEMPOTENCY_META_KEY = "synartesis.dev/idempotency-key";
 var inversePlan = z2.object({
   server: z2.string(),
   tool: z2.string(),
@@ -331,8 +366,10 @@ function classify(action, replanning, goAhead) {
     case "rolled_back":
       return { kind: "already-reverted", reason: "already rolled back", verified: true };
     case "failed":
-    case "denied":
-      return { kind: "skip", reason: `never applied (${action.status})`, verified: true };
+    case "denied": {
+      const why = labelFor(action) === "used" ? "never applied: its approval moved to the call that ran" : `never applied (${action.status})`;
+      return { kind: "skip", reason: why, verified: true };
+    }
     case "pending":
       return {
         kind: "halt",
@@ -572,7 +609,7 @@ ${seen}` : seen;
   };
 }
 function unverifiedBecause(action) {
-  return action.verify === void 0 ? "no pre-read declared, so drift could not be ruled out" : "the post-state was never captured, so drift could not be ruled out";
+  return action.verify === void 0 ? "no read declared for this tool, so drift could not be ruled out -- a `verify` read in its policy would give it one" : "the post-state was never captured, so drift could not be ruled out";
 }
 function describeStep(action) {
   return { seq: action.seq, server: action.server, tool: action.tool };
@@ -652,7 +689,11 @@ async function inspect(options) {
       continue;
     }
     if (SETTLED.has(action.status)) {
-      resources.push({ ...at, condition: "not-applied", note: action.status });
+      resources.push({
+        ...at,
+        condition: "not-applied",
+        note: labelFor(action) === "used" ? "its approval moved to the call that ran" : action.status
+      });
       continue;
     }
     if (action.status === "rolled_back") {
@@ -881,6 +922,19 @@ function size(bytes) {
   }
   return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
+function summariseValue(value) {
+  const flat = value.replace(/\s+/g, " ").trim();
+  if (flat.length <= 48) {
+    return flat;
+  }
+  const looksLikeALocation = !value.includes("\n") && /[/\\]/.test(value);
+  if (looksLikeALocation) {
+    const tail = value.slice(-44);
+    const from = tail.search(/[/\\]/);
+    return `\u2026${from === -1 ? tail : tail.slice(from)}`;
+  }
+  return size(Buffer.byteLength(value));
+}
 function summariseArgs(args, limit = 60) {
   if (!isRecord(args)) {
     return args === void 0 ? "" : JSON.stringify(args);
@@ -888,7 +942,7 @@ function summariseArgs(args, limit = 60) {
   const parts = [];
   for (const [key, value] of Object.entries(args)) {
     if (typeof value === "string") {
-      parts.push(value.length > 48 ? `${key} ${size(Buffer.byteLength(value))}` : `${key} ${value}`);
+      parts.push(`${key} ${summariseValue(value)}`);
       continue;
     }
     if (Array.isArray(value)) {
@@ -1643,7 +1697,11 @@ async function planInstall(sites, manifestPath, invoker) {
         name,
         original: entry,
         wrapped: proxyEntry(manifestPath, key, entry, invoker),
-        ...draft.adopted === void 0 ? {} : { adopted: draft.adopted.server, tools: draft.adopted.tools }
+        ...draft.adopted === void 0 ? {} : {
+          adopted: draft.adopted.server,
+          tools: draft.adopted.tools,
+          ...draft.adopted.provenance === void 0 ? {} : { provenance: draft.adopted.provenance }
+        }
       });
     }
     plans.push({ site, servers: planned, skipped });
@@ -1877,7 +1935,7 @@ function runsView(journal, screen, options) {
     return `  ${here ? style.accent(CURSOR) : " "} ${here ? style.accent(name) : style.strong(name)} ${style.quiet(shortTime(run.startedAt).trimEnd().padEnd(13))}  ${style.quiet(run.status.padEnd(11))} ${style.quiet(`${String(actions.length)} actions`)}${note}`;
   });
 }
-function standing(actions) {
+function standing2(actions) {
   let undoable = 0;
   let conflicted = 0;
   for (const action of actions) {
@@ -1897,7 +1955,7 @@ function elsewhere(journal, exceptId) {
     if (run.id === exceptId) {
       continue;
     }
-    const found = standing(journal.getActions(run.id));
+    const found = standing2(journal.getActions(run.id));
     if (found.undoable > 0 || found.conflicted > 0) {
       return run;
     }
@@ -2138,7 +2196,7 @@ async function openConsole(options) {
     if (run === void 0) {
       return [];
     }
-    const here = standing(ready.getActions(run.id));
+    const here = standing2(ready.getActions(run.id));
     const id = run.id.slice(0, 8);
     if (here.undoable > 0) {
       return [
@@ -2359,7 +2417,7 @@ async function openConsole(options) {
         if (ready === void 0 || run === void 0) {
           return;
         }
-        const here = standing(ready.getActions(run.id));
+        const here = standing2(ready.getActions(run.id));
         if (here.undoable === 0 && here.conflicted === 0) {
           say(nothingToUndo(ready, run));
           return;
@@ -2381,7 +2439,7 @@ async function openConsole(options) {
         if (ready === void 0 || run === void 0) {
           return;
         }
-        const here = standing(ready.getActions(run.id));
+        const here = standing2(ready.getActions(run.id));
         if (here.undoable === 0 && here.conflicted === 0) {
           say(nothingToUndo(ready, run));
           return;
@@ -2541,6 +2599,7 @@ var COMMANDS = `
   synartesis status
   synartesis init <server> -- <command> [args...]  [--manifest <path>]
   synartesis check [--manifest <path>]
+  synartesis pin [--manifest <path>]
   synartesis list [--journal <path>]
   synartesis show <runId> [--full] [--live] [--journal <path>]
   synartesis gates [--journal <path>]
@@ -2612,6 +2671,19 @@ journal is too. Set SYNARTESIS_HOME to put that somewhere else.
 Exit codes: 0 complete, 1 halted or partial, 2 bad usage or configuration.
 `;
 var UsageError = class extends Error {
+  /**
+   * Whether the command list helps.
+   *
+   * It does for a mistyped flag or command. It does not for "there is nothing
+   * here to act on", which is a fact about the journal rather than about what
+   * was typed -- and answering that with forty lines of unrelated commands
+   * buries the one sentence that matters.
+   */
+  listCommands;
+  constructor(message, listCommands = true) {
+    super(message);
+    this.listCommands = listCommands;
+  }
 };
 function flag(argv, name) {
   const at = argv.indexOf(name);
@@ -2641,9 +2713,51 @@ function positional(argv) {
   }
   return values;
 }
+async function runPin(argv) {
+  const path = findManifest(flag(argv, "--manifest"));
+  const manifest = loadManifest(path);
+  const shapes = /* @__PURE__ */ new Map();
+  const upstreams = [];
+  try {
+    for (const [name, spec] of Object.entries(manifest.servers)) {
+      const upstream = await connectStdioUpstream({
+        name,
+        command: spec.command,
+        args: spec.args,
+        stderr: "capture",
+        ...spec.env === void 0 ? {} : { env: spec.env }
+      });
+      upstreams.push(upstream);
+      shapes.set(name, await toolShapes(upstream));
+    }
+  } finally {
+    for (const upstream of upstreams) {
+      await upstream.close();
+    }
+  }
+  const block2 = pinBlock(shapes, manifest);
+  out("");
+  out(`  ${style.label("pins for")}  ${style.strong(path)}`);
+  out("");
+  for (const line2 of block2.split("\n")) {
+    out(`  ${line2}`);
+  }
+  out("");
+  out(`  ${style.quiet("Paste this into the manifest. From then on a tool whose shape")}`);
+  out(`  ${style.quiet("changes stops the proxy instead of quietly keeping its old policy.")}`);
+  out("");
+  return 0;
+}
 async function runCheck(argv) {
   const path = findManifest(flag(argv, "--manifest"));
   const manifest = loadManifest(path);
+  const unproven = untested(manifest);
+  if (unproven.length > 0) {
+    out("");
+    for (const line2 of wrapped(warnUntested(unproven), 74)) {
+      out(`  ${style.accent(line2)}`);
+    }
+  }
   const upstreams = [];
   try {
     for (const [name, spec] of Object.entries(manifest.servers)) {
@@ -2673,8 +2787,20 @@ async function runCheck(argv) {
   out(`  ${rule(54)}`);
   out("");
   out(`  ${style.quiet("servers ")} ${Object.keys(manifest.servers).join(", ")}`);
+  for (const entry of standing(manifest)) {
+    const said = describeStanding(entry);
+    out(
+      `  ${style.quiet("        ")} ${style.strong(entry.server)} ${entry.provenance === "documented" ? style.accent(said) : style.quiet(said)}`
+    );
+  }
   out(`  ${style.quiet("policies")} ${[...counts].map(([k, v]) => `${String(v)} ${k}`).join(", ")}`);
   out(`  ${style.quiet("guarded ")} ${style.accent(String(gated))}`);
+  const pinned = Object.entries(manifest.pins ?? {});
+  const servers = Object.keys(manifest.servers);
+  const unpinned = servers.filter((name) => !pinned.some(([held]) => held === name));
+  out(
+    `  ${style.quiet("pinned  ")} ${pinned.length === 0 ? style.quiet("nothing -- run `synartesis pin`") : pinned.map(([name, tools]) => `${name} (${String(Object.keys(tools).length)})`).join(", ") + (unpinned.length === 0 ? "" : style.quiet(`; not ${unpinned.join(", ")}`))}`
+  );
   out("");
   out(`  ${style.quiet("Anything not mentioned here is treated as irreversible and guarded.")}`);
   out("");
@@ -2711,6 +2837,11 @@ async function runInstall(argv) {
     for (const server of plan.servers) {
       const note = server.adopted === void 0 ? style.accent("drafted, every tool held until you say how to undo it") : style.quiet(`the policy that ships for ${server.adopted} (${String(server.tools ?? 0)} tools)`);
       out(`    ${style.strong(server.name.padEnd(18))} ${note}`);
+      if (server.provenance === "documented") {
+        out(
+          `    ${" ".repeat(18)} ${style.accent("never run against the real server -- check it before trusting undo")}`
+        );
+      }
     }
     for (const skip of plan.skipped) {
       out(`    ${style.quiet(skip.name.padEnd(18))} ${style.quiet(skip.why)}`);
@@ -2921,18 +3052,19 @@ function pick(candidates2, given, noun, newest = false) {
   if (given === void 0) {
     const [only, ...rest2] = candidates2;
     if (only === void 0) {
-      throw new UsageError(`there is no ${noun.one} to act on`);
+      throw new UsageError(`there is no ${noun.one} to act on`, false);
     }
     if (rest2.length > 0 && !newest) {
       throw new UsageError(
         `there are ${String(candidates2.length)} ${noun.many}; name one, or use --all:
-${listed(candidates2)}`
+${listed(candidates2)}`,
+        false
       );
     }
     return only;
   }
   if (given === "") {
-    throw new UsageError(`no ${noun.one} was named; an empty id is usually an unset variable`);
+    throw new UsageError(`no ${noun.one} was named; an empty id is usually an unset variable`, false);
   }
   const exact = candidates2.find((item) => item.id === given);
   if (exact !== void 0) {
@@ -2941,12 +3073,13 @@ ${listed(candidates2)}`
   const matches = candidates2.filter((item) => item.id.startsWith(given));
   const [first, ...rest] = matches;
   if (first === void 0) {
-    throw new UsageError(`no ${noun.one} matches ${given}`);
+    throw new UsageError(`no ${noun.one} matches ${given}`, false);
   }
   if (rest.length > 0) {
     throw new UsageError(
       `${given} matches ${String(matches.length)} ${noun.many}:
-${listed(matches)}`
+${listed(matches)}`,
+      false
     );
   }
   return first;
@@ -2965,8 +3098,10 @@ function out(line2) {
 }
 function runList(journal, asJson, journalPath) {
   const runs = [...journal.listRuns()].reverse();
+  const tally2 = journal.tallyRuns();
+  const counted = (id) => tally2.get(id) ?? { actions: 0, unknown: 0, waiting: 0, applied: 0 };
   if (asJson) {
-    out(JSON.stringify(runs.map((run) => ({ ...run, actions: journal.getActions(run.id).length }))));
+    out(JSON.stringify(runs.map((run) => ({ ...run, actions: counted(run.id).actions }))));
     return 0;
   }
   if (runs.length === 0) {
@@ -2983,16 +3118,15 @@ function runList(journal, asJson, journalPath) {
     )
   );
   for (const run of runs) {
-    const actions = journal.getActions(run.id);
-    const unknown = actions.filter((action) => action.status === "pending").length;
-    const waiting = actions.filter((action) => action.status === "gated").length;
+    const actions = counted(run.id);
+    const { unknown, waiting } = actions;
     const notes = [
       unknown === 0 ? "" : `${String(unknown)} of unknown outcome`,
       waiting === 0 ? "" : `${String(waiting)} awaiting approval`
     ].filter((note2) => note2 !== "");
     const note = notes.length === 0 ? "" : `  ${style.accent(`(${notes.join("; ")})`)}`;
     out(
-      `  ${style.strong(run.id)}  ${style.quiet(shortTime(run.startedAt).trimEnd().padEnd(13))}  ${run.status.padEnd(12)}  ${String(actions.length).padStart(7)}  ${run.label ?? "-"}${note}`
+      `  ${style.strong(run.id)}  ${style.quiet(shortTime(run.startedAt).trimEnd().padEnd(13))}  ${run.status.padEnd(12)}  ${String(actions.actions).padStart(7)}  ${run.label ?? "-"}${note}`
     );
   }
   out("");
@@ -3062,7 +3196,7 @@ async function runShow(argv, journal, asJson) {
       out(`       ${style.quiet(summariseArgs(action.args, 96))}`);
     }
     if (action.approvedAt !== void 0) {
-      const verb = action.status === "denied" ? "denied" : "approved";
+      const verb = labelFor(action) === "denied" ? "denied" : "approved";
       out(
         `       ${style.accent(`${verb} by ${action.approvedBy ?? "nobody"}`)} ${style.quiet(`at ${fullTime(action.approvedAt)}`)}`
       );
@@ -3178,7 +3312,8 @@ function truncate3(text, limit) {
 function summarise2(actions) {
   const counts = /* @__PURE__ */ new Map();
   for (const action of actions) {
-    counts.set(action.status, (counts.get(action.status) ?? 0) + 1);
+    const label = labelFor(action);
+    counts.set(label, (counts.get(label) ?? 0) + 1);
   }
   const parts = [...counts].sort(([a], [b]) => a < b ? -1 : 1).map(([k, v]) => `${String(v)} ${k}`);
   const undoable = actions.filter((a) => a.inverse !== void 0).length;
@@ -3258,12 +3393,14 @@ function runPrune(argv, journal, journalPath) {
 function runClose(argv, journal) {
   const all = journal.listRuns();
   const given = positional(argv)[1];
-  const run = given === void 0 ? pick(
-    [...all.filter((candidate) => candidate.status === "active")].reverse(),
-    void 0,
-    RUN,
-    true
-  ) : pick([...all].reverse(), given, RUN, true);
+  const active = [...all.filter((candidate) => candidate.status === "active")].reverse();
+  if (given === void 0 && active.length === 0) {
+    out("");
+    out(`  ${style.quiet("nothing is open; every run has ended cleanly")}`);
+    out("");
+    return 0;
+  }
+  const run = given === void 0 ? pick(active, void 0, RUN, true) : pick([...all].reverse(), given, RUN, true);
   const closed = journal.closeAbandonedRun(run.id);
   out("");
   out(
@@ -3313,7 +3450,7 @@ function runDecision(argv, journal, approving) {
     const settled = journal.getAction(given);
     if (settled !== void 0 && settled.status !== "gated") {
       process.stderr.write(
-        `synartesis: ${given} is no longer awaiting approval (it is ${settled.status})
+        `synartesis: ${given} is no longer awaiting approval (it is ${labelFor(settled)})
 `
       );
       return 1;
@@ -3362,7 +3499,11 @@ function report(result, alreadyForcing = false) {
     if (step.plan !== void 0 && step.kind === "revert") {
       const verb = `${step.replanned === true ? "replanned, " : ""}${result.dryRun ? "would call" : "called"}`;
       out(
-        `       ${style.quiet(verb)} ${step.plan.server}.${step.plan.tool} ` + style.quiet(truncate3(JSON.stringify(step.plan.args), 120))
+        `       ${style.quiet(verb)} ${step.plan.server}.${step.plan.tool} ` + // summariseArgs, not truncated json: the raw form spent its whole
+        // budget on a long path's leading directories and cut off before
+        // the filename, so every step read "would call fs.write_file
+        // {path: /Users/.../very/long/pre..." and named nothing.
+        style.quiet(summariseArgs(step.plan.args, 120))
       );
     }
   }
@@ -3589,7 +3730,8 @@ var FLAGS = /* @__PURE__ */ new Set([
   "--help",
   "-h",
   "--version",
-  "-V"
+  "-V",
+  "-v"
 ]);
 function version() {
   try {
@@ -3625,12 +3767,13 @@ async function main(argv) {
     await import("./proxy.js");
     return 0;
   }
-  if (argv.includes("--help") || argv.includes("-h")) {
+  const first = positional(argv)[0];
+  if (argv.includes("--help") || argv.includes("-h") || first === "help") {
     process.stdout.write(`${banner()}
 ${COMMANDS}`);
     return 0;
   }
-  if (argv.includes("--version") || argv.includes("-V")) {
+  if (argv.includes("--version") || argv.includes("-V") || argv.includes("-v") || first === "version") {
     process.stdout.write(`${version()}
 `);
     return 0;
@@ -3677,6 +3820,9 @@ ${COMMANDS}`);
   if (command === "check") {
     return await runCheck(argv);
   }
+  if (command === "pin") {
+    return await runPin(argv);
+  }
   if (command === "install") {
     return await runInstall(argv);
   }
@@ -3764,9 +3910,12 @@ try {
   process.exitCode = await main(process.argv.slice(2));
 } catch (error) {
   if (error instanceof UsageError) {
-    process.stderr.write(`synartesis: ${error.message}
+    process.stderr.write(
+      error.listCommands ? `synartesis: ${error.message}
 
-${COMMANDS}`);
+${COMMANDS}` : `synartesis: ${error.message}
+`
+    );
     process.exitCode = 2;
   } else if (error instanceof ManifestError) {
     process.stderr.write(`synartesis: ${error.message}

package/dist/proxy.js

@@ -18,8 +18,11 @@ import {
   refusal,
   runRead,
   toPayload,
-  verifyAgainstServers
-} from "./chunk-DRDKIFD3.js";
+  untested,
+  verifyAgainstServers,
+  warnUntested,
+  withIdempotencyKey
+} from "./chunk-6X7GPUGJ.js";
 import {
   SnapshotError,
   UpstreamError,
@@ -730,7 +733,11 @@ function createProxyServer(options) {
         }
         const forwarded = {
           method: "tools/call",
-          params: { ...request.params, name: route.tool }
+          params: {
+            ...request.params,
+            name: route.tool,
+            _meta: withIdempotencyKey(request.params._meta, pending.idempotencyKey)
+          }
         };
         try {
           const result = await route.upstream.client.request(forwarded, PassthroughResult, {
@@ -775,6 +782,13 @@ function createProxyServer(options) {
               warnings.push(`inverse could not be resolved: ${describe(error)}`);
             }
           }
+          if (verify === void 0 && policy.verify !== void 0) {
+            try {
+              verify = planRead(policy.verify, context);
+            } catch (error) {
+              warnings.push(`the drift check could not be planned: ${describe(error)}`);
+            }
+          }
           let postSnapshot;
           if (verify !== void 0) {
             try {
@@ -1109,6 +1123,10 @@ async function main() {
     process.stderr.write(mark());
   }
   const manifest = loadManifest(argv.manifest);
+  const unproven = untested(manifest);
+  if (unproven.length > 0) {
+    log.warn({ servers: unproven }, warnUntested(unproven));
+  }
   const journal = openJournal(argv.journal);
   const declared = Object.entries(manifest.servers);
   const wanted = argv.server === void 0 ? declared : declared.filter(([name]) => name === argv.server);

package/manifests/filesystem.yaml

@@ -14,6 +14,7 @@ servers:
   fs:
     command: node
     args: ["node_modules/@modelcontextprotocol/server-filesystem/dist/index.js", "."]
+    provenance: live
 
 tools:
   # --- reads -------------------------------------------------------------
@@ -105,3 +106,10 @@ tools:
   - match: "fs.create_directory"
     class: irreversible
     gate: always
+
+# This policy is written for the server version named at the top. A later
+# version can keep a tool's name and change what it takes, which would leave
+# the policy above describing something else -- and undo would still produce an
+# answer. `synartesis pin` prints a `pins:` block for the server you actually
+# have; with it pasted in, a tool whose shape has moved stops the proxy at
+# startup instead of being quietly trusted.

package/manifests/git.yaml

@@ -15,6 +15,7 @@ servers:
   git:
     command: uvx
     args: ["--from", "mcp-server-git", "mcp-server-git"]
+    provenance: live
 
 tools:
   # --- reads -------------------------------------------------------------
@@ -75,3 +76,10 @@ tools:
   - match: "git.git_checkout"
     class: irreversible
     gate: never
+
+# This policy is written for the server version named at the top. A later
+# version can keep a tool's name and change what it takes, which would leave
+# the policy above describing something else -- and undo would still produce an
+# answer. `synartesis pin` prints a `pins:` block for the server you actually
+# have; with it pasted in, a tool whose shape has moved stops the proxy at
+# startup instead of being quietly trusted.

package/manifests/github.yaml

@@ -24,6 +24,9 @@ servers:
     # Read from your shell; never written into this file.
     env:
       GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_PERSONAL_ACCESS_TOKEN}"
+    # Nothing here has met a real github; every shape below comes from
+    # documentation. That is a weaker claim than the others make.
+    provenance: documented
 
 tools:
   # --- reads -------------------------------------------------------------
@@ -188,3 +191,10 @@ tools:
   - match: "github.create_release"
     class: irreversible
     gate: always
+
+# This policy is written for the server version named at the top. A later
+# version can keep a tool's name and change what it takes, which would leave
+# the policy above describing something else -- and undo would still produce an
+# answer. `synartesis pin` prints a `pins:` block for the server you actually
+# have; with it pasted in, a tool whose shape has moved stops the proxy at
+# startup instead of being quietly trusted.

package/manifests/memory.yaml

@@ -18,6 +18,7 @@ servers:
     # or the agent will remember into a different file than it reads from.
     env:
       MEMORY_FILE_PATH: "${MEMORY_FILE_PATH}"
+    provenance: live
 
 tools:
   # --- reads -------------------------------------------------------------
@@ -54,6 +55,16 @@ tools:
       tool: "memory.delete_entities"
       args:
         entityNames: "$result.entities[].name"
+    # Deleting an entity takes its observations and its relations with it. So
+    # the compensating delete is only safe while the entity is still the thing
+    # the agent made: if anybody has added to it since, undoing destroys work
+    # nobody recorded. There is no pre-read to compare against -- the entity
+    # did not exist before the call -- so this reads it back afterwards, and
+    # undo halts rather than deleting over somebody.
+    verify:
+      tool: "memory.open_nodes"
+      args:
+        names: "$result.entities[].name"
 
   - match: "memory.create_relations"
     class: compensable
@@ -94,3 +105,10 @@ tools:
   - match: "memory.delete_observations"
     class: irreversible
     gate: always
+
+# This policy is written for the server version named at the top. A later
+# version can keep a tool's name and change what it takes, which would leave
+# the policy above describing something else -- and undo would still produce an
+# answer. `synartesis pin` prints a `pins:` block for the server you actually
+# have; with it pasted in, a tool whose shape has moved stops the proxy at
+# startup instead of being quietly trusted.