harnery 0.40.0 → 0.42.0

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/commands/webview.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.js";
+export declare function registerWebviewCommand(program: Command, emit: EmitContext, binName: string): void;
+//# sourceMappingURL=webview.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"webview.d.ts","sourceRoot":"","sources":["../../src/commands/webview.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAyCnD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CA2DjG"}

package/dist/commands/webview.js

@@ -0,0 +1,94 @@
+import { resolve } from "node:path";
+import { commandPaceGate } from "../lib/pace/index.js";
+import { parseWebViewTypeStep, parseWebViewViewport, runWebView, WebViewUnavailableError, } from "../lib/webview/index.js";
+export function registerWebviewCommand(program, emit, binName) {
+    program
+        .command("webview <url>")
+        .description("Lightweight headless page probe through Bun.WebView (experimental, Bun 1.4+). " +
+        `Fresh ephemeral browser per call; use ${binName} browse for login, cookies, HAR, and QA.`)
+        .option("--backend <engine>", "Browser engine: auto | chrome | webkit", "auto")
+        .option("--user-agent <ua>", "Chrome user agent: shared store by default; auto refreshes, native disables")
+        .option("--viewport <WxH>", "Viewport in CSS pixels", "1280x800")
+        .option("--profile <dir>", "Persist cookies and local storage in this directory (default is ephemeral)")
+        .option("--chrome-path <path>", "Chrome-family executable; implies the Chrome backend")
+        .option("--browser-arg <flag>", "Extra Chrome launch flag (repeatable)", collect, [])
+        .option("--timeout <ms>", "Navigation and selector timeout in milliseconds", "30000")
+        .option("--wait-for <css>", "Wait for a CSS selector after navigation")
+        .option("--type <css=>text>", "Focus a selector and insert text (repeatable; runs before clicks)", collect, [])
+        .option("--click <css>", "Scroll to and click a CSS selector (repeatable)", collect, [])
+        .option("--press <key>", "Press a key in the currently focused element (repeatable)", collect, [])
+        .option("--evaluate <expression>", "Evaluate a JavaScript expression after actions")
+        .option("--settle <ms>", "Extra delay after actions before capture", "0")
+        .option("--screenshot <path>", "Save a viewport PNG (Bun.WebView does not provide full-page capture)")
+        .option("--html", "Print the final document HTML instead of body text")
+        .option("--json", "Print the full result envelope")
+        .option("--no-pace", "Skip the human-pace gap (3 to 9 s) between page loads of the same site for this run. " +
+        "HARNERY_PACE=off disables it machine-wide; local and private hosts never wait.")
+        .action(async (url, opts) => {
+        try {
+            await runWebview(url, opts, emit);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            emit.error({
+                code: err instanceof WebViewUnavailableError ? err.code : "webview_error",
+                message,
+            });
+            process.exit(1);
+        }
+    });
+}
+async function runWebview(url, opts, emit) {
+    if (!isBackend(opts.backend)) {
+        throw new Error(`Invalid backend "${opts.backend}". Expected auto, chrome, or webkit.`);
+    }
+    const backend = opts.backend === "auto" && opts.chromePath ? "chrome" : opts.backend;
+    const result = await runWebView(url, {
+        backend,
+        viewport: parseWebViewViewport(opts.viewport),
+        profileDir: opts.profile ? resolve(opts.profile) : undefined,
+        chromePath: opts.chromePath ? resolve(opts.chromePath) : undefined,
+        browserArgs: opts.browserArg,
+        timeoutMs: parseNonNegativeInteger(opts.timeout, "--timeout", false),
+        waitFor: opts.waitFor,
+        typeSteps: opts.type.map(parseWebViewTypeStep),
+        clicks: opts.click,
+        presses: opts.press,
+        evaluate: opts.evaluate,
+        settleMs: parseNonNegativeInteger(opts.settle, "--settle", true),
+        screenshotPath: opts.screenshot ? resolve(opts.screenshot) : undefined,
+        captureHtml: opts.html === true,
+        pace: commandPaceGate(opts.pace !== false, (message) => emit.log(message, "info")),
+        userAgent: opts.userAgent,
+    });
+    if (opts.json) {
+        emit.data(result);
+    }
+    else if (opts.html) {
+        emit.text(result.html?.endsWith("\n") ? result.html : `${result.html ?? ""}\n`);
+    }
+    else if (opts.evaluate !== undefined) {
+        const value = typeof result.evaluation === "string"
+            ? result.evaluation
+            : JSON.stringify(result.evaluation, null, 2);
+        emit.text(`${value ?? "undefined"}\n`);
+    }
+    else {
+        emit.text(result.text.endsWith("\n") ? result.text : `${result.text}\n`);
+    }
+}
+function collect(value, previous) {
+    return [...previous, value];
+}
+function isBackend(value) {
+    return value === "auto" || value === "chrome" || value === "webkit";
+}
+function parseNonNegativeInteger(value, flag, allowZero) {
+    if (!/^\d+$/.test(value))
+        throw new Error(`${flag} expects an integer, got "${value}".`);
+    const parsed = Number.parseInt(value, 10);
+    if ((!allowZero && parsed < 1) || (allowZero && parsed < 0)) {
+        throw new Error(`${flag} must be ${allowZero ? "zero or greater" : "greater than zero"}.`);
+    }
+    return parsed;
+}

