@tpsdev-ai/flair 0.30.0 → 0.31.0

package/dist/install/clients.js

@@ -14,10 +14,10 @@
 //   All paths are resolved cross-platform (Linux included) via standard
 //   per-client locations under $HOME / $XDG_CONFIG_HOME.
 // ---- Detection helpers ----------------------------------------------------------
-import { spawnSync } from "node:child_process";
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { mcpServerSpec } from "../lib/mcp-spec.js";
 /**
  * Resolve the user's home dir. Prefer the live HOME/USERPROFILE env over
  * os.homedir(), which caches the value at process start and so ignores a
@@ -59,57 +59,61 @@ function binInPath(name) {
         return false;
     }
 }
-function claudeCodeDetect() {
-    try {
-        const result = spawnSync("npm", ["list", "-g", "@anthropic-ai/claude-code"], {
-            stdio: ["ignore", "ignore", "ignore"],
-        });
-        return result.status === 0;
-    }
-    catch (_e) {
-        return false;
-    }
-}
-function codexDetect() {
-    try {
-        if (binInPath("codex"))
-            return true;
-        const npmResult = spawnSync("npm", ["list", "-g", "@openai/codex"], {
-            stdio: ["ignore", "ignore", "ignore"],
-        });
-        return npmResult.status === 0;
-    }
-    catch (_e) {
-        return false;
-    }
-}
-function geminiDetect() {
-    try {
-        if (binInPath("gemini"))
-            return true;
-        const npmResult = spawnSync("npm", ["list", "-g", "@google/generative-ai"], {
-            stdio: ["ignore", "ignore", "ignore"],
-        });
-        return npmResult.status === 0;
-    }
-    catch (_e) {
-        return false;
-    }
-}
-function cursorDetect() {
+/**
+ * A client is INSTALLED when its executable is on PATH. One rule for all four,
+ * evaluated with filesystem calls only — detection never starts a subprocess.
+ *
+ * Claude Code, Codex and Gemini used to fall back to `npm list -g <pkg>` when
+ * the binary was absent. That fallback was removed (flair#906 follow-up); it
+ * was wrong in three separate directions and bought nothing:
+ *
+ *   1. UNBOUNDED AND SLOW ON AN INTERACTIVE PATH. `npm list -g <pkg>` walks the
+ *      whole global tree, measured at ~0.8 s per call on a warm developer
+ *      machine, with no `timeout` set. `flair init` calls detectClients(), so a
+ *      user with none of these clients paid up to three of those walks — seconds
+ *      of silent stall on first run — and on a loaded CI runner the same three
+ *      calls blew past a 5 s test timeout.
+ *
+ *   2. FALSE POSITIVES. `npm list -g <pkg>` exits 0 when the package appears
+ *      ANYWHERE in the global tree, including as a transitive dependency of an
+ *      unrelated global package. Gemini was probed with `@google/generative-ai`
+ *      — a library, not the CLI — so any globally installed tool that depended
+ *      on it made Flair report Gemini "detected" and write ~/.gemini/settings.json
+ *      for a CLI that was not on the machine.
+ *
+ *   3. FALSE NEGATIVES. It assumes npm's default global prefix, so it reports
+ *      "not installed" for mise / fnm / nvm / volta users whose prefix lives
+ *      elsewhere — the same defect already fixed for `flair upgrade`'s presence
+ *      probes (see "Upgrade presence probes" in src/cli.ts).
+ *
+ * Nothing is lost by dropping it: an `npm install -g` links the package's bin
+ * into the prefix's bin directory, which is on PATH by construction (it is where
+ * `npm` itself is found from). A client whose binary is NOT on PATH is a client
+ * the user cannot launch, and wiring an MCP config for it is at best a no-op.
+ * `flair init --client <name>` still wires a client explicitly, bypassing
+ * detection entirely, so an exotic install is never locked out.
+ */
+function detectBin(bin) {
     try {
-        return binInPath("cursor");
+        return binInPath(bin);
     }
     catch (_e) {
         return false;
     }
 }
 // ---- Shared config shapes -------------------------------------------------------
