harnery 0.6.0 → 0.7.1

package/dist/commands/tunnel.js

@@ -6,17 +6,18 @@ function cachePath(tool, filename) {
 import { spawn, spawnSync } from "node:child_process";
 import { existsSync, openSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { cfdLogFile, clearState, DEFAULT_INSTANCE, ensureCloudflared, gateLogFile, isProcessAlive, listStates, readConfig, readState, writeConfig, writeState, } from "../lib/tunnel/state.js";
+import { clearState, DEFAULT_INSTANCE, ensureCloudflared, gateLogFile, isProcessAlive, listStates, providerLogFile, readConfig, readState, writeConfig, writeState, } from "../lib/tunnel/state.js";
 /**
- * `tunnel`: IP-gated Cloudflare quick tunnel in front of a local upstream.
+ * `tunnel`: provider-backed tunnel in front of a local upstream.
  *
- * Two-process design: a Bun reverse-proxy worker (lib/tunnel/gate.ts) checks
- * the Cloudflare-set `CF-Connecting-IP` header against an allowlist and
- * rewrites Host for the upstream; cloudflared --url then exposes the gate
- * as a random `<words>.trycloudflare.com` hostname.
+ * A Bun reverse-proxy worker (lib/tunnel/gate.ts) rewrites Host for the
+ * upstream. Cloudflare quick tunnels add an IP allowlist at the gate via the
+ * Cloudflare-set `CF-Connecting-IP` header; Tailscale Serve/Funnel exposes the
+ * same gate through tailscaled, with Tailscale owning the access boundary.
  *
  * State + config persisted under `.cache/tunnel/`. cloudflared auto-installs
- * to ~/.local/bin/ on first run (Linux only; macOS users `brew install`).
+ * to ~/.local/bin/ on first run (Linux only; macOS users `brew install`);
+ * Tailscale requires an installed/authenticated `tailscale` CLI.
  */
 const DEFAULT_TARGET = "127.0.0.1:8001";
 const DEFAULT_VHOST = "localhost";
@@ -38,6 +39,54 @@ function resolveName(raw) {
     }
     return name;
 }
+function resolveProvider(raw) {
+    const provider = (raw ?? "cloudflare").trim().toLowerCase();
+    if (provider === "cloudflare" || provider === "cf")
+        return "cloudflare";
+    if (provider === "tailscale" || provider === "ts")
+        return "tailscale";
+    emit.error({
+        code: "tunnel_bad_provider",
+        message: `Invalid provider "${raw}". Use cloudflare or tailscale.`,
+    });
+    process.exit(1);
+}
+function resolveTailscaleMode(raw) {
+    const visibility = (raw ?? "tailnet").trim().toLowerCase();
+    if (visibility === "tailnet" || visibility === "serve")
+        return "serve";
+    if (visibility === "public" || visibility === "internet" || visibility === "funnel") {
+        return "funnel";
+    }
+    emit.error({
+        code: "tunnel_bad_visibility",
+        message: `Invalid Tailscale visibility "${raw}". Use tailnet or public.`,
+    });
+    process.exit(1);
+}
+function resolveTailscalePath(raw, name) {
+    const fallback = name === DEFAULT_INSTANCE ? "/" : `/${name}`;
+    const path = (raw ?? fallback).trim();
+    if (!path.startsWith("/")) {
+        emit.error({
+            code: "tunnel_bad_path",
+            message: `Tailscale path "${path}" must start with /.`,
+        });
+        process.exit(1);
+    }
+    return path === "" ? "/" : path;
+}
+function resolveHttpsPort(raw) {
+    const port = raw === undefined ? 443 : Number(raw);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        emit.error({
+            code: "tunnel_bad_https_port",
+            message: `Invalid HTTPS port "${raw}". Use a number from 1 to 65535.`,
+        });
+        process.exit(1);
+    }
+    return port;
+}
 function gateScriptPath() {
     return resolve(import.meta.dirname, "..", "lib", "tunnel", "gate.ts");
 }