package/dist/core/adapter.d.ts

@@ -1,5 +1,54 @@
 /** First-party harness adapters supported by Harnery's canonical V3 ledger. */
-export type Adapter = "claude-code" | "cursor" | "codex";
+export type Adapter = "claude-code" | "cursor" | "codex" | "opencode";
 /** Canonical producer classes used by V3 provenance. */
 export type EventSource = "agent-hooks" | "agent-coord" | "user" | "system";
+/**
+ * Runtime census of the workflow adapters. Adding a member to `Adapter`
+ * without listing it here is a compile error (see `adaptersComplete`), so a
+ * new adapter can never slip past the shared normalizer.
+ */
+export declare const ADAPTERS: readonly ["claude-code", "cursor", "codex", "opencode"];
+/** Every adapter falls back to this identity when a platform value carries no usable evidence. */
+export declare const DEFAULT_ADAPTER: Adapter;
+/** Why a platform value could not be normalized to a known adapter. */
+export type AdapterFallbackReason = "missing" | "unknown";
+export interface AdapterFallback {
+    /** The raw value that was normalized. */
+    value: unknown;
+    /** `missing` for null, undefined, or an empty string; `unknown` for anything else. */
+    reason: AdapterFallbackReason;
+    /** The adapter that was substituted. */
+    fallback: string;
+    /** Caller-supplied label naming the code path, for the diagnostic line. */
+    context?: string;
+}
+export interface AdapterFallbackOptions {
+    /** Names the caller in the diagnostic line, e.g. `"claim-conflict"`. */
+    context?: string;
+    /**
+     * Receives every fallback. The default writes one stderr line per unknown
+     * value; a missing value is a pre-heartbeat state rather than a
+     * misattribution, so it is passed here but not printed.
+     */
+    onFallback?: (fallback: AdapterFallback) => void;
+}
+/**
+ * Generic membership normalizer shared by every adapter census. Returns the
+ * matching id or `null`; it never substitutes a default.
+ */
+export declare function normalizeAdapterId<T extends string>(value: unknown, census: readonly T[]): T | null;
+/**
+ * Normalize with an explicit, reported fallback. Every caller that must end up
+ * with *some* adapter routes through here so the substitution is visible.
+ */
+export declare function resolveAdapterId<T extends string>(value: unknown, census: readonly T[], fallback: T, options?: AdapterFallbackOptions): T;
+/** Default fallback sink: one stderr line for an unrecognized platform value. */
+export declare function reportAdapterFallback(fallback: AdapterFallback): void;
+/** Strict workflow-adapter normalizer: a known id or `null`. */
+export declare function normalizeAdapter(value: unknown): Adapter | null;
+/**
+ * Heartbeat `platform` (or any adapter-shaped string) to a workflow adapter,
+ * substituting `DEFAULT_ADAPTER` and reporting the substitution.
+ */
+export declare function adapterFromPlatform(value: unknown, options?: AdapterFallbackOptions): Adapter;
 //# sourceMappingURL=adapter.d.ts.map