-/** The standard MCP stdio server entry every client (except Codex TOML) uses. */
+/**
+ * The standard MCP stdio server entry every client (except Codex TOML) uses.
+ *
+ * The spec comes from mcpServerSpec() and is therefore PINNED — this used to
+ * hardcode the bare `@tpsdev-ai/flair-mcp`, so Gemini, Cursor and the Claude
+ * Code array fallback were all wired unpinned while only the inline Claude
+ * Code path in cli.ts got the pin it was documented to get (flair#907).
+ */
 function flairMcpEntry(env) {
     return {
         command: "npx",
-        args: ["-y", "@tpsdev-ai/flair-mcp"],
+        args: ["-y", mcpServerSpec()],
         env: {
             FLAIR_AGENT_ID: env.FLAIR_AGENT_ID,
             FLAIR_URL: env.FLAIR_URL,
@@ -124,12 +128,13 @@ function jsonSnippet(env) {
     return JSON.stringify({ mcpServers: { flair: flairMcpEntry(env) } }, null, 2);
 }
 /** TOML `[mcp_servers.flair]` snippet (Codex format). Exported for tests
- * (flair#727 — asserts the rendered template carries a full scheme+port URL). */
+ * (flair#727 — asserts the rendered template carries a full scheme+port URL).
+ * Pinned via mcpServerSpec() — see flairMcpEntry above for why (flair#907). */
 export function tomlSnippet(env) {
     return [
         `[mcp_servers.flair]`,
         `command = "npx"`,
-        `args = ["-y", "@tpsdev-ai/flair-mcp"]`,
+        `args = ["-y", "${mcpServerSpec()}"]`,
         ``,
         `[mcp_servers.flair.env]`,
         `FLAIR_AGENT_ID = "${env.FLAIR_AGENT_ID}"`,
@@ -283,36 +288,89 @@ export const ALL_CLIENTS = [
     {
         id: "claude-code",
         label: "Claude Code",
+        bin: "claude",
         wire: _wireClaudeCode,
     },
     {
         id: "codex",
         label: "Codex",
+        bin: "codex",
         wire: _wireCodex,
     },
     {
         id: "gemini",
         label: "Gemini",
+        bin: "gemini",
         wire: _wireGemini,
     },
     {
         id: "cursor",
         label: "Cursor",
+        bin: "cursor",
         wire: _wireCursor,
     },
 ];
+/**
+ * The summary `flair init` prints LAST.
+ *
+ * Every fact here was already available mid-run — `wiringResults` has always
+ * distinguished "wired ~/.claude.json" from "snippet printed (no
+ * ~/.claude.json)". What was missing is a place where the difference is still
+ * on screen once the command finishes: a not-wired client showed up only as a
+ * snippet in the middle of a wall of output, *after* a success line, so
+ * `--client all` read as having done all of it (flair#906). Pure so it can be
+ * tested without running init.
+ */
+export function renderWiringSummary(results, opts = {}) {
+    const label = (id) => opts.labels?.get(id) ?? id;
+    const skipped = opts.skippedUndetected ?? [];
+    const wired = results.filter(r => r.wired);
+    const notWired = results.filter(r => !r.wired);
+    if (results.length === 0 && skipped.length === 0)
+        return [];
+    const lines = [{ level: "heading", text: "MCP clients" }];
+    if (wired.length > 0) {
+        lines.push({ level: "ok", text: `Wired: ${wired.map(r => label(r.client)).join(", ")}` });
+    }
+    // One line per NOT-wired client, naming the client and why — a count alone
+    // ("1 client failed") sends the user back to scrollback to find which.
+    for (const r of notWired) {
+        lines.push({ level: "error", text: `NOT wired: ${label(r.client)} — ${r.message}` });
+    }
+    if (skipped.length > 0) {
+        lines.push({ level: "muted", text: `Not installed, skipped: ${skipped.join(", ")}` });
+    }
+    if (wired.length === 0 && notWired.length === 0) {
+        lines.push({
+            level: "warn",
+            text: opts.rewireHint
+                ? `No MCP client was wired. Install a client, then re-run: ${opts.rewireHint}`
+                : "No MCP client was wired.",
+        });
+    }
+    if (notWired.length > 0) {
+        lines.push({
+            level: "warn",
+            text: `${notWired.length} client(s) need manual wiring — see the config printed above, or docs/mcp-clients.md`,
+        });
+    }
+    if (opts.unpinned) {
+        lines.push({
+            level: "warn",
+            text: "MCP server wired UNPINNED (Flair could not read its own version) — see the warning above.",
+        });
+    }
+    return lines;
+}
+/**
+ * Detect every known client. One rule (`bin` on PATH) applied uniformly, so a
+ * client added to ALL_CLIENTS is detected by declaring its executable — there is
+ * no per-client branch here to forget to extend.
+ */
 export function detectClients() {
     return ALL_CLIENTS.map((client) => ({
         ...client,
-        detected: client.id === "claude-code"
-            ? claudeCodeDetect()
-            : client.id === "codex"
-                ? codexDetect()
-                : client.id === "gemini"
-                    ? geminiDetect()
-                    : client.id === "cursor"
-                        ? cursorDetect()
-                        : false,
+        detected: detectBin(client.bin),
     }));
 }
 export function wireClaudeCode(env) {

package/dist/lib/mcp-spec.js

@@ -0,0 +1,128 @@
+// ─── The `@tpsdev-ai/flair-mcp` spec written into client MCP configs ────────
+//
+// ONE definition of "which flair-mcp does a wired client run", shared by every
+// writer. It used to live in src/cli.ts and be applied at exactly ONE of the
+// five places that write a spec — src/install/clients.ts hardcoded the bare
+// unpinned string in `flairMcpEntry()` (Claude Code fallback / Gemini / Cursor)
+// and `tomlSnippet()` (Codex), so every client except the inline Claude Code
+// branch was wired unpinned no matter what the CLI's own version resolved to
+// (flair#907). A pin that lives next to one call site is a pin the next call
+// site forgets; it lives here now so a writer has to go out of its way to be
+// unpinned.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** The npm package a wired client runs via `npx`. */
+export const FLAIR_MCP_PACKAGE = "@tpsdev-ai/flair-mcp";
+/** The CLI package whose version is the correct pin (lockstep with flair-mcp). */
+const FLAIR_PACKAGE = "@tpsdev-ai/flair";
+/** What every version-resolution path reports when it cannot read package.json. */
+export const UNKNOWN_VERSION = "unknown";
+/**
+ * Walk up from `startDir` looking for `@tpsdev-ai/flair`'s own package.json.
+ *
+ * Deliberately a NAMED search rather than a fixed number of `..` hops: this
+ * module is compiled to `dist/lib/mcp-spec.js` while its previous home
+ * (src/cli.ts) compiled to `dist/cli.js`, so a hardcoded depth is one
+ * refactor away from silently resolving "unknown" — and "unknown" is not a
+ * loud failure, it is a downgraded security property (see mcpServerSpec).
+ * Checking `name` also means a stray package.json in an intermediate
+ * directory can't be mistaken for ours.
+ *
+ * Exported for tests, which need to exercise the not-found path without
+ * corrupting a real install.
+ */
+export function resolveFlairCliVersion(startDir) {
+    let dir = startDir;
+    // 8 levels is far more than any real layout needs (dist/lib → package root
+    // is 2) while still terminating on a pathological symlink loop.
+    for (let i = 0; i < 8; i++) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8"));
+            if (pkg?.name === FLAIR_PACKAGE && typeof pkg.version === "string" && pkg.version) {
+                return pkg.version;
+            }
+        }
+        catch {
+            // No package.json here, or unreadable/malformed — keep walking.
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break; // filesystem root
+        dir = parent;
+    }
+    return UNKNOWN_VERSION;
+}
+let cachedVersion;
+/**
+ * This CLI's own version — the single source for `--version`, the CLI↔server
+ * handshake, `upgrade --check`, and the MCP pin. Cached: the answer cannot
+ * change within a process, and several commands ask repeatedly.
+ */
+export function flairCliVersion() {
+    if (cachedVersion === undefined) {
+        cachedVersion = resolveFlairCliVersion(import.meta.dirname ?? __dirname);
+    }
+    return cachedVersion;
+}
+/** True when `version` is usable as a pin. */
+export function isResolvedVersion(version) {
+    return !!version && version !== UNKNOWN_VERSION;
+}
+/**
+ * The `@tpsdev-ai/flair-mcp` spec written into a client's MCP config.
+ *
+ * PINNED, deliberately. A bare `npx -y @tpsdev-ai/flair-mcp` re-resolves to
+ * whatever is currently published on EVERY agent session — so a single bad
+ * publish (stolen credentials, a malicious commit that clears review, or a
+ * compromised dependency of the MCP package) reaches every wired user
+ * silently, with no lockfile and no review step in the path. The postmark-mcp
+ * incident was exactly this shape: a legitimate publish by the legitimate
+ * owner, propagating for 16 days before anyone noticed. Worse, a yank does
+ * not help — unpinned clients keep resolving latest.
+ *
+ * Our publish side is already hardened (OIDC staged publish, human 2FA at the
+ * release gate), but that defends against credential theft, not against a bad
+ * version being published legitimately. The consumer side is where that gap
+ * closes, and pinning is what closes it: a wired client keeps running the
+ * exact version that was current when it was wired, and moving forward
+ * becomes a deliberate act.
+ *
+ * flair and flair-mcp ship in version lockstep from this monorepo, so the
+ * running CLI's own version is the correct pin. `flair init` re-run rewires
+ * to the then-current version.
+ *
+ * Falls back to the unpinned spec when the version can't be read — the same
+ * condition under which `--version` reports "unknown", i.e. a broken install.
+ * That fallback is NOT silent: callers that write a config must surface
+ * unpinnedSpecWarning() (flair#907). Quietly substituting a weaker guarantee
+ * for a documented one is how a user ends up believing they are pinned.
+ */
+export function mcpServerSpec(version = flairCliVersion()) {
+    return isResolvedVersion(version)
+        ? `${FLAIR_MCP_PACKAGE}@${version}`
+        : FLAIR_MCP_PACKAGE;
+}
+/**
+ * The warning a config-writing command MUST print when the spec it is about
+ * to write cannot be pinned. Returns null in the normal case, so a caller is
+ * `const w = unpinnedSpecWarning(); if (w) ...`.
+ *
+ * Warn rather than refuse: an unresolvable version means a damaged install,
+ * and hard-failing `init` there turns "MCP works, but unpinned" into "the
+ * user has nothing" — while leaving them no better able to diagnose it. The
+ * wiring still has value; the false belief in a pin is what has to go. So the
+ * consequence is named explicitly, and the caller is expected to repeat this
+ * where the user will still see it once the command finishes.
+ */
+export function unpinnedSpecWarning(version = flairCliVersion()) {
+    if (isResolvedVersion(version))
+        return null;
+    return [
+        `Could not read Flair's own version, so ${FLAIR_MCP_PACKAGE} is being wired UNPINNED.`,
+        `Consequence: every agent session re-resolves it to the latest published version,`,
+        `so a future publish reaches this machine with no review step. Normally the spec is`,
+        `pinned to the CLI version that wired it.`,
+        `Fix: reinstall the CLI (npm i -g ${FLAIR_PACKAGE}) and re-run this command, or edit`,
+        `the client config by hand to read "${FLAIR_MCP_PACKAGE}@<version>".`,
+    ].join("\n");
+}

package/dist/lib/safe-snapshot-extract.js

@@ -0,0 +1,231 @@
+// safe-snapshot-extract.ts — path-escape-safe extraction for physical
+// snapshot tarballs.
+//
+// WHY THIS EXISTS
+// ---------------
+// `createDataSnapshot` archives with `preservePaths: true`, and it needs to:
+// WITHOUT it, node-tar strips the leading "/" off any absolute symlink
+// TARGET, so an in-bounds symlink pointing at an absolute path under the
+// data dir comes back as a nonsense RELATIVE path — silently broken.
+//
+// The restore side used to mirror that flag, reasoning that the archive
+// "only contains what createDataSnapshot's filter chose to include". That
+// reasoning does not hold: restore accepts a tarball the CLI did not create
+// — copied from another machine, downloaded, or handed over during a
+// migration. `preservePaths: true` disables BOTH of node-tar's containment
+// behaviours (it stops stripping a leading "/" from entry PATHS, and stops
+// rejecting ".." segments), so a hostile archive could write anywhere the
+// invoking user can write.
+//
+// The flag is load-bearing for symlink TARGET text and useless-to-harmful
+// for entry PATHS, and node-tar exposes only the one knob for both. So we
+// keep `preservePaths: true` and do the containment check ourselves —
+// strictly, and BEFORE anything is written to disk.
+//
+// Posture is FAIL CLOSED: a snapshot with even one out-of-bounds entry is
+// refused whole, rather than extracted-minus-the-bad-parts. A snapshot that
+// wants to escape is not a snapshot we can vouch for the rest of.
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, resolve, sep } from "node:path";
+import { extract as tarExtract, list as tarList } from "tar";
+/** Thrown when a snapshot entry would resolve outside the target directory. */
+export class SnapshotPathEscapeError extends Error {
+    entryPath;
+    reason;
+    constructor(message, entryPath, reason) {
+        super(message);
+        this.name = "SnapshotPathEscapeError";
+        this.entryPath = entryPath;
+        this.reason = reason;
+    }
+}
+/**
+ * True when `candidate` is the directory itself or lives underneath it.
+ * Compares resolved absolute paths; the `+ sep` guard stops "/a/bc" from
+ * counting as inside "/a/b".
+ */
+function isWithin(candidate, root) {
+    return candidate === root || candidate.startsWith(root + sep);
+}
+/**
+ * Absolute in the sense that matters for tar containment. `isAbsolute` alone
+ * is platform-dependent, and an archive is attacker-controlled data that need
+ * not match the host it is being extracted on — so a Windows-shaped drive or
+ * UNC path is treated as absolute even on POSIX.
+ */
+function looksAbsolute(p) {
+    return isAbsolute(p) || /^[a-zA-Z]:[\\/]/.test(p) || p.startsWith("/") || p.startsWith("\\\\");
+}
+/** A ".." component anywhere in the path, under either separator. */
+function hasDotDotSegment(p) {
+    return p.split(/[\\/]+/).includes("..");
+}
+/**
+ * Lexical containment check for a single archive entry. Pure — no filesystem
+ * access — so it can run over the whole archive listing before a single byte
+ * is written.
+ *
+ * `linkpath` is the entry's link target, when it has one.
+ */
+export function checkSnapshotEntry(entryPath, type, linkpath, resolvedTargetDir) {
+    if (looksAbsolute(entryPath)) {
+        return { ok: false, reason: `entry has an absolute path ("${entryPath}"), which would write outside the target directory` };
+    }
+    if (hasDotDotSegment(entryPath)) {
+        return { ok: false, reason: `entry path contains a ".." segment ("${entryPath}"), which would traverse outside the target directory` };
+    }
+    const dest = resolve(resolvedTargetDir, entryPath);
+    if (!isWithin(dest, resolvedTargetDir)) {
+        return { ok: false, reason: `entry resolves to "${dest}", outside the target directory` };
+    }
+    if (linkpath) {
+        if (type === "Link") {
+            // Hardlink: node-tar resolves linkpath relative to cwd, and a hardlink
+            // to a file outside the target would expose that file's contents
+            // through the restored tree.
+            if (looksAbsolute(linkpath) || hasDotDotSegment(linkpath)) {
+                return { ok: false, reason: `hard link "${entryPath}" points to "${linkpath}", outside the target directory` };
+            }
+            const linkDest = resolve(resolvedTargetDir, linkpath);
+            if (!isWithin(linkDest, resolvedTargetDir)) {
+                return { ok: false, reason: `hard link "${entryPath}" resolves to "${linkDest}", outside the target directory` };
+            }
+        }
+        else if (type === "SymbolicLink") {
+            // Symlink targets are written verbatim (that is what preservePaths
+            // buys us), so an absolute target is legitimate — but only if it lands
+            // inside the target directory. This mirrors createDataSnapshot's own
+            // filter, which already refuses to archive a symlink pointing outside
+            // the data dir; such an entry cannot have come from a snapshot this
+            // CLI produced for this target directory.
+            const linkDest = looksAbsolute(linkpath)
+                ? resolve(linkpath)
+                : resolve(dirname(resolve(resolvedTargetDir, entryPath)), linkpath);
+            if (!isWithin(linkDest, resolvedTargetDir)) {
+                return { ok: false, reason: `symlink "${entryPath}" points to "${linkDest}", outside the target directory` };
+            }
+        }
+    }
+    return { ok: true };
+}
+/**
+ * Resolve a path's existing ancestor chain through symlinks. Used to catch an
+ * entry that would be written THROUGH a symlink an earlier entry in the same
+ * archive created — the lexical check cannot see that, because the path has
+ * no ".." and is not absolute.
+ */
+function realpathOfNearestExistingAncestor(p) {
+    let cur = p;
+    // Walk up until something exists; the freshly-created target dir always does.
+    for (let i = 0; i < 256; i++) {
+        if (existsSync(cur))
+            return realpathSync(cur);
+        const parent = dirname(cur);
+        if (parent === cur)
+            return cur;
+        cur = parent;
+    }
+    return cur;
+}
+/**
+ * Resolve the target directory for containment comparisons. realpath when it
+ * already exists — on macOS the temp dir itself sits behind a symlink
+ * (/tmp -> /private/tmp), so a purely lexical resolve would misclassify
+ * genuinely in-bounds paths — falling back to a lexical resolve when it does
+ * not (validation runs before the directory is recreated).
+ */
+function resolveTargetDir(p) {
+    const lexical = resolve(p);
+    try {
+        return realpathSync(lexical);
+    }
+    catch {
+        return lexical;
+    }
+}
+/**
+ * Read the archive's listing and throw if any entry would land outside
+ * `targetDir`. Writes NOTHING — call this before any destructive step so a
+ * hostile snapshot cannot cost the operator their data directory on the way
+ * to being refused.
+ */
+export async function validateSnapshotArchive(opts) {
+    const resolvedTargetDir = resolveTargetDir(opts.targetDir);
+    const violations = [];
+    await tarList({
+        file: opts.file,
+        onReadEntry: (entry) => {
+            const verdict = checkSnapshotEntry(String(entry.path ?? ""), entry.type, entry.linkpath ? String(entry.linkpath) : undefined, resolvedTargetDir);
+            // `verdict.ok === false` rather than `!verdict.ok`: an explicit
+            // comparison against the literal discriminant is what narrows the union
+            // to its failure member, so `reason` is known to exist here. The union
+            // is deliberately shaped so a caller cannot read a reason off a success.
+            if (verdict.ok === false) {
+                violations.push({ entryPath: String(entry.path ?? ""), reason: verdict.reason });
+            }
+        },
+    });
+    if (violations.length > 0) {
+        const shown = violations.slice(0, 5).map((v) => `  - ${v.reason}`).join("\n");
+        const more = violations.length > 5 ? `\n  ...and ${violations.length - 5} more` : "";
+        throw new SnapshotPathEscapeError(`refusing to restore: this snapshot contains ${violations.length} ` +
+            `entr${violations.length === 1 ? "y that would write" : "ies that would write"} outside ${resolvedTargetDir}.\n` +
+            `${shown}${more}\n` +
+            `Nothing was extracted and the target directory was left as-is.\n` +
+            `A snapshot taken by "flair snapshot create" never contains such entries — this archive was ` +
+            `either produced by something else or modified after it was taken. Restore from a snapshot you ` +
+            `trust, or inspect this one with "tar -tzvf <snapshot>" before using it.`, violations[0].entryPath, violations[0].reason);
+    }
+}
+/**
+ * Extract a snapshot tarball into `targetDir`, refusing any archive that
+ * would write outside it.
+ *
+ * Two passes on purpose:
+ *   1. `validateSnapshotArchive` — no writes at all, so a hostile archive is
+ *      refused before it can leave a partial mess behind.
+ *   2. Extract, with a filesystem-aware guard that re-checks each entry
+ *      against symlinks created earlier in the same archive — an escape the
+ *      lexical pass cannot see, because such a path is neither absolute nor
+ *      contains "..".
+ *
+ * `preservePaths: true` is retained for symlink-target fidelity; see this
+ * file's header.
+ */
+export async function extractSnapshotSafely(opts) {
+    await validateSnapshotArchive(opts);
+    const resolvedTargetDir = resolveTargetDir(opts.targetDir);
+    // ── Pass 2: extract, guarding against write-through-symlink ─────────────
+    const runtimeViolations = [];
+    await tarExtract({
+        file: opts.file,
+        cwd: resolvedTargetDir,
+        // Load-bearing: keeps absolute symlink TARGET text verbatim. Entry-path
+        // containment is our job, done above and re-checked here.
+        preservePaths: true,
+        filter: (entryPath) => {
+            const dest = resolve(resolvedTargetDir, entryPath);
+            // Resolve `dest` itself, NOT dirname(dest): a real snapshot's first
+            // entry is "./" (createDataSnapshot archives the fileList ["."]), whose
+            // dest IS the target directory — taking its parent would resolve to the
+            // directory ABOVE the target and reject every legitimate snapshot.
+            // Walking up from dest gives the target dir itself for that entry, and
+            // still catches a symlinked ancestor for everything deeper.
+            const anchor = realpathOfNearestExistingAncestor(dest);
+            if (!isWithin(anchor, resolvedTargetDir)) {
+                runtimeViolations.push({
+                    entryPath,
+                    reason: `entry "${entryPath}" would be written through a symlink to "${anchor}", outside the target directory`,
+                });
+                return false;
+            }
+            return true;
+        },
+    });
+    if (runtimeViolations.length > 0) {
+        const v = runtimeViolations[0];
+        throw new SnapshotPathEscapeError(`refusing to complete this restore: ${v.reason}.\n` +
+            `The target directory ${resolvedTargetDir} is now partially written and must not be used — ` +
+            `delete it and restore from a snapshot you trust.`, v.entryPath, v.reason);
+    }
+}