n8n-decanter 0.10.2 → 0.11.2

package/CHANGELOG.md

@@ -7,6 +7,158 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.2] - 2026-10-21
+
+### Fixed
+
+- **`test --scenario` and `test --execution` work again on n8n 2.34 and
+  newer** ([#327](https://github.com/buttjer/n8n-decanter/issues/327)). The run
+  succeeded on the instance, but decanter then stopped with `Tool get_execution
+  not found` and compared nothing. n8n 2.34 renamed that MCP tool to
+  `get_workflow_execution`, and renamed two more that decanter uses:
+  `search_executions` (behind `preflight`'s `history` check, which quietly
+  fell back to the REST API or skipped) and `prepare_test_pin_data` (behind
+  `scenario create --scaffold`, which quietly produced fills without schemas).
+  decanter now asks for the new name and falls back to the old one, so older n8n
+  keeps working too.
+
+## [0.11.1] - 2026-09-10
+
+### Added
+
+- **`N8N_DECANTER_AUTH=upstream` — an auth mode for instances behind a proxy
+  that attaches the n8n credentials itself.** In this mode decanter sends *no*
+  credential header at all: no `Authorization` on MCP, no `X-N8N-API-KEY` on
+  REST. That is the only thing that works — a proxy which adds its own key
+  **appends** it to whatever the client sent, and n8n answers `401` to the pair,
+  so the previous workaround (a placeholder value in `N8N_API_KEY`, to satisfy
+  the REST-verb guard) fails just like an empty one. `N8N_API_KEY` stops being
+  required, so `executions`, `data-tables` and `backup` work with no key of your
+  own. `mcp serve` drops the agent's session secret instead of swapping it for a
+  credential, so that local secret is never forwarded upstream. Set it in `.env`
+  or with the new **`init --auth upstream`**, which needs no token, no browser
+  and no TTY, and verifies both backends through the proxy. Existing credentials
+  are kept, ignored, and reported as unused. Any other value of the variable is
+  an error on every verb — a typo must not silently restore the header.
+
+### Fixed
+
+- **A REST 401 now says what is wrong.** It used to fall through to a bare
+  `401 Unauthorized` status line; it now names `N8N_API_KEY` as invalid for the
+  host (or, in upstream mode, points at the proxy).
+
+## [0.11.0] - 2026-09-03
+
+### Changed
+
+- **Breaking: a compiled `.ts` node now identifies itself on line 1, not on
+  its last line.** Open a bundled node in n8n and you used to see
+  `var __n8n_node = {}` followed by a few hundred lines of inlined helpers,
+  with the only trace of where it came from — `// @ts-n8n sha256:…` — at the
+  bottom, where nobody looks, naming *n8n* rather than the tool that put it
+  there. Push now writes one self-describing line where the editor opens:
+
+  ```js
+  // n8n-decanter · workflows/orders/code/normalize-lines.ts · do not edit here · @ts-n8n sha256:39af5ea6… · v0.10.1 ca3c201 2026-08-20T09:14Z
+  ```
+
+  **Nothing you already pushed has to change.** The old trailing form is read
+  forever and counts as fully in sync — `push`, `diff` and `preflight` say
+  nothing about it, and no write is queued just to relocate a marker. Nodes
+  adopt line 1 on their next real code push; there is no migration and no mass
+  re-push. The break runs the other way: **an older n8n-decanter will not
+  recognise a node pushed by this version** (its reader only looks at the last
+  line) and would pull such a node down as a plain `.js` file. Pre-1.0, that is
+  accepted rather than shimmed — upgrade the CLI everywhere that pulls the same
+  instance. The `@ts-n8n` token itself is unchanged, so one `grep -r @ts-n8n`
+  still finds both forms.
+
+- **The layout guard now rejects a marker line in a node source file in either
+  position, and in `.ts` files too** (it was trailing-only and `.js`-only).
+  That line is written by `push`; it is never source. Surfaces as before via
+  `preflight`'s `layout` check.
+
+### Fixed
+
+- **An auth failure no longer sends you in a circle, and throttling is no
+  longer called an expiry.** Every failed OAuth token refresh used to print
+  the same sentence — `MCP session expired … re-run: n8n-decanter init` — and
+  both halves of it could be wrong. `init` reuses `.decanter-auth.json`
+  whenever the host matches and never re-mints, so following the advice
+  re-probed with the same dead credentials and finished with "credentials
+  written anyway"; the only apparent way out was deleting a credential file
+  that was often perfectly fine. The three cases are now told apart:
+  - **the refresh token really is spent** (`invalid_grant`) — named as such,
+    and pointed at `init --reauth`, a command that actually re-mints;
+  - **n8n is rate-limiting** (429) — now **retried** with the same backoff the
+    MCP endpoint has always had (honouring `Retry-After`, five attempts), and
+    if it still fails it says the credentials are fine and never mentions
+    `init`. OAuth discovery got the same retry; both sat on bare `fetch` calls;
+  - **anything else** — the reason is named without a diagnosis, and nothing
+    is suggested for discarding.
+
+- **`init`'s closing connection check acts on a spent token instead of
+  shrugging.** It had the failure in hand and printed "credentials written
+  anyway". On a terminal it now offers to re-authorize on the spot; off one it
+  names `init --reauth`. Deliberately narrow — a network error, a 401, or a
+  403 "MCP access is disabled" still report as before, because none of them
+  says anything about your credentials.
+
+- **A successful first OAuth consent no longer warns "no MCP credentials
+  yet".** The check looked for a *pre-existing* auth file, so a browser
+  authorization that had just succeeded still ended with advice to re-run
+  `init` with a token.
+
+- **`<verb> --help` prints help instead of running the verb.** `--help` was
+  only recognised in argument slot 0, and every `--flag` is stripped before
+  dispatch, so `n8n-decanter init --help` was indistinguishable from a bare
+  `init` — a request for help **scaffolded a sync dir** into whatever directory
+  it was asked from. `--help` (and `-h`) now wins from any position, before any
+  verb, any namespace and the picker. It prints **that verb's own block** rather
+  than the whole listing, with only the notes that apply to it; `help <verb>` is
+  the same question, and a bare `help`/`--help` still prints everything.
+
+### Added
+
+- **`init` refuses to scaffold on top of a sync dir that already exists below
+  the target.** Run from the root of a bigger repo whose sync dir lives in
+  `n8n/`, `init` used to drop a second `decanter.config.json`, the template,
+  `workflows/`, `shared/`, `tsconfig.json` and the agent configs into the root.
+  It now looks a few levels down first and stops, naming the sync dir it found
+  and the `--dir=`/`N8N_DECANTER_DIR` form that addresses it from where you are
+  — the same advice every read verb already gives. A terminal gets it as a
+  question (`y` scaffolds anyway); a piped or flag-driven run exits 1 having
+  written nothing, not even the target directory. Re-running `init` **inside**
+  an existing sync dir is unchanged.
+
+- **The provenance line carries the build stamp, not just the hash**: the
+  node's source path relative to the sync dir, "do not edit here", the CLI
+  version, the git commit and the push time. The commit is HEAD at build time
+  and renders as `ca3c201+dirty` when the sync dir has uncommitted changes —
+  which, with `commitOnPush` on, is the normal case and reads correctly as
+  "built from working-tree state on top of `ca3c201`". Fields that cannot be
+  known (no git repo, unreadable `package.json`) are simply left out. **None of
+  it is hashed**, so a rename, a new commit or a CLI upgrade never makes a node
+  look changed — only the code below line 1 does.
+
+- **Credentials now resolve in a git worktree.** Both `.env` and
+  `.decanter-auth.json` are gitignored, so a fresh linked worktree had neither
+  and every credentialed verb died on `N8N_HOST must be set` — including the
+  `mcp connect` guard, which left agents in a worktree with no `n8n-instance`
+  tools at all. A worktree without its own credentials now reads the main
+  checkout's copies (same path, resolved from git's own worktree pointer, no
+  `git` subprocess). **A local file still wins**, so a worktree deliberately
+  aimed at another instance keeps its own, and nothing else is redirected —
+  `workflows/`, `.decanter.json` and `decanter.config.json` stay worktree-local.
+  For `.decanter-auth.json` the shared file is the only correct shape: the
+  refresh token is single-use and rotates, so **copying** it into a worktree
+  (what Claude Code's `.worktreeinclude` would do) forks it into two token
+  chains and kills the loser. New [Git
+  worktrees](/docs/concepts/configuration/#git-worktrees) section covers the two
+  remaining worktree gaps decanter cannot fix — a missing `node_modules` and the
+  per-path MCP approval — and the troubleshooting entry for missing
+  `n8n-instance` tools gained the worktree case.
+
 ## [0.10.2] - 2026-08-18
 
 ### Changed

package/README.md

@@ -37,6 +37,10 @@ clean git diffs.
 - **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.
+- **The deployed node says where it came from** — a compiled `.ts` node opens
+  in n8n with its source path, "do not edit here", the content hash and the
+  build stamp (CLI version, git commit, push time) on line 1, so a bundle full
+  of inlined helpers is never a mystery artifact.
 - **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
@@ -90,7 +94,9 @@ set a bare `pull`/`push`/`diff` acts on.)
 headless/CI — pass it to `init --host <url> --token <mcp-token>` rather than
 hand-writing `.env`, which leaves the config, template, `.gitignore` and agent
 configs unscaffolded; `N8N_API_KEY` is optional, needed only for `executions`,
-`data-tables`, and `backup`. Details: [Installation](docs/getting-started/installation.md),
+`data-tables`, and `backup`. Behind a proxy that attaches the n8n credentials
+itself, `init --auth upstream` sets `N8N_DECANTER_AUTH=upstream` and decanter
+sends none of its own. Details: [Installation](docs/getting-started/installation.md),
 [init](docs/cli/init.md), [Configuration](docs/concepts/configuration.md).
 
 ## Works with n8n's official skills
@@ -118,7 +124,7 @@ Full flag reference: `n8n-decanter --help`, or the
 
 | Verb | What it does |
 |---|---|
-| `init [dir]` | Bootstrap a sync dir — OAuth/token, template, config, agent tooling (`--host`/`--token`/`--api-key` drive it non-interactively) |
+| `init [dir]` | Bootstrap a sync dir — OAuth/token, template, config, agent tooling (`--host`/`--token`/`--api-key` drive it non-interactively; `--reauth` re-consents after a spent token) |
 | `completion zsh\|bash` | Print a shell completion script |
 | `pull [workflow…]` | Code + structure snapshot → `workflows/<kebab>/` |
 | `push [workflow…]` | Push Code-node source to the workflow's **draft** |

package/dist/lib/api.mjs

@@ -1,3 +1,4 @@
+import { AUTH_MODE_ENV } from "./config.mjs";
 /**
  * n8n public REST API client — since Plan 33 only the surfaces MCP cannot
  * serve: executions (no MCP read of full run data), data-table rows (MCP is
@@ -16,7 +17,19 @@
  * fold into `dataTable:read`, so a key that lists tables fine still 403s on
  * `/columns`.
  */
-function scopeHint(method, pathname) {
+function scopeHint(method, pathname, authMode) {
+    const scope = scopeName(method, pathname);
+    // In upstream mode the under-scoped key belongs to the proxy, so the scope
+    // name alone would send the reader to an `.env` that holds no key (Plan 92).
+    // Credentials mode keeps its exact previous wording.
+    if (authMode === "upstream") {
+        const where = "The key belongs to the upstream auth proxy, not to your .env — fix it where the proxy mints it.";
+        return scope === "" ? where : `${scope} ${where}`;
+    }
+    return scope === "" ? "Check the key's scopes in n8n → Settings → n8n API." : scope;
+}
+/** The scope a refused path needed, or `""` when the path is not one we map. */
+function scopeName(method, pathname) {
     const readOnly = " decanter only ever READS data tables — no write scope is needed.";
     if (pathname.includes("/data-tables/") && pathname.includes("/columns"))
         return `Add \`dataTableColumn:read\` (listing tables uses \`dataTable:list\`, which does NOT cover columns).${readOnly}`;
@@ -32,16 +45,18 @@ function scopeHint(method, pathname) {
         return "Add `workflow:create` (`backup restore` redeploys a backup as a new workflow).";
     if (pathname.startsWith("/api/v1/workflows"))
         return "Add `workflow:read` (and `workflow:list` for init's connection check).";
-    return "Check the key's scopes in n8n → Settings → n8n API.";
+    return "";
 }
 export class N8nApi {
     #host;
     #apiKey;
     #timeoutMs;
-    constructor({ host, apiKey, requestTimeoutMs = 30_000 }) {
+    #authMode;
+    constructor({ host, apiKey, requestTimeoutMs = 30_000, authMode = "credentials" }) {
         this.#host = host;
         this.#apiKey = apiKey;
         this.#timeoutMs = requestTimeoutMs;
+        this.#authMode = authMode;
     }
     /**
      * Recent executions, newest first. Read-only by design — the executions API is
@@ -134,7 +149,10 @@ export class N8nApi {
             const res = await fetch(this.#host + pathname, {
                 method,
                 headers: {
-                    "X-N8N-API-KEY": this.#apiKey,
+                    // OMITTED, not blanked, in upstream mode: the proxy in front of n8n
+                    // APPENDS its key to whatever the client sent, and n8n answers 401 to
+                    // the pair (measured 2026-09-09). An empty header is still a header.
+                    ...(this.#authMode === "credentials" && { "X-N8N-API-KEY": this.#apiKey }),
                     accept: "application/json",
                     ...(body !== undefined && { "content-type": "application/json" }),
                 },
@@ -147,8 +165,18 @@ export class N8nApi {
                 // and n8n does not say which scope is missing. Mapped HERE rather than
                 // in each caller so every REST surface (executions, data-tables, backup)
                 // gets it: `pathname` already identifies what was refused.
+                // 401 used to fall through to the bare status line below — the least
+                // helpful place to land, and the failure upstream mode makes most
+                // likely (a proxy that forwards but attaches nothing).
+                if (res.status === 401) {
+                    throw new Error(this.#authMode === "upstream"
+                        ? `${method} ${pathname} was rejected (401) — decanter sent no API key by design (${AUTH_MODE_ENV}=upstream); the upstream auth proxy did not attach a valid one`
+                        : `${method} ${pathname} was rejected (401) — N8N_API_KEY is not valid for ${this.#host} (n8n → Settings → n8n API)`);
+                }
                 if (res.status === 403) {
-                    throw new Error(`${method} ${pathname} was refused (403) — N8N_API_KEY is valid but lacks a scope. ${scopeHint(method, pathname)}`);
+                    throw new Error(this.#authMode === "upstream"
+                        ? `${method} ${pathname} was refused (403) — the API key the upstream auth proxy attaches is valid but lacks a scope. ${scopeHint(method, pathname, this.#authMode)}`
+                        : `${method} ${pathname} was refused (403) — N8N_API_KEY is valid but lacks a scope. ${scopeHint(method, pathname, this.#authMode)}`);
                 }
                 throw new Error(`${method} ${pathname} failed: ${res.status} ${res.statusText}\n${text.slice(0, 2000)}`);
             }

package/dist/lib/config.mjs

@@ -1,5 +1,34 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
+import { credentialFile } from "./git.mjs";
+/** The env file `init` writes next to `decanter.config.json` (gitignored). */
+export const ENV_FILE = ".env";
+/** The env var that selects who attaches the n8n credentials (Plan 92). */
+export const AUTH_MODE_ENV = "N8N_DECANTER_AUTH";
+/**
+ * Read `N8N_DECANTER_AUTH`. Unset (or empty, the shape an `.env` line with no
+ * value leaves behind) means decanter holds the credentials itself.
+ *
+ * **An unrecognized value throws rather than falling back to `credentials`.**
+ * The whole point of the upstream mode is that decanter sends no credential
+ * header; a typo that silently restored the header would reintroduce exactly
+ * the 401 this exists to remove, and it would look like a server problem.
+ *
+ * It is `N8N_DECANTER_*` and not `N8N_AUTH_MODE` on purpose: `N8N_HOST`,
+ * `N8N_API_KEY` and `N8N_MCP_TOKEN` carry n8n's name because they ARE n8n's
+ * credentials, while this is a decanter behavior switch — the category
+ * `N8N_DECANTER_DIR` established. It matters because this variable often sits
+ * in a `.env` an n8n container also reads, in a namespace that already holds
+ * `N8N_BASIC_AUTH_*` and `N8N_AUTH_EXCLUDE_ENDPOINTS`.
+ */
+export function readAuthMode(raw) {
+    const value = (raw ?? "").trim();
+    if (value === "" || value === "credentials")
+        return "credentials";
+    if (value === "upstream")
+        return "upstream";
+    throw new Error(`${AUTH_MODE_ENV}="${value}" is not a known auth mode — use "upstream" (a proxy in front of n8n attaches the credentials) or "credentials" (the default: decanter attaches them)`);
+}
 /**
  * The one message every cold start hits — a fresh clone has no `.env`, so this
  * is the first thing a user (or their agent) reads. It names the **flag** form
@@ -32,14 +61,24 @@ export function parseEnvFile(file) {
  * key is suddenly needed in an otherwise MCP-only setup.
  */
 export function requireApiKey(config, verb) {
+    // Upstream mode has no key to require: the proxy in front of n8n attaches
+    // one, and decanter deliberately sends none (Plan 92).
+    if (config.authMode === "upstream")
+        return config;
     if (config.apiKey === "") {
         throw new Error(`\`${verb}\` uses the n8n public REST API (MCP does not cover it) — set N8N_API_KEY in .env next to decanter.config.json (n8n → Settings → n8n API)`);
     }
     return config;
 }
-/** Load .env (if present) into process.env, not overriding existing vars. */
+/**
+ * Load the env file (if present) into process.env, not overriding existing
+ * vars. In a linked worktree without one of its own, the main checkout's copy
+ * is read instead (`credentialFile`) — the file is gitignored, so every fresh
+ * worktree starts without it and every credentialed verb would otherwise fail
+ * on `HOST_UNSET`.
+ */
 export function loadEnv(dir) {
-    for (const [key, value] of Object.entries(parseEnvFile(path.join(dir, ".env")))) {
+    for (const [key, value] of Object.entries(parseEnvFile(credentialFile(dir, ENV_FILE)))) {
         if (process.env[key] === undefined)
             process.env[key] = value;
     }
@@ -106,8 +145,15 @@ export function resolveSearchStart(dirFlag, cwd = process.cwd(), env = process.e
  * One `readdirSync` per visited dir, and the hit is read out of those entries —
  * the earlier shape (readdir the parent, then stat `<child>/decanter.config.json`
  * for every child) paid two round trips per directory to learn the same thing.
+ *
+ * Exported for `init` (Plan 86), the second caller and the only one that asks
+ * *before* writing: 81 taught the failure path of every read verb to recognise a
+ * sync dir below the cwd, while `init` — the one verb that scaffolds into a
+ * directory the user has not vetted — kept scaffolding a second one on top of it.
+ * `start` itself is never a hit, so a re-init inside an existing sync dir is
+ * unaffected.
  */
-function findConfigBelow(start, maxDepth = 3, maxDirs = 400, maxMs = 250) {
+export function findConfigBelow(start, maxDepth = 3, maxDirs = 400, maxMs = 250) {
     const deadline = Date.now() + maxMs;
     const queue = [{ dir: start, depth: 0 }];
     let visited = 0;
@@ -169,6 +215,11 @@ export function loadConfig(cwd = process.cwd(), { requireHost = true } = {}) {
             loadEnv(dir);
             const host = (process.env.N8N_HOST ?? "").replace(/\/+$/, "");
             const apiKey = process.env.N8N_API_KEY ?? "";
+            // Deliberately BEFORE the host check, and reached by the offline verbs
+            // too (they load config as well): a typo'd mode is a setup error worth
+            // hearing about on the first command that reads config, not on the first
+            // one that happens to need a credential.
+            const authMode = readAuthMode(process.env[AUTH_MODE_ENV]);
             if (requireHost && !host) {
                 throw new Error(HOST_UNSET);
             }
@@ -185,6 +236,7 @@ export function loadConfig(cwd = process.cwd(), { requireHost = true } = {}) {
                 backupLimit: typeof cfg.backupLimit === "number" && cfg.backupLimit >= 0 ? Math.floor(cfg.backupLimit) : 20,
                 host,
                 apiKey,
+                authMode,
             };
         }
         const parent = path.dirname(dir);

package/dist/lib/git.mjs

@@ -1,4 +1,6 @@
 import { execFile as execFileCb } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
 import { promisify } from "node:util";
 const execFile = promisify(execFileCb);
 /** True when `dir` sits inside a git work tree (the live-mirror safety-net gate). */
@@ -52,3 +54,115 @@ export async function commitWorkflowDir(dir, message, log, extraPaths = []) {
         return "failed";
     }
 }
+/**
+ * Short HEAD sha for the provenance line (Plan 84), `+dirty` when anything
+ * under `dir` is uncommitted. `null` outside a repo, on an unborn branch, or
+ * when git is missing — the marker line simply drops the field.
+ *
+ * Two things about the value are deliberately imprecise, and the imprecision
+ * runs the safe way:
+ *
+ * - **HEAD is the commit BEFORE the one that will contain the pushed source.**
+ *   `commitWorkflowDir` runs *after* the MCP write (lib/push.mts), so at build
+ *   time the source is still working-tree state. Rendering `ca3c201+dirty`
+ *   says exactly that, and honestly. (Moving the auto-commit ahead of the
+ *   write was rejected: it would leave a commit claiming a push that failed.)
+ * - **The dirty check is scoped to the whole sync dir**, not to this node's
+ *   own inputs. A bundled node pulls in helpers from anywhere in the sync dir
+ *   (Plan 79), and esbuild's input list is not plumbed out here — so an
+ *   unrelated edit elsewhere in the dir also reads as dirty. That over-reports
+ *   rather than under-reports, which is the side that cannot mislead someone
+ *   trying to reproduce the artifact from the named commit.
+ */
+export async function headCommit(dir) {
+    try {
+        const { stdout } = await execFile("git", ["-C", dir, "rev-parse", "--short", "HEAD"]);
+        const sha = stdout.trim();
+        if (sha === "")
+            return null;
+        const { stdout: status } = await execFile("git", ["-C", dir, "status", "--porcelain", "--", "."]);
+        return status.trim() === "" ? sha : `${sha}+dirty`;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------- linked worktrees ----------
+/**
+ * The main checkout's twin of `dir`, or `null` when `dir` is not inside a
+ * linked git worktree.
+ *
+ * Pure filesystem reads — deliberately no `git` subprocess. The callers
+ * (`loadEnv`, `resolveMcpAuth`) are synchronous and sit on the startup path of
+ * `mcp connect`, which an agent spawns once per session; a spawn there would be
+ * paid on every session start of every agent.
+ *
+ * The walk: a linked worktree's `.git` is a FILE holding
+ * `gitdir: <main>/.git/worktrees/<name>`, and that directory's `commondir` file
+ * points back at the shared git dir (`../..`), whose parent is the main
+ * checkout. A submodule's `.git` is a file too, but points into
+ * `.git/modules/<name>` — the `worktrees` parent segment is what tells the two
+ * apart, and a submodule must NOT resolve against its superproject.
+ *
+ * The twin is a path, not a promise that anything exists there: the sync dir is
+ * tracked content (`decanter.config.json` is committed), so its path relative
+ * to the checkout root is identical on both sides — but a worktree branched
+ * from before the sync dir existed has no twin on disk. Callers check.
+ */
+export function mainCheckoutTwin(dir) {
+    const resolved = path.resolve(dir);
+    let root = resolved;
+    while (!existsSync(path.join(root, ".git"))) {
+        const parent = path.dirname(root);
+        if (parent === root)
+            return null; // walked to the filesystem root, no repo
+        root = parent;
+    }
+    const dotGit = path.join(root, ".git");
+    // A directory means the main checkout itself (or a plain clone) — no twin.
+    if (statSync(dotGit, { throwIfNoEntry: false })?.isFile() !== true)
+        return null;
+    const pointer = readFileSync(dotGit, "utf8").trim();
+    if (!pointer.startsWith("gitdir:"))
+        return null;
+    const gitdir = path.resolve(root, pointer.slice("gitdir:".length).trim());
+    if (path.basename(path.dirname(gitdir)) !== "worktrees")
+        return null; // submodule
+    const commonFile = path.join(gitdir, "commondir");
+    const common = existsSync(commonFile)
+        ? path.resolve(gitdir, readFileSync(commonFile, "utf8").trim())
+        : path.resolve(gitdir, "..", ".."); // every git writes commondir; belt and braces
+    const twin = path.join(path.dirname(common), path.relative(root, resolved));
+    return twin === resolved ? null : twin;
+}
+/**
+ * Where to read a gitignored credential file (`.env`, `.decanter-auth.json`)
+ * from: this dir when it has its own, else the main checkout's copy when this
+ * is a linked worktree.
+ *
+ * **Local wins, always.** A worktree deliberately pointed at a staging instance
+ * keeps its own credentials; the fallback only fires where the alternative is
+ * failing outright, because both files are gitignored and therefore absent from
+ * every fresh worktree.
+ *
+ * For the auth file the shared copy is not merely convenient, it is the only
+ * correct shape: the OAuth refresh token is single-use and rotates on every
+ * redemption, and the cross-process recovery in `lib/mcp.mts` re-reads *the
+ * same file* to adopt the winner's token. Two copies fork into two token chains
+ * that recovery cannot repair — which is exactly what copying the file into a
+ * worktree (the obvious workaround, and the one Claude Code's `.worktreeinclude`
+ * would perform) silently does.
+ *
+ * Falls back to the local path when nothing is found, so a "not set" error
+ * still names the file the user is expected to create.
+ */
+export function credentialFile(dir, name) {
+    const local = path.join(dir, name);
+    if (existsSync(local))
+        return local;
+    const twin = mainCheckoutTwin(dir);
+    if (twin === null)
+        return local;
+    const shared = path.join(twin, name);
+    return existsSync(shared) ? shared : local;
+}