synartesis 0.6.12 → 0.6.15

package/dist/cli.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import {
+  IDEMPOTENCY_META_KEY,
   NOTHING_RECORDED_YET,
+  PROXY_FLAGS,
   WORDMARK,
   banner,
   canonical,
@@ -8,6 +10,8 @@ import {
   connectStdioUpstream,
   createPolicyResolver,
   createRouter,
+  describeStanding,
+  errorStyle,
   findJournal,
   findManifest,
   labelFor,
@@ -16,18 +20,23 @@ import {
   openJournal,
   parseManifest,
   pathBinaryMatches,
+  pinBlock,
   planInverse,
   planRead,
   proxyCommand,
   qualify,
   resolvedRead,
   rule,
+  standing,
   style,
   toPayload,
   toResolvedRead,
+  toolShapes,
+  untested,
   verifyAgainstServers,
+  warnUntested,
   wasRefused
-} from "./chunk-FUVEHRJP.js";
+} from "./chunk-OODDXM36.js";
 import {
   DriftConflict,
   ManifestError,
@@ -95,7 +104,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 +270,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 +308,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 +350,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 +368,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 +611,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 +691,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") {
@@ -745,24 +788,6 @@ function verdict(inspection) {
   return "nothing was recorded in this session";
 }
 
-// src/watch.ts
-import { existsSync as existsSync2 } from "fs";
-
-// src/keys.ts
-var SEQUENCE = /^\u001b(\[[0-9;?]*[ -\/]*[@-~]|O[@-~])/;
-function keysIn(chunk) {
-  const keys = [];
-  let at = 0;
-  while (at < chunk.length) {
-    const rest = chunk.slice(at);
-    const sequence = rest.startsWith("\x1B") ? SEQUENCE.exec(rest) : null;
-    const key = sequence?.[0] ?? rest.slice(0, 1);
-    keys.push(key);
-    at += key.length;
-  }
-  return keys;
-}
-
 // src/clock.ts
 var MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
 var pad = (value) => String(value).padStart(2, "0");
@@ -814,6 +839,169 @@ function ago(iso, now = /* @__PURE__ */ new Date()) {
   return `${String(Math.round(hours / 24))}d ago`;
 }
 
+// src/hints.ts
+function hintsWanted() {
+  return process.env["SYNARTESIS_NO_HINTS"] === void 0;
+}
+function hintLine(hint2, paths = "") {
+  if (hint2.run === void 0) {
+    return `  ${style.quiet(hint2.why)}`;
+  }
+  return `  ${style.quiet(`${hint2.why}:`)}  ${style.strong(`${cliCommand()} ${hint2.run}${paths}`)}`;
+}
+function short(id) {
+  return id.slice(0, 8);
+}
+function heldCalls(journal) {
+  const waiting = journal.listGated();
+  const [first, ...rest] = waiting;
+  if (first === void 0) {
+    return void 0;
+  }
+  if (rest.length === 0) {
+    return {
+      why: `${first.server}.${first.tool} is held, and the agent is waiting on you`,
+      run: `approve ${short(first.id)}`,
+      needs: ["journal"]
+    };
+  }
+  return {
+    why: `${String(waiting.length)} calls are held, and the agent is waiting on you`,
+    run: "approve --all",
+    needs: ["journal"]
+  };
+}
+function whatChanged(journal) {
+  const run = journal.newestUndoable();
+  if (run === void 0) {
+    return void 0;
+  }
+  return {
+    why: `${run.label ?? "an agent"} changed something ${ago(run.startedAt)}`,
+    run: `show ${short(run.id)}`,
+    needs: ["journal"]
+  };
+}
+function notPinned(manifest) {
+  const pinned = Object.keys(manifest.pins ?? {});
+  const loose = Object.keys(manifest.servers).filter((name) => !pinned.includes(name));
+  if (loose.length === 0) {
+    return void 0;
+  }
+  return {
+    why: pinned.length === 0 ? "no tool here is pinned, so a server that changes shape keeps its old policy" : `${loose.join(", ")} ${loose.length === 1 ? "is" : "are"} not pinned`,
+    run: "pin",
+    needs: ["manifest"]
+  };
+}
+var LEAVE_IT_RUNNING = {
+  why: "anything an agent holds will appear here as it happens",
+  run: "watch",
+  needs: ["journal"]
+};
+function afterStatus(journal) {
+  if (journal === void 0) {
+    return LEAVE_IT_RUNNING;
+  }
+  return firstOf(
+    () => heldCalls(journal),
+    () => whatChanged(journal),
+    () => LEAVE_IT_RUNNING
+  );
+}
+function firstOf(...candidates2) {
+  for (const candidate of candidates2) {
+    const hint2 = candidate();
+    if (hint2 !== void 0) {
+      return hint2;
+    }
+  }
+  return void 0;
+}
+function didYouMean(typed, known) {
+  if (typed.length < 3) {
+    return void 0;
+  }
+  const ceiling = typed.length <= 4 ? 1 : 2;
+  let best;
+  let bestAt = ceiling + 1;
+  for (const candidate of known) {
+    const gap = distance(typed, candidate);
+    if (gap < bestAt) {
+      best = candidate;
+      bestAt = gap;
+    }
+  }
+  return bestAt <= ceiling ? best : void 0;
+}
+function distance(from, to) {
+  const rows = [];
+  for (let i = 0; i <= from.length; i += 1) {
+    const row = new Array(to.length + 1).fill(0);
+    row[0] = i;
+    rows.push(row);
+  }
+  const top = rows[0];
+  for (let j = 0; j <= to.length && top !== void 0; j += 1) {
+    top[j] = j;
+  }
+  for (let i = 1; i <= from.length; i += 1) {
+    for (let j = 1; j <= to.length; j += 1) {
+      const same = from[i - 1] === to[j - 1];
+      let best = Math.min(
+        (rows[i - 1]?.[j] ?? 0) + 1,
+        (rows[i]?.[j - 1] ?? 0) + 1,
+        (rows[i - 1]?.[j - 1] ?? 0) + (same ? 0 : 1)
+      );
+      if (i > 1 && j > 1 && from[i - 1] === to[j - 2] && from[i - 2] === to[j - 1]) {
+        best = Math.min(best, (rows[i - 2]?.[j - 2] ?? 0) + 1);
+      }
+      const row = rows[i];
+      if (row !== void 0) {
+        row[j] = best;
+      }
+    }
+  }
+  return rows[from.length]?.[to.length] ?? to.length;
+}
+var EVERYDAY = [
+  ["install", "cover the servers your client already lists"],
+  ["watch", "see what an agent does, and answer what it holds"],
+  ["list", "the sessions recorded so far"],
+  ["show", "what one session did, and whether it still holds"],
+  ["undo", "put back what one of them changed"]
+];
+function shortList() {
+  const self = cliCommand();
+  return [
+    "",
+    ...EVERYDAY.map(
+      ([name, said]) => `  ${errorStyle.strong(`${self} ${name.padEnd(8)}`)} ${errorStyle.quiet(said)}`
+    ),
+    "",
+    `  ${errorStyle.quiet(`${self} --help for every command.`)}`,
+    ""
+  ].join("\n");
+}
+
+// src/watch.ts
+import { existsSync as existsSync2 } from "fs";
+
+// src/keys.ts
+var SEQUENCE = /^\u001b(\[[0-9;?]*[ -\/]*[@-~]|O[@-~])/;
+function keysIn(chunk) {
+  const keys = [];
+  let at = 0;
+  while (at < chunk.length) {
+    const rest = chunk.slice(at);
+    const sequence = rest.startsWith("\x1B") ? SEQUENCE.exec(rest) : null;
+    const key = sequence?.[0] ?? rest.slice(0, 1);
+    keys.push(key);
+    at += key.length;
+  }
+  return keys;
+}
+
 // src/describe.ts
 import { basename } from "path";
 var SUBJECT_KEYS = [
@@ -881,6 +1069,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 +1089,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)) {
@@ -1459,8 +1660,8 @@ function pruneBackups(path) {
   try {
     const dir = dirname(path);
     const prefix = `${basename2(path)}.synartesis-backup-`;
-    const ours = readdirSync(dir).filter((name) => name.startsWith(prefix)).sort();
-    for (const name of ours.slice(0, Math.max(0, ours.length - KEEP_BACKUPS))) {
+    const ours2 = readdirSync(dir).filter((name) => name.startsWith(prefix)).sort();
+    for (const name of ours2.slice(0, Math.max(0, ours2.length - KEEP_BACKUPS))) {
       rmSync(join(dir, name), { force: true });
     }
   } catch {
@@ -1643,7 +1844,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 +2082,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 +2102,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 +2343,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 +2564,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 +2586,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 +2746,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>]
@@ -2609,29 +2815,58 @@ it and is found from any directory inside it, the way a version control tool
 finds its root; anything else lives in ~/.synartesis, which is where the
 journal is too. Set SYNARTESIS_HOME to put that somewhere else.
 
+Most commands end by naming the one thing worth doing next, worked out from
+what is actually in the journal rather than from what was typed. Set
+SYNARTESIS_NO_HINTS to turn that off; --json never carries it.
+
 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 ours(argv) {
+  const end = argv.indexOf("--");
+  return end === -1 ? argv : argv.slice(0, end);
+}
 function flag(argv, name) {
-  const at = argv.indexOf(name);
+  const mine = ours(argv);
+  const at = mine.indexOf(name);
   if (at === -1) {
     return void 0;
   }
-  const value = argv[at + 1];
+  const value = mine[at + 1];
   if (value === void 0 || value.startsWith("--")) {
     throw new UsageError(`${name} needs a value`);
   }
   return value;
 }
+var TAKES_VALUE = /* @__PURE__ */ new Set([
+  "--manifest",
+  "--journal",
+  "--to",
+  "--by",
+  "--reason",
+  "--older-than",
+  "--client"
+]);
 function positional(argv) {
-  const skip = /* @__PURE__ */ new Set(["--manifest", "--journal", "--to", "--by", "--reason", "--gate-timeout", "--older-than", "--client"]);
   const values = [];
-  const end = argv.indexOf("--");
-  const ours = end === -1 ? argv : argv.slice(0, end);
-  for (let i = 0; i < ours.length; i += 1) {
-    const token = ours[i] ?? "";
-    if (skip.has(token)) {
+  const mine = ours(argv);
+  for (let i = 0; i < mine.length; i += 1) {
+    const token = mine[i] ?? "";
+    if (TAKES_VALUE.has(token)) {
       i += 1;
       continue;
     }
@@ -2641,9 +2876,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,11 +2950,33 @@ 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("");
+  hint(
+    firstOf(
+      () => notPinned(manifest),
+      () => ({
+        why: "this is sound; to see which clients it covers",
+        run: "status",
+        needs: ["manifest", "journal"]
+      })
+    )
+  );
   return 0;
 }
 async function runInstall(argv) {
@@ -2711,6 +3010,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)}`);
@@ -2866,6 +3170,9 @@ function runStatus(argv) {
       waiting === 0 ? `  ${style.quiet("Everything found is covered.")}` : `  ${style.accent(`${String(waiting)} not covered.`)} ${style.quiet(`${cliCommand()} install covers them.`)}`
     );
     out("");
+    if (waiting === 0) {
+      hint(afterStatus(journal));
+    }
   } finally {
     journal?.close();
   }
@@ -2921,18 +3228,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 +3249,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;
@@ -2963,10 +3272,19 @@ function out(line2) {
   process.stdout.write(`${line2}
 `);
 }
+function hint(candidate) {
+  if (candidate === void 0 || !hintsWanted()) {
+    return;
+  }
+  out(hintLine(candidate, pathArgs(candidate.needs)));
+  out("");
+}
 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 +3301,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("");
@@ -3000,6 +3317,10 @@ function runList(journal, asJson, journalPath) {
     out(`  ${style.quiet(`This journal is ${sizeOf(journalPath)}; synartesis prune reclaims what is old enough to lose.`)}`);
     out("");
   }
+  hint(firstOf(
+    () => heldCalls(journal),
+    () => whatChanged(journal)
+  ));
   return 0;
 }
 async function runShow(argv, journal, asJson) {
@@ -3062,7 +3383,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)}`)}`
       );
@@ -3097,6 +3418,16 @@ async function runShow(argv, journal, asJson) {
       out(
         `  ${style.quiet("undo stops at the first of them; ")}${style.strong(`${cliCommand()} undo ${runId.slice(0, 8)} --force`)}${style.quiet(" shows what it would write")}`
       );
+    } else if (actions.some((action) => action.status === "applied" && action.inverse !== void 0)) {
+      out("");
+      hint({
+        // Not a restatement of the verdict directly above it, which has just
+        // said in its own words that nothing has moved. A hint that repeats
+        // the line above is a line nobody reads twice.
+        why: "to see the plan, before anything is written",
+        run: `undo ${runId.slice(0, 8)} --dry-run`,
+        needs: ["manifest", "journal"]
+      });
     }
   } else {
     out("");
@@ -3178,13 +3509,21 @@ 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;
   return `${String(actions.length)} actions: ${parts.join(", ")} | ${String(undoable)} with a recorded undo`;
 }
 var journalArg = "";
+var manifestArg = "";
+function pathArgs(needs) {
+  if (needs === void 0) {
+    return "";
+  }
+  return needs.map((what) => what === "journal" ? journalArg : manifestArg).join("");
+}
 var PRUNE_NAG_BYTES = 100 * 1024 * 1024;
 function bytesOf(path) {
   try {
@@ -3258,12 +3597,18 @@ 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("");
+    hint(firstOf(
+      () => heldCalls(journal),
+      () => whatChanged(journal)
+    ));
+    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(
@@ -3282,6 +3627,10 @@ function runGates(journal, asJson) {
     out("");
     out(`  ${style.quiet("Nothing is waiting for a decision.")}`);
     out("");
+    hint(firstOf(
+      () => whatChanged(journal),
+      () => LEAVE_IT_RUNNING
+    ));
     return 0;
   }
   out("");
@@ -3310,10 +3659,10 @@ function runDecision(argv, journal, approving) {
   const by = flag(argv, "--by") ?? process.env["USER"] ?? process.env["LOGNAME"] ?? "unknown";
   const reason = flag(argv, "--reason") ?? "denied by operator";
   if (given !== void 0) {
-    const settled = journal.getAction(given);
-    if (settled !== void 0 && settled.status !== "gated") {
+    const settled2 = journal.getAction(given);
+    if (settled2 !== void 0 && settled2.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(settled2)})
 `
       );
       return 1;
@@ -3325,6 +3674,7 @@ function runDecision(argv, journal, approving) {
     return 0;
   }
   let failed = 0;
+  let settled = 0;
   for (const action of targets) {
     const changed = approving ? journal.approve(action.id, by) : journal.deny(action.id, by, reason);
     if (!changed) {
@@ -3336,13 +3686,23 @@ function runDecision(argv, journal, approving) {
       failed += 1;
       continue;
     }
+    settled += 1;
     out(
       `  ${style.accent(approving ? "approved" : "denied")} ${style.strong(`${action.server}.${action.tool}`)} ${style.quiet(action.id)}`
     );
   }
+  if (settled > 0) {
+    out("");
+    hint(
+      firstOf(
+        () => heldCalls(journal),
+        () => approving ? { why: "the agent can make that call again now, and it will go through" } : { why: "the call was refused; the agent is told, and decides what to do next" }
+      )
+    );
+  }
   return failed === 0 ? 0 : 1;
 }
-function report(result, alreadyForcing = false) {
+function report(result, alreadyForcing = false, as = "") {
   out("");
   out(`  ${style.label(result.dryRun ? "dry run" : "undo")}  ${style.strong(result.runId)}`);
   out(`  ${rule(72)}`);
@@ -3362,7 +3722,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))
       );
     }
   }
@@ -3411,6 +3775,13 @@ function report(result, alreadyForcing = false) {
     `  ${style.label("result")}  ${result.status === "rolled_back" ? result.status : style.accent(result.status)}`
   );
   out("");
+  if (result.dryRun && result.status === "rolled_back") {
+    hint({
+      why: "nothing was written; to do exactly this for real",
+      run: `undo ${result.runId.slice(0, 8)}${as}`,
+      needs: ["manifest", "journal"]
+    });
+  }
   return result.status === "rolled_back" ? 0 : 1;
 }
 async function withUpstreams(manifestPath, use, only) {
@@ -3471,6 +3842,11 @@ async function performUndo(manifestPath, journal, runId, options) {
   );
 }
 async function runUndo(argv, journal) {
+  const rawTo = flag(argv, "--to");
+  const toSeq = rawTo === void 0 ? void 0 : Number(rawTo);
+  if (toSeq !== void 0 && (!Number.isInteger(toSeq) || toSeq < 1)) {
+    throw new UsageError("--to needs a positive whole number");
+  }
   const given = positional(argv)[1];
   const chosen = pick([...journal.listRuns()].reverse(), given, RUN, true);
   const runId = chosen.id;
@@ -3506,11 +3882,6 @@ async function runUndo(argv, journal) {
       return 0;
     }
   }
-  const rawTo = flag(argv, "--to");
-  const toSeq = rawTo === void 0 ? void 0 : Number(rawTo);
-  if (toSeq !== void 0 && (!Number.isInteger(toSeq) || toSeq < 1)) {
-    throw new UsageError("--to needs a positive whole number");
-  }
   if (toSeq !== void 0) {
     const highest = journal.getActions(runId).reduce((top, action) => Math.max(top, action.seq), 0);
     if (toSeq > highest) {
@@ -3554,16 +3925,42 @@ async function runUndo(argv, journal) {
       return 1;
     }
   }
+  const replan = argv.includes("--replan");
   return report(
     await performUndo(manifestPath, journal, runId, {
       dryRun: argv.includes("--dry-run"),
       ...toSeq === void 0 ? {} : { toSeq },
-      replan: argv.includes("--replan"),
+      replan,
       ...forcing && said ? { force: true } : {}
     }),
-    forcing
+    forcing,
+    // --to is deliberately absent, and cannot reach here: a floor leaves
+    // actions below it alone, which makes the result `partial`, and the hint
+    // is only offered on `rolled_back`.
+    `${replan ? " --replan" : ""}${forcing && said ? " --force --yes" : ""}`
   );
 }
+var KNOWN_COMMANDS = [
+  "install",
+  "uninstall",
+  "status",
+  "init",
+  "check",
+  "pin",
+  "list",
+  "show",
+  "gates",
+  "close",
+  "prune",
+  "proxy",
+  "desktop",
+  "watch",
+  "approve",
+  "deny",
+  "undo",
+  "help",
+  "version"
+];
 var FLAGS = /* @__PURE__ */ new Set([
   // Two lists have to agree about a flag: this one decides whether it is
   // accepted at all, and the skip set in positional() decides whether its
@@ -3589,7 +3986,8 @@ var FLAGS = /* @__PURE__ */ new Set([
   "--help",
   "-h",
   "--version",
-  "-V"
+  "-V",
+  "-v"
 ]);
 function version() {
   try {
@@ -3601,13 +3999,26 @@ function version() {
     return "unknown";
   }
 }
+function unknownCommand(typed) {
+  const meant = didYouMean(typed, KNOWN_COMMANDS);
+  return meant === void 0 ? `unknown command ${typed}` : `unknown command ${typed}; did you mean ${meant}?`;
+}
 function rejectUnknownFlags(argv) {
-  for (const token of argv) {
-    if (token === "--") {
-      return;
+  const mine = ours(argv);
+  for (let i = 0; i < mine.length; i += 1) {
+    const token = mine[i] ?? "";
+    if (TAKES_VALUE.has(token)) {
+      i += 1;
+      continue;
     }
     if (token.startsWith("-") && token !== "-" && !FLAGS.has(token)) {
-      throw new UsageError(`unknown flag ${token}`);
+      if (PROXY_FLAGS.includes(token)) {
+        throw new UsageError(`${token} is a flag for ${cliCommand()} proxy, not for this`);
+      }
+      const meant = didYouMean(token, [...FLAGS]);
+      throw new UsageError(
+        meant === void 0 ? `unknown flag ${token}` : `unknown flag ${token}; did you mean ${meant}?`
+      );
     }
   }
 }
@@ -3625,17 +4036,25 @@ 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;
   }
   rejectUnknownFlags(argv);
+  if (command !== void 0 && !KNOWN_COMMANDS.includes(command)) {
+    throw new UsageError(unknownCommand(command));
+  }
+  const givenJournal = flag(argv, "--journal");
+  const givenManifest = flag(argv, "--manifest");
+  journalArg = givenJournal === void 0 ? "" : ` --journal ${resolve3(givenJournal)}`;
+  manifestArg = givenManifest === void 0 ? "" : ` --manifest ${resolve3(givenManifest)}`;
   if (command === void 0) {
     const manifestPath = findManifest(flag(argv, "--manifest"));
     const journalPath2 = findJournal(flag(argv, "--journal"), manifestPath);
@@ -3677,6 +4096,9 @@ ${COMMANDS}`);
   if (command === "check") {
     return await runCheck(argv);
   }
+  if (command === "pin") {
+    return await runPin(argv);
+  }
   if (command === "install") {
     return await runInstall(argv);
   }
@@ -3701,7 +4123,6 @@ ${COMMANDS}`);
       decideAs: flag(argv, "--by") ?? process.env["USER"] ?? process.env["LOGNAME"] ?? "unknown"
     });
   }
-  journalArg = given === void 0 ? "" : ` --journal ${resolve3(given)}`;
   if (!existsSync8(journalPath) && (command === "list" || command === "show" || command === "gates")) {
     if (asJson) {
       out(JSON.stringify(command === "show" ? { run: null, actions: [] } : []));
@@ -3739,7 +4160,7 @@ ${COMMANDS}`);
       case "undo":
         return await runUndo(argv, journal);
       default:
-        throw new UsageError(`unknown command ${command}`);
+        throw new UsageError(unknownCommand(command));
     }
   } finally {
     journal.close();
@@ -3764,9 +4185,11 @@ try {
   process.exitCode = await main(process.argv.slice(2));
 } catch (error) {
   if (error instanceof UsageError) {
-    process.stderr.write(`synartesis: ${error.message}
-
-${COMMANDS}`);
+    process.stderr.write(
+      error.listCommands ? `synartesis: ${error.message}
+${shortList()}` : `synartesis: ${error.message}
+`
+    );
     process.exitCode = 2;
   } else if (error instanceof ManifestError) {
     process.stderr.write(`synartesis: ${error.message}