package/dist/core/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/core/adapter.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,MAAM,MAAM,OAAO,GAAG,aAAa,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEzD,wDAAwD;AACxD,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,aAAa,GAAG,MAAM,GAAG,QAAQ,CAAC"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/core/adapter.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,MAAM,MAAM,OAAO,GAAG,aAAa,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAC;AAEtE,wDAAwD;AACxD,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,aAAa,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE5E;;;;GAIG;AACH,eAAO,MAAM,QAAQ,yDAKkB,CAAC;AAMxC,kGAAkG;AAClG,eAAO,MAAM,eAAe,EAAE,OAAuB,CAAC;AAEtD,uEAAuE;AACvE,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,SAAS,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC9B,yCAAyC;IACzC,KAAK,EAAE,OAAO,CAAC;IACf,sFAAsF;IACtF,MAAM,EAAE,qBAAqB,CAAC;IAC9B,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,IAAI,CAAC;CAClD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EACjD,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,SAAS,CAAC,EAAE,GACnB,CAAC,GAAG,IAAI,CAGV;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAC/C,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,SAAS,CAAC,EAAE,EACpB,QAAQ,EAAE,CAAC,EACX,OAAO,GAAE,sBAA2B,GACnC,CAAC,CAYH;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAMrE;AAED,gEAAgE;AAChE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAE/D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAE7F"}

package/dist/core/adapter.js

@@ -1 +1,59 @@
-export {};
+/**
+ * Runtime census of the workflow adapters. Adding a member to `Adapter`
+ * without listing it here is a compile error (see `adaptersComplete`), so a
+ * new adapter can never slip past the shared normalizer.
+ */
+export const ADAPTERS = [
+    "claude-code",
+    "cursor",
+    "codex",
+    "opencode",
+];
+const adaptersComplete = true;
+void adaptersComplete;
+/** Every adapter falls back to this identity when a platform value carries no usable evidence. */
+export const DEFAULT_ADAPTER = "claude-code";
+/**
+ * Generic membership normalizer shared by every adapter census. Returns the
+ * matching id or `null`; it never substitutes a default.
+ */
+export function normalizeAdapterId(value, census) {
+    if (typeof value !== "string")
+        return null;
+    return census.includes(value) ? value : null;
+}
+/**
+ * Normalize with an explicit, reported fallback. Every caller that must end up
+ * with *some* adapter routes through here so the substitution is visible.
+ */
+export function resolveAdapterId(value, census, fallback, options = {}) {
+    const normalized = normalizeAdapterId(value, census);
+    if (normalized !== null)
+        return normalized;
+    const reason = value === undefined || value === null || value === "" ? "missing" : "unknown";
+    (options.onFallback ?? reportAdapterFallback)({
+        value,
+        reason,
+        fallback,
+        context: options.context,
+    });
+    return fallback;
+}
+/** Default fallback sink: one stderr line for an unrecognized platform value. */
+export function reportAdapterFallback(fallback) {
+    if (fallback.reason !== "unknown")
+        return;
+    const where = fallback.context ? ` (${fallback.context})` : "";
+    process.stderr.write(`harnery: unknown adapter platform ${JSON.stringify(fallback.value)}${where}; treating it as ${fallback.fallback}\n`);
+}
+/** Strict workflow-adapter normalizer: a known id or `null`. */
+export function normalizeAdapter(value) {
+    return normalizeAdapterId(value, ADAPTERS);
+}
+/**
+ * Heartbeat `platform` (or any adapter-shaped string) to a workflow adapter,
+ * substituting `DEFAULT_ADAPTER` and reporting the substitution.
+ */
+export function adapterFromPlatform(value, options) {
+    return resolveAdapterId(value, ADAPTERS, DEFAULT_ADAPTER, options);
+}

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

