harnery 0.41.0 → 0.42.0

package/dist/commands/servers.js

@@ -0,0 +1,394 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { hostname } from "node:os";
+import { resolveCoordRoot } from "../core/agents/coord-client.js";
+import { resolveBinName, serverGcConfig } from "../core/config.js";
+import { adoptServer, allocateServerPort, isValidServerId, listServers, planServerGc, readServer, registerServer, SERVER_DEFAULT_IDLE_HOURS, SERVER_DEFAULT_OWNER_STALE_HOURS, stopServer, touchServer, unregisterServer, } from "../core/servers/index.js";
+export function registerServersCommand(program, emit, context) {
+    const root = () => {
+        const resolved = context?.resolveCoordRoot?.() ?? context?.repoRoot ?? resolveCoordRoot();
+        if (!resolved)
+            throw new Error("not inside a Harnery project");
+        return resolved;
+    };
+    const fail = (error, code = "servers_error") => {
+        emit.error({ code, message: error instanceof Error ? error.message : String(error) });
+        emit.setExitCode(1);
+    };
+    const cmd = program
+        .command("servers")
+        .description("Every local server started in this project: list, stop, clean up idle session servers, read logs");
+    cmd
+        .command("list", { isDefault: true })
+        .alias("status")
+        .description("List registered servers and any unregistered listener running inside the project")
+        .option("--no-scan", "Skip the scan for unregistered listeners")
+        .option("--json", "Emit the versioned report")
+        .action((options) => {
+        try {
+            const report = listServers({ coordRoot: root(), scan: options.scan !== false });
+            if (options.json) {
+                emit.config({ format: "json" });
+                emit.data(report);
+            }
+            else
+                emit.text(renderReport(report, resolveBinName(report.coord_root)));
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+    cmd
+        .command("stop [ids...]")
+        .description("Stop named servers now; --type selects several and previews unless --yes")
+        .option("--type <type>", "Select every running server of this type")
+        .option("--pid <pid>", "Stop an unregistered listener found by the list scan (repeatable)", (value, previous = []) => [...previous, value])
+        .option("--kind <kind>", "With --type, limit to session or service")
+        .option("--yes", "Apply a --type selection")
+        .option("--json", "Emit JSON")
+        .action(async (ids, options) => {
+        try {
+            const coordRoot = root();
+            const pids = (options.pid ?? []).map((value) => integer(value, "--pid"));
+            if (!ids.length && !options.type && !pids.length)
+                throw new Error("name server ids, or pass --type or --pid");
+            const report = listServers({ coordRoot, scan: pids.length > 0 });
+            const strays = pids.map((pid) => {
+                const found = report.unregistered.find((item) => item.pid === pid);
+                if (!found)
+                    throw new Error(`pid ${pid} is not an unregistered listener inside this project; only pids shown by "servers list" can be stopped this way`);
+                return found;
+            });
+            const byId = new Map(report.servers.map((view) => [view.record.id, view]));
+            const missing = ids.filter((id) => !byId.has(id));
+            if (missing.length)
+                throw new Error(`no running server named: ${missing.join(", ")}`);
+            const selected = [
+                ...ids.map((id) => byId.get(id)),
+                ...(options.type
+                    ? report.servers.filter((view) => view.record.type === options.type &&
+                        view.state === "running" &&
+                        (!options.kind || view.record.kind === options.kind) &&
+                        !ids.includes(view.record.id))
+                    : []),
+            ];
+            const preview = Boolean(options.type) && !options.yes;
+            const results = [];
+            for (const stray of strays) {
+                results.push(await stopServer({
+                    schema_version: 1,
+                    id: `pid-${stray.pid}`,
+                    kind: "session",
+                    type: "unregistered",
+                    label: stray.command,
+                    pid: stray.pid,
+                    host: hostname(),
+                    started_at: new Date().toISOString(),
+                    registered_at: new Date().toISOString(),
+                }, { coordRoot }));
+            }
+            for (const view of selected) {
+                if (preview && !ids.includes(view.record.id))
+                    results.push({ id: view.record.id, would_stop: true });
+                else
+                    results.push(await stopServer(view.record, { coordRoot }));
+            }
+            if (options.json) {
+                emit.config({ format: "json" });
+                emit.data({ applied: !preview, results });
+            }
+            else {
+                emit.text(results.length
+                    ? results
+                        .map((r) => "would_stop" in r
+                        ? `would stop ${r.id}`
+                        : `${r.stopped ? "stopped" : r.method === "not-running" ? "already stopped" : "could not stop"} ${r.id}${r.detail ? ` (${r.detail})` : ""}`)
+                        .join("\n") +
+                        (preview ? `\nPreview only. Re-run with --yes to stop these.` : "")
+                    : "No matching running servers.");
+            }
+            if (results.some((r) => "stopped" in r && !r.stopped && r.method === "refused"))
+                emit.setExitCode(1);
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+    cmd
+        .command("gc")
+        .description(`Stop idle session servers whose starting agent ended (preview unless --yes); services are never touched`)
+        .option("--idle-hours <hours>", `Idle window before a server may stop (default ${SERVER_DEFAULT_IDLE_HOURS})`)
+        .option("--owner-stale-hours <hours>", `Treat a starting agent unobserved this long as gone (default ${SERVER_DEFAULT_OWNER_STALE_HOURS})`)
+        .option("--yes", "Stop the selected servers")
+        .option("--json", "Emit JSON")
+        .action(async (options) => {
+        try {
+            const coordRoot = root();
+            const configured = serverGcConfig(coordRoot);
+            const idleHours = positive(options.idleHours, configured.idle_hours ?? SERVER_DEFAULT_IDLE_HOURS, "--idle-hours");
+            const ownerStaleHours = positive(options.ownerStaleHours, configured.owner_stale_hours ?? SERVER_DEFAULT_OWNER_STALE_HOURS, "--owner-stale-hours");
+            const report = listServers({ coordRoot, scan: false, ownerStaleHours });
+            const decisions = planServerGc(report.servers, { idleHours, ownerStaleHours });
+            const stops = decisions.filter((d) => d.action === "stop");
+            const results = [];
+            if (options.yes) {
+                for (const decision of stops) {
+                    const view = report.servers.find((v) => v.record.id === decision.id);
+                    results.push(await stopServer(view.record, { coordRoot }));
+                }
+            }
+            if (options.json) {
+                emit.config({ format: "json" });
+                emit.data({ applied: Boolean(options.yes), pruned: report.pruned, decisions, results });
+            }
+            else {
+                const lines = decisions.map((d) => `${d.action === "stop" ? (options.yes ? "stopped" : "would stop") : "keep"}  ${d.id}  ${d.reason}`);
+                if (report.pruned.length)
+                    lines.push(`Removed records of exited servers: ${report.pruned.join(", ")}`);
+                if (!decisions.length)
+                    lines.push("No registered servers.");
+                if (stops.length && !options.yes)
+                    lines.push("Preview only. Re-run with --yes to stop.");
+                emit.text(lines.join("\n"));
+            }
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+    cmd
+        .command("adopt")
+        .description("Register running servers that never registered (only pids the list reports as unregistered)")
+        .option("--pid <pid>", "Adopt this unregistered listener (repeatable)", (value, previous = []) => [...previous, value])
+        .option("--all", "Adopt every unregistered listener the scan reports")
+        .option("--type <type>", "Server family to record", "adopted")
+        .option("--kind <kind>", "session (cleaned up when idle) or service", "session")
+        .option("--label <label>", "Human-readable name (single --pid only)")
+        .option("--scope <path>", "What the server serves (default: its working directory)")
+        .option("--no-owner", "Record no owner, so gc never stops it")
+        .option("--json", "Emit JSON")
+        .action((options) => {
+        try {
+            const coordRoot = root();
+            if (options.kind !== "session" && options.kind !== "service")
+                throw new Error("--kind must be session or service");
+            const pids = options.all
+                ? [...new Set(listServers({ coordRoot, sample: false }).unregistered.map((u) => u.pid))]
+                : (options.pid ?? []).map((value) => integer(value, "--pid"));
+            if (!pids.length)
+                throw new Error(options.all ? "no unregistered listeners" : "pass --pid or --all");
+            if (options.label && pids.length > 1)
+                throw new Error("--label needs a single --pid");
+            const records = pids.map((pid) => adoptServer(pid, {
+                coordRoot,
+                type: options.type,
+                kind: options.kind,
+                ...(options.label ? { label: options.label } : {}),
+                ...(options.scope ? { scope: options.scope } : {}),
+                owner: options.owner === false ? "none" : "self",
+            }));
+            if (options.json) {
+                emit.config({ format: "json" });
+                emit.data({ adopted: records });
+            }
+            else
+                emit.text(records.map((r) => `adopted ${r.id}  ${r.url ?? ""}`).join("\n"));
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+    cmd
+        .command("port <type>")
+        .description("Print a free port from the type's configured range (.harnery/config.jsonc servers.port_ranges)")
+        .action((type) => {
+        try {
+            const port = allocateServerPort(type, { coordRoot: root() });
+            if (port === null)
+                throw new Error(`no port range configured for ${type}`);
+            emit.text(String(port));
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+    cmd
+        .command("logs <id>")
+        .description("Print the end of a server's log file")
+        .option("-n, --lines <n>", "Lines to print", "60")
+        .action((id, options) => {
+        try {
+            const record = readServer(id, { coordRoot: root() });
+            if (!record)
+                throw new Error(`no server named ${id}`);
+            if (!record.log || !existsSync(record.log))
+                throw new Error(`${id} did not record a log file`);
+            const lines = positive(options.lines, 60, "--lines");
+            const size = statSync(record.log).size;
+            const content = readFileSync(record.log, "utf8").slice(Math.max(0, size - 512 * 1024));
+            emit.text(content
+                .split("\n")
+                .slice(-Math.floor(lines) - 1)
+                .join("\n"));
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+    cmd
+        .command("open <id>")
+        .description("Print a server's URL")
+        .action((id) => {
+        try {
+            const record = readServer(id, { coordRoot: root() });
+            if (!record)
+                throw new Error(`no server named ${id}`);
+            if (!record.url)
+                throw new Error(`${id} did not record a URL`);
+            emit.text(record.url);
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+    cmd
+        .command("register")
+        .description("Record a server started by a script or another language (prints the record; the calling agent is recorded as owner)")
+        .requiredOption("--type <type>", "Server family, for example preview or review")
+        .option("--kind <kind>", "session (per piece of work) or service (long-running)", "session")
+        .option("--pid <pid>", "Process that owns the server's lifetime (default: this command's parent)")
+        .option("--port <port>", "Listening port")
+        .option("--id <id>", "Stable id (default derived from type and scope)")
+        .option("--url <url>", "Local URL")
+        .option("--scope <path>", "What the server serves, usually a directory")
+        .option("--label <label>", "Human-readable name")
+        .option("--log <path>", "Log file")
+        .option("--cwd <path>", "Working directory")
+        .action((options) => {
+        try {
+            if (options.kind !== "session" && options.kind !== "service")
+                throw new Error("--kind must be session or service");
+            if (options.id && !isValidServerId(options.id))
+                throw new Error(`invalid id: ${options.id}`);
+            const record = registerServer({
+                kind: options.kind,
+                type: options.type,
+                pid: options.pid ? integer(options.pid, "--pid") : process.ppid,
+                ...(options.port ? { port: integer(options.port, "--port") } : {}),
+                ...(options.id ? { id: options.id } : {}),
+                ...(options.url ? { url: options.url } : {}),
+                ...(options.scope ? { scope: options.scope } : {}),
+                ...(options.label ? { label: options.label } : {}),
+                ...(options.log ? { log: options.log } : {}),
+                ...(options.cwd ? { cwd: options.cwd } : {}),
+            }, { coordRoot: root() });
+            emit.config({ format: "json" });
+            emit.data(record);
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+    cmd
+        .command("unregister <id>")
+        .description("Remove a server's record (with --pid, only if the record still names that pid)")
+        .option("--pid <pid>", "Only remove when the record names this pid")
+        .action((id, options) => {
+        try {
+            const removed = unregisterServer(id, {
+                coordRoot: root(),
+                ...(options.pid ? { pid: integer(options.pid, "--pid") } : {}),
+            });
+            emit.config({ format: "json" });
+            emit.data({ id, removed });
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+    cmd
+        .command("touch <id>")
+        .description("Mark a server as used now, postponing idle cleanup")
+        .action((id) => {
+        try {
+            touchServer(id, { coordRoot: root() });
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+}
+function integer(value, flag) {
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 1)
+        throw new Error(`${flag} must be a positive integer`);
+    return parsed;
+}
+function positive(value, fallback, flag) {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        throw new Error(`${flag} must be a positive number`);
+    return parsed;
+}
+function duration(ms) {
+    const minutes = Math.round(ms / 60_000);
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 48)
+        return `${hours}h${String(minutes % 60).padStart(2, "0")}m`;
+    return `${Math.floor(hours / 24)}d`;
+}
+function ownerText(view) {
+    if (!view.record.owner)
+        return "no agent";
+    const name = view.record.owner.name ?? view.record.owner.instance_id.slice(0, 8);
+    return view.owner_state === "live" ? name : `${name} (${view.owner_state})`;
+}
+/** Plain-text table grouped by kind; exported for tests. */
+export function renderReport(report, bin) {
+    const lines = [];
+    for (const kind of ["service", "session"]) {
+        const views = report.servers.filter((view) => view.record.kind === kind);
+        lines.push(kind === "service"
+            ? "Services (stopped only by hand)"
+            : "Session servers (cleaned up when idle and their agent is gone)");
+        if (!views.length) {
+            lines.push("  none");
+            continue;
+        }
+        for (const view of views) {
+            const { record } = view;
+            const state = view.state === "running" ? "" : ` [${view.state}]`;
+            const started = Date.parse(record.started_at);
+            const use = kind === "service"
+                ? `up ${Number.isFinite(started) ? duration(Date.now() - started) : "?"}`
+                : view.connections === null
+                    ? `idle ${duration(view.idle_ms)}`
+                    : view.connections > 0
+                        ? `${view.connections} open connection(s)`
+                        : `idle ${duration(view.idle_ms)}`;
+            lines.push(`  ${record.id}${state}  ${record.url ?? (record.port ? `port ${record.port}` : "")}`, `      ${record.label} · ${ownerText(view)} · ${use}`);
+        }
+    }
+    if (report.scan === "unsupported") {
+        lines.push("Unregistered listeners: not checked on this platform");
+    }
+    else if (report.unregistered.length) {
+        const byPid = new Map();
+        for (const item of report.unregistered) {
+            const entry = byPid.get(item.pid) ?? { ports: [], command: item.command };
+            entry.ports.push(item.port);
+            byPid.set(item.pid, entry);
+        }
+        lines.push(`Unregistered servers inside this project (${byPid.size} processes):`);
+        for (const [pid, entry] of byPid)
+            lines.push(`  pid ${pid}  port ${entry.ports.join(", ")}  ${entry.command.slice(0, 100)}`);
+        lines.push(`  These started without registering. Stop one with: ${bin} servers stop --pid <pid>`);
+    }
+    if (report.pruned.length)
+        lines.push(`Removed records of exited servers: ${report.pruned.join(", ")}`);
+    lines.push(`Control: ${bin} servers stop <id> · ${bin} servers gc · ${bin} servers logs <id>`);
+    return lines.join("\n");
+}

package/dist/commands/tunnel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tunnel.d.ts","sourceRoot":"","sources":["../../src/commands/tunnel.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAQ1E,OAAO,EAYL,KAAK,cAAc,EACnB,KAAK,WAAW,EAGjB,MAAM,wBAAwB,CAAC;AAoDhC,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,cAAc,EACxB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,IAAI,SAAgB,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAcpC;AAuoBD;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAsE7F;AA+MD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,YAAY,CAAC,EAAE,qBAAqB,GACnC,IAAI,CA2EN"}
+{"version":3,"file":"tunnel.d.ts","sourceRoot":"","sources":["../../src/commands/tunnel.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAgB1E,OAAO,EAYL,KAAK,cAAc,EACnB,KAAK,WAAW,EAGjB,MAAM,wBAAwB,CAAC;AAuDhC,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,cAAc,EACxB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,IAAI,SAAgB,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAcpC;AA2sBD;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAiF7F;AAkND,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,YAAY,CAAC,EAAE,qBAAqB,GACnC,IAAI,CAkFN"}

package/dist/commands/tunnel.js

@@ -1,8 +1,11 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { resolveCoordRoot } from "../core/agents/coord-client.js";
 import { resolveBinName } from "../core/config.js";
+import { tryRegisterServer, tunnelServerId, tunnelServerInput, unregisterServer, } from "../core/servers/index.js";
 import { processLogDestination, runRotatingProcessSync, spawnRotatingProcess, } from "../core/storage/process-log.js";
+import { ALLOW_PATHS_ENV, normalizeAllowPaths } from "../lib/tunnel/path-scope.js";
 import { clearState, DEFAULT_INSTANCE, ensureCloudflared, gateLogFile, isProcessAlive, isTunnelStateLive, listStates, providerLogFile, readConfig, readState, writeConfig, writeState, } from "../lib/tunnel/state.js";
 /**
  * `tunnel`: provider-backed tunnel in front of a local upstream.
@@ -11,6 +14,8 @@ import { clearState, DEFAULT_INSTANCE, ensureCloudflared, gateLogFile, isProcess
  * 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.
+ * Every provider also passes through a path scope: `up` requires at least one
+ * `--allow-path <prefix>`, and the gate refuses any request outside it.
  *
  * State + config persisted under `.cache/tunnel/`. cloudflared auto-installs
  * to ~/.local/bin/ on first run (Linux only; macOS users `brew install`);
@@ -98,6 +103,42 @@ function resolveHttpsPort(raw) {
     }
     return port;
 }
+/**
+ * The path scope for `up`. At least one prefix is required: a tunnel forwards
+ * to a whole local app, and publishing all of it has to be a stated choice
+ * (`--allow-path /`), never the result of leaving a flag off.
+ */
+function resolveAllowPaths(raw) {
+    let paths;
+    try {
+        paths = normalizeAllowPaths(raw ?? []);
+    }
+    catch (error) {
+        emit.error({
+            code: "tunnel_path_scope_invalid",
+            message: error instanceof Error ? error.message : String(error),
+        });
+        process.exit(1);
+    }
+    if (paths.length === 0) {
+        emit.error({
+            code: "tunnel_path_scope_empty",
+            message: "No path scope; refusing to start. Name what the tunnel shares with --allow-path <prefix> " +
+                "(repeatable), or pass --allow-path / to publish the whole upstream.",
+        });
+        process.exit(1);
+    }
+    return paths;
+}
+function samePaths(a, b) {
+    return a.length === b.length && [...a].sort().join("\n") === [...b].sort().join("\n");
+}
+function formatPaths(paths) {
+    return paths.length === 0 ? "(none: every path refused)" : paths.join(", ");
+}
+function collectPath(value, previous) {
+    return [...previous, value];
+}
 function gateScriptPath() {
     return resolve(import.meta.dirname, "..", "lib", "tunnel", "gate.ts");
 }
@@ -366,6 +407,7 @@ function spawnGate(o) {
             HARNERY_TUNNEL_TARGET: o.target,
             HARNERY_TUNNEL_VHOST: o.vhost,
             HARNERY_TUNNEL_PORT: String(o.gatePort),
+            [ALLOW_PATHS_ENV]: o.allowPaths.join(","),
         },
     });
     gateProc.unref();
@@ -389,6 +431,7 @@ async function up(opts) {
     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 allowPaths = resolveAllowPaths(opts.allowPath);
     const existing = readState(name);
     if (existing && tunnelIsAlive(existing)) {
         if (existing.provider !== provider) {
@@ -398,9 +441,18 @@ async function up(opts) {
             });
             process.exit(1);
         }
+        if (!samePaths(existing.allow_paths, allowPaths)) {
+            emit.error({
+                code: "tunnel_instance_in_use",
+                message: `Tunnel [${name}] is already up sharing ${formatPaths(existing.allow_paths)}. ` +
+                    `Stop it before starting it with ${formatPaths(allowPaths)}.`,
+            });
+            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`);
+        emit.text(`  Paths:      ${formatPaths(existing.allow_paths)}\n`);
         return;
     }
     if (existing)
@@ -438,6 +490,7 @@ async function up(opts) {
         vhost,
         provider,
         allowedIps: cfg.allowed_ips,
+        allowPaths,
         gateLogPath,
     });
     await sleep(800);
@@ -507,16 +560,19 @@ async function up(opts) {
         target,
         vhost,
         gate_port: gatePort,
+        allow_paths: allowPaths,
         tailscale_mode: tailscaleMode,
         tailscale_path: tailscalePath,
         tailscale_https_port: tailscaleHttpsPort,
     };
     writeState(state);
+    recordTunnelServer(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(`  Paths: ${formatPaths(allowPaths)}\n`);
     emit.text(`  Gate port: ${gatePort}\n`);
     if (provider === "cloudflare") {
         emit.text(`  Allowed IPs: ${cfg.allowed_ips.join(", ")}\n\n`);
@@ -533,6 +589,14 @@ async function up(opts) {
     emit.text(`  Stop:   ${stopHint}\n`);
     emit.text("  Status: harn tunnel status\n");
 }
+/** The server registry lists tunnels beside every other local server. */
+function registryRoot() {
+    return resolveCoordRoot() ?? process.cwd();
+}
+function recordTunnelServer(state) {
+    const coordRoot = registryRoot();
+    tryRegisterServer(tunnelServerInput(state, coordRoot), { coordRoot });
+}
 /** Tear down a single instance by name. Returns the number of processes killed. */
 function downOne(name, killed) {
     const before = killed.size;
@@ -558,6 +622,7 @@ function downOne(name, killed) {
     // lost; they'd otherwise squat on the port and break the next `up`.
     sweepStrays(state?.gate_port ?? DEFAULT_GATE_PORT, killed);
     clearState(name);
+    unregisterServer(tunnelServerId(name), { coordRoot: registryRoot() });
     return killed.size - before;
 }
 function down(opts) {
@@ -633,6 +698,14 @@ export async function reloadOne(state) {
     if (!bunAvailable()) {
         return { ok: false, message: `[${name}] bun is not on PATH, so the gate can't be respawned.` };
     }
+    if (state.allow_paths.length === 0) {
+        return {
+            ok: false,
+            message: `[${name}] has no recorded path scope, so a reloaded gate would refuse every request. ` +
+                `Restart it with \`${bin} tunnel down --name ${name}\` and ` +
+                `\`${bin} tunnel up --name ${name} --allow-path <prefix>\`.`,
+        };
+    }
     // Kill ONLY the gate. sweepStrays() is deliberately avoided here: it also
     // matches `--url http://localhost:<port>`, which is the provider process we
     // are going out of our way to keep alive.
@@ -662,6 +735,7 @@ export async function reloadOne(state) {
         vhost: state.vhost,
         provider: state.provider,
         allowedIps: cfg.allowed_ips,
+        allowPaths: state.allow_paths,
         gateLogPath: tunnelLogDestinations(name, state.provider).gate,
     });
     await sleep(800);
@@ -676,6 +750,7 @@ export async function reloadOne(state) {
         };
     }
     writeState({ ...state, gate_pid: pid });
+    recordTunnelServer({ ...state, gate_pid: pid });
     const allowNote = state.provider === "cloudflare" ? ` Allowlist: ${cfg.allowed_ips.length} IP(s).` : "";
     return { ok: true, message: `[${name}] gate reloaded, URL unchanged: ${state.url}.${allowNote}` };
 }
@@ -745,6 +820,7 @@ function statusDetail(state) {
     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(`  Paths:       ${formatPaths(state.allow_paths)}\n`);
     emit.text(`  Gate port:   ${state.gate_port}\n`);
     if (state.provider === "cloudflare") {
         emit.text(`  Allowed IPs: ${cfg.allowed_ips.join(", ")}\n`);
@@ -786,6 +862,7 @@ function status(opts) {
         state: instanceState(s),
         url: s.url,
         fwd: `${s.target} (${s.vhost})`,
+        paths: formatPaths(s.allow_paths),
         port: String(s.gate_port),
         up: fmtUptime(s.started_at),
     }));
@@ -795,12 +872,13 @@ function status(opts) {
         state: 5,
         url: Math.max(3, ...rows.map((r) => r.url.length)),
         fwd: Math.max(10, ...rows.map((r) => r.fwd.length)),
+        paths: Math.max(5, ...rows.map((r) => r.paths.length)),
         port: 4,
     };
     const pad = (s, n) => s.padEnd(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`);
+    emit.text(`${pad("NAME", w.name)}  ${pad("PROVIDER", w.provider)}  ${pad("STATE", w.state)}  ${pad("URL", w.url)}  ${pad("FORWARDING", w.fwd)}  ${pad("PATHS", w.paths)}  ${pad("PORT", w.port)}  UPTIME\n`);
     for (const r of rows) {
-        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`);
+        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.paths, w.paths)}  ${pad(r.port, w.port)}  ${r.up}\n`);
     }
 }
 function logs(opts) {
@@ -886,6 +964,8 @@ export function registerTunnelCommand(program, emitParam, contextParam) {
         .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")
+        .option("--allow-path <prefix>", "URL path prefix the tunnel shares (repeatable, required). Every other path is refused; " +
+        "pass / to publish the whole upstream.", collectPath, [])
         .action(up);
     cmd
         .command("down")

package/dist/core/adapters/profiles.d.ts

@@ -17,6 +17,9 @@ export declare const BUILTIN_ADAPTER_PROFILES: {
             readonly date: "2026-08-18";
             readonly version: "2.1.233 (Claude Code)";
         };
+        readonly fullAccess: {
+            readonly argv: readonly ["--permission-mode", "bypassPermissions", "--settings", "{\"sandbox\":{\"enabled\":false}}"];
+        };
         readonly capabilities: AdapterCapabilities;
     };
     readonly codex: {
@@ -41,6 +44,9 @@ export declare const BUILTIN_ADAPTER_PROFILES: {
             };
             readonly writableRoots: true;
         };
+        readonly fullAccess: {
+            readonly argv: readonly ["--sandbox", "danger-full-access"];
+        };
         readonly capabilities: AdapterCapabilities;
     };
     readonly cursor: {
@@ -58,6 +64,9 @@ export declare const BUILTIN_ADAPTER_PROFILES: {
             readonly date: "2026-09-20";
             readonly version: "2026.09.18-9a7762b";
         };
+        readonly fullAccess: {
+            readonly argv: readonly ["--sandbox", "disabled"];
+        };
         readonly capabilities: AdapterCapabilities;
     };
     readonly opencode: {

package/dist/core/adapters/profiles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/profiles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAmB,MAAM,YAAY,CAAC;AAgCvF;gFACgF;AAChF,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkIc,CAAC;AAEpD,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,wBAAwB,CAAC;AAErE,eAAO,MAAM,mBAAmB,8DAE/B,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,EAAE,IAAI,gBAAgB,CAEnE;AAED,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAE5E;AAED,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAUlF"}
+{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/profiles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAmB,MAAM,YAAY,CAAC;AAgCvF;gFACgF;AAChF,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuJc,CAAC;AAEpD,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,wBAAwB,CAAC;AAErE,eAAO,MAAM,mBAAmB,8DAE/B,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,EAAE,IAAI,gBAAgB,CAEnE;AAED,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAE5E;AAED,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAUlF"}