harnery 0.40.0 → 0.42.0

package/src/commands/checkpoint.ts

@@ -1,6 +1,6 @@
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
-import type { Adapter } from "../core/adapter.ts";
+import { ADAPTERS, type Adapter, normalizeAdapter } from "../core/adapter.ts";
 import { monorepoRoot, resolveOwner } from "../core/agents/index.ts";
 import { readLiveCoordinationRow } from "../core/agents/state/live-coordination-view.ts";
 import {
@@ -76,7 +76,7 @@ export function registerCheckpointCommand(
     .description("Create a durable context-continuity capsule for the current work")
     .option("--session <id>", "Session id (defaults to the current agent heartbeat)")
     .option("--instance <id>", "Agent instance id (defaults to the current owner)")
-    .option("--adapter <id>", "claude-code, codex, or cursor (inferred from heartbeat)")
+    .option("--adapter <id>", `${ADAPTERS.join(", ")} (inferred from heartbeat)`)
     .option("--reason <reason>", "manual, pressure, pre_compact, or session_end", "manual")
     .option("--note <text>", "Short continuation note for the recovered agent")
     .option("--json", "Structured JSON output")
@@ -94,7 +94,7 @@ export function registerCheckpointCommand(
           const reason = parseCheckpointReason(opts.reason);
           const identity = resolveContinuityIdentity(context, opts);
           if (!identity.adapter) {
-            throw new Error("could not infer the adapter; pass --adapter claude-code|codex|cursor");
+            throw new Error(`could not infer the adapter; pass --adapter ${ADAPTERS.join("|")}`);
           }
           const result = checkpointContext(identity.coordRoot, {
             sessionId: identity.sessionId,
@@ -166,15 +166,13 @@ function resolveContinuityIdentity(
 }
 
 function adapterFromPlatform(platform: string | undefined): Adapter | null {
-  if (platform === "claude-code") return "claude-code";
-  if (platform === "cursor") return "cursor";
-  if (platform === "codex") return "codex";
-  return null;
+  return normalizeAdapter(platform);
 }
 
 function parseAdapter(value: string): Adapter {
-  if (value === "claude-code" || value === "codex" || value === "cursor") return value;
-  throw new Error(`invalid adapter "${value}"; expected claude-code, codex, or cursor`);
+  const adapter = normalizeAdapter(value);
+  if (adapter) return adapter;
+  throw new Error(`invalid adapter "${value}"; expected one of ${ADAPTERS.join(", ")}`);
 }
 
 function parseCheckpointReason(value: string): CheckpointReason {

package/src/commands/claude-desktop.ts

@@ -8,6 +8,13 @@ import {
   planMirror,
   readCliAccount,
 } from "../lib/claude-desktop.ts";
+import {
+  applyShare,
+  defaultShareDir,
+  planShare,
+  shareSummary,
+} from "../lib/claude-desktop-share.ts";
+import { resolveMachineLabel } from "../lib/machine.ts";
 
 /**
  * `claude-desktop`: make Claude desktop-app sessions survive account
@@ -186,6 +193,60 @@ export function registerClaudeDesktopCommand(
         }
       },
     );
+
+  cmd
+    .command("share")
+    .description(
+      "Share sessions with your other computers through a synced folder (iCloud Drive by default): " +
+        "publish this machine's recent sessions and list + resume every other machine's here. " +
+        "Dry-run by default; --yes applies. Restart the desktop app afterward to see new entries.",
+    )
+    .option("--dir <path>", "Shared folder (default: iCloud Drive/Harnery/claude-sessions)")
+    .option("--days <n>", "Only sessions active in the last N days", "14")
+    .option("--data-dir <path>", "Explicit desktop-app data directory")
+    .option("--yes", "Apply the plan (default is dry-run)")
+    .action((opts: { dir?: string; days: string; dataDir?: string; yes?: boolean }) => {
+      const shareDir = opts.dir ?? process.env.HARNERY_SESSION_SHARE_DIR ?? defaultShareDir();
+      if (!shareDir) {
+        emit.error({
+          code: "no_share_dir",
+          message: "no shared folder: pass --dir <path> or set HARNERY_SESSION_SHARE_DIR",
+        });
+        process.exit(2);
+      }
+      const cli = readCliAccount();
+      if (!cli) {
+        emit.error({
+          code: "no_account",
+          message: "cannot read the signed-in account from ~/.claude.json",
+        });
+        process.exit(2);
+      }
+      const [dataDir] = requireDataDirs(emit, opts.dataDir);
+      const shareOpts = {
+        shareDir,
+        machine: resolveMachineLabel(),
+        days: Number(opts.days) || 14,
+        dataDir: dataDir as string,
+        targetAccountUuid: cli.accountUuid,
+      };
+      const plan = planShare(shareOpts);
+      const summary = { share_dir: shareDir, machine: shareOpts.machine, ...shareSummary(plan) };
+      if (!opts.yes) {
+        emit.data({ dry_run: true, ...summary, hint: "re-run with --yes to apply" });
+        return;
+      }
+      const result = applyShare(plan, shareOpts);
+      emit.data({
+        dry_run: false,
+        ...summary,
+        ...result,
+        hint:
+          result.imported > 0
+            ? "quit the Claude desktop app fully (Cmd+Q) and reopen it to see the new sessions"
+            : "sidebar already current",
+      });
+    });
 }
 
 function collect(value: string, previous: string[]): string[] {

package/src/commands/deinit.ts

@@ -4,7 +4,7 @@
  * `init` makes two kinds of change outside the harnery package:
  *   1. Merges `agent-hook` entries into the adapter settings file
  *      (Claude Code `.claude/settings.json`, Cursor `.cursor/hooks.json`, or
- *      Codex `.codex/hooks.json`).
+ *      Codex `.codex/hooks.json`), or installs the OpenCode plugin directory.
  *   2. Creates the `.harnery/` coord root (runtime state: events, councils,
  *      identities, journal) and stamps the host bin name into
  *      `.harnery/config.jsonc`.
@@ -34,6 +34,7 @@ import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
 import { DEFAULT_BIN_NAME } from "../core/config.ts";
 import { ADAPTER_SPECS, type AdapterId } from "../core/hooks/adapter/events.ts";
+import { removeOpenCodePlugin } from "../core/hooks/adapter/opencode-plugin.ts";
 import type { SettingsFile } from "../core/hooks/adapter/wiring.ts";
 import { removeIndexerExclusions } from "../lib/indexer-exclusions.ts";
 import { removeInstructions } from "../lib/instructions/apply.ts";
@@ -62,7 +63,7 @@ export function registerDeinitCommand(program: Command, emit: EmitContext, binNa
         ".harnery/ coord root (on a terminal it asks first). Idempotent; use " +
         "--dry-run to preview.",
     )
-    .option("--adapter <id>", "claude-code | cursor | codex", "claude-code")
+    .option("--adapter <id>", "claude-code | cursor | codex | opencode", "claude-code")
     .option("--dry-run", "Show what would change without writing")
     .option("--project-root <path>", "Project root (default: git toplevel, else cwd)")
     .option("--purge-state", "Also delete the .harnery/ coord root (runtime state, destructive)")
@@ -70,7 +71,9 @@ export function registerDeinitCommand(program: Command, emit: EmitContext, binNa
       const adapter = opts.adapter as AdapterId;
       const spec = ADAPTER_SPECS[adapter];
       if (!spec) {
-        emit.text(`Unknown adapter '${opts.adapter}'. Expected: claude-code | cursor | codex.`);
+        emit.text(
+          `Unknown adapter '${opts.adapter}'. Expected: claude-code | cursor | codex | opencode.`,
+        );
         emit.setExitCode(1);
         return;
       }
@@ -97,7 +100,9 @@ export function registerDeinitCommand(program: Command, emit: EmitContext, binNa
 
       // ── 1. unwire adapter hooks ────────────────────────────────────────────
       const settingsPath = resolve(projectRoot, spec.settingsFile);
-      if (!existsSync(settingsPath)) {
+      if (spec.installMode === "opencode-plugin") {
+        actions.push(...removeOpenCodePlugin(projectRoot, dryRun));
+      } else if (!existsSync(settingsPath)) {
         actions.push(`· ${rel(projectRoot, settingsPath)} doesn't exist; no hooks to remove`);
       } else {
         let settings: SettingsFile;

package/src/commands/disk.ts

@@ -0,0 +1,114 @@
+import { type Command, InvalidArgumentError } from "commander";
+import type { EmitContext } from "../commander.ts";
+import {
+  type DiskGroup,
+  type DiskOptions,
+  type DiskReport,
+  diskUsage,
+  parseDiskSize,
+} from "../lib/disk-usage.ts";
+
+function positive(value: string): number {
+  if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < 1)
+    throw new InvalidArgumentError("requires a positive integer");
+  return Number(value);
+}
+
+export function registerDiskCommand(program: Command, emit: EmitContext): void {
+  program
+    .command("disk [path]")
+    .description("Measure checkout disk usage, including nested repositories and ignored files")
+    .option(
+      "--git <states>",
+      "Filter: tracked, untracked, ignored, git-metadata, non-repository, unknown (comma-separated)",
+    )
+    .option(
+      "--type <types>",
+      "File extensions or video, audio, image, media, archive (comma-separated)",
+    )
+    .option(
+      "--exclude <paths>",
+      "Skip directory names at any depth or root-relative paths; repeatable, comma-separated",
+      (value: string, previous: string[]) => [...previous, value],
+      [],
+    )
+    .option("--group <by>", "Group by directory, repository, extension, git, or files", "directory")
+    .option("--depth <n>", "Directory grouping depth; does not limit the scan", positive, 1)
+    .option("--top <n>", "Maximum groups and largest files to display", positive, 20)
+    .option(
+      "--min-size <size>",
+      "Include individual files at least this size (e.g. 10MB, 1GiB)",
+      parseDiskSize,
+    )
+    .option("--apparent", "Rank and filter by file lengths instead of allocated blocks")
+    .option("--json", "Emit the versioned disk usage report")
+    .action(
+      (path: string | undefined, options: DiskOptions & { group: DiskGroup; json?: boolean }) => {
+        try {
+          const { json, ...filters } = options;
+          const report = diskUsage(path, filters);
+          if (json) {
+            emit.config({ format: "json" });
+            emit.data(report);
+          } else emit.text(renderDiskUsage(report));
+          if (!report.complete) emit.setExitCode(1);
+        } catch (error) {
+          emit.error({
+            code: "disk_usage_failed",
+            message: error instanceof Error ? error.message : String(error),
+          });
+          emit.setExitCode(1);
+        }
+      },
+    );
+}
+
+export function renderDiskUsage(report: DiskReport): string {
+  const bytes = (value: number): string =>
+    value >= 1e9
+      ? `${(value / 1e9).toFixed(2)} GB`
+      : value >= 1e6
+        ? `${(value / 1e6).toFixed(2)} MB`
+        : value >= 1e3
+          ? `${(value / 1e3).toFixed(2)} KB`
+          : `${value} B`;
+  const size = (row: { allocated_bytes: number | null; apparent_bytes: number }): string =>
+    bytes(
+      report.measurement === "allocated"
+        ? (row.allocated_bytes ?? row.apparent_bytes)
+        : row.apparent_bytes,
+    );
+  const lines = [
+    `Disk usage: ${report.root}`,
+    `${size(report.totals)} in ${report.totals.files.toLocaleString()} regular files (${report.measurement})`,
+    `File lengths: ${bytes(report.totals.apparent_bytes)}. Directory metadata and symlinks are excluded.`,
+    "",
+    "Git state:",
+  ];
+  for (const [state, totals] of Object.entries(report.git))
+    if (totals.files)
+      lines.push(
+        `${size(totals).padStart(12)}  ${String(totals.files).padStart(8)} files  ${state}`,
+      );
+  lines.push(
+    "",
+    `Largest ${report.filters.group} groups (${report.groups.length} of ${report.group_count}):`,
+  );
+  for (const row of report.groups)
+    lines.push(`${size(row).padStart(12)}  ${String(row.files).padStart(8)} files  ${row.path}`);
+  if (report.filters.group !== "files") {
+    lines.push("", "Largest files:");
+    for (const row of report.largest_files)
+      lines.push(`${size(row).padStart(12)}  ${row.git.padEnd(14)}  ${row.path}`);
+  }
+  if (report.skipped.symlinks || report.skipped.special_files || report.skipped.excluded)
+    lines.push(
+      "",
+      `Skipped: ${report.skipped.symlinks} symlinks, ${report.skipped.special_files} special files, ${report.skipped.excluded} excluded entries.`,
+    );
+  if (report.issues.length) {
+    lines.push("", "Incomplete scan:");
+    for (const issue of report.issues) lines.push(`${issue.path}: ${issue.message}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/docs.ts

@@ -6,6 +6,7 @@ import { initDocsContext as initDocsLinks, runLinks } from "../lib/docs-links.ts
 import { initDocsContext as initDocsLint, runLint } from "../lib/docs-lint.ts";
 import { readDocsMetadata, readDocsMetadataKey } from "../lib/docs-meta.ts";
 import { initDocsMetadataAuditContext, runDocsMetadataAudit } from "../lib/docs-metadata-audit.ts";
+import { initDocsMetadataExclusions } from "../lib/docs-metadata-managed.ts";
 import { initDocsMetadataSyncContext, runDocsMetadataSync } from "../lib/docs-metadata-sync.ts";
 import { createDocsFile } from "../lib/docs-new.ts";
 import {
@@ -27,6 +28,7 @@ function ensureContext(context: HarneryProgramContext | undefined): void {
     docsRootAllowlist: context.docsRootAllowlist,
   });
   initDocsLinks({ ...opts, extraExcludedPrefixes: context.extraDocsExcludedPrefixes });
+  initDocsMetadataExclusions(context.extraDocsExcludedPrefixes);
   initDocsMetadataAuditContext(opts);
   initDocsMetadataSyncContext(opts);
   initDocsSweep(opts);

package/src/commands/doctor.ts

@@ -18,7 +18,7 @@ import path from "node:path";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
 import { BUILTIN_ADAPTER_IDS } from "../core/adapters/index.ts";
-import { resolveBinName, ripgrepAutoInstall } from "../core/config.ts";
+import { codexWindowsBridgeConfig, resolveBinName, ripgrepAutoInstall } from "../core/config.ts";
 import {
   countSummarizedSinceV3,
   listDiagnosticSummariesV3,
@@ -33,6 +33,7 @@ import {
   type CodexWslBridgeStatus,
   inspectCodexWslBridge,
 } from "../core/hooks/codex-wsl-bridge.ts";
+import { findUnfinishedHookRuns } from "../core/hooks/run-markers.ts";
 import {
   ADAPTER_BINARIES,
   ADAPTER_INSTALL_HINTS,
@@ -115,6 +116,8 @@ export async function runChecks(): Promise<Check[]> {
   const codexWslStatus = inspectCodexWslBridge();
   const recentCodexMidFlightCount = root ? countRecentCodexMidFlightOnboardings(root) : 0;
   const codexWslBridge = codexWslBridgeCheck(codexWslStatus, recentCodexMidFlightCount);
+  const codexHookRuns = codexHookRunsCheck(root);
+  const codexWindowsRoute = codexWindowsBridgeCheck(root);
   // Probe the adapter CLIs before the hook check runs, not in output order:
   // an unwired adapter only matters if its CLI is actually installed, and
   // probing once here keeps that join to one spawn per CLI.
@@ -131,6 +134,8 @@ export async function runChecks(): Promise<Check[]> {
     ...(codexAuthorization ? [codexAuthorization] : []),
     checkGitHookRegions(),
     ...(codexWslBridge ? [codexWslBridge] : []),
+    ...(codexWindowsRoute ? [codexWindowsRoute] : []),
+    ...(codexHookRuns ? [codexHookRuns] : []),
     ...workflow.map((w) => w.check),
     checkRestic(),
     checkRclone(),
@@ -189,6 +194,52 @@ export function codexWslBridgeCheck(
   };
 }
 
+/**
+ * Hook runs that started but never finished (ADR 0197). Codex kills a hook at
+ * its timeout and the tool proceeds without that hook's checks; the start
+ * marker is the only trace such a run leaves.
+ */
+export function codexHookRunsCheck(
+  coordRoot: string | null,
+  nowMs = Date.now(),
+  isAlive?: (pid: number) => boolean,
+): Check | null {
+  if (!coordRoot) return null;
+  const runs = findUnfinishedHookRuns(coordRoot, nowMs, undefined, isAlive);
+  if (runs.count === 0) return null;
+  const events = runs.events.map((e) => `${e.event} ×${e.count}`).join(", ");
+  return {
+    name: "codex:hook runs",
+    severity: "warn",
+    detail:
+      `${runs.count} hook run${runs.count === 1 ? "" : "s"} started but never finished in the last 24h ` +
+      `(${events}; latest ${runs.latest}); their tools proceeded without those hooks' checks`,
+    hint: "a hook that outlives its timeout is killed; look for a stalled WSL session or a slow hook",
+  };
+}
+
+/** Report the per-project Windows bridge opt-in, or an invalid value init ignored. */
+export function codexWindowsBridgeCheck(coordRoot: string | null): Check | null {
+  if (!coordRoot) return null;
+  const bridge = codexWindowsBridgeConfig(coordRoot);
+  if (bridge.error) {
+    return {
+      name: "codex:Windows hook route",
+      severity: "warn",
+      detail: `${bridge.error}; Codex hooks are wired without commandWindows`,
+      hint: "set hooks.codexWindowsBridge.entryPoint to a plain command name in .harnery/config.jsonc, then re-run init",
+    };
+  }
+  if (!bridge.entryPoint) return null;
+  return {
+    name: "codex:Windows hook route",
+    severity: "ok",
+    detail:
+      `opted in: Windows-native Codex hooks hand off to \`${bridge.entryPoint}\` from WSL paths ` +
+      `when it is on PATH, otherwise run the usual command; bridge health is reported by the bridge itself`,
+  };
+}
+
 const CODEX_MID_FLIGHT_HISTORY_WINDOW_MS = 48 * 60 * 60 * 1000;
 
 /** Count bounded, privacy-safe recovery diagnostics so a healthy environment
@@ -557,13 +608,22 @@ function checkAdapterHooks(installedAdapters: AdapterId[] = []): Check {
     if (d.invalidEventKeys.length > 0) {
       bits.push(`unsupported events (${d.invalidEventKeys.join(", ")})`);
     }
+    if (d.pluginIssues && d.pluginIssues.length > 0) {
+      // Plugin issues already name their file; render them as-is.
+      return d.pluginIssues.join("; ");
+    }
     return `${d.settingsFile}: ${bits.join("; ")}`;
   });
   for (const id of unwired) {
-    parts.push(`${ADAPTER_SPECS[id].settingsFile}: ${id} CLI installed, no harnery hooks wired`);
+    const what = ADAPTER_SPECS[id].installMode === "opencode-plugin" ? "plugin" : "hooks";
+    parts.push(`${ADAPTER_SPECS[id].settingsFile}: ${id} CLI installed, no harnery ${what} wired`);
   }
   const needsManualRepair = drift.some(
-    (d) => d.parseError || d.invalidTopLevelKeys.length > 0 || d.invalidEventKeys.length > 0,
+    (d) =>
+      d.parseError ||
+      d.invalidTopLevelKeys.length > 0 ||
+      d.invalidEventKeys.length > 0 ||
+      d.pluginIssues?.some((issue) => issue.includes("without harnery's ownership header")),
   );
   const wireHints = unwired.map((id) => `\`${bin} init --adapter ${id}\``);
   let hint: string;

package/src/commands/fetch.ts

@@ -3,8 +3,10 @@ import { homedir } from "node:os";
 import { resolve } from "node:path";
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+import { resolveUserAgent } from "../lib/browser/user-agent.js";
 import { CookieJar } from "../lib/cookies/index.ts";
 import { fetchWithJar } from "../lib/http/index.ts";
+import { commandPaceGate } from "../lib/pace/index.ts";
 
 /**
  * `harn fetch`: HTTP request with cookie-jar attach + persist.
@@ -23,6 +25,7 @@ interface FetchOpts {
   output?: string;
   store?: string;
   cookies?: boolean;
+  pace?: boolean;
   redirect: string;
   timeout: string;
   status?: boolean;
@@ -47,6 +50,11 @@ export function registerFetchCommand(
     .option("-o, --output <file>", "Write response body to file (default: stdout)")
     .option("--store <path>", `Cookie store path (default ${DEFAULT_STORE})`)
     .option("--no-cookies", "Skip cookie-jar attach + persist")
+    .option(
+      "--no-pace",
+      "Skip the human-pace gap (3 to 9 s) between requests to the same site for this run. " +
+        "HARNERY_PACE=off disables it machine-wide; local and private hosts never wait.",
+    )
     .option("--redirect <mode>", "Redirect handling: follow | error | manual", "follow")
     .option("--timeout <ms>", "Request timeout in milliseconds", "30000")
     .option("--status", "Print status to stderr")
@@ -70,6 +78,10 @@ async function runFetch(
   context: HarneryProgramContext | undefined,
 ): Promise<void> {
   const headers: Record<string, string> = {};
+  {
+    const ua = resolveUserAgent({ env: process.env.HARNERY_BROWSER_UA });
+    if (ua) headers["User-Agent"] = ua;
+  }
   for (const h of opts.header ?? []) {
     const idx = h.indexOf(":");
     if (idx < 0) {
@@ -83,6 +95,8 @@ async function runFetch(
       ? new CookieJar({ path: opts.store ?? DEFAULT_STORE, source: "harn-fetch" })
       : null;
 
+  await commandPaceGate(opts.pace !== false, (message) => emit.log(message, "info"))?.before(url);
+
   const timeoutMs = Number.parseInt(opts.timeout, 10);
   const ac = new AbortController();
   const timer = setTimeout(() => ac.abort(), timeoutMs);

package/src/commands/files.ts

@@ -5,7 +5,21 @@ import type { EmitContext, HarneryProgramContext } from "../commander.ts";
 import { resolveCoordRoot } from "../core/agents/coord-client.ts";
 import { DEFAULT_WEB_PORT, resolveWebPort } from "../core/config.ts";
 import { coordRootId, localCoordRootIdUrl } from "../lib/coord-root-id.ts";
-import { localFilesOriginUrl, localFileViewerUrl } from "../lib/local-file-url.ts";
+import {
+  encodedRepoPath,
+  encodeLinkSafeComponent,
+  FILES_ORIGIN_HOST,
+  localFilesOriginUrl,
+  localFileViewerUrl,
+} from "../lib/local-file-url.ts";
+import { isPathAllowed } from "../lib/tunnel/path-scope.ts";
+import {
+  isTunnelStateLive,
+  listStates,
+  type ProcessAliveCheck,
+  type TunnelState,
+  tunnelTargetPort,
+} from "../lib/tunnel/state.ts";
 
 export { FILES_ORIGIN_HOST } from "../lib/local-file-url.ts";
 
@@ -162,6 +176,72 @@ export function mintLocalFileUrl(input: string, options: LocalFileUrlOptions): L
   return { url, relPath, mode };
 }
 
+export class TunnelLinkError extends Error {
+  constructor(
+    message: string,
+    readonly hint: string,
+  ) {
+    super(message);
+    this.name = "TunnelLinkError";
+  }
+}
+
+function vhostName(vhost: string): string {
+  return vhost.replace(/:\d+$/, "").toLowerCase();
+}
+
+function newestFirst(states: TunnelState[]): TunnelState[] {
+  return [...states].sort((a, b) => b.started_at.localeCompare(a.started_at));
+}
+
+/**
+ * Turn a minted local URL into the same file's URL on a live tunnel.
+ *
+ * HTML needs a tunnel in front of the isolated files origin (its vhost is
+ * FILES_ORIGIN_HOST), because only that origin renders the page and serves its
+ * relative assets; a dashboard tunnel can only show the viewer, which displays
+ * HTML as source. Other files need a dashboard tunnel that serves the viewer.
+ * In both cases the tunnel's path scope must forward the request, or its gate
+ * would refuse the link, so a tunnel that does not cover the file is skipped.
+ */
+export function tunnelFileUrl(
+  local: LocalFileUrl,
+  port: number,
+  states: TunnelState[],
+  processAlive?: ProcessAliveCheck,
+): string {
+  const live = states.filter(
+    (state) => tunnelTargetPort(state) === port && isTunnelStateLive(state, processAlive),
+  );
+  if (local.mode === "raw") {
+    const path = `/${encodedRepoPath(local.relPath)}`;
+    const tunnel = newestFirst(live).find(
+      (state) =>
+        vhostName(state.vhost) === FILES_ORIGIN_HOST && isPathAllowed(path, state.allow_paths),
+    );
+    if (tunnel) return `${tunnel.url.replace(/\/+$/, "")}${path}`;
+    const folder = local.relPath.includes("/")
+      ? `/${local.relPath.slice(0, local.relPath.lastIndexOf("/"))}`
+      : "/";
+    throw new TunnelLinkError(
+      `no live tunnel serves the files origin for /${local.relPath}`,
+      `Start one scoped to the page's folder, for example: tunnel up --name pages --target 127.0.0.1:${port} --vhost ${FILES_ORIGIN_HOST} --allow-path ${folder}`,
+    );
+  }
+  const tunnel = newestFirst(live).find(
+    (state) =>
+      vhostName(state.vhost) !== FILES_ORIGIN_HOST &&
+      ["/files", "/api/file", "/_next"].every((path) => isPathAllowed(path, state.allow_paths)),
+  );
+  if (tunnel) {
+    return `${tunnel.url.replace(/\/+$/, "")}/files?path=${encodeLinkSafeComponent(local.relPath)}`;
+  }
+  throw new TunnelLinkError(
+    `no live tunnel serves the dashboard file viewer on port ${port}`,
+    `Start one, for example: tunnel up --name files --target 127.0.0.1:${port} --allow-path /files --allow-path /api/file --allow-path /_next`,
+  );
+}
+
 export function registerFilesCommand(
   program: Command,
   emit: EmitContext,
@@ -180,6 +260,10 @@ export function registerFilesCommand(
     .option("--raw", "Use the isolated files origin, regardless of extension")
     .option("--viewer", "Use the dashboard file viewer, regardless of extension")
     .option("--no-verify", "Mint without checking the running dashboard's repository identity")
+    .option(
+      "--tunnel",
+      "Print the file's URL on a live tunnel instead of localhost (HTML uses a files-origin tunnel)",
+    )
     .action(
       async (
         filePath: string,
@@ -189,6 +273,7 @@ export function registerFilesCommand(
           raw?: boolean;
           viewer?: boolean;
           verify?: boolean;
+          tunnel?: boolean;
         },
       ) => {
         if (opts.raw && opts.viewer) {
@@ -224,8 +309,14 @@ export function registerFilesCommand(
             mode: opts.raw ? "raw" : opts.viewer ? "viewer" : "auto",
           });
           if (opts.verify !== false) await verifyDashboardRoot(coordRoot, port);
-          emit.text(`${result.url}\n`);
+          const url = opts.tunnel ? tunnelFileUrl(result, port, listStates(coordRoot)) : result.url;
+          emit.text(`${url}\n`);
         } catch (error) {
+          if (error instanceof TunnelLinkError) {
+            emit.error({ code: "no_tunnel_for_file", message: error.message, hint: error.hint });
+            emit.setExitCode(1);
+            return;
+          }
           if (error instanceof DashboardRootError) {
             emit.error({ code: error.code, message: error.message, hint: error.hint });
             emit.setExitCode(1);