@@ -1 +1 @@
-{"version":3,"file":"attestation.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/attestation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAaH,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/E,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C;;uBAEuB;AACvB,eAAO,MAAM,qBAAqB,2FAMxB,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzE,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,SAAS,CAAC;IACnB;kFAC8E;IAC9E,cAAc,EAAE,MAAM,CAAC;IACvB;kDAC8C;IAC9C,cAAc,EAAE,MAAM,CAAC;IACvB;;8DAE0D;IAC1D,iBAAiB,EAAE,OAAO,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB;6DACyD;IACzD,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,mBAAmB,EAAE,iBAAiB,CAAC,CAAC,CAAC;IACtE,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,uBAAuB;IACtC,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,eAAe,CAAC,IAAI,GAAE,uBAA4B,GAAG,MAAM,CAI1E;AAED;wDACwD;AACxD,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAM7D;AAMD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,IAAI,CAAC,kBAAkB,EAAE,eAAe,CAAC,GAChD,kBAAkB,CAEpB;AASD;;aAEa;AACb,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,kBAAkB,EAC1B,IAAI,GAAE,uBAA4B,GACjC,MAAM,CAmBR;AAED;;kEAEkE;AAClE,wBAAgB,eAAe,CAC7B,OAAO,EAAE,SAAS,EAClB,IAAI,GAAE,uBAA4B,GACjC,kBAAkB,GAAG,IAAI,CAc3B;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,SAAS,GAClB,kBAAkB,GAAG,IAAI,CAe3B;AAED;uBACuB;AACvB,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,kBAAkB,GAAG,IAAI,EACjC,aAAa,EAAE,MAAM,GAAG,IAAI,EAC5B,OAAO,EAAE,cAAc,EACvB,gBAAgB,CAAC,EAAE,OAAO,GACzB,MAAM,IAAI,kBAAkB,CAK9B;AAED,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,uBAA4B,GAAG,kBAAkB,EAAE,CAczF;AAED;;;oDAGoD;AACpD,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,SAAS,cAAc,EAAE,EACnC,IAAI,EAAE,uBAAuB,GAAG;IAC9B,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAChD;wCACoC;IACpC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GACA;IACD,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,YAAY,EAAE,cAAc,CAAC,cAAc,CAAC,CAAC,cAAc,CAAC,CAAA;KAAE,CAAC,CAAC;IAClG,mBAAmB,EAAE,MAAM,CACzB,MAAM,EACN;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CACvE,CAAC;CACH,CAoCA"}
+{"version":3,"file":"attestation.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/attestation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAcH,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/E,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C;;uBAEuB;AACvB,eAAO,MAAM,qBAAqB,2FAMxB,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzE,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,SAAS,CAAC;IACnB;kFAC8E;IAC9E,cAAc,EAAE,MAAM,CAAC;IACvB;kDAC8C;IAC9C,cAAc,EAAE,MAAM,CAAC;IACvB;;8DAE0D;IAC1D,iBAAiB,EAAE,OAAO,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB;6DACyD;IACzD,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,mBAAmB,EAAE,iBAAiB,CAAC,CAAC,CAAC;IACtE,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,uBAAuB;IACtC,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,eAAe,CAAC,IAAI,GAAE,uBAA4B,GAAG,MAAM,CAI1E;AAED;wDACwD;AACxD,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAM7D;AAMD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,IAAI,CAAC,kBAAkB,EAAE,eAAe,CAAC,GAChD,kBAAkB,CAEpB;AASD;;aAEa;AACb,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,kBAAkB,EAC1B,IAAI,GAAE,uBAA4B,GACjC,MAAM,CAmBR;AAED;;kEAEkE;AAClE,wBAAgB,eAAe,CAC7B,OAAO,EAAE,SAAS,EAClB,IAAI,GAAE,uBAA4B,GACjC,kBAAkB,GAAG,IAAI,CAc3B;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,SAAS,GAClB,kBAAkB,GAAG,IAAI,CAe3B;AAED;uBACuB;AACvB,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,kBAAkB,GAAG,IAAI,EACjC,aAAa,EAAE,MAAM,GAAG,IAAI,EAC5B,OAAO,EAAE,cAAc,EACvB,gBAAgB,CAAC,EAAE,OAAO,GACzB,MAAM,IAAI,kBAAkB,CAK9B;AAED,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,uBAA4B,GAAG,kBAAkB,EAAE,CAczF;AAED;;;oDAGoD;AACpD,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,SAAS,cAAc,EAAE,EACnC,IAAI,EAAE,uBAAuB,GAAG;IAC9B,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAChD;wCACoC;IACpC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GACA;IACD,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,YAAY,EAAE,cAAc,CAAC,cAAc,CAAC,CAAC,cAAc,CAAC,CAAA;KAAE,CAAC,CAAC;IAClG,mBAAmB,EAAE,MAAM,CACzB,MAAM,EACN;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CACvE,CAAC;CACH,CAoCA"}

