@henols/vice-mcp 0.1.4

package/containerpath.ts

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+// Build a CONTAINER path from something a HOST-side process handed back to
+// us in host-filesystem terms.
+//
+// This is the INVERSE of hostpath.ts's outbound direction. hostpath.ts
+// solves "I have a container path and need to hand it to something running
+// on the host" -- container -> host. This file solves the opposite: "a
+// host-side process handed ME a path (or a URL naming a loopback host) in
+// ITS OWN terms, and I need the container-side equivalent to actually open
+// it" -- host -> container.
+//
+// This direction did not exist until Phase 01.2's on-demand VICE broker
+// started handing this container back its OWN grant records: the broker
+// runs on the host, legitimately resolves its own repo root, and writes a
+// grant carrying a loopback `url` plus host-rooted `epoch_file` and
+// `supervisor_dir` fields (its own view of the filesystem -- entirely
+// correct from where it's standing). Until this module existed, nothing
+// inverted those coordinates before they were adopted as the session's
+// identity: loopback meant the CONTAINER's own loopback (ECONNREFUSED, since
+// nothing listens there), and the host-rooted epoch path simply didn't
+// resolve inside the container. Every broker-granted instance was silently
+// unreachable -- see
+// .planning/quick/260801-ccn-translate-broker-granted-host-coordinate/260801-ccn-PLAN.md's
+// "The bug" section for the full, already-root-caused failure shape this
+// module fixes.
+//
+// Mirrors hostpath.ts deliberately: the same derive-never-hardcode rule
+// (the mapping is never written down as a literal -- see hostRootCandidates()
+// below), the same `{ candidates, exact?, reason? }` return contract, the
+// same throw-with-the-env-hint contract, the same CLI-at-the-bottom guard.
+// What this file does NOT know: which FIELDS a grant record carries, or what
+// the container-visible host alias is -- that is broker-protocol knowledge
+// that belongs at the one seam that sees every grant as written
+// (vice-proxy.mjs's containerizeGrant()), not duplicated here. This module
+// only ever answers "given a host path or a URL naming a host, what is its
+// container-side equivalent" -- nothing more, so it stays a generic
+// host<->container primitive rather than a second copy of broker knowledge.
+import { hostPathCandidates, SET_ENV_HINT } from "./hostpath.ts";
+import { repoRoot } from "./repo-root.ts";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+export { SET_ENV_HINT };
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+// Same derivation and the same env override hostpath.ts's own
+// WORKSPACE_ROOT/CONTAINER_WS use -- this file lives beside it, so the two
+// must always agree; this is not a second, possibly-diverging copy, just the
+// same resolution applied to this file's own location. Both dropped their
+// hard-coded four-level hop when they moved here from
+// .claude/skills/devcontainer-host-path/scripts/, where that count was
+// correct; see hostpath.ts's note on why a fixed count is the wrong shape.
+const WORKSPACE_ROOT = repoRoot({ from: HERE });
+const CONTAINER_WS = process.env.CONTAINER_WORKSPACE_PATH || WORKSPACE_ROOT;
+
+// Matched structurally (127.0.0.0/8 in full, "localhost", and the IPv6
+// loopback exactly as the WHATWG URL parser itself renders `.hostname` --
+// bracketed, "[::1]"), never against the single "127.0.0.1" literal this bug
+// was actually observed with (D-4).
+const IPV4_LOOPBACK_RE = /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
+
+function isLoopbackHostname(hostname: string): boolean {
+  return hostname === "localhost" || hostname === "[::1]" || IPV4_LOOPBACK_RE.test(hostname);
+}
+
+/** hostRootCandidates()'s own return shape: `roots` the cleaned, de-duplicated,
+ * longest-first list of candidate host root paths, `exact` true only when the
+ * sibling's own hostPathCandidates() came back with an exact (env-derived)
+ * match needing no adjudication. */
+export interface HostRootCandidatesResult {
+  roots: string[];
+  exact: boolean;
+}
+
+/**
+ * The container workspace root's own candidate HOST paths -- from
+ * `hostPathCandidates()`, the sibling's own outbound derivation, never
+ * duplicated here (this is the whole of D-3: the mapping is derived at
+ * runtime off the sibling's own knowledge, and no absolute host path is ever
+ * written down in this file, checked by containerpath.test.ts's own
+ * runtime-derived source assertion). Cleaned up for use as a match prefix: a
+ * trailing separator stripped (hostPathCandidates() for the workspace root
+ * itself returns a candidate with one, since its template joins an empty
+ * relative tail), de-duplicated, and sorted LONGEST-first so a short or
+ * empty guess prefix can never shadow a longer, more specific one when
+ * matching a host path below.
+ */
+export function hostRootCandidates(): HostRootCandidatesResult {
+  const { candidates, exact } = hostPathCandidates(CONTAINER_WS, { workspaceRoot: WORKSPACE_ROOT });
+  const cleaned = [...new Set(candidates.map((c) => c.replace(/\/+$/, "")).filter((c) => c.length > 0))];
+  cleaned.sort((a, b) => b.length - a.length);
+  return { roots: cleaned, exact: Boolean(exact) };
+}
+
+/** containerPathCandidates()'s own return shape, mirroring hostpath.ts's
+ * HostPathCandidatesResult with `raw` in place of `abs`: there is nothing to
+ * resolve against this container's cwd, the input is already host-absolute
+ * or it is not translatable at all. `raw` is `unknown` rather than `string`
+ * because this module's whole job is judging host-side input that may not
+ * even be a path string -- see the non-absolute-input branch below. */
+export interface ContainerPathCandidatesResult {
+  raw: unknown;
+  candidates: string[];
+  exact?: boolean;
+  reason?: string;
+}
+
+/**
+ * Candidate CONTAINER paths for a HOST-side path string, best first.
+ * Returns `{ raw, candidates, exact?, reason? }` -- the sibling's own shape
+ * (`raw` in place of `abs`: there is nothing to resolve against this
+ * container's cwd, the input is already host-absolute or it is not
+ * translatable at all).
+ *
+ * STATED RESIDUAL, matching hostpath.ts's own for its direction: a
+ * non-absolute string is left alone, never guessed at -- indistinguishable
+ * from a non-path value without guessing, and guessing would be a worse
+ * failure than leaving it untranslated.
+ */
+export function containerPathCandidates(hostish: unknown): ContainerPathCandidatesResult {
+  if (typeof hostish !== "string" || !hostish.startsWith("/")) {
+    return {
+      raw: hostish,
+      candidates: [],
+      reason:
+        "not an absolute host-style path -- relative strings are deliberately untouched " +
+        "(mirrors hostpath.ts's own stated residual for its own direction).",
+    };
+  }
+  const { roots, exact } = hostRootCandidates();
+  const candidates: string[] = [];
+  for (const root of roots) {
+    if (hostish === root || hostish.startsWith(`${root}/`)) {
+      const tail = hostish.slice(root.length);
+      candidates.push(resolve(`${CONTAINER_WS}${tail}`));
+    }
+  }
+  const deduped = [...new Set(candidates)];
+  if (!deduped.length) {
+    return {
+      raw: hostish,
+      candidates: [],
+      reason: `${hostish} does not match any known host root -- translation is impossible, not merely unknown.`,
+    };
+  }
+  return exact ? { raw: hostish, candidates: deduped, exact: true } : { raw: hostish, candidates: deduped };
+}
+
+/** The single best container path, or throw with the reason plus the env
+ * hint -- exactly as the sibling's hostPath() does. */
+export function containerPath(hostish: unknown): string {
+  const { candidates, reason, raw } = containerPathCandidates(hostish);
+  if (!candidates.length) {
+    throw new Error(`${reason || `cannot determine a container path for ${String(raw)}`}\n  Or ${SET_ENV_HINT}`);
+  }
+  return candidates[0];
+}
+
+/**
+ * Rewrite a loopback hostname in `urlString` to `alias`, preserving scheme,
+ * port and path. Byte-identical passthrough for anything else: a
+ * non-loopback host is NEVER re-pointed (D-4 -- a bad grant must never be
+ * able to aim a session at an arbitrary endpoint just because it happened to
+ * hand back some other hostname), and a string that does not parse as a URL
+ * at all is returned exactly as given.
+ */
+export function containerHost(urlString: string, alias: string): string {
+  let url: URL;
+  try {
+    url = new URL(urlString);
+  } catch {
+    return urlString;
+  }
+  if (!isLoopbackHostname(url.hostname)) {
+    return urlString;
+  }
+  url.hostname = alias;
+  return url.toString();
+}
+
+/** containerizeRecord()'s options -- the FIELD LIST is supplied by the
+ * caller deliberately (D-7), so `pathFields`/`urlFields` default to empty
+ * arrays. `alias` is required: every real caller (vice-proxy.mjs's
+ * containerizeGrant()) and every test in this suite always supplies one, so
+ * typing it as mandatory here costs nothing in practice (the same
+ * cost-free-tightening call Plan 03 made for install-resources.ts's
+ * resourcesStatus() -- see that plan's SUMMARY). */
+export interface ContainerizeRecordOptions {
+  pathFields?: string[];
+  urlFields?: string[];
+  alias: string;
+}
+
+/** One field actually rewritten by containerizeRecord(). */
+export interface ContainerizeRecordChange {
+  field: string;
+  from: unknown;
+  to: unknown;
+}
+
+/** One field left alone by containerizeRecord(), with the reason why. */
+export interface ContainerizeRecordUntranslated {
+  field: string;
+  value: unknown;
+  reason: string;
+}
+
+/** containerizeRecord()'s return shape: a NEW record (the input is never
+ * mutated), plus the changed and untranslated field lists. */
+export interface ContainerizeRecordResult {
+  record: Record<string, unknown>;
+  changes: ContainerizeRecordChange[];
+  untranslated: ContainerizeRecordUntranslated[];
+}
+
+/**
+ * Pure, never-throwing translation of a host-written record: `pathFields`
+ * go through containerPath(), `urlFields` through containerHost() with
+ * `alias`. Returns a NEW record -- the input is never mutated -- plus
+ * `changes` (`{ field, from, to }`, one per field actually rewritten) and
+ * `untranslated` (`{ field, value, reason }`, one per field left alone
+ * because it was already container-shaped, matched no known host root, or
+ * wasn't a loopback host / parseable URL). Absent and non-string fields are
+ * silently skipped -- never a throw, never reported either way.
+ *
+ * The FIELD LIST is supplied by the caller deliberately (D-7): which fields
+ * a grant record carries is broker-specific knowledge, and keeping it out of
+ * this module is what keeps this a generic host<->container primitive
+ * rather than a broker-protocol module wearing a generic name.
+ */
+export function containerizeRecord(
+  record: Record<string, unknown> | undefined,
+  { pathFields = [], urlFields = [], alias }: ContainerizeRecordOptions
+): ContainerizeRecordResult {
+  const out: Record<string, unknown> = { ...(record || {}) };
+  const changes: ContainerizeRecordChange[] = [];
+  const untranslated: ContainerizeRecordUntranslated[] = [];
+
+  for (const field of pathFields) {
+    const value = record ? record[field] : undefined;
+    if (typeof value !== "string") continue; // absent/non-string -- skip silently
+    let translated: string;
+    try {
+      translated = containerPath(value);
+    } catch (e) {
+      untranslated.push({ field, value, reason: (e as Error).message });
+      continue;
+    }
+    out[field] = translated;
+    if (translated !== value) {
+      changes.push({ field, from: value, to: translated });
+    } else {
+      untranslated.push({ field, value, reason: "already container-shaped -- no translation needed" });
+    }
+  }
+
+  for (const field of urlFields) {
+    const value = record ? record[field] : undefined;
+    if (typeof value !== "string") continue;
+    const translated = containerHost(value, alias);
+    out[field] = translated;
+    if (translated !== value) {
+      changes.push({ field, from: value, to: translated });
+    } else {
+      untranslated.push({ field, value, reason: "not a loopback host, or not a parseable URL -- left unchanged" });
+    }
+  }
+
+  return { record: out, changes, untranslated };
+}
+
+// -------------------------------------------------------------------- CLI
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  if (argv.includes("--help") || argv.includes("-h") || argv.length === 0) {
+    console.log(`usage: node containerpath.ts <host-path...>
+
+Print the container-side path(s) for host filesystem paths handed back by a
+host-side process (e.g. the on-demand VICE broker's grant records), best
+first, one per line -- the inverse of hostpath.ts.
+
+env: CONTAINER_WORKSPACE_PATH   container-side workspace root (default ${CONTAINER_WS})`);
+    process.exit(argv.length === 0 ? 1 : 0);
+  }
+  try {
+    for (const p of argv) {
+      const { candidates, reason, raw } = containerPathCandidates(p);
+      if (!candidates.length) throw new Error(reason || `cannot determine a container path for ${String(raw)}`);
+      for (const c of candidates) console.log(c);
+    }
+  } catch (e) {
+    console.error(`error: ${(e as Error).message}`);
+    process.exit(1);
+  }
+}

