synartesis 0.6.13 → 0.6.15

package/CHANGELOG.md

@@ -2,6 +2,126 @@
 
 What changed, and why it mattered. Dates are release dates.
 
+## 0.6.15 — 2026-09-15
+
+One gap, named by a stranger on Reddit and real.
+
+### Security
+
+- **A retry of a call whose outcome nobody could establish is now held for a
+  person.** The tri-state was already there -- a write that times out is not
+  called `failed`, the resource is re-read to see which way it went, and what
+  cannot be settled is left `pending`, which undo refuses to step over. What
+  was missing was the other half: nothing stopped the agent from simply making
+  the call again.
+
+  The idempotency key cannot close this. It is `runId:seq`, so a retry is a new
+  row under a different key and no upstream can tell the two attempts were one
+  intention -- checked against the real proxy, which records `seq=1 key=…:1`
+  and `seq=2 key=…:2`. A comment beside the forward call claimed otherwise and
+  has been corrected.
+
+  So the person who can go and look is asked before a second side effect
+  exists. It reuses the gate rather than inventing a second mechanism: the call
+  appears in `synartesis gates` with a reason that says what happened, rather
+  than the generic policy text.
+
+  Three things it deliberately does not do. It never holds a **read** -- a read
+  that timed out is left `pending` like anything else, but reading twice
+  changes nothing, and an agent may always look freely. It holds only the
+  **identical** call, matched on server, tool and arguments: the uncertainty is
+  about one call, not about the tool. And approving the retry **does not
+  resolve the first attempt** -- that row stays `pending` and undo still stops
+  on it, because saying yes to going forward is not a claim about what already
+  happened.
+
+### Performance
+
+- `findPending` runs on the way in to every write, and left to choose sqlite
+  walked every action in the run -- rows that carry the snapshots -- to find
+  the handful that are pending. A partial index over exactly those rows, named
+  explicitly, on a single run of twenty thousand actions with two-kilobyte
+  snapshots: **24ms a call to 0.004ms**.
+
+## 0.6.14 — 2026-09-15 (tagged, never published)
+
+The terminal now says what to do next, and the argument parser stopped
+disagreeing with itself.
+
+### Added
+
+- **Most commands end by naming the one thing worth doing next**, with the
+  session id already filled in:
+
+  ```
+  fs.create_directory is held, and the agent is waiting on you:  synartesis approve f0c9935d
+  ```
+
+  It is worked out from the journal rather than from what was typed, so it
+  changes as the state does. A call held for approval outranks everything else
+  -- that is an agent stopped mid-task waiting on a person who may not know it
+  is waiting. Below that: the session that changed something, what is not
+  pinned, and `watch`. There is at most one, there is none when nothing
+  applies, and `--json` never carries it. `SYNARTESIS_NO_HINTS` turns it off.
+
+  The session it names is not simply the newest one. A client that connects
+  and reads opens a session like any other, so "the last thing that happened"
+  is regularly a session in which nothing happened; a session that only read,
+  or was already undone, or was held and never ran, is never offered for undo.
+
+- **A mistyped command gets the word that was meant.** `synartesis lst` used to
+  answer with forty lines of help, thirty-nine of them about something the
+  person was not doing. It now says `did you mean list?` and lists five
+  commands. Flags too: `--jounral`, `--dryrun`, `--forse` all resolve.
+
+- **A flag that belongs to `proxy` is named as such.** `--http`, `--token`,
+  `--server` and `--log-level` are in the help page, and answering one of them
+  with "unknown flag" sent people hunting through that page for a flag already
+  in it.
+
+### Fixed
+
+- **A wrapped server's own flags were read as ours.** `synartesis init db --
+  some-server --manifest audit.yaml` handed `--manifest` to the server
+  correctly and *also* took it, writing the policy to a path nobody asked for
+  -- on a machine where that path is real, one they already had. `positional`
+  and the unknown-flag check had always stopped at the bare `--`; the flag
+  reader had not.
+
+- **The value of a flag was read as a flag.** `deny --reason "-see ticket 42"`
+  answered `unknown flag -see ticket 42`, and `prune --older-than -5` answered
+  `unknown flag -5` instead of the message that knows what `--older-than` is
+  for. Three separate lists had to agree about which flags take a value and
+  did not; there is one now, and a test holds it against the help page.
+
+- **`undo --to 0` announced the session before refusing.** It printed "no
+  session named, so the most recent: a42bf93a" and only then rejected the
+  flag, which reads as though that session had been acted on.
+
+- **A hint that could not be pasted.** `list --journal ./bench.db` named a
+  session, and the `show` it offered read the *default* journal and answered
+  "no run matches". Hints now carry `--journal` and `--manifest` when those
+  were not the obvious ones, and `undo --replan --dry-run` offers a command
+  that still replans.
+
+- **Guessing at a typo was too eager.** A ceiling of half the word answered
+  `--server` with `--live` and `--token` with `--to`, neither of which anybody
+  meant. Two edits at most now, never for a word under three characters, and a
+  swapped pair counts as the one mistake it feels like -- which is what keeps
+  `shwo`, `pruen` and `--jounral` reachable at that ceiling.
+
+- **Colour was decided for both streams from stdout**, so `synartesis nonsense
+  2> errors.log` in a terminal wrote escape sequences into the file.
+
+### Performance
+
+- **`newestUndoable` runs on every `list`** and could only be answered by
+  reading the action rows, which carry the snapshots -- so the cost of one
+  screen of sessions grew with the size of the data rather than the number of
+  sessions. A partial index over exactly the rows it wants fixes that, but only
+  when named: left to choose, sqlite takes `actions_gated` and reads the rows
+  anyway. Measured on a 246MB journal: **56ms to 0.01ms**.
+
 ## 0.6.13 — 2026-09-14
 
 Four things, all of them from one comment by a stranger on Reddit who had
@@ -10,6 +130,26 @@ would have announced itself.
 
 ### Security
 
+- **A server that would not start said nothing useful about why, and could
+  hang the proxy outright.** Two faults in the same few lines, found by hitting
+  the first one in real use.
+
+  What it printed was `code: 'MODULE_NOT_FOUND', requireStack: [], },
+  Node.js v22.16.0` -- the last four lines of node's output, which are the four
+  least informative. `Error: Cannot find module '/path/to/thing'` sits in the
+  middle and was thrown away, so the message named neither the file nor
+  anything to act on. A line that states a fault now leads, stack frames are
+  dropped, and the tail is only the fallback when nothing states one.
+
+  The second was worse and was found while testing the first: nothing read the
+  server's stderr until after the connection failed. A pipe nobody reads fills
+  at around 64kB and blocks the writer, so a server that said more than that
+  before dying never exited, the connect never rejected, and `check` sat there
+  for ever with no output at all. Measured against a server writing 2.4MB to
+  stderr: **killed at 30 seconds, against 0.8 seconds and the right error**.
+  Stderr is now read as it arrives, capped so a logging loop cannot make the
+  proxy the thing that runs out of memory.
+
 - **The one remaining advisory is gone.** `esbuild` reached `pnpm audit`
   through vite, in the renderer build only -- never in anything published, and
   `--prod` was already clean. Pinned anyway, the same way as 0.6.12's three:

package/dist/{chunk-6X7GPUGJ.js → chunk-OODDXM36.js}

@@ -6,6 +6,19 @@ import {
   describe
 } from "./chunk-YVOO3PTV.js";
 
+// src/proxy/flags.ts
+var PROXY_FLAGS = [
+  "--manifest",
+  "--journal",
+  "--server",
+  "--gate-timeout",
+  "--log-level",
+  "--http",
+  "--http-host",
+  "--http-idle",
+  "--token"
+];
+
 // src/invocation.ts
 import { spawnSync } from "child_process";
 import { accessSync, constants } from "fs";
@@ -131,23 +144,25 @@ var INK = `${ESC}38;2;214;201;197m`;
 var DIM = `${ESC}2m`;
 var BOLD = `${ESC}1m`;
 var RESET = `${ESC}0m`;
-var enabled = process.env["NO_COLOR"] === void 0 && process.env["TERM"] !== "dumb" && process.stdout.isTTY;
-function paint(codes, text) {
-  return enabled ? `${codes}${text}${RESET}` : text;
+function usable(stream) {
+  return process.env["NO_COLOR"] === void 0 && process.env["TERM"] !== "dumb" && stream.isTTY;
 }
 function spaced(text) {
   return Array.from(text).join(" ");
 }
-var style = {
-  /** A section label: small, capital, spaced out. */
-  label: (text) => paint(ACCENT + DIM, spaced(text.toUpperCase())),
-  heading: (text) => paint(INK, text.toUpperCase()),
-  accent: (text) => paint(ACCENT, text),
-  strong: (text) => paint(INK, text),
-  quiet: (text) => paint(DIM, text),
-  /** Off-white on oxblood, the way the wordmark is set. */
-  plate: (text) => paint(ON_ACCENT + BOLD, ` ${text} `)
-};
+function palette(on) {
+  const paint = (codes, text) => on ? `${codes}${text}${RESET}` : text;
+  return {
+    label: (text) => paint(ACCENT + DIM, spaced(text.toUpperCase())),
+    heading: (text) => paint(INK, text.toUpperCase()),
+    accent: (text) => paint(ACCENT, text),
+    strong: (text) => paint(INK, text),
+    quiet: (text) => paint(DIM, text),
+    plate: (text) => paint(ON_ACCENT + BOLD, ` ${text} `)
+  };
+}
+var style = palette(usable(process.stdout));
+var errorStyle = palette(usable(process.stderr));
 var WORDMARK = spaced("SYNARTESIS");
 function meander(width) {
   const unit = "\u2517\u2501\u2513\u250F\u2501\u251B";
@@ -270,6 +285,34 @@ CREATE INDEX IF NOT EXISTS actions_gated ON actions(status, ts);
 -- no meaning changes, IF NOT EXISTS makes it idempotent, and an older build
 -- opening the same file afterwards neither notices nor cares.
 CREATE INDEX IF NOT EXISTS actions_run_status ON actions(run_id, status);
+
+-- Partial, which is what makes it small: newestUndoable asks for the newest run
+-- holding something an undo would reverse, and that is a handful of rows out of
+-- a table where every other row is a read, a refusal or something already put
+-- back. Without it the question can only be answered by reaching into the table
+-- to test inverse_json on every applied row -- and those rows carry the
+-- snapshots, so the cost of the hint at the foot of a session list grew with
+-- the size of the data rather than with the number of sessions, which is
+-- exactly what the index above was added to stop. Measured on sixty runs of a
+-- thousand actions with two-kilobyte snapshots, a 246MB journal: 56ms to
+-- 0.01ms.
+--
+-- newestUndoable names this index with INDEXED BY, and has to: left to choose,
+-- sqlite takes actions_gated for the status seek and then reads the rows. See
+-- the query for why that is preferred to running ANALYZE.
+--
+-- Added the same way as the three above and for the same reason: no row
+-- changes, no meaning changes, IF NOT EXISTS makes it idempotent, and an older
+-- build opening the same file afterwards neither notices nor cares.
+CREATE INDEX IF NOT EXISTS actions_undoable ON actions(run_id)
+  WHERE status = 'applied' AND inverse_json IS NOT NULL;
+
+-- Partial for the same reason: findPending runs on the way in to every write,
+-- looking for an earlier attempt at that exact call whose outcome was never
+-- established. Those are rare, so the index holds almost nothing -- while the
+-- rows it saves reading are the ones carrying the snapshots.
+CREATE INDEX IF NOT EXISTS actions_unresolved ON actions(run_id, server, tool)
+  WHERE status = 'pending';
 `;
 
 // src/journal/journal.ts
