n8n-decanter 0.10.0 → 0.10.1

package/CHANGELOG.md

@@ -7,6 +7,216 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.1] - 2026-08-16
+
+### Added
+
+- **The live mirror now tells the agent when it overwrote your work.** It runs a
+  full `pull` after a structure edit, so it can replace an unpushed local code
+  edit with what is on the instance. It always warned about that — on stderr,
+  which is the one stream an MCP agent structurally cannot read, so the party
+  able to react never heard it. The warning now rides the **result of the
+  agent's next tool call**, naming the files and how to recover them from the
+  safety commit. Delivered once, never repeated.
+
+  Only on `mcp connect` (the transport `init` scaffolds). `mcp serve` pipes
+  upstream responses through untouched — including SSE — and buffering them to
+  inject an advisory line would break streaming for every response to deliver it
+  on some. On that transport the stderr warning stays the only signal.
+
+- **`init` now says that its permission rules only bind the next session.** It
+  writes `.claude/settings.json` with the deny rules that keep an agent off
+  `.decanter.json`, `.env` and `push --force` — but agents read permission config
+  at startup, not on change, and `init` is normally run *from inside* the session
+  those rules are meant to constrain. They were silently inert until a restart,
+  and the docs mentioned a restart only for the skills plugin — so the rules that
+  actually gate the agent went unmentioned. Printed once, when the file is first
+  written; a re-init in a set-up directory stays quiet.
+
+- **`node run` fixtures can pin a node's other outputs, so `$('Node').all(1)`
+  finally answers.** Give a node one items array **per output** and the branch
+  is readable offline:
+
+  ```json
+  "nodes": { "Decide": [[{ "json": { "side": "true" } }], [{ "json": { "side": "false" } }]] }
+  ```
+
+  `all(1)` / `first(1)` / `last(1)` and `$items('Decide', 1)` read output 1, and
+  an **empty** array is a real answer — that branch took no items. `input` takes
+  the same shape, indexed by the node's *input* (a Merge node's second input).
+  A plain items array still means a single output, so existing fixtures are
+  unchanged; asking for an output the fixture doesn't supply still refuses,
+  now saying how many it has. Until now every such call was refused outright,
+  because a fixture could only express one array per node.
+
+- **`preflight --simulate` now replays a pinned node's other outputs too.** The
+  stand-in decanter substitutes for a network node is a Code node, which has one
+  output — so an error output (or any second branch) captured in your execution
+  was replayed nowhere, and everything behind it sat with no input, emitted
+  nothing, and let the run pass. Each populated output now gets **its own
+  stand-in**, wired to the same input as the original and feeding exactly that
+  output's targets, so the branch really runs. Deliberately not wired to the
+  synthetic trigger: a stand-in fires only when the original would, so a replay
+  whose real nodes take a different path can't have the old branch's items
+  injected into it anyway. The `simulate` check names the splits in its details
+  (terminal and `--json`). **`test` still replays `main[0]` only** — n8n's
+  `pinData` is one flat items array per node, with no output dimension — and
+  `scenario check` now spells out which of the two you are looking at.
+
+- **`test` now reports what the run actually moved, not just that it
+  finished** — a coverage line over the nodes that executed (enabled and
+  unpinned; a pinned node's items are the input you supplied):
+  `coverage: 7/9 unpinned node(s) emitted items — 2 emitted none: Group
+  products, Write rows`. A node counts as emitting if it put an item on **any**
+  output. Some empty nodes are normal — a filter that dropped everything — so
+  the line warns and nothing more.
+
+  **But a run in which not one unpinned node emitted an item now fails
+  (exit 1), even with synthetic pins.** n8n calls such a run `success` and
+  it is: nothing errored. No data moved either, so nothing was demonstrated,
+  and reporting it as a pass was the check lying. The message names the usual
+  cause — a pin replays a node's first output only.
+
+- **`scenario check` warns about what the replay will throw away.** Both replay
+  paths (`test`'s `pinData`, `preflight --simulate`'s stand-in node) read
+  `main[0]` only, while the validator happily accepts — and `✓ valid`s — a
+  scenario carrying items on several outputs. The check now says so offline:
+  once for a node whose data populates more than one output, naming the indices
+  that get dropped, and once for a node source that reads a pinned node's
+  non-first output (`$('Enrich').all(1)`, `$items('Enrich', 1)`) — the call that
+  returns nothing and leaves the node emitting nothing. Warnings only; the
+  scenario stays valid for the outputs that do replay.
+
+### Changed
+
+- **An explicit `.ts` extension in a node file's import no longer fails the
+  typecheck.** The scaffolded `tsconfig.json` now sets
+  `allowImportingTsExtensions`, so `import { total } from
+  "../../../shared/money.ts"` type-checks — until now it was rejected
+  (TS5097) even though `push` bundles it without complaint, which made the
+  gate and the bundler disagree over a pure spelling choice. Extensionless
+  stays the recommended form (it survives a helper later becoming `.js`);
+  both spellings resolve everywhere. Existing sync dirs are offered the
+  updated `tsconfig.json` on the next `init` — a `tsconfig.json` you edited
+  yourself is reported as drift and left alone, so add the option by hand
+  there.
+- **Two of the four import rules for `.ts` nodes now warn instead of
+  blocking a push**: a relative import resolving outside the sync dir, and an
+  absolute-path import. Both only endanger the author's own portability — the
+  bundle still builds locally and fails loudly (`Could not resolve`) wherever
+  the target is genuinely absent — so blocking them was decanter making the
+  user's call. The advisory prints on every surface (`preflight`'s `layout`
+  details, `push`, `node run`) and exactly once per push;
+  `preflight --fail-on=warn` is the strict variant for CI. **Node builtins
+  and npm packages not opted into `bundleDependencies` still block** —
+  esbuild is silent about both, so without the block the failure would
+  surface at runtime on the n8n instance.
+- **The scaffolded `mcp-route-check.mjs` session hook now also inspects
+  user-level agent config for direct n8n MCP routes** — Claude Code's
+  `~/.claude.json` (including its entry for the current project), Cursor's
+  `~/.cursor/mcp.json`, the VS Code user profile, and opencode's global
+  config. Previously it read only project files, so an `n8n` server added
+  with `claude mcp add -s user` (or any other user-scoped config) bypassed
+  the decanter guard without a word — exactly the "second door" the hook
+  exists to catch. Still a warning, never a gate. Re-run `init` in an
+  existing sync dir (or re-copy the hook from the template) to pick it up.
+- **The scaffolded `tsconfig.json` now covers the whole sync dir**, not just
+  `shared/` and `workflows/` — helper code may live in any folder inside the
+  sync dir (`shared/` is only the scaffolded default), so the typecheck and
+  the editor's tsserver now own every root without a config edit. Existing
+  sync dirs keep their scaffolded file; to match, widen `include` to
+  `["n8n-globals.d.ts", "**/*.ts", "**/*.js"]` and add
+  `"**/backups/**", "**/executions/**", "decanter-ts-plugin", "dist"` to
+  `exclude`. Two consequences worth knowing: a loose node-shaped scratch file
+  (top-level `return` outside any workflow's `code/`) is now part of the
+  program and reports TS1108 — move it into a workflow or add its folder to
+  `exclude`; and when `init` scaffolds into an **existing project** that had
+  no `tsconfig.json`, the new config sweeps that project's own `.ts`/`.js`
+  into the node-file typecheck — add your app dirs to `exclude` if they
+  shouldn't gate pushes.
+
+### Fixed
+
+- **`diff` and `preflight` no longer report a `CONFLICT` for a node with no
+  recorded sync hash.** "Changed both locally and remotely" is measured against
+  the last-sync baseline in `.decanter.json`; with no baseline nothing is
+  *known* to have moved on the instance, and `push` has always treated that as
+  pushable. The two disagreed, so the report described a dead end the CLI did
+  not have — worse, its documented exit (`push --force`) is denied to agents by
+  the permission rules `init` scaffolds. Such a node now reads as
+  `push pending`, which is what `push` does with it. `pull` no longer warns
+  `CONFLICT` for the same case on `.ts` nodes.
+- **A `.js` → `.ts` conversion no longer reads as data loss.** Re-pointing a
+  node's `//@file:` placeholder is the sanctioned way to convert, and `push`
+  and `pull` both adopt it before doing anything — but `diff` and `preflight`
+  looked the file up in `.decanter.json` alone and announced `local file
+  code/<node>.js missing` for the file you had just replaced. They now read the
+  placeholder too, so a converted node reports `local changes in
+  code/<node>.ts — push pending`, identically for every converted node.
+- **`preflight` no longer prints `✓ parity local code matches the draft`
+  directly above `✗ drift CONFLICT`.** Both checks read the same facts, so
+  `parity` may claim a match only when every node is in sync; divergence that
+  `drift` owns is reported as an `info` line pointing at it.
+- **`mcp connect` survives an unreachable n8n instead of dying at the
+  handshake.** `initialize` was forwarded like any other message, so a
+  connection failure answered the *handshake* with an error: the agent's MCP
+  client got no `serverInfo` and tore the session down before a single tool
+  call could report what was wrong. The guard now completes the handshake
+  itself when n8n does not answer, and the failure surfaces on the tool call
+  that needed the instance. Once n8n is reachable, the handshake is replayed
+  upstream so the session it uses is a real one. The startup line now reads
+  `guard: ready — forwarding all n8n MCP tools to <host>` instead of
+  `connected to <host>`, which claimed a connection nothing had made yet.
+- **The scaffolded `AGENTS.md` now names the n8n-side prerequisites.** MCP
+  access is a switch per *instance* **and** one per *workflow* ("Available in
+  MCP"), and until a workflow's is on, `pull`/`push`/`diff`/`preflight`/`watch`
+  all fail for it. The CLI's error says so; the file an agent reads *before*
+  running anything did not.
+- **`preflight`'s `types` check now reports type errors in shared helper
+  files** instead of passing green while `push` fails on them. The scoped
+  typecheck dropped every diagnostic outside the graded workflow's own dir —
+  and helper code lives outside every workflow dir by definition — so a
+  workflow could grade `ready` on code `push` then rejected. Helper
+  diagnostics (under `shared/` or any other folder) now surface in every
+  workflow's `types` line, while another workflow's *node* errors stay out of
+  scope as before.
+- **The documented shared-import path was one level short** for the `code/`
+  layout: `../../shared/money` in the TypeScript-nodes docs and the scaffolded
+  `AGENTS.md` resolved to `workflows/shared/money` and failed on copy-paste.
+  The correct depth from `workflows/<folder>/code/` is `../../../shared/money`.
+- **Compiled module labels — and therefore sync hashes — are now stable when
+  the sync dir is reached through a symlinked path** (macOS `/tmp`, a
+  symlinked checkout). esbuild resolves bundled files to their realpaths, so
+  an un-realpathed label base produced machine-specific `../…`-climbing
+  labels inside the hashed bytes — nodes reading "push pending" across
+  machines with nobody touching code. The same spelling mismatch made a
+  *scoped* typecheck silently drop every node diagnostic under a symlinked
+  path; both now realpath. If a sync dir lives behind a symlink, the first
+  push after this release re-baselines the affected nodes' hashes once.
+- **The route-check hook now reads opencode's real config shape**
+  (`mcp.<name>`). It previously looked only for `mcpServers` / `mcp.servers` /
+  `servers` bags, so an `opencode.json` routing straight at the instance was
+  listed as checked but never actually flagged.
+- **A `watch` save now runs the same folder-wide compliance guard as `push`.** It
+  used to check only the saved file, which cannot see the workflow's node names —
+  so it could not catch a dangling `$('Renamed Node')` and pushed straight to the
+  draft what a manual `push` refuses outright. The break then surfaced at run time
+  in n8n instead of at save time. Four surfaces already claimed the guards were
+  the same; now they are.
+
+  **The abort is scoped, deliberately:** a save is refused when the violation is
+  in the file you just saved, and violations elsewhere in the folder are printed
+  on every save without blocking it. Repairing a rename means fixing several
+  files, and a folder-wide abort would stop every save until the last fix — which
+  would disable `watch` during exactly the job it is for.
+
+- **`liveMirror` is documented as what it is: a full `pull`.** The shipped agent
+  contract and the config reference both described it as refreshing the
+  `workflow.json` snapshot. It also rewrites the `code/` files and
+  `.decanter.json` and moves files on a rename, so it can overwrite an unpushed
+  local edit — which is worth knowing before you restructure. No behaviour change;
+  the docs now say what the code has always done.
+
 ## [0.10.0] - 2026-08-07
 
 ### Added

package/README.md

@@ -34,8 +34,9 @@ clean git diffs.
   every push and pull is auto-committed.
 - **TypeScript or typed JS** — write nodes in TS (compiled on push) or plain
   JS; n8n globals (`$input`, `$('…')`, …) are typed in both.
-- **Shared code and small libraries** — `.ts` nodes import from `shared/` and
-  opted-in npm packages, bundled on push to run anywhere, n8n Cloud included.
+- **Shared code and small libraries** — `.ts` nodes import helper files from
+  anywhere in the sync dir (`shared/` by default) and opted-in npm packages,
+  bundled on push to run anywhere, n8n Cloud included.
 - **Agent-native** — `init` scaffolds Claude Code / Cursor / Codex configs;
   `preflight --offline` and `node run` give agents a credential-free loop.
 - **Guarded agent access to n8n's MCP, wired by default** — the scaffolded
@@ -142,7 +143,7 @@ a broader whole-workflow authoring toolkit:
 | Capability | Native n8n (browser) | n8n-as-code | n8n-decanter |
 |---|---|---|---|
 | **TypeScript for Code nodes** | ❌ JavaScript or Python only | ❌ TS at workflow level, not node logic | ✅ `.ts` nodes, compiled on push, typed n8n globals |
-| **Shared types & helpers in Code nodes** | ❌ self-host `NODE_FUNCTION_ALLOW_*` only | ❌ not part of its model | ✅ `shared/*.ts` + npm bundled into self-contained nodes (Cloud-safe) |
+| **Shared types & helpers in Code nodes** | ❌ self-host `NODE_FUNCTION_ALLOW_*` only | ❌ not part of its model | ✅ helper `.ts` anywhere in the sync dir + npm, bundled into self-contained nodes (Cloud-safe) |
 | **Code as individual files** | ❌ no source files (JSON blob) | 🟡 one `.workflow.ts` per workflow | ✅ folder per workflow; each Code node its own file |
 | **Code-level git versioning** | 🟡 in-app history; Git source control is Enterprise-only | ✅ GitOps sync of workflow source | ✅ real git — diffs, PRs, blame per Code node; auto-commit each sync |
 | **Preflights** (`preflight`, then `test`) | 🟡 re-run past executions, but online in-editor | 🟡 inspect executions against a live env | ✅ one read-only, CI-gateable verdict *before* the push; then `test` runs the pushed draft — each diffs every node vs a real capture |

package/dist/lib/backup.mjs

@@ -135,7 +135,7 @@ async function assembleForRestore(dir, backup, log) {
         if (file === null)
             continue; // inline code (untracked node) — leave as-is
         try {
-            const { jsCode } = await buildNodeCode(dir, file, log);
+            const { jsCode } = await buildNodeCode(dir, file, log, { quietImportWarnings: true });
             node.parameters.jsCode = jsCode;
         }
         catch {

package/dist/lib/compile.mjs

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { builtinModules } from "node:module";
 import path from "node:path";
 import { build, transform } from "esbuild";
@@ -119,38 +119,53 @@ export function findBundleContext(fromDir) {
         dir = parent;
     }
 }
+/** realpath when resolvable, the input untouched otherwise (missing dirs). */
+function realDir(dir) {
+    try {
+        return realpathSync(dir);
+    }
+    catch {
+        return dir;
+    }
+}
 /** Package name of a bare specifier (`@scope/pkg/sub` → `@scope/pkg`). */
 function packageName(spec) {
     return spec.startsWith("@") ? spec.split("/").slice(0, 2).join("/") : spec.split("/")[0];
 }
 /**
- * Offline import rules for a node file (plans/14): relative imports stay
- * inside the sync dir, bare specifiers need a `bundleDependencies` opt-in,
- * builtins can never be bundled. Shared by the compliance guard and the
- * compiler, so preflight's `layout` check and `push` disagree on nothing.
+ * Offline import rules for a node file (plans/14), split by who the rule
+ * protects (Plan 79 task 7): a Node builtin or an un-opted-in npm package is
+ * **blocking** — esbuild is silent about both, so without the block the
+ * failure (a `__require` shim, a silently inlined package) surfaces at
+ * runtime on the instance. A relative import leaving the sync dir, or an
+ * absolute path, is **advisory** — it only endangers the author's own
+ * portability, and esbuild fails loudly wherever the target is genuinely
+ * absent. Shared by the compliance guard and the compiler, so preflight's
+ * `layout` check and `push` disagree on nothing.
  */
 export function checkNodeImports(file, specifiers, ctx) {
-    const problems = [];
+    const blocking = [];
+    const advisory = [];
     for (const spec of specifiers) {
         if (spec.startsWith("node:") || BUILTINS.has(packageName(spec))) {
-            problems.push(`imports the Node builtin "${spec}" — builtins cannot be bundled into a Code node (whether n8n allows them at runtime is the instance's NODE_FUNCTION_ALLOW_BUILTIN policy); inline the logic instead`);
+            blocking.push(`imports the Node builtin "${spec}" — builtins cannot be bundled into a Code node (whether n8n allows them at runtime is the instance's NODE_FUNCTION_ALLOW_BUILTIN policy); inline the logic instead`);
         }
         else if (spec.startsWith("./") || spec.startsWith("../")) {
             if (ctx.syncRoot !== null) {
                 const resolved = path.resolve(path.dirname(file), spec);
                 if (resolved !== ctx.syncRoot && !resolved.startsWith(ctx.syncRoot + path.sep)) {
-                    problems.push(`imports "${spec}", which resolves outside the sync dir (${ctx.syncRoot}) — shared code must live inside it`);
+                    advisory.push(`imports "${spec}", which resolves outside the sync dir (${ctx.syncRoot}) — it bundles, but anyone whose checkout lacks the target can't build this node`);
                 }
             }
         }
         else if (path.isAbsolute(spec)) {
-            problems.push(`imports the absolute path "${spec}" — use a relative import inside the sync dir`);
+            advisory.push(`imports the absolute path "${spec}" — it bundles on this machine only; prefer a relative import inside the sync dir`);
         }
         else if (!ctx.bundleDependencies.includes(packageName(spec))) {
-            problems.push(`imports the npm package "${packageName(spec)}" without opting it in — add it to "bundleDependencies" in decanter.config.json to bundle it into the pushed node`);
+            blocking.push(`imports the npm package "${packageName(spec)}" without opting it in — add it to "bundleDependencies" in decanter.config.json to bundle it into the pushed node`);
         }
     }
-    return problems;
+    return { blocking, advisory };
 }
 /**
  * One-way compile of a .ts node file to the JS that runs inside n8n.
@@ -159,7 +174,7 @@ export function checkNodeImports(file, specifiers, ctx) {
  * imports, the file is bundled self-contained (see the header comment); the
  * output is still a function body ending in a top-level `return`.
  */
-export async function compileTs(file, log) {
+export async function compileTs(file, log, opts) {
     const source = readFileSync(file, "utf8");
     const { importBlock, specifiers, body } = scanNodeImports(source);
     if (specifiers.length === 0) {
@@ -172,11 +187,35 @@ export async function compileTs(file, log) {
         return result.code.endsWith("\n") ? result.code : result.code + "\n";
     }
     const ctx = findBundleContext(path.dirname(file));
-    const problems = checkNodeImports(file, specifiers, ctx);
-    if (problems.length > 0) {
-        throw new Error(`${file}:\n${problems.map((p) => `  ${p}`).join("\n")}`);
+    const { blocking, advisory } = checkNodeImports(file, specifiers, ctx);
+    if (blocking.length > 0) {
+        throw new Error(`${file}:\n${blocking.map((p) => `  ${p}`).join("\n")}`);
+    }
+    // Advisory findings warn and let the compile proceed (Plan 79 task 7). The
+    // push paths pass quietImportWarnings because their guard tier already
+    // printed the same findings — without it every violation would print twice
+    // per push, once per channel.
+    if (!opts?.quietImportWarnings) {
+        for (const p of advisory)
+            log?.warn(`${file}: ${p}`);
     }
-    const workingDir = ctx.syncRoot ?? path.dirname(file);
+    // Realpath the label base: esbuild resolves every bundled module to its
+    // realpath, so a symlink anywhere in the sync dir's own path (macOS /tmp,
+    // a symlinked checkout) would otherwise make `path.relative` climb across
+    // the symlink — machine-specific `../…` module labels inside the hashed
+    // bytes, i.e. the exact cross-machine drift the sync-root-relative labels
+    // exist to prevent (Plan 79 task 4).
+    const workingDir = realDir(ctx.syncRoot ?? path.dirname(file));
+    // resolveDir follows, but ONLY when its realpath stays inside the real sync
+    // root (the whole-tree-behind-a-symlink shape, where realpathing keeps the
+    // entry label clean). When a symlink BETWEEN the root and the node file
+    // realpaths out of the tree, keep the caller's spelling: imports must
+    // resolve exactly where checkNodeImports approved them, or the guard and
+    // the bundler disagree — approving X/shared and then bundling (or failing
+    // on) something else entirely.
+    const spelledDir = path.dirname(file);
+    const realNodeDir = realDir(spelledDir);
+    const resolveDir = realNodeDir === workingDir || realNodeDir.startsWith(workingDir + path.sep) ? realNodeDir : spelledDir;
     // The entry must contain NO `export` syntax: n8n's task-runner sandbox
     // neuters getter property descriptors (Object.defineProperty with `get`
     // reads back undefined), and esbuild lowers module exports to exactly such
@@ -194,7 +233,7 @@ export async function compileTs(file, log) {
             stdin: {
                 contents: entry,
                 loader: "ts",
-                resolveDir: path.dirname(file),
+                resolveDir,
                 sourcefile: ENTRY_SOURCEFILE,
             },
             bundle: true,

package/dist/lib/init.mjs

@@ -321,6 +321,17 @@ async function refreshTemplate(srcDir, destDir, { force, protect, version, extra
         log.info(`copied template -> ${destDir}`);
     else
         log.info(`template up to date (${uptodate} unchanged${added.length ? `, ${added.length} added` : ""})`);
+    // Permission rules do not hot-load, and `init` is normally run from INSIDE the
+    // session they are meant to constrain — so the deny rules it just wrote (no
+    // edits to `.decanter.json`, no reads of `.env`, no `push --force`) are inert
+    // until that session restarts. The docs said "restart" only for the skills
+    // plugin, so the rules that actually gate the agent went unmentioned: the tool
+    // knew something the user needed and never said it. Only when the file is new
+    // — re-running init in a set-up dir must not nag.
+    const settingsFile = path.join(".claude", "settings.json");
+    if (added.includes(settingsFile)) {
+        log.info(style.dim("  agent permission rules take effect on the NEXT session — restart your agent (or /reload) so they apply"));
+    }
 }
 /**
  * Bootstrap a sync dir (Plan 32: OAuth-first). Interactive by default: prompt

package/dist/lib/mcp.mjs

@@ -10,7 +10,7 @@ import { HOST_UNSET } from "./config.mjs";
 import { CODE_NODE_TYPE } from "./util.mjs";
 export const MCP_PATH = "/mcp-server/http";
 export const AUTH_FILE = ".decanter-auth.json";
-const PROTOCOL_VERSION = "2025-03-26";
+export const PROTOCOL_VERSION = "2025-03-26";
 /**
  * n8n's own guidance for a workflow that hasn't been opted into MCP —
  * mirrored (not invented) so CLI hints match what the server says.

package/dist/lib/mcpconnect.mjs

@@ -17,8 +17,8 @@
 // SSE) are decoded back into per-line JSON-RPC messages. Parse failures fail
 // CLOSED, mirroring the HTTP guard.
 import { createInterface } from "node:readline";
-import { MCP_PATH } from "./mcp.mjs";
-import { guardMessage, guardPublish, logToolCall, mirrorTargetId } from "./mcpserve.mjs";
+import { MCP_PATH, PROTOCOL_VERSION } from "./mcp.mjs";
+import { attachMirrorNotices, guardMessage, guardPublish, logToolCall, mirrorTargetId } from "./mcpserve.mjs";
 /** JSON-RPC error codes used by the bridge (server-defined range). */
 const PARSE_ERROR = -32700;
 const UPSTREAM_ERROR = -32001;
@@ -26,6 +26,35 @@ const UPSTREAM_ERROR = -32001;
 function rpcError(id, code, text) {
     return { jsonrpc: "2.0", id: id ?? null, error: { code, message: text } };
 }
+/** The single `initialize` request in a unit, or null (batches are not one). */
+function initializeRequest(unit) {
+    if (unit === null || typeof unit !== "object" || Array.isArray(unit))
+        return null;
+    const msg = unit;
+    return msg.method === "initialize" && msg.id !== undefined ? msg : null;
+}
+/**
+ * The handshake the guard answers with when n8n cannot be reached.
+ *
+ * An error here is fatal to the whole session: an MCP client that gets no
+ * `serverInfo` tears the connection down and never makes the tool call whose
+ * failure it could have reported. So the guard — which is itself the server the
+ * agent spawned, and is running fine — completes the handshake with its own
+ * identity, and the unreachable instance surfaces on the first forwarded call.
+ * No capability beyond `tools` is claimed: everything else is n8n's to answer.
+ */
+function localInitializeResult(request) {
+    const params = (request.params ?? {});
+    return {
+        jsonrpc: "2.0",
+        id: request.id ?? null,
+        result: {
+            protocolVersion: typeof params.protocolVersion === "string" ? params.protocolVersion : PROTOCOL_VERSION,
+            capabilities: { tools: {} },
+            serverInfo: { name: "n8n-decanter guard", version: "0" },
+        },
+    };
+}
 /**
  * Run the stdio guard until stdin closes (the agent ending the session).
  * Messages are processed strictly in order — an MCP client awaits its
@@ -40,13 +69,23 @@ export async function runStdioGuard({ mcp, host, timeoutMs, mirror, log, input =
     // blocked nothing" and "never started" — and they are indistinguishable
     // exactly when it matters. (A Plan 35 harness bug left the guard dead for
     // three committed field-test rounds; the silence read as innocence.)
-    log.info(`guard: connected to ${host} — forwarding all n8n MCP tools, blocking jsCode writes in update_workflow`);
+    // "ready", not "connected": nothing has been contacted yet, and the line
+    // claiming a live instance while the first handshake was still failing is
+    // exactly what made an unreachable host read as a decanter bug.
+    log.info(`guard: ready — forwarding all n8n MCP tools to ${host}, blocking jsCode writes in update_workflow`);
     /** One protocol message (or batch) out — a single output line. */
     const emit = (message) => {
-        output.write(`${JSON.stringify(message)}\n`);
+        // Every outgoing message passes here, which makes this the one place a
+        // background live-mirror notice can reach the agent (Plan 68).
+        output.write(`${JSON.stringify(attachMirrorNotices(message, () => mirror?.takeNotices() ?? []))}\n`);
     };
-    /** Forward one already-guarded JSON-RPC unit (message or batch) upstream. */
-    const forward = async (unit, ids) => {
+    /**
+     * A handshake this guard answered itself because n8n was down. n8n never saw
+     * it, so the HTTP session is uninitialized — it has to be replayed before the
+     * next forward, or every later call rides a session n8n never opened.
+     */
+    let deferredHandshake = null;
+    const attempt = async (unit) => {
         let res;
         let refreshed = false;
         let rateRetries = 0;
@@ -88,9 +127,7 @@ export async function runStdioGuard({ mcp, host, timeoutMs, mirror, log, input =
             const name = err.name;
             const reason = name === "TimeoutError" || name === "AbortError" ? `no response within ${timeoutMs / 1000}s` : err.message;
             log.warn(`upstream request failed: ${reason}`);
-            for (const id of ids)
-                emit(rpcError(id, UPSTREAM_ERROR, `n8n unreachable through the decanter guard (${reason}) — is ${host} up?`));
-            return;
+            return { ok: false, detail: `n8n unreachable through the decanter guard (${reason}) — is ${host} up?` };
         }
         const sid = res.headers.get("mcp-session-id");
         if (sid !== null)
@@ -109,16 +146,43 @@ export async function runStdioGuard({ mcp, host, timeoutMs, mirror, log, input =
                     ? `n8n refused the request (403)${text !== "" ? `: ${text.slice(0, 200)}` : ""} — MCP access is switched off for this instance (n8n → Settings → MCP), or this token's user lacks access`
                     : `n8n answered ${res.status} ${res.statusText}${text !== "" ? `: ${text.slice(0, 300)}` : ""}`;
             log.warn(detail);
+            return { ok: false, detail };
+        }
+        return { ok: true, text, sse: (res.headers.get("content-type") ?? "").includes("text/event-stream") };
+    };
+    /** Forward one already-guarded JSON-RPC unit (message or batch) upstream. */
+    const forward = async (unit, ids) => {
+        // Replay a handshake n8n never saw, so a recovered instance does not answer
+        // every later call with "session not initialized". Failure is not reported
+        // here — the real message follows and carries the error to the caller.
+        if (deferredHandshake !== null && sessionId === undefined) {
+            if ((await attempt(deferredHandshake)).ok) {
+                deferredHandshake = null;
+                await attempt({ jsonrpc: "2.0", method: "notifications/initialized" });
+                log.info(`guard: reached ${host} — the handshake answered locally is now live upstream`);
+            }
+        }
+        const result = await attempt(unit);
+        if (!result.ok) {
+            // A failed HANDSHAKE is answered by the guard itself: an error there ends
+            // the session before a single tool call is made, and the agent is left
+            // with a dead server instead of a working one pointed at a down instance.
+            const handshake = initializeRequest(unit);
+            if (handshake !== null) {
+                deferredHandshake = unit;
+                log.warn(`guard: n8n did not answer the handshake — completing it locally so the session survives; tool calls will report: ${result.detail}`);
+                return emit(localInitializeResult(handshake));
+            }
             for (const id of ids)
-                emit(rpcError(id, UPSTREAM_ERROR, detail));
+                emit(rpcError(id, UPSTREAM_ERROR, result.detail));
             return;
         }
-        if (text === "")
+        if (result.text === "")
             return; // 202 for notifications — nothing to relay
-        if ((res.headers.get("content-type") ?? "").includes("text/event-stream")) {
+        if (result.sse) {
             // SSE: each data: line is one JSON-RPC message (response and/or
             // server notifications) — relay every one, a line each.
-            for (const line of text.split("\n")) {
+            for (const line of result.text.split("\n")) {
                 if (!line.startsWith("data:"))
                     continue;
                 try {
@@ -131,7 +195,7 @@ export async function runStdioGuard({ mcp, host, timeoutMs, mirror, log, input =
             return;
         }
         try {
-            emit(JSON.parse(text)); // plain JSON body (message or batch) — one line
+            emit(JSON.parse(result.text)); // plain JSON body (message or batch) — one line
         }
         catch {
             const detail = `n8n answered 200 with non-JSON content — is ${host} really your n8n instance (captive portal, proxy)?`;

package/dist/lib/mcpserve.mjs

@@ -175,6 +175,37 @@ export function mirrorTargetId(msg) {
     const id = params.arguments?.workflowId;
     return typeof id === "string" && id !== "" ? id : null;
 }
+/**
+ * Attach the live mirror's pending notices to an outgoing tool result (Plan 68).
+ *
+ * Shared by both transports for the same reason the two refusals are: a message
+ * the agent gets from `mcp connect` and not from `mcp serve` is a drift bug
+ * waiting to happen.
+ *
+ * Only a **successful tool result** carries them — an error result already has
+ * the agent's attention and its own instruction, and appending to it would
+ * compete with that. Anything else (handshakes, notifications, `tools/list`)
+ * passes through untouched, and if this message is not a shape we recognise the
+ * notices are handed back so the next one can take them: dropping the warning
+ * silently is the bug this whole plan is about.
+ */
+export function attachMirrorNotices(msg, take) {
+    const record = msg;
+    const content = record?.result?.content;
+    if (!Array.isArray(content) || record.result?.isError === true)
+        return msg;
+    const first = content.find((c) => c?.type === "text");
+    if (first === undefined || typeof first.text !== "string")
+        return msg;
+    // Only NOW take them: `take` empties the queue, so asking before we know the
+    // message can carry them would drop the warning on every handshake that
+    // happens to precede a tool call.
+    const notices = take();
+    if (notices.length === 0)
+        return msg;
+    first.text = `${first.text}\n\n${notices.join("\n\n")}`;
+    return msg;
+}
 /**
  * Start the guard proxy on 127.0.0.1. Auth is a per-session random secret
  * (the agent's MCP config carries it; the n8n credential never leaves this
@@ -302,7 +333,14 @@ export async function startGuardProxy({ mcp, host, configDir, port = DEFAULT_GUA
                 mirror?.schedule(id);
             if (upstreamRes.body === null)
                 return void res.end();
-            // responses (incl. SSE) pipe through untouched
+            // Responses (incl. SSE) pipe through untouched — and that is why the live
+            // mirror's clobber notice (Plan 68) reaches agents on `mcp connect` but
+            // NOT here. `attachMirrorNotices` needs a parsed message; this path never
+            // parses one, and buffering to inject an advisory line would break SSE
+            // streaming for every response to deliver it on some. A deliberate,
+            // named asymmetry rather than a silent one: on the HTTP transport the
+            // stderr warning stays the only signal, so `liveMirror: false` (or
+            // pushing before restructuring) is the safer posture there.
             Readable.fromWeb(upstreamRes.body).pipe(res);
         })().catch((err) => {
             log.warn(`guard-proxy request failed: ${err.message}`);
@@ -320,7 +358,7 @@ export async function startGuardProxy({ mcp, host, configDir, port = DEFAULT_GUA
     const url = `http://127.0.0.1:${actualPort}${MCP_PATH}`;
     // Same "I am alive" line as the stdio guard — an empty log must never be
     // ambiguous between "ran, blocked nothing" and "never started".
-    log.info(`guard: connected to ${host} — forwarding all n8n MCP tools, blocking jsCode writes in update_workflow`);
+    log.info(`guard: ready — forwarding all n8n MCP tools to ${host}, blocking jsCode writes in update_workflow`);
     const stateFile = path.join(configDir, PROXY_STATE_FILE);
     try {
         // discovery for tooling (the config-drift hook); gitignored, 0600