package/hostpath.ts

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+// Build a path that something OUTSIDE this devcontainer can use to reach a file
+// INSIDE the workspace.
+//
+// The problem this solves is generic. Anything running on the host -- an MCP
+// server, a GUI app, a viewer, a debugger, a browser -- resolves paths on the
+// host filesystem, so a container path like /workspaces/foo/bar.d64 means
+// nothing to it and the call fails on a file it cannot find. The workspace is a
+// bind mount, though: the same bytes exist on the host under a different prefix,
+// so the container path only needs its prefix translated.
+//
+// The prefix is never hardcoded -- always discovered at runtime, so this is
+// portable across machines and users. Two mechanisms, best first:
+//
+//   1. HOST_WORKSPACE_PATH, exported from devcontainer.json as
+//        "containerEnv": { "HOST_WORKSPACE_PATH": "${localWorkspaceFolder}" }
+//      Exact, no guessing, resolved per-machine by the devcontainer CLI. Needs a
+//      container rebuild to take effect.
+//
+//   2. Fallback: /proc/self/mountinfo, which leaks the bind-mount source and so
+//      works with no rebuild. Its 4th field is the path *within the source
+//      device*:
+//        <path-within-device> <container-mountpoint> rw,... - ext4 /dev/<device>
+//      That is not yet a host path -- the device is itself mounted somewhere on
+//      the host, which mountinfo cannot reveal. So we emit one candidate per
+//      plausible device mountpoint and let the consumer adjudicate: a wrong path
+//      fails fast and unambiguously. Heuristic by nature, hence the nudge
+//      towards mechanism 1.
+//
+// Node >= 18. No dependencies, no network, nothing machine-specific: copy this
+// file into any devcontainer-based project's .claude/mcp/vice/ and it works.
+//
+// HOSTING CHOICE (01.6.1-02, Criterion B / RESEARCH §3.4 Option B): this
+// module takes the workspace root as an ARGUMENT (an optional `workspaceRoot`
+// on every exported function's options object) and imports NOTHING from
+// repo-root.ts. It used to import { repoRoot } and call it at its own top
+// level -- exactly the shape repo-root.ts's own header (and
+// install-resources.ts's) warns against: repo-root.ts imports
+// install-resources.ts, which imports this module, which imported
+// repo-root.ts back -- a three-module cycle. This module evaluating that
+// top-level call while repo-root.ts's own `HERE` is still in its temporal
+// dead zone is exactly the "Cannot access 'HERE' before initialization"
+// crash 01.6-RESEARCH.md §E and 01.6.1-RESEARCH.md §3.2 both reproduced live.
+//
+// THE CYCLE IS AVOIDED STRUCTURALLY: do not "clean this up" by re-adding
+// `import { repoRoot } from "./repo-root.mjs"` here -- that importable
+// convenience is exactly the cycle described above. Every caller that has a
+// root in scope threads it through the `workspaceRoot` option instead; when
+// none is supplied this module falls back to `CONTAINER_WORKSPACE_PATH`
+// alone and throws a named error if even that is absent -- loud failure over
+// a silently wrong host path (see resolveWorkspaceRoot() below).
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve, relative, isAbsolute } from "node:path";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** Options threaded through every exported function below: the caller's
+ * workspace root, resolved lazily and only when actually needed (see
+ * resolveWorkspaceRoot()). This is the shape Task 1 of 01.6.1-02 added --
+ * see this file's own header for why it exists instead of an import from
+ * repo-root.ts. */
+export interface HostpathOptions {
+  workspaceRoot?: string;
+}
+
+/** The mount backing a container path, per /proc/self/mountinfo -- returned
+ * by mountFor() below. */
+export interface MountInfo {
+  root: string;
+  mountPoint: string;
+  fstype: string;
+}
+
+/** hostPathCandidates()'s own return shape: `abs` is the resolved container
+ * path, `candidates` the ordered list of host-path guesses (best first,
+ * possibly empty), `exact` true only when the single candidate came from
+ * HOST_WORKSPACE_PATH and needs no adjudication, `mount` the backing mount
+ * when one was found, `reason` set only when `candidates` is empty. */
+export interface HostPathCandidatesResult {
+  abs: string;
+  candidates: string[];
+  exact?: boolean;
+  mount?: MountInfo;
+  reason?: string;
+}
+
+/** Resolve the workspace root for a single call: the caller-supplied
+ * `workspaceRoot`, else `CONTAINER_WORKSPACE_PATH`, else a loud, named
+ * throw -- never a silent guess. Called LAZILY, only from inside the one
+ * branch that actually needs the value (the HOST_WORKSPACE_PATH-relative
+ * branch of hostPathCandidates(), and describe()'s own `if (explicit)`
+ * branch) so an environment with neither input, where the mountinfo
+ * fallback works fine today, keeps working fine -- calling this eagerly at
+ * function entry would turn that today-safe path into a throw, a behaviour
+ * regression disguised as a tightening. */
+function resolveWorkspaceRoot(workspaceRoot?: string): string {
+  if (workspaceRoot) return workspaceRoot;
+  const cwp = process.env.CONTAINER_WORKSPACE_PATH;
+  if (cwp) return cwp;
+  throw new Error(
+    "hostpath: cannot resolve the workspace root -- no `workspaceRoot` option was supplied and " +
+      "CONTAINER_WORKSPACE_PATH is not set in the environment. Supply one of the two."
+  );
+}
+
+// Where a bind-mount source device is *itself* mounted on the host. Ordered by
+// how often each turns out to be right; "" covers a source path that is already
+// absolute on the host.
+const DEVICE_MOUNT_GUESSES = ["/home", "", "/Users", "/mnt", "/media", "/host"];
+
+// Filesystems that exist only inside the container: a path on one of these has
+// no host-side counterpart at all, so translation is impossible rather than
+// merely unknown -- and saying so beats emitting six wrong candidates.
+const CONTAINER_ONLY_FS = new Set([
+  "overlay", "tmpfs", "proc", "sysfs", "devtmpfs", "devpts", "cgroup", "cgroup2",
+  "mqueue", "squashfs", "ramfs",
+]);
+
+export const SET_ENV_HINT =
+  'set the mapping explicitly in .devcontainer/devcontainer.json and rebuild:\n' +
+  '    "containerEnv": { "HOST_WORKSPACE_PATH": "${localWorkspaceFolder}" }';
+
+/**
+ * The mount backing `containerPath`, per /proc/self/mountinfo: the longest
+ * matching mountpoint, its path within the source device, and its fstype.
+ */
+export function mountFor(containerPath: string): MountInfo | null {
+  let info: string;
+  try {
+    info = readFileSync("/proc/self/mountinfo", "utf8");
+  } catch {
+    return null;
+  }
+  let best: MountInfo | null = null;
+  for (const line of info.split("\n")) {
+    // <id> <parent> <maj:min> <root> <mountpoint> <opts> ... - <fstype> <source> ...
+    const [pre, post] = line.split(" - ");
+    if (!post) continue;
+    const f = pre.split(" ");
+    if (f.length < 5) continue;
+    const [, , , root, mountPoint] = f;
+    const fstype = post.split(" ")[0];
+    if (containerPath === mountPoint || containerPath.startsWith(mountPoint.replace(/\/?$/, "/"))) {
+      if (!best || mountPoint.length > best.mountPoint.length) best = { root, mountPoint, fstype };
+    }
+  }
+  return best;
+}
+
+/**
+ * Candidate host paths for a container path, best first.
+ *
+ * Returns { abs, candidates, exact?, mount?, reason? }. `exact` means the single
+ * candidate came from HOST_WORKSPACE_PATH and needs no adjudication; `reason`
+ * explains an empty candidate list.
+ *
+ * Deliberately not tied to any repo, workspace layout or file type: translation
+ * is driven by whichever bind mount happens to back the path, so any shared
+ * location works.
+ *
+ * `opts.workspaceRoot`, if supplied, is used ahead of CONTAINER_WORKSPACE_PATH
+ * -- see resolveWorkspaceRoot() above. Resolved lazily, only inside this
+ * branch: the mountinfo fallback below needs no workspace root at all and
+ * must keep working when neither input is available.
+ */
+export function hostPathCandidates(
+  containerPath: string,
+  { workspaceRoot }: HostpathOptions = {}
+): HostPathCandidatesResult {
+  const abs = isAbsolute(containerPath) ? containerPath : resolve(process.cwd(), containerPath);
+
+  // 1. Explicit workspace mapping, when the path falls inside the workspace.
+  const hostWs = process.env.HOST_WORKSPACE_PATH;
+  if (hostWs) {
+    const containerWs = resolveWorkspaceRoot(workspaceRoot);
+    const rel = relative(containerWs, abs);
+    if (!rel.startsWith("..")) {
+      return { abs, candidates: [`${hostWs.replace(/\/$/, "")}/${rel}`], exact: true };
+    }
+    // Outside the workspace: fall through to the generic mount-based path rather
+    // than refusing -- the file may still be shared by some other mount.
+  }
+
+  // 2. Generic: derive from whichever mount backs this specific path.
+  const m = mountFor(abs);
+  if (!m) return { abs, candidates: [], reason: "could not read /proc/self/mountinfo" };
+  if (CONTAINER_ONLY_FS.has(m.fstype)) {
+    return {
+      abs,
+      candidates: [],
+      reason:
+        `${abs} lives on a container-only filesystem (${m.fstype} at ${m.mountPoint}), ` +
+        "so nothing outside the container can see it under any path. Move or copy it " +
+        "into a directory that is bind-mounted from the host.",
+    };
+  }
+  const tail = relative(m.mountPoint, abs);
+  const rootForPath = tail ? `${m.root.replace(/\/$/, "")}/${tail}` : m.root;
+  return {
+    abs,
+    candidates: [...new Set(DEVICE_MOUNT_GUESSES.map((p) => `${p}${rootForPath}`))],
+    mount: m,
+  };
+}
+
+/** The single best host path, or throw with the reason it cannot be built. */
+export function hostPath(containerPath: string, opts: HostpathOptions = {}): string {
+  const { abs, candidates, reason } = hostPathCandidates(containerPath, opts);
+  if (!candidates.length) {
+    throw new Error(`${reason || `cannot determine a host path for ${abs}`}\n  Or ${SET_ENV_HINT}`);
+  }
+  return candidates[0];
+}
+
+/** Printed once when a mapping is guessed, since a guess can silently misfire. */
+export function guessNote(): string {
+  return (
+    "note: HOST_WORKSPACE_PATH is unset, so the host path is being guessed from\n" +
+    "      /proc/self/mountinfo. For an exact, portable mapping, " +
+    SET_ENV_HINT.replace(/\n/g, "\n  ") +
+    "\n"
+  );
+}
+
+/**
+ * Run `fn(hostPath)` against each candidate until one succeeds, letting the
+ * consumer -- which is the only thing that can actually resolve a host path --
+ * adjudicate. Returns { result, hostPath }.
+ *
+ * `fatal(err)` marks an error as "not a wrong-path signal" (a connection
+ * failure, say), so probing stops instead of retrying five more times.
+ * `workspaceRoot`, alongside `fatal`, threads straight through to
+ * hostPathCandidates() -- see resolveWorkspaceRoot() above.
+ */
+export async function tryHostPaths<T>(
+  containerPath: string,
+  fn: (hostPath: string) => T | Promise<T>,
+  { fatal, workspaceRoot }: { fatal?: (e: unknown) => boolean; workspaceRoot?: string } = {}
+): Promise<{ result: T; hostPath: string }> {
+  const { abs, candidates, reason, exact } = hostPathCandidates(containerPath, { workspaceRoot });
+  if (!candidates.length) {
+    throw new Error(`${reason || `cannot determine a host path for ${abs}`}\n  Or ${SET_ENV_HINT}`);
+  }
+  if (!exact) process.stderr.write(guessNote());
+  const errors: string[] = [];
+  for (const p of candidates) {
+    try {
+      return { result: await fn(p), hostPath: p };
+    } catch (e) {
+      errors.push(`  ${p}\n    -> ${(e as Error).message}`);
+      if (fatal?.(e)) throw e;
+    }
+  }
+  throw new Error(
+    `no candidate host path worked for ${abs}:\n${errors.join("\n")}\n  ${SET_ENV_HINT}`
+  );
+}
+
+/** Human-readable report: the mapping, and how it was arrived at.
+ * `opts.workspaceRoot`, resolved lazily inside the `if (explicit)` branch
+ * below (same laziness rule as hostPathCandidates() itself), threads through
+ * to that same call. */
+export function describe(
+  paths: string[],
+  log: (message: string) => void = console.log,
+  { workspaceRoot }: HostpathOptions = {}
+): void {
+  const explicit = process.env.HOST_WORKSPACE_PATH;
+  log(`HOST_WORKSPACE_PATH: ${explicit || "(unset — falling back to /proc/self/mountinfo)"}`);
+  if (explicit) log(`maps container path: ${resolveWorkspaceRoot(workspaceRoot)}`);
+  for (const p of paths.length ? paths : [process.cwd()]) {
+    const { abs, candidates, reason, mount, exact } = hostPathCandidates(p, { workspaceRoot });
+    log(`\n${abs}`);
+    if (mount) log(`  backed by: ${mount.fstype} mount at ${mount.mountPoint} (source ${mount.root})`);
+    if (reason) log(`  UNRESOLVABLE: ${reason}`);
+    for (const [i, c] of candidates.entries()) {
+      log(`  ${i === 0 ? "->" : "  "} ${c}${exact ? "  (exact, from env)" : ""}`);
+    }
+  }
+}
+
+// -------------------------------------------------------------------------- CLI
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  const plain = argv.includes("--plain");
+  const paths = argv.filter((a) => !a.startsWith("--"));
+  if (argv.includes("--help") || argv.includes("-h")) {
+    console.log(`usage: node hostpath.ts [--plain] <path...>
+
+Print the host path(s) for files inside this workspace, for handing to anything
+running outside the container.
+
+  (default)   report the mapping and how it was derived
+  --plain     print candidate host paths only, best first, one per line
+
+env: HOST_WORKSPACE_PATH   host location of the workspace (exact mapping)
+     CONTAINER_WORKSPACE_PATH   container location it maps to (read at call time; no default is computed here)`);
+    process.exit(0);
+  }
+  try {
+    if (plain) {
+      for (const p of paths.length ? paths : [process.cwd()]) {
+        const { candidates, reason, abs, exact } = hostPathCandidates(p);
+        if (!candidates.length) throw new Error(reason || `cannot determine a host path for ${abs}`);
+        if (!exact) process.stderr.write(guessNote());
+        for (const c of candidates) console.log(c);
+      }
+    } else {
+      describe(paths);
+    }
+  } catch (e) {
+    console.error(`error: ${(e as Error).message}`);
+    process.exit(1);
+  }
+}