@@ -681,6 +724,17 @@ var SqliteJournal = class {
       return rows.find((row) => canonical(row.args) === wanted);
     });
   }
+  findPending(query) {
+    return this.#run("findPending", () => {
+      const rows = this.#db.prepare(
+        `SELECT * FROM actions INDEXED BY actions_unresolved
+            WHERE run_id = ? AND server = ? AND tool = ? AND status = 'pending'
+            ORDER BY seq`
+      ).all(query.runId, query.server, query.tool).map(toAction);
+      const wanted = canonical(query.args ?? {});
+      return rows.find((row) => canonical(row.args) === wanted);
+    });
+  }
   getAction(actionId) {
     return this.#run("getAction", () => {
       const raw = this.#db.prepare("SELECT * FROM actions WHERE id = ?").get(actionId);
@@ -743,6 +797,33 @@ var SqliteJournal = class {
       return tally;
     });
   }
+  /**
+   * The newest run that still holds something an undo would put back.
+   *
+   * Not simply the newest run, and not the newest run with an applied action
+   * either. A client that connects and reads opens a session like any other,
+   * and reads are recorded and left `applied` -- rollback steps past them --
+   * so `applied` alone regularly points at a session in which nothing
+   * happened. What makes a run worth offering is an action that is still
+   * applied and carries the inverse that would reverse it, which is the same
+   * test `undo` itself uses when it goes looking for the session somebody
+   * meant. That inverse is also what excludes the reads: the manifest loader
+   * refuses an inverse on a readonly tool, so a read can never carry one, and
+   * a second condition on the class would be a condition that cannot fire.
+   */
+  newestUndoable() {
+    return this.#run("newestUndoable", () => {
+      const raw = this.#db.prepare(
+        `SELECT * FROM runs
+            WHERE id IN (SELECT run_id FROM actions INDEXED BY actions_undoable
+                          WHERE status = 'applied'
+                            AND inverse_json IS NOT NULL)
+            ORDER BY started_at DESC, rowid DESC
+            LIMIT 1`
+      ).get();
+      return raw === void 0 ? void 0 : toRun(raw);
+    });
+  }
   recentActions(limit) {
     return this.#run(
       "recentActions",
@@ -1526,6 +1607,25 @@ function describeError(error) {
   return error instanceof Error ? error.message : String(error);
 }
 var PROXY_CLIENT_INFO = { name: "synartesis-proxy", version: "0.0.0" };
+var STDERR_KEPT = 256 * 1024;
+var STDERR_SETTLE_MS = 200;
+function settled(stream, ms) {
+  if (stream.readableEnded === true) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve2) => {
+    const done = () => {
+      clearTimeout(timer);
+      resolve2();
+    };
+    const timer = setTimeout(done, ms);
+    timer.unref?.();
+    stream.on("end", done);
+  });
+}
+function isReadable(stream) {
+  return typeof stream === "object" && stream !== null && "on" in stream && typeof stream.on === "function";
+}
 function bufferedText(stream) {
   if (typeof stream !== "object" || stream === null || !("read" in stream)) {
     return "";
@@ -1534,14 +1634,26 @@ function bufferedText(stream) {
   if (typeof read2 !== "function") {
     return "";
   }
-  const chunk = read2.call(stream);
-  if (typeof chunk === "string") {
-    return chunk;
+  let text = "";
+  for (; ; ) {
+    const chunk = read2.call(stream);
+    if (typeof chunk === "string") {
+      text += chunk;
+    } else if (Buffer.isBuffer(chunk)) {
+      text += chunk.toString("utf8");
+    } else {
+      break;
+    }
   }
-  return Buffer.isBuffer(chunk) ? chunk.toString("utf8") : "";
+  return text;
 }
+var NAMES_A_FAULT = /^(?:[A-Za-z]*(?:Error|Exception)\b|Cannot find |ENOENT\b|EACCES\b|EADDRINUSE\b|.*: command not found)/;
 function lastWords(text) {
-  const lines = text.split("\n").map((line) => line.trimEnd()).filter((line) => line.trim() !== "");
+  const lines = text.split("\n").map((line) => line.trim()).filter((line) => line !== "" && !/^at\s/.test(line));
+  const named = lines.find((line) => NAMES_A_FAULT.test(line));
+  if (named !== void 0) {
+    return named;
+  }
   const kept = lines.slice(-4).join("; ");
   return kept === "" ? void 0 : kept;
 }
@@ -1573,11 +1685,22 @@ async function start(spec) {
   });
   const client = new Client({ ...PROXY_CLIENT_INFO });
   let said = "";
+  const stderr = transport.stderr;
+  const listening = isReadable(stderr);
+  if (listening) {
+    stderr.on("data", (chunk) => {
+      if (chunk !== void 0 && said.length < STDERR_KEPT) {
+        said += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      }
+    });
+  }
   try {
     await client.connect(transport);
   } catch (error) {
-    said = bufferedText(transport.stderr);
-    const reason = lastWords(said);
+    if (listening) {
+      await settled(stderr, STDERR_SETTLE_MS);
+    }
+    const reason = lastWords(said === "" ? bufferedText(transport.stderr) : said);
     throw new UpstreamError(
       spec.name,
       "connect",
@@ -1741,6 +1864,7 @@ async function observeState(router, read2, signal) {
 }
 
 export {
+  PROXY_FLAGS,
   cliCommand,
   cliCommandFrom,
   proxyCommand,
@@ -1748,6 +1872,7 @@ export {
   findManifest,
   findJournal,
   style,
+  errorStyle,
   WORDMARK,
   rule,
   mark,
@@ -1782,4 +1907,4 @@ export {
   observeState,
   connectStdioUpstream
 };
-//# sourceMappingURL=chunk-6X7GPUGJ.js.map
+//# sourceMappingURL=chunk-OODDXM36.js.map

package/dist/cli.js

@@ -2,6 +2,7 @@
 import {
   IDEMPOTENCY_META_KEY,
   NOTHING_RECORDED_YET,
+  PROXY_FLAGS,
   WORDMARK,
   banner,
   canonical,
@@ -10,6 +11,7 @@ import {
   createPolicyResolver,
   createRouter,
   describeStanding,
+  errorStyle,
   findJournal,
   findManifest,
   labelFor,
@@ -34,7 +36,7 @@ import {
   verifyAgainstServers,
   warnUntested,
   wasRefused
-} from "./chunk-6X7GPUGJ.js";
+} from "./chunk-OODDXM36.js";
 import {
   DriftConflict,
   ManifestError,
@@ -786,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");
@@ -855,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 = [
@@ -1513,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 {
@@ -2668,6 +2815,10 @@ 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 {
@@ -2685,25 +2836,37 @@ var UsageError = class extends Error {
     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;
     }
@@ -2804,6 +2967,16 @@ async function runCheck(argv) {
   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) {
@@ -2997,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();
   }
@@ -3096,6 +3272,13 @@ 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();
@@ -3134,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) {
@@ -3231,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("");
@@ -3320,6 +3517,13 @@ function summarise2(actions) {
   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 {
@@ -3398,6 +3602,10 @@ function runClose(argv, journal) {
     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);
@@ -3419,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("");
@@ -3447,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 ${labelFor(settled)})
+        `synartesis: ${given} is no longer awaiting approval (it is ${labelFor(settled2)})
 `
       );
       return 1;
@@ -3462,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) {
@@ -3473,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)}`);
@@ -3552,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) {
@@ -3612,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;
@@ -3647,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) {
@@ -3695,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
@@ -3743,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}?`
+      );
     }
   }
 }
@@ -3779,6 +4048,13 @@ ${COMMANDS}`);
     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);
@@ -3847,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: [] } : []));
@@ -3885,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();
@@ -3912,8 +4187,7 @@ try {
   if (error instanceof UsageError) {
     process.stderr.write(
       error.listCommands ? `synartesis: ${error.message}
-
-${COMMANDS}` : `synartesis: ${error.message}
+${shortList()}` : `synartesis: ${error.message}
 `
     );
     process.exitCode = 2;

package/dist/proxy.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import {
+  PROXY_FLAGS,
   canonical,
   cliCommandFrom,
   connectStdioUpstream,
@@ -22,7 +23,7 @@ import {
   verifyAgainstServers,
   warnUntested,
   withIdempotencyKey
-} from "./chunk-6X7GPUGJ.js";
+} from "./chunk-OODDXM36.js";
 import {
   SnapshotError,
   UpstreamError,
@@ -585,14 +586,21 @@ function createProxyServer(options) {
       enter();
       try {
         const wantsGate = policy.gate === "always" || policy.gate === "on_write" && shouldGateOnWrite(args);
-        const granted = wantsGate ? journal.findApproval({
+        const unresolved = policy.class === "readonly" ? void 0 : journal.findPending({
+          runId: activeRun,
+          server: route.upstream.name,
+          tool: route.tool,
+          args
+        });
+        const mustAsk = wantsGate || unresolved !== void 0;
+        const granted = mustAsk ? journal.findApproval({
           server: route.upstream.name,
           tool: route.tool,
           args,
           notBefore: new Date(Date.now() - APPROVAL_WINDOW_MS).toISOString()
         }) : void 0;
         const inherited = granted !== void 0 && granted.runId !== activeRun ? granted : void 0;
-        const waiting = granted === void 0 && wantsGate ? journal.findGated({
+        const waiting = granted === void 0 && mustAsk ? journal.findGated({
           runId: activeRun,
           server: route.upstream.name,
           tool: route.tool,
@@ -676,9 +684,13 @@ function createProxyServer(options) {
             );
           }
         };
-        const askedAlready = wantsGate;
-        if (wantsGate && (granted === void 0 || !spent)) {
-          await decide("this action cannot be undone");
+        const askedAlready = mustAsk;
+        if (mustAsk && (granted === void 0 || !spent)) {
+          const because = [
+            unresolved === void 0 ? void 0 : `an earlier attempt at this exact call, action ${String(unresolved.seq)}, went out and its outcome could never be established, so sending it again may apply the change a second time`,
+            wantsGate ? "this action cannot be undone" : void 0
+          ].filter((one) => one !== void 0);
+          await decide(because.join(", and "));
         }
         let snapshot;
         let verify;
@@ -1062,7 +1074,7 @@ function parseArgv(argv) {
     const at = argv.indexOf(flag);
     return at === -1 ? void 0 : argv[at + 1];
   };
-  const known = ["--manifest", "--journal", "--server", "--gate-timeout", "--log-level", "--http", "--http-host", "--http-idle", "--token"];
+  const known = PROXY_FLAGS;
   const unknown = argv.find((token) => token.startsWith("--") && !known.includes(token));
   if (unknown !== void 0) {
     throw new Error(`unknown flag ${unknown}; expected one of ${known.join(", ")}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synartesis",
-  "version": "0.6.13",
+  "version": "0.6.15",
   "description": "An undo layer for AI agents.",
   "type": "module",
   "private": false,