@@ -51,6 +100,9 @@ function gateScriptPath() {
 function bunAvailable() {
     return spawnSync("bun", ["--version"], { stdio: "ignore" }).status === 0;
 }
+function tailscaleAvailable() {
+    return spawnSync("tailscale", ["version"], { stdio: "ignore" }).status === 0;
+}
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
@@ -169,12 +221,98 @@ async function waitForReady(logPath, timeoutMs) {
     }
     return { url, registered: false };
 }
+function tailscaleDnsName() {
+    const r = spawnSync("tailscale", ["status", "--json"], { encoding: "utf-8" });
+    if (r.status !== 0) {
+        emit.error({
+            code: "tunnel_tailscale_status_failed",
+            message: "Failed to read `tailscale status --json`. Install Tailscale and connect this machine to a tailnet first.",
+        });
+        process.exit(1);
+    }
+    try {
+        const parsed = JSON.parse(r.stdout);
+        const dns = parsed.Self?.DNSName?.replace(/\.$/, "");
+        if (dns)
+            return dns;
+    }
+    catch {
+        /* handled below */
+    }
+    emit.error({
+        code: "tunnel_tailscale_no_dns",
+        message: "Tailscale status did not report a MagicDNS name. Enable MagicDNS for the tailnet, then retry.",
+    });
+    process.exit(1);
+}
+function tailscaleUrl(path, httpsPort) {
+    const base = `https://${tailscaleDnsName()}${httpsPort === 443 ? "" : `:${httpsPort}`}`;
+    return path === "/" ? `${base}/` : `${base}${path}`;
+}
+function tailscaleCommand(mode) {
+    return mode === "funnel" ? "funnel" : "serve";
+}
+function runTailscaleShare(mode, targetUrl, path, httpsPort, logPath) {
+    const fd = openSync(logPath, "a");
+    const args = [
+        tailscaleCommand(mode),
+        "--bg",
+        "--yes",
+        `--https=${httpsPort}`,
+        `--set-path=${path}`,
+        targetUrl,
+    ];
+    const r = spawnSync("tailscale", args, {
+        stdio: ["ignore", fd, fd],
+    });
+    if (r.status !== 0) {
+        emit.error({
+            code: "tunnel_tailscale_failed",
+            message: `tailscale ${tailscaleCommand(mode)} failed. Check log: ${logPath}`,
+        });
+        process.exit(r.status ?? 1);
+    }
+}
+function stopTailscaleShare(state) {
+    if (state.provider !== "tailscale" || !state.tailscale_mode)
+        return true;
+    const cmd = tailscaleCommand(state.tailscale_mode);
+    const logPath = cachePath("tunnel", providerLogFile(state.name, "tailscale"));
+    const fd = openSync(logPath, "a");
+    const args = [
+        cmd,
+        `--https=${state.tailscale_https_port ?? 443}`,
+        `--set-path=${state.tailscale_path ?? "/"}`,
+        "off",
+    ];
+    const r = spawnSync("tailscale", args, { stdio: ["ignore", fd, fd] });
+    if (r.status !== 0) {
+        // The gate is torn down and its port is freed for reuse regardless, so a
+        // surviving serve/funnel mapping could later re-expose whatever next binds
+        // that port. Surface it loudly so the operator can clear it by hand.
+        emit.text(`\n  ⚠ Failed to remove the Tailscale ${cmd} mapping (path ${state.tailscale_path ?? "/"}).\n` +
+            `    It may still be exposing this machine. Clear it with:\n` +
+            `      tailscale ${cmd} --https=${state.tailscale_https_port ?? 443} --set-path=${state.tailscale_path ?? "/"} off\n` +
+            `    Log: ${logPath}\n\n`);
+        return false;
+    }
+    return true;
+}
 /** Resolve the context-supplied default vhost (literal or lazy resolver). */
 function contextVhost() {
     const v = context?.tunnelDefaultVhost;
     const resolved = typeof v === "function" ? v() : v;
     return resolved ?? null;
 }
