harnery 0.41.0 → 0.42.0

package/src/commands/tunnel.ts

@@ -4,12 +4,20 @@ import { resolve } from "node:path";
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
 
+import { resolveCoordRoot } from "../core/agents/coord-client.ts";
 import { resolveBinName } from "../core/config.ts";
+import {
+  tryRegisterServer,
+  tunnelServerId,
+  tunnelServerInput,
+  unregisterServer,
+} from "../core/servers/index.ts";
 import {
   processLogDestination,
   runRotatingProcessSync,
   spawnRotatingProcess,
 } from "../core/storage/process-log.ts";
+import { ALLOW_PATHS_ENV, normalizeAllowPaths } from "../lib/tunnel/path-scope.ts";
 import {
   clearState,
   DEFAULT_INSTANCE,
@@ -35,6 +43,8 @@ import {
  * 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`);
@@ -55,6 +65,7 @@ interface UpOpts {
   visibility?: string;
   path?: string;
   httpsPort?: string;
+  allowPath?: string[];
 }
 
 interface DownOpts {
@@ -165,6 +176,46 @@ function resolveHttpsPort(raw: string | undefined): number {
   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: string[] | undefined): string[] {
+  let paths: string[];
+  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: readonly string[], b: readonly string[]): boolean {
+  return a.length === b.length && [...a].sort().join("\n") === [...b].sort().join("\n");
+}
+
+function formatPaths(paths: readonly string[]): string {
+  return paths.length === 0 ? "(none: every path refused)" : paths.join(", ");
+}
+
+function collectPath(value: string, previous: string[]): string[] {
+  return [...previous, value];
+}
+
 function gateScriptPath(): string {
   return resolve(import.meta.dirname, "..", "lib", "tunnel", "gate.ts");
 }
@@ -444,6 +495,7 @@ interface GateSpawnOpts {
   vhost: string;
   provider: TunnelProvider;
   allowedIps: string[];
+  allowPaths: string[];
   gateLogPath: string;
 }
 
@@ -470,6 +522,7 @@ function spawnGate(o: GateSpawnOpts): ChildProcess {
       HARNERY_TUNNEL_TARGET: o.target,
       HARNERY_TUNNEL_VHOST: o.vhost,
       HARNERY_TUNNEL_PORT: String(o.gatePort),
+      [ALLOW_PATHS_ENV]: o.allowPaths.join(","),
     },
   });
   gateProc.unref();
@@ -498,6 +551,7 @@ async function up(opts: UpOpts): Promise<void> {
     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)) {
@@ -508,9 +562,19 @@ async function up(opts: UpOpts): Promise<void> {
       });
       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) downOne(name, new Set());
@@ -552,6 +616,7 @@ async function up(opts: UpOpts): Promise<void> {
     vhost,
     provider,
     allowedIps: cfg.allowed_ips,
+    allowPaths,
     gateLogPath,
   });
 
@@ -630,11 +695,13 @@ async function up(opts: UpOpts): Promise<void> {
     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}`;
@@ -642,6 +709,7 @@ async function up(opts: UpOpts): Promise<void> {
   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`);
@@ -662,6 +730,16 @@ async function up(opts: UpOpts): Promise<void> {
   emit.text("  Status: harn tunnel status\n");
 }
 
+/** The server registry lists tunnels beside every other local server. */
+function registryRoot(): string {
+  return resolveCoordRoot() ?? process.cwd();
+}
+
+function recordTunnelServer(state: TunnelState): void {
+  const coordRoot = registryRoot();
+  tryRegisterServer(tunnelServerInput(state, coordRoot), { coordRoot });
+}
+
 /** Tear down a single instance by name. Returns the number of processes killed. */
 function downOne(name: string, killed: Set<number>): number {
   const before = killed.size;
@@ -684,6 +762,7 @@ function downOne(name: string, killed: Set<number>): number {
   // 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;
 }
 
@@ -771,6 +850,15 @@ export async function reloadOne(state: TunnelState): Promise<{ ok: boolean; mess
   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
@@ -803,6 +891,7 @@ export async function reloadOne(state: TunnelState): Promise<{ ok: boolean; mess
     vhost: state.vhost,
     provider: state.provider,
     allowedIps: cfg.allowed_ips,
+    allowPaths: state.allow_paths,
     gateLogPath: tunnelLogDestinations(name, state.provider).gate,
   });
 
@@ -822,6 +911,7 @@ export async function reloadOne(state: TunnelState): Promise<{ ok: boolean; mess
   }
 
   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}` };
@@ -898,6 +988,7 @@ function statusDetail(state: TunnelState): void {
   );
   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`);
@@ -941,6 +1032,7 @@ function status(opts: StatusOpts): void {
     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),
   }));
@@ -950,15 +1042,16 @@ function status(opts: StatusOpts): void {
     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: string, n: number) => 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`,
+    `${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`,
+      `${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`,
     );
   }
 }