package/dist/core/adapters/attestation.js

@@ -14,6 +14,7 @@
 import { mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
 import { resolve } from "node:path";
 import { monorepoRoot } from "../agents/coord-client.js";
+import { stateDirMode, stateFileMode } from "../storage/modes.js";
 import { stableDigest } from "../workflow/durable-record.js";
 export const ATTESTATION_SCHEMA_VERSION = 2;
 /** Dimensions one minimal live turn can honestly establish. Everything else
@@ -58,12 +59,12 @@ function attestationPath(adapter, opts) {
  * create. */
 export function writeAttestation(record, opts = {}) {
     const path = attestationPath(record.adapter, opts);
-    mkdirSync(attestationsDir(opts), { recursive: true, mode: 0o700 });
+    mkdirSync(attestationsDir(opts), { recursive: true, mode: stateDirMode() });
     const temporary = `${path}.tmp-${process.pid}`;
     try {
         writeFileSync(temporary, `${JSON.stringify(record, null, 2)}\n`, {
             encoding: "utf8",
-            mode: 0o600,
+            mode: stateFileMode(),
         });
         renameSync(temporary, path);
     }

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: {
@@ -55,14 +61,34 @@ export declare const BUILTIN_ADAPTER_PROFILES: {
         readonly modelFamily: "multi";
         readonly effortValues: readonly [];
         readonly verified: {
-            readonly date: "2026-08-18";
-            readonly version: "2026.08.11-e8db854";
+            readonly date: "2026-09-20";
+            readonly version: "2026.09.18-9a7762b";
+        };
+        readonly fullAccess: {
+            readonly argv: readonly ["--sandbox", "disabled"];
+        };
+        readonly capabilities: AdapterCapabilities;
+    };
+    readonly opencode: {
+        readonly id: "opencode";
+        readonly displayName: "OpenCode";
+        readonly binary: "opencode";
+        readonly installHint: "curl -fsSL https://opencode.ai/install | bash";
+        readonly loginHint: "opencode auth login";
+        readonly apiKeyEnv: "OPENCODE_API_KEY";
+        readonly integrationMode: "cli-subprocess";
+        readonly authModel: "own-auth";
+        readonly modelFamily: "multi";
+        readonly effortValues: readonly [];
+        readonly verified: {
+            readonly date: "2026-09-20";
+            readonly version: "opencode v2.0.11";
         };
         readonly capabilities: AdapterCapabilities;
     };
 };
 export type BuiltinAdapterId = keyof typeof BUILTIN_ADAPTER_PROFILES;
-export declare const BUILTIN_ADAPTER_IDS: readonly ("claude-code" | "cursor" | "codex")[];
+export declare const BUILTIN_ADAPTER_IDS: readonly ("claude-code" | "cursor" | "codex" | "opencode")[];
 export declare function isBuiltinAdapter(id: string): id is BuiltinAdapterId;
 export declare function builtinAdapterProfile(id: string): AdapterProfile | undefined;
 export declare function validateAdapterEffort(id: string, effort: string | undefined): void;

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyFc,CAAC;AAEpD,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,wBAAwB,CAAC;AAErE,eAAO,MAAM,mBAAmB,iDAE/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"}

package/dist/core/adapters/profiles.js

@@ -41,6 +41,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>`."),
@@ -70,6 +82,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("Mode renders to --sandbox; writable roots to sandbox_workspace_write.writable_roots."),
@@ -92,17 +107,54 @@ export const BUILTIN_ADAPTER_PROFILES = {
         authModel: "own-auth",
         modelFamily: "multi",
         effortValues: [],
-        verified: { date: "2026-08-18", version: "2026.08.11-e8db854" },
+        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."),
             maxTurns: unsupported("cursor-agent exposes no turn-ceiling flag."),
             sessionId: supported("Read from the JSON result envelope."),
             cost: unsupported("The JSON result envelope carries no cost."),
+            // Still unknown on 2026-09-20 against cursor-agent 2026.09.18: the live
+            // `cursor_composer_context_percent` reader serves IDE hook sessions from
+            // the composer `state.vscdb`, and headless `cursor-agent` children (this
+            // workflow adapter) leave no composer row and no usage in the JSON result.
             contextTelemetry: unknown("No stable Cursor context-usage payload has been certified."),
             preCompactionSignal: supported("Cursor preCompact is wired to a durable checkpoint."),
             postCompactionSignal: unsupported("Harnery does not wire an unverified Cursor postCompact hook."),
         }),
     },
+    opencode: {
+        id: "opencode",
+        displayName: "OpenCode",
+        binary: "opencode",
+        installHint: "curl -fsSL https://opencode.ai/install | bash",
+        loginHint: "opencode auth login",
+        apiKeyEnv: "OPENCODE_API_KEY",
+        integrationMode: "cli-subprocess",
+        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. 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({
+            effortSelection: unsupported("OpenCode selects reasoning through the model id variant; there is no separate effort flag."),
+            maxTurns: unsupported("`opencode run` exposes no turn-ceiling flag."),
+            sessionId: supported("Read from the `sessionID` on every `--format json` NDJSON line."),
+            cost: unsupported("`opencode run --format json` streams parts without a final cost; cost lives in `session export`."),
+            // Tool evidence is delivered on the event axis by the Harnery OpenCode
+            // plugin, not by the final-result workflow spawn, which retains no tool
+            // events (as with Codex and Cursor).
+            contextTelemetry: unknown("OpenCode stores context in SQLite; no context-window bridge is certified yet."),
+            preCompactionSignal: supported('OpenCode session.hook("compaction") is bridged to a durable checkpoint.'),
+            postCompactionSignal: unsupported("No post-compact hook is wired; OpenCode post-compaction recovery is not yet certified."),
+        }),
+    },
 };
 export const BUILTIN_ADAPTER_IDS = Object.freeze(Object.keys(BUILTIN_ADAPTER_PROFILES));
 export function isBuiltinAdapter(id) {

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

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/registry.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAqErD;+EAC+E;AAC/E,qBAAa,eAAe;;gBAGd,QAAQ,GAAE,QAAQ,CAAC,OAAO,CAAM;IAI5C,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAYhC,GAAG,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS;IAIvC,OAAO,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO;IAU/B,IAAI,IAAI,OAAO,EAAE;IAIjB,GAAG,IAAI,SAAS,EAAE;IAIlB,QAAQ,IAAI,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;CAGhD;AAED,wBAAgB,4BAA4B,IAAI,eAAe,CAE9D"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/registry.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAqGrD;+EAC+E;AAC/E,qBAAa,eAAe;;gBAGd,QAAQ,GAAE,QAAQ,CAAC,OAAO,CAAM;IAI5C,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAYhC,GAAG,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS;IAIvC,OAAO,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO;IAU/B,IAAI,IAAI,OAAO,EAAE;IAIjB,GAAG,IAAI,SAAS,EAAE;IAIlB,QAAQ,IAAI,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;CAGhD;AAED,wBAAgB,4BAA4B,IAAI,eAAe,CAE9D"}