+function providerIsAlive(state) {
+    if (state.provider === "tailscale")
+        return true;
+    const pid = state.cloudflared_pid ?? state.provider_pid;
+    return typeof pid === "number" && isProcessAlive(pid);
+}
+function tunnelIsAlive(state) {
+    return isProcessAlive(state.gate_pid) && providerIsAlive(state);
+}
 async function up(opts) {
     if (!bunAvailable()) {
         emit.error({
@@ -185,18 +323,30 @@ async function up(opts) {
         process.exit(1);
     }
     const name = resolveName(opts.name);
+    const provider = resolveProvider(opts.provider);
     const target = opts.target ?? DEFAULT_TARGET;
     // Precedence: explicit --vhost > the consumer's configured default (via
     // context.tunnelDefaultVhost) > "localhost".
     const vhost = opts.vhost ?? contextVhost() ?? DEFAULT_VHOST;
+    const tailscaleMode = provider === "tailscale" ? resolveTailscaleMode(opts.visibility) : undefined;
+    const tailscalePath = provider === "tailscale" ? resolveTailscalePath(opts.path, name) : undefined;
+    const tailscaleHttpsPort = provider === "tailscale" ? resolveHttpsPort(opts.httpsPort) : undefined;
     const existing = readState(name);
-    if (existing && isProcessAlive(existing.gate_pid) && isProcessAlive(existing.cloudflared_pid)) {
+    if (existing && tunnelIsAlive(existing)) {
+        if (existing.provider !== provider) {
+            emit.error({
+                code: "tunnel_instance_in_use",
+                message: `Tunnel [${name}] is already up with provider ${existing.provider}. Stop it before starting ${provider}.`,
+            });
+            process.exit(1);
+        }
         emit.text(`Already up [${name}]: ${existing.url}\n`);
+        emit.text(`  Provider:   ${existing.provider}\n`);
         emit.text(`  Forwarding: ${existing.target} (Host: ${existing.vhost})\n`);
         return;
     }
     if (existing)
-        clearState(name);
+        downOne(name, new Set());
     // Allocate the gate port (after clearing dead state so its old port frees up
     // for reuse). Explicit --gate-port is validated; otherwise auto-scan.
     const gatePort = allocateGatePort(opts.gatePort ? Number(opts.gatePort) : undefined);
@@ -205,18 +355,25 @@ async function up(opts) {
     if (sweepStrays(gatePort, new Set()))
         await sleep(500);
     const cfg = readConfig();
-    if (cfg.allowed_ips.length === 0) {
+    if (provider === "cloudflare" && cfg.allowed_ips.length === 0) {
         emit.error({
             code: "tunnel_allowlist_empty",
             message: "Allowlist is empty; refusing to start. Add an IP first: harn tunnel allow add <ip>",
         });
         process.exit(1);
     }
-    const cloudflaredBin = ensureCloudflared();
+    const cloudflaredBin = provider === "cloudflare" ? ensureCloudflared() : null;
+    if (provider === "tailscale" && !tailscaleAvailable()) {
+        emit.error({
+            code: "tunnel_tailscale_missing",
+            message: "tailscale CLI not found or unavailable. Install Tailscale and sign in, then retry.",
+        });
+        process.exit(1);
+    }
     const gateLogPath = cachePath("tunnel", gateLogFile(name));
-    const cfdLogPath = cachePath("tunnel", cfdLogFile(name));
+    const providerLogPath = cachePath("tunnel", providerLogFile(name, provider));
     writeFileSync(gateLogPath, "");
-    writeFileSync(cfdLogPath, "");
+    writeFileSync(providerLogPath, "");
     const gateFd = openSync(gateLogPath, "a");
     // `--name`/`--port` on argv mirror the env vars; they're what makes the gate
     // process distinguishable per-instance in `pgrep -f` (see sweepStrays).
@@ -226,6 +383,7 @@ async function up(opts) {
         env: {
             ...process.env,
             HARNERY_TUNNEL_ALLOW: cfg.allowed_ips.join(","),
+            HARNERY_TUNNEL_ACCESS: provider === "cloudflare" ? "cloudflare-allowlist" : "trusted-local-proxy",
             HARNERY_TUNNEL_TARGET: target,
             HARNERY_TUNNEL_VHOST: vhost,
             HARNERY_TUNNEL_PORT: String(gatePort),
@@ -240,54 +398,85 @@ async function up(opts) {
         });
         process.exit(1);
     }
-    const cfdFd = openSync(cfdLogPath, "a");
-    // Force HTTP/2 transport. The default QUIC transport wedges at precheck on
-    // constrained hosts (e.g. WSL, where UDP receive buffers can't grow and ICMP
-    // is restricted): the URL prints but the edge never registers. HTTP/2 is
-    // marginally higher-latency but registers reliably, which is what a dev
-    // tunnel needs.
-    const cfdProc = spawn(cloudflaredBin, ["tunnel", "--protocol", "http2", "--url", `http://localhost:${gatePort}`], {
-        detached: true,
-        stdio: ["ignore", cfdFd, cfdFd],
-    });
-    cfdProc.unref();
-    const { url, registered } = await waitForReady(cfdLogPath, 30_000);
-    if (!url) {
-        try {
-            process.kill(gateProc.pid);
-        }
-        catch {
-            /* already dead */
-        }
-        try {
-            process.kill(cfdProc.pid);
-        }
-        catch {
-            /* already dead */
-        }
-        emit.error({
-            code: "tunnel_url_timeout",
-            message: `Failed to obtain tunnel URL within 30s. Check log: ${cfdLogPath}`,
+    let url;
+    let registered = true;
+    let cloudflaredPid;
+    if (provider === "cloudflare") {
+        const cfdFd = openSync(providerLogPath, "a");
+        // Force HTTP/2 transport. The default QUIC transport wedges at precheck on
+        // constrained hosts (e.g. WSL, where UDP receive buffers can't grow and ICMP
+        // is restricted): the URL prints but the edge never registers. HTTP/2 is
+        // marginally higher-latency but registers reliably, which is what a dev
+        // tunnel needs.
+        const cfdProc = spawn(cloudflaredBin, ["tunnel", "--protocol", "http2", "--url", `http://localhost:${gatePort}`], {
+            detached: true,
+            stdio: ["ignore", cfdFd, cfdFd],
         });
-        process.exit(1);
+        cfdProc.unref();
+        cloudflaredPid = cfdProc.pid;
+        const ready = await waitForReady(providerLogPath, 30_000);
+        registered = ready.registered;
+        if (!ready.url) {
+            try {
+                process.kill(gateProc.pid);
+            }
+            catch {
+                /* already dead */
+            }
+            try {
+                process.kill(cloudflaredPid);
+            }
+            catch {
+                /* already dead */
+            }
+            emit.error({
+                code: "tunnel_url_timeout",
+                message: `Failed to obtain tunnel URL within 30s. Check log: ${providerLogPath}`,
+            });
+            process.exit(1);
+        }
+        url = ready.url;
+    }
+    else {
+        // Resolve the public URL (MagicDNS name) BEFORE starting the share.
+        // tailscaleUrl -> tailscaleDnsName() hard-exits when MagicDNS is
+        // unavailable; doing it first means we fail cleanly rather than leaving a
+        // live serve/funnel exposure with no state file — which `down`/`status`/
+        // `heal` would then be unable to see or clean up.
+        url = tailscaleUrl(tailscalePath, tailscaleHttpsPort);
+        const gateTarget = `http://127.0.0.1:${gatePort}`;
+        runTailscaleShare(tailscaleMode, gateTarget, tailscalePath, tailscaleHttpsPort, providerLogPath);
     }
     const state = {
         name,
+        provider,
         url,
         gate_pid: gateProc.pid,
-        cloudflared_pid: cfdProc.pid,
+        cloudflared_pid: cloudflaredPid,
         started_at: new Date().toISOString(),
         target,
         vhost,
         gate_port: gatePort,
+        tailscale_mode: tailscaleMode,
+        tailscale_path: tailscalePath,
+        tailscale_https_port: tailscaleHttpsPort,
     };
     writeState(state);
     const stopHint = name === DEFAULT_INSTANCE ? "harn tunnel down" : `harn tunnel down --name ${name}`;
     emit.text(`\n  Instance: ${name}\n`);
+    emit.text(`  Provider: ${provider}${tailscaleMode ? ` (${tailscaleMode})` : ""}\n`);
     emit.text(`  URL: ${url}\n\n`);
     emit.text(`  Forwarding: ${target} (Host: ${vhost})\n`);
     emit.text(`  Gate port: ${gatePort}\n`);
-    emit.text(`  Allowed IPs: ${cfg.allowed_ips.join(", ")}\n\n`);
+    if (provider === "cloudflare") {
+        emit.text(`  Allowed IPs: ${cfg.allowed_ips.join(", ")}\n\n`);
+    }
+    else {
+        emit.text(`  Tailscale path: ${tailscalePath}\n`);
+        emit.text(tailscaleMode === "funnel"
+            ? "  Visibility: public internet via Tailscale Funnel\n\n"
+            : "  Visibility: tailnet only via Tailscale Serve\n\n");
+    }
     if (!registered) {
         emit.text(`  ⚠ Edge connection didn't register within 30s (QUIC can wedge on a cold\n    start). If the URL 404s or times out, bounce it: ${stopHint} && harn tunnel up\n\n`);
     }
@@ -299,7 +488,11 @@ function downOne(name, killed) {
     const before = killed.size;
     const state = readState(name);
     if (state) {
-        for (const pid of [state.gate_pid, state.cloudflared_pid]) {
+        if (state.provider === "tailscale")
+            stopTailscaleShare(state);
+        for (const pid of [state.gate_pid, state.cloudflared_pid, state.provider_pid]) {
+            if (typeof pid !== "number")
+                continue;
             if (isProcessAlive(pid)) {
                 try {
                     process.kill(pid);
@@ -346,7 +539,7 @@ function down(opts) {
         : `Stopped ${killed.size} process(es). Tunnel [${name}] down.\n`);
 }
 function instanceState(state) {
-    return isProcessAlive(state.gate_pid) && isProcessAlive(state.cloudflared_pid) ? "up" : "stale";
+    return tunnelIsAlive(state) ? "up" : "stale";
 }
 function fmtUptime(startedAt) {
     const secs = Math.floor((Date.now() - new Date(startedAt).getTime()) / 1000);
@@ -361,15 +554,24 @@ function fmtUptime(startedAt) {
 /** Detailed single-instance block (the pre-multi-instance format). */
 function statusDetail(state) {
     const gateAlive = isProcessAlive(state.gate_pid);
-    const cfdAlive = isProcessAlive(state.cloudflared_pid);
+    const providerAlive = providerIsAlive(state);
+    const providerPid = state.cloudflared_pid ?? state.provider_pid;
     const cfg = readConfig();
-    emit.text(`${gateAlive && cfdAlive ? "up" : "stale"} [${state.name}]\n`);
+    emit.text(`${gateAlive && providerAlive ? "up" : "stale"} [${state.name}]\n`);
+    emit.text(`  Provider:    ${state.provider}${state.tailscale_mode ? ` (${state.tailscale_mode})` : ""}\n`);
     emit.text(`  URL:         ${state.url}\n`);
     emit.text(`  Forwarding:  ${state.target} (Host: ${state.vhost})\n`);
     emit.text(`  Gate port:   ${state.gate_port}\n`);
-    emit.text(`  Allowed IPs: ${cfg.allowed_ips.join(", ")}\n`);
+    if (state.provider === "cloudflare") {
+        emit.text(`  Allowed IPs: ${cfg.allowed_ips.join(", ")}\n`);
+    }
+    else {
+        emit.text(`  TS path:     ${state.tailscale_path ?? "/"}\n`);
+    }
     emit.text(`  Gate PID:    ${state.gate_pid}${gateAlive ? "" : " (DEAD)"}\n`);
-    emit.text(`  CFD PID:     ${state.cloudflared_pid}${cfdAlive ? "" : " (DEAD)"}\n`);
+    if (state.provider === "cloudflare") {
+        emit.text(`  CFD PID:     ${providerPid ?? "?"}${providerAlive ? "" : " (DEAD)"}\n`);
+    }
     emit.text(`  Uptime:      ${fmtUptime(state.started_at)}\n`);
 }
 function status(opts) {
@@ -396,6 +598,7 @@ function status(opts) {
     }
     const rows = states.map((s) => ({
         name: s.name,
+        provider: s.provider,
         state: instanceState(s),
         url: s.url,
         fwd: `${s.target} (${s.vhost})`,
@@ -404,20 +607,23 @@ function status(opts) {
     }));
     const w = {
         name: Math.max(4, ...rows.map((r) => r.name.length)),
+        provider: Math.max(8, ...rows.map((r) => r.provider.length)),
         state: 5,
         url: Math.max(3, ...rows.map((r) => r.url.length)),
         fwd: Math.max(10, ...rows.map((r) => r.fwd.length)),
         port: 4,
     };
     const pad = (s, n) => s.padEnd(n);
-    emit.text(`${pad("NAME", w.name)}  ${pad("STATE", w.state)}  ${pad("URL", w.url)}  ${pad("FORWARDING", w.fwd)}  ${pad("PORT", w.port)}  UPTIME\n`);
+    emit.text(`${pad("NAME", w.name)}  ${pad("PROVIDER", w.provider)}  ${pad("STATE", w.state)}  ${pad("URL", w.url)}  ${pad("FORWARDING", w.fwd)}  ${pad("PORT", w.port)}  UPTIME\n`);
     for (const r of rows) {
-        emit.text(`${pad(r.name, w.name)}  ${pad(r.state, w.state)}  ${pad(r.url, w.url)}  ${pad(r.fwd, w.fwd)}  ${pad(r.port, w.port)}  ${r.up}\n`);
+        emit.text(`${pad(r.name, w.name)}  ${pad(r.provider, w.provider)}  ${pad(r.state, w.state)}  ${pad(r.url, w.url)}  ${pad(r.fwd, w.fwd)}  ${pad(r.port, w.port)}  ${r.up}\n`);
     }
 }
 function logs(opts) {
     const name = resolveName(opts.name);
-    const which = opts.cloudflared ? cfdLogFile(name) : gateLogFile(name);
+    const state = readState(name);
+    const provider = state?.provider ?? "cloudflare";
+    const which = opts.cloudflared || opts.provider ? providerLogFile(name, provider) : gateLogFile(name);
     const path = cachePath("tunnel", which);
     if (!existsSync(path)) {
         emit.error({ code: "tunnel_no_log", message: `No log file at ${path}` });
@@ -446,9 +652,9 @@ function allowAdd(ip) {
     cfg.allowed_ips.push(ip);
     writeConfig(cfg);
     emit.text(`Added ${ip}.\n`);
-    const up = listStates();
+    const up = listStates().filter((s) => s.provider === "cloudflare");
     if (up.length > 0) {
-        emit.text(`Allowlist is shared across all tunnels; restart each to apply (${up.map((s) => s.name).join(", ")}).\n`);
+        emit.text(`Cloudflare allowlist is shared across Cloudflare tunnels; restart each to apply (${up.map((s) => s.name).join(", ")}).\n`);
     }
 }
 function allowRm(ip) {
@@ -461,9 +667,9 @@ function allowRm(ip) {
     cfg.allowed_ips.splice(idx, 1);
     writeConfig(cfg);
     emit.text(`Removed ${ip}.\n`);
-    const up = listStates();
+    const up = listStates().filter((s) => s.provider === "cloudflare");
     if (up.length > 0) {
-        emit.text(`Allowlist is shared across all tunnels; restart each to apply (${up.map((s) => s.name).join(", ")}).\n`);
+        emit.text(`Cloudflare allowlist is shared across Cloudflare tunnels; restart each to apply (${up.map((s) => s.name).join(", ")}).\n`);
     }
 }
 let emit;
@@ -473,16 +679,20 @@ export function registerTunnelCommand(program, emitParam, contextParam) {
     context = contextParam;
     const cmd = program
         .command("tunnel")
-        .description("IP-gated Cloudflare quick tunnel(s) in front of a local upstream (default upstream: 127.0.0.1:8001). " +
+        .description("Provider-backed tunnel(s) in front of a local upstream (default upstream: 127.0.0.1:8001). " +
         "Run several at once with --name <instance>.");
     cmd
         .command("up")
-        .description("Start a gate + cloudflared tunnel (one per --name instance)")
+        .description("Start a gate + provider tunnel (one per --name instance)")
         .option("--name <name>", "instance name; run multiple tunnels side by side", DEFAULT_INSTANCE)
+        .option("--provider <provider>", "provider: cloudflare (default) or tailscale", "cloudflare")
         .option("--target <addr>", "upstream to forward to", DEFAULT_TARGET)
         .option("--vhost <host>", "Host header sent to the upstream (default: the consumer's configured " +
         "default, else localhost).")
         .option("--gate-port <port>", "local port the gate binds to (default: auto-allocate the first free port from 9001)")
+        .option("--visibility <visibility>", "Tailscale only: tailnet (Serve, default) or public (Funnel)", "tailnet")
+        .option("--path <path>", "Tailscale only: URL path mount (default: / for default, /<name> for named instances)")
+        .option("--https-port <port>", "Tailscale only: HTTPS listen port (default: 443)", "443")
         .action(up);
     cmd
         .command("down")
@@ -497,15 +707,16 @@ export function registerTunnelCommand(program, emitParam, contextParam) {
         .action(status);
     cmd
         .command("logs")
-        .description("Tail the gate log (default) or cloudflared log for an instance")
+        .description("Tail the gate log (default) or provider log for an instance")
         .option("--name <name>", "instance whose log to tail", DEFAULT_INSTANCE)
         .option("-f, --follow", "follow the log")
         .option("--gate", "tail the gate log (default)")
-        .option("--cloudflared", "tail the cloudflared log instead")
+        .option("--provider", "tail the provider log instead")
+        .option("--cloudflared", "tail the Cloudflare provider log instead (legacy alias)")
         .action(logs);
     const allow = cmd
         .command("allow")
-        .description("Manage the CF-Connecting-IP allowlist")
+        .description("Manage the Cloudflare CF-Connecting-IP allowlist")
         .action(allowList);
     allow.command("add <ip>").description("Add an IP to the allowlist").action(allowAdd);
     allow.command("rm <ip>").description("Remove an IP from the allowlist").action(allowRm);

package/dist/commands/web-fetch.js

@@ -14,7 +14,7 @@ import { fileURLToPath } from "node:url";
  * harnery repo at the *matching version tag* into a cache dir and install the
  * web app's deps. Subsequent runs reuse the cache.
  *
- * The only thing `web/` pulls from `src/` is `harnery/lib/scratch` (a single,
+ * The only thing `web/` pulls from `src/` is `harnery/core/scratch` (a single,
  * dependency-free module), so the install is `web/` deps only: no root install,
  * no Playwright browser download.
  */

package/dist/core/agents/cli.js

@@ -150,6 +150,32 @@ async function handleProject(root, rest) {
     }
     return 0;
 }
+/**
+ * Append a canonical `claim.release` event for a path dropped from an owner's
+ * files_touched. The path is canonicalized to repo-relative (matching the
+ * projector's normalization) so the subtraction matches on replay regardless
+ * of the form the caller passed. Soft-fails: a failed emit must never break
+ * the release/kill flow — the file mutation already happened.
+ */
+async function emitClaimRelease(root, owner, hb, path, reason) {
+    try {
+        const { emit } = await import("./events/emit.js");
+        const canonical = path.startsWith(`${root}/`) ? path.slice(root.length + 1) : path;
+        const platform = hb.platform;
+        const harness = platform === "cursor" ? "cursor" : platform === "codex" ? "codex" : "claude-code";
+        emit(root, {
+            event_type: "claim.release",
+            instance_id: owner,
+            session_id: hb.session_id ?? owner,
+            harness,
+            source: "agent-coord",
+            data: { path: canonical, reason },
+        });
+    }
+    catch {
+        /* soft-fail: never break the caller */
+    }
+}
 async function handleStateAction(root, action, rest) {
     const writer = await import("./state/heartbeat-writer.js");
     const [owner, ...args] = rest;
@@ -189,14 +215,36 @@ async function handleStateAction(root, action, rest) {
                 process.stderr.write("agent-coord release-claim: missing <path>\n");
                 return 2;
             }
+            const before = writer.readHeartbeat(root, owner);
             const hb = writer.releaseClaim(root, owner, path);
             if (!hb)
                 return 1;
+            // Durability: the projector rebuilds files_touched by replaying the
+            // permanent Edit/Write events, so a file-only release is silently
+            // reverted by the next full replay. Emitting claim.release puts the
+            // subtraction into the stream so every future replay honors it. Only
+            // emit when the release actually removed a held path (idempotent
+            // re-releases stay quiet).
+            const heldBefore = before?.files_touched?.length ?? 0;
+            const heldAfter = hb.files_touched?.length ?? 0;
+            if (heldBefore > heldAfter) {
+                await emitClaimRelease(root, owner, before ?? hb, path, "explicit");
+            }
             process.stdout.write(`${JSON.stringify({ instance_id: owner, files_touched: hb.files_touched })}\n`);
             return 0;
         }
         case "kill-heartbeat": {
+            // Read held claims BEFORE the unlink so they can be released durably —
+            // killing only the file leaves the claims resurrectable from the
+            // permanent Edit/Write events on the next full replay (observed: a
+            // 6-day-dead agent's claims returning after its heartbeat was killed).
+            const before = writer.readHeartbeat(root, owner);
             const ok = writer.killHeartbeat(root, owner);
+            if (ok && before) {
+                for (const held of before.files_touched ?? []) {
+                    await emitClaimRelease(root, owner, before, held, "heal");
+                }
+            }
             process.stdout.write(`${JSON.stringify({ instance_id: owner, removed: ok })}\n`);
             return ok ? 0 : 1;
         }

package/dist/core/agents/coord-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coord-client.d.ts","sourceRoot":"","sources":["../../../src/core/agents/coord-client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oGAAoG;IACpG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0IAA0I;IAC1I,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,mEAAmE;IACnE,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CA0C5C;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIvD;AAED,+EAA+E;AAC/E,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI1D;AAaD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAE5C;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI;IACxC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,KAAK,GAAG,QAAQ,GAAG,iBAAiB,GAAG,aAAa,GAAG,kBAAkB,GAAG,MAAM,CAAC;CAC5F,CAuDA;AA4BD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA2BpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAyBpE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAKlE;AAgBD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAOtD;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAIxC"}
+{"version":3,"file":"coord-client.d.ts","sourceRoot":"","sources":["../../../src/core/agents/coord-client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oGAAoG;IACpG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0IAA0I;IAC1I,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,mEAAmE;IACnE,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CA0C5C;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIvD;AAED,+EAA+E;AAC/E,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI1D;AAaD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAE5C;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI;IACxC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,KAAK,GAAG,QAAQ,GAAG,iBAAiB,GAAG,aAAa,GAAG,kBAAkB,GAAG,MAAM,CAAC;CAC5F,CAkEA;AA4CD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA2BpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAyBpE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAKlE;AAgBD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAOtD;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAIxC"}