@@ -1071,6 +1164,13 @@ export function registerTunnelCommand(
       "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

package/src/core/adapters/profiles.ts

@@ -45,6 +45,18 @@ export const BUILTIN_ADAPTER_PROFILES = {
     modelFamily: "claude",
     effortValues: ["low", "medium", "high", "xhigh", "max"],
     verified: { date: "2026-08-18", version: "2.1.233 (Claude Code)" },
+    // Checked against 2.1.283 (ADR 0192). Claude Code has no sandbox mode flag;
+    // its permission mode and its optional Bash sandbox are separate, so full
+    // access needs both: bypass permissions, and a settings layer that turns
+    // the Bash sandbox off in case a user or project settings file enabled it.
+    fullAccess: {
+      argv: [
+        "--permission-mode",
+        "bypassPermissions",
+        "--settings",
+        '{"sandbox":{"enabled":false}}',
+      ],
+    },
     capabilities: capabilities({
       effortSelection: supported("Mapped to `--effort <level>`."),
       maxTurns: supported("Mapped to `--max-turns <n>`."),
@@ -78,6 +90,9 @@ export const BUILTIN_ADAPTER_PROFILES = {
       modes: { "read-only": "read-only", "workspace-write": "workspace-write" },
       writableRoots: true,
     },
+    // Checked against codex-cli 0.155.1 (ADR 0192): `--sandbox` accepts
+    // danger-full-access, and `codex exec` never prompts for approval.
+    fullAccess: { argv: ["--sandbox", "danger-full-access"] },
     capabilities: capabilities({
       effortSelection: supported('Mapped to `-c model_reasoning_effort="<level>"`.'),
       filesystemPolicyProjection: supported(
@@ -107,6 +122,10 @@ export const BUILTIN_ADAPTER_PROFILES = {
     modelFamily: "multi",
     effortValues: [],
     verified: { date: "2026-09-20", version: "2026.09.18-9a7762b" },
+    // Checked against 2026.09.26-dd393fe (ADR 0192): `--sandbox disabled`
+    // overrides the configured sandbox. Cursor carries effort inside the model
+    // id, so a full-access floor for it names exact model ids.
+    fullAccess: { argv: ["--sandbox", "disabled"] },
     capabilities: capabilities({
       effortSelection: unsupported(
         "Cursor embeds effort in some parameterized model ids; Harnery does not rewrite model ids.",
@@ -136,7 +155,9 @@ export const BUILTIN_ADAPTER_PROFILES = {
     authModel: "own-auth",
     modelFamily: "multi",
     // Model reasoning is selected through the `provider/model#variant` id;
-    // OpenCode exposes no separate effort dial for Harnery to map.
+    // OpenCode exposes no separate effort dial for Harnery to map. It also has
+    // no vendor sandbox to remove, so it declares no full-access rendering and
+    // a worker on it is never granted one (ADR 0192).
     effortValues: [],
     verified: { date: "2026-09-20", version: "opencode v2.0.11" },
     capabilities: capabilities({

package/src/core/adapters/types.ts

@@ -67,6 +67,16 @@ export interface AdapterProfile {
   /** How this adapter projects host filesystem policy into the vendor's own
    * sandbox (ADR 0039). Absent means it cannot project any of it. */
   sandboxProjection?: AdapterSandboxProjection;
+  /** Vendor-native arguments that launch a worker with no vendor sandbox
+   * (ADR 0192). Absent means the adapter has no distinguishable full-access
+   * mode, so a worker on it never qualifies for one. */
+  fullAccess?: AdapterFullAccessRendering;
+}
+
+/** How an adapter renders an unsandboxed launch (ADR 0192). The spawner emits
+ * exactly these arguments, so the declaration and the argv cannot drift. */
+export interface AdapterFullAccessRendering {
+  argv: readonly string[];
 }
 
 /** Fully planned child invocation. `resultFile` is used by adapters such as

package/src/core/agents/cli.ts

@@ -309,12 +309,20 @@ async function handleStateAction(root: string, action: string, rest: string[]):
           }
         } catch (error) {
           const detail = error instanceof Error ? error.message : String(error);
-          // A missing heartbeat here means the session's generation ended
-          // while its process lived on. Name the reopen command (ADR 0088);
-          // set-task is usually the first thing such a session runs.
-          const hint = detail.includes("heartbeat_missing:")
-            ? `; run \`${resolveBinName(root)} agents lifecycle active\` to open a fresh generation for this continuing session`
-            : "";
+          // A missing heartbeat usually means the session's generation ended
+          // while its process lived on, so name the reopen command (ADR 0088).
+          // A still-live generation whose authority the ledger withholds looks
+          // the same here; name its diagnostics instead, since reopen cannot apply.
+          const { describeLiveAuthorityBlockV3, liveAuthorityBlockHintV3, liveAuthorityBlockV3 } =
+            await import("./state/live-coordination-view.ts");
+          const block = detail.includes("heartbeat_missing:")
+            ? liveAuthorityBlockV3(root, owner)
+            : null;
+          const hint = block
+            ? `; ${describeLiveAuthorityBlockV3(block)}; ${liveAuthorityBlockHintV3(resolveBinName(root))}`
+            : detail.includes("heartbeat_missing:")
+              ? `; run \`${resolveBinName(root)} agents lifecycle active\` to open a fresh generation for this continuing session`
+              : "";
           process.stderr.write(`agent-coord set-task: V3 authority refused (${detail})${hint}\n`);
           return 1;
         }

package/src/core/agents/render/session-context.ts

@@ -126,6 +126,7 @@ export function renderSessionContext(opts: RenderOpts): string {
       if (d.missing.length > 0)
         bits.push(`missing: ${d.missing.map((m) => m.subcommand).join(", ")}`);
       if (d.orphans.length > 0) bits.push(`orphaned: ${d.orphans.join(", ")}`);
+      if (d.stale.length > 0) bits.push(`outdated: ${d.stale.map((m) => m.subcommand).join(", ")}`);
       return `  - ${d.settingsFile} — ${bits.join("; ")}`;
     });
     messages.push(

package/src/core/agents/state/live-coordination-view.ts

@@ -226,3 +226,76 @@ function observedModel(generation: CoordinationGenerationViewV3): string | undef
 function isLifecycleState(value: string | undefined): value is "active" | "blocked" | "done" {
   return value === "active" || value === "blocked" || value === "done";
 }
+
+/** Why a still-live V3 generation has lost coordination authority. */
+export interface LiveAuthorityBlockV3 {
+  generation_id: string;
+  scope: "generation" | "ledger";
+  diagnostics: { code: string; event_id?: string }[];
+}
+
+/**
+ * Explain an authority refusal for a generation that is still live. Callers
+ * reach this after a lookup came back empty; without it the caller sees only
+ * "missing", which reads like an ended session and points at a reopen that
+ * cannot apply. Returns null when no live generation exists or nothing blocks.
+ */
+export function liveAuthorityBlockV3(
+  coordRoot: string,
+  nativeInstanceId: string,
+): LiveAuthorityBlockV3 | null {
+  let view: CoordinationViewV3;
+  try {
+    if (observeLiveEventLedgerRouteV3(coordRoot).state === "blocked") return null;
+    view = readCoordinationViewV3(coordRoot);
+  } catch {
+    return null;
+  }
+  const generation = view.instances[liveInstanceIdV3(nativeInstanceId)];
+  if (generation?.phase !== "live" || generation.authority_eligible) return null;
+  const own = (view.diagnostics_by_generation[generation.generation_id] ?? []).filter(
+    (diagnostic) => diagnostic.authority_blocking,
+  );
+  const blocking = own.length
+    ? own
+    : view.global_diagnostics.filter((diagnostic) => diagnostic.authority_blocking);
+  if (!blocking.length) return null;
+  return {
+    generation_id: generation.generation_id,
+    scope: own.length ? "generation" : "ledger",
+    diagnostics: blocking.map((diagnostic) => ({
+      code: diagnostic.source_code
+        ? `${diagnostic.code}:${diagnostic.source_code}`
+        : diagnostic.code,
+      ...(diagnostic.event_id ? { event_id: diagnostic.event_id } : {}),
+    })),
+  };
+}
+
+/** One-line description of a live authority block, naming codes and events. */
+export function describeLiveAuthorityBlockV3(block: LiveAuthorityBlockV3): string {
+  const byCode = new Map<string, string[]>();
+  for (const { code, event_id } of block.diagnostics) {
+    const events = byCode.get(code) ?? [];
+    if (event_id) events.push(event_id);
+    byCode.set(code, events);
+  }
+  const parts = [...byCode].map(([code, events]) => {
+    const shown = events.slice(0, 2).join(", ");
+    const more = events.length > 2 ? `, +${events.length - 2} more` : "";
+    return events.length ? `${code} ×${events.length} (${shown}${more})` : code;
+  });
+  const where =
+    block.scope === "generation"
+      ? `the event ledger holds ${block.diagnostics.length} authority-blocking diagnostic(s) for it`
+      : "the event ledger holds authority-blocking diagnostics that block every generation";
+  return `generation ${block.generation_id} is still live, but ${where}: ${parts.join("; ")}`;
+}
+
+/** Recovery pointer for a live authority block, in place of the reopen hint. */
+export function liveAuthorityBlockHintV3(binName: string): string {
+  return (
+    `\`${binName} agents lifecycle active\` cannot help because it only reopens an ended ` +
+    `generation; \`${binName} agents health\` lists the diagnostics`
+  );
+}

package/src/core/artifacts/delivery-card.ts

@@ -12,7 +12,7 @@ import {
 } from "node:fs";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { encodeLinkSafeComponent } from "../../lib/local-file-url.ts";
-import { findLiveTunnelForOrigin } from "../../lib/tunnel/state.ts";
+import { findLiveTunnelForOrigin, tunnelServesPaths } from "../../lib/tunnel/state.ts";
 import { resolveWebPort } from "../config.ts";
 import { stateFileMode } from "../storage/modes.ts";
 import { ARTIFACT_MANIFEST } from "./constants.ts";
@@ -326,9 +326,17 @@ function deliveryLinkBase(repoRoot: string, environment: DisplayEnvironment): st
   // dashboard's own origin will answer them. A tunnel sharing this upstream
   // port under another Host serves a different site and would 400 on /browse
   // and /files, so fall back to the local URL rather than publish that host.
+  // The same holds for a dashboard tunnel whose path scope leaves out either
+  // route: its gate would refuse every link on the card.
+  const tunnel =
+    environment.tunnelUrl === undefined
+      ? findLiveTunnelForOrigin(webPort, `localhost:${webPort}`, repoRoot)
+      : null;
   const tunnelUrl =
     environment.tunnelUrl === undefined
-      ? findLiveTunnelForOrigin(webPort, `localhost:${webPort}`, repoRoot)?.url
+      ? tunnel && tunnelServesPaths(tunnel, ["/browse", "/files"])
+        ? tunnel.url
+        : undefined
       : environment.tunnelUrl;
   return (tunnelUrl ?? `http://localhost:${webPort}`).replace(/\/+$/, "");
 }